Description

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 abnormal 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:

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 need to select the proper ESTAE type as follows:

Depending on whether you code ESTAE or ESTAEX, the system passes the address of the user-specified parameter list differently. The SDWAPARM field in the SDWA contains either the address of the parameter list (ESTAE), or the address of a doubleword that contains the address and ALET of the parameter list (ESTAEX). When you run in AMODE 64 (as indicated by specifying AMODE64=YES through 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.

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

The descriptions of ESTAE and ESTAEX are:
Note: The ESTAE and ESTAEX macros have the same environment specifications, register information, programming requirements, restrictions and limitations, and performance implications described as follows, except where noted in the explanation for ESTAEX.
Parent topic: ESTAE and ESTAEX — Specify task abnormal exit extended

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key. To use the CANCEL, BRANCH, KEY, TOKEN, or SPIEOVERRIDE parameters, one of the following:
  • Supervisor state
  • PKM allowing key 0-7 (for BRANCH, key 0 only)
  • APF-authorized
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 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

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 Branch-entry, IBM recommends that you have no EUT FRRs.

IBM recommends that you do not use the ESTAE or ESTAEX macro to deactivate and no longer define a FESTAE recovery routine that was defined and activated by a FESTAE macro.

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
If you specify KEY=SAVE, used as a work register by the system; otherwise, unchanged
3-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  
   
   ,CANCEL=YES Default: CANCEL=YES
   ,CANCEL=NO  
   
   ,TERM=NO Default: TERM=NO
   ,TERM=YES  
   
   ,BRANCH=NO Default: BRANCH=NO
   ,BRANCH=YES,SVEAREA=save save addr: A-type address, or register (2) - (12) or (13).
   addr  
   
   ,KEY=SAVE storage key: Any numeral in the range 0-15.
   ,KEY=storage key  
   
   ,RECORD=NO Default: RECORD=NO
   ,RECORD=YES  
   
   ,TOKEN=token addr token addr: A-type address, or register (2) - (12).
   
   ,RELATED=value value: Any valid macro keyword specification.
   
   ,SDWALOC31=NO Default: SDWALOC31=NO
   ,SDWALOC31=YES  
   
   ,SPIEOVERRIDE=NO Default: SPIEOVERRIDE=NO
   ,SPIEOVERRIDE=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 you specify 0, 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 routine (OV).
,PARAM=list addr
Specifies the 31-bit address of a user-defined list containing data to be used by the ESTAE 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 this program issues an XCTL macro.
,PURGE=NONE
,PURGE=QUIESCE
,PURGE=HALT
Specifies that all outstanding requests for I/O operations are not to be saved when the ESTAE routine receives control (HALT), or that I/O processing is to be allowed to continue normally when the ESTAE routine receives control (NONE), or that all outstanding requests for I/O operations are to be saved when the ESTAE 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.

PURGE=NONE specifies that all control blocks affected by input/output processing can continue to change during ESTAE routine processing. If you specify PURGE=NONE and the error was an error in input/output processing, recursion develops when an input/output interruption occurs, even if the ESTAE routine is in progress. Thus, it will appear that the ESTAE routine failed when, in reality, input/output processing caused the failure.

Note:
  1. You need to understand PURGE processing before using this parameter. For information about PURGE processing, see z/OS DFSMSdfp Advanced Services.
  2. When using PURGE, you need to consider any access-method ramifications. See the appropriate DFP information for the particular access method you are using to determine these ramifications.
  3. 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 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 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 ESTAE routine issues the CHECK macro 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.
,CANCEL=YES
,CANCEL=NO
Specifies whether you want to allow the recovery routine to be interrupted by cancel or detach processing.

To allow a recovery routine to be interrupted, specify CANCEL=YES.

To prevent a recovery routine from being interrupted, specify CANCEL=NO. If a cancel or detach is attempted against a recovery routine for which you have specified CANCEL=NO, MVS™ defers cancel and detach processing until the recovery routine returns control to the system.
Note:
  1. If a recovery routine that runs under the CANCEL=NO option can be called by an unauthorized program running under the same task, IBM recommends that you specify ASYNCH=NO for each ESTAE(X) macro that the recovery routine issues. This also includes any ESTAE(X) macros issued by programs that the recovery routine calls.
  2. If a recovery routine running under the CANCEL=NO option calls an unauthorized program, cancel and detach processing is also deferred for the called program.
,TERM=NO
,TERM=YES
Specifies that the ESTAE routine will be scheduled (YES) or will not be scheduled (NO) 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 nonjob step task issued the ABEND macro with the STEP parameter.
  • z/OS UNIX is canceled and the user's task is in a wait in the z/OS UNIX kernel.

When the ESTAE routine is entered because of one of the preceding reasons, retry is not permitted. If a dump is requested at the time the ABEND macro is issued, it is taken before entry into the ESTAE routine.

Note: If DETACH was issued with the STAE parameter, the following occurs for the task to be detached:
  • All ESTAE routines are entered.
  • The most recently activated STAE routine is entered.
  • All STAI/ESTAI routines are entered unless one of the STAI routines issues return code 16.

In these cases, entry to the routine occurs before dumping and retry is not permitted.

,BRANCH=NO
,BRANCH=YES,SVEAREA=save addr
Specifies that an SVC entry to the ESTAE service routine is to be performed (NO) or that a branch entry is to be performed (YES). The save area is a 72-byte area used to save the general registers. If the caller is not in key zero, the KEY parameter must be specified.

BRANCH and SVEAREA are not valid on ESTAEX.

,KEY=SAVE
,KEY=storage key
Specifies that supervisor state users who are not in key zero can use the branch entry interface to the ESTAE service routine.

If the user specifies KEY=SAVE, the macro saves the current PSW protection key in register 2 and issues a set protection key instruction (SPKA) to change to protection key zero. When the ESTAE service routine returns control, it restores the original PSW key from register 2. Therefore, the user should save register 2 before the macro expansion and restore it afterwards. Specifying KEY=SAVE destroys the contents of register 2 during the macro expansion.

On the other hand, if the user knows the current PSW protection key, he may specify it directly in the form KEY=(0-15) to eliminate saving and restoring the original protection key. This procedure eliminates an IPK instruction and prevents the use of register 2 in the macro expansion.

KEY is not valid on ESTAEX. KEY is optional and valid only with BRANCH=YES,SVEAREA=save addr.

,RECORD=NO
,RECORD=YES
Specifies whether the system diagnostic work area (SDWA) is to be recorded in SYS1.LOGREC. If you specify RECORD=YES, the system records the entire SDWA (including the fixed length base, the variable length recording area, and the recordable extensions) in SYS1.LOGREC when the associated ESTAE recovery routine returns control, unless the recovery routine indicates otherwise by issuing the SETRP macro with RECORD=NO.

If you specify RECORD=NO, the system does not record the SDWA in SYS1.LOGREC, unless the recovery routine indicates otherwise by issuing the SETRP macro with RECORD=YES.

,TOKEN=token addr
Specifies that a four-byte token is to be associated with the ESTAE routine. Unauthorized or accidental destruction of the ESTAE routine is prevented because the ESTAE cannot be canceled or overlaid unless the same token is specified.

With CT: ESTAE processing places the token created for this request in the location specified by token addr as well as in the ESTAE parameter list.

With OV: ESTAE processing locates the specified ESTAE routine for the current RB and replaces the routine information. If there are any newer ESTAE routines for the RB, they are deactivated and no longer defined.

With a recovery routine address of 0: ESTAE processing locates the specified ESTAE routine for the current RB and deactivates the routine. The routine is no longer defined. Any newer ESTAE routines for the RB are deactivated and no longer defined.

,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 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.)
,SPIEOVERRIDE=NO
,SPIEOVERRIDE=YES
SPIEOVERRIDE specifies that the ESTAEX recovery exit must receive control for all program exceptions even if a SPIE or ESPIE exit is established.

