VM2000 V12.0 (en)

&pagelevel(4)&pagelevel

/CREATE-VM creates and initializes a VM in VM2000.

During the initialization process, the following attributes and resources are assigned to the VM:

VM index and VM name (identification of the VM)
Main memory size of the VM
Minimum and maximum main memory size of the VM for main memory reconfiguration
Location of the VM in the main memory of VM2000 (SU /390)
(Member) CPU quota and maximum CPU utilization of the VM
Maximum I/O utilization of the VM (SU /390)
Adding of the VM to a VM group (SU /390)
Assignment of the VM to a CPU pool
Multiprocessor level of the VM
The password for administration
Range of commands available to VM2000 and VM administrators
Privileges of the VM
We recommend initializing a VM with IO-PRIORITY=*NO and IO-RESET=*NO (i.e. without these privileges) and only assigning the privileges with/MODIFY-VM-ATTRIBUTES.
Settings for controlling the real CPU (SU /390)
Monitor job variable for monitoring the VM
PERSISTENT attribute

After the command has been executed successfully, the VM has state INIT-ONLY.

Depending on the PERSISTENT attribute,a persistent or non-persistent VM definition is configured for the VM.

On SU x86 a VM’s firmware component is started when the VM is initialized. Despite the INIT-ONLY status, the VM already utilizes a minimal CPU capacity.

The monitor VM is automatically initialized when VM2000 is initialized. Its attributes and resources are configured when VM2000 is installed (see chapter "Installing VM2000").

This command is reserved for the VM2000 administrator.

CREATE-VM

MEMORY-SIZE = <integer 1..1048576>(DIMENSION = MEGABYTE / GIGABYTE)
,MIN-MEMORY-SIZE = STD / <integer 1..1048576>(DIMENSION = MEGABYTE / *GIGABYTE)
,VM-NAME = *STD / <name 1..8>
,CPU-QUOTA = STD / <fixed 0.01..99.99> / BY-VM-GROUP(...)
	*BY-VM-GROUP(...)
		\|	VM-GROUP-NAME = <name 1..8>
		\|	,MEMBER-CPU-QUOTA = *STD / <fixed 0.01..99.99>
,MAX-CPU-UTILIZATION = 100 / <fixed 0.01..100.00>
,MAX-IO-UTILIZATION = 100 / <integer 1..100>
,CPU-POOL-NAME = STD / STDPOOL / <name 1..8>
,PASSWORD = *NONE / <c-string 1..8> / <x-string 1..16>
,PROCESSOR = MONO / BI / TRIPLE / QUADRO / OCTO / MAXIMUM / *EXTRA-AND-NORMAL /
						<integer 1..32>
,LOCATION = ANY / BEFORE-VM(...) / AFTER-VM(...) / MEMORY-END / <x-text 1..8>(...)
	*BEFORE-VM(...)
		\|	VM-IDENTIFICATION = <integer 2..99> / <name 1..8>
	*AFTER-VM(...)
		\|	VM-IDENTIFICATION = <integer 1..99> / <name 1..8>
	<x-text 1..8>(...)
		\|	DIMENSION = BYTE / MEGABYTE
,VM-INDEX = *ANY / <integer 1..99>
,ADMIN-PRIVILEGES = STD / MINIMUM / *MAXIMUM
,PRIVILEGES = *PARAMETERS(...)
	*PARAMETERS(...)
		\|	IO-RESET = NO / YES
		\|	,IO-PRIORITY = NO / YES
		\|	,AUTO-SNAP-ASSIGNMENT = YES / NO
		\|	,ASSIGN-BY-GUEST = NO / YES(...)
		\|		*YES(...)
		\|			\|	SET-NAME = STDSET / ALL / EXCEPT(...) / list-poss(8): <name 1..8> / STDSET
		\|			\|		*EXCEPT(...)
		\|			\|			\|	SET-NAME = list-poss(8): <name 1..8> / *STDSET
,VM-ACTIVE-IDLE= NO / AT-DEDICATED-CPUS
,MONJV= *NONE / <filename 1..54 without-gen-vers>
,JV-PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> / <integer -2147483647..2147483648>
,MAX-MEMORY-SIZE = STD / <integer 1..1048576>(DIMENSION = MEGABYTE / *GIGABYTE)
,PERSISTENT = NO / YES

