Using the LINK or LINKX macro

When you use the LINK or LINKX macro, you are requesting the system to assist you in passing control to another load module. There is some similarity between passing control using a LINK or LINKX macro and passing control using a CALL macro in a simple structure. These similarities are discussed first.

The convention regarding registers 2-12 still applies; the control program does not change the contents of these registers, and the called load module should restore them before control is returned. Unless you are an AR mode program calling an AR mode program that uses the linkage stack, you must provide the address in register 13 of the save area for use by the called load module; the system does not use this save area. You can pass address parameters in a parameter list to the load module using register 1. The LINK or LINKX macro provides the same facility for constructing this list as the CALL macro. Register 0 is used by the control program and the contents may be modified. In certain cases, the contents of register 1 may be altered by the LINK or LINKX macro.

There is also some difference between passing control using a LINK or LINKX macro and passing control using a CALL macro. When you pass control using the CALL macro, register 15 contains the entry address and register 14 contains the return address. When the called load module gets control, that is still what registers 14 and 15 contain. When you use the LINK or LINKX macro, it is the control program that establishes the values in registers 14 and 15. When you code the LINK or LINKX macro, you provide the entry name and possibly some library information using the EP, EPLOC, or DE, and DCB parameters, but you have to get this entry name and library information to the control program. The expansion of the LINK or LINKX macro does this by creating a control program parameter list (the information required by the control program) and passing its address to the control program. After the control program determines the entry point address, it places the address in register 15 if the target routine is to run in 24-bit or 31-bit addressing mode. If the target routine is to run in 64-bit addressing mode, that routine is expected to use relative branching, and register 15 contains a value that can be used to determine the addressing mode of the issuer of the LINK or LINKX macro as follows:

The return address in your control section is always the instruction following the LINK or LINKX; that is not, however, the address that the called load module receives in register 14. The control program saves the address of the location in your program in its own save area, and places in register 14 the address of a routine within the control program that will receive control. Because control was passed using the control program, return must also be made using the control program. The control program also handles all switching of addressing mode when processing the LINK or LINKX macro.

Note: A program that is LINKed to will get control with the caller's Floating Point Registers and Floating Point Control register. The S/390® linkage convention applies. For more information, see Linkage conventions.

The control program establishes a use count for a load module when control is passed using the LINK or LINKX macro. This is a separate use count from the count established for LOAD macros, but it is used in the same manner. The count is increased by one when a LINK or LINKX macro is issued and decreased by one when return is made to the control program or when the called load module issues an XCTL or XCTLX macro.

Figure 1 and Figure 2 show the coding of a LINK or LINKX macro used to pass control to an entry point in a load module. In Figure 1, the load module is from the link, job, or step library; in Figure 2, the module is from a private library. Except for the method used to pass control, this example is similar to Figures 10 and 11. A problem program parameter list containing the addresses INDCB, OUTDCB, and AREA is passed to the called load module; the return point is the instruction following the LINK or LINKX macro. A V-type address constant is not generated, because the load module containing the entry point NEXT is not to be edited into the calling load module. Note that the EP parameter is chosen, since the search begins with the job pack area and the appropriate library as shown in Figure 1.
Figure 1. Use of the LINK Macro with the Job or Link Library
           LINK    EP=NEXT,PARAM=(INDCB,OUTDCB,AREA),VL=1
RETURNPT   ...
AREA       DC      12F'0'
Figure 2. Use of the LINK Macro with a Private Library
           OPEN    (PVTLIB)
           .
           .
           LINK    EP=NEXT,DCB=PVTLIB,PARAM=(INDCB,OUTDCB,AREA),VL=1
           .
           .
PVTLIB     DCB     DDNAME=PVTLIBDD,DSORG=PO,MACRF=(R)
Figure 3 and Figure 4 show the use of the BLDL and LINK macros to pass control. Assuming that control is to be passed to an entry point in a load module from the link library, a BLDL macro is issued to bring the directory entry for the member into virtual storage. (Remember, however, that time is saved only if more than one directory entry is requested in a BLDL macro. Only one is requested here for simplicity.)
Figure 3. Use of the BLDL Macro
           BLDL    0,LISTADDR
           .
           .
           DS      0H          List description field:
LISTADDR   DC      H'01'           Number of list entries
           DC      H'60'           Length of each entry
NAMEADDR   DC      CL8'NEXT'   Member name
           DS      26H         Area required for directory information
The first parameter of the BLDL macro is a zero, which indicates that the directory entry is on the link, job, step, or task library. The second parameter is the address in virtual storage of the list description field for the directory entry. The second two bytes at LISTADDR indicate the length of each entry. A character constant is established to contain the directory information to be placed there by the control program as a result of the BLDL macro. The LINK macro in Figure 4 can now be written. Note that the DE parameter refers to the name field, not the list description field, of the directory entry.
Figure 4. The LINK Macro with a DE Parameter
LINK     DE=NAMEADDR,DCB=0,PARAM=(INDCB,OUTDCB,AREA),VL=1
Parent topic: Passing control with return