LOCASCB — Locate address space control block (ASCB) address

Description

The system identifies an address space through an address space identifier (ASID), an address space control block (ASCB), or a space token (STOKEN). Depending on the MVS™ service you want to use, you might be required to supply an identifier you do not have. For example, you might have the ASID of an address space but need to supply the ASCB. If you have the ASID or STOKEN but need to supply the ASCB, use the LOCASCB macro to return the ASCB address.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state or supervisor state, and any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or secondary when you specify the ASID parameter; primary or access register (AR) when you specify STOKEN.
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	CMS lock, if you want to be sure that the address space doesn't terminate while the system is referencing the ASCB; otherwise, no requirement.
Control parameters:	If you specify the ASID parameter, control parameters must be in the primary address space; if you specify the STOKEN parameter, control parameters must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the LOCASCB 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.

Output register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the caller issued the macro. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

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

Register

Contents

0

When the return code is 0, a reason code.

Reason
code: Explanation
0: At the time of checking, the address space was not terminating. As long as the caller remains legally disabled or holds the general CMS lock, if the address space is targeted for termination, the address space may be quiesced (ASCBFAIL) and may be set invalid for cross memory access (ASTEICMA), but memory termination will not proceed to give control to any address space termination resource managers.
4: The address space is terminating, but termination is not complete. As long as the caller remains legally disabled or continues to hold the general CMS lock, the ASCB/ASSB will not be FREEMAINed. All other address space related resources may or may not be cleaned up.

1

ASCB address or 0

2-13

Unchanged

14

Used as a work register by the system

15

Return code

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

Register: Contents
0: Used as a work register by the system
1: 0 if you specify STOKEN; otherwise, used as a work register by the system
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

None.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede LOCASCB.

LOCASCB

␢	One or more blanks must follow LOCASCB.

ASID=`asid addr`	`asid addr`: RX-type address or register (0) - (15).
STOKEN=`stoken addr`	`stoken addr`: RX-type address

Parameters

The parameters are explained as follows:

ASID=asid addr: Specifies the RX-type address of a halfword that contains the ASID for which the ASCB is to be returned or the register that contains the ASID in bits 16-31. (Bits 0-15 of the register are ignored.)
STOKEN=stoken addr: Specifies the RX-type address of the STOKEN that identifies the address space for which the ASCB is to be returned.

ABEND codes

None.

Return codes

When the LOCASCB macro returns control to your program, GPR 15 contains a hexadecimal return code.

Table 1. Return Codes for the LOCASCB Macro
Return Code	Meaning and Action
00	Meaning: LOCASCB successfully located and returned the ASCB address. Action: None.
04	Meaning: Program error. The ASID or STOKEN did not map to a valid, active ASCB. This may occur because the input ASID of STOKEN never was valid, or because the address space it represents is no longer active. Action: Verify that the input ASID or STOKEN is valid.
08	Meaning: Program error. The STOKEN was not valid. Action: Supply a valid input STOKEN.

Example 1

Get the ASCB address for the address space whose ASID is specified by the constant at location ASN.

       LH    4,ASN
       LOCASCB ASID=(4)

ASN    DC    H'34'

Example 2

Get the ASCB address for the address space whose STOKEN is stored at the location STOKADDR.

         LOCASCB STOKEN=STOKADDR

STOKADDR DS    2F