What the retry routine does

Once the retry routine gets control, it continues with mainline processing, and can free resources, deactivate recovery routines, and so on. As stated earlier, the retry routine is really an extension of the mainline routine, and its purpose is to re-establish the mainline environment.

When the retry routine gets control, the following are true:

The retry routine runs under the same unit of work that activated the recovery routine. See Special considerations for ESTAE-type recovery routines for further details related to ESTAE-type recovery routines.

The retry routine might or might not have access to the SDWA, and the recovery routine might or might not have directed that register contents be restored for the retry routine.

For ESTAE-type recovery routines that specify FRESDWA=YES on SETRP, and for all FRRs, the system frees the SDWA before entering the retry routine.

For ESTAE-type recovery routines that specify RETREGS=YES, and for all FRRs, the system restores the registers from the SDWA.

For ESTAE-type recovery routines that specify FRESDWA=NO on SETRP, the system does not free the SDWA, and the retry routine can access it. In that case, the retry routine also has the responsibility of freeing the storage for the SDWA when it is no longer needed. The subpool number and length to use to free the storage are in the SDWA, in fields SDWASPID and SDWALNTH, respectively.

Note: IBM® recommends that the recovery routine use FRESDWA=YES on the SETRP macro, thus alleviating the retry routine's responsibility to free the SDWA. If your recovery routine retries multiple times and the SDWA is not freed, out-of-storage failures can result.

When the retry routine is to free the SDWA, note that an ESTAE-type recovery routine activated under PSW key 0 - 7 receives an SDWA in key 0 storage. If the retry routine is running under a key other than key 0, it must do one of the following:

Issue the MODESET macro to switch into PSW key 0 before freeing the SDWA.
Free the SDWA using the STORAGE macro with the KEY parameter to specify a storage key of 0.

The retry routine can determine what action the recovery routine took in regard to freeing the SDWA and restoring registers by examining the contents of GPR 0:

Table 1. Contents of GPR 0 on Entry to a Retry Routine
GPR 0 Contents	Meaning
0	The system provided an SDWA. The recovery routine specified RETREGS=NO and FRESDWA=NO. Registers are not restored from the SDWA, and the retry routine must free the SDWA. GPR 1 contains the address of the SDWA.
12 (X'0C')	The system did not provide an SDWA.
20 (X'14')	The system provided an SDWA. The recovery routine specified RETREGS=NO and FRESDWA=YES. Registers are not restored from the SDWA, and the retry routine does not have to free the SDWA.
Value restored from SDWA (field SDWASR00)	The system provided an SDWA. The recovery routine specified RETREGS=YES, and either FRESDWA=NO or FRESDWA=YES. If the recovery routine specifies FRESDWA=NO, the recovery routine must alert the retry routine to free the SDWA. Some sort of protocol must be established between the recovery routine and the retry routine. For example, the recovery routine can set a unique value in SDWASR00 (the field that represents GPR 0 in SDWASRSV) to distinguish this case from those above where GPR 0 contains either 0, 12, or 20. The recovery routine can pass the address of the SDWA to the retry routine in a parameter area (use the parameter area pointed to by SDWAPARM) or in a register (consider using register 0).

For complete details about register contents see Understanding the recovery environment.

The recovery routine that requested the retry is still activated and can be entered again, so be aware of the possibility of looping back to the same recovery routine. That recovery routine remains activated and can be entered again unless the recovery routine issued SETRP with REMREC=YES. If the recovery routine specified REMREC=YES, the system deactivated that recovery routine before giving control to the retry routine.
Any previous recovery routines (those that percolated to the recovery routine that requested the retry) are deactivated.

Note:

You can have as many retry points in your program as needed, and you can change the designated retry point as your mainline processing continues.
The retry routine can be a separate routine. The only requirement is that it must be in virtual storage. You are responsible for ensuring that the retry routine is in virtual storage when needed.