SETRP — Set return parameters

The requirements for the caller are:

• If the program is in AR mode, issue the SYSSTATE ASCENV=AR macro before issuing SETRP. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.
• Include the IHASDWA mapping macro to map the system diagnostic work area (SDWA). (See SDWA in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the mapping provided by IHASDWA.)
• If you plan to specify RETREGS=YES, RUB=reg info addr, you must obtain storage for and initialize the register update block (RUB). See the RETREGS parameter description for more information about this area.

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

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 as follows:

,WKAREA=(reg)

Specifies the address of the SDWA passed to the recovery routine.

,REGS=(reg1)

,REGS=(reg1,reg2)

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 options. To create the parameter list, use the list form of either the SNAP or SNAPX macro, or code data constants in your program. 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 is the one for the task that encountered the error. The DCB used is one created by the system, and either SYSABEND, SYSMDUMP, or SYSUDUMP is used as a DDNAME.

,REASON=code

Specifies the reason code that the user wishes to pass to subsequent recovery routines.

,RC=0

,RC=4

,RC=16

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

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.

,REMREC=YES

,REMREC=NO

In an ESTAE environment, specifies that the ESTAE entry for the currently running 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 established with a token, although the token cannot be specified when you code the SETRP macro.

,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 or ESTAEX 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. 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) prior to entry into the retry routine.

,COMPCOD=comp code

,COMPCOD=(comp code,USER)

,COMPCOD=(comp code,SYSTEM)

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

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

,RETRYAMODE=amode

Specifies an explicit AMODE in which a retry routine receives control. Valid values are 24, 31, and 64. This parameter is only honored for ESTAE, ESTAI, ESTAEX, and IEARR recovery routines. If you do not specify this parameter, RTM selects an AMODE as described in Providing Recovery in z/OS MVS Programming: Assembler Services Guide.

None.

None.