SAVE - Save register contents

General

Application area:	Starting, interrupting and terminating; see "Starting, interrupting and terminating"
Macro type:	Type O; see "O-type macros"

Macro description

The SAVE macro may be used to store register contents temporarily.

The SAVE macro is called at the beginning of a subroutine in order to save the register contents of the main program. A return to the main program is effected by the RETRN macro, which reloads the saved contents to the registers and makes the branch. All general registers except register 13 can be saved. Register 13 must contain the address of the save area, which must be defined by the main program.

Macro format and description of operands

SAVE

[(r1[,r2])] [,T] [,entry / *]

r1
Specifies a register (general register) which is to be saved. The numbers from 0 to 15 (except 13) may be specified for “r1“. The parentheses are optional.

r1,r2
Specifies a consecutive number of registers (general registers), which are to be saved.
The range r1, r2 must not contain register 13, but but it may cross the register 15 / register 0 boundary.
Example: If (14,12) is specified, all registers except register 13, i.e. registers 0 to 12, 14 and 15, are saved.

Note

Register specifications can also be entered in the form “Rn”, where n = register number.

T

Is designed for compatibility with TOS language processors and specifies that registers 14 and 15 are to be saved. This operand is specified if “r1” or the range r1, r2 does not start or end on registers 14 and 15.

Note

If the range r1, r2 starts with register 1 or 2 when T is specified, then all registers from 14 to “r2” are saved, i.e. registers 0 and possibly 1 are not excluded from the range.

entry
Provided for compatibility with TOS language processors and specifies an ID for the SAVE macro. “entry” must not comprise more than 155 characters; commas and blanks are not permissible. The ID is included in the macro expansion at a halfword boundary before the first instruction to be executed. The ID is immediately preceded by a byte beginning on a halfword boundary and containing the length of the ID.

*
Provided for compatibility with TOS language processors and specifies that the entry in the name field of the macro is to be used as an ID. If the name field is empty, the name of the CSECT which contains the macro is used.

Functional description

The SAVE macro is used in subroutines, together with the RETRN macro, to save the contents of the main program's general registers. The SAVE macro stores the values, while the RETRN macro reloads them to the registers before the return branch and transfers a return code if desired.
The buffer for the register contents must be defined by the main program with a length of 18 words (72 bytes). Its address must be loaded to register 13.

Buffer structure

1	reserved for compiler
2	address of the calling program's buffer (GR13)	2 - 3: reserved for program nesting
3	address of the called program's buffer
4	general register 14, return address	4 - 18: saved register contents
5	general register 15, destination address
6	general register 0
7	general register 1, data addresses
8	general register 2
9	general register 3
10	general register 4
11	general register 5
12	general register 6
13	general register 7
14	general register 8
15	general register 9
16	general register 10
17	general register 11
18	general register 12

The buffer always contains the register contents of the program in which it is defined. The registers are stored by the called subroutine that calls the SAVE macro at the beginning.

One word of the buffer is allocated permanently to each of the registers 0 to 15 (except 13). If a register is not to be saved, the SAVE macro skips the associated buffer word. The order of the register contents in the buffer (14, 15, 0 to 12) permits all registers to be stored consecutively (excluding register 13). Register 13 cannot be saved by means of the SAVE macro, because it is used by SAVE for addressing the buffer.

If the subroutine changes register 13, this register must be saved separately. The SAVE macro cannot be used for this purpose.

Note on program nesting

A subroutine calling another subroutine, which also saves registers by means of SAVE/RETRN, must also define a buffer. Before it loads the address of this buffer to register 13, it must save the contents of register 13 (the address of the previous program's buffer) in word 2 of its own buffer. Before it returns to the calling program it must reload register 13 from that location.
It may deposit the address of its own buffer in word 3 of the buffer of the calling program.

Figure 25: Buffer

The address in word 2 is entered by the program that defined the buffer.
The address in word 3 and the register contents in words 4 to 18 are entered by the called subroutine (SAVE macro).

Register conventions in nested programs:

Register R13 Register R14 Register R15	buffer address return address destination address (entry point in the called subroutine) or return code (see the RETRN macro)
Register R1	address of data addresses (if data addresses are to be transferred to the called subroutine).