GSLConv 1.32
June 2005GSLConv is a series of DOS and Windows utilities for converting data from GCF format. Each program can input from
- GCF files produced by SAMSmart,
- GCF files produced by Scream!,
- SCSI disks from a SAM unit, or
- BDTS format files
and convert the data into SUDS, SAC and SEG-Y formats for further analysis.
Download GSLConv v1.32
The package is made up of a number of utilities, each of which can provide a specific conversion. These programs are useful in an automated acquisition system, where batch calls are made by a manager application. A front-end interface is provided, called GSLCONV.EXE, which allows the user to interactively select the conversion options.
1.Introduction
This package contains a series of utility programs that convert the 16 bit GSL Smart (BDTS) and 16 or 24 bit Guralp Compressed Format (GSF or SAM format) data to PC-SUDS, PASSCAL modified SEG-Y, and SAC. Input data may be read from an image file or SCSI device. Also included is a menu program named GSLConv that allows the user to run the conversion utilities interactively from a menu.
At the most basic level, this package allows the user to convert data files created by PC-Smart to one of the output formats for analysis. They may also be used to include ancillary information in the output data files such as; station names, coordinates, sensor type and orientation, component identifiers, and ground motion constants via a simple ASCII initialization file used by the utilities.
The user is assumed to have a working understanding of DOS, file management concepts, and seismic data processing in general. You should note that throughout this document we make a distinction between command line arguments, and command line switches. Arguments are the objects (usually files) that the program will act upon and switches modify the action of the program.
2.Installation
This package is made up of five files:
- GSLCONV.COM : The menu program.
- GSLCONV.INI : The initialization file.
- GSL2SUDS.EXE : The PC-SUDS conversion utility.
- GSL2SEGY.EXE : The SEG-Y conversion utility.
- GSL2SAC.EXE : The SAC conversion utility.
These five files should by copied to your hard drive and placed in a directory that is on your search path (i.e., a directory that is listed in the PATH statement in your AUTOEXEC.BAT file). These files should always be kept together in one directory because the conversion utilities look for the initialization file in their home directory (i.e., the directory where the executable file is located) and they all share this file.
If you use the PC-SUDS utilities, we suggest that you copy these files to the same directory that you installed them to (usually C:\PCSUDS).
3.Using GSLConv
This program presents the user with a menu of options and allows the user to specify various parameters for the conversion utilities. The program then invokes the appropriate conversion utility to perform the conversion.
To run the menu program, type:
GSLCONV
and press return. The following menu will appear:
GSLCONV - Version 1.24 Copyright (c) 1995-97, Guralp Systems, Ltd. - All Rights Reserved. F) Output format: SUDS (PC-SUDS version 1.x) I) Input source: C:\DATA\*.CMG O) Output path: C:\DATA S) Start time: (undefined) E) End time: (undefined) J) Jump seconds: (undefined) L) Length: (undefined) M) Masked channels: (from .INI file) R) Raw mode: No D) Month/day format: No G) Granularity: 7200.0 B) Big endian byte order: No Return) Process files. Spacebar) Display command line for current settings. Escape) Quit. Your choice ->
All of the lettered options are used to modify the parameters of the conversion programs. When you have set these option as required, press return to process files, spacebar to display the command line that will be used to invoke the conversion program, or escape to exit the menu and return to the DOS prompt.
When you exit the program, it saves its state to file named GSLCONV.DFL in the its home directory (that is, the directory where GSLCONV.COM is located). This means that however you leave the settings on the menu is how they will be the next time that you start the program. To return a setting to the built-in default, simply select that option and then press return at the prompt. You may restore all settings to the built-in defaults by simply deleting the GSLCONV.DFL file in the home directory.
In the following sections we will cover each option in more detail. It should be noted that each of these options correspond directly to an argument or switch on the command line. Each of the conversion programs accept the same arguments and switches.
3.1.F – Output Format
This option prompts you for the output format. Valid responses are: SUDS, SEGY, or SAC. Note that your response need be only long enough to be unique, so SU=SUDS, SE=SEGY, and SA=SAC.
This option simply tells the program which conversion utility will be invoked to process files. Note that for the PC-SUDS format, one file is created per event that contains all active channels, for SEG-Y and SAC, on file is created per channel per event. These file are given hexadecimal timestamp filenames.
3.2.I – Input Filespec
This option is used to specify the input file specification or SCSI device. The default file specification is the current working directory with *.CMG appended. You may specify any DOS legal partial or fully qualified file specification at the prompt.
As an example, suppose that PC-Smart is outputting files into C:\DATA\SMART. To process all data in that directory, you would specify: C:\DATA\SMART\*.CMG. All data files matching that wildcard specification would be sorted into chronological order and processed.
To read data from a SCSI device (disk or tape), enter “SCSI [host:]device” at the prompt. See section 4.1, Reading data from a SCSI device, below for more details.
This argument corresponds to the first argument on the command line.
3.3.O – Output Path
This option is used to specify the directory where output data files will be created. The specified path must exist.
This option corresponds to the last argument on the command line.
3.4.S – Start Time
This option is used to specify the absolute time at which output data will start being generated. If this is undefined (the default), all data will be processed.
The prompts for the time are dependent on the data/time format (see the D - Month/Day format below). The default format is day-of-year. Enter the time as YY,DDD,HH,MM,SS.SSS where, YY=year, DDD=day-of-year, HH=hour, MM=minute, and SS.SSS=second. The year and day-of-year fields default to this year and today, all others default to 0. If month/day format is in effect, enter the time as MM,DD,YY,HH,MM,SS.SSS where MM=month, and DD=day-of-month. In this case the month, day, and year default to today.
As an example, we would specify 12:15:00 today as: “,,12,15”. Note the two leading commas. These specify null year and day-of-year so they default to today. Also, we didn’t specify seconds so they default to 0.
This option corresponds to the /S switch on the command line.
3.5.E – End Time
Use this option to specify the absolute time to quit generating output data. If this value is undefined, all available data will be processed.
Please see the S – Start Time option for information about the time prompt and time formats.
This option corresponds to the /E switch on the command line.
3.6.J – Jump Seconds
Use this option to specify the start time relative to the time of the first available data in seconds. This option is the relative equivalent to the S – Start Time option.
This option corresponds to the /J switch on the command line.
3.7.L – Length
Use this option to specify the length of the output data relative to the start time in seconds. This option is the relative equivalent to the E – End Time option.
This option corresponds to the /L switch on the command line.
3.8.M – Mask Channels
Use this option to specify one or more channels that will be ignored while processing data. Enter the channel numbers (starting at 1) as comma separated numbers at the prompt. Note that this option has no meaning if the input data is in GCF format. See GSLCONV.INI below for information about excluding channels from GCF format data.
As an example, suppose you have a seven channel digitizer with a CMG-40T connected to channels 1, 2, and 3 and nothing connected to channels 4, 5, 6, and 7. You may wish to mask these dead channels so that they don’t appear in the output data files. You would simply type “4,5,6,7” at the prompt and press return.
This option corresponds to the /M switch on the command line. The /M switch expects a 16 bit field expressed as a decimal or hexadecimal number. To specify the value in hex, lead with “0x”. Each bit corresponds to a channel. Set the bit to mask, clear to include. Bit 0=channel 1, bit 1=channel 2, and so on. When you enter channel numbers through the prompt, the program displays the hexadecimal value for the /M switch in parenthesis at the end of the line.
Note that if the system which generated the current data has a section defined in GSLCONV.INI, the default mask will be read from the .INI file. You may override the Mask setting from the .INI file by specifying a mask value here or with the /M switch on the command line.
3.9.R – Raw Mode
This option affects only PC-SUDS output data. Use this option to tell the program to not include channel set structures in the output data files. There is no prompt, by pressing R you simply toggle this option between yes and no.
This option corresponds to the /R switch on the command line. See also GSLConv.INI below.
3.10.D – Month/Day Format
Use this option to switch between month/day and day-of-year notation of time values. This option affects the entry and display format used by the S – Start Time and E – End Time options. Please refer to these options above for more information.
By selecting this option you simply toggle between month/day and day-of-year format.
This option corresponds to the /D switch on the command line. On the command line, the /D switch should follow the /S or /E switches.
3.11.G – Granularity
Granularity refers to the maximum record length that the conversion programs will create. If you are processing a full day of data, the output records will be broken in chunks of this length. Use this option to specify the granularity in seconds. This option defaults to 7200 seconds (2 hours).
This option corresponds to the /G switch on the command line.
3.12.B – Big Endian Byte Order
This option only affects SEG-Y and SAC output files. PC-SUDS files, by definition, are in little endian (Intel) byte order.
Because this software was written for DOS machines, and DOS runs on Intel hardware, the output data is natively in little endian byte order. This refers to the order of bytes in multibyte data structures. Sun’s and some other computers use big endian (Motorola) byte order and therefore are not able to read data files correctly from Intel based machines. Use this option to tell the software to output big endian order files for use on Sun’s or other big endian machines.
Note that output file in big endian order are not usable under Linux on a PC, these must be in little endian order.
By selecting this option you simply toggle between big and little endian byte order.
This option corresponds to the /B switch on the command line.
4.The Conversion Utilities
Each of the conversion utilities are implemented as an individual executable program. These programs share the same command line interface. The reasoning behind this is that most seismic processing systems require automatic processing of data without user interaction. By providing the GSLConv menu program the user can interact with the software when needed but can call the conversion utilities from within batch programs for automatic processing as well.
Each of the programs provide a help screen with a brief description of the arguments and switches for the program. The see help, simply type the program name with no arguments, or type the program name followed by a question mark. The following is the help screen from GSL2SUDS:
GSL2SUDS - Version 1.24
Copyright (c) 1995-97, Guralp Systems, Ltd. - All Rights Reserved.
Usage: GSL2SUDS GSLfilespec(s) OutputPath
Switches:
/I[HostId:]DevId - Read SCSI disk at DevId on host adapter HostId.
/Stime - Start time, output data starting at absolute time. (IST)
/Etime - End time, output data up to absolute time. (All)
/Jn - Jump, start at n seconds relative to first available data. (0)
/Ln - Length, end at n seconds relative to start time. (All)
/Gn - Granularity, output data will broken into n second records. (7200)
/Mn - Channel mask, n is a 16 bit field, set bits to mask channels. (0x00)
n is decimal as 'nnn' or hex as '0xnn' or 'nnh'.
/R - Raw mode, no channels sets are added to output files. (Off)
/Dn - Date/time format, (n='j'=YY,DDD,HH:MM:SS.S), n='m'=YY,MM,DD,HH:MM:SS.S
/B - Big endian (Motorola) byte order in output file. (Little endian,Intel)
Arguments:
GSLfilespec is one or more GSL file specifications, wildcards are allowed.
Examples: 'DATA1207.CMG', 'C:\DATA\*.CMG', or 'DATA????.*'
OutputPath is taken as the last argument on the command line. This is the
directory where output files will be created.
[] = Optional, () = Default, | = Mutually exclusive.
Switches are not case sensitive and may appear anywhere in the command line.
The arguments and switches from each of the conversion programs correspond exactly to the menu items in GSLConv with the exception of the /I switch (see: Reading data from SCSI devices, below).
Please refer to the corresponding menu item section for a discussion about the use of that option. Note that switches, which always start with a slash (/), can appear anywhere within the command line with the exception of the /Dn switch, which must follow the /S or /E switches.
Each of the programs return and exit code to indicate success or failure. If no errors occurred, the program returns 0. If an error did occur, the program displays an error message and returns 1. This is useful when calling the programs from a batch program.
Below is an example of how you might call GSL2SUDS from within a batch program:
GSL2SUD C:\DATA\SMART\*.CMG C:\DATA\SUDS /M0xFF78 IF ERRORLEVEL 1 GOTO ERROR GOTO END :ERROR ECHO An error occurred in GSL2SUD PAUSE :END
4.1.Reading Data From a SCSI Device
All of the conversion programs can read input data from a SCSI device specified with the /I[Host:]Device switch. Typically a SCSI disk is attached to the first SCSI bus at device ID 3. This would be specified as /I3.
The input SCSI device may be a direct-access (disk) or sequential-access (tape) device. Your computer must have at least one functional SCSI host adapter with an ASPI manager installed. The conversion programs communicate with the SCSI bus through the ASPI interface. ASPI is a host adapter independent method of communicating with SCSI devices, that is, you should be able to use any ASPI compliant host adapter to communicate with your disk or tape drive.
This software was written and tested using Adaptec AHA 1522 (ISA), AHA-1542CF (ISA bus-master), AHA-2940 (PCI), and APA-1460 (PCMCIA) host adapters. The real mode ASPI managers included with Adaptec’s EZ-SCSI 4.0 software were used as well as the Windows95 32 bit protected mode ASPI manager. We recommend these host adapters and ASPI software for use with the conversion programs.
If you have more than one host adapter in your system, the real mode ASPI manager may need to be loaded once for each adapter. These adapters will be numbered from 0 through n, up to 4 can be installed. The conversion programs will use host adapter 0 unless otherwise instructed. To use an adapter other than zero, either specify the host on the command line, or set an environment variable named SCSI_HOST=n, where n is the number of the adapter that you wish to use.
Each of the conversion programs accept the /I switch which is used to specify the SCSI device ID number of the device you wish to read. ASPI allows up to four host adapters to be in the system at once. If you have more than one, you may specify the ID as /I[host:]device. For example, suppose your system has two host adapters: adapter 0 connected to your DOS system drive, and adapter 1 is for reading data disks, and you have a disk with SAM data on it attached at ID 3. You would specify the ID as /I1:3 meaning device ID 3 on host adapter 1. The host adapter defaults to the lowest numbered adapter (0) unless you set an environment variable named SCSI_HOST. In the above example, you could SET SCSI_HOST=1 at the DOS prompt or in your AUTOEXEC.BAT and then simply specify /I3 and have the same result.
5.GSLConv.INI
The initialization file is a simple ASCII text file that is searched for in the conversion utilities home directory, i.e., the directory where the .EXE file for the program is located.
This file is arranged in sections. Each section is marked with a “Section Header” inside square brackets (e.g., [123456789]) followed by a Format entry which specifies the format of the input data. The conversion programs will look for sections containing channel definitions for each system identifier number it finds in the input data. If a matching section is found, the program will read the channel mask, channel, and set definitions that follow the section header.
You may define as many sections as needed, only the section for the system identified in the current input data will be used at any given time. You should build a section for each system that you will see data from.
Note that comments are delimited by a semi-colon and blank lines are ignored. None of the entries are case-sensitive.
The Format= entry, which must immediately follow the section header, is used to specify the format of the input data from a given system. A system section with the Format= entry set to “BDTS” is referred as a BDTS section and one set to “SAM” is referred to as a SAM section below. The following fragment of the sample GSLCONV.INI illustrates setups for two systems, one a DM-16/6 which outputs BDTS format 16 bit data, and one SAM system which outputs 24 bit GCF or SAM data:
;---------------------------------------------------------------------- [1276782124] ; DM-16/6, 50sps, CMG3T/CMG5T, at DTA (Concord, California) Format = BDTS ; This must be the first entry in section Mask = 0xFFC0 ; Mask all channels except 1, 2, 3, 4, 5, 6 Set = 3T, Type = Vector, Channels = 1,2,3 Channel = 1, Name = DTVZ, Comp = v, Azim = 0, Incid = 0, Lat = 37.98, Lon = -122.05, Elev = 9, Sens = v, GMU = 10.0 Channel = 2, Name = DTVN, Comp = n, Azim = 0, Incid = 90, Lat = 37.98, Lon = -122.05, Elev = 9, Sens = v, GMU = 10.0 Channel = 3, Name = DTVE, Comp = e, Azim = 90, Incid = 90, Lat = 37.98, Lon = -122.05, Elev = 9, Sens = v, GMU = 10.0 Set = 5T, Type = Vector, Channels = 4,5,6 Channel = 4, Name = DTAZ, Comp = v, Azim = 0, Incid = 0, Lat = 37.98, Lon = -122.05, Elev = 9, Sens = a, GMU = 2.5 Channel = 5, Name = DTAN, Comp = n, Azim = 0, Incid = 90, Lat = 37.98, Lon = -122.05, Elev = 9, Sens = a, GMU = 2.5 Channel = 6, Name = DTAE, Comp = e, Azim = 90, Incid = 90, Lat = 37.98, Lon = -122.05, elev = 9, Sens = a, GMU = 2.5 ;---------------------------------------------------------------------- [1975237563] Format=SAM ; This must be the first entry in section ; Velocity Set=VEL, Type=Vector, Streams=DSTDZ2, DSTDN2, DSTDE2 Stream=DSTDZ2, Name=VELZ, Gain=1, Comp=v, Azim= 0, Incid= 0, Lat=38.1, Lon=-122.2, Elev=10, Sens=v, GMU=8.0 Stream=DSTDN2, Name=VELN, Gain=1, Comp=n, Azim= 0, Incid=90, Lat=38.1, Lon=-122.2, Elev=10, Sens=v, GMU=8.0 Stream=DSTDE2, Name=VELE, Gain=1, Comp=e, Azim=90, Incid=90, Lat=38.1, Lon=-122.2, Elev=10, Sens=v, GMU=8.0 ; Mass position Set=MAS, Type=Vector, Streams=DSTDM8, DSTDM9, DSTDMA Stream=DSTDM8, Name=MASZ, Gain=1, Comp=v, Azim= 0, Incid= 0, Lat=38.1, Lon=-122.2, Elev=10, Sens=d, GMU=1.0 Stream=DSTDM9, Name=MASN, Gain=1, Comp=n, Azim= 0, Incid=90, Lat=38.1, Lon=-122.2, Elev=10, Sens=d, GMU=1.0 Stream=DSTDMA, Name=MASE, Gain=1, Comp=e, Azim=90, Incid=90, Lat=38.1, Lon=-122.2, Elev=10, Sens=d, GMU=1.0 ; Recorder state-of-health Stream=S00700, Log=SOH.LOG ; Clock status Stream=DSTD00, Log=TIME.LOG
5.1.The Mask Entry
The Mask entry specifies the default channel mask to be used while processing the input data for a particular system. This number is a 16 bit field with each bit corresponding to a channel. Specify the number either in hexadecimal by leading with '0x' or in decimal. Set the bit for channel number - 1 to mask that channel (i.e., bit 0 represents channel 1, bit 15 represents channel 16). The mask entry may by overridden on the command line using the /M switch, see above.
Note that there is no Mask= entry in a SAM format section. Only the streams defined in the section will be processed. If you wish to mask out streams, simply comment the Stream= entry for those that should not be processed
5.2.The Channel or Stream Entries
In a BDTS section, Channel= entries are used, in a SAM section, Stream= entries are used.
The Channel= entries are actually a series of entries separated by commas on a single line. The Channel = n entry must be first on the line, the other entries may follow in any order. All of these entries are optional.
The currently defined BDTS entries are as follows:
Channel = n The channel number, must be first entry on the line.
Name = name The 4 or less character unique station/channel name.
Comp = c The single character component id (v, n, or e).
Sens = c The single character sensor type id (v or a).
Lat = n The station latitude in decimal degrees, north is positive.
Lon = n The station longitude in decimal degrees, east is positive.
Elev = n The station elevation in meters.
Azim = n The component azimuth.
Incid = n The component incidence, up = 0.
GMU = n The volts to ground motion unit conversion constant.
In a SAM section, the Channel= keyword is replaced with the Stream= keyword specifying the base 36 stream identifier as 6 ASCII characters instead of a channel number. These stream identifiers are displayed on the screen as the program starts to process SAM data. The rest of the entries on the line are the same as for BDTS format systems with two additional keywords:
Stream = stream A stream identifier as displayed by the program at startup.
Log = filename Name of file created in the output directory for logging of state-of-health or timing information.
Gain = n n is the gain on the stream as magnification.
5.3.The Set Entries
The Set entries are a series of comma separated entries used to define channel sets. These are used to associate single channels into a logical set, e.g., the three channels from a three-component sensor. Channel sets are supported in PC-SUDS, these entries are irrelevant when outputting SEG-Y or SAC data files. SUDSPick uses this set information to allow you to view and manipulate three-component data as such.
Set = name This is the 4 or less character unique set name.
Type = type Currently the only set type supported is 'Vector', this is a set of three mutually orthogonal components.
Channels = n,n,n This is the three channels that will make up this set in order.
The Set= entries in a SAM section will not contain a Channels= entry, instead it will contain a Streams= entry followed by the 3 stream identifiers as 6 characters, separated by commas.
Streams = s,s,s This is the three streams that will make up this set in order.
6.Glossary of SCSI Terms
SCSI terminology is littered with many acronyms. Some of these are quite obscure and can, at times, be very confusing. Below we have provided a short glossary of the more commonly used term as pertains to SCSI in the hope that we might help avoid and/or dispel some of the confusion.
ANSI The American National Standards Institute.
ASPI The Advanced SCSI Programming Interface. A software standard developed by Adaptec to allow application software to communicate with SCSI devices through a consistent set of interface routines, without regard to the particular host adapter hardware. The interface is typically implemented as an ASPI manager device driver but is sometimes implemented in firmware on the host adapter.
Byte A unit of data storage consisting of 8 binary digits (bits). A byte is capable of storing 28 or 256 possible values. Typically we think of a byte as the amount of storage needed for a single alpha numeric character.
DAT Digital Audio Tape. This is a format used with a 4mm helical scan tape cartridge for storage of digital audio data. This format incorporates two levels on error detection and correction (C1 and C2).
DDS Digital Data Storage. This is a format used to store digital data on 4mm helical scan tape cartridges. The cartridge has the same form factor as DAT, however, the data are stored on the medium in a different format. Because data storage applications are less forgiving than digital audio, a third level of error detection and correction (C3) and read–after write verification is employed. 60 meter DDS tapes hold ~1.2 GB and 90 meter DDS tapes hold ~2.0 GB. Newer drives typically employ hardware data compression to achieve capacities up to ~4.0 GB.
DDS–2 An extension to the DDS format that allows longer tapes and higher densities. DDS–2 tape are 120 meters long with a native capacity of ~4 GB. Most DDS–2 drives employ hardware data compression to achieve capacities up to ~8.0 GB.
Exabyte Exabyte is a company that builds high capacity tape drives. They pioneered the use of 8mm helical scan tape for data storage. This is the same form factor as 8mm video tape except that data grade tape is used. Exabyte also builds 4mm DDS and DDS 2 drives.
Gigabyte (GB) A unit of data storage equal to 230 or 1,073,741,824 bytes. A gigabyte is equal to 210 or 1,024 megabytes, and 220 or 1,048,576 kilobytes.
Host adapter An interface board that plugs into the backplane of a computer and attaches it to the SCSI bus.
Initiator Usually a host adapter. A SCSI device that issues commands and receives responses from targets on the SCSI bus.
Kilobyte (KB) A unit of data storage equal to 210 or 1,024 bytes.
Megabyte(MB) A unit of data storage equal to 220 or 1,048,576 bytes. A megabyte is equal to 210 or 1,024 kilobytes.
QIC Quarter Inch Cartridge. As the name implies, these cartridges use ¼” tape. The data is stored in linear tracks in a serpentine format. Common tapes are QIC 40 and QIC 80. These tapes range in capacity from 40 MB to over 1 GB with the newer types.
SCSI Small Computer Systems Interface, pronounced “scuzzy”. SCSI is an American National Standard interface used to connect disk drives, tape drives, CD ROM’s, printers, scanners, and other peripheral devices to microcomputers.
SCSI bus The physical cabling that connects SCSI devices. The bus can connect up to 8 devices (16 on wide SCSI). Typically, the bus consists of one initiator and one or more targets, although several initiators and/or targets may reside on the bus at one time. Each device occupies a unique address on the bus (0 7) called its SCSI device unit ID.
SCSI device A device such as a host adapter, disk drive, or tape drive that conforms to the SCSI interface standard and occupies an address on the SCSI bus. The device may be an initiator (e.g., the host adapter), or a target. Some devices are capable of acting as both an initiator and a target.
SCSI 2 The second revision of the SCSI standard. This standard included expanded device types, wide SCSI (16 and 32 bits), and fast SCSI (>10Mbits/sec). This standard was adopted by ANSI in 1995. Most SCSI devices available today comply with this standard.
Target A disk drive, tape drive, CD ROM, scanner, printer, or other peripheral device capable of responding to commands from initiators.
Terabyte (TB) A unit of data storage equal to 240 or 1,099,511,627,776 bytes. A terabyte is equal to 210 or 1,024 gigabytes, 220 or 1,048,576 megabytes, and 230 or 1,073,741,824 kilobytes.
Termination An electrical requirement of the SCSI bus that each end of the bus must have a series of termination resistors installed. Most devices have terminators built into them that are enabled or disabled with switches, jumpers, or through software. Care must be taken so that only the devices at each physical end of the bus have termination installed or enabled in order for the bus function properly.