DEFINE STORAGE

Authorization

Privilege Class: G

Purpose

Use DEFINE STORAGE to change the storage size of your virtual machine.

Operands

MAXIMUM

specifies that the maximum size of virtual machine storage as defined on the MAXSTORAGE statement, if any, or defined in the USER directory entry for the virtual machine, is to be the online storage size of your virtual machine. No other keywords can be specified, because when MAXIMUM is specified, the RESERVED and STANDBY storage sizes are 0.

AS size

specifies the online storage size of your virtual machine. When the RESERVED or STANDBY operand is also specified, the AS size might be adjusted upward because of the storage-increment size specified by the INCREMENT operand, or as determined by CP. The sum of the AS or INITIAL, RESERVED, and STANDBY storage sizes cannot exceed the maximum storage size specified for the virtual machine in the CP directory.

See usage note 8 for an example that demonstrates how the AS size might be adjusted by CP.

INITIAL

specifies that the initial size of virtual machine storage as defined on the STORAGE statement, if any, or defined in the USER directory entry for the virtual machine, is to be the online storage size of your virtual machine. When the RESERVED or STANDBY operand is also specified, the INITIAL size might be adjusted upward because of the storage-increment size specified by the INCREMENT operand, or as determined by CP. The sum of the AS or INITIAL, RESERVED, and STANDBY storage sizes cannot exceed the maximum storage size specified for the virtual machine in the CP directory.

IBM recommends that you use INITIAL in a DEFINE STORAGE command with the STANDBY REMAINDER option specified.

See usage note 14 to understand in which situations using INITIAL causes a system-reset-clear function to be performed.

STANDBY size

specifies the standby storage size of your virtual machine.

The STANDBY size might be adjusted upward by CP because of the storage-increment size specified by the INCREMENT operand, or as determined by CP. The sum of the AS or INITIAL, RESERVED, and STANDBY storage sizes cannot exceed the maximum storage size specified for the virtual machine in the CP directory. You can specify a STANDBY storage size of 0.

See usage note 1 for more information about using STANDBY storage, and see usage note 8 for an example of how the STANDBY storage size might be adjusted by CP.

STANDBY REMAINDER

specifies that the STANDBY storage size should be calculated. The INITIAL keyword must be specified when you specify STANDBY REMAINDER. When you specify STANDBY REMAINDER, the STANDBY storage is equal to the maximum storage size (from the CP directory) minus the initial storage size (from the CP directory) and the RESERVED value specified on the DEFINE STORAGE command. The STANDBY size might be adjusted upward or downward by CP because of the storage-increment size specified by the INCREMENT operand, or as determined by CP. The sum of the AS or INITIAL, RESERVED, and STANDBY storage sizes cannot exceed the maximum storage size specified for the virtual machine in the CP directory.

See usage note 13 for examples of using the STANDBY REMAINDER keyword.

RESERVED size

specifies the reserved storage size of your virtual machine.

The RESERVED size might be adjusted upward by CP because of the storage-increment size specified by the INCREMENT operand, or as determined by CP. The sum of the AS or INITIAL, RESERVED, and STANDBY storage sizes cannot exceed the maximum storage size specified for the virtual machine in the CP directory. You can specify a RESERVED storage size of 0.

See usage note 14 to understand in which situations using RESERVED causes a system-reset-clear function to be performed.

INCREMENT size

specifies the size of a unit of storage that can be added or removed by an operating system running in a virtual machine. The minimum size is 1 MB and must be a power of 2. If necessary, CP adjusts the value up or down to conform to the architected requirements.

See usage note 8 for an example demonstrating how the INCREMENT size might be adjusted by CP.

When no standby or reserved storage is defined for the virtual machine, by default or because the STANDBY and RESERVED operands are set to 0, the INCREMENT operand is not allowed. In this case, the increment size reflected to a second-level operating system is 1 MB.

See usage note 14 to understand in which situations using INCREMENT causes a system-reset-clear function to be performed.

size

is the size of the storage you are defining (when CONFIGURATION is not specified). The size value is of the form nu, where n is a 1- to 7-digit decimal number and u is the 1-character storage unit suffix (see Table 1). For the AS value, n must be greater than 0. For the RESERVED or STANDBY value, a size of 0 is valid.

