DISPLAY (Guest Storage - z/Architecture)

Authorization

Privilege Class: G

Purpose

Use DISPLAY (Guest Storage - z/Architecture®) to display the storage contents of a virtual machine in z/Architecture mode.

Operands

L

displays the contents of second-level storage (storage that appears real to your virtual machine) if the virtual machine is operating in DAT OFF mode, or displays the contents of third-level storage (storage that appears virtual to your virtual machine) if the virtual machine is operating in DAT ON mode. This is the default.

The address space selected for display of third-level storage corresponds with the setting of the address space control field in the guest PSW and is the primary, secondary, or (if the virtual machine is an ESA virtual machine) home space. When the PSW indicates access register mode, the primary space is selected for display unless a nonzero BASEnn operand is also specified and the virtual machine is an ESA virtual machine, in which case an access register specified address space is displayed.

R

displays the contents of second-level storage (storage that appears real to your virtual machine).

ALEThexword.

displays the contents of third-level storage (storage that appears virtual to your virtual machine) using the specified access list entry token (ALET). The ALET is used in conjunction with guest access register translation tables to locate the guest address space to display.

ALraddr.

specifies an access list (AL) to be used in conjunction with the ALET to locate the guest address space. The guest real address of the access list may be 1 to 8 hexadecimal digits.

AREGareg.

displays the contents of third-level storage (storage that appears virtual to your virtual machine) using the contents of the specified access register. The areg may be specified as 1 hexadecimal or 2 decimal digits. The ALET within the access register is used in conjunction with guest access register translation tables to locate the guest address space to display.

ASCEasce.

displays the contents of third-level storage (storage that appears virtual to your virtual machine) using the specified address-space-control element (ASCE). The asce may be 1 to 16 hexadecimal digits, separated with an optional underscore for readability; leading zeros are optional.

ASITasit.

displays the contents of absolute storage in the CP-created address space identified by the specified address space identification token (ASIT). The asit may be 1 to 16 hexadecimal digits; leading zeros are optional.

ASNasn.

displays the contents of third-level storage (storage that appears virtual to your virtual machine) using the specified address space number (ASN). The asn may be 1 to 4 hexadecimal digits. It is used in conjunction with guest ASN-translation tables to locate a guest address space to display.

ASTEraddr.

displays the contents of third-level storage (storage that appears virtual to your virtual machine) using the segment table designation contained within the specified ASN second table entry (ASTE) located at guest real address raddr.

HOME

displays the contents of third-level storage (storage that appears virtual to your virtual machine) using guest control register 13.

PRI

displays the contents of third-level storage (storage that appears virtual to your virtual machine) using guest control register 1.

SECO

displays the contents of third-level storage (storage that appears virtual to your virtual machine) using guest control register 7.

SPACEspaceid.

displays the contents of absolute storage in the CP-created address space identified by spaceid. The spaceid is a 1-character to 33-character string of the form:

where owner is an optional 1-character to 8-character user ID of the virtual machine that owns the CP-created address space, and spacename is the 1-character to 24-character address space name assigned to the address space.

If owner is not specified, your virtual machine is assumed to be the owner of the address space. The spacename 'BASE' is preassigned by CP to be the name of your virtual machine's host-primary address space.

N

displays the contents of storage in hexadecimal without character translation. This is the default. Storage is displayed in word segments. An address range is displayed starting at the fullword in which the specified address resides. Storage is displayed in fullword increments.

The storage key is displayed on the first line, as well as at every page boundary.

I

displays the contents of storage in instruction format. The specified address is rounded down to the nearest halfword boundary.

The storage key is displayed on the first line, as well as at every page boundary.

J

stores unformatted storage contents in a response buffer. An address range is stored starting at the byte location specified. If no length or end address is specified, four bytes are stored in the response buffer by default.

When the response buffer is smaller than the response length, a zero-length response is returned, with condition code one to indicate insufficient buffer length.

The operand is accepted only when the DISPLAY command is invoked via DIAGNOSE X'08' with the response-to-buffer option specified. Unlike other invocations of DIAGNOSE X'08', this form of the command does not store a trailing line-end (x'15') character. See usage note 14 for an example of this invocation. See z/VM: CP Programming Services for more information about DIAGNOSE X'08'.

K

displays the storage keys in hexadecimal, the block-usage state, and the block-content state for all page frames or partial page frames included in the specified address range.

S

displays the contents of storage in hexadecimal translation. Storage is displayed as a string starting at the location specified. The specified address range is not boundary-aligned.

The storage key is displayed on the first line, as well as at every page boundary.

U

displays the contents of storage in character form. Storage is displayed starting at the address specified as an EBCDIC string or as an ASCII string if the X option is specified. The specified address range is not boundary-aligned.

The storage key is displayed on the first line, as well as at every page boundary.

T

displays the contents of storage in hexadecimal and character form. Storage is displayed in word segments. An address range is displayed starting at the X'10'-byte boundary in which the specified address resides. X'10' bytes of storage are displayed per line. The default display is in EBCDIC; the display is in ASCII if the X option is specified.

