Silicon Graphics, Inc.
OpenVault
Abstract Library Interface
Language Definition

$Id: ALI.html,v 1.34 1997/08/06 17:41:11 jbt Exp $

Overview and High Level Goals

In a traditional approach, everything that could be in a library would be visible to and managed by the MLM Core. For example, drives, bays, cartridge transfer agent, cartridge access ports, pass-through ports between libraries, etc. This would have made LCPs almost trivial to write, but it would have put the whole problem of efficiently managing the resources of an arbitrarily complex library into the MLM Core.

The OpenVault approach centralizes virtually all of the configuration and management problems for a given library into a piece of software custom written for that library. This means that new library support can be added to an existing environment by simply adding a new piece of software.

The Library Control Program (LCP) is the part of the OpenVault system which knows the intimate details of a particular library and its configuration and control procedures. The language which the MLM Core program speaks to the LCP and the corresponding response language are collectively called the Abstract Library Interface (ALI). ALI is designed to abstract away as many of the details of a library as practicable, without compromising the ability of the OpenVault system as a whole to efficiently manage its resources.

An LCP can be thought of as a black-box language translator device and/or a device management module. The LCP is responsible for performing the tasks that the MLM Core asks it to do while efficiently managing the resources of the library. It speaks ALI with the MLM Core, and some device-specific language to the library itself.

Decisions, Assumptions, and Limitations

We assume that there will be an essentially custom-written LCP for each make/model of library. For example, there might be one LCP that could manage an EXABYTE 440 or an EXABYTE 480 library given their similarities, but you might need a different LCP to manage an EXABYTE 210 library, and you would certainly require a different LCP to manage an ATL 2640. Since each LCP will be custom-written for that make/model of library, it will either have ways of determining the library's configuration and capabilities at run time or they will be implementation constants.

Each LCP has responsibility only for the information that it can gain from reading its configuration file and talking to the connected library. The responsibility to read and determine the information at run time also means that they are the authoritative source for that information. Specifically, the library itself is the authoritative source for information about the library, the LCP is just a buffer and a translator. The MLM Core will ask for device information at (re)boot time or when it needs updated information for some reason. The MLM Core database is available for use as a persistent store by the LCP, however.

We assume that the MLM Core will use information from the DCP's (Drive Control Programs) associated with each drive in a library in conjunction with information from the LCP to manage both of them.

Interfaces

Low Level Data Communications

The communication between the MLM Core and the LCP uses a stylized sequence of phases. Since the interface is a full-duplex bidrectional peer-to-peer interface, this stylization applies to both directions of the channel. The phases of a command are:

command	During the command phase the sender transmits the text of the command. The sender assigns a unique task ID to each command it generates, and sends that task ID as part of the outgoing command. The task ID will be used to match responses with the correct command.
ack	During the ack phase the receiver of the command sends back a packet indicating that it has successfully received the command with the given task ID. The sender cannot send another command until it receives the ack for the prior command. This allows the receiver to throttle the command sequence if necessary. It is possible for the receiver to send back an unacceptable response instead of an ack if the command was incorrectly constructed. In that case, there would be no data phase.
data	During the data phase the receiver of the command sends back the task ID, so as to identify which command is being responded to, and the the actual return value. Note that the return value can be an indication of success, of failure, or a value being returned. Return values may intervene on the channel between transmission of a command and receipt of the corresponding ACK. Commands, ACKs, and return values may intervene on the channel between transmission of an ACK and receipt of the corresponding return value.

Note that since the connection between an LCP and the MLM Core is full-duplex, each direction of the channel may be in any of the above states.

Each end of the communications channel must be prepared to both read and write the channel when it desires to either send or receive on the channel. For example, if one end desires to send on the channel but the channel is full and our write would block, we must be prepared to read any available data on the incoming channel. The next effect is that the only blocking I/O operation permitted on the channel is a select() call. This requirement is how we avoid the possibility of deadlocks on access to the comm channel.

Semantic Interfaces

There are two distinct languages used in the LCP/MLM connection, one for each direction in the bi-directional connection. They are:

ALI The language spoken by the MLM Core to the LCP.

ALI/R The language spoken by the LCP to the MLM Core. The full name is the ALI Response language.
The ALI response language implements a different command set than the ALI language, reflecting its different requirements. The ALI language defines a library control interface while the ALI/R language defines primarily a status reporting and administration/configuration interface.
The relationship between the MLM Core and an LCP is a peer-to-peer relationship. The LCP has the ability via the ALI Response language to persistently store and retrieve data in the MLM Core database, and to inform the MLM Core of changes in the state of the library.
As a result of the task identifiers present in the line-protocol, both ALI languages directly support concurrent execution of multiple tasks, even though there is not much call for concurrent execution in ALI/R. The main reason for this is to get efficient utilization of a library that has multiple "arms"; the LCP needs to have the ability to queue up commands for simultaneous execution.
The ALI language explicitly allows tasks to be queued, and does not mandate that they be executed serially, subject to a constraint. An LCP is free to optimize the use of whatever means it has to move carts from storage to drives and back. The constraint in task reordering is that if one operation depends on the result of another operation that was queued earlier in time, the two operations may not be reordered with respect to each other.
It is possible for an LCP-specific administrative application to use the setting and reading of named attributes as an additional means of interacting with that LCP or controlling its state. You can think of attributes in an LCP as named memory locations that might cause an operation to happen as a side effect of setting or reading them. This gives us both a flexible and an extensible mechanism, but does limit any administrative application that uses that mechanism to interacting with that specific type of LCP.

