IEAARR — Establish an associated recovery routine (ARR)

Description

IEAARR allows you to request that the system establish an associated recovery routine (ARR) while calling a target routine. In this case, the system performs the stacking PC instruction, then give control to your routine (the target routine). When the target routine returns control, the system issues the corresponding PR instruction.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and PSW key 8-15
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	31-bit or 64-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller is not required to hold any locks on entry. The caller may hold the local, CMS, or CPU lock.
Control parameters:	None.

Programming requirements

The caller must include the IHAECVT mapping macro.

Restrictions

IEAARR must not be issued while a functional recovery routine (FRR) is established.

TARGETSTATE=PROB should only be issued by a caller currently running in problem state. TARGETSTATE=SUP should only be issued by a caller currently running in supervisor state.

Input register information

Before issuing the IEAARR macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) 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 GPRs contain:

Register: Contents
0: The value placed in register 0 by the target routine prior to its returning to the system.
1: The value placed in register 1 by the target routine prior to its returning to the system.
2-13: Unchanged
14: Used as a work register by the system
15: The value placed in register 15 by the target routine prior to its returning to the system.

When control returns to the caller, the ARs contain:

Register: Contents
0: The value placed in access register 0 by the target routine prior to its returning to the system.
1: The value placed in access register 1 by the target routine prior to its returning to the system.
2-13: Unchanged
14: Used as a work register by the system
15: The value placed in access register 15 by the target routine prior to its returning to the system.

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.

Performance implications

None.

Syntax

The IEAARR macro is written as follows:

Syntax	Description

`name`	`name:` symbol. Begin `name` in column 1.

␢	One or more blanks must precede IEAARR.

IEAARR

␢	One or more blanks must follow IEAARR.

ARRPTR=`arrptr`	`arrptr:` RX-type address or address in register (2) - (12).
ARR=`arr`	`arr:` RX-type address or address in register (2) - (12).

,DYNSTORAGE=AVAIL	Default: DYNSTORAGE=AVAIL
,DYNSTORAGE=NOTAVAIL

,ARRPARAMPTR=`arrparamptr`	`arrparamptr:` RX-type address or address in register (2) - (12).
,ARRPARAMPTR64=`arrparamptr64`	`arrparamptr64:` RX-type address or address in register (2)-(12), of a 64-bit pointer field.
,ARRPARAM=`arrparamp`	`arrparamp:` RX-type address or address in register (2) - (12).
,ARRPARAM64=`arrparam64`	`arrparam64:` RX-type address or address in register (2) - (12).

,PARAMPTR=`paramptr`	`paramptr:` RX-type address or address in register (2) - (12).
,PARAMPTR64=`paramptr64`	`paramptr64:` RX-type address or address in register (2)-(12), of a 64-bit pointer field.
,PARAM=`param`	`param:` RX-type address or address in register (2) - (12).
,PARAM64=`param64`	`param64:` RX-type address or address in register (2) - (12).

,TARGETPTR=`targetptr`	`targetptr:` RX-type address or address in register (2) - (12).
,TARGET=`target`	`target:` RX-type address or address in register (2) - (12).

,TARGETSTATE=PROB
,TARGETSTATE=SUP

Parameters

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the IEAARR macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

DYNSTORAGE=AVAIL

DYNSTORAGE=NOTAVAIL

An optional parameter that indicates whether this routine is sensitive to your having dynamic storage. The default is DYNSTORAGE=AVAIL.

DYNSTORAGE=AVAIL: Indicates that you have dynamic storage available.
DYNSTORAGE=NOTAVAIL: Indicates that you do not have dynamic storage available. The parameters are defined so that you can place each parameter value in a register and in so doing avoid the need to place parameter values into dynamic storage.

ARRPTR=arrptr

When DYNSTORAGE=AVAIL is in effect, a required input parameter that contains the address of the associated recovery routine. This routine gets control from RTM according to normal z/OS recovery protocols. As it is an ARR, it will get control in AMODE 31.

To code: Specify the RX-type address, or address in register (2)-(12), of a pointer field.

ARR=arr

When DYNSTORAGE=NOTAVAIL is specified, a required input parameter that is the associated recovery routine. This routine gets control from RTM according to normal z/OS recovery protocols. As it is an ARR, it will get control in AMODE 31.

To code: Specify the RX-type address, or address in register (2)-(12), of the associated recovery routine.

,ARRPARAMPTR=arrparamptr

When DYNSTORAGE=AVAIL is in effect and SYSSTATE AMODE64=YES is not in effect, a required input parameter that contains the address of the parameter area that is to be passed to the ARR upon error. The address is placed in the first four bytes of the area pointed to by SDWAPARM and in GPR 2. Note that the second four bytes of the area pointed to by SDWAPARM will not contain interface information.

To code: Specify the RX-type address, or address in register (2)-(12), of a pointer field.

,ARRPARAM=arrparam

