Description

The LINK macro is used to pass control to a specified entry name in another load module; the entry name must be a member name or an alias in the directory of a partitioned data set (PDS) or must have been specified in an IDENTIFY macro. The load module containing the program is brought into virtual storage if a usable copy is not available.

If your program is in access register (AR) address space control (ASC) mode, use LINKX. All the parameters on LINK are valid on LINKX.

Descriptions of the LINK and LINKX macro in this information are:

LINK and LINKX processing ensure that the called program receives control in the correct addressing mode. If the called program has an address mode of ANY, it receives control in the AMODE of the calling program. The program issuing the LINK or LINKX macro regains control in its own addressing mode.

The caller optionally can provide a parameter list to be passed to the called program. If the called program terminates abnormally, or if the specified entry point cannot be located, the task is abnormally terminated unless the caller provides an ERRET exit.

Note: The LINK and LINKX macros have the same environment specifications, register information, programming requirements, restrictions and limitations, performance implications, and return and reason codes described below, except where noted in the explanation for LINKX.
Parent topic: LINK and LINKX — Pass control to a program in another load module

Environment

The requirements for the caller of LINK are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key.
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31-bit for LINK. 24- or 31- or 64-bit for LINKX.
ASC mode: Primary
Interrupt Status: Enabled for I/O and external interrupts
Locks: No locks held
Control parameters: Must be in the primary address space.

Programming requirements

None.

Restrictions

Register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

If the LINK is successful, the GPRs contain the following when the called program receives control:
Register
Contents
0
One of the following:
  • Used as a work register by the system if SF is specified.
  • Otherwise, unchanged.
1
One of the following:
  • Address of the PARAM address list if that is coded.
  • Otherwise, unchanged if LSEARCH=YES not specified and LINKX not specified, and LINK not issued with SYSSTATE ASCENV=AR.
  • Otherwise, used as a work register by the system.
2-13
Unchanged
14
Contains the return address the called module will return to. If the high-order bit of this register is on, the issuer of the LINK or LINKX macro is running in 31-bit mode; if off, the issuer is running in 24-bit mode.
15
Requested program's entry point address
When the target of the LINK or LINKX is AMODE(64), then reg 15 contains 
xxxxxxxY
where Y is:
  • 0 if the caller was AMODE 24
  • 2 if the caller was AMODE 31
  • 4 if the caller was AMODE 64

Upon return to the caller, the GPRs contain whatever values the called program placed there.

If the LINK is not successful and the caller provided an ERRET exit to receive control, the GPRs contain the following:
Register
Contents
0
One of the following:
  • Used as a work register by the system if SF is specified.
  • Otherwise, unchanged.
1

Bits 0–31 of the 64 bit register contain the abend reason code for the abend code for the ABEND that would have been issued if the caller had not provided an ERRET exit.

Bits 32–63 of the 64 bit register contain the abend code for the ABEND that would have been issued if the caller had not provided an ERRET exit.

2-13
Unchanged
14
Used as a work register by the system
15
Address of the ERRET exit.

Performance implications

None.

Syntax

The standard form of the LINK macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede LINK.
   
LINK  
   
␢ One or more blanks must follow LINK.
   
EP=entry name entry name: Symbol.
EPLOC=entry name addr entry name addr: A-type address, or register (2) - (12).
DE=list entry addr list entry addr: A-type address, or register (2) - (12).
   
   ,DCB=dcb addr dcb addr: A-type address, or register (2) - (12).
   
   ,PARAM=(addr) addr: A-type address, or register (2) - (12).
   ,PARAM=(addr),VL=1 Note:  addr is one or more addresses, separated by commas. For example, (addr,addr,addr)
   
   ,ID=id nmbr id nmbr: Symbol or decimal digit, with a maximum value of 4095.
   
   ,ERRET=err rtn addr err rtn addr: A-type address, or register (2) - (12).
   
   ,LSEARCH=NO Default: No
   ,LSEARCH=YES  
   

Parameters

The parameters are explained as follows:

EP=entry name
EPLOC=entry name addr
DE=list entry addr
Specifies the entry name, the address of the entry name, or the address of the name field in a 62-byte list entry for the entry name that was constructed using the BLDL macro. If EPLOC is coded, entry name addr points to an eight-byte field. If the name is less than eight characters, left-justify the name and pad with blanks on the right to make up the eight characters.
The system ignores the information you specify on the DE parameter if the parameter does one or both of the following:
  • Specifies an entry in an authorized library (that is, defined in IEAAPFxx member of parmlib)
  • Requests access to a program or library that is controlled by the system authorization facility (SAF)

Instead, the system uses the BLDL macro to construct a new list entry containing the DE information.

Note: When you use the DE parameter with the LINK macro, DE specifies the address of a list that was created by a BLDL macro. BLDL and LINK must be issued from the same task; otherwise, the system might terminate the program with an abend code of 106 and a return code of 15. Therefore, do not issue ATTACH or DETACH between issuances of BLDL and LINK.
,DCB=dcb addr
Specifies the address of the opened data control block for the partitioned data set containing the entry name described above. This parameter must indicate the same DCB specified in the BLDL used to locate the entry name.

If the DCB parameter is omitted or if DCB=0 is specified when the LINK macro is issued by the job step task, the data sets referred to by either the STEPLIB or JOBLIB DD statement are first searched for the entry point name. If the entry point name is not found, the link library is searched.

If the DCB parameter is omitted or if DCB=0 is specified when the LINK macro is issued by a subtask, the data sets associated with one or more data control blocks referred to by the TASKLIB operand of previous ATTACH macros in the subtasking chain are first searched for the entry point name. If the entry point name is not found, the search is continued as if LINK had been issued by the job step task.

Note: DCB must reside in 24-bit addressable storage.
,PARAM=(addr)
,PARAM=(addr),VL=1
Specifies address(es) to be passed to the called program. To form the parameter list, the macro expands each address inline to a fullword on a fullword boundary, in the order designated. GPR 1 contains the address of the first parameter when the program is given control. (If this parameter is not coded, GPR 1 is not altered unless the execute form of the LINK macro is coded or LSEARCH=YES is specified.)

Specify VL=1 only if the called program can be passed a variable number of parameters. VL=1 causes the high-order bit of the last address parameter to be set to 1; the bit can be checked to find the end of the list.

Note: If you specify only one address for PARAM=, you do not need to enter the parentheses.
,ID=id nmbr
Specifies an identifier for this invocation of the macro, useful for debugging purposes. The last fullword of the macro expansion is a NOP instruction containing, in bytes 3 and 4, the identifier you specified.
,ERRET=err rtn addr
Specifies the address of an exit to receive control when an error condition that would cause abnormal termination of the task is detected. The ERRET exit does not receive control when input parameter errors are detected.
,LSEARCH=NO
,LSEARCH=YES
Specifies whether (YES) or not (NO) the search is to be limited to the job pack area and the first library in the normal search sequence.

Return and reason codes

None.

Example 1

Pass control to a specified entry name (PGMLKRUS) in another load module. Let the system find the module from available libraries. 
LINK    EP=PGMLKRUS

Example 2

Pass control to a specified entry name (PGMA) in another load module, specifying (in registers 4, 6, 8) three addresses to be passed to the called program. 
LINK EP=PGMA,PARAM=((4),(6),(8))