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