Description

Description

z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369-00

The ESTAE macro provides recovery capability facilities. Issuing the ESTAE macro allows the caller to intercept errors. Control is given to a caller-specified exit routine (called a recovery routine) in which the caller can perform various tasks, including diagnosing the cause of the error and specifying a retry address to avoid abnormally ending.

ESTAE type considerations: The type of ESTAE routine, that is, ESTAE or ESTAEX affects the AMODE of the recovery routine as follows. For recovery routines defined through the:

ESTAE macro, at the time of entry to the recovery routine, the AMODE will be the same as at the time of invocation of the macro.
ESTAEX macro, the AMODE will be the same as at the time of invocation of the macro, unless the macro was invoked in AMODE 24 in which case the recovery routine AMODE will be 31-bit.
The AMODE at the retry point will be the same as the AMODE on entry to the recovery routine.

Various mode considerations: Depending on address space, cross-memory (the primary, secondary, and home address spaces are the same), and access register (AR) modes, you should select the proper ESTAE type as follows:

If your program is to execute in 31-bit addressing mode, you must use the SP Version 2 of the ESTAE macro or a later version. For information about how to select a macro for an MVS/SP version other than the current version, see Compatibility of MVS macros.
Callers that are in primary address space control (ASC) mode and not in cross-memory mode can issue either ESTAE or ESTAEX.
Callers that are in access register (AR) mode or in cross-memory mode must use ESTAEX.
IBM® recommends that all callers use the ESTAEX macro, unless your program and your recovery routine are in 24-bit addressing mode, in which case you should use ESTAE.

Depending on whether you code ESTAE or ESTAEX, the system passes the address of the user-specified parameter area differently. The SDWAPARM field in the SDWA contains either the address of the parameter area (ESTAE), or the address of a doubleword that contains the address and ALET of the parameter area (ESTAEX). When you run in AMODE 64 (as indicated by specifying AMODE64=YES via the SYSSTATE macro) and invoke ESTAEX, your ESTAEX routine will get control in AMODE 64. The 8-byte area pointed to by the SDWAPARM field will be the 8-byte address of the parameter area. Note that no ALET information is provided to the ESTAEX routine in this case.

See the section on providing recovery in z/OS MVS Programming: Assembler Services Guide for information about writing recovery routines.

The descriptions of ESTAE and ESTAEX in this book are:

The standard form of the ESTAE macro, which includes general information about the ESTAE and ESTAEX macros, with some specific information about the ESTAE macro. The syntax of the ESTAE macro is presented, and all ESTAE parameters are explained.
The standard form of the ESTAEX macro, which includes information specific to the ESTAEX macro. The syntax of the ESTAEX macro is presented.
The list form of the ESTAE and ESTAEX macros.
The execute form of the ESTAE and ESTAEX macros.

Note: The ESTAE and ESTAEX macros have the same environment specifications, register information, programming requirements, restrictions and performance implications described below, except where noted in the explanation for ESTAEX.

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:	24- or 31-bit for ESTAE; 24- or 31- or 64-bit for ESTAEX
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

If the program is in AR mode, you must use ESTAEX rather than ESTAE; issue the SYSSTATE macro with the ASCENV=AR parameter before you issue ESTAEX. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.

Restrictions

For SVC-entry, you must have no EUT FRRs.
For branch entry, IBM recommends that you have no EUT FRRs.

Input register information

Before issuing the ESTAE 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

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

