AXRES — Reserve authorization index

Description

The AXRES macro reserves one or more authorization index (AX) values for the caller's use. The AX values are owned by the current home address space.

The AXSET macro sets the AX of the home address space to the value (or values) that is reserved by the AXRES macro.

The caller can use the value returned by the system as an AX through the AXSET macro, or as an extended authorization index (EAX) through the ETDEF, ETCRE, and ETCON macros. The AX value associated with a program determines whether that program is permitted to issue the PT instruction with another address space as the target, and/or set another address space as its secondary address space through the SSAR instruction. The EAX value determines whether a program running with the EAX can access data in another address space through a private access list entry.

Related macros

ATSET, AXFRE, AXEXT, and AXSET

Environment

These are the requirements for the caller:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PKM = 0 to 7
Dispatchable unit mode:	SRB or task
Cross memory mode:	PASN=HASN
AMODE:	Any
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	For callers in primary mode, control parameters must be in the primary address space.

Programming requirements

The parameter list passed to the AXRES macro must be addressable in primary mode when the macro expansion is executed.

Restrictions

None.

Input register information

The AXRES macro is sensitive to the SYSSTATE macro with the OSREL=ZOSV1R6 parameter

If the caller has issued the SYSSTATE macro with the OSREL=ZOSV1R6 parameter (Version 1 Release 6 of z/OS® or later) before issuing the AXRES macro, the caller does not have to place any information into any general purpose register (GPR) unless using it in register notation for a particular parameter, or using it as a base register.
Otherwise, the caller must ensure that the following general purpose register contains the specified information:
Register

Contents

13

The address of an 18-word save area

Output register information

After the caller issues the macro, the macro might use some registers as work registers or might change the contents of some registers. When the macro returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. 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-1: Used as work registers by the macro
2-13: Unchanged
14: Used as a work register by the macro
15: Return code

Performance implications

None.

Syntax

This is the standard form of the AXRES macro:

Syntax	Description

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

␢	One or more blanks must precede AXRES.

AXRES

␢	One or more blanks must follow AXRES.

AXLIST=`list addr`	`list addr`: RX-type address or register (0) - (12).

,RELATED=`value`	`value`: Any valid macro keyword specification.

Parameters

The parameters are explained as follows:

AXLIST=list addr: Specifies the address of a variable length list, addressable in primary mode, of halfword entries in which requested AX values are to be returned. The first halfword must contain the number of values to be returned. Enough halfwords must follow the first entry to contain the requested number of values. If the requested number of AX values is not available, the caller is abnormally terminated.
,RELATED=value: Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and can be any valid coding values.

ABEND codes

See z/OS MVS System Codes for an explanation and programmer responses for these codes.

Return codes

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

Table 1. Return Code for the AXRES Macro
Hexadecimal Return Code	Meaning
00	The AX value or values were successfully reserved.

Examples

For examples of the use of this and other cross memory macros, refer to the chapter on cross memory communication in z/OS MVS Programming: Extended Addressability Guide.