February 26, 1999 Release 1.2.1

All liability rests with the user of this software. If you are not comfortable with this, then do not use this software.

The GCF for UNIX software suite provides the owner of the Guralp DM24 with the necessary tools to acquire and convert Guralp Compressed Format (GCF) data under a number of UNIX operating systems (Linux, SunOS 4.X, Solaris 2.X, & Solaris 7). The software suite also provides the capability to transmit GCF data to a SCREAM server running under Windows or to other UNIX servers using TCP/IP networking. GCF for UNIX provides discrete utilities for performing specific data acquisition and conversion tasks. These utilities and a brief description of what they do are listed below:

• gcfutil – obtain GCF data via a serial port and write to UNIX files, or view headers of GCF data in files.

• gcfconv – convert GCF data into AH, PASSCAL-SEGY, or SAC formats.
• gcfdisk/xdisk – extract GCF data from SAM SCSI disks into UNIX files.
• gcfserv – read GCF data from a serial port and transmit it to SCREAM or other UNIX clients using TCP/IP networking.
• gcfclient – obtain GCF data from SCREAM or other UNIX servers via TCP/IP networking.

In addition, GCF for UNIX provides a C language Application Programming Interface (API) for developers to interface their software with the Guralp DM24 (the C API is not documented in this manual but in a forthcoming developer’s manual).

This document is a user manual containing HOWTO information about the GCF for UNIX software. While the software suite comes with on-line UNIX manual pages, this document is intended to provide more of a general overview with examples of how the software can be used and some of its capabilities. The first section describes how to install the software and set up your UNIX environment to use the software. The second section provides a quick tutorial on using the software. And the final section describes the utilities in more detail

groucho% gcfutil –t term

The GCF for UNIX software suite is distributed as a UNIX tar archive file that has been compressed using the GNU gzip utility. To unbundle the tar, you must have enough disk space to accommodate the uncompressed tar, which for the 1.2.1 release is about 600 kilobytes. Find an appropriate directory to install the software; we recommend /usr/local for Linux, or /opt for Suns. We use /usr/local in the examples below. Make sure you have write permission in the appropriate directory and untar the package. The package comes named according to the operating system (OS) and host architecture your site is using. In the following install example,

groucho% gzip –cd gcf_linux_1.2.1.tar.gz | tar xvf –

the linux portion of the distribution name indicates a Linux distribution. Alternatively, the OS/platform listing could have been either sunos4.1.X, solaris2.X_intel, or solaris2.X_sparc. The version number, in this case 1.2.1, comes after the OS name.

Listing the distribution should provide you with the following output:

COPYRIGHT INSTALL README VERSION

bin/ include/ lib/ man/

Where COPYRIGHT, INSTALL, README, and VERSION are ASCII text files for users to read and learn more about the installation. bin, include, lib, and man are directories that contain executables, include files, the library, and manuals respectively.

In order to access a DM24 via a serial port, the user executing the GCF for UNIX utilities must have read and write permissions to the serial port. Under UNIX, the serial port is a file in the /dev directory. There is a different convention for naming the serial device file for each of the various brands of UNIX supported by this software suite. The table below highlights the default serial port used by the GCF utilities.

Table 1. Listing of default serial port names for various UNIX OS

groucho# chown sam /dev/ttya

groucho# chmod u+rw /dev/ttya

If you are connecting a SAM SCSI disk to a UNIX workstation, you must similarly enable the read/write permissions for the disk device that will be accessed. Just as names of serial ports are different under the different UNIX OS’ supported, so are the disk device names.

Table 2. Listing of default disk device names for SCSI disk id = 1.

We recommend setting two shell variables to point to the executables and manuals to make using the software easier. The shell variable path should be set to point to the executable directory. For C shell users, edit the .cshrc file and add the following line:

Likewise, to view manual pages, the path to the gcf/man directory must be added to the MANPATH environmental variable. If the MANPATH is already set to something, use the following line to add in the location of the GCF manual pages:

Using a standard serial cable (refer to the DM24 manual for a wiring diagram), connect the DM24 to the UNIX serial port. Make sure you have set the appropriate permissions on the serial port or you will be denied read/write access. It is assumed that you have configured the parameters of the DM24 using SCREAM, or via a serial communications tool (this version of GCF for UNIX does not support configuration of the DM24). The gcfutil program provides a monitor to test your DM24 connection without actually doing anything with the data. In our example below, we use a baud rate of 9600 and a Solaris serial port /dev/term/a:

groucho% gcfutil –t /dev/term/a –b 9600

This resulted in the following output:

Blk#: 000 SyID: DTA005 StrmID: 511100 NS: 604 SPS: 0 CFmt: 8 1999:066:23:18:44

Blk#: 001 SyID: DTA005 StrmID: 5111Z2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:36

Blk#: 002 SyID: DTA005 StrmID: 5111N2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:36

Blk#: 003 SyID: DTA005 StrmID: 5111E2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:36

Blk#: 004 SyID: DTA005 StrmID: 5111Z2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:46

Blk#: 005 SyID: DTA005 StrmID: 5111N2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:46

Blk#: 006 SyID: DTA005 StrmID: 5111E2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:46

Blk#: 007 SyID: DTA005 StrmID: 5111Z2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:56

Blk#: 008 SyID: DTA005 StrmID: 5111N2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:56

Blk#: 009 SyID: DTA005 StrmID: 5111E2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:18:56

Blk#: 010 SyID: DTA005 StrmID: 5111Z2 NS: 1000 SPS: 100 CFmt: 8 1999:066:23:19:06

^C *

* ^C was used to stop the process running