MEMORY-SIZE = <integer 1..1048576>(DIMENSION = *MEGABYTE / *GIGABYTE)
Size of main memory for the appropriate VM up to a size of 1 Tbyte
(terabyte; 1 Tbyte = 1024 Gbytes = 1 048 576 Mbytes).

On SU x86 a small amount of a VM’s main memory is required for the firmware component. The main memory of a VM must be at least 1024 Mbytes in size. The value must be a multiple of 2 Mbytes.

MIN-MEMORY-SIZE = *STD / <integer 1..1048576>(DIMENSION = *MEGABYTE / *GIGABYTE)
Minimum size of the main memory for the relevant VM when main memory is reconfigured. The default is the size of the main memory for the VM as defined by MEMORY-SIZE.

On SU x86 the main memory of a VM must be at least 1024 Mbytes in size. The value must be a multiple of 2 Mbytes.

VM-NAME =
Name of the new VM. This identifies the VM in addition to the VM index. The VM name must be unique on the Server Unit.

VM-NAME = *STD
Standard VM name. VM00nn is assigned as the standard name, nn being the VM index (nn=01..99).

VM-NAME = <name 1..8>
VM name assigned by the VM2000 administrator. A VM name corresponding to the standard name of another VM is not permissible (e.g VM-NAME=VM0002,VM-INDEX=5).

See also the general conditions for SU x86 in paragraph “Recommendations for the definition and use of VM names” in section "Initializing a VM".

CPU-QUOTA = *STD / <fixed 0.01..99.99> / *BY-VM-GROUP(...)
CPU quota of the VM. The default value is 1 (the VM is not added to any VM group).

CPU-QUOTA = *STD / <fixed 0.01..99.99>
CPU quota of the VM which is not (yet) added to a VM group when it is created. Determines the VM’s own share of the CPU capacity of the CPU pool in comparison to the VM groups and the other VMs which have not been added to a VM group (see "Planning distribution of the CPU capacity to the VMs").

CPU-QUOTA = *BY-VM-GROUP(...)
The VM is added to a VM group at creation time (SU /390).

VM-GROUP-NAME = <name 1..8>
Name of the VM group to which the VM is added.

MEMBER-CPU-QUOTA = *STD / <fixed 0.01..99.99>
Member CPU quota of the VM which is added to a VM group at creation time. This determines the VM’s own CPU share in comparison to the other VMs in the VM group (see "Operating VM groups (SU /390)"). The default value is 1.

MAX-CPU-UTILIZATION = 100 / <fixed 0.01..100.00>
Maximum CPU utilization of the VM (see "Planning distribution of the CPU capacity to the VMs").

If the VM belongs to a VM group, its maximum CPU utilization is also restricted by the “maximum CPU utilization of the VM group” (see "Operating VM groups (SU /390)").

MAX-IO-UTILIZATION = 100 / <integer 1..100>
Maximum I/O utilization of the VM (SU /390, see "Use of IORM in VM2000 operation").

CPU-POOL-NAME =
Determines the CPU pool to which the VM is assigned. Every VM is always assigned to precisely one CPU pool.

On SU x86 the CPU pool must possess at least one attached real CPU.

The CPU-QUOTA operand determines the (individual) VM’s or VM group’s own CPU share in comparison to the other VMs or VM groups which are assigned to the CPU pool (see "Scheduling procedure").

CPU-POOL-NAME = *STD
When a (single) VM is initialized (CPU-QUOTA = *STD / <fixed 0.01..99.99>), it is assigned to the standard CPU pool.

When the VM is assigned to a VM group (CPU-QUOTA = *BY-VM-GROUP(...)), it is assigned to the CPU pool of the VM group.

CPU-POOL-NAME = *STDPOOL / <name 1..8>
Name of the CPU pool to which the VM is assigned.

If the VM is added to a VM group (CPU-QUOTA=*BY-VM-GROUP(...) operand), it may only be assigned to the CPU pool of the VM group.

