MODIFY-IO-UNIT

Modify configuration attributes of input/output unit

Component:	BS2000
Functional area:	Device management
Domain:	DEVICE
Privileges:	OPERATING
Routing code:	G

Function

Systems support can modify the configuration attributes of controllers or of devices dynamically using the MODIFY-IO-UNIT command. The path names can be modified for a controller or, for a device, the preferred input/output path. A controller with at least two channel links can be relinked without having to interrupt normal operation.
The timeout setting for devices can also be modified using this command.
The command is only accepted when changing configuration attributes, if dynamic reconfiguration was initiated successfully (see the START-CONFIGURATION-UPDATE command).
If only the timeout settings for devices (TIMEOUT operand) or the PAV settings (operand PAV-PREFERRED-DEVICE) are to be modified, the command may also be entered outside of a dynamic I/O configuration change (i.e. without START-CONFIGURATION-UPDATE command and regardless of the system type). In VM2000 operating mode, the command is only executed in the local system. In VM2000 operating mode the command MODIFY-IO-OPTIONS should be used to modify the timeout settings. 

Format

MODIFY-IO-UNIT

UNIT = *CONTROLLER(...) / *DEVICE(...)
	*CONTROLLER(...)
		|	NAME = <alphanum-name 2..2> / <x-text 4..4>
		|	,PATH = *NO / list-poss(8): *CHANNEL(...)
		|		*CHANNEL(...)
		|			|	CHANNEL-PATH-ID = <x-text 2..3>
		|			|	,CONTROLLER-ADDRESS = <x-text 1..2>
		|			|	,PATH-STATE = *INCLUDED / *REMOVED
		|			|	,PORT-ID = *NONE / <x-text 2..16>
	*DEVICE(...)
		|	NAME = <alphanum-name 2..2> / <x-text 4..4> / *RANGE(...)
		|		*RANGE(...)
		|			|	FIRST-NAME = <alphanum-name 2..2> / <x-text 4..4>
		|			|	,NUMBER-OF-DEVICES = <integer 2..256>
		|	,STATE = *UNCHANGED / *PREFERRED-PATH(...) / *PAV-PREFERRED-DEVICE(...)
		|		*PREFERRED-PATH(...)
		|			|	,PREFERRED-PATH = *NO / *YES(...)
		|			|		*YES(...)
		|			|			|	CHANNEL-PATH-ID = <x-text 2..3>
		|		*PAV-PREFERRED-DEVICE(...)
		|			|	,PAV-PREFERRED-DEVICE = *UNCHANGED / *NO / *YES
,TIMEOUT = *UNCHANGED / *DEFAULT / <integer 16..86400 seconds>

Operands

UNIT = *CONTROLLER(...) / *DEVICE(...)
Specifies whether the configuration attributes of a controller or of a device are to be modified.

UNIT = *CONTROLLER(...)
The configuration attributes of a controller are to be modifies.

NAME = <alphanum-name 2..2> / <x-text 4..4>
Mnemonic device code of the controller.

PATH = *NO / list-poss(8): *CHANNEL(...)
Specifies whether the input/output paths of the controller are to be modified. The default is *NO, i.e. the paths are not modified.

PATH = list-poss(8): *CHANNEL(...)
As many as eight input/output paths via which the controller is to be accessible in the future can be specified in a list. All paths have to be specified, i.e. even if only one path is being added, modified or removed, all the other paths that are to remain unchanged also have to be included in the list.

CHANNEL-PATH-ID = <x-text 2..3>
Specifies the number of the channel to which the controller is linked.

CONTROLLER-ADDRESS = <x-text 1..2>
Specifies the physical controller address.

PATH-STATE = *INCLUDED / *REMOVED
Specifies whether the link between the channel and the controller are available. The default is *INCLUDED, i.e. the connection is available.

PORT-ID = *NONE / <x-text 2..16>
Specifies whether the controller is connected to a channel type FC.
The default is *NONE, i.e. the controller is not connected to a channel type FC.