Register: Contents
0: Reason code if GPR 15 contains X'4'; otherwise, used as a work register by the system
1: Used as a work register 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 (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 standard form of the ESTAE macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede ESTAE.

ESTAE

␢	One or more blanks must follow ESTAE.

`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=NONE	Default: PURGE=NONE
,PURGE=QUIESCE
,PURGE=HALT

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

,TERM=NO	Default: TERM=NO
,TERM=YES

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

,SDWALOC31=NO	Default: SDWALOC31=NO
,SDWALOC31=YES

Parameters

The parameters are explained as follows:

exit addr

0

Specifies the 31-bit address of an ESTAE recovery routine to be entered if the task issuing this macro ends abnormally. If 0 is specified, the most recent ESTAE recovery routine is deactivated and no longer defined.

The ESTAEX exit always gets control in 31-bit mode, regardless of the mode in which the macro was invoked.

,CT

,OV

Specifies that a new ESTAE recovery routine is to be defined and activated (CT); or indicates that parameters passed in this ESTAE macro are to overlay the data contained in the previous ESTAE recovery routine (OV).

,PARAM=list addr

Specifies the address of a user-defined parameter area containing data to be used by the ESTAE recovery routine when it is scheduled for execution.

,XCTL=NO

,XCTL=YES

Specifies that the ESTAE recovery routine will be deactivated and no longer defined (NO) or will remain activated and defined (YES) if an XCTL macro is issued by this program.

,PURGE=NONE

,PURGE=QUIESCE

,PURGE=HALT

Specifies that all outstanding requests for I/O operations will not be saved when the ESTAE recovery routine receives control (HALT), that I/O processing will be allowed to continue normally when the ESTAE recovery routine receives control (NONE), or that all outstanding requests for I/O operations will be saved when the ESTAE recovery routine receives control (QUIESCE). If QUIESCE is specified, the user's retry routine can restore the outstanding I/O requests.

For PURGE=QUIESCE and PURGE=HALT, RTM requests that all I/O be purged at the task level for the current task. Be aware that the purge request involves all I/O started by the task, not just the I/O started by the program that created this recovery routine. PURGE=QUIESCE must thus be used carefully, as it may wait for I/O that was not started by the program that created this recovery routine. Likewise, PURGE=HALT must be used carefully as it may terminate I/O that was not started by the program that created this recovery routine.

If PURGE=NONE is specified, all data areas affected by input/output processing may continue to change during ESTAE recovery routine processing.

If PURGE=NONE is specified and the error was an error in input/output processing, recursion will develop when an input/output interruption occurs, even if the recovery routine is in progress. Thus, it will appear that the recovery routine failed when, in reality, input/output processing was the cause of the failure.

Do not use PURGE=HALT to stop processing a data set if you expect to continue reading the data set at a different point.

Note:

You need to understand PURGE processing before using this parameter. For information about PURGE processing, see &idas300t;.
When using PURGE, you should consider any access-method ramifications. See the appropriate DFP manual for the particular access method you are using to determine these ramifications.
The system performs the requested I/O processing only for the first ESTAE-type recovery routine that gets control. Subsequent routines that get control receive an indication of the I/O processing previously done, but no additional processing is performed.

,ASYNCH=YES

,ASYNCH=NO

Specifies that asynchronous exit processing will be allowed (YES) or prohibited (NO) while the user's ESTAE recovery routine is running.

ASYNCH=YES must be coded if:

Any supervisor services that require asynchronous interruptions to complete their normal processing are going to be requested by the ESTAE recovery routine.
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 ESTAE recovery routine for any access method that requires asynchronous interruptions to complete normal input/output processing.

Note: If ASYNCH=YES is specified and the error was an error in asynchronous exit handling, recursion will develop when an asynchronous exit handling was the cause of the failure.

,TERM=NO

,TERM=YES

Specifies that the recovery routine associated with the ESTAE request will be scheduled (YES) or will not be scheduled (NO), in addition to normal ESTAE processing, in the following situations:

System-initiated logoff
Job step timer expiration
Wait time limit for job step exceeded
DETACH macro without the STAE=YES parameter issued from a higher-level task (possibly by the system if the higher-level task encountered an error)
Operator cancel
Error on a higher level task
Error in the job step task when a non-job step task issued the ABEND macro with the STEP parameter.
z/OS UNIX System Services is canceled and the user's task is in a wait in the z/OS UNIX System Services kernel.

When the recovery routine is entered because of one of the preceding reasons, retry will not be permitted. If a dump is requested at the time the ABEND macro is issued, it is taken prior to entry into the recovery routines.

Note: If DETACH was issued with the STAE parameter, the following will occur for the task to be detached:

All ESTAE recovery routines will be entered.
The most recently activated STAE recovery routine will be entered.
All STAI/ESTAI recovery routines will be entered unless return code 16 is returned from one of the STAI recovery routines.

In these cases, entry to the recovery routine is prior to dumping and retry will not be permitted.

,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.
,SDWALOC31=NO
,SDWALOC31=YES: Specifies that the SDWA be in 31-bit storage (YES) or the default 24-bit storage (NO). You must specify SDWALOC31=YES when the your program is running in AMODE 31 and you are using 64-bit general purpose registers, because the time-of-error 64-bit GPRs are only presented to routines with an SDWA in 31-bit storage. Only routines with an SDWA in 31-bit storage can retry while setting those registers.
Note: The SDWALOC31= parameter applies to ESTAE only. (For ESTAEX, the SDWA is always in 31-bit storage.)

ABEND codes

X'13C'

See z/OS MVS System Codes for an explanation and programmer response for the abend code.

Return and reason codes

When control is returned to the instruction following the ESTAE macro, GPR 15 contains one of the following return codes and GPR 0 contains one of the following reason codes.

Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	none	Meaning: Successful completion of the ESTAE request. Action: None.
04	00	Meaning: Program error. ESTAE OV was specified but ESTAE CT was performed. No valid ESTAE recovery routine existed. Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.
04	04	Meaning: Program error. ESTAE OV was specified but ESTAE CT was performed. The last ESTAE recovery routine was not owned by the user's RB. Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.
04	08	Meaning: Program error. ESTAE OV was specified but ESTAE CT was performed. The last ESTAE recovery routine was not created at the current linkage stack level. Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.
04	0C	Meaning: Program error. ESTAE OV was specified but ESTAE CT was performed. The last recovery routine was not an ESTAE recovery routine. Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.
0C	none	Meaning: Program error. A recovery routine address equal to zero was specified and either there are no recovery routines for this task, the most recent recovery routine is not owned by the caller, or the most recent recovery routine is not an ESTAE recovery routine. Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.
10	none	Meaning: System error. An unexpected error was encountered while this request was being processed. Action: Rerun your program one or more times. If the problem persists, record the return and reason code and supply it to the appropriate IBM support personnel.
14	none	Meaning: System error. ESTAE was unable to obtain storage for a system data area. Action: Rerun your program one or more times. If the problem persists, check with the operator to see if the installation is experiencing a storage constraint problem.
18	none	Meaning: Program error. ESTAE OV was specified without the TOKEN parameter, but the ESTAE recovery routine was created with the TOKEN parameter. (The TOKEN parameter is available only to programs in supervisor state with PSW key 0-7 or programs that are APF-authorized.) Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.
1C	none	Meaning: Program error. ESTAE was unable to access the input parameter area. Action: Make sure the parameter area is in the primary address space and reissue the ESTAE macro.
20	none	Meaning: Program error. XCTL=YES was rejected because the linkage stack was not at the same level as it was when the RB was created. Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.
24	none	Meaning: Program error. A recovery routine address equal to zero was specified, but it was rejected because no ESTAE recovery routines were active for the current linkage stack level. Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.
28	none	Meaning: Program error. ESTAE OV was specified, but it was rejected because no ESTAE recovery routines were active for the current linkage stack level. Action: Correct the environment and either reissue the ESTAE macro or rerun your program, as appropriate.

Example 1

Request an overlay of the existing ESTAE recovery routine (at ADDR), with the following options: parameter area is as PLIST, I/O will be halted, no asynchronous exits will be taken, ownership will be transferred to the new request block resulting from any XCTL macros.

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

Example 2

Provide the pointer to the recovery code in the register called EXITPTR, and the address of the ESTAE recovery routine parameter area in register 9. Register 8 points to the area where the ESTAE parameter area (created with the MF=L option) is to be modified.

ESTAE  (EXITPTR),PARAM=(9),MF=(E,(8))