Appendix B. Return Values and Ready States

Appendix B. Return Values and Ready States
Prev		Next

This appendix lists error codes and response types, then discusses ready state processing.

B.1. ALI Error and Return Values

The following list shows the error codes for an LCP:

#define ALI_E_NOSLOT   "ALI_E_NOSLOT"   /* unknown slot */
#define ALI_E_NOPCL    "ALI_E_NOPCL"    /* unknown PCL */
#define ALI_E_NOBAY    "ALI_E_NOBAY"    /* unknown bay */
#define ALI_E_NODRIVE  "ALI_E_NODRIVE"  /* unknown drive */
#define ALI_E_NOATTR   "ALI_E_NOATTR"   /* unknown attribute */
#define ALI_E_NOTYPE   "ALI_E_NOTYPE"   /* unknown type */
#define ALI_E_NOCMD    "ALI_E_NOCMD"    /* unknown command */
#define ALI_E_NOTASK   "ALI_E_NOTASK"   /* unknown task ID */
#define ALI_E_ACCESS   "ALI_E_ACCESS"   /* access denied or object inaccessible */
#define ALI_E_BADVAL   "ALI_E_BADVAL"   /* bad attribute value */
#define ALI_E_SRCFULL  "ALI_E_SRCFULL"  /* source location full */
#define ALI_E_SRCEMPTY "ALI_E_SRCEMPTY" /* source location empty */
#define ALI_E_DSTFULL  "ALI_E_DSTFULL"  /* destination location full */
#define ALI_E_DSTEMPTY "ALI_E_DSTEMPTY" /* destination location empty */
#define ALI_E_AGAIN    "ALI_E_AGAIN"    /* retry recommended */
#define ALI_E_READY    "ALI_E_READY"    /* target not ready */
#define ALI_E_PCL      "ALI_E_PCL"      /* PCL mismatch */
#define ALI_E_SEQUENCE "ALI_E_SEQUENCE" /* command sequence error */
#define ALI_E_ABORT    "ALI_E_ABORT"    /* command aborted by LCP */
#define ALI_E_LIBRARY  "ALI_E_LIBRARY"  /* library or device driver failure */
#define ALI_E_SHAPE    "ALI_E_SHAPE"    /* cartridge-drive fungibility error */

The following list shows the response types for ALI response:

ALI_response_accepted,          /* command queued */
ALI_response_unacceptable       /* command not queued */
ALI_response_success,           /* command worked */
ALI_response_error,             /* command failed */
ALI_response_cancelled          /* command cancelled */

B.2. ADI Error and Return Values

The following list shows the error codes for a DCP:

#define ADI_E_PART     "ADI_E_PART"     /* unknown or unsupported partition */
#define ADI_E_MODE     "ADI_E_MODE"     /* unknown or unsupported mode */
#define ADI_E_HANDLE   "ADI_E_HANDLE"   /* unknown or in use handle */
#define ADI_E_NOATTR   "ADI_E_NOATTR"   /* unknown attribute */
#define ADI_E_NOTYPE   "ADI_E_NOTYPE"   /* unknown type */
#define ADI_E_NOCMD    "ADI_E_NOCMD"    /* unknown command */
#define ADI_E_NOTASK   "ADI_E_NOTASK"   /* unknown task ID */
#define ADI_E_ACCESS   "ADI_E_ACCESS"   /* access denied or object inaccessible */
#define ADI_E_BADVAL   "ADI_E_BADVAL"   /* bad attribute value */
#define ADI_E_AGAIN    "ADI_E_AGAIN"    /* retry recommended */
#define ADI_E_READY    "ADI_E_READY"    /* target not ready */
#define ADI_E_SEQUENCE "ADI_E_SEQUENCE" /* command sequence error */
#define ADI_E_DRIVE    "ADI_E_DRIVE"    /* drive or device failure */

The following list shows the return values for ADI response:

ADI_response_accepted,          /* command queued */
ADI_response_unacceptable,      /* command not queued */
ADI_response_success,           /* command worked */
ADI_response_error,             /* command failed */
ADI_response_cancelled          /* command cancelled */

B.3. Ready States

Ready state describes the condition of the OpenVault connection with a device. Whenever the ready state changes, the library or drive control program should save changes and also send them to the MLM server, by means of the ready command.

When the control program is in ready yes state, that means it can talk to its device. If not in this state, the control program can still accept ALI or ADI commands, but will fail to execute any ALI or ADI commands requiring that it to talk to its device.

The following terms define state for both libraries and drives, defining how changes in the underlying device and API state can affect control-program ready status.

Device connected
	The control program can communicate with its device by means of the formal device API.