Open Issues

None known at this time.

Functional Specification

ALI Element Descriptions

cartridge	A cartridge is the physical shell that encases the writeable media. Note that not all types of media are writeable, eg: CDROM. We distinguish between a cartridge and the media it contains because an LCP is only concerned with the cartridge and not the media, and some types of cartridges contain more that one piece of media, eg: two sided optical disks.
PCL	The Physical Cartridge Label is some form of cartridge identification on the outside of the cartridge, instead of stored on the media inside the cartridge. This is usually a barcode, and is usually machine readable, but could also be handwritten notes for a non-sighted library.
form factor	This is the name for the type of cartridges handled by the library. For example, "DLT", "8mm", "4mm", etc. are valid form factors. The names presented here are "blessed names" in that they must be the same names as MLM Core uses for physical cartridge types. See the document on Pre-Defined Tokens and Descriptions for more examples. Note that the format of the bits on the media contained in the cartridge is not specified here. For exmple: a "3480" form factor could be written with bits in 3480 format or with bits in 3490 format (ie: it is really a 3490 tape). Again, see the document on Pre-Defined Tokens and Descriptions for more examples.
drive	This refers to the device used to access the contents of the media, eg: this could be a tape drive or an optical disc drive. Note that the LCP never accesses the media, it only moves the cartridge to the drive so that a DCP, and then the application, can access the media. The MLM Core needs to know the names of the drives contained within an LCP. The LCP needs to know the correspondence between the OpenVault name for a drive and the addressing information for that drive within the library, but the MLM Core does not because it will always refer to it by name.
slot ID	This is a text string provided by the LCP, which OpenVault treats as an opaque handle, referring to a particular physical slot in the library. OpenVault will only display a slotID or do a string comparison with another slotID to check for equality. The LCP should generate slotIDs such that when a human looks at them they make some sort of sense in terms of the topology of the library. For example: "slot 34", "bay 3, slot 128", and "room H, rack 4, tape 22" are all good slotIDs. The slotID must be sufficient to uniquely identify any slot under the control of that LCP. The slotIDs must also be parseable by the LCP. SlotIDs will be used by the Administrator to do physical slot addressing, and non-sighted libraries must use them for cartridge mounts, so the LCP needs to be able to recover the semantic information from the slotID.
bayID	This is a text string provided by the LCP, which OpenVault treats as an opaque handle, referring to a particular group of physical slots in the library. OpenVault will only display a bayID or do a string comparison with another bayID to check for equality. The MLM Core uses bayIDs to compare access times (ie: locality information) for carts and drives. The LCP should generate bayIDs such that when a human looks at them they make some sort of sense in terms of the topology of the library. For example: "bay 3", "bay 4", and "room H" are all good bayIDs. For some libraries, the difference between one bay and another will be obvious based on topology and access times. For example, each silo in a group of Storage Tek silos would be a separate bay, and each room in a tape library building would be a bay. They are defined based on a large increase in the access time for a cartridge between inside the bay versus outside the bay.

ALI Command Descriptions

mount

The mount command is used to mount cartridge(s) into drive(s). The mount arguments are a single drive name and a set of triplets of slotIDs, PCLs, and sides. The operation is to take one of the cartridges from the given slots and put it into the given drive. In sighted libraries, the cartridge in a given slot must have the corresponding PCL or it will be skipped.

Note that there may be only one slot specified. If there is more than one slot specified, which slot is mounted is explicitly an LCP decision.

unmount

The unmount command is used to unmount a cartridge from a drive. The unmount arguments are a drive name and either a list of slotIDs or a wildcard token. The operation is to take the cartridge from the given drive and put it into one of the given slots, or any available slot if the wildcard token is used.

Note that there may be only one slot specified. If there is more than one slot specified, which slot the cartridge is placed in is explicitly an LCP decision.

move

The move command is used to move a cartridge from one physical slot in the library to another physical slot. The move source is both a slotID and the PCL for the cartridge in that slot. The destination is a single slotID. In sighted libraries, the PCL is used as a cross-check on the contents of the source slot.

eject

The eject command is used in conjunction with the openPort command to push a cartridge out of the library. It takes a pair consisting of a slotIDs and a PCL representing the cartridge that is to be operated on. In sighted libraries, the cartridge in that slot must have that PCL or an error is returned. The implementation of the eject command will vary from LCP to LCP, but there seem to be 3 basic cases:

Operator Help Needed Library must go not ready Drive(s) must be idle Semantics and Likely Effects

No 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 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 actually pushed out of the library yet. The LCP is free to move the cartridge if it needs to. The 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 Storage Tek silo is one example of a library in this class. The silo has a door with slots mounted on the inside where the LCP can move cartridges when they are ejected. The openPort command would unlock the access door(s) and allow the operator to physically remove the cartridge(s).

