UWPFIF(UW) UWPFIF(UW)



NAME
uwpfif - package for isolation and high level access to UW
style pick files

SYNOPSIS
#include "uwpfif.h"


GENERAL
Uwpfif is a package of high level access routines for
reading and writing UW style pick files. This package of
routines is designed to (a) isolate the users application
program from the details of pick file management, (b)
standardize the way pick files are written and formatted,
(c) provide extensions to the old pickfile format to bring
the pickfile utility up to current broadband, three-compo-
nent standards, and (d) provide backward compatibility
with the "old-style" UW pickfile format so that they can
be read transparently by applications software. To the
degree that applications use this interface package to
read and write pickfiles, when pickfile changes are neces-
sitated, the impact can be localized to the pickfile
interface, allowing little or no modification of end
application programs.


PICKFILE FORMAT DESCRIPTION & CONVENTIONS
UW pickfiles are files constructed to hold seismic parame-
ter data in ascii format which can be read by humans and
edited with standard text editors. By convention, current
pickfile names are constructed of a date-time string con-
sisting of a series of digits representing the start of
the time window of the seismic data from which the pick-
file is derived. These names normally correspond to the
same naming convention used for trace data (year through
10s of seconds), with a final lower case letter that char-
acterizes the nature of the event (e.g., teleseism: 't',
regional: 'r', etc.) or the region where the event is
located.

Note that a current shortcoming of the UW file naming con-
vention is that the year is only valid within a century,
so that when the century boundary is crossed, the file
names will not reflect the correct century. This is also
true for the reference time string contained within the
pickfile itself. This could be handled by an addition
time reference placed within the pickfile, or by external
file management. An example of a current pick file name
is - 92042101141p which is year: 1992, month: 04, day: 21,
hour: 01, minute: 14, seconds: 10. The trailing 'p' char-
acter is a generic pickfile identifier. trailing flags
are by convention lower case alpha characters. See the
man page for uwdfif for further details on the data file
naming conventions.

Within the ascii pickfile, we use a "flagged line" format
with some overall structure conventions. The flag is the
first character in the first column of each line, and it
"flags" the contents of that line. For example, the "A
line" has the character 'A' in column 1, and is followed
by location summary information such as origin time, lati-
tude, longitude, and depth in fixed column locations.
Column 1 must have a recognized character flag or it is
ignored by the interface software and placed unto an
unrecognized category. Some lines require column oriented
data, and some lines allow free field, token oriented
data. This format may be easily extended by defining a
new flag, and then the contents of the new line indicated
by that flag. By adding fairly straightforward extensions
to the software interface, the extensions may be under-
stood and managed by the software interface (uwpfif).
Alternatively, a user may define new flags for restricted
use that are not recognized by the interface, but are nev-
ertheless accessible through the software interface
through the "unrecognized" line capability. In general,
when new data are added to the format, it is done with
free field, token driven conventions to allow greater
flexibility in the format, albeit with somewhat reduced
human readability.

A single pickfile will normally contain data for one event
(earthquake, explosion, etc.) with the following require-
ment: the first line of the file must start with an 'A'
line (i.e., a line beginning with the character 'A' in
column 1). Remaining lines in the pickfile may be in
arbitrary order, but certain order is followed by conven-
tion, making the files easier to read. The order conven-
tion is: A line; E and F lines for error summary info;
phase lines; followed by comment and other lines in arbi-
trary order. The requirement for the 'A' line as the
first line of the pick file is made so that pickfiles may
be concatenated into larger "stream" files for stream mode
processing. This makes it convenient to do certain types
of repetitive processing on collections of pickfiles such
as repeated relocations with a number of velocity models.
Also sorting a single pickfile will result in the 'A' line
emerging at the top of the file. Following is a summary
table of the recognized line types with a brief descrip-
tion of their function, and whether they are column ori-
ented (col), token oriented (tok), or string info (str).

