Chapter 4. Programming the C Interface
Prev   Next

Chapter 4. Programming the C Interface

This chapter introduces CAPI programming, and includes the following topics:

CAPI and AAPI

The Client Application Programming Interface (CAPI) and Administrative Application Programming Interface (AAPI) are languages that OpenVault client and administrative programs use to communicate with the MLM server.

CAPI commands are a subset of AAPI commands, which are granted more privileges. For a list of AAPI language elements not available in the more limited CAPI language, see “CAPI Language Differences” in Appendix B.

A client application speaks to the MLM server in CAPI, and the server replies in CAPI/R. An administrative application speaks to the MLM server in AAPI, and the server replies in AAPI/R.

Client Development Framework

The application developer's kit includes a framework for writing CAPI or AAPI that helps ease the development, porting, and maintenance effort for client or administrative applications. This section describes the general source tree layout.

OpenVault Client-Server IPC

OpenVault clients and servers communicate using a custom interprocess communication (IPC) layer. Modules using this PIC layer need to include the following header file, and be loaded with the following Clibrary:

ovsrc/include/ov_lib.h
 

C data structures, macros, and subroutine prototypes for IPC

ovsrc/libs/comm/libov_comm.so
 

C library containing IPC subroutines

CAPI Generator and CAPI/R Parser

OpenVault includes language parsers and generators. Modules using these facilities need to include the following header files, and be loaded with the following Clibraries:

ovsrc/include/capi.h
 

Supported CAPI and CAPI/R version number, command enumeration, definitions for CAPI objects, C data structures for command sequences, and library function prototypes

ovsrc/include/hello.h
 

C data structures for HELLO and WELCOME command representation

ovsrc/libs/hellor/libov_hello.so
 

C library (DSO) that contains HELLO parser-generator subroutines

ovsrc/libs/capi/libov_capi.so
 

C library (DSO) that contains CAPI parser-generator subroutines

C Library Routines

Table 4-1 offers a summary of the CAPI and CAPI/R lexical library routines that you employ when writing client or administrative applications.

Table 4-1. CAPI and CAPI/R Lexical Library Routines

Purpose of Activity

CAPI Function

Short Description

To initiate session with MLM server

CAPI_initiate_session()

Begins session with a specific MLM server, including HELLO version negotiation.

To parse CAPI/R command from MLM server

CAPIR_receive()

Parses a CAPI/R command from the server and returns a CAPIR_cur_cmd structure

To acknowledge CAPI/R command

CAPIR_acknowledge()

Informs MLM server that the client received a CAPIR command.

To send string to server

CAPI_send_string()

Sends string from application to the server.

To formulate CAPI commands to send MLM server

CAPI_alloc_cmd()

CAPI_alloc_string()

CAPI_alloc_substring()

CAPI_alloc_attrlist()

Allocates CAPI command structure.

Allocates CAPI stringlist structure.

Allocates CAPI string sublist.

Allocates attribute structure linked into list.

To formulate match, order, and number clauses for sending to MLM server

CAPI_alloc_match_binary()

CAPI_alloc_match_unary()

CAPI_alloc_match_object()

CAPI_alloc_match_literal()

CAPI_alloc_order()

CAPI_alloc_number()

Allocates element of MATCH clause list.

Allocates element of MATCH clause list.

Allocates element of MATCH clause list.

Allocates element of MATCH clause list.

Allocates element of ORDER clause list.

Allocates element of NUMBER clause list.

To find attribute in list

CAPI_find_attr()

CAPI_find_attr_byvalue()

Returns first instance of argument in the argument list.

Returns first match of argument in the argument list.

To send CAPI command

CAPI_send()

Sends CAPI command to MLM server.

To free CAPI command

CAPI_free()

Deallocates CAPI command structure.

To close session with MLM server

CAPI_conclude_session()

Ends session with a specific MLM server, including memory deallocation.


Common Framework

The application developer's kit includes common utility code for writing applications. To use this code, include the following header files, and read the following C module:

ovsrc/include/cctxt.h
 

Generic command queuing mechanism.

ovsrc/include/ov_lib.h
 

OpenVault data structures and MLM definitions and limits.

ovsrc/include/queue.h
 

Generic queue and linked list implementation.

ovsrc/clients/admin/common/capi_utils.c.
 

Convenience routines for writing client and administrative applications.

The capi_utils.h header file defines a simplified CAPI send and receive interface, used by the ov_* administrative commands.

Defined Tokens List

This section documents the predefined strings that are relevant to CAPI programming.

Drive Capabilities

OpenVault assumes that there is a default set of drive capabilities. Table 4-2 shows the tokens that describe changes from a standard drive.

Table 4-2. Predefined mount Tokens

Token

Description

audio

Mount point allows playing audio data from media (often unimplemented).

compression

Attempts compression of the data stream.

fixed

Blocks on the media are a fixed size.

readonly

The mount point allows reading of the media.

readwrite

The mount point allows writing of the media.

rewind

Rewinds the media on close of the mount point.

status

A status-only mount point is also created (in a directory created for the session).

variable

Blocks on the media are variable sized.

Drive capabilities are extensible; so this list is not exhaustive.

Cartridge Form Factors

Table 4-3 shows a list of predefined slot type names, or cartridge form factors.

Table 4-3. Predefined Cartridge Form Factor Tokens

Token

Description or Usage

8mm

Any generic 8-mm shell

3480

For example: IBM 3480/3490/3495, STK 4480/4490, and so forth

DLT

Digital linear tape (Quantum)

DAT

4-mm digital audio tape (DDS1 and DDS2)

D2-S

Small DST cartridges (25 GB capacity)