The storage key is displayed on the first line, as well as at every page boundary.

M

displays the contents of storage in hexadecimal and character form. A header is displayed as the first line, and at every page boundary, which contains the high-order 32 bits of the 64-bit address along with the storage key. Storage is displayed in word segments. An address range is displayed starting at the X'10' byte boundary in which the specified address resides. X'10' bytes of storage are displayed per line. The hexadecimal display is followed by the storage as an EBCDIC string or as an ASCII string if the X option is specified.

0

hexloc1

is the starting storage location that is to be displayed. The address hexloc1 may be 1 to 16 hexadecimal digits, separated with an optional underscore for readability, leading zeros are optional. The default is zero.

Storage locations and the minimum amount displayed are rounded according to the following conventions (in hexadecimal):

Option	Start	Minimum Length
T	10	10
M	10	10
K	800	800
S	1	1
I	2	2 - 6 depending on the instruction
J	1	1 (default length is 4)
N	4	4
U	1	1

%

indicates 31-bit address indirection. Indirection means that the contents of the specified address are used instead of the address itself. In this case, the 31 bits at the specified address (the high-order bit is turned off) are used as the new address for the DISPLAY command.

When specified following the INDEX and BASE operands, the indirect address is determined after BASE and INDEX are applied.

&

indicates 64-bit address indirection. Indirection means that the contents of the specified address are used instead of the address itself. In this case, the 64 bits at the specified address are used as the new address for the DISPLAY command. A maximum of 16 indirection characters can be specified.

When specified following the INDEX and BASE operands, the indirect address is determined after BASE and INDEX are applied.

-hexloc2

:hexloc2

-END

:END

is the last of a range of hexadecimal storage locations whose contents are to be displayed. If specified, hexloc2 must be equal to or greater than hexloc1 and must be within the virtual machine storage size. The address hexloc2 may be from 1 to 16 hexadecimal digits, separated with an optional underscore for readability; leading zeros are optional. A colon (:) means the same as a dash (-) when you are specifying a range of addresses.

Specify END if you want to display the remaining contents of storage. END is the default if you specify a dash (-) or a colon (:) without an address.

.bytecount

.END

is a hexadecimal integer designating the number of bytes of storage (starting with the byte at hexloc1) to be displayed. If specified, the bytecount must have a value of at least 1 and may be from 1 to 16 hexadecimal digits, separated with an optional underscore for readability; leading zeros are optional.

Specify END if you want to display the remaining contents of storage. END is the default if you specify a period (.) without a byte count value.

BASEnn

displays the contents of guest storage using the specified starting address (hexloc1) as a displacement from the address in the specified general register (nn). The general register may be specified as a decimal number from 0 to 15 or as a hexadecimal number from 0 to F. nn specifies an AR/GR pair if all of the following are true:

• The L operand is specified.
• The virtual machine is an ESA virtual machine in z/Architecture mode.
  Note: An ESA virtual machine simulates ESA/390 architecture when initially defined. However, a guest may have the capability to switch the virtual machine from ESA/390 mode to z/Architecture mode.
• The virtual CPU is in access register mode.

The specified access register is used, in the same manner as if the AREGareg. operand had been specified, in conjunction with guest access-register-translation tables to locate the guest address space to display.

INDEXnn

displays the contents of guest storage using the specified starting address (hexloc1) as a displacement from the address in the specified register (nn). This register may be a decimal number from 0 to 15 or a hexadecimal number from 0 to F.

Usage Notes

1. When running with a saved segment, you can display storage locations outside the range of your virtual machine size if they are within the saved segment. If locations exist between the upper limit of your virtual machine and the address at which the saved segment was saved, any attempt to display those locations (or associated keys) causes the non-addressable storage response to be displayed.

   Refer to Usage Notes.

2. When you use the operand ALEThexword.ALraddr., the primary list bit in the ALET is ignored.
3. When the operands L, PRI, SECO, HOME, ASTEraddr., ASCEhexword., ASNasn., AREGareg., ALEThexword., and ALEThexword.ALraddr. are specified, the access-register-translation (ART), the ASN translation and the dynamic-address-translation (DAT) processes may be used. These contain special-case translation processes, including:
   • ALET 0 always indicates the current primary address space designated by the ASCE in guest control register 1, regardless of the current contents of the dispatchable-unit access list.
   • ALET 1 always indicates the current secondary address space designated by the ASCE in guest control register 7, regardless of the current contents of the dispatchable-unit access list.
   • Access register 0 is always treated as containing ALET 0. The contents of access register 0 are not used during access-register-translation processing.
   • General register 0 is always treated as containing the value 0 when used as the base or index register. The contents of general register 0 are never used.
