The instantiation of a drive access method--the implementation of a particular set of capabilities that describe a mode of access to the drive; this is equivalent to a UNIX device special file or dev node.

ADI commands become objects as far as ADI is concerned. When the MLM server sends an ADI 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 a DCP receives a command, it includes the task ID in command responses.

A place where a cartridge may be mounted and its media loaded for read/write access. For a conceptual view, see Figure 5-1.

Each DCP manages the configuration of drives, and performs drive control tasks associated with mount and unmount requests from OpenVault client applications. The main purposes of a DCP are to expose drive configuration to the MLM server, and to control drives that have an OpenVault accessible control interface.

See Chapter 6, “Programming a Drive Control Program (DCP)”, for a tutorial on DCP programming.

A region on the cartridge media that has a physically marked beginning and end, both of which the drive recognizes.

A drive has an associated set of capabilities, which describe specific feature settings. Capabilities determine which device driver to use for control and data requests, what device settings to select, and device state to check. Particular combinations of capabilities represent a particular mode of access. A drive has a configurable set of legal access modes, each of which represents a logical instance of the drive with underlying control and access methods. The use of canonical capabilities and modes of access is what permits a DCP to hide implementation details such as the underlying local control and access methods for the device.

A control interface to the drive that is accessible by the DCP, and possibly by OpenVault client applications on the DCP host. Typically, a drive is connected to a host by a local channel or bus. This connection represents the control path to the drive.

A connection between the DCP host and the drive media access point that may be accessible by the DCP and MLM client applications on the DCP host. Drives with a control path typically also have a data path, with control and data paths sharing the same connection, with access through a local device driver. For drives with a data path, DCP may require access to that data path, for example to identify a partition. A drive media access point may lack a data path. For example, a set of RGB lines attaching a video drive to a display device lacks a host connection, so applications do not have access to it.

A local binding between a name, such as a device pathname, and a logical instance of the drive, such as a device node that corresponds to a particular mode of access. The name is called a drive handle. For drives that have a data path, the drive handle may be passed to and used by an OpenVault client application to send drive control or access the media. When the binding is removed, the drive handle is invalidated.

Recordable surface(s) upon which data are read or written. A cartridge may contain one or more pieces of media. Associated with this and the drive is a bit format, which determines the recording format. Together with media type, bit format determines media storage capacity.

A cartridge must be moved and the media it contains engaged at a media access point before the media can be read/write accessed. This is the component that reads and writes the media contained by a cartridge. The cartridge, media, or media access point may physically restrict access to the media. For instance physical access may be restricted to read only. Once media is engaged at the media access point, media data may be accessed through the drive data path.

The physical drive opening where a cartridge may be placed, often called the drive door. A cartridge must be present at the mount point before the cartridge and the media it contains can be engaged at the media access point. When the media is disengaged from the media access point (and returned to its cartridge, as necessary), the cartridge is returned to the mount point.

A DCP developer may also maintain arbitrary attributes, and store them in and recover them from the MLM server persistent store. These attributes are opaque to the MLM server.

A DCP developer may store the loglevel mandatory attribute in the MLM server persistent store, so it can recover the attribute and resume logging at the same level across reboots.

Refers to a specific drive, and is the name by which a client identifies itself in a HELLO command to the MLM server. This is the name the MLM server associates with the device managed by the associated DCP.

Each DCP is uniquely named by a value pair including an OpenVault client name and an OpenVault instance name.

Refers to a particular drive access method instance.

Refers to a removable media drive.

This name is arbitrary, but is needed if multiple DCPs control the same drive, so as to differentiate DCPs with the same client (drive) name.

References the name for a media partition.

Uniquely identifies a sender-generated command.

Starts and stops the DCP and drive interactions. Once the DCP has established a session with the MLM server with a hello-welcome sequence, it may begin accepting ADI commands from the server. However, until it has successfully been activate enabled by the server, and is in ready state, it should resend ready lost state and fail any ADI commands that require drive access, with an ADI_E_READY error.

The DCP should issue one of the ready command variations when it finishes processing the activate request. activate is supported for all drives managed by OpenVault, but is not an implemented operation for drives that lack an OpenVault control interface.

Note that activate may require the DCP to have access to a drive data path, in addition to a control path; otherwise, it may be not an implemented operation.

Selects the appropriate logical instance of a drive according to the access mode specified by the MLM server. Attach instantiates this access method as needed, and binds an opaque drive handle to the logical instance (on UNIX systems, this means linking to a device node). The drive handle must be unique on the DCP host, and may be generated by the DCP, or specified by the MLM server. The DCP returns an error if it detects that the drive handle is already in use on the local host.

Generally, the MLM server invokes attach as part of drive selection for a CAPI mount, after loading. This command is supported for all drives managed by OpenVault, but is not an implemented operation for drives that lack a data path.

In the case of partitioned drives (such as two-sided optical disc units), the drive handle that is created may be dependent on the partition. For example, most disks on UNIX systems have the partition to be accessed encoded in the drive handle (the device node). The loaded media is positioned to the specified partition. Partition names may be defined; see Section 6.5 in Chapter 6, for a list of partition names.

Typically, drives have a shared control and data path. In this case, the drive handle that is passed back to the MLM server is ultimately passed back to an OpenVault client application. The application uses the drive handle to establish access to the drive control/data path.

The attach command allows the MLM server to change drive access mode multiple times, without changing any names from the client application's perspective. However, the application must reestablish access after each attach for the change to affect the application.

The MLM server ensures that drive access mode is consistent with drive capabilities.

Provides an attribute, a mechanism by which information that is not contained in normal configuration data passed to the MLM server can be accessed. Examples include data that is unique to a drive type, or data that varies over time. Attributes may read/write or read-only. If the attributes represent internal information or settings associated with the drive itself, the DCP sends corresponding requests to the drive, then returns that information. See Section 5.1.4.