Yes 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 actually pushed out of the library yet. The LCP is free to move the cartridge if it needs to. The openPort command tells the LCP to put the library into the ready not state and prepares it to allow the operator easy access to those cartridge marked for ejection.
An EXABYTE-10H is one example of a library in this class. The entire cartridge inventory is in one magazine so the library must be taken offline in order to physically remove any cartridge(s). The openPort command would put the library into the ready not state and unlock the access door in order to allow the operator to remove the ejected cartridge(s).

When a cartridge is ejected it should immediately be marked as inaccessable in the slotmap maintained in the MLM Core by the LCP. This implies that an LCP that cannot immediately push the cartridge out of the library must be prepared to store the fact that a particular slotID (and therefore PCL) has been marked for ejection and filter that PCL out of the slotmap that it pushes into the MLM Core until the cartridge is actually removed from the library. The LCP is free to mark a slotID as inaccessable in order to accomplish this.

openPort

The openPort command is used in conjunction with the eject command to push cartridges out of the library. It may also be used on its own in order to do cartridge import operations. The function of the openPort command is to ready the library for the operator to have physical access to the cartridge inventory.

Once physical access is gained, new cartridges can be put into the library. Given the three classes of libraries defined above (note that any given library might be in a different class for export than it is for import):

Operator Help Needed Library must go not ready Drive(s) must be idle Semantics and Likely Effects

No No 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 No The LCP must prepare to accept a new cartridge.
For example, the LCP for a Storage Tek silo must be told to unlock the access door(s) so that we can add new cartridges.

Yes Yes No The LCP will put the library into the ready not state, reexamine the cartridge inventory afterward to see what has been added or removed, then put the library back ready.
For example, the EXABYTE-10H must be taken offline and the main door unlocked before we can add new cartridges.

See the description of the ready and ready not commands in ALI/R for more information about how an LCP takes a library offline during an openPort operation.

There will be a configurable switch in OpenVault for each non-sighted LCP. The switch tells OpenVault what to do when the slotmap for that library changes. If the occupancy information in the slotmap has not changed, should OpenVault continue normal operation of that library or stop and wait for the operator to verify the correctness of the slotmap.

Cartridge export operations are explained above.

scan

The scan command and its variations are used to force the LCP to (re)verify the PCLs of the cartridges in the library.

scan all: The LCP should rescan the entire contents of the library in order to resynchronized its internal information with the physical state of the library, specifically including any modifications to the slotmap information in the MLM Core.
scan from to: The LCP should rescan all of the slots represented by the slotIDs lexicographically between the from slotID and the to slotID. It is acceptable for the LCP to rescan more slots than those listed for some implementation dependent reason.

The ready not command will likely be used by the LCP to tell the MLM Core that the LCP is temporarily busy and not available for cartridge mounts while the scan is being performed.

activate

The activate command and its variations are used to start/stop the LCP's interactions with the library. The LCP will generate one of the ready command variations just before it has finished processing the activate command.

activate enable

The activate enable command is used to force the LCP to do whatever is required in order to resynchronize its internal information with the physical state of the library, and keep it synchronized. For example: on a sighted, SCSI-based robot a barcode inventory and resumption of status polling would be appropriate.

Performing this command may result in the LCP modifying the slotmap information in the MLM Core for this library and/or accessing LCP-private attributes stored in the OpenVault database. The LCP will execute the ready command as soon as all of its internal resynchronization operations have completed (eg: the barcode scan), just before the activate command itself returns a completion status.

All interactions with the MLM Core that happen as a result of or in order to process the activate enable command should be completed before the activate enable command returns success or failure.

activate disable

The activate disable command is used to force 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.

The LCP will require an activate enable command before it will again talk to the library.

The LCP will respond to the activate disable command as soon as all unabortable commands have completed execution, all abortable commands have been aborted, all of its state update operations have completed, and any internal machinery has been shut down. The LCP will execute a ready disconnected command as the final step before the activate command returns.

Performing this command may not result in the cartridges in the library being inaccessable if there is an alternate LCP and the library is dual-ported.

reset

The reset command is used to force the LCP to do whatever is required to get the library to reinitialize and run any internal diagnostics. This is a best effort command, the LCP should do everything that it can, but there is no hard requirement to do anything.

The ready not command will likely be used by the LCP to tell the MLM Core that the LCP is temporarily busy and not available for cartridge mounts while the reset is taking place.

exit

The exit command is used to tell the LCP to clean up and exit.

The LCP should store any persistent information in the MLM Core database, do any closedown operations that are required by its interface to the library, then it should exit.

barrier

The barrier command is used to force the LCP to compelete work on all commands received prior to the barrier command before it begins work on any commands that might have followed it.

An LCP is in general free to execute the commands that it receives in any convenient order. Since there might be circumstances where the MLM Core will require an explicit order that a sequence of commands must be executed in, the barrier command can be used to force that ordering.

attribute

The attribute command is used to set and unset named attributes in the LCP. You can think of attributes in an LCP as named memory locations. Some of the attributes defined by an LCP may be read-only to the MLM Core. It is permissible for the act of setting or accessing an attribute to cause some operation to happen as a side effect.

A list of attribute names that should be supported by every LCP is listed in a section below, and in the Pre-Defined Tokens and Descriptions document.

show

The show command is used to obtain the current value of an attribute. Some of the attributes defined by an LCP may be write-only to the MLM Core.

