.bp
.nr H1 1
.hr H2 0
.OH ' ' 'Database Attributes'
.EH 'Database Attributes' ' '
.Lp
.ce
.B "\s+2DATABASE ATTRIBUTES\s0"
.Lp
This chapter describes each of the attributes used in the 
schema.  Descriptions of the relations are found in Chapter 3, 
\fIDatabase Relations\fP.
Attributes are presented as follows:
.KS
.sp 1
.Hl
.in 1i
.LP
.ta 1i 2i
.TI
Name:	\fIThis is the name of the attribute.\fP
.TI
Relation:	\fBThese are the database relations which contain the attribute.\fP
.TI
Description:	This paragraph describes the attribute.
.TI
NA Value:	This is a value used to indicate that information is not 
available for this attribute.  Many attributes in this schema are optional.
The NULL value is defined for these attributes and should be used when the 
actual value is not known.  Essential attributes must always be given a
value.
.TI
Units:	This lists the unit of measurement for the attribute, if applicable.
.TI
Range:	This is the range of permissible or recommended values for this 
attribute, if such a range exists.  For most strings, the range indicates the 
recommended values, but is not restricted to those values. 
.in 0i
.LP
.Hl
.KE
.Lp
The following conventions are applied throughout.
.SH
Dates and Times
.LP
The \fItime\fP attribute throughout the database 
is stored as epochal time, the number of seconds since January 1, 1970.
Epochal time has a precision of 1 millisecond. 
Often \fItime\fP is matched by the more readable attribute,
\fIjdate\fP. This so called "Julian date" represents a day in the form,
for example, 1981231 where 1981 is the year (YYYY) and 231 is the day of year
(DOY).
.SH
Units of Measurement
.LP
Attribute descriptions also include the unit of measurement, if
applicable.  Here are some quantities with their corresponding 
measurement units:
.sp
.ta 15 23
.nf
period, time	seconds	\fIcalper\fP, \fItime\fP, \fIendtime\fP, etc.
 
julian date	YYYYDOY	\fIjdate\fP
 
amplitude	nanometers	Note that long-period measurements are frequently
		reported in microns so conversion is required.
 
angular measurements	degrees	\fIdelta\fP, \fIazimuth\fP, etc.
 
depth, errors in location	kilometers	\fIdeast\fP, \fIdepdp\fP, \fIdepth\fP, etc.
.fi
.bp
.SH
Range
.Lp
Whenever possible, explicit ranges are defined for each attribute.  
The specified ranges are in the form of expressions which can be evaluated
by the db library routines, to simplify automated validity checks of databases.
.Lp
The style of these  expressions closely follows standard c syntax, 
with an extension similar to awk, perl or the shell for regular
expression matches.  Typically, a numerical attribute
may have an expression like:
.IP  "lat >= -90. && lat <= 90."
.br
which means that lat must fall between -90 degrees and +90 degrees.
.LP
Some character attributes are can take on only a 
few legal values.  The enumeration of these values is written
like:
.IP "clip =~ /c|n/"
.br
which means that clip may either be "c" or "n".  (The NULL value
is a third possibility, in this case.)
.Lp
Sometimes no information is available for an attribute.
In that case, a NULL value is assigned.
A NULL value is outside
the range of permissible or recommended values for the attribute.
This special NULL value alerts users and applications that the desired
attribute was not available when the record was created.
For example, in the \fBorigin\fP relation, the attribute \fIms\fP,
surface wave magnitude, 
may be unknown for a given record, since it often can't be measured.
Then the NULL value for magnitudes (\-999.0) should be assigned to \fIms\fP
and \fImsid\fP should be set to \-1, the NULL value for \fImsid\fP.
Some attributes are essential to defining a meaningful record and they must be
specified; the NULL value is not allowed.  For example, the attribute 
\fItime\fP in \fBarrival\fP must be given a value in the valid range,
not an NULL value. 
.Lp
Some general guidelines and specific examples of NULL values are given in
the following table.
.sp
.in +5
.ta 15 20
.nf
.UL "Representative NULL Values:"
 
character fields	- (a dash)
non-negative integer numbers	\-1
non-negative real numbers	\-1.0
negative real numbers	\-999.0 
\fIconf\fP	0.0
\fIdeast, dnorth\fP	0.0
\fIendtime\fP	+9999999999.999
\fItime\fP	\-9999999999.999
.fi
.in -5
.sp
In Versions 2.7 and 2.8 of the schema, the underscore "_" was used to 
denote an unavailable character string.
Since the underscore "_" represents the ANSI SQL
"match any single character" wildcard, Version 3.0 uses the dash "-" to
denote an unknown character string.
.SH
Format of Character Data
.LP
Most character fields are mixed case, but \fIsta\fR and \fIchan\fR are normally
uppercase only.
.bp