D2-M

Medium DST cartridges (75 GB capacity)

D2-L

Large DST cartridges (165 GB capacity)

DTF

20 GB cartridges from Sony


Media Bit Formats

The format of bits recorded on media is independent of external cartridge appearance. One well-known case is the EXABYTE 8200 versus EXABYTE 8500 format, both being recorded on 8-mm media.

Table 4-4 shows tokens for each bit format, what form factors use it, and a description of how the format is generated.

Table 4-4. Predefined Bit Format Tokens

Token

Form Factor

Description

8200

8 mm

EXABYTE 8200 native

8200c

8 mm

EXABYTE 8200 compressed

8500

8 mm

EXABYTE 8500 native

8500c

8 mm

EXABYTE 8500 compressed

mammoth

8 mm

EXABYTE mammoth native

mammothc

8 mm

EXABYTE mammoth compressed

3480

3480

3480 native

3490

3480

3490 native

3490E

3480

3490E native

3495

3480

IBM Magstar native

4480

3480

STK TimberLine native

4490

3480

STK RedWood native

DLT2000

DLT

DLT2000 native

DLT2000c

DLT

DLT2000 compressed

DLT4000

DLT

DLT4000 native

DLT4000c

DLT

DLT4000 compressed

DLT7000

DLT

DLT7000 native

DLT7000c

DLT

DLT7000 compressed

DDS1

DAT

Digital data storage 1.3 GB

DDS2

DAT

Digital data storage 2.0 GB

DDS3

DAT

Digital data storage 4.0 GB

D2

D2-[SML]

Ampex DST-310

DTF

DTF

Sony GY-10

QIC80

QIC

Quarter-inch cartridge 80 MB

QIC100

QIC

Quarter-inch cartridge 100 MB

QIC150

QIC

Quarter-inch cartridge 150 MB

QIC525

QIC

Quarter-inch cartridge 525 MB

QIC1024

QIC

Quarter-inch cartridge 1024 MB

ISO9660

CDROM

DOS-like (8.3) filesystem on CD-ROM


Cartridge Types

Table 4-5 shows tokens used to describe media inside a cartridge.

Table 4-5. Predefined Media Type Tokens

Token

Product Name or Description

8mm-12m

12 meter 8 mm

8mm-60m

60 meter 8 mm

8mm-90m

90 meter 8 mm

8mm-112m

112 meter 8 mm

8mm-160m

160 meter 8 mm

mammoth

EXABYTE mammoth

3480

IBM 3480

3490

IBM 3490

3490E

IBM 3490E

3495

IBM Magstar native

4480

STK TimberLine native

4490

STK RedWood native

DLT2000

Quantum DLT2000

DLT2000XT

Quantum DLT2000XT

DLT4000

Quantum DLT4000

DLT7000

Quantum DLT7000

DDS1

DAT 60 meter

DDS2

DAT 90 meter

DDS3

DAT 120 meter

D2-S

Ampex DST-310 small format

D2-M

Ampex DST-310 medium format

D2-L

Ampex DST-310 165GB large format

DTF

Sony GY-10

QIC

Quarter-inch cartridge tape

ISO9660

CD-ROM


Partition Names

The ADI interface assumes that there is a standard set of names used for partitioned media. Table 4-6 shows the tokens used for naming partitions.

Table 4-6. Predefined Partition Name Tokens

Token

Description

PART 1

The first partition on the media. For magneto-optical or two-sided optical disc, this would be side one or side A.

PART 2

The second partition on the media. On linear media such as a tape, PART 2 immediately follows PART 1. On non-linear media such as a disk, PART 2 is the second-lowest numbered or lettered partition. Note that PART 2 does not refer to the next partition that is in use, it refers to the next partition.


Attribute Names

Table 4-7 shows attributes used in OpenVault, where they are used, and what they mean.

Table 4-7. Predefined Attribute Name Tokens

Attribute Name

Where Used

Possible Values

Required?

Description

ReadBandwidth

ADI config command, perf clause

Numeric, in bytes per second

Yes

The total effective bandwidth that an application should be able to sustain when reading from that drive using the given capability set.

WriteBandwidth

ADI config command, perf clause

Numeric, in bytes per second

Yes

The total effective bandwith that an application should be able to sustain when writing to that drive using the given capability set.

Capacity

ADI config command, perf clause

Numeric, in bytes

Yes

The total storage capacity of the cartridge that an application should be able to expect when accessing that drive using the given capability set.

BlockSize

ADI config command, perf clause

Numeric, in bytes

Yes

The I/O size that would best use the drive/cartridge combination with that drive with the given capability set.

LoadTime

ADI config command, perf clause

Numeric, in seconds

Yes

The number of seconds between the time a cartridge is first inserted into a drive and the time that the drive is ready to read/write data.

SlotTypeName

ADI config command, config clause

Cartridge FormFactor token (see Table 4-3)

Yes

A supported form factor when the drive is using the given capability set.

CartridgeTypeName

ADI config command, config clause

MediaType token

Yes

A supported media type, usually indicating tape length.

BitFormat

ADI config command, config clause

Bit Format token

Yes

A supported recording format when the drive is using the given capability set.

NominalLoad

ALI config command, perf clause

Numeric, in seconds

Yes

Approximate time it takes for the library to move a cartridge from its home location to a drive, or back, not including drive load/unload time. This is analogous to nominal seek time of a disk drive.

 

 

 

 

It is defined as the total real time to execute a large number of cartridge move-load operations randomly spread through the physical space of a library, divided by the number of such operations performed.


Prev Table of Contents Next
Chapter 3. OpenVault Programming with Perl  Appendix A. Error Messages