CSRL16J — Transfer control with all registers intact

Description

Call the CSRL16J service to transfer control to another routine running under the same request block (RB). The CSRL16J service functions much like a branch instruction, but will transfer control with the contents of all registers intact.

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:	31-bit
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

Before calling the CSRL16J service, you must build data area CSRYL16J to form a parameter list that defines the entry characteristics and register contents for the target routine; include the CSRYL16J mapping macro. See z/OS MVS Programming: Assembler Services Guide for information on how to build the parameter list.

You can optionally include the CSRLJASM macro to obtain assembler declarations in the calling program for the return code from CSRL16J. CSRLJASM provides the following constants for use in your program:

**********************************************************************/
*                      Service Return Codes                          *
**********************************************************************/
CSRL16J_OK             EQU     0
CSRL16J_BAD_VERSION    EQU     4
CSRL16J_BAD_AMODE      EQU     8
CSRL16J_BAD_RESERVED   EQU     12
CSRL16J_BAD_LENGTH     EQU     16
CSRL16J_BAD_PSW        EQU     24
**********************************************************************/

Restrictions

The caller cannot have an EUT FRR established.

Input register information

Before calling the CSRL16J service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register: Contents
13: Address of a standard 18 word save area

Output register information

The CSRL16J service returns control to the caller only when it cannot successfully transfer control to the target routine because of an error. Otherwise CSRL16J transfers control to the target routine, which can return control to any program running under the same RB, including the calling program.

When CSRL16J returns control to the caller because of an error, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

When CSRL16J returns control to the caller because of an error, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.

Syntax	Description
CALL CSRL16J	,(L16J ,return_code)

Parameters

The parameters are explained as follows:

L16J: Specifies the parameter list (CSRYL16J) containing the entry characteristics and environment for the target routine.
return_code: Specifies a fullword to contain the return code from the CSRL16J service.

ABEND codes

None.

Return and reason codes

If the CSRL16J service returns control to the caller, CSRL16J was unable to transfer control to the target routine. In this case, return_code contains a nonzero value.

When the CSRL16J service successfully transfers control to the target routine, return_code contains a value of zero.

Return codes from the CSRL16J service are as follows:

Table 1. Return Codes for the CSRL16J Service
Hexadecimal Return Code	Meaning and Action
00	Meaning: Successful completion. The calling program does not receive this return code because it indicates that the target routine received control. Action: None.
04	Meaning: The value specified in the L16JVERSION field of the L16J data area was not zero. The L16JVERSION field must contain a value of zero. Action: When you build CSRYL16J, first clear the entire data area and then fill in the required fields. This process ensures that all fields that must contain zeros are correct.
08	Meaning: The calling program was not in 31-bit addressing mode, which is required. Action: Make sure the calling program is in 31-bit addressing mode.
0C	Meaning: One of the fields in CSRYL16J that is reserved for IBM® use contained a nonzero value. Any field reserved for IBM use must contain a value of zero. Action: When you build CSRYL16J, first clear the entire data area and then fill in the required fields. This process ensures that all fields that must contain zeros are correct.
10	Meaning: The value specified in field L16JLENGTH in CSRYL16J was less than the actual length of the data area. Action: Make sure that the value in the L16JLENGTH field reflects the actual length of the data area.
18	Meaning: The PSW provided in field L16JPSW of CSRYL16J specified an ASC mode that is not valid. Action: In the L16JPSW field, specify either primary or AR ASC mode.