Linkage conventions

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.