CALLRTM — Call recovery termination manager

Description

The CALLRTM macro schedules abnormal termination for a task, an address space, or a preemptable SRB identified by the token returned by the SRBIDTOKEN= parameter of the IEAMSCHD macro.

To terminate a task, use TYPE=ABTERM and the following parameter or parameters to identify the specific task.

For a task in the home address space, use TCB or TTOKEN.
For a task in a specific address space, use one of the following:
- TTOKEN and ASID
- TCB and ASID.

To terminate an address space, use TYPE=MEMTERM. Be aware, however, that tasks in the abending address space cannot perform recovery and task-level resource managers do not get control. (Note that address space recovery routines and resource managers do get control.) To terminate an address space, consider using CALLRTM TYPE=ABTERM,RETRY=NO to abend each job step task in the address space. When all tasks in the address space have terminated, the system terminates the address space.

To terminate a preemptable SRB identified by the token returned by the SRBIDTOKEN= parameter of the IEAMSCHD macro, use TYPE=SRBTERM. The target SRB is processed asynchronously and may terminate after control has returned to the invoking program. Also, the target SRB may finish normally before RTM can terminate it with the requested completion code. If the target SRB has not started yet, it may be purged instead of abended (in which case its RMTR will receive control).

For more information about using CALLRTM, see z/OS MVS Programming: Authorized Assembler Services Guide.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state and PSW key 0
Dispatchable unit mode:	Task or SRB
Cross memory mode:	For TYPE=MEMTERM and TYPE=SRBTERM, any PASN, any HASN, any SASN. For TYPE=ABTERM, see the TCB and TTOKEN parameter descriptions.
AMODE:	24- or 31-bit, except for TYPE=SRBTERM which only supports AMODE 31 callers.
ASC mode:	Primary or secondary
Interrupt status:	When using TTOKEN to terminate a task other than the current one, the caller must not be disabled for I/O and external interrupts.
Locks:	When terminating a task without specifying ASID, the caller must hold the LOCAL lock. When terminating an SRB, any lock may be held, but none are required.
Control parameters:	For callers in primary ASC mode, control parameters must be in the primary address space; in secondary mode, control parameters must be in the secondary address space.

Programming requirements

When the caller runs in 31-bit addressing mode, all input parameters except the TCB can reside above 16 megabytes. The TCB always resides below 16 megabytes.
The caller must include the CVT mapping macro.

Restrictions

None.

Input register information

Before issuing the CALLRTM macro with TYPE=MEMTERM, or with TYPE=ABTERM with ASID or TTOKEN or both, the caller must ensure that the following general purpose registers (GPRs) contain the specified information.

Register: Contents
13: The address of a 72-byte work area
Note: The work area that you provide is not the standard 72-byte save area. The system stores into the area. If you pass in register 13 the save area that you are using to link your program to your caller's, you will not be able to get back to your caller.

Before issuing the CALLRTM macro with TYPE=SRBTERM, the caller must ensure that the following general purpose registers (GPRs) contain the specified information.

Register: Contents
13: The address of a 144-byte work area
Note: The work area that you provide is not the standard 144-byte save area. The system stores into the area. If you pass in register 13 the save area that you are using to link your program to your caller's, you will not be able to get back to your caller.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0-1: Used as work registers by the system
2: If you specify the ASID parameter, used as a work register by the system; otherwise, unchanged
3: If you specify the DUMPOPT or DUMPOPX parameter, used as a work register by the system; otherwise, unchanged
4-5: Unchanged
6: If you specify the TYPE=ABTERM or TYPE=SRBTERM, COMPCOD, and REASON parameters, used as a work register by the system; otherwise, unchanged
7-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, 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

The CALLRTM macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede CALLRTM.

CALLRTM

␢	One or more blanks must follow CALLRTM.

TYPE=ABTERM
TYPE=MEMTERM
TYPE=SRBTERM
,SRBIDTOKEN=`token addr`	`token addr`: 16-byte token.