While the recovery routine that requests this parameter is established, no SPIE or ESPIE exit can receive control.

You can use this parameter to ensure that the ESTAEX recovery exit receives control for all program exceptions that occur while running in Problem state.

The SPIEOVERRIDE parameter is not required for programs that run in Supervisor state, run in cross-memory, or hold any lock, because SPIE and ESPIE exits are not eligible to receive control in these environments.

SPIEOVERRIDE is not valid on ESTAE.

The default value is SPIEOVERRIDE=NO.

ABEND codes

None.

Return and reason codes

When control returns 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.

Table 1. Return and Reason Codes for the ESTAE Macro
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.
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 TCB,
  • The most recent recovery routine is not owned by the caller,
  • The most recent recovery routine is not an ESTAE recovery routine, or
  • The ESTAE was created with the TOKEN parameter and on a deactivate request, either
    • The token was not specified or
    • The token does not match.

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 codes and supply them to the appropriate IBM support personnel.
14 None Meaning: Environmental error. ESTAE was unable to obtain storage for a system data area.

Action: Free some storage and reissue the ESTAE macro.
18 None Meaning: Program error. ESTAE OV request was invalid for one of the following reasons:
  • ESTAE OV with the TOKEN parameter was specified but
    • No ESTAE recovery routine exists or
    • The recovery routine is not an ESTAE recovery routine created with the matching token value by the current RB.
  • ESTAE OV without the TOKEN parameter was specified but the ESTAE recovery routine was created with the TOKEN parameter.

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 list.

Action: Make sure the parameter list 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.
30 None Meaning: Program error. Branch-entered ESTAE CT was specified, but it was rejected because the caller has a cross-memory environment.

Action: Use ESTAEX for programs that run in a cross-memory environment.

Example 1

If an error occurs, pass control to the ESTAE routine specified by register 4, allow asynchronous exit processing, do not allow special error processing, do not branch enter, and default to CT and PURGE=NONE. 
ESTAE (4),ASYNCH=YES,TERM=NO,BRANCH=NO

Example 2

If an error occurs, pass control to the ESTAE routine specified by register 4. The address of the ESTAE parameter list is in register 2. Place the token associated with this ESTAE routine in TOKENFLD. 
ESTAE (4),PARAM=(2),TOKEN=TOKENFLD

Example 3

If an error occurs, pass control to the ESTAE routine labeled ADDR, allow synchronous exit processing, halt I/O, allow special error processing, branch enter, use the 72-byte save area at SADDR, and execute the execute form of the macro. EXEC is the label of the ESTAE parameter list built by a list form of the macro elsewhere in this program. 
ESTAE ADDR,ASYNCH=YES,PURGE=HALT,TERM=YES,BRANCH=YES,   X
      SVEAREA=SADDR,MF=(E,EXEC)

Example 4

Request an overlay of the existing ESTAE recovery routine with the following options: the address of the parameter list is at 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 5

Provide the pointer to the recovery code in the register called EXITPTR, place the address of the ESTAE parameter list in register 9. Register 8 points to the area where the ESTAE parameter list (created with the MF=L option) was moved. 
ESTAE   (EXITPTR),PARAM=(9),MF=(E,(8))