cancel

The cancel command is used to prevent the execution of a command that has already been queued in the LCP but not yet started. The cancelled command will return a response cancelled status, while the response for the cancel command itself will follow.

ALI/R Element Descriptions

slotmap	A slotmap is an array of elements provided by the LCP that allow the MLM Core to operate and administer the library, with one element per named slot in the library. Note that there may be free slots with names and free slots without names. Various pieces of information about each named slot is stored by the MLM Core and refreshed by the LCP when appropriate. The stored data includes: The slotID for the slot the cartridge is in. The bayID for the bay the cartridge is in. The formFactor for the slot the cartridge is in. The PCL (physical cartridge label), eg: barcode. Slot full/empty information (PCL will be NULL if this is false). Slot accessable information (PCL will be NULL if this is false). A non-sighted library will only be able to provide an empty PCL, so the Administrator will be responsible for associating a PCL with each slotID. The OpenVault database must store the fact that the PCL in the table did not originate from the LCP, and therefore may not be accurate if the slotmap changes. Some libraries do not have names for empty slots. The slotmap for such an LCP will only contain information on slots that are occupied and the LCP must provide a count of the number of unnamed free slots for each form factor in each bay.
message	A message is an uninterpreted character string that the LCP would like to be stored in the MLM Core logs, displayed on the operator console, sent to the administrator, or possibly all of the above.
severity level	A severity level is a level of urgency associated with a message. This determines (along with site policy) whether the text of the message is simply stored in the MLM Core logs or displayed on the operator or administrator consoles or both.
operator vs. administrator	A message is targetted by the generating LCP at either an operator or an administrator. An Operator is assumed to be the person who has day to day responsibility for maintaining the hardware and the cartridge pool. An Administrator is assumed to be the person who has control over library configuration and access issues. The two functions could be supported by the same person.

ALI/R Command Descriptions

message	The message command is used to send a message of some severity level to the MLM Core's Operator Interface, Administrator Interface, and/or logfile. Based on the severity level and site policy, messages may be (re)directed to some combination of those destinations. This command provides a mechanism for the LCP to send messages to the operator and/or administrator based on LCP-dependent conditions or errors.
config	The config command copies configuration information (especially changed slotmap information) from the LCP up to the MLM Core for use. The MLM Core stores a non-authoritative copy of all the slotmap information for all the LCPs it controls. Each LCP must use the config command in ALI/R to update the copy of the slotmap information in the MLM Core whenever it changes. Note that since slotmaps are defined to be stable in ALI Version 1, the slotmap should only change as a result of Administrator or Operator actions. In a full scope, all information associated with the LCP should be deleted and replaced with the information listed in the config command. In a partial scope, only the pieces of information about the LCP that are listed in the config command should be replaced. It is expected that the norm will be to use the full scope option on startup and/or major changes to the library configuration, and that the partial scope will be used when a cartridge movement operation happens. Very large libraries can initially use a partially populated full scope command followed by a series of partial scope commands for startup information if a full scope would be too unwieldy. The config command is used to: Copy the list of named slots in the library up to the MLM Core, including information on which bay each slot is in, what PCL is in that 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 accessable or not. It is possible for a slot to be empty, contain a non-barcoded cartridge, contain a barcoded cartridge, be inaccessable, etc. Copy the list of drives in the library up to the MLM Core, including information on whether there is a cartridge in the drive (it may not be loaded, so the DCP may not see it). Copy the list of bays in the library up to the MLM Core, including information on whether each bay is accessable or not. It is possible for a single bay in a multi-bay library to be inaccessable or temporarily broken. Copy a list of the count of free slots of each form factor in each bay in the library up to the MLM Core. It is possible for a single bay to contain several form factors of cartridges and we need a count of the number of free slots of each type. Copy a list of the count of unnamed free slots of each form factor in each bay of the library up to the MLM Core. Some libraries do not have names for empty slots, so we allow such an LCP to simply provide a count of such slots. Provide some approximate performance information to the MLM Core for the library. The MLM Core may use that information when it is choosing which library to use. For example, a library with an expected cartridge load time of 10 seconds may be preferrable over one with an expected load time of 24 hours.
ready	The ready command and its variations are used to tell the MLM Core the current status of the library, ie: is it available for cartridge operations? ready The LCP has already resynchronized its internal information with the physical state of the library, including any modifications to the slotmap information in the MLM Core. For example: on a sighted, SCSI-based robot whose door has just been closed, when the barcode inventory completes, the LCP would report ready to the MLM Core. An activate command should result in an ready command being sent to the MLM Core when the LCP is ready. This gracefully handles an LCP/library pair that take a significant amount of time to resynchronize their state (eg: the barcode scan time). ready not The library is unavailable for cartridge operations for the reason given in the command. For example: this could be a result of someone opening the front door of a robotic library. The LCP will send an ready command when it can again accept cartridge operations. ready disconnected The ready disconnected command is used to tell the MLM Core that the LCP has lost contact with the library, and that an alternate control path (ie, another LCP) might be used. For example: if someone kicked out the control cable from the current host to the library, using another host might bypass the problem. ready broken The ready broken command is used to tell the MLM Core that the LCP library has developed an unrecoverable hardware error and is now unusable. This differs from ready lost in that there is no point in trying another LCP (another control path) since the hardware is broken.
attribute	The attribute command is used to set and unset named attributes in the MLM Core in order to create persistent storage for whatever the LCP deems necessary. The MLM Core simply stores these attributes, there are never any side effects of setting them.
show	The show command is used to obtain the value of an attribute that was stored in the MLM Core by the LCP.
cancel	The cancel command is used to prevent the execution of a command that has already been queued in the MLM Core but not yet started. The cancelled command will return a response cancelled status, while the response for the cancel command itself will follow. This is really only here for completeness, it is not expected that any LCPs will need to use it.

