The requirements for the caller are:

• You can use SETRP only if the system provided an SDWA.
• Recovery routines established through the STAE macro, or the STAI parameter on the ATTACH or ATTACHX macro, cannot update registers on retry, so the RETREGS parameter does not apply.
• For FRRs, RETREGS=YES (or RETREGS=NO) has no effect. For FRRs, the system always restores GPRs 0-14 from the SDWASRSV field, and ARs 0-14 from the SDWAARSV field. If you specify RETRY15=YES, the system also restores GPR 15 and AR 15 from the SDWASRSV and SDWAARSV fields, respectively.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

None.

The SETRP macro is written as follows:

The parameters are explained below:

WKAREA=(reg)

Specifies the address of the SDWA passed to the recovery routine. If this parameter is omitted, the address of the SDWA must be in register 1.

,REGS=(reg 1)

,REGS=(reg 2)

Specifies the register or range of registers to be restored from the 72-byte standard save area pointed to by the address in register 13. If you specify REGS, a branch on register 14 instruction will also be generated to return control to the system. If you do not specify REGS, you must code your own branch on whichever register contains the return address.

Note: If you specify reg1,reg2, specify the registers in the same order as in an STM instruction; for example, to restore all registers except register 13, specify REGS=(14,12).

,DUMP=IGNORE

,DUMP=YES

,DUMP=NO

Specifies that the dump option fields will not be changed (IGNORE), will be zeroed (NO), or will be merged with dump options specified in previous dump requests, if any (YES). If IGNORE is specified, a previous recovery routine had requested a dump or a dump had been requested through the ABEND macro, and the previous request will remain intact. If NO is specified, no dump will be taken.

DUMP=YES does not guarantee that a SYSABEND/SYSUDUMP will be taken. You may specify this request in an FRR for an SRB but you will get an abdump only if the SRB abend successfully percolates to a task and none of the FRRs for that task choose to retry and the final value of the DUMP= remains the same after every recovery routine has received control.

,DUMPOPT=parm list addr

,DUMPOPX=parm list addr

Specifies the address of a parameter list of dump options. You can create the parameter list through the list form of the SNAP or SNAPX macro, or you can create a compatible list. DUMPOPT specifies the address of a parameter list that the SNAP macro creates. DUMPOPX specifies the address of a parameter list that the SNAPX macro creates. A program in secondary mode cannot use the DUMPOPX parameter.

If the specified dump options include subpools for storage areas to be dumped, up to seven subpools can be dumped. Subpool areas are accumulated and wrapped, so that the eighth subpool area specified replaces the first.

If the dump options specified include ranges of storage areas to be dumped, only the storage areas in the first thirty ranges will be dumped.

The TCB, DCB, ID, and STRHDR options available on SNAP or SNAPX are ignored if they appear in the parameter list. The TCB used will be the one for the task that encountered the error. The DCB used will be one created by the system, and either SYSABEND, SYSMDUMP, or SYSUDUMP will be used as a DDNAME.

,REASON=code

Specifies the reason code that the user wishes to pass to subsequent recovery routines. The value range for code is any 32-bit hexadecimal number or 31-bit decimal number. See z/OS MVS Programming: Assembler Services Reference ABE-HSP for information about how a user can change this code.

,RC=0

,RC=4

,RC=16

Specifies the return code the recovery routine sends to the system to indicate what further action is required:

Decimal Code

Meaning

0

Continue with error processing; causes entry into previously-specified recovery routine, if any.

4

Retry using the retry address specified.

16

Valid only for an ESTAI/STAI recovery routine. The system should not give control to any further ESTAI/STAI routines, and should abnormally end the task.

,RETADDR=retry addr

Specifies the address of the retry routine to which control is to be given.

,RETREGS=NO

,RETREGS=YES

,RETREGS=YES ,RUB=reg info addr

,RETREGS=64

Specifies the contents of the registers to be restored on entry to the retry routine. RETREGS=NO indicates that you do not want the system to restore any register contents from the SDWA.

