ADD-VM-DEVICES (Allocate devices to a VM)

/ADD-VM-DEVICES is used to assign individual devices or all devices of a pubset to a VM explicitly. Individual devices are addressed using their mnemonic device names. The devices of a pubset are determined by means of the catalog ID of the pubset or the mnemonic device name of the pubres device.

The assigned devices are noted in the VM definition.

No devices can be assigned explicitly to a VM while it is being migrated (VM Migration).

The devices must be then attached in the guest system so that they can be addressed in this system. A pubset must be imported in the guest system before it is used.

  Alias devices (PAV/DPAV) and CRD devices cannot be assigned explicitly.

This command is reserved for the VM2000 administrator and VM administrators with ADMIN-PRIVILEGES=*MAXIMUM.

ADD-VM-DEVICES

UNITS = *PUBSET-DEVICES(...) /
				list-poss(28): *DEVICE-RANGE(...) / <alphanum-name 1..4 with-wild(20)>
	*PUBSET-DEVICES(...)
		|	PUBSET = *BY-PUBRES-DEVICE(...) / <cat-id 1..4>
		|		*BY-PUBRES-DEVICE(...)
		|			|	UNIT = <alphanum-name 2..2> / <x-text 4..4>
	*DEVICE-RANGE(...)
		|	FROM = <alphanum-name 2..2> / <x-text 4..4>
		|	,TO = <alphanum-name 2..2> / <x-text 4..4>
,VM-IDENTIFICATION = <integer 1..99> / <name 1..8>
,TYPE = *NONE / *SD / *VC

UNITS =
Specifies the devices to be assigned to a VM.

UNITS = *PUBSET-DEVICES(...)
All devices of a pubset are to be assigned to the VM.

See also "Notes on pubset specification in the VM2000 commands" and "Pubset reconfiguration".

PUBSET = *BY-PUBRES-DEVICE(...)
Determines the devices of the pubset by means of the pubres device.

UNIT = <alphanum-name 2..2> / <x-text 4..4>
Mnemonic device name of the pubres device.

PUBSET = <cat-id 1..4>
Catalog ID of the pubset. The pubset must be entered together with its pubres device in the monitor system’s MRS catalog.

UNITS = *DEVICE-RANGE(...)
All the devices in this range of names are to be assigned to the VM.

Device names <x-text 4..4> (in *DEVICE-RANGE) are selected from FROM to TO in hexadecimal order. Otherwise, device names <alphanum-name 2..2> are selected in alphabetical order.

If UNITS are specified with *DEVICE-RANGE or with wildcards, alias devices (PAV/DPAV) and CRD devices are ignored.

Due to the performance reasons, the assignment of a large amount of devices with /ADD-VM-DEVICES (UNITS specification with *DEVICE-RANGE or wildcards) should be avoided on SU x86. The device assignment should be accomplished preferably before the activation of a persistent VM definition or via the SE Manager.

FROM = <alphanum-name 2..2> / <x-text 4..4>
Defines the start of the name range.

TO = <alphanum-name 2..2> / <x-text 4..4>
Defines the end of the name range. The mnemonic device name must be in the same value range (2- or 4-digit mn) as the FROM device name and must be greater than or equal to the FROM device name in ascending order in the value range.

UNITS = <alphanum-name 1..4 with-wild(20)>
Defines the devices to be assigned to the VM.

VM-IDENTIFICATION = <integer 1..99> / <name 1..8>
Identifies the virtual machine by means of a VM index or VM name.

TYPE =
Defines the devices to be assigned to the VM.

TYPE = *NONE
The device is assigned exclusively (usage mode EXCLUSIVE). Exclusively assigned devices are listed in the information commands after the keyword EXCL.

TYPE = *SD
The device is declared as shareable (shared device, usage mode SHARED). The device can be assigned to several VMs at the same time (see also "Shared disk devices"). Shared devices are listed in the information commands after the keyword SHARED.

TYPE = *VC
The device is assigned exclusively as a virtual console (SU /390). It must be appropriately generated (see "Device peripherals on SU /390"). Only one device for each VM can be operated as a virtual console. A virtual console cannot be assigned to the monitor VM. It is not permissible to specify a list in the UNITS operand for TYPE=*VC. Virtual consoles are marked in the information commands of VM2000 with the suffix (VC).

Command return codes

