Description

The LXRES macro reserves one or more linkage indexes for the caller's use. The reserved linkage indexes are owned by the cross memory resource ownership task of the current home address space. The linkage index reservation applies across all linkage tables in the system and remains in effect until the LX is eligible to be reassigned, as described below:

Non-reusable system LX: The system does not reassign the LX. The original requestor of the LX should reconnect to the LX if the address space terminates and then restarts.
Reusable system LX: The system reassigns the LX after the owning address space has terminated or after the owner has used LXFRE to free the LX.
Non-reusable non-system LX: The system reassigns the LX after all entry tables are disconnected from the LX. This is the case when the owning address space terminates or when the owner uses ETDIS to disconnect the entry table from the LX and uses LXFRE to free the LX; and all address spaces that have used ETCON to connect the LX to that entry table have either terminated or used ETDIS to disconnect the entry table from the LX.
Reusable non-system LX: The system reassigns the LX after the owning address space has terminated or after the owner has used LXFRE to free the LX.

Related macro

LXFRE

Environment

These are the requirements for the caller:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PKM 0-7
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in primary address space

Programming requirements

Restrictions

None.

Input register information

The LXRES 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 LXRES 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

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

Syntax	Description

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

␢	One or more blanks must precede LXRES.

LXRES

␢	One or more blanks must follow LXRES.

LXLIST=`lx list addr`	`lx list addr`: RX-type address or register (2) - (12).
ELXLIST=`elx list addr`	`elx list addr`: RX-type address or register (2) - (12).

,LXSIZE=12	Default: LXSIZE=12 when you do not specify EXLIST or REUSABLE=YES; LXSIZE=16 when you specify ELXLIST or REUSABLE=YES.
,LXSIZE=16
,LXSIZE=23
,LXSIZE=24

,REUSABLE=NO	Default: REUSABLE=NO
,REUSABLE=YES
,SYSTEM=NO	Default: SYSTEM=NO
,SYSTEM=YES

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

Parameters

The parameters are explained as follows:

LXLIST=list addr

ELXLIST=list addr

lx list addr specifies the address of a variable-length list of fullword entries. The first fullword in the list must contain the number (1 to 32) of linkage index (LX) values to be returned. The list must be long enough to contain the requested number of values. The LX values are returned in the list entries in the proper position for ORing with the entry index to form a PC number.

elx list addr specifies the address of an area that contains extended linkage index (LX) values. The first fullword in the list must contain the number (1 to 32) of extended linkage index (LX) values to be returned. Each extended LX value is an eight-byte area that contains a 4-byte sequence number followed by a 4-byte LX value. The area must be long enough to contain the requested number of values. The LX value within the extended LX value is in the proper position for ORing with the entry index to form a PC number. The sequence number in each extended LX value is relevant only when you have specified REUSABLE=YES. You can specify ELXLIST even if the LX Reuse Facility is not enabled.

LXSIZE=12

LXSIZE=16

LXSIZE=23

LXSIZE=24

LXSIZE allows you to specify the maximum size of the LX, which is either 12, 16, 23, or 24 bits. The system is allowed to return any LX that is no larger than the size that you specify. On a system that supports only 2048 LXs (running on a processor prior to a z890 or z990 at driver level 55 and running at level z/OS V1R6 or with the LX reuse facility, the returned LX will fit within 12 bits. The LX reuse facility is available with z/OS V1R6 to provide additional LXs and improve reusability of LXs. It is enabled when running on a z890 or z990 processor at driver level 55 or above, with APAR OA07708 installed. When the facility is enabled bit CVTALR in byte CVTFLAG2 of the CVT data area is 1.

LXSIZE=12 is the default when you do not specify REUSABLE=YES and you do not specify ELXLIST. If you specify LXSIZE=12 along with EXLIST or REUSABLE=YES, the system ignores LXSIZE=12 and uses LXSIZE=16 instead. You can use the LXLIST parameter for the returned data regardless of the LXSIZE value, unless you also specify REUSABLE=YES.

LXSIZE=16 is the default when you have specified either the ELXLIST or REUSABLE parameter.

Because the LX forms part of the PC number (bits 0–23), and because the PC instruction generates the PC number as an 'effective address', the value you specify for LXSIZE depends on the addressing mode of the calling programs that will execute the PC:

Specify LXSIZE=16 if any callers might execute the PC instruction in AMODE 24.
Specify LXSIZE=23 if callers will execute the PC instruction only in AMODE 31 or 64. Do not specify LXSIZE=23 if the PC can ever be executed in AMODE 24.
Specify LXSIZE=24 if callers will execute the PC instruction only in AMODE 64.

REUSABLE=NO

REUSABLE=YES

By specifying the REUSABLE keyword, you can decide that whether or not the LX being returned is reusable. When you specify REUSABLE=YES, you must also:

Specify the ELXLIST parameter.
Make sure that the PC issued using the reusable LX is done by placing the sequence number for that LX in bits 0-31 of 64-bit GPR 15 prior to issuing the PC.

The sequence number for the LX is returned within the ELXLIST entry for the LX.

If the LX Reuse Facility is not enabled, a non-reusable LX will be returned.

,SYSTEM=NO

,SYSTEM=YES

Specifies whether (YES) or not (NO) the linkage indexes are being reserved for system connections. If YES is specified, a subsequent ETCON macro specifying the linkage index causes all address spaces to be connected to the entry table.

,RELATED=value

Specifies information used to self-document macros by “relating” functions or services to corresponding services performed elsewhere. The format and contents of the information specified can be any valid coding values.

ABEND codes

052
053

See z/OS MVS System Codes for an explanation and programmer responses for this code.

Return codes

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

Table 1. Return Code for the LXRES Macro
Return Code	Meaning
00	Meaning: The specified linkage indexes 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.