Linkage

Home Up Search Credits Site Map Contact Info. Links Disclaimer Download

Within the architecture of MVT, MVS, OS/390 and z/OS, certain conventions have been established regarding the use of registers.  These conventions will have been followed when you, the problem programmer, receive control from the operating system.  They also should be followed for any routines, which you call, or for communications with the system (e.g. system macro calls, SVC’s, returning control, etc.).  Following these conventions will make your code easier for someone else to follow.  Certain debugging aids are also available for those who adhere to standard conventions.  In general, unless there is a STRONG reason to deviate, these conventions should be employed.  The Operating System conventions are:

 Return Register

Register 14 is called the “return register” and contains the address to which this routine is to return upon exit.

 Entry Point Register

Register 15 is called the “entry point register” and contains the address through which this routine was entered.  Note that temporary addressability my be established by using the following at the start of your routine:
            USING            ENTRYPOINT,R15
If this routine calls no other routines, register 15 may  be used as a permanent base register.  If this routine calls any other routine (including operating systems service) however, register 15 will be changed, and should not be used as a permanent base register.  In this case, the sequence
            LR                   BASEREG,R15
            USING            ENTRYPOINT,BASEREG
(Where BASEREG is any of registers 2-13) may be used to establish permanent addressability.

On return, register 15 may be used to return a code to indicate normal or error return.  One frequently used technique is to set register 15 to zero on a normal return and set it to non-zero if some error condition occurred prior to return.

Return Value Register

 Register 0 is used to return a single result from some process (as in a FORTRAN function subprogram).  Note: although you will probably not use this convention much, it is heavily used by the operating system.  Register 0 cannot be guaranteed to be intact after executing some call to the system, as a system MACRO, or an SVC.

 Argument List

Register 1 is the pointer to an argument list.  It contains the address of the first of one or more full word entries (on consecutive full word boundaries).  These entries are the addresses of arguments to be used by the calling routine.

