Description

The XCTL macro passes control to a specified entry name in a load module; the entry name must be a member name, an alias in a directory of a partitioned data set, or have been specified in an IDENTIFY macro. The system brings the load module (called the target module) containing the entry name into storage if a usable copy is not already available. Control passes from the program that issues the XCTL or XCTLX (called the XCTL issuer) to the target module; control does not return to the XCTL issuer. Rather, control returns to the program that caused the XCTL issuer to run. The use count for the XCTL issuer's load module is decremented by 1. If the use count becomes zero, the system deletes the XCTLX issuer's module and reassigns that storage.

Descriptions of the XCTL and XCTLX macro in this information are:

The standard form of the XCTL macro, which includes general information about the XCTL and XCTLX macros with specific information about the XCTL macro. The syntax of the XCTL macro and all XCTL parameters are described.
The standard form of the XCTLX macro, which presents information specific to the XCTLX macro. The topic explains the syntax of the XCTLX macro and the parameters that are valid only on XCTLX.
The list form of the XCTL and XCTLX macros.
The execute form of the XCTL and XCTLX macros.

The XCTL or XCTLX issuer can pass data to the target module in register 1 in several ways:

Using XCTL without LSEARCH and PARAM, placing the data directly in register 1. This choice is not available to the caller in AR mode.
Using the execute form of the macro, placing the address of the data on the MF parameter. For this choice, the issuer might have used the CALL macro to build a user parameter list.
Using the execute form of XCTL or XCTLX, specifying the location or locations of the data on the PARAM parameter. XCTL or XCTLX builds a list of the addresses (a user parameter list) at the location you specify on the MF parameter.

The data passed to the target module must not reside within the XCTL issuer's module; if the system deletes the XCTL issuer's module, any data in that module is not available. For more help in understanding passing parameters with XCTL and XCTLX, see Examples of passing data to the target module.

The target module gets control in the residency mode and addressing mode established by the link-edit. If XCTL=YES was specified on the ESTAE or ESTAEX macro that set up recovery for the XCTL issuer, then the ESTAE-type recovery routine covers the target module also.

The target module must return to the program that caused the XCTL issuer to run. According to linkage conventions, the target module is responsible for restoring the status of the program that originally caused the XCTL issuer to run. The status includes the contents of registers 2 through 14, as well as other information that is expected by the program that caused the XCTL issuer to run, such as:

The program interruption control area (PICA)
The program mask.

The system abnormally terminates the task under either of the following conditions:

The system cannot locate the entry point that is to receive control
The XCTL issuer added entries to the linkage stack, and did not remove those entries prior to issuing the XCTL.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24-bit or 31-bit for XCTL; 24- or 31- or 64-bit for XCTLX
ASC mode:	Primary or access register
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must reside in the primary address space
User parameters:	Must reside in the primary address space

Syntax

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

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede XCTL.

XCTL

␢	One or more blanks must follow XCTL.

(`reg1`), (`reg1,reg2`),	`reg1` and `reg2`: Decimal digits in the order 2 through 12.

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).

,LSEARCH=NO	Default: LSEARCH=NO
,LSEARCH=YES

Parameters

The parameters are explained as follows:

(reg1),

(reg1,reg2),

Specifies the register or range of registers to be restored before the target routine gets control from the save area at the address contained in register 13. Note that the registers must be specified as decimal numbers; forms like "(R2,R12)" are not accepted.

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 a 62-byte list entry for the entry name that was constructed using the BLDL macro. If EPLOC is coded, the name must be padded to eight bytes, if necessary.

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 XCTL macro, DE specifies the address of a list that was created by a BLDL macro. BLDL and XCTL 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 an ATTACH or a DETACH macro between issuances of the BLDL and the XCTL macros.

,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 used in the BLDL mentioned above. The DCB must not be defined in the XCTL issuer.

If the DCB parameter is omitted or if DCB=0 is specified when the XCTL 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 name. If the entry name is not found, the link library is searched.

If the DCB parameter is omitted or if DCB=0 is specified when the XCTL 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 the XCTL had been issued by the job step task.

Note: The DCB must reside in 24-bit addressable storage.

,LSEARCH=NO

,LSEARCH=YES

Specifies whether (YES) or not (NO) you want the search limited to the job pack area and the first library in the normal search sequence.

Note: When you use LSEARCH on XCTL, the system does not pass the contents of register 1 to the target module, unless you specify MF=(E,(1)) on the execute form.

Return and reason codes

None.

Example

Pass control through the address of the entry name (XCTLEP), and have registers 2 through 12 restored.

XCTL   (2,12),EPLOC=XCTLEP