Chapter 15. Using access registers. IBM z/OS Version 2 Release 3

PDF

Документ

Chapter 15. Using access registers

For storing data, MVS offers a program the use of a virtual storage area called a data space. Assembler instructions (such as Load, Store, Add, and Move Character) manipulate the data in a data space. When you use instructions to manipulate data in a data space, your program must use the set of general purpose registers (GPRs) plus another set of registers called access registers. This chapter describes how to use access registers to manipulate data in data spaces.

Through access registers, your program can use assembler instructions to perform basic data manipulation, such as: v Moving data into and out of a data space, and within a data space v Performing arithmetic operations with values that are located in data spaces

To fully understand how to use the macros and instructions that control data spaces and access registers, you must first understand some concepts.

What is an access register (AR)? An AR is a hardware register that a program uses to identify an address space or a data space. Each processor has 16 ARs, numbered

0 through 15, and they are paired one-to-one with the 16 GPRs. When your program uses ARs, it must be in the address space control mode called access register (AR) mode.

Access

Registers

0 1 Identify address spaces or data spaces

14 15

General

Purpose

Registers

0 1

Identify locations within an address or data space 14 15

ARs are used when fetching and storing data, but they are not used when doing branches.

What is address space control (ASC) mode? The ASC mode controls where the system looks for the data that the program is manipulating. Two ASC modes are available for your use: primary mode and access register (AR) mode.

v In primary mode , your program can access data that resides in the program's primary address space. When it resolves the addresses in data-referencing instructions, the system does not use the contents of the ARs.

v In AR mode , your program can access data that resides in the address space or data space that the ARs indicate. For data-referencing instructions, the system uses the AR and the GPR together to locate an address in an address space or data space.

How does your program switch ASC mode? Use the SAC instruction to change

ASC modes: v SAC 512 sets the ASC mode to AR mode.

v SAC 0 sets the ASC mode to primary mode.

285

What does an AR contain? An AR contains a token, an access list entry token

(ALET). An ALET is an index to an entry on the access list. An access list is a table of entries, each one of which points to an address space, data space, or hiperspace to which a program has access.

Figure 65 shows an ALET in the AR and the access list entry that points to an

address space or a data space. It also shows the address in the GPR that points to the data within the address/data space.

Address/Data Space

Access List

ALET

GPR

Data

Figure 65. Using an ALET to Identify an Address Space or a Data Space

For programs in AR mode, when the GPR is used as a base register in an instruction, the corresponding AR must contain an ALET. Conversely, when the

GPR is not used as a base register, the corresponding AR is ignored.

By placing an entry on an access list and obtaining an ALET for the entry, a program builds the connection between the program and an address space, data space, or hiperspace. The process of building this connection is called establishing addressability to an address space, data space, or hiperspace. To add the entry to

the access list, your program uses the ALESERV macro, which is described in “The

ALESERV macro” on page 291.

A program adds an entry to an access list so that it can: v Gain access to a data space or an address space through assembler instructions.

v Obtain the ALET for a hiperspace. With that ALET, the program can use the

HSPALET parameter on HSPSERV to:

– Gain additional performance from the transfer of data to and from expanded storage. Information on when and how you use an access list entry for

hiperspaces is described in “Obtaining additional HSPSERV performance” on page 323.

– Improve its ability to share hiperspaces with other programs. The subject of

sharing hiperspaces is described in “Shared and non-shared standard hiperspaces” on page 320.

For the rest of this information, assume that entries in access lists point to data spaces, not hiperspaces or address spaces.

v The subject of inter-address space communication, appropriate only for programs in supervisor state or with PSW key 0 - 7, is described in z/OS MVS

Programming: Extended Addressability Guide.

286

z/OS MVS Assembler Services Guide

v Because a program cannot use ARs to directly manipulate data in a hiperspace, the subject of how a program uses ARs and access lists to access hiperspaces differs from the discussion in the rest of this chapter.