If there are an indefinite number of arguments, (as with a routine which would accept one, two, or any number of arguments), the first bit of the last address is set to a 1.  (this bit will not interfere with 24-bit addressing.  This cannot be used when running in 31-bit mode.

The following example illustrates how to use the address list passed through register 1.

LA            R1,ARGLIST                         GET ARGUMENT LIST ADDR
            L            R15,=V(CALLRTN)                GET ADDRESS TO CALL
            BALR            R14,R15                             CALL THE ROUTINE

ARGLIST       DC            A(ARG1
                        DC            A(ARG2)
                        DC            X’80’,AL3(ARG3)                

CALLRTN     CSECT
                        L            R2,0(R1)                     GET ADDR OF NEXT ARG
                        LTR            R1,R1                          LAST ARG. IN LIST?
                        BM            RETURN                   IF YES, RETURN
                        LA            R1,4(0,R1)                  ELSE GET ADDR OF NEXT ARG

When a programmer receives control from the system, information from the PARM field of his/her EXEC card is passed via register 1.  Register 1 points to a full word of storage.  Bit 0 of this full word is set to 1 (to indicate the last-only-argument of the list).  This full word contains the address of a half word.  The half word is a count of the number of characters in the PARM field message, and these characters follow immediately after the half word count field.  The contents of the half word may be picked up to use as a length count in an execute instruction, and the address of the half word may be used as a base to move the information characters of the PARM field.

  Save Area Register

Register 13 is called the “save area register”.  It contains the address of an 18 full word area (on a full word boundary) within the calling routine.  The routine called will use this area to save the contents of registers, to be able to return the registers intact to the calling program.  This save area has a set format as follows: 

Save Area Word

Description

Word 1

Used by PL/I and FORTRAN

Word 2

Address of the save area used by the calling program

Word 3

Address of the save area set up by the called program

Word 4

Address to which to return (register 14)

Word 5

Address of the entry point (register 15)

Word 6

Contents of register 0

Word 7

Contents of register 1

Word 8

Contents of register 2

Word 9

Contents of register 3

Word 10

Contents of register 4

Word 11

Contents of register 5

Word 12

Contents of register 6

Word 13

Contents of register 7

Word 14

Contents of register 8

Word 15

Contents of register 9

Word 16

Contents of register 10

Word 17

Contents of register 11

Word 18

Contents of register 12

  Save areas are chained in a double-linked list.  At any low-level routine, by tracing back through a chain of save areas links, one can eventually return to the system at the original point of call.

When your routine is entered, first you should save registers and then establish and like your own save area.

            STM        R14,R12,12(R13)            SAVE REGS 14,15 AND 0-12
                         LA           R5,MYSAVE                  GET ADDR OF MY SAVE AREA
                         ST            R5,8(R13)                        LINK CALLING PGM S.A. TO MINE
                        ST            R13,4(R5)                        LINK MY S.A. TO CALLING PGM’S
                        LR           R13,R5                             POINT TO MY SAVE AREA NOW

On return

                        XR          R15,R15                          SET ZERO RETURN CODE
                         L             R13,4(R13)                      RETRIEVE ADDR OF CALLING PGM’S
*                                                                                SAVE AREA
                         LM          R14,R12,12(R13)            RESTORE REGISTERS
                         BR           R14                                 RETURN TO CALLER
 

MYSAVE            DC            18F’0’                         MY SAVE AREA

  A calling program is known as a “higher routine”, and the routine called is the “lower routine”.  Register 13 is always to point to an area whose contents may be destroyed.

 An exception to the requirement that a routine must always establish a save area is that the lowest-level routine (the one which call no others) need not set up a save area.  The reason for this is the save area is for the use of any called routines, but that the lowest-level routine will have no called routines.

 Save Area Naming

The name convention is a means of having the EBCDIC form of the name of a routine appear at certain key places on dumps.  To use this convention, the first four bytes of a routine must be a branch, on register 15 as a base register, which passed over a series of bytes.  These bytes contain the EBCDIC form of the name of a routine, and also a length code for this name area.  This example shows how to code a name field. 

 

NAME             CSECT 
                         B                      M+1+4(,R15)
                         DC                   X’M’
                         DC                   CLM’NAME’
                           NEXT INSTRUCTION

The value of “M” must be odd, in order to make the next instruction properly aligned.  An alternate approach used the convention on register 15:

  NAME             CSECT
    USING            NAME,R15
                            B                      NEXTINST
                            DC                   X’M’
                            DC                   CLM’NAME’
NEXTINST        EQU                *

 

MVT, MVS and OS/390 follow these conventions strongly.  In particular, the system often destroys the contents of registers 0, 1, 14, and 15 when it returns control from a system MACRO, an SVC, or another system function.  One must save the contents of these registers before execution one of these functions (hard to locate errors will frequently occur after failure to do so).

  It is a good idea to mark a save area upon exit.  This is usually done by moving X’FF” into the first byte of the fourth word of the save area (the place register 14 was stored).  Although this technique does not seriously affect the contents of the save area for reading a dump, this technique quickly shows what save areas are active and which are not active when reading a dump.  This technique does not work in OS/390 when the address mode is 31-bits. 

  Register 13 must be kept as the save area pointer; however, by careful programming, it can also double as a base register.  You may set up your own save area for this purpose by setting it high in the program, and following it by a using on register 13, referencing the name of the save area.  For reserving the 18 full words on storage for a save area, us DC instead of DS.  A constant of F’0’, or F’-1’ will quickly show in a dump if the save area was ever used.

  SAVE and RETURN are two system MACROS which will eliminate must of the coding for saving and returning conventions.  SAVE generates the code necessary to save a specified series of registers.  The registers are specified as they would be for a STM instruction.  In addition, the operand “T” will cause registers 14 and 15 to be stored, regardless of what other registers may also be saved from the pair specified.  The following example will cause registers 5,6, …. 10, 14, and 15 to be saved.

                        Save             (R5,R10),T

The RETURN MACRO will generate code to restore registers, insert a return code in register 15, flag the save area (X’FF” in full word 4), and branch back via register 14.  The registers to be restored are coded as with save.  If register 15 already has a return code in it and should not be restored, it is coded as RC=(R15); else RC=N may be coded, where N is some value to insert into register 15.  The operand “T” causes the flag X’FF’ to be inserted in the save area.  The following code will restore registers 5,6, …. 10 to be reloaded, the save area to be flagged, and register 15 to be loaded with a value of 16.

            RETURN            (R5,R10),T,RC=16

  **NOTE**  both of these MACROS expect that register 13 will already be loaded with the address of the appropriate save area.

Credits:  This document was a green-bar listing found from about 1972.  It appears to be from the Pennsylvania State University.

The information on this site is the combined effort of a lot of people, please credit the authors if you use their information.
Please read the Disclaimer page for the restrictions, copyright, and other uses of the information contained on this site.
For problems or questions regarding this web contact Bob.
Last updated: January 25, 2004.