ALI Specification

Syntactic conventions are the same as for CAPI, including that single quotes may be used in place of double quotes in all contexts.

ALI Command Language Syntax

This syntax is used by the MLM Core when talking to the LCP. The ALI Response Language (ALI/R) syntax is detailed later and is used when the LCP is talking to the MLM Core.

commands mountStmt
unmountStmt
moveStmt
ejectStmt
openportStmt
scanStmt
activateStmt
barrierStmt
resetStmt
exitStmt
attributeStmt
showStmt
cancelStmt
responseStmt

mountStmt mount mountArgs ;

mountArgs /* empty */
task [ string ] mountArgs
drive [ string ] mountArgs
slot [ string string string ] mountArgs

unmountStmt unmount unmountArgs ;

unmountArgs /* empty */
task [ string ] unmountArgs
drive [ string ] unmountArgs
slotid [ string ] unmountArgs
any unmountArgs

moveStmt move moveArgs ;

moveArgs /* empty */
task [ string ] moveArgs
from [ string string ] moveArgs
to [ string ] moveArgs

ejectStmt eject ejectArgs ;

ejectArgs /* empty */
task [ string ] ejectArgs
slot [ string string ] ejectArgs

scanStmt scan scanArgs ;

scanArgs /* empty */
task [ string ] scanArgs
all scanArgs
from [ string ] scanArgs
to [ string ] scanArgs

openportStmt openport task [ string ] ;

activateStmt activate activateArgs ;

activateArgs /* empty */
task [ string ] activateArgs
enable activateArgs
disable activateArgs

barrierStmt barrier task [ string ] ;

resetStmt reset task [ string ] ;

exitStmt exit task [ string ] ;

attributeStmt attribute attributeArgs ;

attributeArgs /* empty */
task [ string ] attributeArgs
type [ string ] attributeArgs
name [ string ] attributeArgs
set [ string string ] attributeArgs
unset [ string ] attributeArgs

showStmt show showArgs ;

showArgs /* empty */
task [ string ] showArgs
type [ string ] showArgs
name [ string ] showArgs
report [ listOfStrings ] showArgs
reportmode [ string ] showArgs

cancelStmt cancel cancelArgs ;

cancelArgs /* empty */
task [ string ] cancelArgs
whichtask [ string ] cancelArgs

responseStmt response responseArgs ;

responseArgs /* empty */
whichtask [ string ] responseArgs
accepted responseArgs
unacceptable responseArgs
success responseArgs
error [ string ] responseArgs
cancelled responseArgs
text [ listOfStrings ] responseArgs

listOfStrings /* empty */
STRING listOfStrings

string STRING

ALI Command Language Examples

mount task['2'] slot["bay 2, slot 12" "AB1234" "side 2"] drive["DLT2"];: If the cartridge in slot bay 2, slot 12 has PCL AB1234, then mount it with side 2 active into the drive named DLT2.
mount task['2'] slot["bay 2, slot 12" "AB1234" "side A"] slot["bay 2, slot 14" "AB1235" "side B"] driveOneOf["DLT2"];: Mount into the drive named DLT2 either the cartridge in slot bay 2, slot 12 with side A active (if it has PCL AB1234), or slot bay 2, slot 14 with side B active (if it has PCL AB1235).
unmount task['2'] drive["DLT1"] slotid["slot 43"];: Unmount the contents of the drive named DLT1 and put that cartridge into slot 43.
unmount task['2'] drive["DLT1"] slotid["slot 43"] slotid["slot 82"];: Unmount the contents of the drive named DLT1 and put the cartridge into either slot 43 or slot 82.
move task['2'] from["bay 4, slot 74"] to["bay 2, slot 93"];: Move the cartridge located in bay 4, slot 74 to bay 2, slot 93. Note that the semantic meaning of the slotID text is LCP dependent, and any internal structure of a slotID is completely opaque to OpenVault. OpenVault will only display a slotID or do a string comparison with another slotID to check for equality, no other operations are defined.
eject task['2'] slot["slot 12" "AB1234"];: Push out of the library the cartridge in slot slot 12 if it has PCL AB1234.
openport task['2'];: Ready the library for the operator to have physical access to the cartridge inventory sufficient to accomplish export/import operations. This usually means unlocking some door(s) and possibly taking the library offline.
scan task['2'] all;: Tell the LCP to go back to the library and (re)verify the PCLs of all the cartridges in the library. When this command starts, the LCP will send the ready not command to the MLM Core. When the resynchronization is complete, the LCP will send the ready command to the MLM Core.
scan task['2'] from["slot 12"] to["slot 14"];: Tell the LCP to go back to the library and (re)verify the PCLs of the cartridges in slots 12, 13, and 14 of the library. The actual semantics calls for at least any slots whose slotID is lexicographically between (inclusive) of the given slotIDs. When this command starts, the LCP will send the ready not command to the MLM Core. When the resynchronization is complete, the LCP will send the ready command to the MLM Core.
activate task['2'] enable;: Tell the LCP to resynchronize itself with the library and do whatever it takes to stay that way. When the resynchronization is complete, the LCP will send the ALI/R ready command to the MLM Core.
activate task['2'] disable;: Tell the LCP to gracefully close everything down, save and local state in the persistent store (if required) and completely stop talking to the library.
reset task['2'];: Tell the LCP to do whatever is required to get the library to go through a full (re)initialization sequence, including any self-diagnostics that it may have. When this command starts, the LCP will send the ready not command to the MLM Core. When the restart and subsequent LCP/library resynchronization is complete, the LCP will send the ready command to the MLM Core.
exit task['2'];: Tell the LCP to push any persistent information back up into the MLM Core, do any other shutdown processing that might be required, then exit.
barrier task['2'];: Tell the LCP to fully complete execution of any commands that were received prior to this command before beginning execution of any commands that might follow this one.
attribute task['2'] type["LCP"] name[""] set["loglevel" "emergency"];: Associate a name/value pair with a global-to-the-LCP attribute named loglevel
attribute task['2'] type["extensions"] name["options"] set["camera" "off"];: Set an attribute of type extensions in the group options called camera to the value off.
show task['2'] type["drive"] name["DLT1"] report["bayID"] reportMode["value"];: Return the value of the attribute named bayID that is associated with the drive named DLT1. This will tell us which bay the given drive is in.
cancel task['2'] whichtask["762"];: Cancel the previously submitted task labelled "762", if possible.

