Silicon Graphics, Inc.
OpenVault
Client Application Programming Interface (CAPI)
and
Administrative Application Programming Interface (AAPI)

The OpenVault Client Application Programming Interface (AAPI) and the OpenVault Administrative Application Programming Interface (AAPI) are the languages and interfaces that OpenVault client and administrative programs use to communicate with MLM. CAPI and AAPI commands to MLM and responses from it are nominally human-readable ASCII strings.

Access to MLM is session-oriented. The application initiates a session with the hello command, and ends by sending a goodbye command. See the HELLO Language Specification for more detailed information on session initiation. After session initiation the application may send commands to the server to query and modify various pieces of system state information or to exercise physical device control.

CAPI/AAPI Operational Model

The Client/Administrative Application Program Interfaces use a hybrid of an object/attribute interface and function-oriented commands to accomplish all the various tasks that are required in a low-level media-management system.

The CAPI/AAPI command-response format is a semi-asynchronous one. After submitting each command, the application must wait for the server's acknowledgement of receipt of the command, but need not wait for the results of the command before sending the next one.

From the client's point of view of a single command in a session, the sequencing is that the client sends a command, waits for MLM's acknowledgement of receipt of that command, and then sometime later MLM sends the client the response to the command. Since the client is required to put a task identifier on each CAPI/AAPI command, if the client can guarantee that those identifiers are unique within the context of a session, then the application can determine which response goes with which command. A couple example, with real CAPI/AAPI commands, may serve to clarify this idea:

Client sends command (direction of arrow indicates sender-- the right arrow indicates that the client is sending to MLM; the left arrow indicates the reverse):

Client sends command to MLM:

--> mount task["1"] match[streq(VOLUME."VolumeName" "v1")];

MLM sends acknowledgement of receipt:

<-- response task["1"] accepted;

Sometime later, MLM sends response to command:

<-- reponse task["1"] success;

Since the application can determine which response came from the execution of each individual command, the sequence could look something more like this:

--> mount task["1"] match[streq(VOLUME."VolumeName" "v1")];
<-- response task["1"] accepted;
--> attribute task["a43"] match[streq(VOLUME."VolumeName" "v1")] set[VOLUME."Color" "green"];
<-- response task["a43"] accepted;
<-- response task["a43"] success;
<-- response task["1"] success;

Note that in this example, the application sent its second command before the first command had completed execution. In fact, in this particular example, the second command completed its execution before the first.

SGI will provide sample CAPI/AAPI communications libraries which can be used either in a fully synchronous or in the native semi-asynchronous manner.

Objects and Their Attributes

OpenVault defines 34 types of objects that make up a media environment. A complete description of the objects, their attributes, and how they relate to each other is in the OpenVault Object Definitions document.

Relationships Between Objects

OpenVault objects are all related to each other. Some relationships are physical, eg: partitions, sides, and cartridges, or slots, bays, and libraries. And some relationships are logical, eg: applications, volumes, and partitions.

Those relationships must be understood in order to effectively administer the OpenVault environment.

Function Oriented Commands

In addition to objects and their attributes, an administrative application can directly cause some operations to occur. For example, an application can eject a cartridge from a library into an operator's hand.

There is a set of commands in the AAPI language that implement those operations. The objects and the attributes that control them are still active and will influence exactly what happens when one of the operation-oriented commands is executed. For example, the current value of any drive group attributes on the drives in the system will affect an AAPI mount command by influencing which drives are candidates for the mount.

Security Model

The OpenVault security model in general is based around both applications and the limitations of the interface that that application has access to. A normal client application only has access to the CAPI interface, with the limitations in control that that implies: no visibility into other applications's namespaces for volumes, read-only access to drive or library attributes, no ability to directly create or destroy objects, etc. An administrative application has access to the much more powerful AAPI language, implying: read-write access to attributes on any object in the system, and the ability to create and destroy objects.

CAPI client applications are protected from each other, but all AAPI applications share complete access to the entire system. It is expected that in Release 1 of Openvault only trusted applications will be granted access to the AAPI interface.

