• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

dbptr - introduction to database pointers

DESCRIPTION

Most Datascope database operations use a construct called a database pointer. This construct can be and is used to address a variety of database parts, from a specific field in a record in a table, to a whole record, to a whole table, to a whole database. A database pointer is constructed of a set of small integers which index arrays internal to Datascope.

These various integers may be and often are manipulated by the user as well. The various integers are

The database number is just the index corresponding to the order in which databases were opened. A typical application may only open one database, in which case database number would be zero.

Table number is just the sequence number of the table, in the order in which relations are added to the schema.

Field number is the sequence number of the field in a table.

Typically the user directly manipulates only the record number and uses dblookup(3) to lookup table and field numbers.

These indexes may also take on a few special values:

dbALL
dbSCRATCH
dbNULL
dbINVALID

When the field number is dbALL, the database pointer refers to the entire record. Similarly, when the record number is dbALL, the database pointer refers to the entire table. (However, it is not supported to have field number refer to a field and record number be dbALL). dbopen(3) returns a database pointer where the database index is set, and all the other values are dbALL.

The record number may be dbSCRATCH or dbNULL, in which case the database pointer refers to two special records for a table -- the scratch record, and the null record. You may assemble a new record in the scratch record before adding it to the table, and you may read null values for fields or records from the null record.

dblookup(3) can return dbINVALID in any of the indexes, to indicate that the corresponding database/table/field/record cannot be found. Also, some operations return a database pointer composed of all dbINVALID, indicating some problem with the operation.

Views are actually arrays of database pointers. They are also addressed by database pointers. A view is just a new table in the schema, and it has a unique index which depends on the order in which views are created. The field number, however, does not refer to a particular database pointer (that is, a "field" of the view), but rather to an actual field in one of the tables which make up the view. For example, in a view that is the join of two tables, the fields of both tables would be indexed by a field number corresponding to the sequence number of the field in the joined table.

More complex operations like sorting, joining, and subsetting do not operate directly on database files, but rather create views and return database pointers to them. Thus, dbjoin(3), dbsort(3) and dbsubset(3) take database pointers selecting the tables or views on which to operate and an additional arguments specifying the operation; they return a database pointer to the newly created view.

SEE ALSO

Datascope Tutorial
Antelope Software Development Guide

AUTHOR

Daniel Quinlan
Printer icon