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: Authorized Assembler Services Guide.

The output of IEALSQRY depends upon the current environment and on the recovery environment that exists:
  • If FRRs exist, the value returned in TOKEN is the difference between the current level of the linkage stack and the level of the stack at the time the FRR was activated.
  • If no FRRs exist, but the caller holds a lock or is in SRB mode, a return code of 8 is returned.
  • If no FRRs exist, and the caller is unlocked and in task mode, and at least one ESTAE-type recovery routine is in effect, the output depends on the most recently activated routine:
    • If it is a STAE, STAI, or FESTAE routine, a return code of 8 is returned.
    • If it is an ARR, the value returned in TOKEN is the difference between the current level of the linkage stack and the level of the stack at the time the ARR was activated.
    • 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 FRRs exist, and the caller is unlocked and in task mode, and no ESTAEXs, ESTAEs, STAEs, or FESTAEs exist for this RB and no ESTAIs, STAIs, or ARRs in effect, a return code of 8 is returned.

See z/OS MVS Programming: Authorized 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 or SRB
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: The caller can hold the local lock of the primary address space and can additionally hold the CMS lock. The caller can hold the CPU lock. No locks are required. If the primary address space does not match the home address space, the caller must not hold the local lock of the home address space.
Control parameters: Control parameters must be in the primary address space.

Programming requirements

None.

Restrictions

Do not issue the IEALSQRY macro in a DIE routine.

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. If in a state from which you cannot issue ESTAEX, no FRR exists. If in a state from which you can issue ESTAEX, either no recovery routine exists or the most recently activated recovery routine is STAE, STAI, or FESTAE.

Action: Avoid using the token when retrying. You cannot retry to the current linkage stack level.
12 (C) Meaning: You called IEALSQRY in a DIE routine.

Action: Do not use the IEALSQRY macro in a DIE routine.
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