DEFINE STORAGE

Config

Notes:

¹ Up to seven additional extents can be specified.

Authorization

Privilege Class: G

Purpose

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

Operands

AS size

specifies the online storage size of your virtual machine.

RESERVED size

specifies the reserved storage size of your virtual machine. See usage note 1.

STANDBY size

specifies the standby storage size of your virtual machine. See usage note 1.

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 an AS value, n must be greater than 0. For a RESERVED or STANDBY value, 0 is also valid.

Table 1. Maximum Input Values for Storage Units
Storage unit	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:

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.
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.
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:

Using decrement to calculate address is explained in the surrounding text.

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

The RESERVED and STANDBY operands allow you to configure reserved and standby storage before you IPL a guest operating system in the virtual machine. This allows the guest to exploit the dynamic storage reconfiguration (DSR) capabilities of the Service Call (SERVC) instruction. For example, the operator of a second-level z/VM system can issue the SET STORAGE command to increase the amount of real storage (if additional storage is available).
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.
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 zero. A system-reset-clear function is performed.
STANDBY specified alone (without an AS or RESERVED value) takes the standby amount of storage from the reserved storage size or returns it. You can specify a standby storage size of zero. No system-reset-clear function is performed.
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 second-level operating system has issued the SERVC instruction to increase the amount of real storage for the operating system (for example, if the operator of a second-level z/VM system has issued the SET STORAGE command), the response for a DEFINE STORAGE or QUERY VIRTUAL STORAGE command at first level will show the new amount of online 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.
In all cases, except for AS specified alone, each size is rounded up to the next higher increment multiple. Increment size is determined from the maximum of the online size and the sum of the reserved and standby sizes. It is a power of two in megabytes and is not less than 1/512th of the maximum size. If the storage size you specify is not an integral multiple of this increment, the size is rounded up to the next higher multiple. The minimum size you can specify is 1M. For AS specified alone, the increment size is 1M. Likewise, for DEFINE STORAGE CONFIG, the increment size is 1M. The total defined storage after rounding cannot exceed the maximum specified in the user directory entry for your virtual machine.
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 detail in the description of the SYSTEM CLEAR command. 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.
If the online storage size is changed and there is standby storage defined, the amount of standby storage is adjusted to keep the total amount available constant. For example, if the online storage was 1024M and 256M was in standby, increasing the online size by 128M to 1152M would reduce the standby size to 128M. If such an adjustment is not possible, the standby size is set to zero. In the previous example, if the online size was increased by 512M to 1536M, the standby size would be set to zero.
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.
z/VM supports any virtual configuration established through the DEFINE STORAGE command. In addition, it supports any real storage configuration set up by a SET STORAGE command issued by a previous instance of z/VM running in the virtual machine. However, if you choose to run z/VM at second level in the same virtual machine where a non-z/VM operating system was previously running, it is suggested that you log off or issue DEFINE STORAGE commands to trigger a SYSTEM RESET CLEAR (to reestablish the original storage configuration) before you IPL z/VM.
The DEFINE STORAGE command fails if issued when VMRELOCATE is in progress. When it fails the DEFINE STORAGE command causes a SYSTEM RESET or a software-initiated Dynamic Storage Reconfiguration request (specifically, an Unassign Storage or Detach Element request).
For general usage notes for the DEFINE command, see Usage Notes.

Responses

Response 1:

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

where:

STORAGE = nu: specifies the size of online (assigned) virtual machine storage.
MAX = nu: specifies the maximum size of virtual machine storage as defined in the user directory entry for the virtual machine.
INC = nu: specifies the size of the virtual machine storage increment.
STANDBY = nu: specifies the amount of virtual machine storage in standby state that is available to be configured online.
RESERVED = nu: specifies the amount of virtual machine storage in reserved state that can be defined online or as standby.

Response 2:

STORAGE CLEARED - SYSTEM RESET

is issued whenever you change your virtual machine storage size.

Response 3: (when CONFIGURATION was specified)

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

where:

STORAGE = nu

specifies the size of online (assigned) virtual machine storage, including the configuration extents.

configspec

is the storage configuration specification input used on the DEFINE STORAGE CONFIGURATION command that defines the current storage configuration.

Extent Specification

specifies the information supplied by the QUERY VIRTUAL STORAGE command. Each configuration extent is listed on a separate line:

boundaryaddresu
boundaryadru: is the boundary address as specified in the DEFINE STORAGE CONFIGURATION command, where u is the 1-character storage unit suffix.
ssssssssssssssu: is the extent size, 1 - 14 decimal digits followed by the 1-character storage unit suffix.
nnnnu: is the decrement specified in DEFINE STORAGE CONFIGURATION used to modify the extent start boundary address, expressed as 1 - 4 decimal digits followed by the 1-character storage unit suffix (which must be a smaller storage unit than that used for the start address it modifies). The decrement is subtracted from the base start boundary specification to determine the effective extent start boundary address.

Address Range

specifies the extent information converted to beginning and ending addresses:

begadres_begadres: is the 16-digit extent start address expressed in hexadecimal (always ends in X'00000', a megabyte boundary). Underscores are used for readability if SET UNDERSCORE ON has been issued.
endadres_endadres: is the 16-digit extent end address expressed in hexadecimal (always ends in X'FFFFF', one less than a megabyte boundary). Underscores are used for readability if SET UNDERSCORE ON has been issued.

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 RESERVED (ressize) exceeds directory maximum (maxsize)
HCP094E STANDBY (stbysize) exceeds directory maximum (maxsize)
HCP094E STANDBY (stbysize) plus RESERVED (ressize) exceeds directory maximum (maxsize)
HCP094E Storage size (storsize) exceeds directory maximum (maxsize)
HCP094E Storage size (storsize) plus RESERVED (ressize) exceeds directory maximum (maxsize)
HCP094E Storage size (storsize) plus STANDBY (stbysize) exceeds directory 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} option conflicts with current storage configuration