ALI/R Language Syntax

This syntax is used by the LCP when it is talking to the MLM Core. The ALI Command Language syntax is used when the MLM Core is talking to the LCP.

commands responseStmt
messageStmt
configStmt
readyStmt
attributeStmt
showStmt
cancelStmt

messageStmt message messageArgs ;

messageArgs /* empty */
task [ string ] messageArgs
who [ string ] messageArgs
severity [ string ] messageArgs
text [ listOfStrings ] messageArgs

configStmt config configArgs ;

configArgs /* empty */
task [ string ] configArgs
scope [ string ] configArgs
slot [ string string string string string string ] configArgs
bay [ string string ] configArgs
drive [ string string string string string ] configArgs
freeslots [ string string string ] configArgs
delslots [ string ] configArgs
perf [ string string ] configArgs

readyStmt ready readyArgs ;

readyArgs /* empty */
task [ string ] readyArgs
disconnected readyArgs
broken readyArgs
not [ listOfStrings ] readyArgs

attributeStmt attribute attributeArgs ;

attributeArgs /* empty */
task [ string ] attributeArgs
type [ string ] attributeArgs
name [ string ] attributeArgs
set [ string string ] attributeArgs
unset [ string ] attributeArgs

showStmt show showArgs ;

showArgs /* empty */
task [ string ] showArgs
type [ string ] showArgs
name [ string ] showArgs
report [ listOfStrings ] showArgs
reportmode [ string ] showArgs

cancelStmt cancel cancelArgs ;

cancelArgs /* empty */
task [ string ] cancelArgs
whichtask [ string ] cancelArgs

responseStmt response responseArgs ;

responseArgs /* empty */
whichtask [ string ] responseArgs
accepted responseArgs
unacceptable responseArgs
success responseArgs
error [ string ] responseArgs
cancelleD responseArgs
text [ listOfStrings ] responseArgs

listOfStrings /* empty */
STRING listOfStrings

string STRING

ALI/R Language Examples

response whichtask["12"] accepted;

The last ALI command submitted was accepted and put on the task list. Responses from that command will show task label "12" as a way of associating the response with the command.

response whichtask["12"] unacceptable;

The last ALI command submitted was not accepted. There will be no other response for that command.

response whichtask["12"] unacceptable text['Syntax error'];

The last ALI command submitted was not accepted. There will be no other response for that command. This shows the most likely cause of an unacceptable response, the command was not correctly constructed.

response whichtask["762"] success;

Command "762" was sucessfully completed (and produced no output).

response whichtask["762"] cancelled;

Command "762" was sucessfully cancelled before beginning to execute.

response whichtask["robbie23"] success text["outholder1"];

Show command "robbie23" produced a string type result.

response whichtask["robbie486"] success text["236"];

Show command "robbie486" produced a number type result.

response whichtask["84"] success text["AB001" "AB002" "AB003" "AB004" "AB004" "AB005" "AB006"];

Show command "84" produced a list-of-strings type result.

response whichtask["1298"] error ["cartridgeUnknown"] text ["The named cartridge is not in this library"];

Command "1298" was not sucessfully completed, it produced the given error token and user-reable error text string.

message task['2'] severity["information"] text["Cartridge AB1234 mounted into drive Fred"];

Send the given message to the OpenVault log and/or the operator as an informational message.

message task['2'] severity["critical"] who["operator"] text["Gripper error, cannot let go"];

