STAFILEIF(UW) STAFILEIF(UW)



NAME
stafileif - package for station information access

SYNOPSIS
#include "stafileif.h"
load with library: ~snaps/Src/Utils/libutils.a


GENERAL
This package provides the general interface to the station
file data in the UW station file table(s). UW station
tables contain station latitude, longitude, elevation and
possibly other data in the form described below. P and S
station delay information are kept in separate files which
can also be loaded with the station table data. The pack-
age also includes utility functions for manipulating coor-
dinate and distance information. All of the external
callable functions in this package have names of the form
STA... For example, STAinit_default() loads the default
station table(s). STAget_latlon() will return the station
lat, lon, elev information for a specified station. Stor-
age for station data is dynamically allocated, so size of
the station table(s) is(are) not generally of concern.
The package also uses a hash table for efficient table
access. In the following section, the individual C-
callable functions are described.


UW STATION FILE FORMAT AND CONVENTIONS
The UW station file format is basically very simple.
The files are interpreted free field by this package, and
so lines in the station file consist of tokens separated
by white space. Lines beginning with a pound sign (#) are
interpreted as comments and ignored. Station files con-
tain zero or more data lines of the following form:

STANAME LATDEG LATMIN LATSEC LONDEG LONMIN LONSEC ELEV < +
optional info >

The data fields are self explanatory, and all fields must
be present. For example, if the latitude and longitude
are given as decimal degrees only, the then minutes and
seconds fields must be present and represent zero values.

The UW station file format has the following important
limitations. It does not adhere to the usual sign conven-
tions for geographic coordinates (normally, west longti-
tudes and south latitutdes are negative). However, the
coordinate retrieval routines correct for these deficien-
cies internally and return coordinates with the correct
(usual) sign conventions. This is done through the fol-
lowing hack. The coordinates are stored internally just
as they are given in the station table(s). When coordi-
nates are returned, they are multiplied by the auxiliary
definitions: LATSIGN and LONSIGN that are defined in the
stafileif_defaults.h header file. Note that signs are
associated with all three quantities: degrees, minutes,
and seconds. Therefore the user has two basic choices:
(1) follow the UW convention and do not put signs directly
in the table, and then set LATSIGN and LONSIGN correctly
(they are +1. and -1.0 respectively for the UW tables for
the Washington network); or (2) Put signs in the table
directly (remember that the appropriate signs must be put
on degress, minutes, and seconds) and then set both LAT-
SIGN and LONSIGN to +1.0 which means that they have no
effect. If your tables should span zero latitude and/or
zero longitude, then you have no choice but to follow
choice #2 since the LATSIGN and LONSIGN corrections must
apply to all values in the table.

Special channel names, such as TCG (time code generator)
and WWVB (WWVB time channel) may be put into the table to
designate channels that are not real seismic channels and
to keep the applications happy. For these channels, put
in zero latitude and zero longitude, which are invalid
locations (i.e., off the coast of west Africa). The
stafileif recognized these zero locations as "special"
channels and returns a query for status. Alternatively,
the users application program can recognize these bogus
station locations as special channels.

STATIONFILE PROTOTYPE FILE
Below is a list of the prototype file that is included
with the users program through the header: stafileif.h.
The prototype gives a convenient list of the functions
available in the package with their argument syntax, and
provides a convenient summary list of the functions for
the programmer. Detailed function descriptions are pro-
vided in the next section.

/*
* This file was automatically generated by version 1.7 of cextract.
* Manual editing not recommended.
*
* Created: Tue Mar 8 17:33:24 1994
*/
#ifndef __STAFILEIF_PROTO__
#define __STAFILEIF_PROTO__
#if __STDC__

int STAarcdistkm ( double, double, double, double, double *, double * );
int STAazdist ( double, double, double, double, double *, double *, double * );
int STAchange_loc ( char *, struct Gpoint, float );
int STAcoord2 ( double, double, double, double, double *, double * );
int STAget_declatlon ( char *, double *, double *, float * );
int STAget_latlon ( char *, float [], float [], float * );
int STAget_psdel ( char *, float *, float * );
int STAinit_default ( void );
int STAinit_del ( char * );
int STAinit_table ( char * );
int STAisInTable ( char * );
int STAisSeisChan ( char * );
int STAtable_loaded ( void );

#endif /* __STDC__ */
#endif /* __STAFILEIF_PROTO__ */

FUNCTION DESCRIPTIONS
Function: STAarcdistkm
/*
This utility function returns the arc distance in kilometers (r) and the
azimuth (az; degrees clockwise from north) between two points: the "evt"
and the "sta". The event and station positions are specified by lat/lon
pairs which are given as the floating point (double) values evtlat/evlon,
and stlat/stlon. The azimuth returned is from the event to the
station (position 1 to position 2).
*/
int STAarcdistkm ( double evtlat, double evtlon,
double stlat, double stlon, double *r, double *az
);


Function: STAazdist
/*
Utility function returns the arc distance in degrees (delta),
the azimuth from event to station (az; degress clockwise from north),
and the backazimuth from station to event (baz; degrees clockwise from
north) between two points: the "evt" and "sta". The event and station
positions are specified by lat/lon pairs which are given as the
decimal (double) values evtlat, evtlon, and stlat, stlon.
The azimuth returned is from the event to the station (position 1
to position 2).
*/
int STAazdist ( double evtlat, double evtlon, dou-
ble stalat, double stalon, double *delta, double
*az, double *baz );


Function: STAchange_loc
/*
Allows user to change values in the station table. The input values
are station "location" as the structure gpoint (see definition in
"stafileif.h"), and the elevation. Note that these are passed by
value, not by name. If station is not in table, FALSE is returned.
*/
int STAchange_loc ( char *name, struct Gpoint loca-
tion, float elev );


Function: STAcoord2
/*
Utility function to compute a second lat/lon coordinate position given an
origin point as a lat/lon pair (origlat & origlon), plus an azimuth (az)
and a distance (delta; in degrees). The coordinates of the second
position are returned in pt2lat, pt2lon.
*/
int STAcoord2 ( double origlat, double origlon,
double delta, double az, double *pt2lat, double
*pt2lon );


Function: STAget_declatlon
/*
Returns station coordinates, but as single decimal (double) values
for lat and lon. Otherwise, identical to STAget_latlon().
*/
int STAget_declatlon ( char *name, double *lat,
double *lon, float *elev );


Function: STAget_latlon
/*
Returns station coordinates for station specified by string "name"
in float arrays lat[] and lon[], and float value elev. If station
is not found, returns FALSE value.
*/
int STAget_latlon ( char *name, float lat[], float
lon[], float *elev );


Function: STAget_psdel
/*
Returns station delay values for station specified by string "name".
If station is not found, returns FALSE value.
*/
int STAget_psdel ( char *name, float *pdel, float
*sdel );


Function: STAinit_default
/*
Initializes the default station table(s).
Either STAinit_default or STAinit_table MUST be called prior to
accessing any station table data.
Station tables are read, storage space is allocated, and a
hash table is created. The default station table(s) is found
by (1) first looking for an environment variable called
DEFAULT_STA_TABLE_DIR, and, if this is not found, using (2) the
path defined by the default user and default path information
set in the stafileif_defaults.h file in the stafileif source directory.
The path established by either the environment variable or by
the hard wired defaults, is actually a directory containing one
or more station tables. It is assumed that ALL files in this
directory are station files; therefore DO NOT includes extraneous
description or other files in this directory. Station table files
must be in the UW (i.e., wash.sta) standard format.
*/
int STAinit_default ( void );


Function: STAinit_del
/*
Loads station delay table information into memory from file specified
by the path string "del_file_name". Produces FALSE return value if
delay file cannot be found. Message will be issued to standard
error for stations that are not found in the current station table.
*/
int STAinit_del ( char *del_file_name );


Function: STAinit_table
/*
Alternate direct method of initializing station table. This loads
a single station table with a specific path given by the string
"sta_file_name". Additional station tables may be loaded (added)
by repeated calls to STAinit_table. Message is issued to
standard error if file is not found.
*/
int STAinit_table ( char *sta_file_name );


Function: STAisInTable
/*
Returns TRUE if station is in currently loaded table; otherwise
returns FALSE.
*/
int STAisInTable ( char *name );


Function: STAisSeisChan
/*
Returns TRUE if station is both in currently loaded table and is
seismic channel (e.g., not a special channel). Otherwise returns
FALSE.
*/
int STAisSeisChan ( char *name );


Function: STAtable_loaded
/*
Query if station table is loaded. Returns TRUE if station
table is currently loaded; otherwise returns FALSE.
*/
int STAtable_loaded ( void );


LITERAL INCLUDE FILES
INCLUDE FILE: stafileif.h
/*
* LATSIGN & LONSIGN are hack to correct for inadequate sign convention
* in station table. The UW station table has no sign convention
* for longitudes, so we must force one. The correct convention is
* longitude (+ east, - west), latitude (+ north, - south). If (as
* is true for UW convention) longitudes are given without sign, set
* the LONSIGN to -1.0 for stations in west longitudes, +1.0 for
* station in east longitudes. Similarly, set LATSIGN to -1.0
* for stations in south latitudes without sign; +1.0 otherwise.
* Note that this cannot handle stations split between W & E
* longitudes; or stations split between N & S latitudes. Such a
* situation requires a fix to the code and the station table to read
* the sign correctly for each coordinates.
*/
#ifndef __STAFILEIF_H__
#define __STAFILEIF_H__

#ifndef BOOL
#define BOOL int
#endif

struct gcoord { /* geographic coordinates */
float deg, min, sec;
};

struct Gpoint { /* point in geographic coordinate space */
struct gcoord lat, lon;
};
#include "stafileif_proto.h"

#endif /* __STAFILEIF_H__ */



INCLUDE FILE: stafileif_defaults.h
/*
* Set up default path for station table(s) here. owner string
* must be a valid user name on the current system with a home directory.
* Path must be a path relative to the owners home directory containing
* one or more station tables in standard UW (wash.sta) table format.
* Note that all station tables in this directory will be loaded.
* This allows the easy addition or deletion of working station tables
* by dropping them into, or removing them from, the station table
* directory. If duplicate stations entries are encountered (in one
* or more tables, a warning message is issued - the first entry encountered
* holds and successive duplicate entries are ignored.
*/
#define DEFAULT_STA_TABLE_OWNER "lees"
#define DEFAULT_STA_TABLE_PATH "/home/lees/snaps/Tables/ActiveStas"

/*
* Set the sign conventions for the UW style station table
* LATSIGN = +1.0 since we are correct in northern hemisphere
* LONSIGN = -1.0 since we are reversed in western hemisphere
*/
#define LATSIGN 1.0 /* OK for UW since unsigned equiv. to + for N */
#define LONSIGN -1.0 /* UW convention */


AUTHOR
Bob Crosson (bob@geophys.washington.edu)


BUGS
Report bugs to author.



STAFILEIF(UW)