Table 1. Maximum Input Values for Storage Units

Storage unit (powers of 2)	Suffix (u)	Maximum input value (n)
Kilobytes	K	2096128
Megabytes	M	9999999
Gigabytes	G	9999999
Terabytes	T	9999999
Petabytes	P	16384
Exabytes	E	16

Notes:

1. The K suffix is provided for upward compatibility only; a K specification is rounded up to a MB value. The maximum specification is 2096128K (2047 MB). The K suffix is not valid with a CONFIGURATION specification.
2. The maximum input value of 9999999 for the M, G, or T suffix is not a size limit but the physical limit of the operand (7 digits plus suffix). If the maximum input value for one of these suffixes does not allow you to define the amount of storage you want, you need to use a larger storage unit.
3. An XC virtual machine cannot address more than 2047 MB of storage in its base address space.

CONFIGuration

allows you to define multiple, noncontiguous storage extents. You can also define a single extent just as you would without CONFIGURATION, for example:

DEF STOR 64M
DEF STOR CONFIG 0.64M 

The advantage of CONFIGURATION is that it provides more detail in the command response and in the output of the QUERY VIRTUAL STORAGE command.

0.size

is the size of the first extent you are defining (when CONFIGURATION is specified), which always starts at address 0. The size value is of the form nu, where n is a 1- to 7-digit decimal number and u is the 1-character storage unit suffix (see Table 1).

address

is the starting address of the extent you are defining. The address value is of the form nu, where n is a 1- to 7-digit decimal number and u is the 1-character storage unit suffix (see Table 1). The first address must be zero. Subsequent extent start specifications must specify a higher address than the ending address of the last extent plus one (contiguous extents are not valid).

.size

is the size of the extent you are defining. The size value is of the form nu, where n is a 1- to 7-digit decimal number and u is the 1-character storage unit suffix (see Table 1).

-decrement

is subtracted from the extent starting address specified to calculate the actual extent start address you are defining. The decrement value is of the form nnnnu, where nnnn is a 1- to 4-digit decimal number and u is the 1-character storage unit suffix (see Table 1). The decrement:

• Cannot be larger than the address
• Cannot cause overlap or abutment of a previous extent specification.
• Must use a unit of measure smaller than the one used for address

The decrement value helps to determine addresses of higher values, especially when they cross boundaries, for example:

DEF STOR CONFIG 0.64M 2G-1M.2M

This would define the 66 MB of storage shown below without you having to know (or type in) the address that is 1 MB below the 2 GB line:

The response would be:

 def stor config 0.64m 2g-1m.2m
 STORAGE = 66M
 Storage Configuration:
 0.64M 2G-1M.2M
 Extent Specification               Address Range
 ---------------------------------- -----------------------------------
                  0.64M             0000000000000000 - 0000000003FFFFFF
              2G-1M.2M              000000007FF00000 - 00000000800FFFFF
 Storage cleared - system reset.

See Response 3 for a detailed definition of the information.

Usage Notes

1. The STANDBY operands allow you to define standby storage before you IPL a guest operating system in the virtual machine.

   This allows a second-level operating system to exploit the dynamic storage reconfiguration (DSR) capabilities of the architecture. For example, the operator of a second-level z/VM® system can issue the SET STORAGE command to convert standby storage to configured storage, thereby increasing the size of the storage configuration, or convert configured storage to standby storage to reduce the size of the storage configuration. These changes can be seen first-level in the QUERY VIRTUAL STORAGE command response values for STORAGE= and STANDBY=.