,COMPCOD=`comp code`	`comp code`: Symbol, decimal digit, or register (1) - (12).

,REASON=`code`	`code`: Symbol, decimal or hexadecimal number, or register (2) - (12).

,ASID=`asid`	`asid`: Decimal digits 0-32,765 or register (2) - (15).

,TCB=`tcb addr`	`tcb addr`: 0, or register (2) - (12).
,TTOKEN=`ttoken`	`ttoken`: 0, or register (2) - (12).
	Note: Use TCB and TTOKEN only with TYPE=ABTERM.
	Default: TCB=0

,STEP=NO	Default: STEP=NO
,STEP=YES	Note: Use STEP only with TYPE=ABTERM.

,DUMP=YES	Default: DUMP=YES
,DUMP=NO	Note: Use DUMP only with TYPE=ABTERM.

,DUMPOPT=`parm list addr`	`parm list addr`: Register (3) - (15).
,DUMPOPX=`parm list addr`	`parm list addr`: Register (3) - (15).
	Note: Use DUMPOPT and DUMPOPX only with DUMP=YES.

,RETRY=YES	Default: RETRY=YES
,RETRY=NO	Note: Use RETRY only with TYPE=ABTERM.

,SYSTEM=YES	Default: SYSTEM=YES
,SYSTEM=NO

Parameters

The parameters are explained as follows:

TYPE=ABTERM

TYPE=MEMTERM

TYPE=SRBTERM,SRBIDTOKEN=token addr

Specifies whether CALLRTM is to terminate a task (ABTERM), an address space (MEMTERM), or a preemptable SRB (SRBTERM) identified by the token returned by the SRBIDTOKEN= parameter of the IEAMSCHD macro.

For TYPE=ABTERM, you must identify the task through the TCB or TTOKEN parameters.

For TYPE=MEMTERM, no task-level recovery processing occurs.

For TYPE=SRBTERM, the 16-byte token pointed to by token addr uniquely identifies the preemptable SRB to be terminated, including its ASID. The following CALLRTM parameters are valid when TYPE=SRBTERM has been specified: COMPCOD, REASON, RETRY, SYSTEM. The default values for RETRY and SYSTEM are YES. COMPCOD must be specified. Use CALLRTM TYPE=SRBTERM only when the SRBIDTOKEN has been successfully returned by the IEAMSCHD macro, as indicated by a non-zero value in the first eight bytes of the SRBIDTOKEN.

,COMPCOD=compcode

Specifies the system (if you specify SYSTEM=YES or take the default) or user (if you specify SYSTEM=NO) completion code (0 - 4096 decimal) that you associate with the abnormal termination. Specify this parameter as a hexadecimal code (x‘80A’), a decimal code (2058), or a register containing a hexadecimal code. In all cases, the result is hexadecimal.

,REASON=code

Specifies information to supplement the completion code associated with an abnormal termination. The value range for the reason code is a 32-bit hexadecimal number or 31-bit decimal number. In all cases, the result is hexadecimal.

The system passes the reason code value to the recovery routine in the SDWACRC field of the SDWA.

For TYPE=SRBTERM, set the high-order bit of the reason code to 1 when you want to indicate that an SVCDUMP is not necessary for the abend being issued. The system does not do anything special with this bit, but recovery routines can use the information when determining if they should request an SVCDUMP of the abend.

,ASID=asid

Specifies the address space to be terminated (for MEMTERM), or the one that contains the task to be terminated (for ABTERM). ASID=0, the default, specifies the home address space.

,TCB=tcb addr

,TTOKEN=ttoken

Specifies the task to be terminated. TCB=0 is the default, which identifies the current task.

tcb addr is the address of the TCB that CALLRTM is to terminate.

If the current task is specified or implicitly specified by not specifying either TCB= or TTOKEN=, a non-zero ASID parameter must also be specified.

