Using the XCTL or XCTLX macro

The XCTL or XCTLX macro, in addition to being used to pass control, is used to indicate to the control program that this use of the load module containing the XCTL or XCTLX macro is completed. Because control will not be returned, the XCTL issuer must load the address of the old save area into register 13 prior to issuing the XCTL. The return address must be loaded into register 14 from the old save area, as must the contents of registers 2-12. The XCTL or XCTLX macro can be written to request the loading of registers 2-12, or you can do it yourself. If you restore all registers yourself, do not use the EP parameter. This creates an inline parameter list that can only be addressed using your base register, and your base register is no longer valid. If EP is used, you must have XCTL or XCTLX restore the base register for you.

Note: A program that is XCTLed to will get control with the caller's Floating Point Registers and Floating Point Control register. The program that issued the XCTL macro is not returned to, instead the XCTLed program will return to the program that caused the issuer of the XCTL macro to run. The S/390® linkage convention applies except that the non-volatile FPRs and FPC register that must be restored are different. The issuer of the XCTL macro must restore its caller's non-volatile FPRs and FPC register before issuing the XCTL (just as if it were returning to its caller). For more information on linkage conventions, see Linkage conventions.

When using the XCTL or XCTLX macro, pass parameters to the target module in a parameter list. In this case, however, the parameter list (or the parameter data) must be established in remote storage, a portion of virtual storage outside the current load module containing the XCTL or XCTLX macro. This is because the copy of the current load module may be deleted before the called load module can use the parameters (more details follow).

The XCTL or XCTLX macro is similar to the LINK macro in the method used to pass control: control is passed by the control program using a control parameter list. The control program loads a copy of the target load module, if necessary, saves the address passed in register 14, and determines the entry address. When the entry address is to run in 24-bit or 31-bit addressing mode, the control program loads the entry address in register 15 and passes control to that address. When the entry address is to run in 64-bit addressing mode, the 64-bit program is expected to use relative branching and the control program puts into register 15 a value that can be used to determine the address mode of the issuer of the XCTL or XCTLX macro as follows:

Issuer AMODE 24: X'FFFFF000'
Issuer AMODE 31: X'FFFFF002'
Issuer AMODE 64: X'FFFFF004'

Note:

For assistance in converting a program to use relative branching, refer to the IEABRC and IEABRCX macros. End of change

The control program then passes control to the entry address. The control program adds one to the use count for the copy of the target load module and subtracts one from the use count for the current load module. The current load module in this case is the load module last given control using the control program in the performance of the active task. If you have been passing control between load modules without using the control program, chances are the use count will be lowered for the wrong load module copy. And remember, when the use count of a copy reaches zero, that copy may be deleted, causing unpredictable results if you try to return control to it.

Figure 1 shows how this could happen. Control is given to load module A, which passes control to the load module B (step 1) using a LOAD macro and a branch and link instruction. Register 14 at this time contains the address of the instruction following the branch and link. Load module B then executes, independently of how control was passed, and issues an XCTL or XCTLX macro when it is finished (step 2) to pass control to target load module C. The control program knowing only of load module A, lowers the use count of A by one, resulting in its deletion. Load module C is executed and returns to the address which used to follow the branch and link instruction. Step 3 of Figure 1 indicates the result.

Figure 1. Misusing Control Program Facilities Causes Unpredictable Results

Two methods are available for ensuring that the proper use count is lowered. One way is to always use the control program to pass control with or without return. The other method is to use only LOAD and DELETE macros to determine whether or not a copy of a load module should remain in virtual storage.

Note: The control program abnormally terminates the task if the XCTL issuer added entries to the linkage stack and did not remove them before issuing the XCTL.