Using ARRs

An ARR provides recovery for a stacking PC routine and receives control if the stacking PC routine encounters an error. An ARR is an ESTAE-type recovery routine. An ARR receives all of the defaults of the ESTAEX macro, with the exception of the TERM parameter. For ARRs, the system uses TERM=YES.

To define an ARR, either:

Issue the IEAARR macro to establish an ARR to cover a target routine, as described in z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG.
Specify the name or address of the routine on the ARR parameter of the ETDEF macro when you define the entry table definition (ETD) for the stacking PC routine; you must also issue the ETCRE macro before the ARR is actually defined to the system. You can use an ARR only for a stacking PC routine that is always entered enabled, unlocked, and in task mode.

You activate an ARR when you issue the PC instruction; you deactivate an ARR when you issue the corresponding PR instruction.

While the stacking PC routine is running, you cannot deactivate its ARR. Therefore, if you do not want an ARR associated with the stacking PC routine, do not code the ARR parameter on the ETDEF macro.

An ARR receives control in 31-bit or 64-bit addressing mode depending on the mode specified via the ETDEF macro or the mode at the time that IEAARR was issued. If it is passed an SDWA, the SDWA is in 31-bit addressable storage.

A stacking PC routine can also have an FRR; however, if the stacking PC routine has an FRR, its ARR gets control only if the FRR percolates. The writer of a stacking PC routine should be aware of the environment in which the routine is called. The system does not give control to an ARR in the following circumstances:

The cross-memory environment required for the ARR (which matches the environment on entry to the stacking PC routine) could not be established.
Your program is running in SRB mode.
Your program is running in task mode; prior to issuing the PC instruction to pass control to the stacking PC routine associated with the ARR, you activated one or more FRRs. If the stacking PC routine encounters an error, the most recently activated FRR gets control. If all FRRs percolate, then unless the ARR was defined with ARRCOND=YES, the system records a symptom record in the logrec data set describing the fact that an ARR has been skipped.

If you issue an IEAARR macro to establish an ARR, you can skip the following instructions until the end of this information. See Setting up, passing, and accessing the parameter area for explanations of passing parameter areas for IEAARR.

If you define the ARR via the ETDEF macro, the stacking PC routine can use the 8-byte modifiable area of the current linkage stack entry to pass parameters to the ARR. To store data into this 8-byte area, the stacking PC routine can use the modify stacked state (MSTA) instruction. The stacking PC routine might, for example, store the address of a footprint area into the first 4 bytes and the ALET identifying the footprint area's address space into the second 4 bytes.

The following example shows how a stacking PC routine can use the 8-byte modifiable area of the linkage stack to pass parameters to an ARR.

Figure 1. Passing Parameters to an ARR

         LAE    2,PARMAREA      GET ALET AND ADDRESS OF PARMAREA
         EAR    3,2             PUT CONTENTS OF AR2 INTO GPR3
         MSTA   2               PLACE ALET AND ADDRESS OF PARMAREA
*                               INTO LINKAGE STACK

The assembler instructions perform the following functions:

LAE places the address of PARMAREA into GPR 2 and the ALET that identifies the address space that contains the PARMAREA into AR 2.
EAR places the contents of AR 2 (the ALET) into GPR 3.
MSTA places the contents of GPR 2 (the address of PARMAREA) and GPR 3 (the ALET of PARMAREA) into the modifiable area of the linkage stack.

When the ARR receives control, the SDWAPARM field contains the address of a copy of the 8-byte modifiable area of the linkage stack entry established by the stacking PC routine associated with the ARR. For example, suppose PGM1 uses a stacking PC to call PCRTN1. After PCRTN1 gets control, it encounters an error and control passes to the ARR associated with the stacking PC routine. At this time, SDWAPARM contains the address of a copy of the modifiable area in the linkage stack entry associated with the stacking PC routine. Note that SDWAPARM does not necessarily contain the address of a copy of the current entry. Between the time it received control and encountered the error, PCRTN1 could have added an entry to the linkage stack through a BAKR instruction. This entry would be the current entry; SDWAPARM contains the address of a copy of a previous entry.

If there is no SDWA, the ARR receives the copy of the 8-byte area in GPR/AR 2: GPR 2 contains the first 4 bytes, and AR 2 contains the second 4 bytes.

If there is no SDWA when the recovery routine requests a retry, the system uses the linkage stack entry that was current when the ARR's stacking PC routine was entered, and from that entry, provides a copy of the current contents of the 8-byte modifiable area in GPR/AR 1.

You have the option to allow or prevent asynchronous interrupts from interrupting an ARR while it is running. To allow asynchronous interrupts, specify ASYNCH=YES on the ETDEF macro. To prevent asynchronous interrupts from interrupting the ARR, specify ASYNCH=NO. If the ARR uses any supervisor services that depend on an asynchronous interrupt for successful completion, specify ASYNCH=YES.

You also have the option to allow cancel or detach processing to interrupt an ARR while it is running or to prevent this interrupt. To allow the interrupt, specify CANCEL=YES on the ETDEF macro. To prevent the interrupt, specify CANCEL=NO. If you specify CANCEL=NO, and a cancel or detach is attempted while the ARR is running, the ARR completes running before the system begins cancel or detach processing. The routine that issues ETDEF cannot use CANCEL=NO unless the stacking PC routine to be associated with the ARR runs in supervisor state or with PSW key 0 - 7.

One ARR can serve multiple stacking PC routines. In this case, each stacking PC routine must not only store information about where in its processing the stacking PC routine is, but must also store information that identifies which stacking PC routine it is.