2. AS specified alone (without a RESERVED or STANDBY value) defines the online storage size of the virtual machine. If the online storage size is changed, or if reserved or standby storage was previously defined, a system-reset-clear function is performed. If reserved or standby storage was previously defined, their sizes are set to zero.
3. RESERVED specified alone (without an AS or STANDBY value) defines the reserved storage size of the virtual machine but does not change the online size or standby size. You can specify a reserved storage size of 0, with or without an AS or STANDBY value. A system-reset-clear function is performed when a RESERVED value is specified. Use of RESERVED is not recommended unless directed by IBM.
4. STANDBY specified alone (without an AS or RESERVED value) takes the standby amount of storage from the reserved storage size or returns it. That is, the RESERVED value is implicitly adjusted opposite to the STANDBY value, so that their sum remains unchanged. When you specify only the STANDBY value, it cannot be set to greater than the sum of the current STANDBY and RESERVED values. No system-reset-clear function is performed when a STANDBY value is specified alone.
5. If more than one option is specified, a new virtual machine configuration is defined containing the respective storage areas:
   • If the AS option is not specified, its value is the previously configured amount. If a virtual machine has changed the amount of its real storage (for example, if the operator of a second-level z/VM system has issued the SET STORAGE command or a Linux guest has issued a chmem command), the response for a DEFINE STORAGE or QUERY VIRTUAL STORAGE command at first level will reflect the updated amount of online configured and STANDBY storage for the virtual machine.
   • If AS is specified and either the RESERVED or STANDBY option is not specified, the respective value is assumed to be zero.
   If any storage size is different from the current configuration, a system-reset-clear function is performed.
6. If the DEFINE STORAGE command performs a system-reset-clear function, it is as though the SYSTEM CLEAR command had been processed. The effects of this system-reset-clear function are described in the description of the CLEAR operand of the SYSTEM command. (See SYSTEM.) Because a system-reset-clear function sets all of your virtual machine storage to binary zeros, you must repeat your IPL procedure to continue operation.
7. A DEFINE STORAGE command that results in a system-reset-clear function will fail when issued while a VMRELOCATE of the virtual machine is in progress.
8. A storage increment is the unit in which an operating system can add or remove storage. If the INCREMENT operand is not specified on the DEFINE STORAGE command, CP determines the increment size. When no standby or reserved storage is defined for the virtual machine, the increment size is set to 1 MB. Otherwise, the increment size must be a power of 2 in megabytes and no less than 1/512th of the AS size, or 1/512th of the sum of the STANDBY plus RESERVED sizes, whichever is larger. If the increment size you specify does not adhere to these rules, CP adjusts the value, along with the AS or INITIAL, RESERVED, and STANDBY sizes, to be multiples of the increment size. The resulting values are displayed in the DEFINE STORAGE command response. For example, in the following command, all values are adjusted:

   DEFINE STORAGE 1M STANDBY 3G RESERVED 543G INCREMENT 3M
   STORAGE = 2G MAX = 15E INC = 2G STANDBY = 4G RESERVED = 544G

   where:

   • The INCREMENT size is adjusted downward to a power of 2, namely 2 MB.
   • The INCREMENT size is adjusted again to 1/512th of the AS size, and made a power of 2; in this case it remains 2 MB.
   • The INCREMENT size is adjusted again to 1/512th of STANDBY + RESERVED, and made a power of 2, specifically 2 GB.
   • The AS size must be adjusted to at least the INCREMENT size, and must be a multiple of the INCREMENT size, specifically 2 GB.
   • The STANDBY size must be adjusted to at least the INCREMENT size, and must be a multiple of the INCREMENT size, specifically 4 GB
   • The RESERVED size must be adjusted to at least the INCREMENT size, and must be a multiple of the INCREMENT size, specifically 544 GB.

   If any adjustment causes the sum of the AS or INITIAL, RESERVED, and STANDBY sizes to exceed the maximum storage size specified for the virtual machine in the CP directory, the command fails and message HCP0094E is issued.
9. If the increment size you specify on the DEFINE STORAGE command using the INCREMENT operand, or the increment size determined by the DEFINE STORAGE command, is less than 128 MB, a second-level z/VM system running in the virtual machine will apply a dynamic storage reconfiguration (DSR) unit size of 128 MB in place of the storage-increment size. When this occurs, the increment size (INC=) displayed using the QUERY STORAGE command on the second-level z/VM system is different from the increment size (INC=) displayed by the QUERY VIRTUAL command first-level.

   Because storage must be added or removed from an operating system's storage configuration in units of the storage-increment size, z/VM's usage of the DSR unit size as the effective storage-increment size, can make a portion of a virtual storage configuration unusable by a second-level z/VM system. In addition, storage values that normally round up to a storage-increment multiple, will be rounded down when insufficient CONFIGURED or STANDBY storage exists to round up.

