Linkage conventions are the register and save area conventions
a program must follow when it receives control from another program
or when it calls another program. It is important that all programs
follow the linkage conventions described here to ensure that the programs
can successfully pass control from one to the other while preserving
register contents and parameter data that they need to run successfully.
One program can call another program through any one of the following branch
instructions or macros:
- BALR, BASR, or BASSM instructions
- LINK, LINKX, XCTL, XCTLX, and CALL macros
The program that issues the branch instruction or the macro is
the
calling program. The program that receives
control is the
target program. A program should
follow these conventions when it:
- Receives control from a calling program
- Returns control to the calling program
- Calls another program
The PC instruction provides another means of program linkage.
Linkage conventions for the PC instruction are described in z/OS MVS Programming: Extended Addressability Guide.
In this chapter, programs are classified by their address space
control (ASC) mode as follows:
- A primary mode program is one that executes
all its instructions in primary ASC mode and does not change the contents
of ARs 2 through 13.
- An AR mode program is one that executes
one or more instructions in AR mode or it changes the contents of
ARs 2 through 13. A program that switches from one mode to another
is considered to be an AR mode program. A program that runs in AR
mode can access data that is outside its primary address space.
The ASC mode at the time a program issues the call determines whether
addresses passed by the program must be qualified by access list entry
tokens (ALETs). An ALET identifies the address space or data space
that contains the passed addresses. An ALET-qualified address is
an address for which the calling program has provided an ALET. The
ASC mode at the time of the call also determines whether the program can call a primary mode
program or an AR mode program.
- A calling program that is in primary ASC mode at the
time of the call can call either another primary mode program or an
AR mode program. Addresses passed by the calling program are not
ALET-qualified.
- A calling program that is in AR mode at the time of the call can
call only another AR mode program. Addresses passed by the calling
program are ALET-qualified.
An AR mode program can call a primary mode program, but the calling
program must first switch to primary ASC mode and then follow
the linkage conventions for a primary mode caller. Addresses passed
by the calling program cannot be ALET-qualified.
When one program calls another, the target program receives control in the caller's
ASC mode at the time the call was made. If the calling program is
in AR mode at the time of the call, the target program receives control
in AR mode. If the calling program is in primary ASC mode
at the time of the call, the target program receives control in primary ASC mode.
After a target program receives control, it can switch its ASC mode
by issuing the Set Address Control (SAC) instruction. For more information
about ASC mode, see Using access registers.