TESTART — Tests the validity of ALETs

Description

TESTART tests for conditions that lead to an access register translation (ART) program interruption. Use it to test:

The validity of an access list entry token (ALET)
The validity of the extended authorization index (EAX) authority of the program that passed the ALET
The value of an ALET
If a specified ALET points to an entry for a SCOPE=COMMON data space.

By testing for these conditions, your program can avoid using an ALET that would cause an ART program interruption.

For information about ALETs, EAXs, and EAX-authorization, see z/OS MVS Programming: Extended Addressability Guide.

Environment

Requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	Any
ASC mode:	Primary or AR
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks held:	The caller can be locked or unlocked.
Control parameters:	Not applicable

Programming requirements

None.

Restrictions

None.

Input register information

The input to the macro is the ALET and the caller's EAX.

Output register information

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

Register: Contents
0-1: Used as work registers by the system
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-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

None.

Syntax

The TESTART macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede TESTART.

TESTART

␢	One or more blanks must follow TESTART.

ALET=`(access-reg)`	`access-reg`: Access register (0) - (15).

,EAX=`(eax)`	`eax`: Register (0) - (14).

,CADS=YES	Default: CADS=NO
,CADS=NO

Parameters

The parameters are explained as follows:

ALET=(access-reg)

Specifies an access register 0 through 15 that contains the ALET to be tested.

,EAX=(eax)

Specifies a general purpose register 0 through 14 that contains the EAX to be used in the test, in bit positions 0-15. (The system ignores bits 16 - 31.)

,CADS=YES

,CADS=NO

Specifies if TESTART is to check the caller's PASN-AL to see if the specified ALET points to an entry for a SCOPE=COMMON data space. If CADS=YES is specified, TESTART returns one of the following return codes:

X'04' if the ALET does not represent a SCOPE=COMMON data space
X'18' if the ALET is for a SCOPE=COMMON data space.

If CADS=NO is specified, TESTART does not indicate whether or not the specified ALET is for a SCOPE=COMMON data space.

ABEND codes

None.

Return codes

When TESTART macro returns control to your program, GPR 15 contains a return code.

Table 1. Return Codes for the TESTART Macro
Hexadecimal Return Code	Meaning and Action
00	Meaning: The specified ALET is 0. Action: None.
04	Meaning: The specified ALET represents a valid entry on the DU-AL. If CADS=YES was specified on the call, the ALET does `not` point to an entry for a SCOPE=COMMON data space. Action: None required. However, you might take some action based upon your application.
08	Meaning: The specified ALET represents a valid entry on the PASN-AL. Action: None required. However, you might take some action based upon your application.
0C	Meaning: The specified ALET is 1. Action: None required. However, you might take some action based upon your application.
10	Meaning: The specified ALET and/or EAX will cause an ART program interruption. Action: None required. However, you might take some action based upon your application.
14	Meaning: A system error occurred in the TESTART service routine. Action: Retry the request.
18	Meaning: The program specified CADS=YES on the call to TESTART. The specified ALET points to an entry for a SCOPE=COMMON data space. Action: None required. However, you might take some action based upon your application.

Example 1

Request that TESTART verify the following two conditions:

The ALET in AR1 passed by the caller is zero or is a valid ALET on the caller's dispatchable unit access list. The caller's registers were saved in the linkage stack prior to this example.

The caller is EAX-authorized to data being passed as a parameter that can be accessed by the called program that runs with an authorized EAX.

R1       EQU   1                General register 1
AR1      EQU   1                Access register 1
R15      EQU   15               General register 15
*
         SLR   R15,R15          Set a zero code for the ESTA
         EREG  AR1,AR1          Extract GPR/AR 1 from the linkage stack
         ESTA  R0,R15           Place the caller's EAX in R1 bits 0-15
         TESTART ALET=(AR1),EAX=(R1)  Test the ALET/EAX
         CL    R15,=X'00000004' Test the TESTART return code
         BH    ERROR            Branch to error routine when the return
*                               code is greater than 4

Example 2

Request that TESTART verify the following two conditions:

The ALET passed by the caller (on the linkage stack) points to an entry for a SCOPE=COMMON data space

The caller is EAX-authorized to data being passed as a parameter that can be accessed by the called program that runs with an authorized EAX.

R1       EQU   1                General register 1
AR1      EQU   1                Access register 1
R15      EQU   15               General register 15
*
         SLR   R15,R15          Set a zero code for the ESTA
         EREG  AR1,AR1          Extract GPR/AR 1 from the linkage stack
         ESTA  R0,R15           Place the caller's EAX in R1 bits 0-15
         TESTART ALET=(AR1),EAX=(R1),CADS=YES  Test the ALET/EAX
         CL    R15,=X'00000018' Test the TESTART return code
         BE    CADS_ALET        Branch to CADS ALET routine processing