Introduction ============ IASPEI Seismic Format is an extension to IMS1.0 or GSE2.1. Thus, an ISF parser will read or write IMS1.0 formatted data but can also read or write additional data types, not included in IMS1.0. This is done by introducing new blocks and sub_blocks to the IMS1.0 standard and by using formatted IMS1.0 comments. A description of the IMS1.0 format can be found in a variety of formats at the Swiss Seismological Service at "http://seismo.ethz.ch/autodrm/autodrm_doc.html" A PDF document describing the ISF extension can be downloaded from "http://www.isc.ac.uk/Documents/isf.pdf" The purpose of the ISC's library of ISF functions is to help users read and write properly formatted ISF bulletins. The library functions perform no data manipulation; they merely parse or format individual lines of an ISF bulletin. The ISC's ISF library is implemented in 2 languages: Fortran C Function names are the same in both languages, the only differences are those necessitated by differences between the languages. A PERL version of the functions is planned. For each type of data line in the ISF "bulletin" data-type, the library includes: - a function to parse a line and assign values to variables - a function to write a line with values from variables - a function to assign null values to the variables For each type of header line in the ISC "bulletin" data-type, the library includes: - a function to confirm that a read line is a header line of given type - a function to write a header, including the preceding blank line Line types are: type head data type head data type head data ----------- ---- ---- ----------- ---- ---- ----------- ---- ---- data type x origin x x phase x x event x prime x phase info x x comment x centroid x phase min x stop magnitude x x phase max x mag stations x original x mag basis x origin ID x momten x x correction x fault_plane x x measure x prinax x x param x effects x x Availability ============ The ISC offers source code only. Users must compile the Fortran and C functions and, if they wish, build a library to more easily link in only the functions required by each of their programs. The source code has been compiled and tested successfully with both the gnu and Solaris compilers for Fortran and C. For each language there are 4 files containing subprograms and a header file. These are called. isf_read.[cf] isf_writ.[cf] isf_null.[cf] isf_util.[cf] isf_bul.h The first 3 files can be compiled independently of each other but both the read and write files contain calls to functions in isf_util. The source files are available by anonymous ftp from ftp://seismo.isc.ac.uk/pub/ISF/src Values Returned =============== Each function returns an integer, which is 0 if the function ran successfully. Each function returns a value of 20 if parsing or writing fails completely and the function ends early. Examples would be if a field to be parsed as a number contains letters or if a file to be written to is unwritable. Write functions have an additional return value of 10. These functions keep track of the type of line last written by a program. Data will be written regardless of this but if the type of the line being written should not, according to the ISF format, follow the previous type written then a value of 10 will be returned. No function tries to correct values. If a value is too large for the field provided by the ISF format then the function will stop and return an error. This will also happen in a few simple cases where the data provided does not make sense, such as an hour greater than 23 or an azimuth greater than 360. When an error occurs, the function will assign an error message to the string isf_bulletin_error, which can be printed for further information on the nature of an error. Null Values =========== To avoid conflict between null and zero values for numeric parameters a value ISF_NULL is defined. Numeric parameters are assigned this value when they have no other value. String parameters are assigned the null string "" in C or left empty in FORTRAN when they have no other value. The write functions write space characters where a variable has the null value and the parameter concerned is optional. The read functions assign the null value to variables where the line parsed has space characters where an optional value could have been. Header files ============ A header file called 'isf_bul.h' is provided for each language. This should be included from the users main program. Maximum lengths are defined for those parameters in an ISF bulletin that need to be treated as strings. These lengths can be used to declare character arrays to store such strings. The variables 'isf_bulletin_error' and 'isf_prev_line_type' are set up in the header files, as global variables in C and as common blocks in FORTRAN. The parameter ISF_NULL is defined in the header files. The C header file contains prototypes for all of the ISF C functions but in FORTRAN any functions called from main must be declared in main - they all return integer. Writing a Bulletin ================== The user is responsible for opening the output file, assigning values to variables representing the required parameters and passing these variables to the relevant ISF functions. If only some of the parameters expected by a given function are known it may be useful to create variables for all of the possible parameters and pass them to the respective nullify function before assigning values for those that are known. This means that the write function can be called with a full list of arguments without worrying which have values for any specific line of data. If only ISF library functions are used to write to a bulletin then each one should return 0 on completion. This not only confirms that the write was successful but that the order of lines within the bulletin so far conforms to the format specification. The user may choose to write some lines on their own, rather than using a function from the library, but in that case (unless the user sets 'isf_prev_line_type') the value returned by library functions called afterwards will be 10 after a successful write. The functions that write headers for the various blocks and sub-blocks also write any necessary preceding blank lines so there is no need for the user to write to the file at all except through the functions provided. For example, a user's C code might begin: #include "isf_bul.h" main() { FILE *fp; int event; int yyyy,mm,dd,hh,mi,ss,msec,strike,ndef,nsta,gap; float stime,sdobs,lat,lon,depth,smaj,smin,sdepth,mindist,maxdist; char epifix,depfix,antype,loctype; char *etype, *author, *origid; float *ellipse_maj; etype = (char *)malloc(ISF_ETYPE_LEN); author = (char *)malloc(ISF_AUTHOR_LEN); origid = (char *)malloc(ISF_ORIGID_LEN); fp = fopen("infile.isf","w"); write_data_type(fp,"BULLETIN","","IMS1.0",""); for (event=0; event