When DYNSTORAGE=NOTAVAIL is specified and SYSSTATE AMODE64=YES is not in effect, a required input parameter that is the parameter area that is to be passed to the ARR upon error. The address is placed in the first four bytes of the area pointed to by SDWAPARM and in GPR 2. Note that the second four bytes of the area pointed to by SDWAPARM will not contain interface information.

To code: Specify the RX-type address, or address in register (2)-(12), of the parameter area.

,ARRPARAMPTR64=arrparamptr64

When DYNSTORAGE=AVAIL is in effect and SYSSTATE AMODE64=YES is in effect, a required 8-byte input parameter that contains the address of the parameter area that is to be passed to the ARR upon error. The address is placed in the 8-byte area pointed by SDWAPARM and in the 64-bit GPR 2.

To code: Specify the RX-type address, or address in register (2)-(12), of a 64-bit pointer field.

,ARRPARAM64=arrparam64

When DYNSTORAGE=NOTAVAIL is specified and SYSSTATE AMODE64=YES is in effect, a required 8-byte input parameter that is the parameter area that is to be passed to the ARR upon error. The address is placed in the 8-byte area pointed by SDWAPARM and in the 64-bit GPR 2.

To code: Specify the RX-type address, or address in register (2)-(12), of the parameter area.

,PARAMPTR=paramptr

When DYNSTORAGE=AVAIL is in effect and SYSSTATE AMODE64=YES is not in effect, a required input parameter that contains the address of a parameter that is to be passed to the target routine in GPR 1.

To code: Specify the RX-type address, or address in register (2)-(12), of a pointer field.

,PARAM=param

When DYNSTORAGE=NOTAVAIL is specified and SYSSTATE AMODE64=YES is not in effect. a required input parameter that is the parameter that is to be passed to the target routine in GPR 1.

To code: Specify the RX-type address, or address in register (2)-(12), of the parameter.

,PARAMPTR64=paramptr64

When DYNSTORAGE=AVAIL is in effect and SYSSTATE AMODE64=YES is in effect, a required 8-byte input parameter that contains the address of the parameter that is to be passed to the target routine in 64-bit GPR 1.

To code: Specify the RX-type address, or address in register (2)-(12), of a 64-bit pointer field.

,PARAM64=param64

When DYNSTORAGE=NOTAVAIL is specified and SYSSTATE AMODE64=YES is in effect, a required 8-byte input parameter that is to be passed to the target routine in 64-bit GPR 1.

To code: Specify the RX-type address, or address in register (2)-(12), of the parameter.

,TARGETPTR=targetptr

When DYNSTORAGE=AVAIL is in effect, a required input parameter that contains the address of the routine to which the system is to branch after establishing the ARR. The target routine will get control in the same key and state as the IEAARR caller, in AMODE 31, with the following input registers:

General Purpose Registers:

Register: Contents
0: Not part of the intended interface
1: Address of parameter area provided by IEAARR caller
2-13: Unchanged from the IEAARR caller
14: Tne return address
15: The address of the target routine

Access Registers:

Register: Contents
0-1: Not part of the intended interface
2-13: Unchanged from the IEAARR caller
14: Not part of the intended interface
15: Not part of the intended interface

The target routine gets control with one more entry on the linkage stack than existed when IEAARR was called. That linkage stack entry contains the caller's registers 2-13 which can be extracted using the EREG instruction if needed.

The target routine need not save any registers, but is expected to return to the address provided in GPR 14 on entry. The target routine can pass information back to the caller of IEAARR by placing it in GPR/AR 0, 1, and/or 15. The IEAARR caller will resume immediately after the IEAARR macro expansion.

To code: Specify the RX-type address, or address in register (2)-(12), of a pointer field.

,TARGET=target

When DYNSTORAGE=NOTAVAIL is specified. a required input parameter that is the routine to which the system is to branch after establishing the ARR. The target routine interface is identical to that described under the TARGETPTR parameter.

To code: Specify the RX-type address, or address in register (2)-(12), of the target routine.

,TARGETSTATE=PROB

,TARGETSTATE=SUP

A required parameter that indicates the requested PSW state of the target routine.

,TARGETSTATE=PROB: indicates the target routine is to get control in problem state. This should only be used by a caller currently in problem state.
,TARGETSTATE=SUP: indicates the target routine is to get control in supervisor state. This should only be used by a caller currently in supervisor state.

ABEND codes

The caller may get the following abend code:

0C2-02: TARGETSTATE=SUP was requested by a caller currently running in problems tate.

Return codes

None.

Example 1

Operation:

Branch to the target routine pointed to by field TP, and establish as an ARR the routine pointed to by field AP. Pass to the target area in register 1 the contents of field PP. Make sure that the ARR will get access to the contents of field APP (which ordinarily would contain the address of a parameter area). Make sure that the target routine gets control in problem state (which implies that the caller of IEARR should currently be running in problem state).

The code is as follows.

IEAARR TARGETPTR=TP,ARRPTR=AP,PARAMPTR=PP,
      ARRPARAMPTR=APP,TARGETSTATE=PROB
   ...