Using STAE/STAI routines

Note:
  1. IBM® recommends you use the ESTAEX or ESTAE macro, or the ESTAI parameter on ATTACHX.
  2. 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.

Parent topic: Providing recovery