When the target program receives control, it saves the 32-bit
GPRs (bits 32-63 of the 64-bit GPRs) into the 72-byte caller-provided
save area pointed to by GPR 13. The format of this area is shown
in Figure 1. As indicated by this figure,
the contents of each 32-bit GPR, except GPR 13, must be saved in a
specific location within the save area. GPR 13 is not saved into the
save area; it holds the address of the save area.
Figure 1. Format of the Save
Area- Word
- Contents
- 0
- Used by language products
- 1
- Address of previous save area (stored by calling program)
- 2
- Address of next save area (stored by target program)
- 3
- GPR 14 (return address)
- 4
- GPR 15 (entry address)
- 5 - 17
- GPRs 0 - 12
You can save 32-bit GPRs either with a store-multiple (STM)
instruction or with the SAVE macro. Use the following STM instruction
to place the contents of all 32-bit GPRs except GPR 13 into the proper
words of the caller's 72-byte save area: STM 14,12,12(13)
When SYSSTATE AMODE64=NO is in effect, the SAVE macro stores
32-bit GPRs into the save area. Code the GPRs to be saved
in the same order as in a STM instruction. The following example of
the SAVE macro places the contents of all GPRs except GPR 13 in the
proper words of the save area.
PROGNAME SAVE (14,12)
Later, the program can use the RETURN macro to restore 32-bit GPRs
and return to the caller.
Whether or not the target program creates a save area, it must
save the address of the calling program's save area. If the target
program creates a save area, it:
- Stores the address of the calling program's save area (the address
passed in GPR 13) into the second word of its own save area.
- Stores the address of its own save area (the address the target
program will place in GPR 13) into the third word of the calling program's
save area.
These steps enable the target program to find the calling program's
save area when the target program needs the calling program to restore
the caller's registers, and they enable a trace from save area to
save area should one be necessary while examining a dump.
If the target program does not create a save area, it
can keep the address of the calling program's save area in GPR 13
or store it in a location in virtual storage.
If you choose not to use the SAVE and RETURN macros, you can use
the IHASAVER macro to map the fields in the save area.