Device not connected
	The control program cannot communicate with its device by means of the formal device API.
Device online
	The control program has a connection to its device, and the device is able to accept commands.
Device not online
	The control program has a connection to its device, but the device is unable to accept commands because it is in some unusable state. (For a library, controller software might be down, and hardware might be offline, or in diagnostic state.)
Device ready
	The control program has a connection to its device, which reports “device online” and is ready to accept commands.
Device not ready
	The control program has a connection to the device, which reports “device online” but is temporarily not ready to accept commands.

B.3.1. Ready State Transition Rules

Table B-1, describes the initial ready states, the actions that trigger them to change the new ready state for each condition, and the control program action for state transitions (not including the need to send ready state to the MLM server for each transition).

Table B-1. Ready State Transitions

Initial State	Action Triggering Change	New State	Control Program Action
Lost	MLM server sends `activate enable` command. Control program is unable to connect to device.	Lost
Lost	MLM server sends `activate enable` command. Control program is able to connect to device and finds it online and ready.	Yes	Gets device state and send full `config` command to the MLM server.
Lost	MLM server sends `activate enable` command. Control program is able to connect to device but finds it online not ready.	No
Lost	MLM server sends `activate enable` command. Control program is able to connect to device but finds device not online.	Broken
Yes	MLM server sends `activate disable` or `exit` command to control program, or control program finds that its connection to device is lost.	Lost	Stops communicating with device. Forces pending device requests to completion, or cancels. Forgets device state.
			If exiting, forces pending ALI or ADI commands to completion, or cancels them, and completes or aborts pending ALI/R or ADI/R commands. Also does shutdown processing.
Yes	MLM server sends `activate enable` to control program.	Yes	Resends full `config` command to the MLM server.
Yes	Control program about to send command to device that will effectively block or reject all other commands to device until this one completes, or control program finds device is online but not ready.	No
Yes	Control program finds that device is not online.	Broken	Stops communicating with device. Forces pending device requests to completion, or cancels. Forgets device state.
No	MLM server sends `activate disable` or `exit` to control program, or control program finds its connection to device is lost.	Lost	Stops communicating with device. Forces pending device requests to completion, or cancels. Forgets device state.
No	A device command issued by the control program that effectively blocked all other device commands has now completed, or the control program finds that the device is now online and ready.	Yes
No	MLM server sends ALI or ADI command to control program that requires use of the device.	No
No	Control program finds that device is not online.	Broken	Stops communicating with device. Force pending device requests to completion, or cancel. Forgets device state.
Broken	MLM server sends `activate disable` or `exit` to control program, or control program finds its connection to device is lost.	Lost
Broken	Control program finds its device is online and ready.	Yes
Broken	Control program finds its device is online, but not ready.	No
Broken	MLM server sends ALI or ADI command to control program that requires use of the device.	Broken

B.3.2. Ready State Responses

The MLM action in response to control program ready state changes are as follows:

Yes	The control program can be selected for use. May not activate another control program for the same device until this one is disabled.
No	Temporarily do not send ALI or ADI commands that require device access to the control program. May not activate another control program for the same device until this one is disabled.
Broken	The device associated with control program has failed. Do not try to activate another control program for this device, because the device itself is broken. Some recovery technique is needed, such as notifying the operator to take corrective action. For instance, the operator can choose to disable the current control program and start a separate one in manual mode, or switch the current control program into manual mode.
Lost	The control program is not ready for use. If no other control program is currently active for this device, the MLM server may try to activate this or a different control program for the device, as needed.

These ASCII tokens are associated with each ready state:

Lost	`“lost”`
Yes	`““`
Broken	`“broken”`
No	`“not”`

The following list gives more information about control program actions in response to ready state changes:

Once it has established a connection with the MLM server, a control program should initialize its ready state to lost, and send this to the server.
Once it has established a connection with the MLM server, a control program should accept and process ALI or ADI commands. If it is in ready lost, no, or broken state, and it receives a command that requires it to access its device, then the control program should resend its ready state to the server and fail the command with a ready error (for example, ALI_E_READY or ADI_E_READY).

The exception to this is that the LCP should process activate enable, as usual, if in ready lost or broken state.
If a control program is already in ready yes state, and receives another activate enable command, it should resend its full configuration, including its ready state, and send a success response to the server.
Before transitioning to ready lost or broken state, a control program must process all pending ALI or ADI commands to completion, either by normal completion along with the appropriate response, or by aborting commands that it cannot complete along with a cancelled response.

Prev	Table of Contents	Next
Appendix A. Sample Implementations		Appendix C. LCP and DCP Syntax