Description of iscbul


  1. Installing iscbul
  2. Running iscbul
  3. Command line options
  4. Output Format

1 Installing iscbul

Compiled and linked versions of iscbul are included for MS-DOS (iscbul/MSDOS/iscbul.exe) and Sun Solaris 7 (iscbul/unix/iscbul). The MS-DOS version was compiled at ISC with Microsoft FORTRAN Compiler Version 5.00.03. using the /FPi option. The Unix version was compiled and linked with Sun Microsystems f77 compiler with the -e option and ld link editor.

1.1 Installing a built version

Each version of iscbul creates temporary files in the directory from which it is run. Thus, in order to use one of the executable versions of iscbul on the CD, it must first be copied to a directory on your own disk.

1.1.1 Installing the built Unix version

You may want to copy the executable to a directory included in your PATH environment variable. To run any Fortran program linked on another system, including iscbul, it may be necessary to set the environment variable LD_LIBRARY_PATH. The list of paths in this variable would have to include the directory where dynamically-linked Fortran libraries are kept on your system.

1.1.2 Installing the built MS-DOS version

It is possible to do use the ISCBUL program and access the bulletin data from the CD-ROM without moving any program or data files to your directory on the hard disk. First of all, load the CD-ROM and determine which drive the CD-ROM is on. If, for example, the CD-ROM is on drive G, then typing the following at the command prompt will list the prime estimates of events for 1993 :-

 G:\iscbul root G time 1993

If the program is run from the CD-ROM, AND your current directory is ALSO on the CD-ROM (ie G in the above example) then it will fail with:-

   run-time error F6414: OPEN(ZZ009467)
   - access not allowed

when it attempts to create scratch files on the CD-ROM.

1.2 Building from source code

For either Unix or MS-DOS, it is probably best to copy the complete set of source files (.for or .f) and include files (.inc) to a newly created directory and compile and link them there. The source files differ slightly in some of their file naming conventions and the Unix version includes routines for a few services that are supplied by system utilities under MS-DOS.

1.2.1 Building for Unix

There are 64.f files and 2 .inc files, which should all be copied to a newly created directory of your choice. A Makefile is included in the source directory. The Makefile includes comments that may be useful if the first attempt at building the binary fails. ( Please note that the Makefile file is named makefile.txt on the CD and would need to be renamed Makefile if it is to be used or use make -f makefile )

1.2.2 Building for MS-DOS

There are 64 .for files and 2 .inc files. No script is provided to build an MS-DOS version. To compile the software and build < your own executable on your hard disk :-

2 Running iscbul

ISCBUL is run by typing iscbul at the command prompt followed by at least one keyword and value pair - e.g. :-

             iscbul time 1990 

NOTE - this minimum case assumes that the program can find the data files without additional information. See command line option 'Root'.

The program is run by typing iscbul at the command prompt followed by at least one keyword and value pair, e.g.,

    iscbul time 1990
This command should cause the program to begin listing the prime estimates of the events in the ISC bulletin for 1990 January. Note that by default iscbul provides the minimum amount of information: prime estimates only. Further information is available for each event by using the "Show" command line option (see section 4 below).

2.1 Running under Unix

Under Unix, users may prefer to use the option 'C' - continuous mode, which causes iscbul to write all of the selected information to stdout (standard output) without interruption. The normal Unix options can be used capture this information. For example, it can be piped to more (" | more") to be viewed one screen-full at a time or redirected to a file ("> filename") for examination using a text editor or for further processing.

2.2 Running under MS-DOS

Once a full screen of information has been displayed a prompt will be shown (unless the 'C[ontinuous]' command line option is used). The possible user-inputs and resulting actions are :-

'Enter' (or 'Return') displays a further screen-full (20 lines).
'C' produces a continuous display.
A number, [n], e.g. '10' displays the next [n] lines of output
The number '0' stops the program

(NOTE - C/number/0 inputs are all terminated by 'Enter'/'Return').

The use of the 'C' - continuous mode, together with the use of the 'Output' keyword (see below), is probably the most effective way of producing usable data for further processing. The resulting text file can then be input to a text editor or even a word processor such as WORD, for ease of reading/editing, and also for input to other user's programs.

Control on the information selected can be made by entering keyword and value pairs. The keywords are case independent and can be abbreviated to the part shown in upper case text in the table below.

2.3 Running under Windows

