Description

The STAE macro enables the user to intercept a scheduled ABEND and to have control returned to him at a specified exit routine address. The STAE macro operates in both problem program and supervisor modes.

Note: The STAE macro is not supported for users executing in 31-bit addressing mode. Such users will be abended.

Syntax

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

Syntax	Description

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

␣	One or more blanks must precede STAE.

STAE

␣	One or more blanks must follow STAE.

`exit addr`	`exit addr`: A-type address, or register (2) - (12).
0

,CT	Default: CT
,OV

,PARAM=`list addr`	`list addr`: A-type address, or register (2) - (12).

,XCTL=NO	Default: XCTL=NO
,XCTL=YES

,PURGE=QUIESCE	Default: PURGE=QUIESCE
,PURGE=HALT
,PURGE=NONE

,ASYNCH=NO	Default: ASYNCH=NO
,ASYNCH=YES

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

Parameters

The parameters are explained as follows:

exit addr
0: Specifies the address of a STAE exit routine to be entered if the task issuing this macro terminates abnormally. If 0 is specified, the most recent STAE request is canceled.
,CT
,OV: Specifies the creation of a new STAE exit (CT) or indicates that the parameters passed in this STAE macro are to overlay the data contained in the previous STAE exit (OV).
,PARAM=list addr: Specifies the address of a user-defined parameter list containing data to be used by the STAE exit routine when it is scheduled for execution.
,XCTL=NO
,XCTL=YES: Specifies that the STAE macro will be canceled (NO) or will not be canceled (YES) if an XCTL macro is issued by this program.
,PURGE=QUIESCE
,PURGE=HALT
,PURGE=NONE: Specifies that all outstanding requests for I/O operations are not saved when the STAE exit is taken (HALT), that I/O processing is allowed to continue normally when the STAE exit is taken (NONE), or that all outstanding requests for I/O operations are saved when the STAE exit is taken (QUIESCE). For QUIESCE, at the end of the STAE exit routine, the user can code a retry routine to handle the outstanding I/O requests.

Note: If any IBM-supplied access method, except EXCP, is being used, the PURGE=NONE option is recommended. If you use PURGE=NONE, all control blocks affected by input/output processing can continue to change during STAE exit routine processing.

If PURGE=NONE is specified and the ABEND was originally scheduled because of an error in input/output processing, an ABEND recursion develops when an input/output interruption occurs, even if the exit routine is in progress. Thus, it appears that the exit routine failed when, in reality, input/output processing caused the failure.

ISAM Notes: If ISAM is being used and PURGE=HALT is specified or PURGE=QUIESCE is specified but I/O is not restored:

Only the input/output event on which the purge is done is posted. Subsequent event control blocks (ECBs) are not posted.
The ISAM check routine treats purged I/O as normal I/O.
Part of the data set may be destroyed if the data set is being updated or added to when the failure occurred.

,ASYNCH=NO
,ASYNCH=YES: Specifies that asynchronous exit processing is allowed (YES) or is not allowed (NO) while the STAE exit is executing.

ASYNCH=YES must be coded if:

The STAE exit routine requests any supervisor services that require asynchronous interruptions to complete their normal processing.
PURGE=QUIESCE is specified for any access method that requires asynchronous interruptions to complete normal input/output processing.
PURGE=NONE is specified and the CHECK macro is issued in the STAE exit routine for any access method that requires asynchronous interruptions to complete normal input/output processing.

Note: If ASYNCH=YES is specified and the ABEND was originally scheduled because of an error in asynchronous exit handling, an ABEND recursion develops when an asynchronous interruption occurs. Thus, it appears that the exit routine failed when, in reality, asynchronous exit handling caused the failure.

,RELATED=value: Specifies information used to self-document macros by relating functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values. Control returns to the instruction following the STAE macro.

Return codes

Table 1. Return and Reason Codes for the STAE Macro
Hexadecimal Return Code	Meaning
00	Successful completion of STAE request.
04	STAE was unable to obtain storage for STAE request.
08	Attempt was made to cancel or overlay a nonexistent STAE request.
0C	Exit routine or parameter list address was invalid, or STAI request was missing a TCB address.
10	Attempt was made to cancel or overlay a STAE request of another user, or an unexpected error was encountered while processing this request.

Example

Request an overlay of the existing STAE recovery exit with the following options: new exit address is ADDR, parameter list is at PLIST, halt I/O, do not take asynchronous exits, transfer ownership to the new request block resulting from any XCTL macros.

STAE ADDR,OV,PARAM=PLIST,XCTL=YES,PURGE=HALT,ASYNCH=NO