Access lists

When the system creates an address space, it gives that address space an access list

(PASN-AL) that is empty. Programs add entries to the DU-AL and the PASN-AL.

The entries represent the data spaces and hiperspaces that the programs want to access.

Types of access lists

An access list can be one of two types: v

A dispatchable unit access list (DU-AL), the access list that is associated with the

TCB v A primary address space access list (PASN-AL), the access list that is associated with the primary address space

Figure 66 shows PGM1 that runs in AS1 under TCB A. The figure shows TCB A's

DU-AL. It is available to PGM1 (and to other programs that TCB A might represent). The DU-AL has an entry for Data Space X, and PGM1 has the ALET for

Data Space X. Therefore, PGM1 has access to Data Space X. PGM1 received an

ALET for Space Y from another program. The PASN-AL has the entry for Space Y.

Therefore, PGM1 also has access to Data Space Y. Because it does not have the

ALET for Space Z, PGM1 cannot access data in Space Z.

PASN-AL

Space Z

Space Y

Data Space X

TCB A

PGM1

DU-AL

ALETX DC F

ALETY DC F

Data

Space X

Figure 66. An Illustration of a DU-AL

The differences between a DU-AL and a PASN-AL are significant and you need to understand them. The following table summarizes the characteristics of DU-ALs and PASN-ALs as they relate to problem state programs with PSW key 8 - F.

Chapter 15. Using access registers

287

Table 25. Characteristics of DU-ALs and PASN-ALs

DU-AL

Each work unit (TCB and SRB) has its own unique DU-AL. All programs associated with that work unit can use its DU-AL.

A program that the work unit represents can add and delete entries on the work unit's

DU-AL for the data spaces it created or owns.

PASN-AL

Each address space has its own unique

PASN-AL. All programs that run in the primary address space can use its PASN-AL.

A program can add entries for the data spaces it owns or created to the PASN-AL, providing an entry for the data space is not already on the PASN-AL through the actions of another problem state program with PSW

8 - F. A program can delete entries for data spaces it owns or created.

A PASN-AL cannot be passed from one address space to another.

A program cannot pass its task's DU-AL to a program running under another task, with one exception: when a program issues an

ATTACH macro, it can pass a copy of its

DU-AL to the subtask. This allows the subtask to start with a copy of the attaching task's DU-AL. After the attach, the attaching task and the subtask can add and delete entries on their own DU-ALs.

A DU-AL can have up to 509 entries.

When the work unit terminates, the DU-AL is purged.

A PASN-AL can have up to 510 entries, some of which are reserved for the type of space called SCOPE=COMMON.

When the owning jobstep task terminates, the PASN-AL is purged.

Writing programs in AR mode

After your program has an entry on an access list and the ALET that indexes the entry, it must place a value in an AR before it can use the data space. To understand how the system resolves addresses in instructions for programs in AR

mode, see Figure 67 on page 289. This figure shows how an MVC instruction in AR

mode moves data from location B in one data space to location A in another data space:

288

z/OS MVS Assembler Services Guide

Address Space

GPR

ALET ALET

X Y . . .

. . .

MVC A(LEN,1),B(2)

Access List

Space Y

Space X

GPR 1 is used as a base register to locate the destination of the MVC and

AR 1 is used to identify Space X.

GPR 2 is used to locate the data to be moved and AR 2 identifies Space Y that contains the data.

Space X

Space Y

Figure 67. Using Instructions in AR Mode

GPR 1 is used as a base register to locate the destination of the data, and AR 1 is used to identify space X. GPR 2 is used to locate the source of the data, and AR 2 identifies Space Y. In AR mode, a program can use a single MVC instruction to move data from one address/data space to another.

Note:

The address space that contains the MVC instruction does not have to be either Space X or Space Y.

In similar ways, you can use instructions that compare, test-under-mask, copy, move, and perform arithmetic operations.