PASSWORD =
Password controlling access authorization in /BEGIN-VM-DIALOG. The password can be up to 8 bytes long.

PASSWORD = *NONE
No password is necessary.

PASSWORD = <c-string 1..8>
Password in character form.

PASSWORD = <x-string 1..16>
Password in hexadecimal form. The password comprising zeros only (X'00..00') is ignored.

PROCESSOR =
This defines the multiprocessor level of the VM (see "Virtual CPUs").

PROCESSOR = *MONO
A VM with one virtual CPU is set up.

PROCESSOR = *BI
A VM with two virtual CPUs is set up.

PROCESSOR = *TRIPLE
A VM with three virtual CPUs is set up.

PROCESSOR = *QUADRO
A VM with four virtual CPUs is set up.

PROCESSOR = *OCTO
A VM with eight virtual CPUs is set up.

PROCESSOR = *MAXIMUM
A VM with the maximum possible number of virtual CPUs is created. The maximum possible number of virtual CPUs matches the number of real normal CPUs which are available for VM2000 operation, see "Real CPUs".
On SU /390, the maximum number of virtual CPUs is 16.

PROCESSOR = *EXTRA-AND-NORMAL
A VM is configured with as many virtual CPUs as normal CPUs and extra CPUs are available for VM2000 operation.
On SU /390, up to 16 virtual CPUs are possible.

A VM with this number of CPUs can utilize the maximum CPU capacity, including the CPU capacity of the attached extra CPUs. For a Server Unit without extra CPUs this value is the same as the value of PROCESSOR=*MAXIMUM.

PROCESSOR = <integer 1..32>
A VM is set up with the number of virtual CPUs specified here. A value less than or equal to the value of PROCESSOR=*MAXIMUM is permissible.

LOCATION =
Specifies the location of the VM in the main memory of VM2000 (SU /390).

LOCATION = *ANY
The location is selected by VM2000.

LOCATION = *BEFORE-VM(VM-IDENTIFICATION = <integer 2..99> / <name 1..8>)
Specifies the VM before which the new VM is to be located.

LOCATION = *AFTER-VM(VM-IDENTIFICATION = <integer 1..99> / <name 1..8>)
Specifies the VM after which the new VM is to be located.

LOCATION = *MEMORY-END
The new VM is to be located at the end of the VM2000 main memory.

LOCATION = <x-text 1..8>(DIMENSION = *BYTE / *MEGABYTE)
Specifies the address with the dimension. The address must be a multiple of 1 Mbyte. Permissible range of values: 00000000..7FF00000 (hexadecimal digits). If necessary, the address is padded with leading zeros.

VM-INDEX =
The VM index.

VM-INDEX = *ANY
The VM index is assigned by VM2000.

VM-INDEX = <integer 1..99>
Specifies the VM index.
The largest possible VM index depends on the hardware. /SHOW-VM-RESOURCES INFORMATION=*CONFIGURATION provides the necessary information.

If VM-INDEX=*ANY is specified and the VM migrated at a later point (VM Migration), the VM will receive any free VM index on the target SU. Otherwise, the specified (fixed) VM index must be available on the target SU as well.

ADMIN-PRIVILEGES =
Defines the command/function range for the VM2000 administrator and the VM administrator (see "Extending and restricting the range of commands/functions").

ADMIN-PRIVILEGES = *STD
Standard command/function range.

ADMIN-PRIVILEGES = *MINIMUM
Restricted command/function range for the VM2000 administrator.

	The operand value `*MINIMUM` only be specified on SU /390 (`/CREATE-VM` in the configuration file of the monitor VM or when the monitor system is started up in dialog mode).
	On SU x86, the command/functional scope for the VM2000 administrator can only be restricted with `/MODIFY-VM-ATTRIBUTES`.

ADMIN-PRIVILEGES = *MAXIMUM
Extended command/function range for the VM administrator.

This operand value is ignored in the configuration file for the monitor VM. ADMIN-PRIVILEGES=*STD is used.

PRIVILEGES = *PARAMETERS(...)
Describes privileges of the VM (see "Initializing a VM").

IO-RESET = *NO / *YES
Specifies on SU /390 whether the channels are reset in the hardware for this VM at /START-VM or when the guest system is restarted or the channels reconfigured.