PORT-ID = <x-text 2..16>
When a controller is connected to a channel type FC the WWPN (World Wide Port Name) of the controller port (16 hexadecimal characters) must be specified. The /SHOW-DEVICE-CONFIGURATION INF=*INNER command for the controller can then be used to output the WWPN.

UNIT = *DEVICE(...)
The configuration attributes of a device are to be modified.

NAME = <alphanum-name 2..2> / <x-text 4..4> / *RANGE(...)
Mnemonic device code. A group of devices can be addressed using the *RANGE operand value. 

NAME = *RANGE(...)
The modifications of the configuration attributes refer to a group of devices. Based on the mnemonics of the first device (FIRST-NAME operand), the mnemonics of the following devices are determined by adding 1 until the maximum number of devices defined in the NUMBER-OF-DEVICES operand is reached. The group can comprise as many as 256 devices. The maximum number has to be chosen so as not to exceed the value FFFF when the mnemonics are calculated.

FIRST-NAME = <alphanum-name 2..2> / <x-text 4..4>
Mnemonic device code of the first device.

NUMBER-OF-DEVICES = <integer 2..256>
Number of devices for which the modification is to be made.

STATE = *UNCHANGED / *PREFERRED-PATH(...) / *PAV-PREFERRED-DEVICE(...)
Specifies whether a particular path should be preferred on input to or output from a device.

STATE = *PREFERRED-PATH(...)
Specifies whether a path is to preferred on input/output if the device can be accessed via different paths.

PREFERRED-PATH = *NO
No path is preferred on input/output.

PREFERRED-PATH = *YES(...)
The path specified in the CHANNEL-PATH-ID operand should be preferred on input/output.

CHANNEL-PATH-ID = <x-text 2..3>
Designates the preferred path (Channel Path Identifier).

STATE = *PAV-PREFERRED-DEVICE(...)
Specifies whether the PAV device is to be preferred on input/output In VM2000 operating mode.

PAV-PREFERRED-DEVICE = *UNCHANGED
The current setting remains unchanged.

PAV-PREFERRED-DEVICE = *YES
The PAV device is preferred on input/output In VM2000 operating mode.

PAV-PREFERRED-DEVICE = *NO
The PAV device is no longer preferred.

TIMEOUT = *UNCHANGED / *DEFAULT / <integer 16..86400 seconds >
Specifies whether the standard timeout value for the devices named in the UNIT operand is to be modified. It applies to disk devices only.
When a controller is specified (UNIT=*CONTROLLER), the settings apply to all devices linked to that controller. The default timeout value only refers to devices and is independent of the input/output paths. If a device is connected through several controllers and if the default timeout values are modified for several of the controllers, then it is always the most recent setting that takes effect for the device.

Changes to default timeout values should only be effective for a limited time and for specific actions (e.g. during the online update of RAID system’s firmware). The default timeout values should then be restored using TIMEOUT= *DEFAULT.

TIMEOUT = *DEFAULT
The system default timeout value is set. The value depends on the device type.

TIMEOUT = <integer 16..86400 seconds >
The new timeout value in seconds. 

Return codes

(SC2)	SC1	Maincode	Meaning
	0	CMD0001	Command processed without errors
	1	NKR0006	Syntax error
	64	CMD0216	Privilege error
1	64	NKR0169	System error
2	64	NKR0169	Wrong parameter
3	64	NKR0169	Dynamic I/O configuration change was rejected
4	64	NKR0169	Dynamic I/O configuration change is not supported
6	64	NKR0169	Internal input/output unit not defined
9	64	NKR0169	Input/output unit not defined
11	64	NKR0169	Path to input/output unit not removed
12	64	NKR0169	Dynamic I/O configuration change was not started
14	64	NKR0169	Configuration change was not performed in the guest system
19	64	NKR0169	Device is not a PAV device
16	128	NKR0169	Another guest system is currently being started
17	128	NKR0169	Another guest system is currently being terminated
18	128	NKR0169	Dynamic I/O configuration change is not supported by one or several guest systems