Note: - IBM® recommends you
use the ESTAEX or ESTAE macro, or the ESTAI parameter on ATTACHX.
- Under certain circumstances, STAE or STAI routines might receive
control in a restricted environment. See Restricted environments for
more information.
The STAE macro causes a recovery routine address to be made known
to the system. This recovery routine is associated with the task
and the RB that issued STAE. Use of the STAI option on the ATTACH
macro also causes a recovery routine to be made known to the system,
but the routine is associated with the subtask created through ATTACH.
Furthermore, STAI recovery routines are propagated to all lower-level
subtasks of the subtask created with ATTACH that specified the STAI
parameter.
If a task is scheduled for abnormal termination, the recovery routine
specified by the most recently issued STAE macro gets control and
runs under a program request block created by the SYNCH service routine.
Only one STAE routine receives control. The STAE routine must specify,
by a return code in register 15, whether a retry routine is to be
scheduled. If no retry routine is to be scheduled (return code =
0) and this is a subtask with STAI recovery routines, the STAI recovery
routine is given control. If there is no STAI recovery routine, abnormal
termination continues.
If there is more than one STAI recovery routine existing for a
task, the newest one receives control first. If it requests that
termination continue (return code = 0), the next STAI routine receives
control. This continues until either all STAI routines have received
control and requested that the termination continue, a STAI routine
requests retry (return code = 4 or 12), or a STAI routine requests
that the termination continue but no further STAI routines receive
control (return code = 16).
Programs running under a single TCB can issue more than one STAE
macro with the CT parameter to define more than one STAE routine.
Each issuance temporarily deactivates the previous STAE routine. The
previous STAE routine becomes active when the current STAE routine
is deactivated.
A STAE routine is deactivated (it cannot receive control again
for this error) under any of the following circumstances:
- When the RB that activated it goes away (unless it issued XCTL
and specified the XCTL=YES parameter on the STAE macro)
- When the STAE macro is issued with an address of 0
- When the STAE routine receives control.
If a STAE routine receives control and requests retry, the retry
routine reissues the STAE macro if it wants continued STAE protection.
A STAI routine is deactivated if the task completes or if the STAI
routine requests that termination continue and no further STAI processing
be done. In the latter case, all STAI recovery routines for the task
are deactivated.
STAE and STAI routine environment: Prior to
entering a STAE or STAI recovery routine, the system attempts to obtain
and initialize a work area that contains information about the error. The first 4 bytes of the SDWA contains the address of the
user parameter area specified on the STAE macro or the STAI parameter
on the ATTACH macro.
Upon entry to the STAE or STAI routine, the GPRs contain the following:
If an SDWA was obtained:
- GPR
- Contents
- 0
- A code indicating the type of I/O processing performed:
-
-
- 0
- Active I/O has been quiesced and is restorable.
- 4
- Active I/O has been halted and is not restorable.
- 8
- No active I/O at abend time.
- 16 (X'10')
- Active I/O, if any, was allowed to continue.
- 1
- Address of the SDWA.
- 2
- Address of the parameter area you specified on the PARAM parameter.
- 3-12
- Do not contain any information for use by the routine.
- 13
- Save area address.
- 14
- Return address.
- 15
- Address of STAE recovery routine.
If no SDWA was available:
- GPR
- Contents
- 0
- 12 (X'0C') to indicate that no SDWA was obtained.
- 1
- Completion code.
- 2
- Address of user-supplied parameter list.
- 3-13
- Do not contain any information for use by the routine.
- 14
- Return address.
- 15
- Address of STAE recovery routine.
When the STAE or STAI routine has completed, it should return to
the system through the contents of GPR 14. GPR 15 should contain one
of the following return codes:
- Return Code
- Action
- 0
- Continue the termination. The next STAI, ESTAI, or ESTAE routine
will be given control. No other STAE routines will receive control.
- 4,8,12
- A retry routine is to be scheduled.
Note: These values
are not valid for STAI/ESTAI routines that receive control when a
resource manager fails during
normal termination
of a task. See
Restricted environments for more information.
- 16
- No further STAI/ESTAI processing is to occur. This code may
be issued only by a STAI/ESTAI routine
For the following situations, STAE/STAI routines are not entered:
- If the abnormal termination is caused by an operator's CANCEL
command, job step timer expiration, or the detaching of an incomplete
task without the STAE=YES option.
- If the failing task has been in a wait state for more than 30
minutes.
- If the STAE macro was issued by a subtask and the attaching task
abnormally terminates.
- If the recovery routine was specified for a subtask, through the
STAI parameter of the ATTACH macro, and the attaching task abnormally
terminates.
- If a problem other than those above arises while the system is
preparing to give control to the STAE routine.
- If another task in the job step terminates without the step option.
STAE and STAI retry routines: If the STAE retry routine is scheduled, the system automatically
deactivates the active STAE routine; the preceding STAE routine, if
one exists, then becomes activated. Users wanting to maintain STAE
protection during retry must reactivate a STAE routine within the
retry routine, or must issue multiple STAE requests prior to the time
that the retry routine gains control.
Like the STAE/STAI recovery routine, the STAE/STAI retry routine
must be in storage when the recovery routine determines that retry
is to be attempted. If not already resident in your program, the
retry routine may be brought into storage through the LOAD macro by
either the mainline routine or the recovery routine.
If the STAE/STAI routine indicates that a retry routine has been
provided (return code = 4, 8, or 12), register 0 must contain the
address of the retry routine. The STAE routine that requested retry
is deactivated and the request block queue is purged up to, but not
including, the RB of the program that issued the STAE macro. In addition,
open DCBs that can be associated with the purged RBs are closed and
queued I/O requests associated with the DCBs being closed are purged.
The RB purge is an attempt to cancel the effects of partially run
programs that are at a lower level in the program hierarchy than the
program under which the retry occurs. However, certain effects on
the system are not canceled by this RB purge. Generally, these effects
are TCB-related and are not identifiable at the RB level. Examples
of these effects are as follows:
- Subtasks created by a program to be purged. Subtasks cannot be
associated with an RB; the structure is defined through TCBs.
- Resources allocated by the ENQ macro. ENQ resources are associated
with the TCB and are not identifiable at the RB level.
- DCBs that exist in dynamically acquired virtual storage. Only
DCBs in the program, as defined by the RB through the CDE itself,
are closed.
If there are quiesced restorable input/output operations (as specified
by PURGE=QUIESCE on the macro invocation), the retry routine can restore
them in the same manner as the retry routine from an ESTAE routine.
See Outstanding I/Os at the time of failure.
If an SDWA was obtained upon entry to the STAE/STAI retry routine,
the contents of the GPRs are as follows:
- GPR
- Contents
- 0
- 0
- 1
- Address of the first 104 bytes of the SDWA.
- 2-14
- Do not contain any information for use by the routine.
- 15
- Address of the STAE/STAI retry routine.
When the storage is no longer needed, the retry routine should
use the FREEMAIN macro to free the first 104 bytes of the SDWA. If
the retry routine is in the user key, this storage should be freed
from subpool 0 which is the default subpool for the FREEMAIN macro.
If the retry routine is in the system key, storage must be freed
from subpool 250.
If the system was not able to obtain storage for the work area,
GPR contents are as follows:
- GPR
- Contents
- 0
- 12 (X'0C')
- 1
- Completion code.
- 2
- Address of purged I/O restore list or 0 if I/O is not restorable.
- 3-14
- Do not contain any information for use by the routine.
- 15
- Address of the STAE/STAI retry routine.
The retry routine is entered in supervisor state if the RBOPSW
of the retry RB is in supervisor state and the task was authorized
at the time the STAE routine was activated or at the time of the error.
Otherwise, the retry routine is entered in problem state.
The task is considered to be authorized at the time the STAE routine
is activated when at least one of the following is true:
- The task is APF-authorized.
- The requestor is in supervisor state.
- The requestor has a PSW key less than 8.
- The task has a protect key less than 8.
- The PKM of the requestor allows keys less than 8.
The mainline routine is considered to be authorized at the time
of the error when at least one of the following is true:
- The task is APF-authorized.
- The task in error has a protect key less than 8.
- All RBs for the task in error run in supervisor state.
The retry routine is entered with the same PSW key as the one in
RBOPSW of the retry RB when one of the following is true:
- The task was authorized at the time of the error as described
above.
- The RBOPSW of the retry RB has a key greater than or equal to
8 and is in problem state, and the PKM of that RB does not have authority
to keys less than 8.
Otherwise, the PSW key of the retry routine is that of the task
in error.