Summary description:
A : event location summary info (col)
E : expanded error info (col)
F : error ellipse info (col)
phase line : (blank - old; . = new) phase arrival
info (tok)
T : time windowing info (tok)
C : comment (str)
N : pickfile name (str)
O : other station names (tok)
M : focal mechanism (tok)
S : additional magnitude info
I : intensity info
D : dead channel info (tok)

Following is a more complete description of each of the
recognized lines in the pickfile.

A line A header line begins with an 'A' in the first col-
umn and contains summary information of the event
origin time, location, magnitude, and other quanti-
ties related to the location. This line is column
oriented and requires only the reference time field
(all other fields are optional). Columns not
specifically referenced below are blank.

Col. 2 : code for event type; recognized types are:
X - Known explosion
P - Probable explosion
F - Felt event
T- Teleseism, H- Hand picked (other `types' take
precedence), L- Low frequency event eg. St. Helens
B-type volcanic earthquake or Rainier low frequency
icequake, R- Regional earthquake (outside network),
S- Special (non earthquake) signal like rockfall,
sonic boom,etc, 8- Earthquake information from
another source and event occurred between 1800 and
1899, 9- Earthquake information from another source
and event occurred between 1900 and 1999.

Cols. 3-12: Reference time for pickfile (required
field)
Reference time from year through minute. An exam-
ple is 8901171355 which represents the time: year -
1989, month 01, day 17, hour 13, and minute 55.
All times in the pick file are in seconds relative
to this reference time. Note that the reference
time has only two year digits, and therefore is not
able to distinguish the century (see abovd).

Cols. 13-18: Origin time in seconds relative to
reference time; floating point with a explicit dec-
imal point.

Cols 20-21: Degrees of latitude.

Col 22: Latitude sign symbol (N for +, S for -)

Cols 23-26 : Decimal minutes of latitude (decimal
point implicit between cols 24 and 25)

Cols 28-30: Degrees of longitude.

Cols 31: Longitude sign symbol (E for +, W for -)

Cols 32-35: Decimal minutes of longitude (decimal
point implicit between cols 33 and 34)

Listing of field names in order:
Type,Year,Month,Day,Hour,Min,Sec,LatDeg,NS,Lat-
min*100,LongDeg,EW,Lonmin*100 Depth,Fix,Magni-
tude,Numsta,numphase,Gap,Min-
delta,RMS,ERR,Q1,Q2,Velmodel

Template:
ATYYMMDDHHMM SS.SS LLNMMMM LLLWMMMM DD.DD* M.M
NN/0NN GGG DD R.RR EE.EQQ VV

Example:
AF8901171355 28.82 47N3919 122W1143 1.53 3.3
38/042 51 8 0.24 0.9BB P3

E line << error summary line >>

F line << error ellipse line >>

phase line
<< phase line >>

C line << comment line >>

N line << file name line >>

O line << other channels line >>

D line << dead channels line >>

M line << mechanism line >>

S line << other magnitudes line >>

I line << intensity line >>

T line << time window line >>


PICKFILE APPLICATION INTERFACE
All externally available functions in this package have
names beginning with UWPF... (for example, UWPFdepth()
provides access to the event depth in the pick file).
Each pickfile represents one logical event (normally an
earthquake or explosion). Pickfiles may be concatenated
together into a pickfile "stream", since each logical
pickfile is defined by its beginning 'A' line.

An important feature of the interface is that it allows
either stream access from/to the standard I/O, or direct
access from/to individual files. To the users applica-
tion, these two modes look identical - the differences are
handled by the interface package and are thus isolated
from the users program. The users program needs only to
make a single simple choice between modes. Stream access
handles one or more concatenated pick files in succession.

Below is a list of the prototype file that is included
with the users program through the header: uwpfif.h. The
prototype gives a convenient list of the functions avail-
able in the package with their argument syntax, and pro-
vides a convenient summary list of the functions for the
programmer. Detailed function descriptions are provided
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:30 1994
*/
#ifndef __UWPFIF_PROTO__
#define __UWPFIF_PROTO__
#if __STDC__

int UWPFcanonStr ( char * );
int UWPFchanRef ( char, struct Chan );
int UWPFchans ( char, int *, struct Chan * );
int UWPFcomment ( char, int *, char * );
int UWPFdeadChan ( char, int *, struct Chan * );
int UWPFdepth ( char, float *, char * );
int UWPFellipse ( char, struct Ellipse * );
int UWPFevtLatLon ( char, float *, float * );
int UWPFevtype ( char, char * );
int UWPFexErrors ( char, float *, float *, float *, float *, int *, char *, float *, float *, float *, float * );
int UWPFfileName ( char, char * );
int UWPFgap ( char, int * );
int UWPFherr ( char, float * );
int UWPFlocProg ( char, char * );
int UWPFmag ( char, float *, float * );
int UWPFmech ( char, int *, struct Mechanism * );
int UWPFhcard ( char, int *, struct Hloc * );

int UWPFmodflg ( char, char * );
int UWPFnearDist ( char, float * );
int UWPFnpobs ( char, int * );
int UWPFnsobs ( char, int * );
int UWPForigsec ( char, float * );
int UWPFparseChanStr ( char *, struct Chan * );
int UWPFpickIndex ( struct Chan, char * );
int UWPFpicks ( char, int *, struct Pick * );
int UWPFqual ( char, char * );
int UWPFrd1evt ( char * );
int UWPFrefTime ( char, struct Time * );
int UWPFrms ( char, float * );
int UWPFsortDist ( void );
int UWPFsortTime ( void );
int UWPFstartNewPickfile ( void );
int UWPFunknowns ( char, int *, char * );
int UWPFunparseChanStr ( struct Chan, char * );
int UWPFwinEndTime ( char, struct Time * );
int UWPFwinStartTime ( char, struct Time * );
int UWPFwr1evt ( char * );
const char *UWPFaLine( void );

#endif /* __STDC__ */
#endif /* __UWPFIF_PROTO__ */


FUNCTION DESCRIPTIONS
Function descriptions are included here, from documenta-
tion extracted directly from the source code via the docu-
mentation extractor: cextdoc. This makes it easy to add
or change functions with the documentation bound directly
to the function definitions. After a change, documenta-
tion is updated by "make doc".

Each function has its documented usage in a comment field
directly ahead of the function definition. In the
extracted documentation, the function name is given in a
header, followed by its comment field documentation, fol-
lowed by the function prototype. Function names are given
in bold. To keep the number of functions comparatively
low, most functions serve multiple uses via a function
code which is the first argument (named "func"). The
function code is always a single character variable (not a
string). Providing multiple use functions necessitates
the heavier use of pointers as arguments, since values
must be passed both into and out of the function.

The function code determines the behavior of the function
when it is called. Commonly a function can inquire,
return, set or unset a parameter in the pickfile. The
function codes corresponding to these four commonest func-
tions are: 'I' (inquire - return truth value depending if
parameter is set or not), 'R' (return value), 'S' (set
value), and 'U' (unset value). Since these four function
codes are used so often, they are not described in detail
in the function comment fields. Where the function codes
deviate from these common four, function codes are
described in detail in the comment fields.


Function: UWPFaLine
/*
* Returns a pointer to the pickfile A line. Note that the application
* should NEVER try to alter the string pointed to by this pointer. NULL
* will be returned if no A line is found.
*/
const char *UWPFaLine ( void );


Function: UWPFcanonStr
/*
* Put channel string into canonical form; convenience routine
* that simply parses and unparses the channel string, knowing that the
* unparsing routine will put back into canonical form. Done in-place
* the users string. TRUE is always returned.
*/
int UWPFcanonStr ( char *chanstr );


Function: UWPFchanRef
/* Access to channel reference in the pickfile; note the use of upper and
lower case flags to reference by full channel info and by station name
only, respectively. This function allows the user to control (add,
remove, or inquire) the reference to a channel in the pick file. If
a channel is removed, its name will not appear in the pickfile. If a
channel is added, its identifier will appear on a 'O' line of no pick is
added, or on a dot line if a pick is added. A channel is automatically
added to the channel reference list if a pick is added. Note that if the
'u' function is selected, all channels with the specified station name
will be removed from the channel reference list.
ARGS
func = function code (I, i, A, U, u) (NONSTANDARD)
i - inquiry; return TRUE if station (only) is referenced
I - inquiry; return TRUE if full channel info is referenced
A - add channel reference with FULL channel info
U - unset (delete) by FULL channel reference
u - unset (delete) by STATION NAME reference only
chan = structure with channel info
*/
int UWPFchanRef ( char func, struct Chan chan );


Function: UWPFchans
/* Provide access to channel list structures; NOTE that the functions are
non-standard here; NOTE that the S function essentially renames a
channel including any associated picks.
ARGS
func = function code (I, R, and S) (NONSTANDARD)
I - returns number of channels
R - return channel struct for channel pointed to by nc
S - set existing channel using chanptr
nc = either number of channels available, or index for specific channel
chanptr = points to structure for particular channel.
*/
int UWPFchans ( char func, int *nc, struct Chan
*chanptr );


Function: UWPFcomment
/* Provides access to pickfile comment lines ('C' lines of pickfile);
there can be an arbitrary number of comment lines in the pickfile.
Access is provided in a non-standard manner; user must provide pointer
to comment buffer which will be used to return old comments and set
new ones. Note that existing comment may not be changed, since space
is dynamically allocated for the comment strings. This avoids the problem
of a user writing beyond the end of available comment storage. If a
comment needs to be changed, delete the old comment and add a new one.
The interface interface will return FALSE if there is an attempt to access
a comment that is not within the available index range. Only the comment
part of the comment line is returned or passed (cols 2- on the C line).
ARGS
func = function code (I, R, U, or A) (NONSTANDARD)
I - return number of comment lines only in "ncmts"
R - return pointer to comment line with index "*ncmts"
U - delete comment line referenced by "*ncmts"
A - add comment line pointed to by cmtptr; note that new number of
comments are returned in "ncmts"
ncmts = int var used to return number of comment lines
and to index individual comment lines
cmtptr = char pointer used to pass and return comment lines;
user must provide storage space
*/
int UWPFcomment ( char func, int *ncmts, char
*cmtptr );


Function: UWPFdeadChan
/* Access dead channel table; dead channels are maintained in a table
within the uwpfif interface. Information on dead channels is returned
or added in the standard Chan structure. The I, R, S, and A function
codes for this function behave the same as for the UWPFcomment function.
The S function code sets a dead channel, replacing the dead channel that
was previously in that position.
ARGS
func = function code (I, R, S, U, or A) (NONSTANDARD)
index = pointer to int used to return the number of entries
in the dead channel table (for I and A functions),
and to point to a specific entry (for R and U functions)
chanptr = pointer used to pass channel struct into table (A function)
and to return chan struct (R function); remember an address
must be passed just like any other variable to be returned
*/
int UWPFdeadChan ( char func, int *index, struct
Chan *chanptr );


Function: UWPFdepth
/* Set or return event depth and flag indicating if depth is set
by seismologist from 'A' line of pickfile. The fixdepth character
is in the column immediately following the depth field on the 'A'
line of the pickfile.
ARGS
func = function code (I, R, S, or U)
depth = depth as float var
fixdepth = char var following depth (typically 'F' if depth fixed)
*/
int UWPFdepth ( char func, float *depth, char
*fixdepth );


Function: UWPFellipse
/* Set or return error ellipse info from 'F' line of pickfile;
NOTE that error ellipse info is passed in a struct "Ellipse",
so all fields are handled in parallel
ARGS
func = function code (I, R, S, or U)
ee = error ellipse info as structure (struct Ellipse)
*/
int UWPFellipse ( char func, struct Ellipse *ee );


Function: UWPFevtLatLon
/* Set or return event location as float lat & lon variables. These
quantities are stored in the 'A' line of pickfile. They are returned
as single float variables in degrees.
ARGS
func = function code (I, R, S, or U)
lat = event latitude in degrees as float var (+ north, - south)
lon = event longitude in degrees as float var (+ east, - west)
*/
int UWPFevtLatLon ( char func, float *lat, float
*lon );


Function: UWPFevtype
/* Set or return event type flag. This is the second column of the 'A' line
of the pickfile. Note that this is a single character (not a string) for
which the address must be passed to the function.
ARGS
func = function code (I, R, S, or U)
type = event flag character
*/
int UWPFevtype ( char func, char *type );


Function: UWPFexErrors
/* Set or return extended residual & error info from 'E' line of
pickfile; NOTE that this information is handled as an "all or
nothing" package (all variables are handled in parallel so that
the function selected applies to all vars)
ARGS
func = function code (I, R, S, or U)
meanres = mean residual (float)
stdr0 = standard deviation of residuals about zero (float)
stdrm = standard deviation of residuals about mean (float)
sswres = sum of squared weighted residuals (float)
ndrf = number of degrees of freedom (int); this is the number
of observations minus the number of unknowns (usually 4)
fixflgs = string indicating which hypocenter parameters are
fixed (char string of len 4)
stderrx = standard error of latitude (in km)
stderry = standard error of longitude (in km)
stderrz = standard error of depth (in km)
stderrt = standard error of time (in secs)
*/
int UWPFexErrors ( char func, float *meanres, float
*stdr0, float *stdrm, float *sswres, int *ndfr,
char *fixflgs, float *sterrx, float *sterry, float
*sterrz, float *sterrt );


Function: UWPFfileName
/* Return the pickfile name string contained on the N line of the
pickfile. The 'I' function returns FALSE if there is no N line
(not initialized). If the N line is not initialized, the 'R' function
will return a null string.
ARGS
func = function code (I, R, S, or U)
name = pickfile name string (user must provide address of
pointer to return the pointer to string)
*/
int UWPFfileName ( char func, char *name );


Function: UWPFgap
/* Set or return gap value (in degrees) from 'A' line of pickfile
ARGS
func = function code (I, R, S, or U)
gap = gap value as int var (gap in degrees)
*/
int UWPFgap ( char func, int *gap );


Function: UWPFherr
/* Set or return the horizontal error value from the 'A' line of pickfile
ARGS
func = function code (I, R, S, or U)
herr = horizontal error as float value
*/
int UWPFherr ( char func, float *herr );


Function: UWPFlocProg
/* Set or return the location program flag from 'E' line
of pickfile; NOTE that this flag is a 2 char string, so char
buffer used to pass this string must be at least of length 3
to allow for null termination.
ARGS
func = function code (I, R, S, or U)
locprog = location routine flag as 2 char string
*/
int UWPFlocProg ( char func, char *locprog );


Function: UWPFmag
/* Set or return event magnitude and standard error of magnitude
from 'A' line of pickfile.
ARGS
func = function code char (I, R, S, or U)
mag = magnitude value as float var
serrmag = standard error of magnitude as float var
*/
int UWPFmag ( char func, float *mag, float *serrmag
);


Function: UWPFmech
/* Provides access to mechanism lines ('M' lines) in pickfile. There
can be an arbitrary number of mechanism lines, so mechanism lines
are handled in non-standard manner (similar to comment lines). Info
on each mechanism line is returned in a mechanism structure (Mechanism)
which is defined in a header for the uwpfif interface; user must
provide space for struct Mechanism for both set and return functions.
ARGS
func = function code (I, R, U, or A) (NONSTANDARD)
I - inquire about number of mechanism lines (returns nm)
R - return mechanism pointed to by nm through pointer mec
U - unset mechanism pointed to by nm (new number returned)
A - add mechanism (new number returned)
nm = int variable used to return number of mechs and point
to specific mech
mech = mechanism struct (pointer to structure in users
space used to pass mechanism info to/from pickfile
*/
int UWPFmech ( char func, int *nm, struct Mechanism
*mec );


Function: UWPFmodflg
/* Set or return model flag string from 'A' line of pickfile;
NOTE that this is 2 char string, so char buffer used to pass
this string must be at least of length 3 to allow for null
termination
ARGS
func = function code (I, R, S, or U)
modflg = model flag string as 2 char string
*/
int UWPFmodflg ( char func, char *modflg );


Function: UWPFnearDist
/* Set or return distance to closest station parameter from 'A' line of
pickfile
ARGS
func = function code (I, R, S, or U)
nearsta = nearest station value as float var
*/
int UWPFnearDist ( char func, float *nearsta );


Function: UWPFnpobs
/* Set or return number of P observations from the 'A' line of pickfile.
ARGS
func = function code (I, R, S, or U)
npobs = number of P obs as int var
*/
int UWPFnpobs ( char func, int *npobs );


Function: UWPFnsobs
/* Set or return number of S observations from 'A' line of pickfile
ARGS
func = function code (I, R, S, or U)
nsobs = number of S obs as int var
*/
int UWPFnsobs ( char func, int *nsobs );


Function: UWPForigsec
/* Set or return origin time (seconds field only) for 'A' line of the
pickfile. NOTE that this is a single float variable that is defined
relative to the reference time (see UWPFreftime)
ARGS
func = function code (I, R, S, or U)
origtime = origin time (as float seconds relative to ref time)
*/
int UWPForigsec ( char func, float *origtime );


Function: UWPFparseChanStr
/*
* parse channel id string (chanstr) into users channel ID structure (chan)
*/
int UWPFparseChanStr ( char *chanstr, struct Chan
*chan );


Function: UWPFpickIndex
/*
* Return index of pick with channel structure matching "tchan"
* and pick type matching "picktype"; if pick does not exist, then
* return -1 (an illegal pick index)
*/
int UWPFpickIndex ( struct Chan tchan, char *pick-
type );


Function: UWPFpicks
/* Provide access to pick info structures; NOTE that the functions are
non-standard here; all picks regardless of type are handled the same here.
NOTE also that it is an error to attempt to change the channel of
a pick using the 'S' function. To change the channel, the pick must
be unset and a new pick added with the desired channel.
ARGS
func = function code (I, R, A, and U) (NONSTANDARD)
I - returns number of picks
R - return pick struct for pick pointed to by np
S - set existing pick using pickptr
A - add new pick defined contents of input struct (new np returned)
U - unset pick pointed to by np; note that pick is not actually
removed, it is just "turned off"; this means that it will
not actually be written out in a new pickfile
np = either number of picks available, or index for specific pick
picptr = points to structure for particular pick.
*/
int UWPFpicks ( char func, int *np, struct Pick
*pickptr );


Function: UWPFqual
/* Set or return the quality flag string from 'A' line of pickfile;
NOTE that this is a 2 char string, so char buffer used to pass
this argument must be at least of length 3 to allow for null
termination
ARGS
func = function code (I, R, S, or U)
qual = quality string as 2 char string
*/
int UWPFqual ( char func, char *qual );


Function: UWPFrd1evt
/* Read one pick file from either stream input, or from file and
initialize all variables; if a file name is given, then file mode
is assumed; if file name is a null string, then stream mode
is assumed. FALSE is returned if there is no more data to
read (end of file is encountered immediately). Otherwise TRUE
is returned.
ARGS
pickfilename: file name as string
*/
int UWPFrd1evt ( char *pickfilename );


Function: UWPFrefTime
/* Set or return reference time from 'A' line of pickfile. The
reference time is used for all timing quantities in the pickfile.
Normally, the seconds field of the reference time structure is
set to zero, since reference times are given only to the minute
in the pickfile.
ARGS
func = function code (I, R, S, or U)
time = structure containing reference time; struct Time
is defined in headers for the uwdfif package; NOTE that
only the year through minutes fields of Time are used
for the reference time
*/
int UWPFrefTime ( char func, struct Time *time );


Function: UWPFrms
/* Set or return rms residual value from both 'A' line and 'E' line
of the pickfile; NOTE that the same value is set in both A and
E lines, but with one extra decimal point of precision in E line
ARGS
func = function code (I, R, S, or U)
rms = rms value as float var
*/
int UWPFrms ( char func, float *rms );


Function: UWPFsortDist
/* Sort pick array into ascending distance order from current epicenter.
Returns TRUE if sort is successful. If there is no current
epicenter, the return value is FALSE. Routine can be called to
ensure that pickfile output will have picks listed in distance
order from epicenter.
*/
int UWPFsortDist ( void );


Function: UWPFsortTime
/* Sort pick array into ascending arrival time order. Pick type is
ignored in the sort. Return TRUE if sort is successful.
*/
int UWPFsortTime ( void );


Function: UWPFstartNewPickfile
/* Initialize for generating new pick file. This function sets
up buffers so that a new pickfile may be initialized and written.
Must be called prior to setting any variables in the new pickfile.
ARGS
None
*/
int UWPFstartNewPickfile ( void );


Function: UWPFunknowns
/* Access lines that are unknown to the pickfile interface.
There can be an arbitrary number of these lines in the pickfile.
Access is provided in a non-standard manner; user must specify these
lines by the reference int "index", after finding out how many
of these lines currently exist. The lines are returned as strings
in the users space. Note that the entire line is returned as one
string, provide complete access to any of these lines. As with the
comment strings, a line cannot be changed, only unset and a new line
added.
ARGS
func = function code (I, R, U, or A) (NONSTANDARD)
I - inquire (return) number of comment lines only in "index"
R - return pointer to comment line with index "*index"
U - unset (delete) comment line referenced by "*index"
A - add line pointed to by lineptr; note that new
number of unknown lines are returned in "index"
index = pointer to int used to return number of unknown lines
(I and A functions) and index specific line (R and U functions)
unknownlintstr = address of pointer used to return line specified by
index
*/
int UWPFunknowns ( char func, int *index, char
*unknownlinestr );


Function: UWPFunparseChanStr
/*
* Unparse the input channel structure back into channel string;
* routine always puts channel string back into canonical form
* TRUE is always returned; user can test if the resultant string
* is empty if this is needed.
*/
int UWPFunparseChanStr ( struct Chan chan, char
*str_out );


Function: UWPFwinEndTime
/* Provide access to end time on T line; returns TRUE if defined
Note that here we can use the 'R' flag to both inquire and return
value if set, at the same time
ARGS
func = function code (I, R, S, or U)
winEndTime = pointer to end time of window as Time struct
*/
int UWPFwinEndTime ( char func, struct Time
*winEndTime );


Function: UWPFwinStartTime
/* Provide access to start time on T line; returns TRUE if defined
Note that here we can use the 'R' flag to both inquire and return
value if set, at the same time
ARGS
func = function code (I, R, S, or U)
startTime = pointer to start time of window as Time struct
*/
int UWPFwinStartTime ( char func, struct Time *win-
StartTime );


Function: UWPFwr1evt
/* Write out one pickfile. If non-null pickfile name is given,
then the results are written to that file which is opened
in write mode, written, and then closed. If pickfile name
is null string, then the results are placed on standard output
stream. Returns TRUE if successful.
ARGS
pickfilename = name of file to write to (null string if
standard output)
*/
int UWPFwr1evt ( char *pickfilename );


UWPFIF HEADER
All applications using the interface should include the
"uwpfif.h" header to ensure proper declaration of needed
structures and function prototypes. A copy of this header
file is given below, primarily for definitions of needed
structures such as Chan, Mechanism, Pick, etc.

/*
* This header is to be used by applications using the uwpfif interface.
* There are some structures defined here that are passed by external
* access routines.
*/

#ifndef BOOL
#define BOOL int
#endif

#ifndef TRUE
#define TRUE (1)
#endif

#ifndef FALSE
#define FALSE (0)
#endif

#ifndef MAX
#define MAX(a,b) ((a) > (b) ? (a) : (b))
#endif

#ifndef MIN
#define MIN(a,b) ((a) <= (b) ? (a) : (b))
#endif

/*
* Struct for full time; all routines should use this
*/
#ifndef TIME_DEFINED
#define TIME_DEFINED
struct Time {
int yr, mon, day, hr, min;
double sec;
}; /* length of Time = 28 bytes */
#endif

/*
* Struct for trace data; specifies name, component,
* and chan id in one structure
*/
struct Chan {
char name[8]; /* station name; e.g., GMW, SHW, ... */
char comp[8]; /* component string; e.g., SHZ, SHN, SHE, ... */
char chid[8]; /* channel id string; e.g., 0, 1, ... (often not used) */
};

/*
* Struct for phase arrival time packet; this is needed by applications.
* The quantities have the following meaning (all character tokens are
* handled as strings)
* type = phase type; e.g., P, S, PmP, Pg, ...
* pol = polarity; U, D, +, -, ...
* time = arrival time in float seconds (relative to reference time)
* etime = uncertainty in time; used in location calcs, inversion, etc.
* res = residual (obs - calc); calculated in locations calcs, etc.
* dur = duration from phase; typically coda duration from P pick
* dist = distance of pick (station) from epicenter
* wt = string for traditional (USGS) wt flg (typically 0, 1, 2, ... 9)
* ietime = true if etime is initialized
* ires = TRUE if residual is initialized
* idur = TRUE if duration is initialized
* chan = complete channel id (name, comp, chid)
* pickon = TRUE if pick is turned on; set FALSE to deactivate pick
* machine_time = TRUE if time is machine picked
* machine_dur = TRUE if dur is machine picked
* amptime = time of amplitude pick (relative to reference time)
* ampvalue = amplitude value
* ampon = TRUE if amplitude is initialized
*/
struct Pick {
char type[8];
char pol[4];
float time, etime, res, dur, dist;
char wt[8];
BOOL ietime, ires, idur;
BOOL pickon, machine_time, machine_dur;
struct Chan chan;
float amptime, ampvalue;
BOOL ampon;
};

/*
* Struct for 3 orthogonal axes of error ellipse info
*/
struct Ellipse {
float azim[3], plunge[3], val[3];
float maxherr, maxverr;
};

/*
* Struct for single pole info (for focal mech)
*/
struct pole {
float az, pl;
};

/*
* Struct for one complete focal mech, UW style; az = azimuth, pl = plunge
*/
struct Mechanism {
struct pole Fplane, Gplane, Upole, Vpole, Ppole, Tpole;
BOOL Finit, Ginit, Uinit, Vinit, Pinit, Tinit;
};




/*
* Struct for one complete H card
*/
struct Hloc {
int yy, mo, dd, hh, mi;
float sec, lat, lon, dep, mag;
};




#include "uwpfif_proto.h"


EXAMPLE PROGRAM
<< EXAMPLE PROGRAM WILL GO HERE >>


AUTHOR
Pickfile Interface: Bob Crosson, Geopysics Program, Uni-
versity of Washington
Pickfile format and conventions: numerous folks have
helped


BUGS
Report bugs in pickfile interface to bob@geophys.washing-
ton.edu



UWPFIF(UW)