Note that the values will depend upon how your DM24 is configured. The first number represents the block number (Blk#) of the data which should be contiguous and should rollover at 255. The next values represent system id, stream id, number of samples, sample rate, and compression format (See the DM24 manual for details of each item).

To stop gcfutil from running, you must kill the program using the ^C (Control C) keystroke, or using the UNIX kill command.

To view the status messages (state of health) from the DM24, use the –S option:

groucho% gcfutil –t /dev/term/a –b 9600 -S

Some examples of status messages are provided below:

SyID: DTDEM3 StrmID: DEM3N2 NS: 500 SPS: 100 CFmt: 16 1998:015:21:01:07

SyID: DTDEM3 StrmID: DEM300 NS: 664 SPS: 0 CFmt: 8 1998:015:21:01:14

Status BLOCK

1998 1 15 19:43:03 Auto 3-D SV# 18

Strengths : #18 = 4 #31 = 0 #3 = 2 #19 = 0 #21 = 0 #16 = 0

1998 1 15 19:44:09 2 SV's Control OFF 10 1998 1 15 19:43:22

1998 1 15 19:44:09 Auto 3-D SV# 18 3

Strengths : #18 = 4 #31 = 0 #3 = 4 #19 = 0 #7 = 0 #23 = 0

1998 1 15 19:47:12 1 SV's Control OFF 10 1998 1 15 19:46:25

1998 1 15 19:47:12 Auto 3-D SV# 18

Strengths : #18 = 5 #31 = 0 #3 = 2 #19 = 0 #10 = 0 #1 = 0

1998 1 15 21:00:56 0 SV's Control OFF 10 1998 1 15 21:00:10

1998 1 15 21:00:56 Auto 3-D SV#

Strengths : #18 = 2 #31 = 0 #3 = -1 #19 = 0 #2 = 0 #5 = 0

1998 1 15 21:02:01 1 SV's Control OFF 10 1998 1 15 21:01:14

SyID: DTDEM3 StrmID: DEM3Z2 NS: 500 SPS: 100 CFmt: 16 1998:015:21:01:09

Refer to the appropriate DM24 documentation for details about how to decipher the status messages.

Now that you have tested the DM24 connection and know that it is functioning, the next step will be to store the GCF data to the UNIX file system. The gcfutil program must be directed to save GCF data to a file using the –D option as follows:

groucho% gcfutil –D /home/groucho/gcf.data

The example above will save all GCF data from the default serial port to the file named by the –D option. Note that in this example we did not specify the –t and –b options. The simple reason is that if you do not include them, the default terminal (/dev/term/a under Solaris) and baud rate (9600) are used automatically. An alternative to get data out of a DM24 and into a file is to use the –o option to send data to standard output (>) as follows:

groucho% gcfutil –o > /home/groucho/gcf.data

All of these invocations will run forever, or until the machine is rebooted. To stop the program use the ^C keystroke.

To parse a GCF data file to view the headers and status messages, you can read the file via standard input with gcfutil using the –d option:

groucho% gcfutil –d –S < /home/groucho/gcf.data

The GCF for UNIX utility that converts GCF data files or data coming directly from a serial port, is gcfconv. This utility stores the data in one of three common seismic formats, PASSCAL-SEGY, Lamont-Doherty’s AH, and Livermore’s SAC. By default the program will output PASSCAL-SEGY. To process GCF data using gcfconv connected to a serial port, simply use the following command line:

groucho% gcfconv –t /dev/term/a –b 9600 –l 1800

This will create 1800 second long PASSCAL-SEGY files in directories below the current working directory. The files will be stored in directories named GYYYY.DDD where YYYY is the year of the data and DDD is the day of year of the data. The files will be named GCF.YYYY:DDD:HH:MM:SS.sssss.ff where YYYY is the year, DDD is the day, HH is the hour, MM is the minute, SS is the rounded second, sssss is the stream name, and ff is the format (ah, segy, or sac). In addition to the data files a log file is created in the working directory that reports how the program was working and any status messages that were observed in the data. The logfile is named GCF.YYYY:DDD:HH:MM.log where the time in this case is when the program was started.

To read the data coming from a file of GCF data, the command line would be the following:

groucho% gcfconv –F gcf.data –l 1800

If your favorite seismic format is AH, then you would use the following command line:

groucho% gcfconv –F gcf.data –l 1800 –f ah

To get SAC formatted data, simply replace the ah in the above command line with the keyword "sac".

If you are operating in a heterogeneous environment where your data processing software is located under Windows 95/98/NT and your data collection is performed on a more robust UNIX workstation, you will need some way to transfer the data. While you could use SAMBA, PC-NFS, or FTP just to name a few, these utilities require a file or files to be transferred using some scripting. An alternative to the aforementioned utilities is to transmit the data over a TCP/IP network to a SCREAM client using the GCF for UNIX utility gcfserv. For example, if your Windows95 host has a dedicated IP address, say 172.16.11.2, the command line to transmit data from the serial port to that host would be:

groucho% gcfserv –t /dev/term/b –b 9600 –w –H 172.16.11.2

where the –w indicates that the client the server will be transmitting to is a SCREAM program and the –H is used to specify the IP address. On the SCREAM client you must set up the program to allow network reception of data (refer to the SCREAM manual for how to do this). If the /etc/hosts table or other DNS service is available on your UNIX computer, gcfserv will understand host names with the –H option. For example, in this command line:

groucho% gcfserv –t /dev/term/b –b 9600 –w –H harpo

our Windows95 host from the previous example is named harpo. Names are always easier to remember than IP addresses and thus gcfserv, and all of the GCF for UNIX utilities that transmit data over a network, understand both names and IP addresses.

Since SCREAM has the ability to receive data via broadcast, if the clients are located on the same local network, gcfserv also has the ability to broadcast data. In this example:

groucho% gcfserv –t /dev/term/b –b 9600 –w –B –H 172.16.11.255

where 172.16.11.255 is a broadcast address for the network.

The GCF for UNIX network transmission/reception programs all use the default SCREAM port number 1567 to receive and transmit data when using the –w option. This is, however, configurable to be any port number using the –p option.

If our heterogeneous network from the previous example is reversed and we have Windows boxes collecting the data via SCREAM, but our data archiving/processing software is sitting on a robust UNIX workstation, we will need to transmit the data over to the UNIX side. SCREAM has the capability to transmit the data to specific hosts or to all hosts (via a broadcast). To receive this data we have a GCF for UNIX client program, called--you guessed it--gcfclient. In the following example it is assumed that the SCREAM program has been configured to either broadcast data onto a local area network or unicast it to the UNIX host running the data archiving software. On the UNIX workstation the command line to receive data from SCREAM is:

groucho% gcfclient –w –D /home/groucho/gcf.data

The –D option has the same meaning as when used with gcfutil. In this example, it stores the GCF data received from the SCREAM server in a file named /home/groucho/gcf.data.

In our next example let us say your network is homogeneously UNIX workstations and you collect the data with one workstation, say a Linux box with hostname harpo, and archive the data with another workstation, say a Solaris SPARCstation with hostname chico. In this situation, we call harpo the server and chico a client. On harpo we start the GCF for UNIX server:

harpo% gcfserv –t /dev/term/a –b 9600

and on the client chico we collect the data into a single data file:

chico% gcfclient –H harpo –D /home/chico/gcf.data

In this example we would have had to start the server on harpo before the client was started. We recommend having a shell script that monitors the gcfserv process and restarts it as necessary, including when the host reboots. We also recommend having a shell script wrapper around gcfclient to restart it should the server’s host die. Should the data flow be interupted, and the gcfclient program does not receive a response from the server after a specified timeout (default is 30 seconds), the client exits. At startup, gcfclient will try to connect to a server for about 5 seconds; if the server is not present then the client will exit and notify the user that the server was not available.

In our preceding example we only had one client, but there could be any number of clients receiving data from the server on harpo. If for instance you wish to run a trace viewing program or a triggering algorithm on another workstation, it is easy enough to pipe the data coming out of gcfclient through another processing program. In the example below, the host named zeppo is also receiving data but processing it simply as a status monitor to see that data are flowing off of harpo:

zeppo% gcfclient –v –H harpo

where –v indicates verbose mode.

Connect up a SAM SCSI disk to your workstation as specified in the "Getting Started" section. To view the header of a disk, simply type:

groucho% gcfdisk –H /dev/rdsk/c1t5d0s2

will output the following:

Disk device: /dev/sdc System_id=KEETCH Contains 6 streams

Disk size=8921106(sects) Data: Start=18(sect) Free=498(sect) 0.3(Mbytes)

Strm StrmID Start End SPS: From: To:

---- ------ ----- --- ---- ----- ---

01 D248E0 18 416 200 1999:060:16:52 1999:060:16:57

02 D248Z0 34 480 200 1999:060:16:52 1999:060:16:58

03 D248N0 50 496 200 1999:060:16:52 1999:060:16:58

04 D248Z2 178 432 50 1999:060:16:52 1999:060:16:57

05 D248N2 194 448 50 1999:060:16:52 1999:060:16:57

06 D248E2 210 464 50 1999:060:16:52 1999:060:16:57

where the final argument to gcfdisk is the disk device being accessed, in this case on a Solaris workstation’s disk named /dev/rdsk/c1t5d0s2.

To extract all data to one file, enter:

groucho% gcfdisk /dev/rdsk/c1t5d0s2 > all_disk_file

where all_disk_file is the name of the new file created, containing all data from the field instrument. To extract all data to multiple files, enter:

groucho% gcfdisk –B /dev/rdsk/c1t5d0s2

Here, -B (the breakout option) will split each data stream out to a separate UNIX file. The following convention is used to name these files:

sysid.strmid.YYYY:JJJ:HH:MM.gcfdata

Where sysid is the identifier of the system that wrote the data, strmid is the data stream identifier, and the start time is that of the first packet.

To extract specific streams, the user must specify the desired data streams to be extracted off the disk. The syntax for this command is gcfdisk –sstream[,stream]:

groucho% gcfdisk –s DEM3Z2,DEM3N2 /dev/rdsk/c1t5d0s2

Here, the streams extracted are DEM3Z2 and DEM3N2. Note that all streams are indicated with uppercase lettering, and where there are multiple streams these are separated by commas but no spaces.

To extract specific stream(s) & times, add the –T start and –l len options to with the above example:

groucho% gcfdisk –sDEM3Z2 –T1999:066:04:52 –l60\ /dev/rdsk/c1t5d0s2

–T start specifies the start time of an event of interest, and is used in conjunction with the –l option to calculate an end time. A length must be specified with the –l option; if the –l option is not used, a default length of 1000 seconds will be assigned to this stream (for this extraction)

Finally, to extract data and convert directly to PASSCAL SEGY files, use the gcfconv

utility:

groucho% gcfdisk –s DEM3Z2 /dev/dsk/c1t5d0s2 | gcfconv –t –

Although –t specifies a terminal under standard gcfconv usage, the – indicates that the GCF data are coming from standard input.

Usages are the responses issued by all of the programs when executed using the –h option.

groucho% gcfutil -h

gcfutil: Version 99.066

gcfutil: [-q][-o][-r][-S][-d] [-b baud] [-t terminal] [-D file]

[-c | -s] [-wB][-P port][-H host]

-b baud 1200,2400,9600,19200,38400 are valid baud rates

-t terminal - serial input device

-S print status blocks to stdout

-d pass GCF disk packets in via stdin

-o pass GCF disk packets to stdout

-D filename - pass serial data to file specified

-u uncompressed GCF C struct output [default is GCF disk packets]

--------client and server options--------

-q quiet mode (echo nothing!) default is verbose

-c client-mode (receive GCF packets from a server)

-C secs - GCF-UNIX client timeout in seconds

-s server-mode (transmit GCF packets to client(s)

-w act as a SCREAM (server or client) (use with -c or -w)

[-c or -s] by default are GCF-UNIX

client or servers

-H hostname or broadcast address

-P port-number (1567 is default)

-B force broadcasting (SCREAM server only!)

groucho% gcfconv -h

gcfconv: Version 99.067

gcfconv: -t port [-b baud] [-l file_len]

[-d directory] [-s station]

[-P packet_len] [-L logdir] [-x][-v][-f format] [-S]

-t port = serial device (default: /dev/ttyS0)

Option Summary:

-l file_len = length of output files in seconds. (default: 15)

-f (ah|sac) = format to use instead of segy.

-b baud = set serial baud rate (default: .)

-d directory = top dir in which to place files. (default: .)

-s station = station name to use for files (<= 5 chars only).

-L logdir = directory for logfile to be written

-v = verbose mode, tell all to stdout.

-S data are being fed via stdin

-F filename = read data from a unix file.

filename of '-' means read from the stdin (same as -S)

groucho% gcfclient -h

gcfclient: Version 99.066

gcfclient: [-p][-w][-C secs][-q][-H host][-P port-number][-o|-D filename]

-w act as a SCREAM client (default is GCF-UNIX)

-p ping a GCF-UNIX server and exit

-C secs - GCF-UNIX client timeout in seconds

-P port-number (1567 is default)

-H server hostname

-o pass GCF disk packets to stdout

-D filename - pass serial data to file specified

-q quiet mode (echo nothing!) default is verbose

groucho% gcfserv -h

gcfserv: Version 99.066

gcfserv: [-b baud][-t terminal][-w][-vl][-B][-H host][-P port-number][-a auth]

-b baud 1200,2400,9600,19200,38400 are valid baud rates

-t terminal - serial input device

-v Verbose mode (default is quiet)

-w act as a SCREAM server (default is GCF-UNIX)

-P port-number (1567 is default)

-H hostname or broadcast address

-B force broadcasting (SCREAM server only!)

-l syslog diag msgs (GCF-UNIX server only!)

-a authfile - authorize clients (GCF-UNIX server only!)

%groucho gcfdisk -h

gcfdisk: Version 99.066

gcfdisk: [-cf][-v][-B][-H][-h][-s stream,stream...] [-t time,time] [[-T time] -l length]

-c - clear disk, but prompt user first, then exit

-f - forcefully clear disk, then exit

-v - verbose mode echos info to stderr

-B - Breakout all streams to seperate UNIX files

-H - Display only disk header

-s stream,stream,... - Obtain GCF packets for

specified streams only. Separate streams with commas

-t time,time - Obtain GCF packets within time range

times are of the format YY:JJJ:HH:MM[:SS]

where seconds are optional

-T time - Obtain GCF packets closest to time

-l len - length in seconds for obtaining packets

in conjunction with option -T

> file - Send entire disk to stdout