Attempts to stop execution of a command sent to the DCP. The DCP is free to continue the execution of the command if the command has proceeded too far to cancel.

---

Note: The cancel and response commands may not be cancelled.

---

Removes the logical instance as necessary, and the binding created by an attach command (on UNIX systems, this means unlinking a device node associated with the device). The detach command invalidates the drive handle created by a previous attach command. For drives with a shared control and data path, this disables a client application from establishing access to drive control and data paths through this handle.

Generally, the MLM server invokes this command as part of drive deselection for a CAPI unmount, before unloading. This command is supported for all drives managed by OpenVault, but is not an implemented operation for drives that lack a data path.

The MLM server and the DCP should try to ensure that applications do not continue to access drive control or data through a drive handle that has been invalidated by detach. Note that detach and attach may have no immediate impact on an application that was already accessing the drive control and data paths. Once the application has established its access, it may proceed to access the drive control and data paths, without being affected by subsequent invocations of attach and detach.

A case in point is with random access media and UNIX applications that perform an open (read/write) and close system call sequence in which the drive handle is passed by the application as an argument only to open(). In this case, the effects of the attach or detach command may occur only during the open() call. The detach and attach commands may have no effect on any reads and writes that are made between open and close.

Tells the DCP to store any persistent DCP and drive information to the MLM server, complete or cancel pending ADI commands, complete or abort pending drive operations, do shutdown processing as required, send ready lost and goodbye commands to the MLM server, and exit.

Tells the communicating DCP to end this session.

Moves the cartridge (if a cartridge is present at the drive mount point) to the media access point, and engages it, making it accessible at the media access point. The drive is then called loaded.

Minimally, load verifies that the drive is loaded. This command does not identify which media is engaged. It is invoked by the MLM server as part of a CAPI mount request. Normally, the ALI mount command associated with the CAPI mount loads the drive (the library causes the load to occur), so DCP load needs to verify only that the drive is loaded.

This command is supported for all drives managed by OpenVault, but is not an implemented operation for drives that lack an OpenVault control interface.

Tells the DCP to force the drive to reinitialize. This may also cause the drive to execute self-diagnostics. This is a best-effort type of command. If it is possible to reset a drive only by resetting the whole SCSI bus, thereby interrupting other transfers on that bus, the DCP is free to treat this command as not an implemented operation.

If reset is a prolonged drive activity, the DCP should send a ready not command to indicate that its drive is temporarily not available, followed by a ready command when the drive becomes available again.

Acknowledges and indicates success or failure of an ADI/R command. The optional text portion of the response contains error details or command results.

Is the attribute query mechanism. Note that show commands that query information directly from a drive may require that a DCP have access to a data path with the drive, and otherwise may return an error. See Section 5.1.4.

Disengages the media from a loaded drive, returns it to the cartridge as necessary, and returns the cartridge to the drive mount point. The drive is said to be unloaded at this point. This command rewinds media before disengaging, as necessary. It is invoked by the MLM server as part of a CAPI unmount. Minimally, it detects whether the drive is already unloaded.

This command is supported for all drives managed by OpenVault, but is not an implemented operation for drives that lack an OpenVault control interface.

The ADI/R response is responsible for returning drive usage and error statistics as transmitted on pages 2 through 5 of the SCSI log:

response whichtask["A"] success
    text ["bytes written" "32768" "softerrors" "0" ... ];

ADI/R commands become objects as far as ADI/R is concerned. When a DCP sends an ADI/R 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 the MLM server receives a command, it includes the task ID in command responses.

A text message to be entered into an MLM server-managed log, and perhaps displayed on some console by the MLM server, or one of its administrative applications. Messages are associated with a severity level, or a level of urgency, which determines (along with site policy) whether the message text is stored in the MLM server logs, displayed on a library or OpenVault console for the operator, or both.

Refers to a text message of a given severity level.

Uniquely identifies a sender-generated command.

With an attribute command, the DCP stores persistent state in the OpenVault database.

Tells the MLM server to prevent execution of a particular command, if possible.

---

Note: The cancel and response commands may not be cancelled.

---

Tells the MLM server what access modes are supported, with the form factors, media formats, and performance characteristics for each. The config command copies configuration information, such as the capabilities of a drive, from the DCP to the MLM server. The MLM server stores a nonauthoritative copy of all such information for all the DCPs it controls. Each DCP must use the config command to update configuration information whenever it changes.

The config command is shorthand for sending attributes about a drive to the MLM server. See Section 5.1.4, and Section 6.5 in Chapter 6, for more information.

In a full scope, all information associated with the DCP should be deleted and replaced with the information listed by config. By contrast, in a partial scope, only the pieces of information about the DCP that are listed by config should be replaced. Normally, full scope is used only at startup time, or when making major changes to drive configuration.

The config command gives the MLM server a list of access modes that the drive offers. Each mode has a name and additional characteristics:

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 a DCP exited other than the TCP/IP keepalive option. keepalive helps recover from process failures, but a DCP should send a goodbye before exiting to prevent unnecessary continuation of connection resources.

Provides a method for the DCP to send a message to the operator or to a log file. It contains a list of uninterpreted character strings.

With a ready command, the DCP informs the MLM server about the current status of its drive connection. Like the config command, the ready command is shorthand for sending drive attributes to the MLM server.

These are variations of the ready command:

See Section B.3 in Appendix B, for more detailed information.

Acknowledges and indicates success or failure of an ADI command. The optional text portion of the response contains error details or command results.

With a show command, the DCP queries persistent state it has stored in the OpenVault database.