Notify the operator of an internal failure of the robotic mechanism; in this example the robot cannot proceed until the fault has been corrected. Since this is a critical message, at some sites it might trigger a page of the operations staff.

message task['2'] severity["warning"] who["admin"] text["Source slot empty"];

Notify the administrator of an error in the OpenVault's slotmap for the library.

message task['2'] severity["information"] text["Turn the cylinder to face 1" "Start at the top and count down 4 slots" "Remove that cartridge"];

This is an example of a formatted message. It is expected that a user interface will normally flow the text of a long string to fit the current output area. In this example, there is more than one string, and it is expected that a user interface will force a line break between each of the separate text strings. This allows the LCP to control the output (if it chooses) to one of:

Message Structure Resulting Look

"This is a long single string message output by an LCP that is not concerned about a specific structure on the screen." This is a long single string message output by an LCP that is not concerned about a specific structure on the screen.

"This is a set of short messages." "Taken together they have a structure." "But they should also be distinct." This is a set of short messages.
Taken together they have a structure.
But they should also be distinct.

config task['2'] scope["full"] slot[ "bay 4, slot 3" "bay 4" "" "DLT" "occupied" "accessable" ] slot[ "bay 4, slot 4" "bay 4" "" "DLT" "unoccupied" "accessable" ] freeslots[ "bay 4" "DLT" "12" ];

In a non-sighted library, replace the entire slotmap with the information for slotIDs "bay 4, slot 3" and "bay 4, slot 4" and the fact that there are "12" additional "DLT"-sized slots in "bay 4". Note that this example is a non-sighted library, and the PCLs are zero length strings.

config task['2'] scope["partial"] slot[ "bay 4, slot 3" "bay 4" "AB1234" "DLT" "occupied" "accessable" ] slot[ "bay 4, slot 4" "bay 4" "" "DLT" "unoccupied" "accessable" ] delslots[ "bay 4, slot 8" ];

Update the slotmap for slotIDs "bay 4, slot 3" and "bay 4, slot 4" to show the information provided here, and delete slot "bay 4, slot 8" from the slotmap.

config task['2'] scope["partial"] bay[ "bay 2" "accessable" ] freeslots[ "bay 2" "DLT" "3" ] bay[ "bay 4" "inaccessable" ];

Update the bay information for this library to show that "bay 2" is accessable and has 3 unnamed "DLT"-sized slots, and that "bay 4" is now inaccessable.

config task['2'] scope["partial"] drive[ "fred" "" "unoccupied" "inaccessable" ] drive[ "barney" "AB1234" "occupied" "accessable" ];

Update the drive information for this library to show that the drive called "fred" is inaccessable and that the drive called "barney" is accessable and occupied with a cartridge having PCL AB1234.

config task['2'] scope["partial"] perf[ "nominal_load" "10" ];

Tell the MLM Core to expect that the robotics movement component of the time required for cartridge movement operations (ie: mounts, unmounts, or moves) will take about 10 seconds each.

ready task['2'];

Notify the MLM Core that the LCP is ready to accept cartridge operations.

ready task['2'] not["Door openned"];

Notify the MLM Core that the LCP is not ready to accept cartridge operations, and the reason is that someone has openned the door. The LCP may also use the message command to send related information to the operator.

ready task['2'] disconnected;

Notify the MLM Core that the LCP has lost contact with the library and it may be appropriate to try an alternate control path to the library (ie: another LCP).

Possible Error Returns

The following table shows the possible error return values and which commands may return which errors.

Error String	Meaning	ALI Commands
ALI_E_NONE	no error
ALI_E_NOSLOT	unknown slot
ALI_E_NOPCL	unknown PCL
ALI_E_NOBAY	unknown bay
ALI_E_NODRIVE	unknown drive
ALI_E_NOATTR	unknown attribute
ALI_E_NOTYPE	unknown type
ALI_E_NOCMD	unknown command
ALI_E_NOTASK	unknown task id
ALI_E_ACCESS	access denied/object inaccessible
ALI_E_BADVAL	bad attribute value
ALI_E_SRCFULL	source location full
ALI_E_SRCEMPTY	source location empty
ALI_E_DSTFULL	destination location full
ALI_E_DSTEMPTY	destination location empty
ALI_E_AGAIN	retry recommended
ALI_E_READY	target not ready
ALI_E_PCL	PCL mismatch
ALI_E_SEQUENCE	Command sequence error
ALI_E_ABORT	Command aborted by LCP
ALI_E_LIBRARY	library or device driver failure
ALI_E_SHAPE	Cart-drive fungibility error

There are undoubtedly more error codes, but they have not yet been defined.

List of Required Attributes

Each LCP must support the following attributes. They are primarily used for configuration discovery, but some of them might be used for ongoing maintenance.

Quoted values must be used literally as shown. Unquoted values are descriptions or variable names. The following acronyms are used: r/w - readable and writeable, r/o - readable only, w/o - writeable only.

Type Name Attr Name Access Description of Contents

"LCP" "" "name" r/o OpenVault name for that library

"LCP" "" "support_PCLs" r/o true/false: does this lib support PCLs

"LCP" "" "vendor" r/o make and model number of library

"LCP" "" "loglevel" r/w severity level of messages to log