If you specify RETREGS=YES, in a recovery routine defined through the ESTAE, ESTAEX, or FESTAE macro, the ESTAI parameter on the ATTACH or ATTACHX macro, or an associated recovery routine (ARR), the system does the following:

• Initializes GPRs 0-15 from the SDWASRSV field of the SDWA
• Initializes ARs 0-15 from the SDWAARSV field of the SDWA.

Specifying RETREGS=64 is the same as specifying RETREGS=YES, except the registers for retry are the 64-bit general purpose registers in field SDWAG64.

RUB (register update block) specifies the address of an area that contains register update information for the GPRs. The data you specify in this area will be moved into the SDWASRSV field of the SDWA and will be loaded into the GPRs on entry to the retry routine. You cannot use the RUB to specify data to be moved into the SDWAARSV field for loading the ARs. You can use the RUB for both ESTAE-type recovery routines and FRRs. The maximum length of the RUB is 66 bytes. You must acquire storage for and initialize this area as follows:

• The first two bytes represent the registers to be updated, register 0 corresponding to bit 0, register 1 corresponding to bit 1, and so on. The user indicates which of the registers are to be stored in the SDWA by setting the corresponding bits in these two bytes.
• The remaining 64 bytes contain the update information for the registers, in the order 0-15. If all 16 registers are being updated, this field consists of 64 bytes. If only one register is being updated, this field consists of only 4 bytes for that one register.

For example, if only registers 4, 6, and 9 are being updated:

• Bits 4, 6, and 9 of the first two bytes are set.
• The remaining field consists of 12 bytes for registers 4, 6, and 9; the first 4 bytes are for register 4, followed by 4 bytes for register 6, and 4 final bytes for register 9.

,FRESDWA=NO

,FRESDWA=YES

Specifies that the entire SDWA be freed (YES) or not be freed (NO) before entry into the retry routine.

,COMPCOD=code1

,COMPCOD=(code)

,COMPCOD=(code,USER)

,COMPCOD=(code,SYSTEM)

Specifies the user or system completion code that the user wants to pass to subsequent recovery routines.

,FRELOCK=(locks)

Specifies the locks to be freed and the corresponding lockwords that are placed in the SDWA:

CPU

Processor lock

CMS

Cross memory services lock

LOCAL

Storage lock of the storage the caller is executing in

CML(cmlascb)

Cross memory local lock, where cmlascb indicates the ASCB address of the address space for which the local lock is to be freed

Note: If FRLKRTY=NO is specified or taken as a default, the specified locks are freed only on percolation, not on retry. Specifying FRLKRTY=YES allows the locks listed in FRELOCK to be freed on retry.

,RECORD=IGNORE

,RECORD=YES

,RECORD=NO

Specifies whether the SDWA is to be recorded in SYS1.LOGREC (RECORD=YES/NO), or whether the system should honor previous instructions about recording the SDWA in SYS1.LOGREC (RECORD=IGNORE).

If you specify RECORD=YES, the system records the entire SDWA (including the fixed length base, the variable length recording area, and the recordable extensions) in SYS1.LOGREC when the ESTAE recovery routine returns control, even if the mainline program issued the ESTAE or ESTAEX macro with RECORD=NO.

If you specify RECORD=NO, the system does not record the SDWA in SYS1.LOGREC, even if the mainline program issued ESTAE or ESTAEX with RECORD=YES.

If you specify RECORD=IGNORE, the system honors the request as specified by the RECORD parameter on the ESTAE or ESTAEX macro.

,RECPARM=record list addr

Specifies the address of a user-supplied record parameter list used to update the SDWA with recording information. The parameter list consists of three 8-byte fields:

• The first field contains the load module name.
• The second field contains the CSECT name (assembly module name).
• The third field contains the recovery routine name (assembly module name). If the recovery routine label is not the same as the assembly module name, the label can be used.

The three fields are left-justified, and padded with blanks.

,SERIAL=YES

,SERIAL=NO