When the instructions reference data in the primary address space, the ALET in the

AR must indicate that the data is in that address space. For this purpose, the system provides a special ALET with a value of zero. Other than using this value to identify the primary address space, a program should never depend on the value of an ALET.

An ALET of zero designates the primary address space.

The “Loading the value of zero into an AR” on page 291 shows several examples

of loading a value of zero in an AR.

Coding instructions in AR mode

As you write your AR mode programs, use the advice and warnings in this information.

v For an instruction that references data, the system uses the contents of an AR to identify the address/data space that contains the data that the associated GPR points to.

v Use ARs only for data reference; do not use them with branching instructions.

Chapter 15. Using access registers

289

v Just as you do not use GPR 0 as a base register, do not use AR/GPR 0 for addressing.

An AR should contain only ALETs; do not store any other kinds of data in an

AR.

Because ARs that are associated with index registers are ignored, when you code

assembler instructions in AR mode, place the commas very carefully.

In those instructions that use both a base register and an index register, the comma that

separates the two values is very important. Table 26 shows four examples of how a

misplaced comma can change how the processor resolves addresses on the load instruction.

Table 26. Base and Index Register Addressing in AR Mode

Instruction Address Resolution

L 5,4(,3) or L 5,4(0,3) There is no index register. GPR 3 is the base register. AR 3 indicates the address/data space.

L 5,4(3) or L 5,4(3,0) GPR 3 is the index register. Because there is no base register, data is fetched from the primary address space.

L 5,4(6,8)

L 5,4(8,6)

GPR 6 is the index register. GPR 8 is the base register. AR 8 indicates the address/data space.

GPR 8 is the index register. GPR 6 is the base register. AR 6 indicates the address/data space.

For the first two entries in Table 26:

v In primary mode, the examples of the load instruction give the same result.

v In AR mode, the data is fetched using different ARs. In the first entry, data is fetched from the address/data space represented by the ALET in AR 3. In the second entry, data is fetched from the primary address space (because AR/GPR

0 is not used as a base register).

For the last two entries in Table 26:

v In primary mode, the examples of the load instruction give the same result.

v In AR mode, the first results in a fetch from the address/data space represented by AR 8, while the second results in a fetch from the address/data space represented by AR 6.

Manipulating the contents of ARs

Whether the ASC mode of a program is primary or AR, it can use assembler instructions to save, restore, and modify the contents of the 16 ARs. The set of instructions that manipulate ARs include: v CPYA — Copy the contents of an AR into another AR.

EAR — Copy the contents of an AR into a GPR.

v LAE — Load a specified ALET and address into an AR/GPR pair.

v SAR — Place the contents of a GPR into an AR.

v LAM — Load the contents of one or more ARs from a specified storage location.

v STAM — Store the contents of one or more ARs to a specified storage location.

For their syntax and help with how to use these instruction, see Principles of

Operation.

290

z/OS MVS Assembler Services Guide

Loading an ALET into an AR

An action that is very important when a program is in AR mode, is the loading of an ALET into an AR. The following example shows how the LAM instruction loads an ALET into AR 2:

LAM 2,2,DSALET

DSALET DS F

LOAD ALET OF DATA SPACE INTO AR2

DATA SPACE ALET

Loading the value of zero into an AR

When the code you are writing is in AR mode, you must be very conscious of the contents of the ARs. For instructions that reference data, the ARs must always contain the ALET that identifies the data space that contains the data. When the data is in the primary address space, the AR that accompanies the GPR that has the address of the data must contain the value zero.

The following examples show several ways of placing the value zero in an AR.

Example 1: Set AR 5 to value of zero, when GPR 5 can be changed.

SLR 5,5

SAR 5,5

SET GPR 5 TO ZERO

LOAD GPR 5 INTO AR 5

Example 2: Set AR 5 to value of zero, without changing value in GPR 5.