(SC2)   SC1	Main code	Meaning
0 1             0 1             0 1             0 2             0 2             0 2             0 2             0 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 128	CMD0001 CMD0001 VMS4035 VMS4180 CMD0001 VMS2306 VMS4221 VMS4222 VMS3002 VMS3003 VMS4000 VMS4004 VMS4006 VMS4016 VMS4026 VMS4032 VMS4033 VMS4034 VMS4060 VMS4064 VMS4067 VMS4089 VMS4170 VMS4190 VMS4195 VMS4223 VMS9005 VMS3042	Command successfully executed Device or pubset already assigned, no action required No corresponding device found (perhaps only alias devices were specified) Specified set of devices empty Device already implicitly assigned by the guest system, device now explicitly assigned VM definition could not be updated (SU /390) Not all of the pubset’s devices could be assigned Only the pubres device could be assigned Invalid operand value (e.g. *DEVICE-RANGE operand) Invalid combination of operands VM not yet created Device already assigned to a VM Device not available Device cannot be used as a virtual console VM already has a virtual console Device cannot be assigned to several VMs at the same time Maximum number of sharers already reached Device is currently in shared use Only one virtual console possible per VM No channel path available Resource bottleneck in the hardware Virtual console must be assigned with TYPE=*VC I/O execution mode cannot be set to “indirect“ Device is an alias device (PAV/DPAV) Device is a CRD device Command not executed (operand *PUBSET-DEVICES) Command not or only partially processed VM being migrated

Guaranteed messages

VMS4004, VMS4005, VMS4016, VMS4026, VMS4030, VMS4032, VMS4033, VMS4034,
VMS4064, VMS4067, VMS4068, VMS4088, VMS4089, VMS4170

Only if *PUBSET-DEVICES is specified:  VMS4220, VMS4221, VMS4222, VMS4223, VMS4234

Only if UNITS is specified without *DEVICE-RANGE and without wildcards:  VMS4006, VMS4190,
VMS4195

Example

/add-vm-devices unit=*pubset-devices(pubset=4ivw),vm-id=system2 ———————  (1)
VMS4005 DEVICE 'E059' ASSIGNED TO VIRTUAL MACHINE (2,SYSTEM2) —————————  (2) 
VMS4005 DEVICE 'E05A' ASSIGNED TO VIRTUAL MACHINE (2,SYSTEM2)
VMS4005 DEVICE 'E05B' ASSIGNED TO VIRTUAL MACHINE (2,SYSTEM2)
VMS4220 PUBSET '4IVW' WITH PUBRES DEVICE 'E059' ASSIGNED TO VM (2,SYSTEM2)
/add-vm-devices (ch,ci),vm-id=system2 —————————————————————————————————  (3)
VMS4005 DEVICE 'CH' ASSIGNED TO VIRTUAL MACHINE (2,SYSTEM2)
VMS4005 DEVICE 'CI' ASSIGNED TO VIRTUAL MACHINE (2,SYSTEM2)
/add-vm-devices e062,vm-id=system2,type=*sd ———————————————————————————  (4)
VMS4005 DEVICE 'E062' ASSIGNED TO VIRTUAL MACHINE (2,SYSTEM2) (TYPE=SD)
/add-vm-devices cc,vm-id=system2,type=*vc —————————————————————————————  (5)
VMS4005 DEVICE 'CC' ASSIGNED TO VIRTUAL MACHINE (2,SYSTEM2) (TYPE=VC)
/show-vm-attributes information=*units,vm-id=system2
VM-ID        UNITS
 2 SYSTEM2   ASSIGNED BY VM-ADMIN —————————————————————————————————————  (6)
             EXCL:   CC(VC),CH,CI,E059,E05A,E05B
             SHARED: E062

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

(1)	The VM2000 administrator assigns the home pubset devices to VM2.
(2)	VM2000 reports that the devices have been successfully assigned. Pubset 4IVW is entered together with its pubres device E059 in the monitor system’s MRS catalog, and thus identified by VM2000.
(3)	The VM2000 administrator assigns the KVP device pair to VM2.
(4)	A disk device is assigned for shared use with other VMs.
(5)	The VM2000 administrator assigns the KVP console device pair to VM2.
(6)	List of the mnemonic device names that are explicitly assigned to the VM2. EXCL: indicates the devices that are assigned for exclusive use. The (VC) suffix designates a virtual console. The list for SHARED: contains the devices that are assigned for shared use with other VMs.

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

See also the detailed examples for device and pubset management ("Example of peripheral device management" and "Example of pubset management").