IARR2V — Convert a central storage address to a virtual storage address

Description

Use the IARR2V macro to convert a central storage address to a virtual storage address. This conversion can be useful when you have the central storage address from handling I/O or doing diagnostic support and need to know the corresponding virtual address.

When the input storage address is a central storage address that backs a single page, the system returns the ASID that indicates the address space that owns the central storage, and the STOKEN that indicates the address space or data space that uses the central storage. When a central storage address does not back any page, or backs a read-only nucleus page, the system returns a non-zero return code and reason code.

For more information on the use of the IARR2V macro, see z/OS MVS Programming: Authorized Assembler Services Guide. IARR2V is also described in the z/OS MVS Programming: Assembler Services Guide with the exception of the LINKAGE parameter.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state with any PSW key. For the LINKAGE parameter, supervisor state with any PSW key.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24-, 31- or 64-bit.
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller may hold the local or CPU lock, but is not required to hold any locks.
Control parameters:	None.

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the IARR2V 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

When control returns to the caller, the GPRs contain:

Register: Contents
0: ASID if return code is 0 or 4; otherwise, reason code. The ASID value is X'FFFF' if the returned virtual address represents common storage.
1: Virtual storage address if return code is 0 or 4; otherwise, used as a work register 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 ARs contain:

Register: Contents
0: First four bytes of STOKEN if return code is 0 or 4; otherwise, used as a work register by the system.
1: Last four bytes of STOKEN if return code is 0 or 4; otherwise, used as a work register by the system.
2-13: Unchanged.
14: Total shared view count if return code is 0 or 4; otherwise, used as a work register by the system.
15: Valid shared view count if return code is 0 or 4; otherwise, used as a work register by the system.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede IARR2V.

IARR2V

␢	One or more blanks must follow IARR2V.

RSA=`rsa_addr`	`rsa_addr`: RS-type address, or register (2) - (12).
RSA64=`rsa_addr64`	`rsa_addr64`: RS-type address, or register (2) - (12).

,VSA=`vsa_addr`	`vsa_addr`: RS-type address, or register (2) - (12).
,VSA64=`vsa_addr64`	`vsa_addr64`: RS-type address, or register (2) - (12).

,ASID=`asid_addr`	`asid_addr`: RS-type address, or register (2) - (12).

,STOKEN=`stoken_addr`	`stoken_addr`: RS-type address, or register (2) - (12).

,WORKREG=`work_reg`	`work_reg`: RS-type address, or register (2) - (12).
,WORKREG=NONE	Default: WORKREG=NONE

,NUMVIEW=`view_addr`	`view_addr`: RS-type address, or register (2) - (12).

,NUMVALID=`val_addr`	`val_addr`: RS-type address, or register (2) - (12).

,LINKAGE=SYSTEM	Default: LINKAGE=SYSTEM
,LINKAGE=BRANCH

,RETCODE=`retcode`	`retcode`: RS-type address, or register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address, or register (2) - (12).

Parameters

The parameters are explained as follows:

RSA=rsa_addr: Specifies the name (RS-type) or address (in register 2-12) of an input fullword that contains the central storage address to be converted to a virtual storage address. This keyword is used to provide a 31–bit real address. RSA and RSA64 are mutually exclusive keywords. You must specify one or the other.
RSA64=rsa_addr64: Specifies the name (RS-type) or address (in register 2-12) of an input double-word that contains the central storage address to be converted to a virtual storage address. This keyword is used to provide a 64–bit real address. RSA and RSA64 are mutually exclusive keywords. You must specify one or the other. To use this keyword, the SYSTATE macro must be invoked specifying ARCHLVL greater than 1.
,VSA=vsa_addr: Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the virtual storage address that corresponds to the input central storage address.
,VSA64=vsa_addr64: Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the 64–bit virtual storage address that corresponds to the input central storage address. VSA and VSA64 are mutually exclusive keywords. To use this keyword, the SYSTATE macro must be invoked specifying ARCHLVL greater than 1.
,ASID=asid_addr: Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the ASID of the address space associated with the output virtual storage address. The system returns the ASID in bits 16-31 of the fullword, and clears bits 1-15 to 0. If the input central storage address backs a page that is shared through the use of the IARVSERV macro, the system sets bit 0 to 1; otherwise, bit 0 contains 0.
,STOKEN=stoken_addr: Specifies the name (RS-type) or address (in register 2-12) of an optional 8-character output field that the system uses to return the STOKEN for the address space or data space associated with the output virtual storage address.
,WORKREG=work_reg
,WORKREG=NONE: Specifies whether the system is to return a page sharing view count. If you want the system to return a page sharing view count, specify work-reg as a digit from 2 through 12 that identifies a GPR/AR pair that the system can use as work registers. WORKREG=work_reg is required if you code NUMVIEW or NUMVALID.
WORKREG=NONE is the default and specifies that the system is not to return the sharing count.
,NUMVIEW=view_addr: Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the number of page sharing views associated with the input central storage address. This number is non-zero only if the system sets bit 0 of the ASID. NUMVIEW=view_addr is required with the WORKREG=work_reg parameter.
,NUMVALID=val_addr: Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the number of valid page sharing views associated with the input central storage address. A valid page must be currently defined in central storage. This number is non-zero only if the system sets bit 0 of the asid_addr. NUMVALID=val_addr is required with the WORKREG=work_reg parameter.
,LINKAGE=SYSTEM
,LINKAGE=BRANCH: Specifies whether the system is to use a program call (LINKAGE=SYSTEM) or branch entry (LINKAGE=BRANCH). LINKAGE=SYSTEM is the default.
,RETCODE=retcode: Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword into which the system copies the return code from GPR 15.
,RSNCODE=rsncode: Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword into which the system copies the a reason code from GPR 0.

ABEND codes

None.

Return and reason codes

When the IARR2V macro returns control to your program, GPR 15 (and retcode if you coded RETCODE) contains the return code. If the return code is not 0 or 4, GPR 0 (and rsncode if you coded RSNCODE) contains the reason code.

Table 1. Return and Reason Codes for the IARR2V Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	None	Meaning: The IARR2V request completed successfully. The address returned in the VSA parameter represents an address space page. Action: None required.
04	None	Meaning: The IARR2V request completed successfully. The address returned in the VSA parameter represents a data space page. Action: None required.
08	xx0001xx	Meaning: Program error. The IARR2V request was unsuccessful because the input central storage address was not within the bounds of central storage. Action: Check your input central storage address and rerun the program.
08	xx0002xx	Meaning: Program error. The IARR2V request was unsuccessful because the frame corresponding to the input central storage address was not assigned to a page. Action: Check your input central storage address and rerun the program.
08	xx0003xx	Meaning: Program error. The IARR2V request was unsuccessful because the frame corresponding to the input central storage address contains shared data, but no virtual address for any accessible address space (either home, primary, or secondary) corresponds to the frame. Action: Check your input central storage address and rerun the program.
08	xx0004xx	Meaning: System error. The IARR2V request was recursively invoked. Action: Record the return code and reason code and supply them to the appropriate IBM support personnel.
08	xx0005xx	Meaning: Program error. The IARR2V request was unsuccessful because the frame corresponding to the input central storage address was assigned, but the data space STOKEN could not be found. Action: Check your input central storage address and rerun the program.
08	xx0006xx	Meaning: Program error. The IARR2V request was unsuccessful because the virtual address is above 2G and the caller did not specify VSA64. Action: Specify VSA64 on the IARR2V invocation.

Example 1

Convert the central storage address in variable VSA and place the result in variable VSAOUT.

         LRA   1,VSA
         LR    5,1
INVOKE1  IARR2V RSA=(5),VSA=VSAOUT
  .
  .
VSA      DS    F
VSAOUT   DS    F

Example 2

Same as Example 1, but return ASID in variable ASIDO.

INVOKE2  IARR2V RSA=(5),ASID=ASIDO
  .
  .
ASIDO    DS    F

Example 3

Same as Example 1, but return STOKEN in variable STOKO.

INVOKE3  IARR2V RSA=(5),STOKEN=STOKO
  .
  .
STOKO    DS    F

Example 4

Obtain the total and valid number of page sharing views associated with the input address. WORKREG is required.

INVOKE4  IARR2V RSA=(5),WORKREG=(6),NUMVIEW=VIEWS,NUMVALID=VALS
  .
  .
VIEWS    DS    F
VALS     DS    F