10. The CONFIGURATION option with more than one extent is primarily for testing. Do not confuse this with loading discontiguous saved segments. Directory limits apply to the sum of the extent sizes.
11. When a second-level z/VM system comes up with the STORE=n IPL parameter in a virtual machine whose storage was defined with a DEFINE STORAGE CONFIGURATION command, and the STORE=n value falls outside of a storage extent, the highest storage address online after IPL is equal to the value that would have resulted if the STORE=n value had been specified.
12. For general usage notes for the DEFINE command, see Usage Notes.
13. An example of using the STANDBY REMAINDER keyword follows:
    • With this directory entry:

      USER ANYONE SECRET18 6G 48G ABCDEFG

      with this command:

      DEFINE STORAGE INITIAL STANDBY REMAINDER RESERVED 16G

      the response would be:

      STORAGE = 6G MAX = 48G INC = 128M STANDBY = 26G RESERVED = 16G

14. A system-reset-clear function is performed when any of these conditions are met:
    • The INCREMENT, INITIAL, or RESERVED operand is specified.
    • The requested AS size is different than the current configured value.
    • The requested configuration has neither STANDBY nor RESERVED storage, but the current configuration has STANDBY storage, RESERVED storage, or both. For example:
      Given the current memory configuration of:

      STORAGE = 16G MAX = 32G INC = 32M STANDBY = 5G RESERVED = 5G

      with this command:

      DEFINE STORAGE 16G

      the response would be:

      STORAGE = 16G
      Storage cleared - system reset

    • The requested configuration has STANDBY storage, but the current configuration has no STANDBY storage. For example:
      Given the current memory configuration of:

      STORAGE = 16G

      with this command:

      DEFINE STORAGE 16G STANDBY 5G

      the response would be:

      STORAGE = 16G MAX = 32G INC = 32M STANDBY = 5G RESERVED = 0
      Storage cleared - system reset

    • The requested configuration's sum of STANDBY and RESERVED storage is different from the current configuration's sum of STANDBY and RESERVED storage. For example:
      Given the current memory configuration of:

      STORAGE = 16G MAX = 32G INC = 32M STANDBY = 5G RESERVED = 5G

      with this command:

      DEFINE STORAGE 16G STANDBY 7G

      the response would be:

      STORAGE = 16G MAX = 32G INC = 32M STANDBY = 7G RESERVED = 0
      Storage cleared - system reset

Responses

STORAGE = nu

STORAGE = nu MAX = nu INC = nu STANDBY = nu RESERVED = nu

STORAGE CLEARED - SYSTEM RESET

Response 4 is displayed when the DEFINE STORAGE command contains the CONFIGURATION operand:

STORAGE = nu
Storage Configuration:
configspec

Extent Specification               Address Range
---------------------------------- -------------------------------------
                 0.ssssssssssssssu 00000000_00000000 - endadres_endadres
   boundaryaddresu.ssssssssssssssu begadres_begadres - endadres_endadres
boundaryadru-nnnnu.ssssssssssssssu begadres_begadres - endadres_endadres

Messages

For the list of general messages for the DEFINE command, see Messages.

Messages:

• HCP093E RESERVED (ressize) exceeds hardware maximum (maxsize)
• HCP093E STANDBY (stbysize) exceeds hardware maximum (maxsize)
• HCP093E STANDBY (stbysize) plus RESERVED (ressize) exceeds hardware maximum (maxsize)
• HCP093E Storage size (storsize) exceeds hardware maximum (maxsize)
• HCP093E Storage size (storsize) plus RESERVED (ressize) exceeds hardware maximum (maxsize)
• HCP093E Storage size (storsize) plus STANDBY (stbysize) exceeds hardware maximum (maxsize)
• HCP093E Storage size (storsize) plus STANDBY (stbysize) plus RESERVED (ressize) exceeds hardware maximum (maxsize)
• HCP094E Storage size (storsize) plus STANDBY (stbysize) plus RESERVED (ressize) exceeds directory maximum (maxsize)
• HCP096E Configuration extent (extent) exceeds maximum allowed on this processor (maxsize). Storage configuration remains unchanged.
• HCP098E Insufficient storage available to satisfy STANDBY request
• HCP099E {STANDBY|RESERVED|INCREMENT} option conflicts with current storage configuration