IEALSQRY — Linkage stack query

Description

The linkage stack query macro IEALSQRY checks the level of the current entry on the linkage stack relative to the level of the entry associated with the most recent recovery routine. The output of the macro is a value (in the TOKEN parameter) a recovery routine can use to ensure that a retry routine runs with the appropriate linkage stack entry. If the return code is not zero, the value in TOKEN is not valid.

Your program is to pass the value in TOKEN to a recovery routine. When the recovery routine gets control, it can place that value in the SDWA field SDWALSLV. That action ensures that, when a retry routine gets control, it has the correct linkage stack level. For information about how to use the value in TOKEN, see the topic about the linkage stack at a retry routine in z/OS MVS Programming: Assembler Services Guide.

The output of IEALSQRY depends upon the current environment and on the recovery environment that exists:
  • If at least one ESTAE-type recovery routine is in effect, the output depends on the most recently activated routine:
    • If it is a STAE or STAI routine, a return code of 8 is returned.
    • If it is an ESTAE or ESTAEX for the current RB, the value returned is the difference between the current level of the linkage stack and the level of the stack at the time the ESTAE or ESTAEX was activated.
    • If it is an ESTAI, the value returned is the difference between the current level of the linkage stack and the level of the stack at the time the newest PRB that is older than the oldest non-PRB was created (or simply the newest PRB if all the RBs are PRBs).
  • If no STAEs, ESTAEXs, ESTAEs exist for this RB and no ESTAI or STAIs are in effect, a return code of 8 is returned.

See z/OS MVS Programming: Assembler Services Guide for further information about the use of the SDWALSLV field.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state, PSW key 8-15
Dispatchable unit mode: Task
Cross memory mode: Any PASN, any HASN, any SASN
Amode: 24- or 31-bit
ASC mode: Primary or access register (AR)
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: No locks are required.
Control parameters: Control parameters must be in the primary address space.

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the IEALSQRY macro, the caller does not have to place any information into a general purpose register (GPR) or access register (AR).

Output register information

When control returns to the caller from IEALSQRY, the GPRs contain:
Register
Contents
0
Output token value, which is copied to the area specified by the TOKEN parameter.
1
Used as a work register by the system.
2-13
Unchanged.
14
Used as a work register by the system.
15
Return code.
When control returns to the caller from IEALSQRY, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system.
2-13
Unchanged.
14 and 15
Used as work registers by the system.

Performance implications

This macro should not be used in a performance-sensitive program.

Syntax

The standard form of the IEALSQRY macro is written as follows:

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
␢ One or more blanks must precede IEALSQRY.
   
IEALSQRY  
   
␢ One or more blanks must follow IEALSQRY.
   
  Valid parameters
   TOKEN=token token: RS-type address or register (1) - (12).

Default: Leave token in GPR 0.
   
   ,RETCODE=retcode retcode: RS-type address, or register (2) - (12).

Default: No retcode processing.
   

The parameters are explained as follows:

TOKEN=token
Specifies a halfword area (or the address of the area in register (1)-(12)) where the system places a value that indicates the difference between the number of linkage stack entries present when the recovery routine was activated and the number that are currently present. A recovery routine can place this value in field SDWALSLV (in mapping macro IHASDWA) to ensure that the retry routine runs with the proper level of the linkage stack. If you do not use TOKEN, you can find the value in GPR 0.
RETCODE=retcode
Specifies a fullword output variable (or register (2)-(12)) into which the system copies the return code GPR 15. If you do not use RETCODE, you can find the return code in GPR 15.

ABEND codes

The IEALSQRY caller might receive abend code X'B78'. For detailed abend code information, see z/OS MVS System Codes.

Return codes

When control returns to the caller, register 15 contains one of the following decimal return codes (hexadecimal values are shown in parentheses):

Table 1. Return Codes for IEALSQRY
Return Code Meaning and Action
0 (0) Meaning: Successful completion. A valid value is in the TOKEN parameter.

Action: None required.
4 (4) Meaning: The system encountered a linkage stack entry that violates the authorization or stacking-PC conditions that are required for successful retry.

Action: Avoid using the token when retrying. You cannot retry to the current linkage stack level.
8 (8) Meaning: No recovery routine of the proper type exists. Either no recovery routine exists or the most recently activated recovery routine is STAE or STAI.

Action: Avoid using the token when retrying. You cannot retry to the current linkage stack level.
16 (10) Meaning: System error.

Action: Report the problem to IBM. Avoid using the token when retrying. You cannot retry to the current linkage stack level.

Example

Obtain the value that a recovery routine can place in SDWALSLV: 
         IEALSQRY TOKEN=MYTOKEN
 .
 .
MYTOKEN  DS    H        Output TOKEN