The db package is a collection of routines designed to simplify the use of databases like CSS represented in a set of flat files. While it has several features specifically designed for CSS, it can also be used for arbitrary flat file ascii databases. It would also be straightforward to extend the package to allow accessing fixed header binary formats like AH and SAC.
This package provides the following features:
2007-073 6:16:38 perl *fatal*: Out of memory at line 84 in 'dbadd.c' Can't malloc 147490688 bytes for table->data Not enough space
The basic operations are opening a database, reading and writing values to tables in the database, and providing information about the database and schema. A database is opened with the dbopen(3) routine, and values may be read from and written to the database with the dbget(3), dbgetv(3), dbput(3), and dbputv(3) routines. A matching record in a table can be found using dbfind(3). A new descriptor file can be created with the dbcreate(3) routine. Information like the number of records in a table, the units of a particular field, the description of a table, the null value of a field, etcetera are obtained via the dbquery(3) routine. See dbconstants(5) for codes for dbquery.
Records may be added to a table with dbadd(3), dbaddv(3), and dbaddnull(3).
Comments may be added to the CSS3.0 remark table with dbadd_remark(3), and gotten back from the table with dbget_remark(3). New ids for tables may be generated with dbnextid(3).
Deletions are supported in two different ways. Because views use record indexes which are just the sequence number of the record in a table, (and users may also cache these indexes separately), it may be dangerous to simply delete a record: the index of all subsequent records would change. Thus while a plain delete is supported, a method of marking records for deletion and then later deleting them all in one operation is provided.
Records are deleted with dbdelete(3). Alternatively, records may be marked for deletion (all values set to null) with dbmark(3) and later deleted with dbcrunch(3). For the truly destructive, dbdestroy(3) completely eliminates every table in a database, while dbtruncate(3) truncates a database, shortening it to a specified number of records.
Most 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 the db package. See dbptr(3) for additional information.
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 one.
Table number is just the sequence number of the table in the schema file.
Field number is the sequence number of the field in the table.
Typically the user directly manipulates only the record number and uses dblookup(3) to lookup table and field numbers. This description is intended to make a database pointer a little more concrete object. However, you should never hard code numbers for table and field into a program; doing so would forfeit many of the advantages of a separate, dynamic schema and make your program much less immune to changes in the database.
These indexes may also take on a few special values: dbALL, dbSCRATCH, dbNULL, or 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 valid to have field number refer to a field and record number be 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.
Various routines exist to perform calculations on database pointers. Regular expressions, seismic travel times, arithmetic functions, spherical geometry, epoch time calculations, character functions including pattern substitution, and aggregate functions such as min and max are all supported. See dbeval(3) and dbexpressions(5) for more information.
To determine the string type of a database field use dbstrtype(3).
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), dbnojoin(3), dbseparate(3), dbsever(3), dbsort(3) and dbsubset(3) take database pointers selecting the tables or views on which to operate and any additional arguments specifying the operation: they return a database pointer to the newly created view.
These routines provide a simple but powerful toolkit for creating most views. Arbitrarily complex views may be created using dbcompile(3) dbprocess(3), and dbadd(3). Grouping of a sorted table can be done using dbgroup(3). To find matching records in a second table, use dbmatches(3) which returns a list of record numbers which satisfy the match, rather than a joined table.
Finally, views may be saved with the routine dbsave_view(3), and then later used as another table by referencing it from dblookup(3). As mentioned above, this allows precomputing certain views.
Simple unix commands corresponding to dbjoin(1), dbsort(1), dbsubset(1), dbset(1), dbnojoin(1), and dbunjoin(1) have been written. These facilitate shell based tools which operate on the database.
A perl interface (see perldb(3p)) and tcl/tk package (see tcldb(3t)) have also been written that provide most of the functionality of the c routines.
dbschema(5) dbdescriptor(5) dbexpressions(5) dbdoc(1) elog(3) $ANTELOPE/doc/datascope.pdf $ANTELOPE/doc/antelope_refguide.pdf