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: Assembler Services Guide.
Environment
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem 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
- 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.
- 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). |
,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.
- ,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.
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
LRA 1,VSA
LR 5,1
INVOKE1 IARR2V RSA=(5),VSA=VSAOUT
.
.
VSA DS F
VSAOUT DS F
Example 2
INVOKE2 IARR2V RSA=(5),ASID=ASIDO
.
.
ASIDO DS F
Example 3
INVOKE3 IARR2V RSA=(5),STOKEN=STOKO
.
.
STOKO DS F
Example 4
INVOKE4 IARR2V RSA=(5),WORKREG=(6),NUMVIEW=VIEWS,NUMVALID=VALS
.
.
VIEWS DS F
VALS DS F