Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
SA23-1375-00

Note: To suspend an RB, use the variation of the SUSPEND macro described under SUSPEND — Suspend execution of an RB.

To request suspension of a supervisor request block (SRB), use this variation of the SUSPEND macro.

When a caller issues the SUSPEND macro for an SRB, the system passes control to an exit routine identified on the SUSPEND macro and passes the suspend token to the routine. The exit routine decides whether to suspend the SRB or allow the SRB to continue execution and informs the system of its decision. If the SRB is to be suspended, the exit routine must store the suspend token so that the token can later be used to resume the SRB. The system takes the action requested by the exit routine. If the SRB is suspended, the SRB remains suspended until a subsequent RESUME macro either causes the SRB to resume execution or purges the SRB. If the exit routine allows the SRB to continue execution, control returns to the program that issued the SUSPEND macro.

Note: If the suspend completes successfully, the system will release any local lock that the caller might have held.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PSW key 0 - 7
Dispatchable unit mode:	SRB
Cross memory mode:	Any
AMODE:	31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled for I/O and external interrupts
Locks:	The caller may hold the local or CML lock but is not required to hold any
Control parameters:	Must be in the caller's primary address space or addressable through the caller's dispatchable unit access list (DU-AL)

Programming requirements

Programming requirements for the calling program are:

Before issuing the SUSPEND macro, ensure that the global symbol &SYSASCE is correctly set to indicate the ASC mode of your program. To test or set this global symbol, use the SYSSTATE macro.
Programs in AR ASC mode must ensure that parameter addresses are ALET-qualified.

Restrictions

None.

Input register information

Before issuing the SUSPEND macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.

Output register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

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

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

When control returns to the caller, the access registers contain:

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

Performance implications

None.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede SUSPEND.

SUSPEND

␢	One or more blanks must follow SUSPEND.

SPTOKEN=`sptoken addr`	`sptoken addr`: RX-type address.

,EXIT=`exit addr`	`exit addr`: RX-type address or register (2) - (12).

,EXITPARM=`exitparm addr`	`exitparm addr`: RX-type address.

,RSCODE=`rscode addr`	`rscode addr`: RX-type address.

,RELATED=`value`	`value`: Any valid macro parameter specification.

Parameters

The parameters are explained as follows:

SPTOKEN=sptoken addr: Specifies the address of an 8-byte location where the system is to place the suspend token that identifies the SRB that is to be suspended.
,EXIT=exit addr: The 31-bit address of the suspend exit routine. The suspend exit routine must be addressable in the caller's primary address space.
,EXITPARM=exitparm addr: The 31-bit address of the parameters to be passed to the suspend exit routine.
,RSCODE=rscode addr: Specifies the address of the fullword where the system is to place the resume code optionally returned by the suspend exit routine or by the program that issued the RESUME macro.
,RELATED=value: Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and content of the information provided is at the discretion of the user and may be any valid coding values.

ABEND codes

017

See z/OS MVS System Codes for an explanation and programmer responses for this code.

Return codes

When the SUSPEND macro returns control to your program, GPR 15 contains a hexadecimal return code.

Table 1. Return Codes for the SUSPEND Macro
Return Code	Meaning and Action
00	Meaning: The SRB was successfully suspended and resumed. If you code the RSCODE parameter, the program that issues the RESUME macro might have stored a value into RSCODE. Action: None.
04	Meaning: The exit routine elected to allow the SRB to continue execution. If you coded the RSCODE parameter, the exit routine might have stored a value into RSCODE. Action: None.
08	Meaning: Environmental error. A program tried to issue the SUSPEND macro from an SRB after the SRB abended with code X'47B'. This SRB cannot be suspended because it is in the process of being abended. Action: None required. However, you might take some action based upon your application.
0C	Meaning: Program error. A program tried to issue the SUSPEND macro from within the suspend exit. The suspend exit tried to resuspend the SRB. Action: Change your suspend exit program so it does not issue a SUSPEND request.
20	Meaning: Program error. An error occurred in the exit routine. Action: Correct your suspend exit program to remove program errors.
24	Meaning: A system error occurred. Action: Retry the request.

Example

Suspend the execution of an SRB.

⋮
          SUSPEND  SPTOKEN=TOKEN,EXIT=EXITRTN,RSCODE=RCODE
⋮
EXITRTN   DS    0H
⋮
          XR    15,15     Indicate to suspend the SRB
          BR    14
⋮
RCODE     DS    F'0'
TOKEN     DS    CL8
⋮