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:
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:
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.
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.
GET ARGUMENT LIST ADDR
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 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.
SAVE REGS 14,15 AND 0-12
SET ZERO RETURN CODE
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.
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:
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.
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.
**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.