4. The BASE operand is primarily intended to be used in conjunction with the L operand. It lets you display the storage used by the virtual machine in one less step than would otherwise be possible. Without the BASE operand, you may need to display the contents of a general register, add the displacement, and then enter the DISPLAY command to examine storage the program is using. With the use of access registers, the BASE option also lets you examine storage without needing to know whether the program is currently in access register mode. This is done automatically for you by CP.
5. If the BASEnn and INDEXnn operands are used together, the specified starting address for display is used as a displacement from the address formed from the sum of the contents of the two specified registers.
   The values in the registers specified by the BASEnn and INDEXnn operands are treated as 24-bit, 31-bit, or 64-bit real addresses according to the addressing mode bits (EA and BA - bits 31 and 32) in the virtual machine's PSW. The addressing mode is determined as follows:

   Bit 31	Bit 32	Addressing Mode
   0	0	24-bit
   0	1	31-bit
   1	1	64-bit

6. During DISPLAY command processing, the authorization mechanisms used during normal address translation are not used.
7. Special authorization is required to use the SPACE or ASIT operand of this command to view any address space other than the host-primary address space of the virtual CPU. In order to use this command to display storage in an address space, one of the following conditions must be satisfied:
   • Your virtual machine must be the owner of the address space. Your virtual machine is the owner of its host-primary address space and of any address space that it creates using the CREATE function of the ADRSPACE macro.
   • If the address space is owned by another virtual machine, your virtual machine must have read-only or read-write authorization to the address space. The owner of the address space can grant authorization to your virtual machine using the PERMIT function of the ADRSPACE macro.

   Authorization is granted on a space-by-space basis, so that you may be authorized to view one address space of a virtual machine, but not to view a different space.

8. The operands V and W used in displaying third-level storage from guest primary and secondary are supported for compatibility. The PRI and SECO operands replace the V and W operands.
9. When multiple DISPLAY requests are entered on a single line, the BASEnn and INDEXnn operands are not applied to subsequent DISPLAY requests on the command line. They must be explicitly entered for each DISPLAY request.
10. When the ASIT or SPACE operand is specified, the DISPLAY request will fail if the specified address space does not exist, or if you are not authorized to access the address space. The current request is rejected and processing of the command line is terminated. The rejected operands are displayed along with a message indicating the nature of the error.
11. The DISPLAY command requires an address-space-control element (ASCE) to display third-level storage (storage that appears virtual to your virtual machine). It may receive the ASCE as an operand, find it in a control register, or use the access-register translation (ART) process or the address space number (ASN) translation process to obtain the ASCE. The access-register translation and ASN translation processes may fail because of one of several program exception conditions. If the translation does not succeed, the current request is rejected, and processing of the command line is terminated. The rejected operands are displayed along with a response indicating the nature of the exception condition.
12. If you use an underscore, it must be followed by 8 hexadecimal digits.
13. If you issue DISPLAY with the ASIT operand and specify the ASIT of a space owned by a user that has been relocated by the VMRELOCATE command prior to a subsequent reset clear function, the DISPLAY command is rejected and error message HCPCDL6156E is issued. To avoid this situation, issue a command that initiates a reset clear function on the user on the relocation target system. Then obtain the new ASIT value by using the QUERY SPACES command or the ADRSPACE QUERY API from a program. Commands that result in a reset clear include:
    • SYSTEM CLEAR
    • IPL by NSS name
    • IPL by device with the CLear option
    • SET MACHine (to a different machine architecture)
14. The J operand is useful in an adjunct context to retrieve memory from the principal configuration. For example, the following line

    pgmold=Diag(8,'CPU * DISPLAY RJ140.10')

    can be included in a REXX exec to capture the z/Architecture program old PSW.
15. For more information, see Usage Notes.

Responses

Response 1:

thexloc word1 word2 word3 word4 [key] [*TRANSLATION*] [Rhexloc]

Response 2:

thexlochi_ Storage Key - [key]
 hexloclo word1 word2 word3 word4 [*TRANSLATION*] [Rhexloc]

Response 3:

thexloc *TRANSLATION* [key] [Rhexloc]

Response 4:

thexloc mnemonic x-x mnemonic x-x mnemonic x-x [key] [Rhexloc]

Response 5:

thexloc stringhexadecimaldata [key] [Rhexloc]

Response 6:

thexloc1 TO hexloc2 KEY = key STATE = uc

A response is sent for every contiguous address range that has unique storage keys and whenever a segment boundary is crossed.

Response 7:

addr is not addressable because of an invalid PSW.

Response 8:

thexloc1 to hexloc2  non-addressable storage
thexloc1 to hexloc2  non-addressable storage
- protection exception
thexloc1 to hexloc2  non-addressable storage
- addressing exception
thexloc1 to hexloc2  non-addressable storage
- segment translation exception
thexloc1 to hexloc2  non-addressable storage
- page translation exception
thexloc1 to hexloc2  non-addressable storage
- translation specification exception
thexloc1 to hexloc2  non-addressable storage
- ASCE type exception
thexloc1 to hexloc2  non-addressable storage
- region-first-translation exception
thexloc1 to hexloc2  non-addressable storage
- region-second-translation exception
thexloc1 to hexloc2  non-addressable storage
- region-third-translation exception
thexloc1 to hexloc2  non-addressable storage
- block volatility exception

Response 9:

thexloc1 TO hexloc2 SUPPRESSED LINE(S) SAME AS ABOVE …