IO-PRIORITY = *NO / *YES
Specifies on SU /390 whether a waiting virtual CPU of the VM is executed again on a real CPU by the VM2000 hypervisor immediately after the end of pending input/output for this VM.

The total number of virtual CPUs of all the VMs with this privilege may not be greater than the number of the real normal CPUs of the Server Unit.

AUTO-SNAP-ASSIGNMENT = *YES / *NO
Determines whether the guest system on the VM may implicitly assign itself snap units for Snapsets without the VM and device being assigned the ASSIGN-BY-GUEST privilege or attribute.

ASSIGN-BY-GUEST = *NO / *YES(...)
Specifies whether devices can also be implicitly assigned to this VM by the guest system (*YES).
Alternatively (*NO), the devices must be assigned explicitly to the VM by the VM or VM2000 administrator.

SET-NAME =
Determines the assignment sets from which the guest system may implicitly assign devices to the VM. With /CREATE-VM, up to 8 assignment sets can be assigned to the VM by means of explicit list specification. Additional assignment sets (up to maximum of 28) can be assigned to the VM with /MODIFY-VM-ATTRIBUTES.

SET-NAME = *STDSET / list-poss (8): <name 1..8> / *STDSET
Explicit specification of the assignment sets.
The explicit list of the assignment sets can be extented up to 28 assignment sets with /MODIFY-VM-ATTRIBUTES.

SET-NAME = *ALL
All existing and future assignment sets.

SET-NAME = *EXCEPT(SET-NAME = list-poss (8): <name 1..8> / *STDSET)
All existing and future assignment sets with the exception of those which are specified with SET-NAME.
The explicit exception list of the assignment sets can be extented up to 28 assignment sets with /MODIFY-VM-ATTRIBUTES.

VM-ACTIVE-IDLE =
Determines on SU /390 whether, in the event of fixed CPU assignment (dedicated CPUs), a VM still retains control over a real CPU if the VM’s virtual CPU which runs on this is inactive (interruptible wait state), see "Initializing a VM".

VM-ACTIVE-IDLE = *NO
The VM leaves control over the real CPU if the VM’s virtual CPU which runs on this becomes inactive (interruptible wait state, "Idle").

VM-ACTIVE-IDLE = *AT-DEDICATED-CPUS
The VM retains control over the real CPU even if the VM’s virtual CPU which runs on this is inactive (interruptible wait state, "Idle"). This idle time is then indicated in the VM2000 accounting records, with /SHOW-VM-STATUS (VM-ACTIVE output column) and in the VM2000 report of openSM2 as a time in which the VM actively uses the real CPU.

With fixed CPU assignment, VM-ACTIVE-IDLE=*AT-DEDICATED-CPUS is only effective if the VM’s maximum CPU utilization is not restricted.

MONJV =
Defines a MONJV for monitoring the VM (see "Monitoring a VM with job variables (MONJV)").

MONJV = *NONE
No MONJV is defined.

MONJV = <filename 1..54 without-gen-vers>
The specified MONJV is supplied with data by VM2000; therefore, the sender of the command must have write permission for the specified MONJV. If no catalog ID or user ID is specified in the file name, VM2000 completes the file name, in accordance with the runtime environment of the sender of the command.
If the specified file name does not refer to an existing job variable, VM2000 creates the MONJV as shareable and without a password.

JV-PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> / <integer ...>
Password of the MONJV for checking access authorization. The input field is automatically blanked in the guided dialog. The value input is not logged.

This operand is only evaluated if a previously created job variable was specified with MONJV.

MAX-MEMORY-SIZE = *STD / <integer 1..1048576>(DIMENSION = *MEGABYTE / *GIGABYTE)
Maximum size of the main memory for the VM when main memory is reconfigured. The default value is twice the size of the VM’s main memory which is predefined by MEMORY-SIZE. Take note of the information in section "Initializing a VM".

This operand has no effect for SU /390.

The value must be a multiple of 2 Mbytes for SU x86.

PERSISTENT =
Determines whether a persistent VM is to be created.

PERSISTENT = *NO
A VM is created which is not persistent.
A non-persistent VM definition is created for the VM.