Under Windows 95 or Windows NT, from the "Start" menu the standard configuration includes a submenu "Programs", which includes an item "Command Prompt". Selecting "Command Prompt" opens a text window. In this window, iscbul can be run as an MS-DOS program.

3 Command line options

Control on the information selected can be made by putting keyword and value pairs on the command line. The keywords are case independent and can be abbreviated to the part shown in upper case text in the table below. For example the keyword 'LAtitude' can be entered as 'la' or 'LAT' or 'LATITUDE' or even 'lAtItUdE', but 'l' or 'L' would not be sufficient.

Use of the Time, LAtitude and LOngitude keywords will cause selection of events based on matching the criteria specified against the prime estimates found within the fixed format bulletin (.FFB) files. The prime estimate being the estimate of the event adopted by the ISC for calculating the station distances, azimuths, time residuals etc.

3.1 Command Line option "Root"

Default = D

This keyword instructs the program where it is to find the data files. The default has been set to 'D' so that it expects to find the monthly data files for the year 1993 on the path D:\1993\. If your data is on device L then the keyword 'ROOT' and value 'L' should be specified on the command line.

    e.g.   iscbul r l

The data files could be copied to another path, for example if they were copied from device D to a subdirectory on the hard disk C using:

           xcopy d: c:\iscdata /s

The files could then be referenced by:

           iscbul r c:\iscdata

3.2 Command Line option "Time"

Default is all data in the .FFB files within the path.

This can either be specified as a single value or a range. A range is indicated by providing two values separated by a minus sign. If a range is given the earlier time should be given first.

Examples of the single values allowed are:

    1993            All data for the year 1993
    199303          All data for 1993 March
    19930317        All data for 1993 March 17th.
    1993031703      All data for specified hour.
    199312312359    All data for specified minute.
    19930102030405  All data for specified second.

An example of a range would be:

    199211-19930221 All data from 1992 Nov to 1993 Feb. 21st.

3.3 Command Line option "LAtitude"

Default = 90S-90N

Latitude range - given as a pair of values joined by a minus ('-'). South is negative and North is positive. Hemisphere can be indicated by S or N as suffix or by preceding the value with a sign. Note that -3S would be interpreted as 3 degrees North. 54.00S and -54 are equivalent.

3.4 Command Line option "LOngitude"

Default = 180W-180E

Longitude range - given as a pair of values joined by a minus ('-'). West is negative and East is positive. Hemisphere can be indicated by E or W as suffix or by preceding the value with a sign. Note that -3W would be interpreted as 3 degrees East and that 54.00W and -54 are equivalent.

The Westernmost longitude should be given first. Thus 54W-44W will select events in the 10 degree range between 54W and 44W, but 44W-54W will select events in a 350 degree range.

3.5 Command Line option "Output"

Default to screen

Output file name. If the file already exists the program will fail. The output device must be writeable and there is nothing within the program to prevent your output file filling up the output device.

e.g.     o junk.txt               

3.6 Command Line option "Show"

Default = 1

Level of detail to be shown

  1. Prime estimates only - those from which distances and azimuths are given in the ISC bulletin.
  2. All estimates
  3. All estimates and epicentral comments
  4. All estimates, comments and initial phases
  5. All estimates, comments and all phases
  6. All estimates, comments, phases and phase comments

4 Output Format

The output generated is in the same order as the .FFB files.

4.1 Fields in epicentral records

             1- 5  Agency code 
                6  '*' if prime estimate
             7-25  Date and time 
            27-40  Latitude and longitude 
            42-44  Depth in kilometres
            46-50  First magnitude and type
            51-55  Second magnitude and type
            56-60  Number of observations
            61-    Flinn-Engdahl region name (prime estimates only)

4.2 Fields in epicentral comments records

             1- 6  Agency code
             7-    Comment

4.3 Fields in phase records

             1- 6  Station code
             7-12  Distance in degrees
            14-16  Azimuth (epicentre to station)
               17  Component
               18  First motion
               19  Onset (e or i)
            20-27  Station phase identification
            28-35  ISC phase identification
            36-46  Time
            47-51  Residual in seconds from station identification
            52-56  Residual in seconds from ISC identification
               58  A - if amplitude given
            59-62  Mantissa of amplitude in nanometres
               63  E - if amplitude given
            64-65  Exponent of amplitude in nanometres
               67  T - if period given
            68-72  Period in seconds
            58-68  Log A/T

4.4 Fields in phase comment records

             1- 6  Station code
             7-    Comment

Last modified: Wed Jun 23 13:13:34 BST 1999