LINK and LINKX 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.
- The standard form of the LINK macro, which includes general information about the LINK and LINKX macros with specific information about the LINK macro. The syntax of the LINK macro and all LINK parameters are explained.
- The standard form of the LINKX macro, which presents information specific to the LINKX macro and callers in AR mode.
- The list form of the LINK and LINKX macros.
- The execute form of the LINK and LINKX macros.
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.
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
- The caller cannot have an EUT FRR established.
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.
- 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 addressWhen the target of the LINK or LINKX is AMODE(64), then reg 15 contains
where Y is:xxxxxxxY
- 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.
- 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 to 76-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
LINK EP=PGMLKRUS
Example 2
LINK EP=PGMA,PARAM=((4),(6),(8))