PERSISTENT = *YES
A persistent VM is created.
A persistent VM definition is created for the VM. The guest system on the VM is not started automatically (AUTO-IPL=*NO). The specifications for the automatic start (when the VM definition is activated with /ACTIVATE-VM-DEFINITION) can be modified with /MODIFY-VM-ATTRIBUTES after the VM has been initialized (see "MODIFY-VM-ATTRIBUTES (Modify attributes of a VM)").

Command return codes

(SC2) SC1	Main code	Meaning
0 1 0 2 0 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64	CMD0001 CMD0001 CMD0001 VMS2101 VMS3002 VMS2305 VMS2310 VMS2311 VMS2332 VMS3034 VMS3035 VMS4000 VMS4010 VMS4011 VMS4012 VMS4013 VMS4014 VMS4015 VMS4071 VMS4093 VMS4200 VMS4340 VMS4400 VMS4422 VMS4600 VMS4612	Command successfully executed No action required Decimal specifications rounded to 2 decimal places VM2000 shutdown in progress Invalid operand value VM definition could not be created Generation of the VM definition not confirmed in the expected time Maximum permitted number of VM definitions already reached Storage for VM definitions cannot be reached (SU /390) ADMIN-PRIVILEGES=MIN only permissible for the monitor VM IO-PRIORITY cannot be set (total of virtual CPUs with privilege too high) VM not yet created (BEFORE-VM or *AFTER-VM operand) Maximum permitted number of VMs already reached Requested memory size or location not available Requested memory size too small VM name not available SVP error VM ID already reserved Invalid memory size or location Invalid memory size Assignment set not yet created MONJV could not be accessed VM group not yet created VM not assigned to the CPU pool of the VM group CPU pool not yet created No attached CPU is assigned to the CPU pool (SU x86)

Guaranteed messages

VMS4425, VMS4615

Example

/create-vm memory-size=1024,vm-name=system2,cpu-quota=30,            processor=*mono,password=c'sys2',monjv=jv-sys2——————————————  (1)
VMS3050 VIRTUAL MACHINE (2,SYSTEM2) CREATED ———————————————————————————  (2)
VMS4615 VIRTUAL MACHINE (2,SYSTEM2) ASSIGNED TO CPU POOL '*STDPOOL' /show-vm-attributes vm-id=system2——————————————————————————————————————  (3)
CPU-POOL(P)
VM-ID        VM-GROUP(G)  CPU-Q   MAX-U   PROC   MEM-SIZE  MAX-IO
2 SYSTEM2   *STDPOOL(P)  30.00  100.00     1      1024 MB (100)
VM-ID        STATE           VERSION PER ADMIN PRIV
2 SYSTEM2   INIT-ONLY               NO  NO    AS
/show-vm-attributes vm-id=system2,information=*monjv———————————————————  (4)
VM-ID        VM-MONJV 2 SYSTEM2  :4IVR:$TSOS.JV-SYS2
/show-jv jv-contents=jv-sys2 ——————————————————————————————————————————  (5)
$I 0    4IVR    V0292021-02-09110022 SYSTEM2 002NONE

-----------------------------------------------------------------------------------------------------------------

(1)	A VM is initialized by the VM2000 administrator. The VM receives the VM name `SYSTEM2`. It is created as a mono-VM. The size of main memory of the VM is 1024 Mbytes, and the CPU quota is 30. The password `SYS2` is defined for dialog access. The MONJV `jv-sys2` is used to monitor the VM.
(2)	VM2000 reports the initialization of the VM. The VM is assigned to the standard CPU pool.
(3)	The VM2000 administrator requests the attributes and status of VM2.
(4)	The VM2000 administrator queries the complete name of the MONJV.
(5)	The BS2000 command shows the contents of the MONJV (Column 1: Status `$I` , Column 17: Identifier `V`); the guest system is not loaded (Columns 82-86: `NONE` ).

-----------------------------------------------------------------------------------------------------------------

See also the detailed "Example of operating VM groups" and the detailed "Example of managing CPU pools".

Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly

CREATE-VM (Initialize a VM)

Command return codes

Guaranteed messages

Example