SWITCH-VM-DEVICES (Remove devices from one VM and add them to another)

/SWITCH-VM-DEVICES removes devices from one VM and adds them to another VM. 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.

If /ADD-VM-DEVICES was used to define a device attribute (using the TYPE operand), this will be retained when /SWITCH-VM-DEVICES is used. For implicitly assigned devices the usage mode is preserved (EXCLUSIVE/SHARED).

The home pubset and other imported pubsets, paging disks and the final console cannot be removed from the monitor VM.

The removed and assigned devices are deleted and noted in the VM definitions of the VMs.

The devices removed from a VM should be detached beforehand in the corresponding guest system with /DETACH-DEVICE.

The devices must be attached in the guest system to which they are assigned so that they can be addressed in it.

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

This command is reserved for the VM2000 administrator.

 

SWITCH-VM-DEVICES

UNITS = *ALL(...) / *PUBSET-DEVICES(...) /
				list-poss(28): *DEVICE-RANGE(...) / <alphanum-name 1..4 with-wild(20)>
	*ALL(...)
		|	CHECK-VM-STATE = *YES / *NO
	*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>
,FROM-VM = <integer 1..99> / <name 1..8>
,TO-VM = <integer 1..99> / <name 1..8>
,FORCE = *NO / *YES

UNITS =
Specifies the devices to be removed from the FROM-VM and assigned to the TO-VM.

UNITS = *ALL(...)
All devices assigned to the FROM-VM are to be removed and reassigned. If a device cannot be removed, the command is not executed for this device. Alias devices and CRD devices are only removed (implicitly).

CHECK-VM-STATE =
Determines whether the command is executed depending on the current status of the FROM-VM.

CHECK-VM-STATE = *YES
The command is only executed if the FROM-VM is in the DOWN or INIT-ONLY state.

CHECK-VM-STATE = *NO
The command is executed regardless of the FROM-VM state.

UNITS = *PUBSET-DEVICES(...)
All devices of the specified pubset are to be removed and reassigned.

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 devices in this name range are to be removed and reassigned.

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, the devices that are not assigned to the FROM-VM are ignored.

On SU /390, alias devices (PAV/DPAV) and CRD devices are ignored additionally.

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)>
Specifies the devices that are to be removed and reassigned by the mnemonic device name.

FROM-VM = <integer 1..99> / <name 1..8>
Identifies by means of a VM index or VM name the VM from which the devices are to be removed.

TO-VM = <integer 1..99> / <name 1..8>
Identifies by means of a VM index or VM name the VM to which the devices are to be assigned.

FORCE =
Specifies the conditions under which devices are to be removed from the FROM-VM.

FORCE = *NO
The device is removed from the FROM-VM if the FROM-VM is in the DOWN or INIT-ONLY state, or if the device is detached in the guest system. However, it is not removed if an input/output is outstanding for the device, if the FROM-VM is in the wait state (after /HOLD-VM) or if the guest system is in the startup phase.
The device configuration of a VM cannot be modified with FORCE=*NO while it is being migrated (VM Migration).

FORCE = *YES
VM2000 tries to remove the device from the FROM-VM, even if it is still in use. If this is not possible, message VMS4003 or VMS4031 is output. The operand should only be used in exceptional circumstances.

  The IO-RESET privilege of the FROM-VM must be noted on SU /390 (see "Initializing a VM").

 

Command return codes

(SC2)   SC1	Main code	Meaning
0 1             0 1             0 2             0 2             0 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 128 128	CMD0001 VMS4035 VMS4180 VMS2306 VMS4229 VMS3002 VMS3040 VMS4000 VMS4006 VMS4007 VMS4021 VMS4022 VMS4026 VMS4030 VMS4031 VMS4064 VMS4069 VMS4081 VMS4085 VMS4086 VMS4143 VMS4144 VMS4190 VMS4195 VMS4223 VMS9005 VMS3042 VMS4003	Command successfully executed No corresponding device found Specified set of devices empty VM definition could not be updated (SU /390) Not all devices of the pubset could be processed Invalid operand value (e.g. *DEVICE-RANGE) or FROM-VM=TO-VM Not processed because of the state of the VM VM not yet created Device is not available Device is not assigned to the virtual machine Device is the last console or main console of the monitor system. Reconfiguration not possible Device is currently being used as a public disk in the monitor system. Reconfiguration not possible VM already has a virtual console The monitor VM may not be assigned a virtual console Device is INOP No channel path available Device is already assigned to the TO-VM Device only removed. Switching incomplete Device not detached in guest system (FORCE=*NO) Device state not known in the guest system (FORCE=*NO) Guest system is in the startup phase (FORCE=*NO) VM is in the wait state (FORCE=*NO) Device is an alias device (PAV/DPAV) Device is a CRD device Command not executed (operand *PUBSET-DEVICES) Command could not be processed or could be processed only partially VM being migrated Device is busy

Guaranteed messages

VMS4003, VMS4008, VMS4021, VMS4022, VMS4026, VMS4030, VMS4031, VMS4064, VMS4069, VMS4081, VMS4085, VMS4086

Only if *PUBSET-DEVICES is specified:  VMS4223, VMS4228, VMS4229.

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

Example

/switch-vm-devices from-vm=system2,to-vm=system3,
                   units=*pubset-devices(pubset=4ivi) —————————————————  (1) 
VMS4008 DEVICE 'FC1E' SWITCHED FROM VIRTUAL MACHINE (2,SYSTEM2) TO VIRTUAL
        MACHINE (3,SYSTEM3)
VMS4008 DEVICE 'FC1F' SWITCHED FROM VIRTUAL MACHINE (2,SYSTEM2) TO VIRTUAL
        MACHINE (3,SYSTEM3)
VMS4228 PUBSET '4IVI' WITH PUBRES DEVICE 'FC1E' SWITCHED FROM VM
        (2,SYSTEM2) TO VM (3,SYSTEM3) —————————————————————————————————  (2)

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

(1)	The VM2000 administrator removes the pubset devices of pubset 4IVI from VM2 and assigns them to VM3.
(2)	VM2000 confirms the old and new assignments.