File iscbul.txt -- a description of the program iscbul 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.10. 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, your 'current directory' cannot be the CD-ROM. 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 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 66 .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.txt ) 1.2.2 Building for MS-DOS There are 80 .FOR files and 2 .INC files. A sample script (compile.bat) and a link response file (makeobj) are provided to build an MS-DOS version - however 'compile.bat' may need the 'SET LIB' line changing for a particular installation. To compile the software and build your own executable on your hard disk :- * Copy the source files *.FOR ; *.INC ; compile.bat ; makeobj from the \iscbul\MSDOS directory on the CD-ROM to your own directory on the hard disk. 1.2.2.1 Step by step method (without using compile.bat) * Check that the environment variable LIB is set correctly. * Type SET to check the setting. LIB should be set to point to the directory containing the LLIBFOR7.LIB library file. Check with your system manager if you are not sure where this is. * If (for example) the library file LLIBFOR7.LIB resides in C:\XYZ\LIB - then to set the environment variable LIB, type :- SET LIB=C:\XYZ\LIB * Type the following :- FL /c *.FOR (Note the lower case 'c') LINK @MAKEOBJ This will create the executable iscbul.EXE in your directory on the hard disk. 1.2.2.2 Using compile.bat file The file contents are :- SET LIB=C:\FORTRAN\LIB FL /c *.FOR LINK @MAKEOBJ where ISC's fortran libraries are in C:\FORTRAN/LIB If your libraries are in a different place - change this line accordingly. Then to compile/link/create the executable iscbul.EXE - type :- compile 1.2.2.3 Version with centi-seconds Another version of showea (showea_centisecs.f) is also provided. This enables hypocenter centi-seconds to be output. In order to use this file for Unix - change 'showea.o' to 'showea_centisecs.o' in the file 'makefile' and re-make the executable. For msdos - change the name of 'showea.for' to 'showea.for.keep' (or a name of your own choice) and change the name of 'showea_centisecs.f' (the unix suffix '.f' was left there so that it was not normally compiled) to 'showea.for' - and then re-build the executable. NOTE - however that all output columns after the time output are shifted right by three columns. 1.2.2.4 Version with latitude/longitude to 4 decimal places Another version of showea (showea_lat.f) is also provided. This enables hypocenter latitude and longitude to be displayed to 4 decimal places. In order to use this file for Unix - change 'showea.o' to 'showea_lat.o' in the file 'makefile' and re-make the executable. For msdos - change the name of 'showea.for' to 'showea.for.keep' (or a name of your own choice) and change the name of 'showea_lat.f' (the unix suffix '.f' was left there so that it was not normally compiled) to 'showea.for' - and then re-build the executable. NOTE - however that all output columns after the latitude and longitude output are shifted right by four columns. 1.2.2.5 Version with centi-seconds and latitude/longitude to 4 decimal places Another version of showea (showea_lat_cs.f) is also provided. This enables hypocenter centi-seconds AND latitude and longitude to be displayed to 4 decimal places. In order to use this file for Unix - change 'showea.o' to 'showea_lat_cs.o' in the file 'makefile' and re-make the executable. For msdos - change the name of 'showea.for' to 'showea.for.keep' (or a name of your own choice) and change the name of 'showea_lat_cs.f' (the unix suffix '.f' was left there so that it was not normally compiled) to 'showea.for' - and then re-build the executable. NOTE - however that all output columns after the latitude and longitude output are shifted right by seven columns. 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 data files are on drive D - see 'Root' - below). 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, many users 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 to 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. (The 'output filename' option can also be used for file output - see section 3). 2.2 Running under MS-DOS The possible user-inputs and resulting actions are as follows :- * 'Enter' (or 'Return') - displays a further screen-full (24 lines). * 'C' - produces a continuous display. * A number eg '10' - displays the next 10 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. Keyword Notes ------- ----- 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 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. 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. 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. 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. 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 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 Column 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 or 58-68 Log A/T 4.4 Fields in phase comment records 1- 6 Station code 7- Comment