SETFRR — Set up functional recovery routines

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:

IHAFRRS
IHAPSA

Restrictions

None.

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.

Performance implications

None.

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.

Note: When an FRR wants to deactivate itself, IBM® recommends that the FRR issue SETRP with REMREC=YES rather than issuing SETFRR D. See the chapter on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide for an explanation.

,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.

Return and reason codes

None.

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)