Description

The IOS Offline Device Service macro provides the interface for authorized code to mark a device offline and in use by a system component.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state and key 0.
Dispatchable unit mode:	Task mode.
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts.
Locks:	No locks held.
Control parameters:	None

Programming requirements

None.

Restrictions

The caller may not hold any locks.
The caller is required to pin the UCB for the device before invoking the IOSODS macro service. Pinning the UCB will insure that the proper identification of the user of the device will be displayed if the installation should try the dynamically delete it.
Issuers of the IOSODS macro service must provide recovery and resource termination managers to insure that the device is freed for use by other applications in case of an unexpected failure or cancellation of the address space.

Input register information

None.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: Reason code
1–14: Unchanged
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-15: Unchanged

Performance implications

None.

Syntax

The standard form of the IOSODS macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␣	One or more blanks must precede IOSODS.

IOSODS

␣	One or more blanks must follow IOSODS.

ON	Default: None.

[,WLMPAVSUSPEND]	This function is disabled.

OFF	Default: None.

[,WLMPAVRESTORE]	This function is disabled.

,DEVN=`devn`	`devn`: RS-type name or address in register (2) - (12).

[,DEVNCHAR=`devnchar`]	`devnchar`: RS-type address or register (2) - (12).

[SCHSET=`schset`\|0]	Default: 0

[,LDEVNCHAR=`ldevnchar`]	`ldevnchar`: RS-type address or register (2) - (12).

[,RETCODE=`retcode`]	`retcode`: RS-type name or register (2) - (12).

[,RSNCODE=`rsncode`]	`rsncode`: RS-type name or register (2) - (12).

[,PLISTVER={`plistver` \| MAX \| IMPLIED_VERSION}]	Default: IMPLIED_VERSION

Parameters

The parameters are explained as follows:

The following is a set of mutually exclusive keywords. This set is required; only one keyword must be specified.

ON

Keyword that indicates the input device number is to be marked as offline and in use by a system component.

,WLMPAVSUSPEND: Optional keyword that indicates that the Work Load Manager dynamic alias tuning capability for the device (if applicable) will be suspended. Note that it is up to the user to restore this capability through an IOSODS OFF request with the WLMPavRestore keyword specified. This function is currently disabled.
Default: None.

OFF

Keyword that indicates the input device number is no longer to be marked as offline and in use by a system component.

,WLMPAVRESTORE: Optional keyword that indicates that the Work Load Manager dynamic alias tuning capability for the device (if applicable) will be restored. Note that it is up to the user to restore this capability through an IOSODS ON request with the WLMPavSuspend keyword specified. This function is currently disabled.
Default: None.

This ends the of set of mutually exclusive required keywords.

,DEVN=devn: The name (RS-type), or address in register (2) - (12), of a required halfword input that specifies the device number in binary of the device that is to be operated on.
,DEVNCHAR=devnchar: The name (RS-type), or address in register (2) - (12), of an optional byte input that specifies the device number in EBCDIC, of the device that is to be operated on.
,SCHSET=schset|0: The name (RS-type), or address in register (2) - (12), of an optional byte input that specifies the subchannel set of the device. The default is 0.
,LDEVNCHAR=ldevnchar: The name (RS-type), or address in register (2) - (12), of a 5-character input that specifies the logical device number, in EBCDIC, of the device whose UCB address is to be obtained.
Note: A logical device number is represented by a 1-digit subchannel set id followed by the 4-digit device number, sdddd.
,RETCODE=retcode: The name (RS-type), or register (2) - (12), of an optional fullword output into which the return code is to be copied from GPR 15.
,RSNCODE=rsncode: The name (RS-type), or register (2) - (12), of an optional fullword output into which the reason code is to be copied from GPR 0.
,PLISTVER=plistver | MAX | IMPLIED_VERSION: is an optional byte input decimal value in the "1–1" range that specifies the macro version. PLISTVER is the only key allowed on the list form of MF and determines which parameter list is generated. Note that MAX may be specified instead of a number and will cause the parameter list to be of the largest size currently supported. This size may grow from release to release (thus possibly affecting the amount of storage needed by your program). If your program can tolerate this, IBM® recommends that you always specify MAX when creating the list form parameter list as this will ensure that the list form parameter list is always long enough to hold whatever parameters might be specified on the execute form.
Default: IMPLIED_VERSION. When PLISTVER is omitted, the default is the lowest version which allows all of the parameters specified on the invocation to be processed.

ABEND codes

None.

Return codes

Return and reason codes, in hexadecimal, from the IOSODS macro are as follows:

Hexadecimal return code	Hexadecimal reason code	Meaning
00	None	The requested function executed successfully.
08	01	The requested function failed because the input device number was not found.
08	02	A request to allocate an offline device was made, but it is already in use by a system component (ON function).
08	03	A request to unallocate a device was made, but the device is not currently in use (OFF function).
08	04	IOS Path Validation failed (ON function).
08	05	IOS Dynamic Pathing function failed (OFF function).
08	06	Allocation service to set UCBNALOC failed (ON function).
20	None	An unexpected error occurred. The recovery routine recovered and returned control to the caller.