STORE (Guest Storage - z/Architecture)

Read syntax diagramSkip visual syntax diagram STore1 LRALET hexword.AL rddr.AREG areg.ASCE asce.ASIT asit.ASN asn.ASTE raddr.HOMEPRISECOSPACE spaceid.NKSUX0hexloc%&;BASE nn;INDEX nn%& data
Notes:
  • 1 Do not put blanks between operands that relate to a single STORE request, but at least one blank must precede the data to be stored.

Authorization

Privilege Class: G

Purpose

Use STORE (Guest Storage - z/Architecture®) to store data in the second-level or third-level storage of a virtual machine in z/Architecture mode.

Operands

L
stores the data in second-level storage (storage that appears real to your virtual machine) if the virtual machine is operating in DAT OFF mode, or stores the data in 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 corresponds to 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 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 selected.

R
stores your data in second-level storage (storage that appears real to your virtual machine).
ALEThexword.
stores the data in 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 store data in.
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.
stores the data in 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 store data in.
ASCEasce.
stores the data in 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.
ASITasit.
stores the data in 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.
stores the data in 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 the guest address space to store data in.
ASTEraddr.
stores the data in third-level storage (storage that appears virtual to your virtual machine) using the segment table designation contained within the ASN second table entry (ASTE) located at guest real address raddr.
HOME
stores the data in third-level storage (storage that appears virtual to your virtual machine) using guest control register 13.
PRI
stores the data in third-level storage (storage that appears virtual to your virtual machine) using guest control register 1.
SECO
stores the data in third-level storage (storage that appears virtual to your virtual machine) using guest control register 7.
SPACEspaceid.
stores the data in absolute storage in the CP-created address space identified by spaceid. The spaceid is a 1-character to 33-character string of the form:
Read syntax diagramSkip visual syntax diagram owner: spacename
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
stores the data (in hexadecimal) in successive fullword locations starting at the address specified by hexloc. The smallest group of hexadecimal values that can be stored is one fullword. This is the default.

If hexloc is not on a fullword boundary, the store operation begins on the next lower fullword boundary. If the value being stored is less than one fullword (8 hexadecimal digits) in length, it is right-adjusted in the word and is filled in with zeros. If two or more hexadecimal words are specified, they must be separated with one or more blanks.

K
stores the data in the storage key for the 4 KB page in which hexloc is located. Two hexadecimal digits are used to form the key for the page. If one digit is provided, it becomes the lower digit, and the upper digit is zero.
S
stores the data (in hexadecimal) without word alignment, starting at the address specified in hexloc. The shortest string that can be stored is 1 byte (2 hexadecimal digits).

If the string contains an odd number of characters, the last character is not stored; an error message is issued, and the function terminates. If you specify the S operand, the data you enter must be a string of two or more hexadecimal digits with no embedded blanks.

U
stores the data starting at the address specified by hexloc. The data is treated as an EBCDIC string by default; it is treated as an ASCII string if the X option is specified. The data is stored in byte segments with no word alignment.
hexloc
is the starting storage location that is to be altered. The address hexloc may be 1 to 16 hexadecimal digits, separated with an optional underscore for readability; leading zeros are optional. The default is zero.
%
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 set to 0) are used as the address for the STORE 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 address for the STORE 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.

BASEnn
stores the data in guest storage using the specified address (hexloc) 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 the guest access-register-translation tables to locate the guest address space to store data in.

INDEXnn
stores the data in guest storage using the specified starting address (hexloc1) as a displacement from the address in the specified register. The specified register may be a decimal number from 0 to 15 or a hexadecimal number from 0 to F.
data
is the data you want to place in storage. The operand takes on different meanings, depending on the type of STORE you are performing (N, K, S, or U). See the descriptions of each of these operands for the meaning of data.

Usage Notes

  1. An attempt to store at an address in a protected page, or to change the key at an address in a protected page, results in an error message. A protected page is a page of read-only storage.
  2. The operands HOME, AREGareg., ALEThexword., and ALEThexword.ALraddr. are valid only if the the virtual machine is an ESA virtual machine.
  3. When you use the operand ALEThexword.ALraddr., the primary list bit in the ALET is ignored.
  4. The operands L, PRI, SECO, HOME, ASTEraddr., ASCEasce., ASNasn., AREGareg., ALEThexword., and ALEThexword.ALraddr. use the access register translation (ART), the ASN translation or the dynamic address translation (DAT) processes. These contain special case translation processes including the following:
    • 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 the ALET 0. The contents of access register 0 are not used during ART processing.
    • General register 0 is always treated as containing the value 0 when used as the base or index register. The contents of GR 0 are never used.
  5. The BASE operand is primarily intended for use in conjunction with the L operand. It allows a user to modify the storage the virtual machine uses in one less step than would otherwise be possible. Without the BASE operand, a user may need to display the contents of a general register, then add the displacement, and then enter the STORE command to modify storage the program is using. With the use of access registers, the BASE option allows the user to modify storage without needing to know whether the program is currently in access register mode. This is done automatically by CP.
  6. If you use the BASEnn and INDEXnn operands together, the specified hexloc is used as a displacement from the address formed by 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
  7. During STORE command processing, the authorization mechanisms used during normal address translation are not used.
  8. Special authorization is required to use the SPACE or ASIT operand of this command to alter any address space other the host-primary address space of the virtual CPU. In order to use this command to alter 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-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 alter one address space of a virtual machine but may not be authorized to alter a different space.

  9. The operands V and W used to place data in third-level storage from guest primary and secondary are being supported for compatibility. The PRI and SECO operands replace the V and W operands.
  10. When the ASIT or SPACE operand is specified, the STORE request fails if the specified address space does not exist, or if you are not authorized to alter 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 STORE command requires a segment table designation (ASCE) to alter 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 STORE 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 STORE command is rejected and error message HCPSTT6156E 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)

Responses

Response 1:
Store complete
is issued when the command completes successfully.

Messages

  • HCP003E Invalid option - {option|command contains extra option(s) starting with option}
  • HCP005E Invalid hexdata - hexdata
  • HCP010E Invalid register - register
  • HCP012E Invalid PSW - psw
  • HCP026E Operand missing or invalid
  • HCP033E Hexloc missing or invalid
  • HCP160E Hexloc hexloc exceeds storage
  • HCP163E STORE exceeds maximum register
  • HCP164E Hexloc hexloc non-addressable storage [- block volatility exception]
  • HCP260E {Command|command command} processing cannot complete due to errors.
  • HCP261E key is an invalid storage key.
  • HCP422E The same option was specified twice.
  • HCP657E The virtual machine's page zero is unavailable because it is damaged.
  • HCP1001E An operand is missing for option.
  • HCP2611E {Data|Key} cannot be stored into a read-only page.
  • HCP6025E Operand {STATUS|STORE STATUS|RESTART} is invalid because CPU nn is in check-stop state.
  • HCP6150E An option has been specified that is not valid in z/Architecture mode.
  • HCP6151E Storage {operand} is not addressable because of { a protection | an addressing | a segment translation | a page translation | a translation specification | an ASN translation | an AFX translation | an ASX translation | an ALET translation | an ALEN translation | an ALE sequence | an ASTE validity | an ASTE sequence } exception.
  • HCP6525E Authorization request failed.