MODIFY-VM-DEVICE-USAGE (Modify usage mode of devices of a VM)

/MODIFY-VM-DEVICE-USAGE changes the usage mode of VM devices, see "Usage mode of a device". 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 SHARED usage mode can be set for exclusively assigned devices if the device permits this (disk devices, for example, with the exception of the IPL device of the VM, emulated devices and FastDPAV alias devices (SU /390)).

The EXCLUSIVE usage mode can be set for shared devices which are assigned to only one VM at the time of command execution (SHARED usage mode with direct I/O, SH(D)).

The change of usage mode is noted in the VM definition.

This command does not change the attributes of the device (see "MODIFY-VM-DEVICE-ATTRIBUTES (Modify device attributes)").

Alias devices (PAV/DPAV) always have the same usage mode as the associated base device. The usage mode of a base device can be changed using this command (the usage mode of its alias devices thus changes). The command cannot be used explicitly for an alias device.

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

MODIFY-VM-DEVICE-USAGE

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>
,USAGE = *EXCLUSIVE / *SHARED

UNITS =
Specifies the VM devices whose usage mode is to be changed.

UNITS = *PUBSET-DEVICES(...)
The usage mode is to be modified for all devices of a pubset.

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(...)
Defines the start of the name range.

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)>
Specifies the devices whose usage mode is to be changed.

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

USAGE =
Specifies the new usage mode.

USAGE = *EXCLUSIVE
The device is assigned to the VM exclusively. Exclusively assigned devices are listed in the outputs of the VM2000 information commands under the keyword EXCL.

USAGE = *SHARED
The device is declared as shareable (SHARED), see also "Usage mode of a device". Shared devices are listed in the outputs of the VM2000 information commands under the keyword SHARED.

Command return codes

(SC2)   SC1	Main code	Meaning
0 1             0 1             0 1             0 2             0 2             0 64 64 64 64 64 64 64 64 64 64 128	CMD0001 CMD0001 VMS4035 VMS4180 VMS2306 VMS4231 VMS3002 VMS4000 VMS4006 VMS4007 VMS4032 VMS4172 VMS4190 VMS4195 VMS4223 VMS9005 VMS3042	Command successfully executed No action required No corresponding device found (perhaps only alias devices were specified) Specified set of devices empty VM definition could not be updated (SU /390) Usage mode not changed for all devices of the pubset Invalid operand value (e.g. *DEVICE-RANGE operand) VM not yet created Device not available Device is not assigned to the virtual machine Device cannot be assigned to several VMs at the same time Device is assigned to several VMs 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

VMS4032, VMS4172

Only if *PUBSET-DEVICES is specified:  VMS4223, VMS4230, VMS4231

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

Example

/modify-vm-device-usage vm-id=system2,usage=*shared
                         units=*pubset-devices(pubset=vm04) ———————————  (1)
VMS4230 DEVICE USAGE OF PUBSET 'VM04' WITH PUBRES DEVICE 'D4' MODIFIED

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

(1)	The VM2000 administrator wants to set the usage mode SHARED for the devices of the pubset VM04.

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