Operator Control of Program Behaviour
There are two ways that the user can influence how iscloc works without
changing source code and recompiling. To change the behaviour of an
entire instance of the program the configuration file
must be edited, while to affect the way that an individual event is treated instructions
can be given on the command line.
Configuration file - config.txt
When the program is first run a function read_config
is called that reads a file (called config.txt here) whose path and name is set using a #define
statement at the top of main. This file informs the program where to write its error messages,
log file, and data output as well as containing a number of seismological
constants used in the solution. Each line in config.txt corresponds
to an external variable which is assigned in read_config
and which can be declared in any function that needs to know its value.
The options concerning input and output are listed here. Other
constants and options are dealt with elsewhere, when discussing those parts
of the program where the values become important.
There are 7 external variables related to input and output assigned in
read_config
and corresponding to possible lines in config.txt:
-
instructfile - input stream to read lines of instructions, one per event. Can be stdin or a filename.
-
logfile - output stream for information and error messages. Can be stderr, stdout, or a filename.
-
errfile - output stream for error messages. Can be stderr, stdout, or a filename.
- isf_outfile - output stream for ISF format event reports. Can be stdout or a filename or could not be there at all.
- update_db - 0 or 1. If 1 then output will be made to database, assuming a schema like that at the ISC.
- repid - numerical report ID. If update_db
is set then data will be inserted with this repid.
-
out_agency - agency code. If update_db
is set then data will be inserted with author set to this value.
-
isf_stafile - if data for an event is input from ISF file (see instructions
) then station data will be read from here, not the database.
By editing these lines in the configuration file it is possible to output solutions
to either database or ISF file or to neither or both. The format of
the input is controlled on an event by event basis, as described below, but
if an ISF filename is given on the instruction line then there must be a
valid isf_stafile
line in the configuration file as the program will not try and get station
information from the database if it is getting the rest of its data elsewhere.
Error messages will be written to the logfile
stream as well as to the errfile
stream so that they can be seen in the context of the event and of the process
that was running at the time the error occurred. To only send errors
to the same place as other messages logfile
must have the same value as errfile
- errors will only be written there once.
Instructions
Each time iscloc is ready to start a new event one line is read from instructfile, this is referred to as the instruction line and is parsed by function read_instruction. The instruction line must include either the evid of the next event
to be read from the database or the filename of an ISF format file to read
the next event from. If the filename is the same as for the previous
event then the event after the previous one will be read, otherwise the first
event in the file will be taken. (If the filename option is chosen isf_stafile
must be set, see above.)
In addition to the parameters set in config.txt
there are certain parameters that can be set on an event by event basis
on the instruction line. These include the agency code of the hypocentre
to be used as the first starting point and options to fix the solution to
lesser or greater degree. These parameters may be in any order in parameter=value
format or, in some cases, as flags whose presence on the line is enough.
Possible entries on the instruction line are:
- bare integer - evid of next event to read from database.
- filename=string - read next isf event from this file.
- seed=AGENCY - use this agencies hypocentre as the first seed.
- depth=AGENCY - fix depth to this agency's hypocentre depth.
- depth=value - fix depth to this number.
- location=AGENCY - fix location to this agency's hypocentre location.
- lat=value - fix latitude to this value ( lon must also be fixed.)
- lon=value - fix longitude to this value ( lat must also be fixed.)
- time=AGENCY - fix solution to this agency's hypocentre time.
- time=datetime - fix location to this time (in yyyy/mm/dd_hh:mm:ss.sss).
- fix_on_depdp- presence means that depth will be fixed using pP phases.
- no_reid_phase - presence sets flag for no phase reidentification (id_pha).
- no_purge_phase - presence sets flag for no phase purging (purge_pha).
It is not possible to fix location without fixing depth or to fix time without
fixing location. If only location is fixed by agency then depth will
be fixed by the same agency. If only time is fixed by agency then the other
parameters will be fixed using the same agency. If location is fixed explicitly
but depth is not fixed then depth will be fixed to the default value from
config.txt. Fixing time explicitly but not fixing the location is an error.
The checks on instruction consistency are done in function init_event, where fixing by agency is also implemented.
For example, (assuming instructfile
= stdin) these two lines are equivalent and iscloc will calculate residuals w.r.t. to an NEIC hypocentre:
echo '1759325 depth=NEIC location=NEIC time=NEIC' | location
echo '1759325 time=NEIC' | iscloc
This flexibility does make it possible to do funky things if desired, for
example to fix the latitude and longitude to that of the NEIC but fix the
depth to 33 km:
echo '1759325 depth=33 location='NEIC' | iscloc
Other examples:
echo 'filename=cannikin.isf seed=IASPEI' | iscloc
To calculate a hypocentre for an event from an ISF text file, choosing which existing hypocentre to use as first seed.
echo 'filename=nevada.isf lat=37.17 lon=-116.45 depth=18.7' | iscloc
To solve only for origin time.