.help dbki Aug85 "Database Kernel Interface"

.ce

\fBDatabase Kernel Interface\fR

.sp 3

.nh

Overview



    The DBKI is the interface between DBIO and the DB kernel.  The DB kernel

is responsible for all storage management.  The DBKI isolates DBIO from the

details of how storage is managed by the DB kernel.  The DBKI also permits

DBIO to be used to access any storage format or host database system.  All

access to a database is via the DBKI, i.e., DBIO assumes nothing about, for

example, the association of logical database objects to files or directories.



The DBKI provides access to a database consisting of a set of tables.  Each

table consists of a set of records, all of which have the same structure. 

Records may be accessed either directly via a pointer or index, or sequentially

in either storage order or index order.





.ks

.nf

	directory table

	domain descriptor table

	record descriptor tables

	index descriptor table

	data tables

.fi

.sp

.ce

Figure 1.  Major Components of a Database

.ke





Each database contains a special directory table containing a record for each

table in the database.  In addition, for each type of record in the database

there must be a table defining the record type.  There is an entry in the

index table for each index in the database.  A final system defined table is

the domain definition table, used to define the domains upon which attributes

are defined in a record type definition.



All access to the fields of a record by DBIO is mediated by the DB kernel.  In

particular, DBIO has no knowledge of the internal storage format of a field in

a record.  DBIO manipulates the values of fields using the machine dependent

SPP datatypes which may be quite different from the internal storage formats

(e.g., bit field integer, byte packed ASCII or EBCDIC character, IEEE floating

point, FITS cardimage, etc.).  The datatype used by DBIO to access a particular

field is however fixed at record definition time, hence the DB kernel need not

be prepared to perform arbitrary runtime datatype conversions.



.nh

Database Management Operators

.nh 2

General



    A database must be opened or created before it can be accessed.  All

access to an open database is via a database descriptor returned when the

database is opened or created.  Multiple databases may be accessed

simultaneously.

.ls

.ls o

Create a new, empty database.

.le

.ls o

Open a database.

.le

.ls o

Close a database.

.le

.ls o

Delete a database.

.le

.ls o

Sort a table in index order.

.le

.ls o

Query DB kernel capabilities.

.le

.le

.nh 2

Record Definition



    A new record type is defined by creating a record definition table and

inserting one record in the table for each field in the new record type.

The record type for a record definition table is itself defined by a table

which is initialized by DBIO when the database is created.  A record

definition table is accessed using the standard record access entry points,

outlined below.

.nh 2

Table Creation and Deletion



    A new instance of a table is created by insertion of a record defining

the table into the database directory table.  The record type must be specified

when the new data table is created.  Deletion of a record from the directory

table deletes the associated data table and any associated indexes.  The

database directory table is accessed via the standard record access interface,

outlined below.

.nh 2

Indexes



    Indexes are maintained and used by the DB kernel rather than by DBIO.  An

index is created by inserting a record defining the index into the index table. 

The primary attributes of an index are the name of the indexed table and the

names of the fields used in the index.  The index will be automatically

maintained by the DB kernel as insertions, deletions, and updates are performed

on the associated relation.  An index is deleted by deletion of the

corresponding record from the index table.



.nh

Record Level Access



    Two types of record level access are provided by the DBKI interface.

The first type of access is direct access, wherein a single record is accessed

either by a magic kernel supplied record id number, or via an index given the

values of the indexed fields.  The second type of access is sequential access,

wherein a user defined subset of the records in a table are accessed either in

storage order or in the order defined by an index on the table.  The record id

numbers used in a direct access must be obtained by a prior sequential scan.

.nh 2

Direct Access Functions

.ls

.ls fetch

Extract the specified fields from a record given

the record id or key value.

.le

.ls insert

Insert a new record into the indicated table.  A list of field values may

optionally be given.  All other field values are initialized either to their

default values or to the values present in an existing user defined record.

.le

.ls delete

Delete the specified record.

.le

.ls update

Update (assign into) the indicated fields of the indicated record.

.le

.le

.nh 2

Sequential Access Functions

.ls

.ls open scan

Position to the first record of a sequential scan, returning a pointer to a

scan descriptor.  The scan may be either an unindexed scan of the records in a

table in storage order or an indexed scan in index order.  In the case of an

index scan a key value may be given to define the starting point of the scan.

.le

.ls next

Return the record id of the next scan record satisfying a boolean expression

defined on the fields of the record.

.le

.ls close scan

Return the scan descriptor.

.le

.le



.nh 

Escape Function



    The DBKI interface is cut at a fairly low level to simplify the

requirements for a DB kernel, to simplify the DBKI interface itself, and to

ensure consistent behaviour at the user interface regardless of the nature of

the underlying database system.  When the underlying database system is not

just a kernel but rather a full blown host resident database system, however,

it will be highly desirable to have a mechanism for passing relational commands

posed in the query language of the host DBMS to the host system, without

leaving the IRAF environment.  The DBKI shall provide an escape function for

this purpose.
