contents

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:
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:
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.