LINKX — Pass control to a program in another load module

The LINKX macro performs the same function as LINK. It passes control to a specified entry name in another load module. LINKX is intended for use by programs running in access register (AR) mode.

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

Environment

The LINKX macro can be used by callers in AR or primary ASC mode.

Programming requirements

If your program is in AR mode, issue the SYSSTATE ASCENV=AR macro before you issue LINKX.

Parameters passed to the called program using the PARAM parameter must reside in your primary address space.

Register information

When the caller regains control or the ERRET exit receives control, the access registers (ARs) are unchanged.

Syntax

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

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede LINKX.
   
LINKX  
   
␢ One or more blanks must follow LINKX.
   
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)
   
   ,PLIST4=YES Default: None.
   ,PLIST4=NO  
   
   ,PLIST8=YES Default: None.
   ,PLIST8=NO  
   
   ,PLIST8ARALETS=NO Default: PLIST8ARALETS=NO
   ,PLIST8ARALETS=YES  
   
   ,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  
   
   ,AMODE64OK=NO Default: NO
   ,AMODE64OK=YES  
   

Parameters

The parameters are explained under LINK with the following exceptions. The parameter list on the PARAM parameter is different for callers in AR mode. It is described as follows:

PARAM=(addr)
PARAM=(addr),VL=1
Specifies an address or addresses to be passed to the called program. LINKX expands each address inline to a fullword boundary and builds a parameter list with the addresses in the order specified. When the called program receives control, GPR1 contains the address of the parameter list. If the program that issued the LINKX macro was in AR mode, access register 1 contains the ALET that qualifies the parameter list address.
When an AR mode caller uses either:
  • a parameter list with 4 bytes per entry; or
  • a parameter list with 8 bytes per entry and specifies PLIST8ARALETS=YES,
the addresses passed to the subtask are in the first part of the parameter list and their associated ALETs are in the second part. For a non-AR mode caller, or for an AR mode caller using a parameter list with 8 bytes per entry without PLIST8ARALETS=YES, ALETs are not passed in the parameter list. When ALETs are passed in the parameter list, the ALETs occupy consecutive 4-byte fields, whether the parameter list is 4 or 8 bytes per entry. See the description of the PLIST4 and PLIST8 keywords below for more information about controlling the bytes-per-entry in the parameter list. See the description of the PLIST8ARALETS keyword below for more information about ALETs and 8-bytes-per-entry parameter lists. See User parameters for an example of passing a parameter list in AR mode.
When using a 4-bytes-per-entry parameter list, specify VL=1 when you pass a variable number of parameters. VL=1 results in setting the high-order bit of the last address to 1. The 1 in the high-order bit identifies the last address parameter (which is not the last word in the list when the ALETs are also saved). When using an 8-bytes-per-entry parameter list, VL=1 is not valid.
Note: If you specify only one address for PARAM= and you are not using register notation, you do not need to enter the parentheses.
,PLIST4=YES
,PLIST4=NO
 
,PLIST8=YES
,PLIST8=NO
Defines the size of the parameter list entries for a parameter list to be built by LINKX based on the PARAM keyword.
PLIST4 and PLIST8 cannot be specified together. If neither is specified, the default is:
  • If running AMODE 64, PLIST8=YES
  • If not running AMODE 64, PLIST4=YES

If running AMODE 64 and PLIST4=YES is specified, the system builds a 4-bytes-per-entry parameter list just as it would if the program were running AMODE 24 or AMODE 31 and did not specify PLIST4 or PLIST8.

If running AMODE 24 or AMODE 31 and PLIST8 is specified, the system builds an 8-bytes-per-entry parameter list just as it would if the program were running AMODE 64 and did not specify PLIST4 or PLIST8.

,PLIST8ARALETS=NO
,PLIST8ARALETS=YES
If there is to be an 8-byte-per-entry parameter list and the invoker is in AR mode, indicates if the parameter list is also to contain the ALETs associated with the addresses. Otherwise, this parameter is ignored.
,PLIST8ARALETS=NO
Indicates that the 8-byte-per-entry parameter list is to consist of just the 8-byte addresses.
,PLIST8ARALETS=YES
Indicates that the 8-byte-per-entry parameter list is to consist of the following two parts:
  • All the 8-byte addresses,
  • All the associated ALETs in consecutive 4-byte fields.
,AMODE64OK=NO
,AMODE64OK=YES
Indicates if the system is to accept an attempt to link to an AMODE 64 target routine from an AMODE 24 or AMODE 31 routine.
NO
Indicates that the system is to abend such an attempt.
YES
Indicates that the system is to accept such an attempt.