The function of the semantic layer is the same for CAPI and AAPI. It is responsible for the following:

The parser and generator layer uses the POSIX compliant GNU utilities bison and flex, and is responsible for the following:

The over-the-wire CAPI and CAPI/R layer employs nothing but ASCII strings, and is responsible for the following:

The OpenVault IPC layer is responsible for the following:

The TCP/IP socket layer employs standard networks to aid portability.

The eject command is used by an administrative application when it wants to have a media cartridge pushed out of a library into a human's hand. The syntax is as follows:

eject
{ task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

The match operator must resolve to a library.

Example 2-6 asks the alexandria library to eject the cartridge in slot 24:

eject match [and(
      strEQ (LIBRARY."LibraryName" "alexandria")
      strEQ (SLOT."SlotName" "slot 24"))]
   task["0"];

The inject command is used by an administrative application when it wants to allow the human operator to insert a cartridge into a library. The syntax is as follows:

inject
{ task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

The match operator must resolve to a library.

Example 2-7 requests the alexandria library to accept a new cartridge:

inject match [strEQ(LIBRARY."LibraryName" "alexandria")] task["0"];

The mount command provides data access to one or more volumes, partitions, or sides. Things to be mounted may be explicitly enumerated or may be implicitly declared by a match operator. The syntax is as follows:

mount
{ mountMode [mountMode]
  volname [volNameSpec ...] 
  task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)]
  report [reportSpec] 
  reportMode [modeName]}; 

See “Semantics of Common Syntactic Elements”, for information about the match, order, number, and report operators.

Table 2-2 lists the tokens that specify different mount modes.

The following default applies only to the mount command:

mountMode ["read" "write"]

The following defaults apply to all commands containing a number or reportMode clause:

number [FIRST..LAST]
reportMode [value]

Whether volumes are explicitly or implicitly enumerated, any number of volumes may be specified for mounting. Some volumes must be mounted read-only, others read-write, or an application can specify a preference, if mount mode is not volume dependent.

Example 2-8 mounts volume myVolume-003 for reading and writing:

mount mountMode ["read" "write"] volname ["myVolume-003"]
   task["0"]; 

Example 2-9 mounts the first available DLT volume that is less than 60% full for reading and writing (note that percentFull is a user-defined token):

mount mountMode ["read" "write"]
  number [FIRST] match [and(
    strEq (CARTRIDGE."CartridgeTypeName" "DLT") 
    numLe (VOLUME."percentFull" "60"))
    task["0"]]; 

The move command is used by an administrative application when it wants to have a cartridge moved from one library slot to another. The syntax is as follows:

move
{ fromslot [slotID] 
  fromPCL [PCL] 
  toslot [slotID] 
  task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]};  

Example 2-10 moves the cartridge labeled AB1234 from slot 12 to slot 24 in the library named alexandria if all these objects exist:

move match [strEQ(LIBRARY."LibraryName" "alexandria")] 
  fromslot ["slot 12"] fromPCL["AB1234"] toslot["slot 24"] task["0"]; 

---

Note: The reject command is not supported in the OpenVault releases 1.x.

---

Implemented but currently disabled, this allowed applications to refuse acceptance of OpenVault-assigned volumes. It is unclear whether this should be allowed.

When an application is done accessing a partition, side, or volume, it can use the unmount command to free the drive for use by another application. The unmount command must specify currently mounted volumes, either by enumerating volumes to be unmounted, or by means of a match operation. The thing to be unmounted must be mounted when this command is given. The syntax is as follows:

unmount
{ volname [volNameSpec ...] 
  task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

The unmount command does not immediately unload media--delay is affected by the default unload time specified as drive group attribute (DriveGroupUnloadTime).

Example 2-11 unmounts volume myVolume-003:

unmount volname ["myVolume-003"] task["0"]; 

Example 2-12 unmounts the two volumes in pool servers that are nearest to full capacity (note that all these VOLUME attributes are user-defined tokens):

unmount number[2] 
  order [numHiLo(VOLUME."percentFull")] match [and ( 
    strEq (VOLUME."allFull" "true") 
    strEq (VOLUME."pool" "servers"))
  task["0"]]; 

Unprivileged applications may obtain ownership of cartridges and create new volumes on those cartridges by using the allocate command. When a volume is created, it immediately takes its place next to all other volumes owned by that application. No other non-privileged application can see the new volume or allocate a volume on the same cartridge. The syntax is as follows:

allocate 
{ volname [volNameSpec] ... 
  task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

In Example 2-13, OpenVault allocates any convenient volume as the first named Servers:

allocate volname ["Servers.001"] task["0"]; 

An administrative application may modify the values of object attributes in OpenVault. The attribute command modifies behavior-controlling object attributes, thus permitting administrative control of the MLM server. The syntax is as follows:

attribute
{ volname [volNameSpec] ... 
  task [taskID]
  match [matchSpec(s)] 
  order [=orderSpec(s)]= 
  number [=number(s)]= 
  set [setSpec(s)] 
  unset [unsetSpec(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

Applications can also use the attribute command to attach or remove non-system-defined attribute-value pairs from objects in the system.

When using the attribute command, the list of objects to operate on is primarily specified using the match element. There are additional elements that can be used to order the list of objects and even to restrict that list to a certain subset.

An application may disassociate attributes that it has associated with an object in exactly the same way it associated them, except that it will use the unset rather than the set operator. Set and unset operators may be freely mixed, but a single attribute command may not contain more than one set or unset operator referencing the same attribute.

---

Note: System-defined attributes may not be disassociated from an object. Any attempt to do so returns an error. Example 2-14 and Example 2-15 show how you can use the attribute command.

---

attribute 
   match [strEQ( VOLUME."VolumeName" "vol001")]
   set [VOLUME."PartitionName" "PART 2"]
   task ["0"];

attribute
   match [and (strEQ(SLOT."SlotName" "Slot 1")
         strEQ(SLOT."BayName" BAY."BayName")]
   set [SLOT."SlotOccupied" "true"]
   report [BAY."BayName"]
   task ["0"];

Administrative applications may create new objects. Once an object has been created, it immediately takes its place next to all other objects of that type. The syntax is as follows:

create type [tableNameSpec] 
{ set [setSpec] ... 
  task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

The application must specify all required attributes for the type of object being created, or the MLM server returns failure. The application may specify additional attributes and values beyond those required.

In Example 2-16, the administrative application creates an object of type LIBRARY named alexandria in group physics but not currently online:

create type [LIBRARY]
   set [LIBRARY."LibraryName" "alexandria"]
   set [LIBRARY."Group" "physics"]
   set [LIBRARY."Online" "false"]
   task["0"];

Applications may delete volumes that they own. The volume immediately disappears-- there is neither a grace period nor an undo operation. Lacking a volume name, that portion of the cartridge is no longer available to the application for mount operations. Non-privileged applications can delete only volumes that they own, but they can do so at any time and with no restrictions. The syntax is as follows:

deallocate 
{ volname [volNameSpec] ... 
  task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

In Example 2-17, OpenVault deallocates the volume named Servers.001:

deallocate volname ["Servers.001"] task["0"]; 

Administrative applications may delete existing objects by using the delete command. Deleted objects disappear immediately--there is neither a grace period nor an undo operation. The syntax is as follows:

delete type [tableNameSpec] 
{ task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

Permission to delete an object is subject to the internal consistency constraints of MLM. If the object is still in use or being referenced by other objects, then the delete operation fails. For example, a LIBRARY object may not be deleted until all DRIVE objects for that library have been deleted.

In Example 2-18, the administrative application deletes the LIBRARY object named alexandria previously created:

delete type [LIBRARY] match [strEQ(LIBRARY."LibraryName" "alexandria")]
   task["0"];

An administrative application may delete volumes from the list known to the MLM server, using the forget command. The volumes cannot be in use by any application. The syntax is as follows:

forget
{ volname [volNameSpec] ... 
  task [taskID]
  match [matchSpec(s)] 
  ordermm [orderSpec(s)] 
  number [number(s)] 
  reportm [reportSpec] 
  reportModem [modeName]}; 

In Example 2-19, the lack of an application name might cause the MLM server to delete database information for several volumes from different applications:

forget match [strEQ(VOLUME."VolumeName", "servers.001")]
   task["0"];

Example 2-20 is more limiting and thus more realistic:

forget match [and (strEq (APPLICATION."ApplicationName" "deadApp")
     strEq (CARTRIDGE."CartridgeTypeName" "8mm-112m"))]
  task["0"];

Client applications may rename their own volumes, while administrative applications may rename any volumes, using the rename command. The syntax is as follows:

rename
{ volname [volNameSpec] 
  volnewname [volNameSpec]
  task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

Because Example 2-21 contains no match component, this command renames all volumes of that name, no matter which application owns the volumes.

rename volname ["servers.001"] volnewname ["servers.003"] task["0"];

The show command displays data from the OpenVault environment to application users, often in ways not directly supported by the MLM server. The syntax is as follows:

show
{ volname [volNameSpec] ... 
  task [taskID]
  match [matchSpec(s)] 
  order [orderSpec(s)] 
  number [number(s)] 
  report [reportSpec] 
  reportMode [modeName]}; 

The application may use the match operator to select objects to be operated on, the order operator to specify that the results of the command be ordered in some manner, the number operator to specify that only certain numbers of records be returned, the report operator to specify attributes of the selected objects to be returned, and the reportMode operator to specify how the results should be formatted.

---

Caution: Things can change in MLM between show commands or between a show command and a command intended to act on the information returned by show.

---

In Example 2-22, OpenVault reports about all drives known to the MLM server:

show report [DRIVE."DriveName"]
   task["0"];

In Example 2-23, the MLM server selects bay 1 in the library named alexandria, sorts the slot names in ascending order, and reports the names of the first four:

show match [and (strEQ (LIBRARY."BayName" "bay 1")
     strEq (LIBRARY."LibraryName" "alexandria"))]
  order [strLoHi (SLOT."SlotName")]
  number [1..4]
  report [SLOT."SlotName"]
  reportMode [nameValue]
  task["0"];

An attribute may be interpolated by referring to its object type and field name. This syntax is used in combination with the match and order operators. The object type is chosen from a predefined list; see Table 2-1. The field name may be predefined or user defined. The object type is all uppercase, while the field name is enclosed in quotes:

OBJECTTYPE."fieldname" 

Example 2-24 reports the physical cartridge labels of all the volumes named servers.001, from all applications shows all on the servers.001 volume:

show volname ["servers.001"] report[CARTRIDGE."CartridgePCL"]; 

Example 2-25 reports the name of the library containing the physics1 drive:

show match [strEQ(DRIVE."DriveName" "physics1")] 
report [LIBRARY."LibraryName"]; 

The volname operator restricts the set of volumes to which a command is applied. It is shorthand for a much more complicated match statement as shown in Example 2-26.

volname ["servers.001" "servers.002" "servers.003" ] 

match [ or( 
  strEQ (VOLUME."VolumeName" "servers.001") 
  strEQ (VOLUME."VolumeName" "servers.002") 
  strEQ (VOLUME."VolumeName" "servers.003") 
)]; 

---

Note: If the volname operator is given, it is illegal to supply a match operator also.

---

The match operator restricts the set of objects to which a command is applied. Restriction is accomplished by applying various functions to specified object attributes in order to determine true or false status, which in turn determines membership or exclusion from the working set. As an example, suppose the current working set of volumes and attributes is shown in Table 2-3:

With that working set, Example 2-27 shows the match statement returns vol3 as its result (the Ne in strNe means not equal to):

match [and( 
  strEq (VOLUME."Group" "Servers")
  strNe (VOLUME."Handler" "Marge")
)]; 

Roughly translated, the match statement would read: “Find volumes where the Group attribute is set to Servers and the Handler attribute is not set to Marge.” After evaluation, only the volume named vol3 and related objects remain in the working set.

The order operator sorts the set of objects in the working set. It is useful in cases where the application wants to optimize its activities as much as possible.

As an example, suppose the current working set of volumes and attributes is shown in Table 2-4:

With that working set, this order statement returns vol3 vol1 vol2 vol4 as its result:

order [numHiLo(VOLUME."percentFull")]; 

The number operator declares which elements in the current working set are reported. The elements given after number specify ordinal numbers of items in the work list for further operation. It is possible to specify both single items and ranges of items.

A range is specified by numbers separated by two periods (..) and includes elements at each end of the range. The additional tokens FIRST and LAST refer to the initial and final elements of the work list. Negative numbers are offsets from the end of the work list.

The specification number [1 3 5] means that the first, third, and fifth items from the ordered work list should be used. Specifications number [2..4] and number [2 3 4] are identical. The specification number [FIRST..3 7..-8 -3..LAST] is equivalent to number [1 2 3 7 8 9 14 15 16] if there are 16 elements in the working set.

As an example, suppose the current working set of volumes and attributes is shown in Table 2-5:

Example 2-28 shows the output that is produced by the number and report statements using this working set:

number[2 4] 
report [VOLUME."group" VOLUME."VolumeName" VOLUME."handler"]
text ["Clients" "vol2" "Sam"] 
text ["Clients" "vol4" "Marge"] 

The report operator declares attributes or attribute values that are to be returned by the current command.

The reportMode operator declares whether the report contains only the “name” of each reported attribute, only the “value” of each attribute, or both (specified as “nameValue”).

As an example, suppose the current working set of volumes and attributes is shown in Table 2-6:

Example 2-29 shows the output produced a report statement and that working set:

report [VOLUME."group" VOLUME."VolumeName" VOLUME."handler"]
text ["Servers" "vol1" "Marge"]
text ["Clients" "vol2" "Sam"]
text ["Servers" "vol3" "Bill"]
text ["Clients" "vol4" "Marge"]

Example 2-30 shows the output produced when a reportMode statement is added:

reportMode [nameValue]
text[
  text [VOLUME."group" "Servers"]
  text [VOLUME."VolumeName" "vol1"]
  text [VOLUME."handler" "Marge"]]
text[
  text [VOLUME."group" "Clients"]
  text [VOLUME."VolumeName" "vol2"]
  text [VOLUME."handler" "Sam"] ]
text[
  text [VOLUME."group" "Servers"]
  text [VOLUME."VolumeName" "vol3"]
  text [VOLUME."handler" "Bill"]]
text[
  text [VOLUME."group" "Clients"]
  text [VOLUME."VolumeName" "vol4"]
  text [VOLUME."handler" "Marge"]]

The text operator is a general container for lists of character strings or object references. In some contexts, such as the use of this operator in the rename command, the number of and content of strings that can be enclosed by the text operator may be constrained. But usually, command responses are encapsulated in one or more text statements.

Example 2-31 shows use of the text operator in a reject command:

reject volname ["myVolume-003"] 
text ["This is not what I thought it was"];