AAPI Command Descriptions

CAPI/AAPI commands fall into three basic groupings: session management, database manipulation, and device control. (Commands marked with an asterisk (*) are not available to CAPI applications):

• Session Management:
  hello (see HELLO Language Specification)
  goodbye
  attach
  detach
  

• Database Manipulation:
  create *
  delete *
  show
  attribute
  rename
  forget *
  

• Device Control:
  mount
  unmount
  move *
  eject *
  insert *
  

Session Management

• hello

  The hello command is used when the application wants to initiate its connection to MLM. Please see the HELLO Language Specification for more information than is given here.

  Command Specification:

  helloStmt: 'hello' <helloOrdering> ';'
  
  helloOrdering: <clientSpec> | <instanceSpec> | <languageSpec> | <versionsSpec> | <helloOrdering>
  
  clientSpec: 'client' '[' <SHORTSTRING> ']'
  instanceSpec: 'instance' '[' <SHORTSTRING> ']'
  languageSpec: 'language' '[' <SHORTSTRING> ']'
  versionsSpec: 'versions' '[' <versions> ']'
  versions: <SHORTSTRING> versions | NULL
  

  Note: All of the elements of the command must be specified for the command to be syntactically correct, though they may be specified in any order.

  Final Reply Specification:

  helloReply: 'welcome' <versionSpec> | 'unwelcome' <unwelcomeArgs>
  unwelcomeArgs: <errorSpec> | <textSpec> | <unwelcomeArgs> | NULL
  versionSpec: 'version' '[' <SHORTSTRING> ']'
  errorSpec: 'error' '[' <SHORTSTRING> ']'
  textSpec: 'text' '[' <STRING> ']'
  

  Examples and Example Replies:

  hello client['admin'] instance['fred']
      language['AAPI'] versions['1.0' '1.1'] ;
  welcome version['1.1'] ;
  
  hello client['admin'] instance['jane']
      language['AAPI'] versions['1.2' '1.7'] ;
  unwelcome error['EBADVERSION']
      text['No Version Supported'];
      

• goodbye

  The goodbye command is used when the application wants to sever its connection to MLM.

  Example:

  goodbye task['1234'];
      

  Example Reply:

  response whichtask['1234'] accepted;
  response whichtask['1234'] success;
      

  Command Specification:

  goodbye

Database Manipulation