LAM 5,5,=F’0’ LOAD AR 5 WITH A VALUE OF ZERO

Another way of doing this is the following:

ZERO

LAM 5,5,ZERO

DC F’0’

Example 3: Set AR 5 to value of zero, when AR 12 is already zero.

CPYA 5,12 COPY AR 12 INTO AR 5

Example 4: Set AR 12 to zero and set GPR 12 to the address contained in GPR 15.

This sequence is useful to establish a program's base register GPR and AR from an entry point address contained in register 15.

PGMA CSECT

LAE 12,0(15,0)

USING PGMA,12

ENTRY POINT

ESTABLISH PROGRAM’S BASE REGISTER

Another way to establish AR/GPR module addressability through register 12 is as follows:

LAE 12,0

BASR 12,0

USING *,12

Example 5: Set AR 5 and GPR 5 to zero.

LAE 5,0(0,0) Set GPR and AR 5 to zero

The ALESERV macro

Use the ALESERV macro to add an entry to an access list and delete that entry.

The information describes the parameters on the ALESERV macro and gives examples of its use.

Chapter 15. Using access registers

291

Adding an entry to an access list

The ALESERV ADD macro adds an entry to the access list. Two parameters are required: STOKEN, an input parameter, and ALET, an output parameter.

v STOKEN - the eight-byte STOKEN of the address/data space represented by the entry. You might have received the STOKEN from DSPSERV or from another program.

v ALET - index to the entry that ALESERV added to the access list. The system returns this value at the address you specify on the ALET parameter.

The best way to describe how you add an entry to an access list is through an example. The following code adds an entry to a DU-AL. Assume that the

DSPSERV macro has created the data space and has returned the STOKEN of the data space in DSPCSTKN and the origin of the data space in DSPCORG. ALESERV

ADD returns the ALET in DSPCALET. The program then establishes addressability to the data space by loading the ALET into AR 2 and the origin of the data space into GPR 2.

* ESTABLISH ADDRESSABILITY TO THE DATA SPACE

ALESERV ADD,STOKEN=DSPCSTKN,ALET=DSPCALET

LAM

2,2,DSPCALET

2,DSPCORG

USING DSPCMAP,2

5,DSPWRD1

LOAD ALET OF SPACE INTO AR2

LOAD ORIGIN OF SPACE INTO GR2

INFORM ASSEMBLER

GET FIRST WORD FROM DATA SPACE

USES AR/GPR 2 TO MAKE THE REFERENCE

DSPCSTKN DS CL8

DSPCALET DS F

DSPCORG DS F

DSPCMAP DSECT

DSPWRD1 DS

DSPWRD2 DS

DSPWRD3 DS

DATA SPACE STOKEN

DATA SPACE ALET

DATA SPACE ORIGIN RETURNED

DATA SPACE STORAGE MAPPING

WORD 1

WORD 2

WORD 3

Using the DSECT that the program established, the program can easily manipulate data in the data space.

It is possible to use ALESERV ADD to obtain an entry for a hiperspace. For

information on how hiperspaces use ALETs, see “Obtaining additional HSPSERV performance” on page 323.

Deleting an entry from an access list

Use ALESERV DELETE to delete an entry on an access list. The ALET parameter identifies the specific entry. It is a good programming practice to delete entries from an access list when the entries are no longer needed.

The following example deletes the entry that was added in the previous example.

ALESERV DELETE,ALET=DSPCALET REMOVE DS FROM AL

DSPSERV DELETE,STOKEN=DSPCSTKN DELETE THE DS

DSPCSTKN DS CL8

DSPCALET DS F

DATA SPACE STOKEN

DATA SPACE ALET

If the program does not delete an entry, v An entry on the DU-AL remains on the access list until the work unit terminates. At that time, the system frees the access list entry.

292

z/OS MVS Assembler Services Guide

v An entry on the PASN-AL remains on the access list until the owning jobstep task terminates. At that time, the system frees the access list entry.

