|
Description
The SETFRR macro gives authorized programs the ability to define
their recovery in the FRR (functional recovery routine) LIFO stack,
which is used during processing of the system recovery manager. Any
program function can use SETFRR to define its own unique recovery
environment.
The SETFRR macro can be used to add, delete, or replace FRRs in
the LIFO stack, or to purge all FRRs in the stack. The macro also
optionally returns to the user the address of a parameter area that
is eventually passed to the FRR when an error occurs. The parameter
area can be used to keep information that might be useful to the FRR.
The recovery and retry routines execute in the same addressing mode
as the issuer of the macro.
z/OS MVS Programming: Authorized Assembler Services Guide describes
the interface to an FRR and contains guidelines for writing an FRR.
Environment
The requirements for the caller are:
Environmental factor |
Requirement |
---|
Minimum authorization: |
Supervisor state and PSW key 0 |
Dispatchable unit mode: |
Task or SRB (see note below) |
Cross memory mode: |
Any PASN, any HASN, any SASN |
AMODE: |
24- , 31-bit, or 64-bit |
ASC mode: |
Primary, secondary or access register (AR) |
Interrupt status: |
Enabled or disabled for I/O and external interrupts
(see note below) |
Locks: |
The caller may hold locks, but is not required
to hold any. (See note below.) |
Control parameters: |
None. |
Note: If the caller does not specify the EUT=YES parameter, the caller
must be one of the following: - Holding a lock
- Disabled for I/O and external interrupts
- In SRB mode.
Programming requirements
If your program is in AR mode, issue the SYSSTATE ASCENV=AR macro
before issuing SETFRR. SYSSTATE ASCENV=AR tells the system to generate
code appropriate for AR mode.
For primary mode callers, the parameter list you specify on the
PARMAD parameter must be in the primary address space. For AR mode
callers, this parameter list can be located in any address space.
The caller must include the following mapping macros:
Input register information
Before issuing the SETFRR macro, the caller does not have to place
any information into any register unless using it in register notation
for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the contents of the general
purpose registers (GPRs) and access registers (ARs) are unchanged,
with the exception of the GPRs you specify on the WRKREGS parameter,
which are used by the system.
Syntax
The SETFRR macro is written as follows:
Syntax |
Description |
---|
|
|
name |
name: Symbol. Begin name in
column 1. |
|
|
␢ |
One or more blanks must precede SETFRR. |
|
|
SETFRR |
|
|
|
␢ |
One or more blanks must follow SETFRR. |
|
|
A,FRRAD=FRR addr |
FRR addr: A-type address, or
register (2) - (12). |
R,FRRAD=FRR addr |
|
D |
|
P |
|
|
|
,WRKREGS=(reg1,reg2) |
reg1: Decimal digits 1-15. |
|
reg2: Decimal digits 1-15. |
|
|
,PARMAD=parm area addr |
parm area addr: A-type address,
or register (2) - (12). |
|
Note: This parameter may only be specified
with A or R above. |
|
|
,CANCEL=YES |
Default: CANCEL=YES |
,CANCEL=NO |
|
|
|
,EUT=YES |
|
|
|
,MODE= |
Default: MODE=HOME |
( |
|
FULLXM |
|
PRIMARY |
|
HOME |
|
, |
|
LOCAL |
|
) |
|
|
|
,RELATED=value |
value: Any valid macro keyword
specification. |
|
|
,SDWALOC31=NO |
Default: SDWALOC31=NO |
,SDWALOC31=YES |
|
|
|
Parameters
The parameters are explained as follows:
- A,FRRAD=FRRAD addr
- R,FRRAD=FRRAD addr
- D
- P
- Specifies the operation to be performed on the FRR LIFO stack:
- A
- An FRR address is to be added to the stack.
- R
- The FRR address last added to the stack is to be replaced by another
FRR address.
- D
- The FRR address last added to the stack is to be deleted.
- P
- All entries in the stack are to be purged.
FRRAD specifies the address of a fullword containing
the FRR address that is to be added or replaced. The parameter specifies
the FRR address in a register or specifies the address of a storage
location containing the FRR address.
- ,WRKREGS=(reg1,reg2)
- Specifies two unique general purpose registers to be used as work
registers by the system.
- ,PARMAD=parm area addr
- Specifies the address of a fullword to receive the address of
the 24-byte parameter area initialized to zeros and provided by the
system to the issuer of SETFRR. This 24-byte parameter area is in
key 0 storage. If a register is specified, the address of the 24-byte
parameter area is placed in the register. This parameter area is associated
with the FRR address that has either been added to or has replaced
an FRR address on the stack. This parameter area is passed to the
FRR when an error occurs.
- ,CANCEL=YES
- ,CANCEL=NO
- Specifies whether you want to allow the recovery routine to be
interrupted by cancel or detach processing.
To allow a recovery
routine to be interrupted, specify CANCEL=YES.
To prevent a
recovery routine from being interrupted, specify CANCEL=NO. If a
cancel or detach is attempted against a recovery routine for which
you have specified CANCEL=NO, MVS™ defers cancel and detach processing
until the recovery routine returns control to the system. Note: - If a recovery routine that runs under the CANCEL=NO option can
be called by an unauthorized program running under the same task, IBM recommends
that you specify ASYNCH=NO for each ESTAE(X) macro that the recovery
routine issues. This also includes any ESTAE(X) macros issued by programs
that the recovery routine calls.
- If a recovery routine running under the CANCEL=NO option calls
an unauthorized program, cancel and detach processing is also deferred
for the called program.
- ,EUT=YES
- Used only with A and R, specifies that the new FRR can be used
in any environment. EUT=YES is used by routines that are not certain
of their environment; for example, a routine that can be called by
an SRB or by a task that is executing enabled and might not hold any
locks. While the FRR remains in effect, no SVCs can be issued, no
new asynchronous exits are dispatched, and no vector instructions
can be executed.
- ,MODE=options
- Specifies the environment in which the FRR is to get control and
also, optionally, identifies the FRRs that free critical resources.
The normal or expected addressing environment is identified by FULLXM,
PRIMARY, or HOME. Specify LOCAL to enable the FRR to be entered in
a restricted addressing environment for freeing critical resources.
Parentheses are not needed if only one option is chosen.
- FULLXM
- Specifies that the FRR must be entered in the same cross memory
environment that existed when the SETFRR was issued.
- PRIMARY
- Specifies that the FRR must be entered in primary addressing mode
with both the PASID and SASID the same as the PASID that existed when
the SETFRR was issued, the home address space must be unchanged, and
the PSW key mask must be the same as when the SETFRR was issued.
- HOME
- Specifies that the FRR must be entered in primary addressing mode
with PASID=SASID=HASID, and the PSW key mask either the same as that
at the time of the error for SRB mode, or the task storage protect
key for TCB mode.
If neither FULLXM, PRIMARY, nor HOME is coded,
HOME is the default.
- LOCAL
- Specifies that the FRR frees a critical local resource. If the
FRR cannot be entered in its normal addressing environment then it
must be entered in LOCAL restricted addressing environment to free
resources.
For the FRR to be entered in LOCAL restricted addressing
environment, a local lock must be held.
If it cannot be entered
either as an FRR or as a resource manager, the FRR is skipped.
- ,RELATED=value
- Specifies information used to self-document macros by “relating”
functions or services to corresponding functions or services. The
format and contents of the information specified are at the discretion
of the user, and may be any valid coding values.
- ,SDWALOC31=NO
- ,SDWALOC31=YES
- Used only with A and R, SDWALOC31=YES specifies that an AMODE
31 FRR can tolerate an SDWA in 31-bit storage. The default of SDWALOC31=NO
specifies that an AMODE 31 FRR is not known to be able to tolerate
an SDWA in 31-bit storage and an SDWA in 24-bit storage will be provided.
Because 31-bit storage is generally less likely to be constrained
than 24-bit storage and RTM skips FRRs for which it can not obtain
an SDWA, SDWALOC31=YES should be used whenever possible for AMODE
31 FRRs.
This parameter is ignored for FRRs established in AMODE
64 because they are assumed to be able to tolerate an SDWA in 31-bit
storage. It is also ignored for FRRs established in AMODE 24.
Note: Programs
generated with this parameter can be used on systems before HBB7770,
where the parameter will be ignored.
ABEND codes
SETFRR might abnormally end with abend code X'07D'. See z/OS MVS System Codes for
an explanation and programmer response for this code.
Example 1
Add an FRR to the FRR stack and return the address of the parameter
list to the issuer of the SETFRR. The FRR address contained in register
(R5) is placed on the FRR stack in the next available FRR entry. On
return, register (R2) contains the address of the parameter list associated
with this FRR entry. Registers R3 and R4 are work registers used by
the system. SETFRR A,FRRAD=(R5),PARMAD=(R2),WRKREGS=(R3,R4)
Example 2
Delete the last FRR added to the FRR stack. Registers 1 and 6
are work registers used by the system. SETFRR D,WRKREGS=(1,6)
|