REMOVE-VM-DEVICES (Deallocate devices from VM)

/REMOVE-VM-DEVICES is used to remove devices explicitly from a VM that were previously assigned explicitly or implicitly. 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 home pubset and other imported pubsets, paging disks and the final console cannot be removed from the monitor VM.

The deallocated devices are removed from the VM definition.

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

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

REMOVE-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>
,VM-IDENTIFICATION = *CURRENT / <integer 1..99> / <name 1..8>
,FORCE = *NO(...) / *YES
	*NO(...)
		|	WAIT-FOR-UNASSIGN = *NO / *YES

UNITS =
Defines the devices to be removed from the VM.

UNITS = *ALL(...)
All the devices assigned to this VM are removed. Alias devices (PAV) and CRD devices are also removed. If a device cannot be removed when *ALL is specified, the command is not executed for this device.

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

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

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

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

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

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 name range are to be removed from 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, the devices that are not assigned to the 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)>
Defines the devices which are to be removed from the VM.

VM-IDENTIFICATION =
Identification of the virtual machine.

VM-IDENTIFICATION = *CURRENT
The VM identification assigned previously by means of /BEGIN-VM-DIALOG is used.

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

FORCE =
Specifies the conditions under which devices are removed.

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

WAIT-FOR-UNASSIGN = *NO
If the device is still attached in the guest system, it remains assigned explicitly to the VM.

WAIT-FOR-UNASSIGN = *YES
If the device is still attached in the guest system, it remains assigned implicitly to the VM until the BS2000 command /DETACH-DEVICE releases this device implicitly in the guest system. The explicit assignment of the device to the VM is canceled.

FORCE = *YES
VM2000 tries to remove the device from the 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.
 On SU /390 the IO-RESET privilege of the VM must be noted (see "Initializing a VM").

 

Command return codes

(SC2)   SC1	Main code	Meaning
0 1             0 1             0 1             0 2             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 128 128	CMD0001 CMD0001 VMS4035 VMS4180 CMD0001 VMS2306 VMS4226 VMS4235 VMS4237 VMS3002 VMS3040 VMS4000 VMS4006 VMS4007 VMS4021 VMS4022 VMS4031 VMS4085 VMS4086 VMS4143 VMS4144 VMS4190 VMS4195 VMS4223 VMS9005 VMS3042 VMS4003	Command successfully executed Pubset not assigned to VM (VMS4236) No corresponding device found Specified set of devices empty Device remains assigned implicitly to the VM until it is detached in the guest system (VMS4087) VM definition could not be updated (SU /390) Not all of the pubset’s devices could be removed Some devices of the pubset remain assigned implicitly to the VM (VMS4087) Only the pubres device could be removed Invalid operand value (e.g. *DEVICE-RANGE operand) 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 Device is INOP 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 only be partially processed VM being migrated Device is busy

Guaranteed messages

VMS4003, VMS4009, VMS4021, VMS4022, VMS4031, VMS4085, VMS4086, VMS4087

Only if *PUBSET-DEVICES is specified:  VMS4223, VMS4225, VMS4226, VMS4235, VMS4236, VMS4237

Only if UNITS is specified without *DEVICE-RANGE and without wildcards: VMS4006, VMS4007 (but not in the case of UNITS specification with *PUBSET-DEVICES), VMS4190, VMS4195

Example

/remove-vm-devices vm-id=system2,units=*pubset-devices(pubset=4ivl) ———  (1)
VMS4085 DEVICE 'FC1C' STILL ATTACHED IN GUEST SYSTEM. DEVICE NOT REMOVED
VMS4085 DEVICE 'FC1D' STILL ATTACHED IN GUEST SYSTEM. DEVICE NOT REMOVED
VMS4223 VM2000 COMMAND /REMOVE-VM-DEVICES FOR PUBSET SPECIFIED BY PUBRES
        DEVICE OR CATID '4IVL' REJECTED ———————————————————————————————  (2)
/remove-vm-devices units=*pubset-devices(pubset=4ivl),vm-id=system2,
                   force=*no(wait-for-unassign=*yes) ——————————————————  (3)
VMS4087 DEVICE 'FC1C' REMAINS ASSIGNED TO VM (2,SYSTEM2) UNTIL DETACH IN
        GUEST SYSTEM HAS BEEN DONE
VMS4087 DEVICE 'FC1D' REMAINS ASSIGNED TO VM (2,SYSTEM2) UNTIL DETACH IN
        GUEST SYSTEM HAS BEEN DONE
VMS4235 SOME DEVICES OF PUBSET '4IVL' WITH PUBRES DEVICE 'FC1C' REMAIN
        ASSIGNED TO VM (2,SYSTEM2) UNTIL DETACH IN GUEST SYSTEM HAS BEEN DONE
/remove-vm-devices units=(ch,ci,990f),vm-id=system2, ——————————————————  (4)
VMS4009 DEVICE 'CH' REMOVED FROM VIRTUAL MACHINE (2,SYSTEM2)
VMS4009 DEVICE 'CI' REMOVED FROM VIRTUAL MACHINE (2,SYSTEM2)
VMS4009 DEVICE '990F' REMOVED FROM VIRTUAL MACHINE (2,SYSTEM2)

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

(1)	The VM2000 administrator wants to remove the pubset devices of pubset 4IVL from VM2.
(2)	The devices cannot be removed because they are still attached in the guest system.
(3)	By means of the FORCE=*NO(WAIT-FOR-UNASSIGN=*YES) operand the VM2000 administrator changes explicit assignment to implicit assignment (FORCE=*YES should only be used in exceptional cases).
(4)	Further devices are removed from VM2.

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

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