Issuing MVS macros in AR mode

Many MVS macro services support callers in both primary and AR modes. When the caller is in AR mode, the macro service must generate larger parameter lists at assembly time. The increased size of the list reflects the addition of ALET-qualified addresses. At assembly time, a macro service that needs to know whether a caller is in AR mode checks the global indicator that SYSSTATE ASCENV=AR sets. The system expects that you have issued SYSSTATE ASCENV=AR when a macro is issued while in AR mode. Then, when the program returns to primary mode, issue

SYSSTATE ASCENV=P to reset the global indicator.

When your program is in AR mode, keep in mind these two facts: v Before you use a macro in AR mode, check the description of the macro in z/OS

MVS Programming: Assembler Services Reference ABE-HSP or z/OS MVS

Programming: Assembler Services Reference IAR-XCT. If the description of the macro does not specifically state that the macro supports callers in AR mode, use the SAC instruction to change the ASC mode and use the macro in primary mode.

v ARs 14 - 1 are volatile across all macro calls, whether the caller is in AR mode or primary mode. Don't count on the contents of these ARs being the same after the call as they were before.

Example of using SYSSTATE

Consider a program that changes ASC mode from primary to AR mode and while in AR mode, issues the LINKX and STORAGE macros. When it changes ASC mode, it issues the following:

SAC 512

SYSSTATE ASCENV=AR

The LINKX macro generates different code and addresses, depending on the ASC mode of the caller. During the assembly of LINKX, the LINKX macro service checks the setting of the global indicator. Because the global indicator indicates that the caller is in AR mode, LINKX generates code and addresses that are appropriate for callers in AR mode.

The STORAGE macro generates different code, depending on the ASC mode of the caller. During the assembly of STORAGE, the STORAGE macro service checks the setting of the global indicator. Because the global indicator indicates that the caller is in AR mode, STORAGE generates code that is appropriate for callers in AR mode.

When the program changes back to primary mode, it issues the following:

SAC 0

SYSSTATE ASCENV=P

Using X-macros

Some macro services, such as LINK and LINKX, offer two macros, one for callers in primary mode and one for callers in either primary or AR mode. The names of the two macros are the same, except the macro that supports both primary and AR mode caller ends with an “X”. This information refers to these macros as

“X-macros”. The rules for using all X-macros, except ESTAEX, are:

Chapter 15. Using access registers

293

v Callers in primary mode can invoke either macro.

Some parameters on the X-macros, however, are not valid for callers in primary mode. Some parameters on the non X-macros are not valid for callers in AR mode. Check the macro descriptions in z/OS MVS Programming: Assembler

Services Reference ABE-HSP or z/OS MVS Programming: Assembler Services

Reference IAR-XCT for these exceptions.

v Callers in AR mode should issue the X-macro after issuing the SYSSTATE

ASCENV=AR macro.

If a caller in AR mode issues the non X-macro, the system substitutes the

X-macro and issues a message during assembly that informs you of the substitution.

IBM recommends

you always use ESTAEX unless your program and your recovery routine are in 24-bit addressing mode, in which case, you should use

ESTAE.

If your program issues macros while it is in AR mode, make sure the macros support AR mode callers and that SYSSTATE ASCENV=AR is coded.

If you rewrite programs and use the X-macro instead of the non X-macro, you must change both the list and execute forms of the macro. If you change only the execute form of the macro, the system will not generate the longer parameter list that the X-macro requires.

Note that an X-macro generates a larger parameter list than the corresponding non

X-macro. A program using the X-macros must provide a larger parameter list than if it used the non X-macro.

Formatting and displaying AR information

The interactive problem control system (IPCS) can format and display AR data.

Use the ARCHECK subcommand to: v Display the contents of an AR v Display the contents of an access list entry

See z/OS MVS IPCS Commands for more information about the ARCHECK subcommand.

294

z/OS MVS Assembler Services Guide