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

 

NAME

dbschema - format of the schema file

DESCRIPTION

A Datascope database is described by a schema file. The file is reasonably readable, and free format; case is significant throughout.

There are four possible statements: Include, Schema, Attribute, and Relation. The Schema, Attribute and Relation statements are each terminated with a semicolon.

Include

The Include statement includes some other schema into the current schema. It can be used to extend an existing schema by first including the existing schema, and then adding new attributes and relations. New Schema statements override and replace previous statements. Here's an example of an Include statement:

Include  css3.0

Schema

The Schema statement specifies a name for the schema, and optionally a description and some detail. It may also specify a Timedate field (of type Time) which is automatically updated whenever a record is modified (and when it is first added).

Schema "css3.0"
    Description ( "CSS Schema Version 3.0" )
    Detail {
       There is much more detail in the
       actual file $ANTELOPE/data/schemas/css3.0.
    }
    Timedate lddate
    ;

Attribute

The Attribute statement describes one field of the database; its format is: Attribute name clauses ;. For example:

Attribute amp
    Real ( 10 )
    Format ( "%10.1lf" )
    Units ( "Nanometers" )
    Range (  "amp  > 0.0" )
    Null  ( "-1.0"  )
    Description ( "amplitude, instrument corrected, nm" )
    Detail {
        Signal amplitude.  This is the
        zero-to-peak amplitude of the earth's
        displacement for a seismic phase.  Amp is
        assumed to be corrected for the response
        of the instrument.
        }
    ;

Only the name, and the type and format clauses are required. The clauses may appear in any order. The allowable types are Real, Integer, String, Time, Date, and YearDay. Following the type in parentheses is the size of the field in characters.

The format specifies a preferred format (in printf form) for converting the value to ascii.

Units, Description and Detail are just character strings which are accessible in a program using dbquery.

The Null value must correspond to the Format value -- i.e., the null value must fit in the field when formatted according to the Format code.

The Range is an expression which can be evaluated, to test if a value is legal.

Relation

The Relation statement describes a table in the database and has the format: Relation name Fields ( fieldnames .. ) clauses ; . For example:

Relation arrival
    Fields (
        sta time arid jdate stassid chanid chan
        iphase stype deltim azimuth delaz slow
        delslo ema rect amp per logat clip fm snr
        qual auth commid lddate
        )
    Primary ( sta  time  )
    Alternate ( arid  )
    Foreign  ( stassid  chanid  commid   )
    Defines arid
    Separator ( " " )
    Transient
    Description ( "information on a seismic arrival" )
    Detail {
        Summary information on a seismic arrival.
        Information characterizing a 'seismic
        phase' observed at a particular station is
        saved here.  Many of the attributes
        conform to seismological convention and
        are listed in earthquake catalogs.
        }
    ;

The name and Fields are required; the various clauses are optional. However, the optional clauses are used by the more advanced operations like join and sort.

The name may take the special form Anonymous, in which case a unique (but otherwise meaningless) name is generated.

Fields specifies the attributes which make up a row in the table, in the order in which they appear. Fields in an actual record are often separated by spaces, to facilitate inspection with editors.

It's possible to override the default field and record separators, (space and linefeed, respectively), using the separator clause. These separators may be set to null using "", or to some other single character. However, backslash escapes are not recognized, so the actual character must appear in the schema file. The Separator clause accepts either just the field separator, or both the field and record separator.

The Transient clause creates a memory only relation, which has no disk representation. The relation is otherwise identical to a relation which is not transient.

Description and Detail are short and verbose descriptions of the table, accessible through dbquery.

The Primary, Alternate, and Foreign clauses specify the various keys for the table. A key is a list of fields or ranges from the relation. A range of values is indicated with a double colon, e.g.:


time::endtime

Ranges should always be placed last in the list making up a primary or alternate key, for the sake of efficiency. The search in a sorted list which Datascope performs during a join or dbmatches operation devolves to a linear search for keys following a range.

If a table has an integer key which identifies a row in that table, it is specified with the Defines clause.

An alternative method for specifying a new relation is the Like clause, which creates a relation with the same structure as another relation, but a different name:


Relation pde
    Like origin
    Description ( "PDE origins" )
    Detail {
        This is a table of origins from the PDE.
        }
    ;

The fields in a Relation statement may actually be other relations. For instance, if the fields of relation example include the name of another relation other, this means that the table example contains a pointer to a row in the other table. All of the fields in the other table can be read from the table example, as if they were a part of the table, but the data comes from the other table. Any relation which contains references like this to other relations is a view.

Most of the content of the schema file is free format; the indentation shown above is only convention. However, the indentation of the Detail clauses is preserved in the text returned by dbquery calls. This affects the display in dbhelp(1), for example.

FILES

Schema files are usually kept in a central location -- $ANTELOPE/data/schemas -- but may also be kept in the directory where the database file lives. You may use multiple schema directories by setting the environment variable SCHEMA_DIR. Directories are searched in the following order:

Multiple schema files

In the simplest situation, there is a single schema file which describes all the attributes and relations in the schema. However, it can be convenient to add new attributes and relations in additional files inside an extension directory: the name of the extension directory must be <schema-name>.ext. More specifically, the Datascope library searches each directory in the environment variable SCHEMA_DIR. Any files named <schema>, plus any file in any directory named <schema>.ext found in the SCHEMA_DIR directories are combined to make up the complete schema. If there is no SCHEMA_DIR environment variable, the default SCHEMA_DIR is $ANTELOPE/data/schemas.

ENVIRONMENT

see antelopeenv(5).

SEE ALSO

dbintro(3)
dbhelp(1)
dbe(1)
dbdoc(1)

The schema may be converted to a troff(1) document with the program dbdoc(1), producing a document which describes the format of all the tables and fields in a database.

AUTHOR

Daniel Quinlan
Printer icon