• create

  Administrative applications may create new objects. Once the object has been created, it will immediately take its place next to all the other objects of that type in MLM.

  The application must specify in the create command all of the required attributes for the given type of object being created or the MLM Core will fail the operation. The app may specify additional attributes and values beyond those that are required.

  Examples:

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

  Command Specification:

  create type[tableNameSpec] set[setSpec]* match[matchSpec(s)] order[orderSpec(s)] number[number(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

• delete

  Administrative applications may delete objects. Deleted objects immediately disappear, there is no grace period and no "oops, I didn't really want to do that" recovery.

  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 will fail. For example, a LIBRARY object may not be deleted until all DRIVEs contained in that library have been deleted.

  Examples:

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

  Command Specification:

  delete type[tableNameSpec] match[matchSpec(s)] order[orderSpec(s)] number[number(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

• show

  The show command is used by applications which want to display data from the OpenVault environment to their users, or which which need to combine their queries in ways not directly supported by the MLM Core. Caveat: thngs can change in MLM between show commands or between a show command and a command intended to act on the information returned by the show.

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

  Examples:

  show report[DRIVE."DriveName"]

  show


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

  Command Specification:

  show volname[volNameSpec] match[matchSpec] order[orderSpec(s)] number[number(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

• attribute

  An administrative application may modify the values of attributes of objects in MLM. Administrative control of the OpenVault system is accomplished by modifying those attributes of an object that control its behavior.

  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[] element in the attribute command. Set and unset elements may be freely mixed in attribute commands. Caveat: a single attribute command may not contain more than one set[] or unset[] element which references the same attribute.

  NOTE: system defined attribute may not be disassociated from an object. An attempt to do so will return an error.

  Examples:

  attribute

  match[ strEQ(DRIVE."DriveName", "physics1") ]
set[ DRIVE."color" "red" ];
  attribute

  match[ and (
  
  strEq (DRIVE."color" "blue")
  strEq (DRIVE."LibraryName" LIBRARY."LibraryName")) ]
  
  set[ LIBRARY."hasBlueDrives" "true" ]
  report[LIBRARY."LibraryName"]

  Specification:

  attribute volname[volNameSpec] match[matchSpec] order[orderSpec(s)] number[number(s)] set[setSpec(s)] unset[unsetSpec(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

• forget

  An administrative application may delete volumes from the list of known volumes in MLM. The volumes cannot be in use by any application.

  Examples:

  forget match[ strEQ(VOLUME."VolumeName", "servers.001") ]
  (Note that this might forget several volumes from different apps)
  forget

  match[and (

  strEq (APPLICATION."ApplicationName" "deadApp")
strEq (CARTRIDGE."CartridgeTypeName" "8mm-112m"))]
  (Note that this example is much more realistic)

  Specification:

  forget
  
  match[matchSpec] number[number(s)] order[orderSpec(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

• rename

  Any application may rename its volumes; while administrative applications may rename any volumes.

  Examples:

  rename volname[ "servers.001" ] volnewname[ "servers.003" ]

  Since there is no match[] element, this will rename all volumes of that name, no matter which application owns it.

  Specification:

  rename volname[volNameSpec] volnewname[volNameSpec] match[matchSpec] number[number(s)] order[orderSpec(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

Device Control

• mount

  The mount command in AAPI is used by an administrative application when it wants 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[] element. The match[] element will have access to the entire space of partitions, sides, and all volumes of all applications.

  Please refer to the show command, the Glossary of match functions, and the Semantics of Common Syntactic Elements sections for more information.

  Whether volumes are explicitly or implicitly enumerated, a number of volumes may be specified for mounting. Volumes may be required to be mounted read-only or read-write, or an application can specify a preference, where a preference is explicitly not a requirement.

  Examples:

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

  mount

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

  Specification:

  mount
  
  mountMode[mountMode] volname[volName(s)] match[matchSpec] order[orderSpec(s)] number[number(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  mountMode["read" "write"]
  number[FIRST..LAST]
  reportMode[value]
  

• unmount

  When the application is done accessing a partition, side or volume, it may use the unmount command to free the drive being used for use by itself or by another application. The unmount command must specify currently-mounted volumes, either by enumerating the volumes to be unmounted, or via a query operation. The thing specified to be unmounted must mounted at the time of the unmount command.

  The unmount command will not necessarily unload the media, that is affected by the default unload time specified as an attribute of the Drive Group the drive is in.

  Examples:

  unmount volname["myVolume-003"] ;

  unmount

  number[ 2 ]
  order[numHiLo (VOLUME."pctFull")] match[and (
  
  strEq (VOLUME."allFull" "true")
  strEq (VOLUME."pool" "servers") ) ] ;
  

  Specification:

  unmount
  
  volname[volName(s)] match[matchSpec] order[orderSpec(s)] number[number(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

• move

  The move command is used by an administrative application when it wants to cause a cartridge to be moved from one slot in a library to another.

  Examples:

  move match[ strEQ (LIBRARY."LibraryName" "alexandria") ]

  fromslot["slot 12"] fromPCL["AB1234"] toslot["slot 24"] ;

  Specification:

  move
  
  fromslot[slotid] fromPCL[PCL] toslot[slotid] match[matchSpec] order[orderSpec(s)] number[number(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

• eject

  The eject command is used by an administrative application when it wants to cause a media cartridge to be pushed out of a library into a human's hand.

  The match[] element must resolve to a library.

  Examples:

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

  Specification:

  eject match[matchSpec] order[orderSpec(s)] number[number(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

• inject

  The inject command is used by an administrative application when it wants to allow a human to insert a cartridge into a library.

  The match[] element must resolve to a library.

  Examples:

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

  Specification:

  inject match[matchSpec] order[orderSpec(s)] number[number(s)] report[reportSpec] reportMode[modeName]

  Element Defaults:

  number[FIRST..LAST]
  reportMode[value]
  

Semantics of Common Syntactic Elements

There are several syntactic elements which are common to many AAPI and CAPI commands. These include match[], order[], number[], report[], reportMode[] and others. In the interest of general utility, the meaning of each of these elements is constant no matter which command it is found in.

General Order of Operations for Commands

1. Start with whole object name space as our work set.
2. Restrict work set to objects which match specified attribute criteria, using match[] element.
3. Order the work set by sorting on values of specified attributes, using order[] element.
4. Select certain ordinal items from the ordered work set using the number[] element.
5. Report specified attributes from the objects which are in the final work set. The report[] and reportMode[] elements work together to influence the output.

Description of Specific Syntax Elements

The syntax elements described in the sections below are "executed" in the order explained above.

• OBJECTTYPE."fieldname"

  The OBJECTTYPE."fieldname" syntax is how a particular attribute of an object is referenced. This is mostly used in the match[] and order[] syntactic elements. It is composed of an object type name chosen exclusively from the list of predefined tables, and a field name. The field name may be a predefined field name or it may be a user defined field name.

  Example use of the OBJECTNAME."fieldname" element in a match element:

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

  show match[strEQ(DRIVE."DriveName" "physics1") ]


  report[LIBRARY."LibraryName"] ;

  The first example reports the PCL(s) of all the volume(s) named "servers.001", from all applications, while the second example reports the name of the library that the drive "physics1" is inside.

  Please refer to the section defining the match[] common syntax element for examples of its use, and the section defining the report[] and reportMode[] common syntax elements for examples of their use.

• volname[]

  The volname[] syntax element is used in place of the volmatch[] element to restrict the set of objects on which the command may be applied. It is no more and no less than a shorthard for a match[] element of a particular structure.

  The volname[] syntax element accepts a list of volume names, for example:

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

  The equivalent match[] element would be:

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

  If a volname[] element is used, a match[] element cannot also be used.

• match[]

  The match[] syntax element is used to restrict the set of objects on which the command may be applied. The restriction is accomplished by applying specified function(s) to attributes attached to the objects in question to determine true/false status, which in turn determines membership or exclusion from the working set.

  Example:

  If the current working set of volumes and their attributes is this:

  Volume	Volume Attr	Volume Attr
  Name	(attr=value)	(attr=value)
  "vol1"	Group="Servers"	Handler="Marge"
  "vol2"	Group="Clients"	Handler="Sam"
  "vol3"	Group="Servers"	Handler="Bill"
  "vol4"	Group="Clients"	Handler="Marge"

  and the match[] syntax element is this:

  match[and (strEq (VOLUME."Group" "Servers")


  strNe (VOLUME."Handler" "Marge"))]

  the result will be:
  vol3

  If presented in English, the match[] syntax element presented above would read: Find the volumes where the "Group" attribute is set to "Servers" and the "Handler" attribute is not "Marge". In this example, after the match[] element is evaluated, only the volume named "vol3" and any other objects that may relate to that volume remain in the working set.

• order[]

  The order[] syntax element is used to sort the set of objects left after the match[] element has finished removing the unwanted objects from the working set. It is useful in cases where there is no particular quality bar to match, but the application nonetheless wants to optimize its activities as much as possible.

  Example:

  If the current working set of objects is the following set of volumes and their attributes:

  Volume Name	Volume Attributes
  	(attr=value)
  "vol1"	pctFull="40"
  "vol2"	pctFull="31"
  "vol3"	pctFull="93"
  "vol4"	pctFull="11"

  and the order[] syntax element is this:

  order[ numHiLo (VOLUME."pctFull") ]

  the order of volumes in the working set will be:

  vol3 vol1 vol2 vol4

• number[]

  The number[] syntax element is used to declare which of the elements in the current work list will be used and then reported by the command.

  The elements inside the number[] syntax element specify the ordinal numbers of the items in the sorted work list that we want to operate on. It is possible to specify both single items and ranges of items. A range is given by two numbers separated by a pair of periods (eg: ".."), and is inclusive of the elements at each end of the range. There are two additional tokens "FIRST" and "LAST" that refer to the first and last elements in the work list, respectively. Negative numbers are ordinal offsets from the end of the sorted list of items in the work list.

  The number[] element: number[1 3 5] means that the first, third, and fifth items from the ordered work list should be used. The element: number[2..4] is exactly equivalent to: number[2 3 4]. The element: number[FIRST..3 7..-7 -3..LAST] when there are 16 items in the work list is exactly equivalent to: number[1 2 3 7 8 9 14 15 16 ].

  Example:

  Given that the current working set of volumes and their attributes is this:

  volumeName	Volume Attr	Volume Attr
  	(attr=value)	(attr=value)
  "vol1"	group="Servers"	handler="Marge"
  "vol2"	group="Clients"	handler="Sam"
  "vol3"	group="Servers"	handler="Bill"
  "vol4"	group="Clients"	handler="Marge"

  and the number[], report[], reportMode[] syntax elements are these:

  number[2 4]
report[VOLUME."group" VOLUME."VolumeName" VOLUME."handler"]
reportMode[value]

  then the output of the command will be:

      text["Clients" "vol2" "Sam"]
      text["Clients" "vol4" "Marge"]
      

• report[]
  reportMode[]

  The report[] syntax element is used to declare the attributes and/or attribute values which are to be returned by the current command. The reportMode[] syntax element declares whether the output from the report[] element contains only the name of each attribute to be reported ("name"), only the value of the attribute ("value"), both the name and value ("nameValue"), and controls whether all combinations are returned or only the unique combinations ("unique"). . The report[] and reportMode[] syntax elements together describe the required format of the command's output.

  Example:

  If the current working set of volumes and their attributes is this:

  volumeName	Volume Attr	Volume Attr
  	(attr=value)	(attr=value)
  "vol1"	group="Servers"	handler="Marge"
  "vol2"	group="Clients"	handler="Sam"
  "vol3"	group="Servers"	handler="Bill"
  "vol4"	group="Clients"	handler="Marge"

  and the report[] and reportMode[] syntax elements are these:

  report[VOLUME."group" VOLUME."VolumeName" VOLUME."handler"]
reportMode[value]

  then the output of the command will be:

  text["Servers" "vol1" "Marge"]
text["Clients" "vol2" "Sam"]
text["Servers" "vol3" "Bill"]
text["Clients" "vol4" "Marge"]

  If the reportmode[] element was changed to this:

  reportMode[nameValue unique]

  then the output of the command will be changed to:

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

  If the reportmode[] element was changed to this:

  reportMode[unique name]

  then the output of the command will be changed to:

  text["group" "VolumeName" "handler"]
• text[]

  The text[] systax element is a general container for lists of character strings or object references. In some contexts, such as the use of the text[] element in the rename command, the number of strings which can be enclosed by the text[] element as well as their content may be constrained. In most cases, though, one or more text[] elements are used to encapsulate the response from a command.

  Example use of the text[] element in a reject command:

  reject volname["myVolume-003"]
  
  text["This is not what I thought it was"]
  Please refer to the section defining the report[] and reportMode[] common syntax elements for examples of the use of the text[] element as a command output construct.

Glossary of match[] Sub-Functions

The following functions operate in the context of the AAPI and CAPI match syntax element. For each possible combination of objects in the system, an expression made up of field references (eg: OBJECT."field") in combination with the following functions is evaluated. If the expression returns false, then the object is not included in with work set for whatever operation the match[] clause is part of.

• isAttr ( <nameSpec> ) -> <boolean>

  Returns true if the attribute named <nameSpec> is defined on this object, otherwise returns false.

• noAttr ( <nameSpec> ) -> <boolean>

  Returns false if the attribute named <nameSpec> is defined on this object, otherwise returns true.

• regex ( <SHORTSTRING(regularExpression)> <expression> ) -> <boolean>

  Returns true if the <expression> matches the regular expression defined by <SHORTSTRING(regularExpression)>. Returns false otherwise.

  For regular expression rules, please see regcmp(3G).

• strXX ( <expression1> <expression2> ) -> <boolean>

  Returns true if the defined relationship between the values denoted by value1 and value2 is true. Returns false otherwise.

  Note: replace "XX" with the appropriate suffix given below. Suffixes are case-insensitive.

  Suffix	Meaning
  Eq	value1 identical to value2
  Ne	value1 not identical to value2
  Lt	value1 less than value2
  Le	value1 less than or equal to value2
  Ge	value1 greater than or equal to value2
  Gt	value1 greater than value2

  String value comparisons will be made on the entire lengths of the two strings, and will be based on standard 7-bit ASCII collation ordering.

• numXX ( <expression1> <expression2> ) -> <boolean>

  Returns true if the defined relationship between the values denoted by value1 and value2 is true. Returns false otherwise.

  Note: replace "XX" with the appropriate suffix given below. Suffixes are case-insensitive.

  Suffix	Meaning
  Eq	value1 identical to value2
  Ne	value1 not identical to value2
  Lt	value1 less than value2
  Le	value1 less than or equal to value2
  Ge	value1 greater than or equal to value2
  Gt	value1 greater than value2

  Numbers are defined to be those values (expressed in characters [-0-9]), either positive or negative, which fit in a signed 32-bit word. Numeric conversion will be performed by atoi() or equivalent.

• and ( <expression>+ ) -> <boolean>

  Returns true if all expressions return true, and returns false if any expression returns false.

• or ( <expression>+ ) -> <boolean>

  Returns true if any expression returns true, and returns false if all expressions return false.

AAPI Command Examples and Pseudo-Code

What follows is a list of example AAPI commands, each followed by a description of what is does.

• Command:
  show match[ numGt (VOLUME."myNumber" "75") ] report[VOLUME."VolumeName"];

  Description:

  Return the volume names of all volumes that have an attribute called "myNumber" where that attribute has a numeric value which is greater that 75.

• Command:
  attribute
  match[ and (
  numGt (VOLUME."myNumber" "75")
  strEq (VOLUME."hello" "no")) ]
  set[ nameValue[VOLUME."zorba" "greek"] ]

  Description:

  Set or create an attribute named "zorba" with a value of "greek" on all volumes that have an attribute named "myNumber" with a numeric value greater that 75 and an attribute named "hello" with a value of "no".

Miscellaneous Notes

Character Set and Quoting Considerations

The character set for OpenVault strings includes all 7-bit ASCII characters in the decimal value range 32 to 126. Strings are required to be quoted with either a double-quote or single-quote character. (" or '). OpenVault considers the single quote character and double quote characters to be exactly identical. To include a double- or single-quote character in a string, put a backslash (\) before it in the string. To include a single backslash character in a string, put two backslash characters in your string (as in: "this string actually contains \\ a single backslash character and a quote \" character')

Command Element Ordering

All commands are designed so that the basic elements of the command may be entered in any order.

AAPI Command Return Formats and Values

In general, when a command is successful, the return value specification is the following:

response success <successSpec>

Potential return value types depend on the command issued.

When a command is unsuccessful, the error return value conforms to the following specification:

response error <errorSpec>

Complete AAPI Syntax Specification (in modified BNF)

STRING: String of character-set bytes <= 65536 bytes long, surrounded by quotes.

DIGITS: Any string of numeric characters [-][0-9]+ which resolve to a value that can fit in a 32-bit signed integer.

Error symbolic names, error numbers, and associated text

Commands and the Errors that can be Encountered by Them

Command	Error(s)
show	cannot meet "match" specification unknown object name
attribute	cannot meet "match" specification read-only attribute reserved attribute name unknown object name
create	cannot meet "match" specification duplicate object name
delete	unknown object name
rename	duplicate object name unknown object name
mount	cannot meet "match" specification cannot meet "mountMode" specification volume mounted unknown object name
unmount	cannot meet "match" specification volume not mounted unknown object name