Choosing the appropriate recovery routine

The recovery routines you can provide are called ESTAE-type recovery routines. This information describes the different types of ESTAE-type recovery routines, and for each type, describes how you define it, activate it, deactivate it, and request that it no longer be defined. A summary of this information is in Table 1.

When you provide one or more recovery routines for your program, you have the opportunity to identify a user parameter area for the system to pass from the mainline routine to the recovery routine. Creating such a parameter area with information for the recovery routine is a very important part of providing recovery. See Setting up, passing, and accessing the parameter area for more information about what this parameter area should contain, and how to pass it.

Define ESTAE-type recovery routines in the following ways:

STAE, ESTAE, and ESTAEX macros
ATTACH and ATTACHX macros with STAI and ESTAI parameters
IEAARR macro

The following describes the recovery routines you can define with each of the above macros:

STAE, ESTAE, and ESTAEX macros
To provide recovery to protect itself and any other programs running under the same task, a program can issue either the STAE, ESTAE, or ESTAEX macro with the CT parameter. Each of these macros both defines and activates the recovery routine. The recovery routine is defined and activated until one of the following events occurs:
- You deactivate it and request that it be no longer defined (issue STAE 0, ESTAE 0, or ESTAEX 0).
- The recovery routine fails to or chooses not to retry (explained under Understanding recovery routine options).
- The request block (RB) under which the caller of the macro is running terminates.
A program cannot protect other tasks with recovery routines defined through these macros.

IBM® recommends you always use ESTAEX unless your program and your recovery routine are in 24-bit addressing mode, in which case, you should use ESTAE. ESTAE and ESTAEX provide the same function, except that ESTAEX can be issued in AR ASC mode.

The remainder of this chapter refers to the recovery routines you define and activate through the ESTAE and ESTAEX macros as ESTAE routines or ESTAEX routines, respectively.
ATTACH and ATTACHX macros with STAI and ESTAI parameters
To attach a task and provide recovery to protect the attached task and all of its subtasks, a program can issue either the ATTACH or the ATTACHX macro with either the STAI or the ESTAI parameter. You define the recovery routine when you issue the macro. The recovery routine is not activated until the attached task gets control. The recovery routine remains activated as long as the attached task is still running, or until the recovery routine fails to or chooses not to retry. The system deactivates the recovery routine when the attached task ends. At that point, the recovery routine is no longer defined.

The program attaching the task is not protected by the recovery defined in this manner. Only the attached task and its subtasks are protected.

IBM recommends you always use the ESTAI, rather than the STAI, parameter on ATTACHX, rather than ATTACH. ATTACH and ATTACHX provide the same function, except that ATTACHX can be issued in AR ASC mode.

The remainder of this chapter refers to the recovery routines you define through ATTACHX with ESTAI as ESTAI routines. All references to the ATTACHX macro apply also to the ATTACH macro.
IEAARR macro
Use the IEAARR macro to define and activate an associated recovery routine (ARR) to protect the currently running program and any programs it calls running under the same task. ARRs provide recovery for stacking PC routines.

IEAARR is a higher performance alternative to ESTAEX. When IEAARR is issued, a system-defined stacking non-space switching PC is used to give control to a target program (such as your program's mainline). That program and any programs that it calls are protected by the recovery routine that you specify on the IEAARR macro. The recovery routine is deactivated and undefined when the target program returns and the system issues a PR instruction to return to the issuer of IEAARR. The recovery routine is also deactivated and undefined if it fails to or chooses not to retry, or if the RB that your program is running under is terminated.
Note: Authorized programs can also establish ARRs for stacking PC routines that they define via the ETDEF macro.

In summary, ESTAE-type recovery routines include ESTAE and ESTAEX routines, ESTAI routines and ARRs.