We can now explore how to add system level functionality using SVC (Supervisor Call) routines.  SVC routines are invoked through the use of the SVC machine instruction.  A SVC instruction causes a SVC Interruption to occur.  It effectively allows for a special type of call instruction that can switch between problem mode execution and supervisor mode.  SVC routines are defined at SYSGEN time.  SVC routines are categorized into six types.  Type 1, 2, and 6 SVC routines are linked as part of the resident control program.  Type 3 and 4 SVC routines reside in the Link Pack Area (LPA) and may be either fixed or pageable.  All SVC routines must be reentrant.  I will focus on type 3/4 SVC routines since they reside in LPA as individual modules and are less restrictive – and they provide all the functionality I am looking for.

SVC modules must have a specific name in the format:

There are a maximum of 256 SVC routines that can be defined (0-255).  The nnn part of the name indicates the SVC number.  It is a signed decimal number so the last digit contains the sign in the high order four bits (x’C0′)  make the last digit a letter (A-I) for the numbers zero through nine.  If the last digit is zero then the last character is X’C0′ or ‘{‘.  For example a Type 3 SVC with the number 123 would be named “IGC0012C”.  If it was SVC 130 it would be named “IGC0013{“.  Once you understand the way the names are generated it is easy to deal with.  The difference between Type 3 and 4 SVC routines is that Type 3 routines consist of a singe module and type 4 routines are made up multiple modules.  For our purposes Type 3 and 4 SVC routines are the same.  A Type 5 SVC is a placeholder and indicates the SVC will be added after the SYSGEN in complete.

Since the SVC call is routed through the SVC interrupt handler the SVC routine does not have to save the callers registers (they are saved by the system in the Request Block).  Registers 0, 1, 13, and 15 are passed from the caller to the SVC routine.  On return the system restores registers 2 through 12.  The SVC routine may pass information back to the caller in registers 0, 1, and 15.  Register 13 usually points to a save area established by the calling routine.  It may be necessary for the SVC routine to establish a save area if standard call linkage will be used to call other routines.  Registers 3 through 7 contain parameters passed by the SVC interrupt handler.  Here is a summary of register contents on entry to a SVC routine:

A Simple SVC Routine

Now we can write a simple SVC routine.  We will accept two input parameters in registers 0 and 1.  The SVC routine will add the contents of these two registers and return the result in register 15.  This is really a very silly SVC routine but it will prove that we understand the basics of writing our own SVC.

On my system I happen to know that SVC number 230 is a Type 3 SVC and it is currently not in use.  I will use it for my test SVC routine but you may have to use another SVC number depending how SVC routines are defined and used on your system.

SVC01    CSECT ,        
         USING SVC01,R6 
*                       
         LR    R15,R0   
         AR    R15,R1   
*                       
         BR    R14

Here is our whole SVC routine (minus the equates for the registers).  Our load module must be named to reflect the SVC number (“IGC0023A” for SVC 231) but the internal CSECT name can be anything we want.  We establish addressability using register 6 as our base register since it already contains the entry point address.  We copy the value of register 0 into register 15 and then add teh value of register 1.  All that is left is to return using the address in register 14.  The contents of registers 0, 1, and 15 will be returned to the caller.

Now we can assemble and link into SYS1.LPALIB.

Next we need a test program to invoke our new SVC.  Here is the main part of the test program:

         LA    R0,111                     
         LA    R1,222                     
         SVC   231                        
*                                         
         CVD   R15,DOUBLE                 
         MVC   RESULT,=X'4020202020202120'
         ED    RESULT,DOUBLE+4            
*                                         
         MVC   WTO+8(8),RESULT            
WTO      WTO   '++++++++',ROUTCDE=(1,11)

I left out the program linkage but once our program is up and running we load up our two input parameter registers and issue the SVC instruction to call our SVC routine.  On return from the SVC we convert the return value in register 15 to decimal and use the edit instruction to make it printable.  The result is moved into the WTO parameter list and a message is sent to the console.

JOB 6815  $HASP373 SVC01T   STARTED - INIT 12 - CLASS A - SYS TCS3 
JOB 6815  IEF450I SVC01T MVSSP - ABEND SFE7 U0000 - TIME=07.06.47  
JOB 6815   7.06.48   0.00.00   0.00.00  SFE7   SVC01T    MVSSP     
JOB 6815   7.06.48   0.00.00   0.00.00  SFE7   SVC01T    ########  
JOB 6815  $HASP395 SVC01T   ENDED

When we try running our test program we get a System ABEND FE7.  Notice that X’E7′ is 231 decimal which is our SVC number.  This ABEND indicates the SVC has not been installed.  To actually get our SVC routine installed we need to IPL and CLPA (Create Link Pack Area) or we could use MLPA (Modify Link Pack Area) to do a temporary install of our routine.  A normal IPL does not change the LPA.  It is only rebuilt when CLPA is specified.

Now after a quick IPL with a CLPA we run our test again:

JOB 6825  $HASP373 SVC01T   STARTED - INIT 12 - CLASS A - SYS TCS3 
JOB 6825  +     333                                                
JOB 6825   7.31.17   0.00.00   0.00.00  0000   SVC01T    MVSSP     
JOB 6825   7.31.17   0.00.00   0.00.00  0000   SVC01T    ########  
JOB 6825  $HASP395 SVC01T   ENDED

And we get the expected result (111+222=333) which proves we have successfully written, installed, and invoked a SVC routine.