When you specify TCB=tcb address and you omit the ASID parameter, the system assumes the task is in the home address space and that the home address space is currently addressable. That is:

If you are in primary ASC mode, the primary address space must be the home address space (PASN=HASN).
If you are in secondary ASC mode, the secondary address space must be the home address space (SASN=HASN).

ttoken specifies the TTOKEN for the task that is to be terminated. ASID with TTOKEN identifies a task in the specified address space.

When you omit the ASID parameter, there are requirements on locks. See Environment.

,STEP=NO

,STEP=YES

Specifies whether the job step task associated with the specified task is (YES) or is not (NO) to be abnormally terminated if the specified task terminates. Note that the job step task does not end abnormally if the specified task successfully retries.

STEP is valid only for TYPE=ABTERM.

,DUMP=YES

,DUMP=NO

Specifies whether a dump is (YES) or is not (NO) to be taken. You can use DUMPOPT or DUMPOPX to specify the dump options; otherwise, the contents of the dump are defined by the //SYSABEND, //SYSMDUMP, or //SYSUDUMP DD statement and the system or user-defined defaults. The target address space of the CALLRTM request is treated as the dump error address space.

The final decision on whether a dump will be taken depends on the recovery routines that run as a result of this CALLRTM. If the recovery routines indicate in the ",DUMP=" option of the SETRP macro whether a dump is to be taken, this specification overrides the ",DUMP=" value in CALLRTM.

,DUMPOPT=parm list addr

,DUMPOPX=parm list addr

Specifies the address of a parameter list of dump options. To create the parameter list, use the list form of the SNAP or SNAPX macro; or build the parameter list by coding your own data constants. DUMPOPT specifies the address of a parameter list that the SNAP macro creates. DUMPOPX specifies the address of a parameter list that the SNAPX macro creates. When you terminate a task that is not the current one, the dump options must reside in fixed or disabled reference (DREF) storage.

The system dump options, specified by the CHNGDUMP operator command, can add to or override this parameter list. All recovery routines entered for the failure can also add to the list of dump options. The TCB, DCB, ID, and STRHDR options available on SNAP or SNAPX are ignored when they appear in the parameter list. The TCB is for the task that receives the ABEND. The DCB is provided by the ABDUMP routine. When a //SYSABEND, //SYSMDUMP, or //SYSUDUMP DD statement is not provided, the system ignores the DUMPOPT or DUMPOPX parameters.

Note: When you use this parameter, the system destroys the contents of register 3.

,RETRY=YES

,RETRY=NO

Specifies whether the target task's recovery routines can retry. If you specify RETRY=NO, the recovery routines are forced to percolate rather than retry. RETRY is valid only for TYPE=ABTERM. RETRY=YES is the default.

,SYSTEM=YES

,SYSTEM=NO

Specifies whether the completion code is to be a system or user completion code.

ABEND codes

CALLRTM might abnormally terminate with abend code X'70D'. See z/OS MVS System Codes for an explanation of this abend code and its associated reason codes.

Return codes

When CALLRTM returns control to your program, for TYPE=ABTERM, register 15 contains one of the following hexadecimal return codes.

Table 1. Return codes for the CALLRTM macro for TYPE=ABTERM
Hexadecimal return code	Meaning and action
00	Meaning: The ABTERM request was processed successfully. Action: None.
04	Meaning: The task has already been scheduled for termination by a previous ABTERM request. Action: None.
08	Meaning: An asynchronous unit of work has been scheduled to terminate the task. Action: None.
18	Meaning: Program error. The ASID value is not valid. Action: Ensure that the ASID specified represents a currently active address space.
1C	Meaning: Program error. The TCB address or TTOKEN does not represent a valid TCB. Action: Ensure that the TCB address or TTOKEN represents a valid TCB within the primary address space or the ASID parameter is also specified to further qualify the target TCB.
20	Meaning: Program error. TTOKEN specifies a TCB in another address space. Action: The ASID parameter must also be specified to terminate the TCB in another address space.
24	Meaning: Program error. The caller tried to terminate a task other than the current task, but did not hold the LOCAL lock. Action: Ensure that the LOCAL lock is obtained prior to invoking the CALLRTM macro for this type of request.
28	Meaning: Program error. TTOKEN specifies a task other than the current one and the caller is disabled for I/O and external interrupts. Action: Ensure that the caller is enabled for I/O and external interrupts before invoking the CALLRTM macro for this type of request.