"bayID" bayID "description" r/o prose describing how to physically find that bay in the library

"slotID" slotID "description" r/o prose describing how to physically find that slot in the library

ALI	The language spoken by the MLM Core to the LCP.
ALI/R	The language spoken by the LCP to the MLM Core. The full name is the ALI Response language.

commands	mountStmt unmountStmt moveStmt ejectStmt openportStmt scanStmt activateStmt barrierStmt resetStmt exitStmt attributeStmt showStmt cancelStmt responseStmt
mountStmt	mount mountArgs ;
mountArgs	/* empty / task* [ string ] mountArgs drive [ string ] mountArgs slot [ string string string ] mountArgs
unmountStmt	unmount unmountArgs ;
unmountArgs	/* empty / task* [ string ] unmountArgs drive [ string ] unmountArgs slotid [ string ] unmountArgs any unmountArgs
moveStmt	move moveArgs ;
moveArgs	/* empty / task* [ string ] moveArgs from [ string string ] moveArgs to [ string ] moveArgs
ejectStmt	eject ejectArgs ;
ejectArgs	/* empty / task* [ string ] ejectArgs slot [ string string ] ejectArgs
scanStmt	scan scanArgs ;
scanArgs	/* empty / task* [ string ] scanArgs all scanArgs from [ string ] scanArgs to [ string ] scanArgs
openportStmt	openport task [ string ] ;
activateStmt	activate activateArgs ;
activateArgs	/* empty / task* [ string ] activateArgs enable activateArgs disable activateArgs
barrierStmt	barrier task [ string ] ;
resetStmt	reset task [ string ] ;
exitStmt	exit task [ string ] ;
attributeStmt	attribute attributeArgs ;
attributeArgs	/* empty / task* [ string ] attributeArgs type [ string ] attributeArgs name [ string ] attributeArgs set [ string string ] attributeArgs unset [ string ] attributeArgs
showStmt	show showArgs ;
showArgs	/* empty / task* [ string ] showArgs type [ string ] showArgs name [ string ] showArgs report [ listOfStrings ] showArgs reportmode [ string ] showArgs
cancelStmt	cancel cancelArgs ;
cancelArgs	/* empty / task* [ string ] cancelArgs whichtask [ string ] cancelArgs
responseStmt	response responseArgs ;
responseArgs	/* empty / whichtask* [ string ] responseArgs accepted responseArgs unacceptable responseArgs success responseArgs error [ string ] responseArgs cancelled responseArgs text [ listOfStrings ] responseArgs
listOfStrings	/* empty */ STRING listOfStrings
string	STRING

commands	responseStmt messageStmt configStmt readyStmt attributeStmt showStmt cancelStmt
messageStmt	message messageArgs ;
messageArgs	/* empty / task* [ string ] messageArgs who [ string ] messageArgs severity [ string ] messageArgs text [ listOfStrings ] messageArgs
configStmt	config configArgs ;
configArgs	/* empty / task* [ string ] configArgs scope [ string ] configArgs slot [ string string string string string string ] configArgs bay [ string string ] configArgs drive [ string string string string string ] configArgs freeslots [ string string string ] configArgs delslots [ string ] configArgs perf [ string string ] configArgs
readyStmt	ready readyArgs ;
readyArgs	/* empty / task* [ string ] readyArgs disconnected readyArgs broken readyArgs not [ listOfStrings ] readyArgs
attributeStmt	attribute attributeArgs ;
attributeArgs	/* empty / task* [ string ] attributeArgs type [ string ] attributeArgs name [ string ] attributeArgs set [ string string ] attributeArgs unset [ string ] attributeArgs
showStmt	show showArgs ;
showArgs	/* empty / task* [ string ] showArgs type [ string ] showArgs name [ string ] showArgs report [ listOfStrings ] showArgs reportmode [ string ] showArgs
cancelStmt	cancel cancelArgs ;
cancelArgs	/* empty / task* [ string ] cancelArgs whichtask [ string ] cancelArgs
responseStmt	response responseArgs ;
responseArgs	/* empty / whichtask* [ string ] responseArgs accepted responseArgs unacceptable responseArgs success responseArgs error [ string ] responseArgs cancelleD responseArgs text [ listOfStrings ] responseArgs
listOfStrings	/* empty */ STRING listOfStrings
string	STRING

Message Structure	Resulting Look
"This is a long single string message output by an LCP that is not concerned about a specific structure on the screen."	This is a long single string message output by an LCP that is not concerned about a specific structure on the screen.
"This is a set of short messages." "Taken together they have a structure." "But they should also be distinct."	This is a set of short messages. Taken together they have a structure. But they should also be distinct.

Type	Name	Attr Name	Access	Description of Contents
"LCP"	""	"name"	r/o	OpenVault name for that library
"LCP"	""	"support_PCLs"	r/o	true/false: does this lib support PCLs
"LCP"	""	"vendor"	r/o	make and model number of library
"LCP"	""	"loglevel"	r/w	severity level of messages to log
"bayID"	bayID	"description"	r/o	prose describing how to physically find that bay in the library
"slotID"	slotID	"description"	r/o	prose describing how to physically find that slot in the library

Silicon Graphics, Inc. OpenVault Abstract Library Interface Language Definition