Special considerations for FRRs

Consider the following when writing an FRR:

FRR stack: When you define an FRR, the SETFRR macro creates an entry in a system area called an FRR stack. The size of the FRR stack satisfies the recovery needs of the system. If additional FRRs placed on the stack cause the size to be exceeded, the routine issuing the SETFRR macro ends abnormally. User-written routines outside of the system may add up to two FRRs to the FRR stack. All remaining stack entries are reserved for the system. If a routine attempts to add an entry to the stack when the stack is full, the system issues an X'07D' abend.

SDWA: The system always gives control to FRRs with an SDWA. If the system cannot supply an SDWA, the system bypasses the FRR, goes to the next FRR, and again attempts to supply an SDWA. When no FRRs remain, the system gives control to any ESTAE-type recovery routines that are available. When an FRR receives control in AMODE 64 the SDWA may be in 31-bit addressable storage.

AMODE 31 users of SETFRR can specify SDWALOC31=YES to indicate that their FRR can tolerate an SDWA in 31-bit addressable storage. Considering that 31-bit storage is less likely to be constrained than 24-bit storage and RTM skips FRRs for which it can not obtain an SDWA, use SDWALOC31=YES whenever possible for AMODE 31 FRRs.

Locks: When the system invokes an FRR, the FRR runs with the locks (and the enablement implied by those locks) that were held at the time of the error, plus an additional CPU lock obtained for the system if the FRR was holding any CPU locks, unless a previous FRR does one of the following:

Deletes one or more of the locks
Requests the system to delete one or more of the locks using the FRELOCK parameter on the SETRP macro.

The FRR should take the following action regarding locks held when the FRR is entered:

The FRR should issue SETRP with the FRELOCK parameter. This indicates that the system is to free the specified locks if the FRR percolates.
Assuming retry is not prohibited, if the FRR retries, it should request that the system free locks prior to entering the retry routine by specifying the following on SETRP:
- The FRELOCK parameter, specifying the locks to be freed.
- The FRLKRTY=YES parameter.
If the FRR needs to do some processing that cannot be done with the locks that were held at time of entry, keep the following in mind:
- If entered holding one or more CPU locks (that is, the FRR is entered disabled), then the FRR must not release all of the CPU locks (it must remain disabled by retaining at least one CPU lock). Freeing the last CPU lock can cause different units of work to use the same SDWA simultaneously.
- If entered holding the CMS lock, the FRR can release that lock.
- If entered holding the LOCAL lock or a CML lock, the FRR can release that lock if either of the following is true:
  - The FRR is in SRB mode.
  - The FRR is in task mode and is an EUT FRR.

Deactivating an FRR: When an FRR wants to deactivate itself, the FRR should issue SETRP with REMREC=YES. FRRs can also issue SETFRR D, but must exercise caution when doing so. The FRR should not call any other program or service after issuing SETFRR D because of the following:

When the FRR issues SETFRR D, it removes itself from the FRR stack.
If the FRR then calls a program or service that sets another FRR, that FRR goes on the FRR stack.
The system thinks the new FRR is the original FRR.
In the event the called program or service encounters an error, the system does not give control to the new FRR because it appears to be the original FRR.

For example, suppose the FRR issues SETFRR D, and then issues the SDUMPX macro. SDUMPX processing places another FRR on the FRR stack, in the location of the original FRR. If SDUMPX processing encounters an error, the system does not give control to its FRR because the system thinks it is the original FRR, to which control was already given.

Thus, IBM® recommends that you issue SETRP with REMREC=YES rather than issuing SETFRR D within an FRR. If the FRR specifies SETRP REMREC=YES, the system deactivates the FRR after the FRR gives up control, thus removing the entry from the FRR stack at a safe time.