FESTAE — Fast extended STAE

Description

The FESTAE macro allows an SVC to define and activate, or to deactivate and no longer define, an ESTAE-type recovery routine with minimal overhead and no locking requirements. The ESTAE-type recovery routine activated by FESTAE receives control in the same sequence and under the same conditions as it would if it were activated by the ESTAE macro. The FESTAE macro can be issued in cross memory mode as long as the currently addressable address space is the home address space. For more information, see z/OS MVS Programming: Authorized Assembler Services Guide. To delete a FESTAE recovery routine that was established by the FESTAE macro, use the FESTAE macro rather than macros such as ESTAE, ESTAEX, or STAE.

The FESTAE macro expansion has no external linkage.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state and PSW key 0
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	The caller may hold locks, but is not required to hold any.
Control parameters:	Must be in the primary address space Except for the TCB, all input parameters to this macro can reside in storage above 16 megabytes if the issuer is executing in 31-bit addressing mode.

Programming requirements

FESTAE users executing in 31-bit addressing mode must recompile using the FESTAE macro expansion so that the exit routine gets control in 31-bit addressing mode.

The caller must include the following mapping macros:

IHAPSA
IHARB
IHASCB
IKJTCB

Restrictions

Only type 2, 3, or 4 SVC routines can use the FESTAE macro
The FESTAE macro can be issued to create only one recovery routine within the scope of the SVC routine. The ESTAEX macro or the ESTAE macro with the BRANCH option must be used to create additional recovery routines.

Input register information

Before issuing the FESTAE 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. Register notation is required for the following FESTAE macro parameters: EXITADR, WRKREG, RBADDR, TCBADDR, and PARAM.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register

Contents

0

Unchanged

1-14

One of the following:

If you specify 0,WRKREG=work reg addr, the register you specify (1-14) is used as a work register by the system.
If you specify EXITADR=exit addr, the register you specify (1-14) is used as a work register by the system.
Registers not specified for either work reg addr or exit addr are unchanged.

15

Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

Specification of the TCBADDR keyword results in more efficient code.

Syntax

The FESTAE macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede FESTAE.

FESTAE

␢	One or more blanks must follow FESTAE.

EXITADR=`exit addr`	`exit addr`: Register (1) - (14).
0,WRKREG=`work reg`	`work reg addr`: Register (1) - (14).

,RBADDR=`svrb addr`	`svrb addr`: Register (1) - (14).

,TCBADDR=`tcb addr`	`tcb addr`: Register (1) - (14).

,PARAM=`list addr`	`list addr`: Register (1) - (14).

,XCTL=NO	Default: XCTL=NO
,XCTL=YES

,PURGE=NONE	Default: PURGE=NONE
,PURGE=HALT
,PURGE=QUIESCE

,ASYNCH=YES	Default: ASYNCH=YES
,ASYNCH=NO

,TERM=NO	Default: TERM=NO
,TERM=YES

,RECORD=NO	Default: RECORD=NO
,RECORD=YES

,ERRET=`label`	`label`: Any valid assembler name.

,SDWALOC31=NO	Default: SDWALOC31=NO
,SDWALOC31=YES

Parameters

The parameters are explained as follows:

EXITADR=exit addr
0,WRKREG=work reg: Specifies whether an ESTAE-type recovery routine is to be defined and activated, or deactivated and no longer defined. EXITADR=exit addr specifies the register that contains the address of an ESTAE-type recovery routine to be entered if the task issuing FESTAE ends abnormally.
If you specify 0,WRKREG=work reg, the current ESTAE-type recovery routine is deactivated and no longer defined if it was defined by the FESTAE macro. An error occurs if the current ESTAE-type recovery routine was not created by FESTAE. You do not have to initialize the register you specify for work reg; the system uses it as a work register.
,RBADDR=svrb addr: Specifies a register that contains the address of the current SVRB prefix. RBADDR must be specified if EXITADR has also been specified.
,TCBADDR=tcb addr: Specifies the register containing the current TCB address.
,PARAM=list addr: Specifies the register containing the address of a user-defined parameter list that contains data to be used by the ESTAE routine. The routine receives this address when it is scheduled for execution. The use of this parameter list is optional, but the user should zero out any spurious data it might contain whether or not he intends to use it. If the user does not select the PARAM option, the routine receives instead the 24-byte parameter area in the SVRB. In this case, the user must locate this SVRB parameter area and initialize it with appropriate data.
,ERRET=label: Specifies a label within the CSECT issuing the FESTAE for which addressability has been established. The FESTAE macro branches to this label if it is returning a code other than zero. This option saves the user the instructions necessary to check the return code. If the user does not specify the ERRET option, control returns instead to the instruction immediately following the FESTAE macro. The return code is in register 15.
All the other FESTAE parameters have the same meaning as their ESTAE counterparts.

ABEND codes

None.

Return codes

When control is returned to the instruction following the FESTAE macro, GPR 15 contains one of the following return codes.

Table 1. Return Codes for the FESTAE Macro
Hexadecimal Return Code	Meaning and Action
00	Meaning: Successful completion of the FESTAE request. Action None.
08	Meaning: Program error. A previous create has been issued with FESTAE for this SVRB; the request has been ignored. Action: None; do not reissue this macro.
0C	Meaning: Program error. Cancel has been specified under one of the following conditions: There is no exit for this TCB. The most recent exit is not owned by the caller. The most recent exit was not created by FESTAE. Action: Ensure that the current recovery routine was established using the FESTAE macro.

Example

In case of an abnormal termination, execute the ESTAE routine specified by register 2, allow asynchronous processing, do not allow special error processing, default to PURGE=NONE, and pass the parameter list pointed to by register 7 to the ESTAE routine.

FESTAE  EXITADR=(REG2),RBADDR=(REG3),TCBADDR=(REG6),   X
        PARAM=(REG7),ASYNCH=YES,TERM=NO