STORE (Guest Storage - ESA/XC, z/XC)

Read syntax diagramSkip visual syntax diagram STore1 LALET alet.AREG areg.ASIT asit.PRISPACE 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 - ESA/XC, z/XC) to store data into the storage of an ESA/XC or z/XC virtual machine.

Operands

L
alters the contents of storage in an address space based on the setting of the address-space-control field in the guest PSW. This is the default.

If the virtual CPU is in primary-space mode, the contents of real storage in the host-primary address space are altered. If the virtual CPU is in the access-register mode and a nonzero BASEnn operand is also specified, the contents of real storage in an AR-specified address space are altered.

If the virtual CPU is in access-register mode, but either the BASEnn operand is not specified or is specified as 'BASE0', the contents of real storage in the host-primary address space are altered.

ALETalet.
alters the contents of real storage in an access list entry token (ALET) specified address space. The alet may be 1 to 8 hexadecimal digits; leading zeros are optional. The ALET is used in conjunction with the virtual machine's host access list to determine the address space to store data in.
AREGareg.
alters the contents of real storage in an access register specified address space. The areg may be specified as 1 hexadecimal or 2 decimal digits. The ALET within the access register is used in conjunction with the virtual machine's host access list to determine the address space to store data in.
ASITasit.
alters the contents of absolute storage in the address space identified by the specified address space identification token (ASIT). The asit may be 1 to 16 hexadecimal digits; leading zeros are optional.
PRI
alters the contents of real storage in the host-primary address space. This is the address space from which the virtual CPU is fetching instructions at the time the command is run.
SPACEspaceid.
alters the contents of absolute storage in the address space identified by spaceid. The spaceid is a 1-character to 33-character string of the form:
Read syntax diagramSkip visual syntax diagramowner: spacename
where owner is an optional 1-character to 8-character user ID of the virtual machine that owns the 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. N is the default.

If hexloc is not on a fullword boundary, the store operation begins on the next lower fullword boundary. If data is less than one fullword (8 hexadecimal digits) in length, it is right-justified 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 form the key for the page.
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, data must be a string of 2 or more hexadecimal digits with no embedded blanks.
U
stores the data starting at the address specified by hexloc. By default the data is treated as EBCDIC; if the X option is specified, the data is treated as ASCII. The data is stored in byte segments with no word alignment.
hexloc
specifies the starting storage location that is to be altered. The value hexloc can be 1 - 16 hexadecimal digits, separated with an optional underscore for readability; leading zeros are optional. The default is zero.

If neither the BASE or INDEX operand is used, hexloc is the address of the first location to be altered. This address is treated as a 64-bit address, regardless of the addressing mode of the virtual CPU.

If either the BASE or the INDEX operand is used, hexloc is a displacement rather than an address. The first location to be altered is specified by the sum of hexloc and the contents of the registers that are specified with the BASE and INDEX operands. If general register 0 is specified in the BASE or INDEX operand, it is always treated as containing zero when forming this sum. The sum is treated as a 24-bit, 31-bit, or 64-bit address according to the addressing mode of the virtual CPU.

%
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 contents of guest storage using the specified starting address (hexloc) as a displacement from the address in the specified general register. The specified register may be a decimal number from 0 to 15 or a hexadecimal number from 0 to F.

If the virtual CPU is in access-register mode, and the L operand is specified (or defaulted), nn designates an access register/general register pair. Access register nn is implicitly used, in the same manner as if the AREG operand had been specified, in conjunction with the virtual machine's host access list to determine the address space in which to store. If the virtual CPU is not in the access-register mode, or if one of the other space-designation operands (PRI, AREG, ALET, SPACE, ASIT) is specified, access register nn is not implicitly used.

INDEXnn
stores the contents of guest storage using the specified starting address (hexloc) 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 insert into storage. The operand takes on different meanings depending on the type of STORE you are performing (N, S, K, or U). See the descriptions of each of these operands for the meaning of data.

Usage Notes

  1. Special authorization is required to use this command to alter storage in any address space other than 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.

  2. When running with a saved segment, you can store 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 store those locations (or associated keys) causes the non-addressable storage response to be displayed.
  3. The operands L, ALET, AREG, and PRI use the host access-register-translation (ART) process. The ART process performs special-case translation processes for certain ALET values and access registers:
    • The ALET X'00000000' always indicates the host-primary address space.
    • Access register 0 is always treated as containing ALET X'00000000'. The contents of access register 0 are not used during host access-register-translation processing.
  4. General register 0 is always treated as containing the value 0 when used as the base or index register through the BASE or INDEX operands. The contents of general register 0 are never used.
  5. In the XC environment, special rules govern the conversion of real addresses into absolute addresses. In some cases, prefixing is performed as usual to convert a real address to an absolute address, while in other cases prefixing is not performed and real addresses are treated unchanged as absolute addresses.
    These rules have an effect on the interpretation of the addresses that specify the range of storage locations to be altered:
    • When storage is specified using the ALET or AREG operand and the ALET used is not X'00000000', prefixing is not performed on the addresses that specify the range of storage in the target address space.
    • When storage in the host-primary address space is specified by using the PRI operand, or by using the ALET or AREG operand when the ALET used is X'00000000', prefixing is performed as usual on the addresses that specify the range of storage in the host-primary address space.
  6. Although the R operand is not shown in the syntax for this command, it is accepted for compatibility with the STORE (Guest Storage) command used for XA and ESA virtual machines. The R operand performs the same function as the L operand and alters storage in the host-primary address space.
  7. The BASE operand lets you store the storage used by the virtual machine in one less step than would otherwise be possible. Without the BASE operand, you may need to store the contents of a general register, then add the displacement, and then enter the DISPLAY command to examine storage the program is using. With the use of access registers, the BASE operand additionally lets you alter storage without needing to know whether the program is currently in the access-register mode. This is done automatically for you by CP.
  8. When multiple STORE requests are entered on a single line, the BASE and INDEX operands are not applied to subsequent STORE requests on the command line. They must be explicitly entered for each STORE request.
  9. During STORE command processing, key-controlled protection and low-address protection is not used. However, all of the host-related protection mechanisms, such as host page protection and those mechanisms applied during host-access-register translation, are used as normal. For example, an attempt to store at an address in a host-page-protected page, or to change the key at an address in a host-page-protected page, results in an error message.
  10. If the ALET or AREG operand is specified, the STORE command uses the host access-register-translation (ART) process to determine the address space in which to store data. This translation process 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 ended. The rejected operands are displayed along with a message indicating the nature of the exception condition.
  11. 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 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.
  12. If you use an underscore, it must be followed by 8 hexadecimal digits.

Responses

Response 1: 
Store complete
indicates that the data has been stored.

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
  • HCP163E STORE exceeds maximum register
  • HCP260E {Command||command command} processing cannot complete due to errors.
  • HCP657E The virtual machine's page zero is unavailable because it is damaged.
  • 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 {ESA/XC|z/XC} mode.
  • HCP6525E Authorization request failed.