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.