RB considerations

A program must activate and deactivate ESTAE-type recovery routines under the same RB level. If you try to deactivate an ESTAE-type recovery routine that is not associated with your RB, you get a return code that indicates your request is not valid.

ESTAE-type recovery routines are deactivated when their associated RBs terminate. This is important because a program expects one of its own ESTAE-type recovery routines to get control rather than one left behind by a called program. A program might, however, invoke a service routine that does not create an RB. If that routine then issues an ESTAEX or ESTAE macro and fails to deactivate the resulting ESTAE-type recovery routine, a problem could develop if the original program encounters an error. The ESTAE-type recovery routine left behind by the service routine would receive control rather than the ESTAE-type recovery routine associated with the program, because the recovery routine specified by the most recently issued ESTAE or ESTAEX macro gets control.

IBM® recommends that every program that activates an ESTAE-type recovery routine also deactivate it.

The TOKEN parameter on the ESTAEX or ESTAE macro can help you if your program is running in an environment where a called program is unable to deactivate its own ESTAE-type recovery routine. The TOKEN parameter associates a token with the ESTAE-type recovery routine you are activating. To deactivate (ESTAE or ESTAEX with the 0 parameter) or overlay (ESTAE or ESTAEX with the OV parameter) the recovery routine that was activated with TOKEN, the same token must be specified. All of the more recently activated ESTAE or ESTAEX recovery routines are deactivated at the same time. Using the TOKEN parameter can help in these ways:

When you attempt to deactivate your ESTAE-type recovery routine, you are sure of deactivating the correct one.
You deactivate all of the more recently activated ESTAE-type recovery routines, so your program's caller does not have the problem of leftover recovery routines when your program returns control.
You could activate a dummy ESTAE-type recovery routine with the TOKEN parameter and then deactivate it. The sole purpose of the dummy routine would be to ensure that all leftover ESTAE-type recovery routines are deactivated. Then if your program encounters an error, you are assured that your own ESTAE-type recovery routine gets control.

If a program issues an ESTAE or ESTAEX macro that specifies both the TOKEN parameter and XCTL=YES and then issues the XCTL or XCTLX macro, the token must be passed as part of the parameters to the called routine so that the routine can deactivate the ESTAEX or ESTAE routine.

For retry from an ESTAE-type recovery routine, the retry routine runs as a continuation of the code that activated the recovery routine. That is, the retry routine runs under the same RB that defined the ESTAE-type recovery routine, and the system purges all RBs created after the retry RB before giving control to the retry routine.

Note that ESTAI is an exception; a retry request from a recovery routine defined by the ESTAI parameter of the ATTACHX macro must run under a program request block (PRB). The retry routine cannot run under the PRB of the routine that defined the ESTAI routine, because that PRB is associated with a different task. The system scans the RB queue associated with the task under which the retry is to occur, starting with the RB that was interrupted (the newest RB). The system then uses the following rules to select a PRB for the retry routine:

If one or more PRBs exist that represent an ESTAE-type recovery routine, use the newest one.
If no PRBs exist that represent ESTAE-type recovery routines, use the newest PRB that does not have any non-PRBs (such as SVRBs) that are older.

If the RB queue contains no PRBs at all, retry is suppressed.