When CALLRTM returns control to your program, for TYPE=MEMTERM, register 15 contains one of the following hexadecimal return codes.

Table 2. Return codes for the CALLRTM macro for TYPE=MEMTERM
Hexadecimal return code	Meaning and action
00	Meaning: The MEMTERM request was scheduled successfully. Note that memory termination occurs asyncronously and that the actual termination process might not have started when the CALLRTM service returns to its caller. Termination of an address space might also be temporarily deferred by a system service. If so, when the deferral condition is released, the system will honor the MEMTERM request. Action: None.
18	Meaning: Program error. The ASID value is not valid. Action: Ensure that the ASID represents a currently active address space.
2C	Meaning: Environmental error. The requested ASID represents an address space that is non-memtermable. Action: The memory termination request is not honored. Depending on the circumstances involved, it might be appropriate to stop the system with a WAIT state when this return code is received.

When CALLRTM returns control to your program, for TYPE=SRBTERM, register 15 contains one of the following hexadecimal reason and return codes. The first 3 bytes of the register contain the reason code and the last byte contains the return code.

Table 3. Reason and return codes for the CALLRTM macro for TYPE=SRBTERM
Hexadecimal reason code	Hexadecimal return code	Meaning and action
000000	00	Meaning: The SRBTERM request was scheduled successfully. The target SRB will be terminated at the next opportunity. Action: None.
000001	04	Meaning: The SRBIDTOKEN is no longer valid. This return code implies that the target SRB has already terminated. Action: None.
000002	04	Meaning: An SRBTERM request with RETRY=YES was issued against an SRB for which a previous SRBTERM request with RETRY=NO is still being processed. The older RETRY=NO SRBTERM will be honored rather than the new RETRY=YES SRBTERM. Action: None.
000001	08	Meaning: The SRBIDTOKEN contains data that is not valid. Action: Ensure that the SRBIDTOKEN parameter points to a valid token which was returned by the IEAMSCHD service.
000001	10	Meaning: System error. The target SRB will terminate if it is running, but may not terminate if it is suspended or stopped. Action: If the SRB does not terminate, reissue the SRBTERM request a reasonable number of times. If the SRB still does not terminate, report this error to the appropriate IBM support personnel.
000002	10	Meaning: System error. The target SRB will not be terminated. Action: Report this error to the appropriate IBM support personnel.

Example 1

Terminate the primary address space with a completion code of 123.

CALLRTM   TYPE=MEMTERM,COMPCOD=123,ASID=0

Example 2

Schedule the TCB, addressed in register 8, for abnormal termination. The abnormal termination of the TCB takes place in the address space identified by the ASID, specified in register 5. It has a completion code of 123.

CALLRTM   TYPE=ABTERM,COMPCOD=123,ASID=(5),TCB=(8)

Example 3

Terminate the current task and its associated job step task. Register 1 identifies the completion code and register 6 identifies the accompanying reason code. The system does not allow the recovery routines of the job step task and its attached tasks to retry from the abend.

CALLRTM TYPE=ABTERM,RETRY=NO,STEP=YES,TCB=0,COMPCOD=(1),REASON=(6)

Example 4

Terminate the address space identified by the contents of register 2. Register 1 identifies the completion code. TYPE=MEMTERM prevents all task-related recovery, including task resource managers, from getting control. The system gives control only to the address space's resource managers.

CALLRTM TYPE=MEMTERM,ASID=(2),COMPCOD=(1)