GCF for UNIX Software Suite

A User's Manual for SAM/DM24 Software under UNIX

February 26, 1999 Release 1.2.1

ISTI for GSL

http://www.isti.com

http://www.guralp.demon.co.uk

 

 

Table of Contents 

Table of Contents *

Disclaimer *

Copyright *

Introduction *

Support *

Document Summary *

Document Conventions *

Getting Started *

Installation *

Setting Permissions *

SAM SCSI Disks *

Setting up the Environment *

GCF Utilities Tutorial *

Testing the DM24 connection *

Saving GCF data to files *

Converting GCF data to seismic formats *

Transmitting GCF data to SCREAM *

Receiving GCF data from SCREAM *

Serving GCF data to multiple clients *

Extracting data from a SAM disk *

Utilities Usages *

gcfutil *

gcfconv *

gcfclient *

gcfserv *

gcfdisk *

 

Disclaimer

ISTI and GSL are not responsible for the use or misuse of this software. ISTI and GSL cannot be held liable for any losses. ISTI shall not be liable for any damages whatsoever arising out of or related to the use of any software that ISTI writes for its clients, including but not limited to: direct, indirect, special incidental, or consequential damages, and damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss.

 

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

Copyright

ISTI maintains the sole copyright of this document and the software described herein. Please contact ISTI via email at support@isti.com for permission to copy this document. Academic institutions may freely copy this document without our permission.

 

Introduction

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:

 

 

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 developers manual).

 

Support

Support for and expansion of any of the utilities described in this user manual can be obtained from Instrumental Software Technologies, Inc. (ISTI) by contacting our customer support via email: support@isti.com. ISTI is committed to providing quality programs and welcomes any feedback.

Document Summary

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

Document Conventions

There are two simple conventions used in the examples provided in this user manual. Courier font is used to specify commands typed on the command line and Italics Courier font is used to signify arguments within those commands. For example, the following lines are a command line with an option:

groucho% gcfutil t term

 

where the italics portion of the example, term is an argument that could be different depending upon the usage of the utility. The user should type any text not in bold Courier font. Note that the UNIX prompt in all the examples represents the name of the host on which the program is being run. In the example above, the host was named "groucho".

Getting Started

Installation

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% cd /usr/local

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:

 

groucho% ls F gcf

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.

Setting Permissions

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.

OS

Serial Port 1

Solaris

/dev/term/a

SunOS

/dev/ttya

Linux

/dev/ttyS0

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

 

Use the UNIX chown and chmod commands to change the ownership and permissions, respectively, of the appropriate serial ports to which you are connecting a DM24. The chown command must be run as root or super user. The following example shows how to provide the user sam with the correct permissions on a SunOS host:

groucho# chown sam /dev/ttya

groucho# chmod u+rw /dev/ttya

 

One common pitfall under the Solaris OS is that the device named in /dev is really a symbolic link to the /devices directory where the permissions must really be granted. To view the name of the true file to which permissions must be set, use the ls l option when listing the /dev/term/a file under Solaris. On a Sparc Ultra 1 we see this device as being linked to /devices/sbus@1f,0/zs@f,1100000:a (clear as mud? We thought so too).

SAM SCSI Disks

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.

OS

DISK SCSI id=1

Solaris

/dev/dsk/c0t1d0s2 *

SunOS

/dev/sd1c *

Linux

/dev/sda **

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

* For Sun Microsystems Solaris and SunOS, the disks are assumed to be attached to the first controller (c0) and have appropriate Sun disk labels. You must also allow permissions for the raw disk device (/dev/rdsk or /dev/rsd) to be read/write under Solaris and SunOS.

** Note that the listing for Linux represents the first SCSI device on the SCSI chain and if a disk with SCSI id=0 were on the chain, the device name for id=1 would be /dev/sdb.

 

When first connecting up a SCSI disk to a Sun SPARC Workstation running Solaris, you must boot the workstation using the boot r option to check for devices. We always recommend powering down your workstation if you plan on connecting the SCSI disk to your main SCSI bus. If you plan on hotswapping disks, we recommend that you purchase a second SCSI bus card with which to swap disks.

Setting up the Environment

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:

set path=(/usr/local/gcf/bin $path)

 

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:

 

setenv MANPATH $MANPATH\:/usr/local/gcf/man

GCF Utilities Tutorial

This section provides a seven-step tutorial for using the GCF for UNIX utilities for some common data acquisition tasks. The tutorial does not describe all of the capabilities of the software, but highlights what we feel are the most important ones. All of the utilities described in this tutorial are command-line driven, however we can easily customize a graphical user interface for any of the utilities. Please contact ISTI at support@isti.com if you are interested in expanding the GCF for UNIX utilities.

Testing the DM24 connection

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.

Saving GCF data to files

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

 

Converting GCF data to seismic formats

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-Dohertys AH, and Livermores 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".

Transmitting GCF data to SCREAM

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.

Receiving GCF data from SCREAM

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.

Serving GCF data to multiple clients

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

Extracting data from a SAM disk

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

 

 

Utilities Usages

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

gcfutil

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!)

gcfconv

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)

 

 

gcfclient

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

gcfserv

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!)

gcfdisk

%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