This chapter provides programmers with an introduction to the OpenVault languages for controlling removable media libraries, and includes the following sections:
Section 3.1 describes the language in which the MLM server sends directives to an LCP, and responds to requests sent by an LCP.
Section 3.2, tells how an LCP sends configuration and status to the MLM server, and responds to directives from the MLM server.
The following sections describe the abstract library interface (ALI), including objects, object attributes, naming conventions, and the ALI command repertoire.
ALI is a language that provides an abstraction of a removable media library that is managed by OpenVault. ALI hides details of the underlying library and control methods without compromising the ability of OpenVault as a whole to manage its resources effectively. The MLM server communicates with an LCP using the ALI.
The ALI language manipulates the following objects:
Bay: A location for cartridges, with locality determined by similar access (mount) time. Typically, a bay is a physical grouping of cartridges in a common unit of housing, where cartridges are stored. A bay contains storage locations for cartridges, optional drives, and one or more transfer agents to move cartridges between storage locations and drives or other storage locations.
In a multibay library, each bay in the library is attached to at least one other bay in the same library. For each cartridge in the library, there is some path for moving that cartridge from its current bay to any other bay, with one or more transfer agents to move that cartridge.
Cartridge: A physical container for storage media. Each cartridge in the OpenVault system should have some kind of external identifying label (a physical cartridge label) that the library or an operator can verify. Part of the external label should be human readable. For automated libraries, another part of the label is machine readable--typically a barcode label that a laser scanner can interpret.
Cartridges can have multiple sides. If they do, their containing library should be able to move or mount cartridges to achieve a particular orientation, for example, “side A” up.
Command: ALI commands are objects as far as ALI is concerned. When the MLM server sends an ALI command, it associates a task ID with that command. The sender may refer to that command later by using the same task ID, but only to cancel the command. When an LCP receives a command, it includes the task ID in command responses.
Drive: A device for accessing media inside a cartridge that has been mounted.
Library control program (LCP): Each LCP knows the details of a removable media library, including its configuration and control procedures. An LCP is responsible for accomplishing tasks that the MLM server asks it to perform, primarily managing library resources. An LCP communicates with its library using some device-specific language.
An LCP can be seen as a black-box language translator, or a device management module. See Chapter 4, “Programming a Library Control Program (LCP)” for details about writing an LCP.
Port: A door or opening where cartridges may be inserted into or removed from the library.
Removable media library: A library contains one or more housing units, called bays, for storing cartridges. Bays contain storage locations for cartridges, optional attached drives, and one or more transfer agents for moving cartridges between storage locations in the same or different bay (using the move command), or between storage locations and drives in the same or a different bay (using the mount and unmount commands).
A library provides some way to read or verify external labels affixed to cartridges. A removable media library also provides some means for inserting cartridges into and removing cartridges from the library.
Each library has a specific control method. For automated libraries, this is typically some physical control connection from a host. For a human operated library, this might be a connection to an operator console.
Typically, a library is a single automated device, with some sort of robotic transfer agent to move cartridges between storage locations and drives. Larger devices may include a number of bays attached with pass-through ports. A human operated vault, where tapes are stored on racks and transported between racks and drives by people, is another type of removable media library.
Slot: A storage location for a cartridge. It has a shape, or form factor, that determines which kinds of cartridges it can hold.
OpenVault requires an LCP to maintain library configuration attributes and notify the MLM server when they change. LCPs use the ALI/R config and ready commands to do this. These commands send properties back to the MLM server, where configuration information is kept in the MLM server persistent store. It is potentially recoverable by the LCP using the ALI/R show command. Here are the required configuration attributes:
LCP ready state (Section B.3 in Appendix B)
Library nominal cartridge exchange time (Table 4-3)
Element maps for slot, bay, and drive ( Section 3.1.4)
Cartridge form factor associated with slots, ports, and drives
Number of free slots in each bay, by form factor
Note: Currently, OpenVault does not support recovery of any attribute or property information stored in the MLM server persistent store by an LCP. However, this may be supported in a future version of OpenVault.
Arbitrary attributes are LCP private attributes. Developers may devise arbitrary attributes, and store them to and recover them from the MLM server persistent store. These attributes are opaque to the MLM server.
Mandatory attributes are attributes that an LCP is required to support. Developers may store the loglevel mandatory attribute in the MLM server persistent store; so the LCP can recover it and resume logging at the same level across reboots.
ALI expresses LCP attributes using the tuple:
object type, object name, attribute name |
Table 3-1 shows the mandatory attributes, not including the configuration attributes.
Table 3-1. Mandatory LCP Attributes
Object Type | Object Name | Attribute Name | Command |
|---|---|---|---|
LCP | "" | Name | ALI show |
LCP | "" | SupportPCLs | ALI show |
LCP | "" | Vendor | ALI show |
LCP | "" | loglevel | ALI show, ALI attribute set |
Element maps are kept in the OpenVault persistent store and refreshed by the LCP when appropriate. There are element maps for the following objects:
Baymap: List of bays in the library, with information on whether each bay is accessible or not
Drivemap: List of drives in the library, with information on whether there is a cartridge in each drive, and whether it is accessible
Slotmap: Array of elements, one per slot, provided by the LCP to help the MLM server operate and administer the library, including:
Physical cartridge label (PCL); for instance, a barcode
bayID for the bay the slot is in
slotID for the name of the slot
formFactor of the slot
Whether a slot is full or empty (PCL is NULL if a slot is empty.)
Slot accessibility information (PCL is NULL if this is false.)
Table 3-2 shows element map objects that an LCP supports.
Table 3-2. Element Map Components
Object Type | Object Name | Attribute Name | Command |
|---|---|---|---|
Bay | bayID | Description | ALI show |
Slot | slotID | Slot description | ALI show |
Drive | driveID | Description | ALI show |
These names refer to specific ALI objects:
Bay ID: A text string provided by the LCP, which refers to a bay in the library. An LCP should choose bay IDs that are easy for a human operator to interpret. For multibay libraries, the bay ID is usually consistent with the device name or address for a bay.
Client name: The OpenVault client name refers to a specific removable media library. This is the name by which a client identifies itself in a hello command to the MLM server. For ALI clients, this is name that the MLM server associates with the library that is managed by the associated LCP.
Instance name: The OpenVault instance name is arbitrary, but is needed in case there are multiple LCPs controlling the same library, so as to distinguish between LCPs with the same client (library) name.
LCP name: Each LCP is uniquely named by a value pair including an OpenVault client name and an OpenVault instance name.
PCL: A physical cartridge label (PCL) refers to a cartridge. It is some form of identification on the outside of the cartridge, as opposed to being stored on media inside the cartridge. A PCL may contain a machine-readable label (barcode), but it must also contain a human-readable text portion.
Port name: Currently, there is no ALI support for port names. Port naming may be supported in a future version of OpenVault.
Slot ID: A text string provided by the LCP, which refers to a slot in the library. The slot ID must uniquely identify any slot under control of that LCP, and should be easy for a human operator to interpret. For libraries with explicit slot locations, slot ID is usually consistent with the device name or address for that slot.
Attribute naming in ALI is different than for CAPI and AAPI, in which an attribute is given as TableName.ColumnName; attributes are just columns in a relational table. In ALI and ALI/R, attributes are named with a tuple:
objectType, objectName, attrName |
The MLM server speaks ALI to the LCP, which in turn speaks ALI/R to the MLM server. The ALI language includes the following commands:
activate: Starts and stops LCP interactions with the library. The activate command includes two variations. Note that once the LCP has established a session with the MLM server using the hello-welcome sequence, it may begin accepting ALI commands from the server. However, until it has successfully been activate enabled and is in ready state, it will resend ready lost state and fail ALI commands requiring access to its library with the error ALI_E_READY. The LCP uses one of the ALI/R ready command variations after processing the current command.
These are the variations of the activate command:
activate enable: Forces the LCP to resynchronize its internal information with the physical state of the library, and keep it synchronized. For example, with a SCSI-based sighted robot, the LCP could do a barcode inventory and resume status polling.
Performing this command will probably result in the LCP modifying slotmap information in the MLM server for this library, pushing the slotmap to the MLM server using config, and possibly accessing LCP-private attributes stored in the MLM database. The LCP reports ready when all its internal resynchronization operations have completed (for example, when the barcode scan is done).
activate disable : Forces the LCP to stop talking to the library. For example, on a SCSI-based robot the LCP may be in the habit of polling the device for status changes; this command would stop that polling.
An activate disable should complete or cancel ALI commands that require access to the library, and store any persistent library state in the MLM server.
The LCP requires an activate enable command before it can talk to the library again.
The LCP reports ready lost when all its state update operations have completed and any internal machinery has been shut down. Performing this command may not result in the library's cartridges becoming inaccessible if there is an alternate LCP and the library is connected to multiple hosts.
attribute: Sets and unsets named attributes in the LCP. You can think of attributes in an LCP as named memory locations that may cause operations to happen as a side effect of setting or reading them. Some attributes defined by an LCP may be read-only to the MLM server.
A list of mandatory attribute names appears in Table 3-1.
barrier: Forces the LCP to complete work on all commands received prior to the barrier command, before it begins working on any commands that might follow. This may require special processing for queued eject and openPort commands. For example, if an LCP normally flushes ejects with the openPort command, barrier should be rejected if the LCP has not already received an openPort command.
In general, an LCP is free to execute the commands it receives in any convenient order. Since there might be circumstances where the MLM server requires an explicit order for executing a sequence of commands, the barrier command can be employed to force ordering.
cancel: Prevents execution of a command that has been queued in the LCP but which the device has not yet started. The LCP may choose to cancel already started jobs on a best-effort basis.
Note: The cancel and response commands may not be cancelled. eject: Pushes, in conjunction with the openPort command, cartridges out of the library. It takes a (slot ID, PCL) pair for the cartridge that is to be operated on. The LCP should send the corresponding changes in its slot and drive maps to the MLM server.
The implementation of the eject command may vary from LCP to LCP, but there are three basic cases, as listed in Table 3-3.
Table 3-3. Three Cases of eject
Operator
Interaction
Required
LCP
Becomes
not ready
Likely Semantics and Effect
No
No
The eject command causes the given cartridge to be immediately pushed out of the library. The openPort command is a successful no-op. The library continues operation uninterrupted.
The ATL2640 is one example of a library in this class. It has a bin where exported cartridges simply pile up. No operator interaction with the LCP is required.
Yes
No
The eject command causes the given cartridge to be marked as needing to be pushed out of the library, but the cartridge is not yet pushed out. The LCP is free to move the cartridge if it needs to. An openPort command tells the LCP that the operator is ready to physically take the cartridges out of the library. The library continues operation uninterrupted.
A StorageTek silo is an example of this library type. The silo has a port with slots on the inside where the LCP can move cartridges when they are ejected. The openPort command unlocks access port(s) and allows the operator to remove the cartridge(s).
Yes
Yes
The eject command causes the given cartridge to be marked as needing to be pushed out of the library, but the cartridge is not yet pushed out. The LCP is free to move the cartridge if it needs to. An openPort command tells the LCP to put the library into the “ready not” state and prepare it to allow the operator easy access to those cartridges marked for ejection.
The EXABYTE 210 is an example of this type of library. It must be taken offline to physically remove cartridge(s). The openPort command puts the library into ready not state and unlocks the access door, allowing the operator to remove ejected cartridge(s).
When an LCP determines that the access door has been opened and closed, it should lock the door, reinventory the library, complete affected ejects, inform the MLM server of slotmap changes, and transition to ready state.
When a cartridge is physically ejected, it must immediately disappear from the OpenVault slotmap maintained by the LCP. This implies that an LCP that cannot immediately push a cartridge out of the library must be prepared to inform OpenVault that a particular slot ID (and therefore PCL) has been marked for ejection. The LCP should mark this slot as inaccessible and push the information to the MLM server.
The LCP should recall this information from the OpenVault database upon booting, when OpenVault supports retrieval of LCP attributes from the MLM server's persistent storage.
exit: Tells the LCP to clean up and exit.
The LCP should store any persistent LCP or library information in the OpenVault database, complete or cancel any pending ALI commands, send or abort any pending ALI/R commands, do shutdown processing as required by its interface to the library, send ready lost and goodbye commands to the MLM server, and exit.
mount: Places a cartridge into a drive. The arguments to mount are a list of tuples (slot ID, PCL, side) and a drive name. The operation involves taking a cartridge from one of the given slots and putting it into the specified drive. For multisided cartridges, placement is according to a specified side orientation, for example “side A” up. The slot list may have just one element; if more than one is specified, the LCP decides which slot to use. The LCP should send the corresponding changes in its slot and drive maps to the MLM server.
Note: Multisided cartridges are not supported in OpenVault version 1.0. move: Transfers a cartridge from one physical slot in the library to another physical slot. The move source is a slot ID, PCP pair, and the destination is a slot ID. The LCP should send the corresponding changes in its slot and drive maps to the MLM server.
openPort: Removes or allows, in conjunction with the eject command, cartridges to be removed from the library. It may also be used on its own to allow cartridges to be inserted into the library. The function of the openPort command is to prepare the library for an operator to gain physical access to cartridges. Once access is granted, cartridges may be removed from and inserted into the library. The implementation of openPort may vary from LCP to LCP, and a given library might be in a different class for export than for import, but there are three basic cases, as listed in Table 3-4.
Table 3-4. Three Cases of OpenPort
Operator
Interaction
RequiredLCP
Becomes
not ready
Likely Semantics and EffectNo
No
New cartridges are simply inserted into the library.
For example, the ATL2640 has a cartridge insert door and a request button next to it. Pressing the request button is all that is required to prepare the library to accept a new cartridge.
Yes
No
The LCP must prepare to accept a new cartridge.
For example, the StorageTek silo may be told to unlock port(s) so that the operator can add new cartridges.
Yes
Yes
The LCP unlocks the library door and puts the library into ready not state when it detects a door open. When it detects the door is closed again, it reexamines cartridge inventory to see what has been added or removed, and returns the library to ready state.
For example, the EXABYTE-210 must have its main door unlocked before the operator can add cartridges.
See the description of the ready and ready not commands under ALI/R for more information on how an LCP becomes not ready, permitting its library to be temporarily not available during an openPort operation.
reset: Asks the LCP to try and force the library to reinitialize. This may cause the library to perform internal diagnostics.
If a reset makes the library unavailable to process other requests for an extended time, the LCP should use the ready not command to tell the MLM server that its library is temporarily not available, followed by a ready command when the library becomes available again.
response: Acknowledges and indicates success or failure of an ALI/R command. The optional text portion of the response contains error details or command results.
scan: Forces the LCP to verify or recheck the PCLs of all cartridges in the library. These are variations of the scan command:
scan all: The LCP should rescan the entire contents of the library in order to resynchronize its internal information with the physical state of the library. It should send changes in content information to the MLM server.
scan from to: The LCP should rescan all slots represented by slot IDs lexicographically between the from slot and the to slot. The LCP may rescan more slots than listed for some implementation dependent reason. It should send changes in content information to the MLM server.
If the library will be unavailable to process other requests during this time, the LCP should use the ready not command to tell the MLM server that the library is temporarily not available for other motion commands (such as mount, unmount, move, or eject), followed by a ready command when the library becomes available again.
show: Obtains the current value of an attribute. Some of the attributes defined by an LCP may be write-only to the MLM server.
For more information about LCP attributes, see Section 3.2.3.
unmount: Takes a cartridge out of a drive and returns it to a slot. The arguments to unmount are a drive name and a slot ID. The operation involves taking the cartridge from the drive and putting it into the given slot. Optionally, you can specify any for slot ID, and let the LCP choose where to return a cartridge. The LCP should send the corresponding changes in its slot and drive maps to the MLM server.
The following sections describe the ALI/R language, including objects, object attributes, naming conventions, and the ALI/R command repertoire.
ALI/R is primarily the response language for ALI. In addition to giving the matching acknowledgment and final response to an ALI command, ALI/R provides the means for an LCP to send its configuration and status to the MLM server.
The ALI/R language manipulates the following objects:
Currently, ALI/R attributes are not supported by OpenVault, except for attributes stored by the ALI/R config and ready commands in the MLM server persistent store. Currently, OpenVault supports setting and unsetting of config and ready attributes only.
These names refer to specific ALI/R objects:
The LCP reads ALI commands from the MLM server, and replies to the server in ALI/R. The ALI/R language includes the following commands:
attribute: Sets and unsets named attributes in the MLM server, thereby creating persistent storage for whatever the LCP deems necessary. The MLM server simply stores these attributes; there are never any side effects of setting them. For background, see Section 3.1.3.
cancel: Prevents execution of a command that has already been queued in the MLM server but not yet started. The cancelled command returns response cancelled status, and the response for the cancel command itself follows.
Note: The cancel and response commands may not be cancelled. config: Copies configuration information, especially about element map changes, from the LCP to the MLM server.
The MLM server stores a non-authoritative copy of all the element map information for all the LCPs it controls. Each LCP must use the config command in ALI/R to update the MLM server's copy of the element map information whenever it changes. The element map should change only as a result of administrator or operator actions.
In the full scope option, all information that the MLM server associates with the LCP is deleted and replaced with information listed in the config command. In the partial scope option, the MLM server replaces only pieces of LCP information that are listed in the config command.
Normally, the full scope option is employed at startup and when major changes to the library configuration occur, whereas partial scopeis employed when a cartridge movement operation happens. Very large libraries can initially use a partially populated full scope option followed by a series of partial scope commands, if this proves easier.
The config command does the following:
Copies the list of slots to the MLM server, including information on which bay slots are in, the PCL of the cartridge in a slot, what form factor of cartridge is in (or could be in) that slot, whether the slot is occupied or not, and whether the slot is accessible or not.
Copies the list of drives to the MLM server, including information on whether there is a cartridge in the drive (it may not have been loaded, so the DCP might not see it) and whether it is accessible.
Copies the list of bays to the MLM server, including information on whether each bay is accessible or not. It is possible for a single bay in a multibay library to be inaccessible or temporarily broken.
Copies a list and count of free slots in each form factor inside all library bays to the MLM server. Some libraries have no name for empty slots, and bays sometimes contain several form factors, so we need a count of the number of free slots of each type.
Provides some approximate performance information to the MLM server for the library. The MLM server may use that information when choosing which library to use. For example, a library with an expected cartridge mount time of 10 seconds may be preferable over one with an expected mount time of 24 hours.
goodbye: Tells the MLM server to end this session and clean up its end of the session. This protects against the accumulation of idle connections, since the MLM server has no way of detecting that an LCP exited other than the TCP/IP keepalive option. keepalive helps recover from process failures, but an LCP should send a goodbye before exiting to prevent unnecessary continuation of connection resources.
message: Sends a message of some severity level to the MLM server. The LCP loglevel attribute determines a limit on the severity level of messages sent to the MLM server. This command provides a mechanism for the LCP to send messages that the MLM server can convey to an operator and possibly a system administrator.
Note: This mechanism may change in future releases of OpenVault. ready: Tells the MLM server, along its variations, the current status of the library, and whether it is available for cartridge operations. Like the config command, the ready command is just a shorthand way of conveying attributes about ALI objects to the MLM server.
These are variations of the ready command:
ready: The LCP has resynchronized its internal information with the physical state of its device, and is prepared to accept commands that require it to access its device.
ready not: The library is temporarily unavailable for motion operations, such as ALI mount, unmount, move, and eject, or ADI load and unload .
ready broken: The LCP detected that its device hardware is reporting a hard failure and is nonfunctional.
See Section B.3 in Appendix B, for more information about ready states.
response: Acknowledges and indicates success or failure of an ALI command. The optional text portion of the response contains error details or command results.
show: Obtains the value of an attribute that the LCP previously stored in the MLM server.
For some ALI commands, the matching ALI/R response command for a successful response contains a text portion, which must have a particular format and ordering. This section describes these requirements.
The text portion of a successful response to the show command depends on the specified mode for the show command, and on the number of attributes to be queried. There are three possible modes:
| ALI_show_name | Shows name only. | |
| ALI_show_value | Shows value only. | |
| ALI_show_namevalue | Shows name and value, in that order. |
For each attribute to be queried, the text portion of the response includes name-value information, as dictated by this mode, and is ordered according to the specified attribute list. So, for example, if a show command requested a query of LCP loglevel and vendor attributes, with the ALIR_show_namevalue mode, the corresponding text portion of the response would look something like this:
text[ 'loglevel' 'debug' 'vendor' 'EXABYTE' ] |
The text portion of a success response for mount and unmount includes the value tuple:
source slotID, PCL, and OpenVault drive name |
The values are not tagged with a name, and must appear in this order. The corresponding text portion of the response would look something like this for source slotID slot 1, for PCL AB1234, and for drive fred:
text[ 'slot 1' 'AB1234' 'fred' ]; |
The text portion of a success response for a move command includes the value tuple:
source slotID, PCL, destination slotID |
The values are not tagged with a name, and must appear in this order. The corresponding text portion of the response would look something like this for source slotID slot 2, for PCL AB5432, and for destination slotID slot 5:
text[ 'slot 2' 'AB5432' 'slot 5' ]; |
The text portion of a success response for an eject command includes the value pair slotID, PCL. The values are not tagged with a name, and must appear in this order. The corresponding text portion of the response would look something like this for slotID slot 10 PCL AB9999:
text[ 'slot 10' 'AB9999' ]; |
See Appendix B, “Return Values and Ready States”, for a list of return values and detailed information about ready states.