Specifies whether the percolation from an SRB mode FRR to a related task recovery routine (ESTAE or FRR) is to be serialized (YES) or not serialized (NO) with respect to unlocked task recovery. See 'SRB to Task Percolation' in z/OS MVS Programming: Authorized Assembler Services Guide.

If the task is already in recovery for another error when SERIAL=YES is specified, the percolation request is deferred pending a requested task retry from any recovery routine covering mainline code. If such a retry is not requested, the task is terminated and all deferred percolations are purged. Only the last FRR to receive control when an error occurs can specify SERIAL=YES.

,RETRY=FRR

,RETRY=ERROR

Specifies the cross memory environment in which the retry routine gets control.

RETRY=FRR, the default, specifies that the retry routine gets control in the cross memory environment that exists at the time of entry to the FRR.

RETRY=ERROR specifies that the retry routine gets control in the cross memory environment that existed at the time of the error. Do not specify RETRY=ERROR if the cross memory status at the time of the error is not available, that is, if SDWARPIV is set to one. (Be careful not to create a loop by retrying to an erroneous cross memory state with RETRY=ERROR.)

,RETRY15=YES

,RETRY15=NO

In an FRR environment only, specifies that GPR 15 is restored from SDWASRSV and AR 15 is restored from SDWAARSV if RETRY15=YES. Otherwise, it contains the entry point address of the retry routine.

This parameter may be specified only when RC=4 is specified. If RETRY15=YES is not coded on any SETRP invocation prior to returning to the system, the effect is that of specifying RETRY15=NO.

,REMREC=YES

,REMREC=NO

In an FRR or ESTAE environment, specifies that the FRR/ESTAE entry for the currently running FRR/ESTAE routine be removed (REMREC=YES) or not removed (REMREC=NO). This parameter may be specified only when RC=4 is specified, indicating a retry request.

The entry is removed before control returns to the retry point. If REMREC=YES is not coded on any SETRP invocation before the system receives control, the effect is that of specifying REMREC=NO. The REMREC parameter may be used to remove a recovery routine that has been defined with a token, although the token cannot be specified when you code the SETRP macro.

,FRLKRTY=YES

,FRLKRTY=NO

In an FRR environment only, specifies that the locks specified on FRELOCK be freed (FRLKRTY=YES) or not be freed (FRLKRTY=NO) on retry.

This parameter may be specified only when RC=4 is specified. If FRLKRTY=YES is not coded on any SETRP invocation prior to returning to the system, the effect is that of specifying FRLKRTY=NO.

SSRESET=YES

SSRESET=NO

SSRESET=YES specifies that, if the current recovery routine abnormally ends, the next recovery routine is to get control in the subspace environment that existed when the current recovery routine was entered. Specify SSRESET=YES when the current recovery routine has temporarily modified the subspace environment, and when it is appropriate for the next recovery routine to receive control in the subspace environment in which the current recovery routine received control.

SSRESET=NO negates an earlier specification of SSRESET=YES. Specify SSRESET=NO when SSRESET=YES protection is no longer needed. If the current recovery routine abnormally ends after specifying SSRESET=NO, the next recovery routine will get control in the subspace in which the current routine was running when the error occurred.

If you do not specify SSRESET and the current recovery routine abnormally ends, the next recovery routine will get control in the subspace in which the current recovery routine was running when the error occurred.

See the chapter on subspaces in z/OS MVS Programming: Extended Addressability Guide for more information about subspaces and recovery.

,RETRYAMODE=amode

Specifies an explicit AMODE in which a retry routine receives control. This parameter is only honored for ARR, ESTAE, ESTAI, ESTAEX, FESTAE, FRR and IEAARR recovery routines. If you do not specify this parameter, RTM selects an AMODE described in "providing recovery" in z/OS MVS Programming: Authorized Assembler Services Guide.

The following table indicates which parameters are available to functional recovery routines (FRRs) and which parameters are available to ESTAE-type recovery routines.

None.

None.