SAC Command Reference Manual
Using SAC Commands: A - Z Functional Subprocesses: SPE SSS SAC/IRIS

READ

SUMMARY

Reads data from on disk into memory.

SYNTAX

READ [options] [filelist]

where options is one or more of the following:

MORE
TRUST ON|OFF
COMMIT|ROLLBACK|RECALLTRACE
DIR CURRENT|name
XDR
ALPHA
SEGY

ALL options must preceed any element in the filelist.

INPUT

MORE:

Place the new data files in memory AFTER the old ones. If this option is omitted, the new data files REPLACE the old ones.
Note:

if the MORE option is not specified, the COMMIT, ROLLBACK, and RECALLTRACE options have no effect.
TRUST ON|OFF:

This option is used to resolve an ambiguity in converting files from SAC to CSS format. When converting data, matching event IDs could mean the files have identical event information, or they could be an artifact of the merging of these two very different formats. When TRUST is ON, SAC is more likely to accept matching event IDs as identical event information than when TRUST is OFF, depending on the history of READ commands associated with the current data files in memory.
COMMIT:

If the MORE option is specified, the COMMIT option commits headers and waveforms in SAC memory -- removing any previous versions of headers or waveforms from RAM -- prior to reading more files. COMMIT is the default.
ROLLBACK:

If the MORE option is specified, the ROLLBACK option reverts to the last committed version of the header and waveform before reading more files.
RECALLTRACE:

If the MORE option is specified, the RECALLTRACE option:

  • reverts to the last committed version of the waveform,
  • reverts to the last committed version of those header variables closely linked to the waveform,
  • commits those header variables which are loosely linked to the waveform. (use HELP RECALLTRACE for a list of header variables which are committed, and which are rolled back.)
DIR CURRENT:

Read all simple filenames (with or without wildcards) from the current directory. This is the directory from which you started SAC.
DIR name:

Read all simple filenames (with or without wildcards) from the directory called name. This may be a relative or absolute directory name.
XDR:

The input files are in XDR format. This format is used for moving binary data files to/from a different architecture, such as a pc running LINUX.
ALPHA:

The input files are SAC formatted alphanumeric (ascii) files. the ALPHA option is incompatible with the XDR option.
SEGY:

Read file formatted according to the IRIS/PASSCAL form of the SEGY format. This format allows one waveform per file.
filelist:

file | wild .
file:

A legal filename. This may be a simple filename or a pathname. The pathname can be a relative or absolute one. See the DESCRIPTION and EXAMPLES sections below for more details.
wild:

A wildcard laden token that expands to a list of filenames. See the DESCRIPTION and EXAMPLES sections below and the WILD command for more details.

DEFAULT VALUES

READ COMMIT DIR CURRENT

DESCRIPTION

All commands in SAC work on the data that is currently in memory. This data in memory is analogous to the temporary or working files used by a text editor. The READ command transfers data from one or more disk files into memory. The default is to read all of the data from each disk file.

AUTO-DETECTION: SAC will attempt to determine the types of files for reading. Known file types include SAC binary, SAC alphanumeric, SEG-Y, and miniSEED. If the type of file is specifiled using ALPHA or SEGY it will be assumed all files are of that type.

miniSEED: All data within a miniSEED file will be read into memory.

The CUT command can be used to specify that only a portion of each disk file be read. SAC files produced in or after the year 2000 are presumed to have a four digit value for the year. Files with two digit year values will be assumed to be in the twentieth century, and will be incremented by 1900. Normally all data in memory prior to the execution of another READ command is lost. The new data replaces the old data.

If the keyword MORE is the second symbol in the command, the new data is placed in memory after the old data. The data file list becomes the concatenation of the old file list and the new file list. There are three cases where the MORE option may be useful:

  1. The filelist is too long to be typed on one line.
  2. A name was misspelled in a long filelist.
  3. A file is read, some analysis performed, and a comparison with the original is desired.

Examples of each of these cases are given below. The filenames may be simple filenames in the current directory or they may be absolute or relative pathnames pointing to other directories on your system. Examples of an absolute pathname is:

/disk/dir/subdir/file

Examples of a relative pathnames is:

./subdir/file
../subdir2/file

In the above examples "disk" is the name of a physical disk partition, "dir" is the name of a top level directory, "subdir" is a subdirectory of that partition, and "file" is a file in that subdirectory. In general there is no limit on the nesting of subdirectories. The first relative-pathway example assumes the user is in subdir.

Filenames may also contain wild-card characters. You can use them match a single character, to match zero or more characters, and to form groupings of characters. Some examples are given below. See the WILD command for more examples and a complete explanation of all the wildcarding options.

* Important * SAC has two data buffers; this is what allows SAC to provide the COMMIT, ROLLBACK and RECALLTRACE commands. One data buffer stores the header information in SAC format, and the second stores headers in CSS 3.0 format. This CSS 3.0 data buffer allows seamless consistency with CSS 3.0 in READCSS and WRITECSS; it also allows direct access to the CSS 3.0 formatted Oracle database.

In CSS (a relational format), it is important to maintain consistency with the event IDs (evid, or nevid in SAC). In SAC format (a very flat format), such consistency is not as important, and in some cases, it is lost. Anytime data is loaded into SAC, it is stored in both buffers. When transfering data from SAC to CSS data buffers, there is a potential ambiguity in handling event information. If matching evids are found, it could be that the two files have identical event information, or it could be that the match is an artifact of the merge of these two different data formats within SAC.

Two pieces of information are involved in resolving this ambiguity, one is the history of data loaded into SAC memory, and the other is the confidence the user sets with the TRUST ON|OFF option on the command line of most Read commands and ADDSTACK. It is expected that the user will have some idea if the data files are consistent, if they share event information, etc. The history of data loaded into SAC memory begins when data is loaded into memory without the MORE option, and ends the next time data is loaded into memory without the MORE option. Any time in between that data is loaded into memory with the MORE option, it becomes part of the existing history.

EXAMPLES

In the following examples is it assummed that the following SAC data files are in your current disk directory: F01, F02, F03, and G03. In these examples, the UNIX wildcard characters (e.g., "?" matches any single character and "*" matches zero or more characters) are used. See the WILD command for more information on how to use wildcards. To read the first three files:

SAC> READ F01 F02 F03

The following command produces the same result using the wildcard operator:

SAC> READ F*

This command also produces the same result by using the concatenation operator:

SAC> READ F0[1,2,3]

To read the second, third, and fourth files:

SAC> R F02 ?03

The following examples show the use of the MORE option:

SAC> R F03 G03

files F03 and G03 are in memory:

SAC> R F01 F02

files F01 and F02 are in memory:

SAC> R MORE F03 G03

files F01, F02, F03, and G03 are in memory

This example uses the MORE option when a filename was misspelled:

SAC> R F01 G02 F03
   WARNING: File does not exist: G02
   Will read the remainder of the data files.

files F01 and F03 are in memory:

SAC> R MORE F02

files F01, F03, and F02 are now in memory:

note the order of the files in this case.

If you wanted to apply a highpass filter to a data file and then graphically compare the results to the original:

SAC> READ F01
SAC> HIGHPASS CORNER 1.3 NPOLES 6
SAC> READ MORE F01
SAC> PLOT1

plot shows filtered and original data

Now assume you were in the directory "/me/data" when you started up SAC and that you wanted to work with the data files in the subdirectories "event1" and "event2":

SAC> READ DIR EVENT1 F01 F02

files in directory /me/data/event1 are read:

SAC> READ F03 G03

files in same directory are read:

SAC> READ DIR EVENT2 *

all files in /me/data/event2 are read:

SAC> READ DIR CURRENT F03 G03

files in directory /me/data are read.

Note For examples of the differing behavior between the COMMIT, ROLLBACK, RECALLTRACE options, see the commands of the same names.

ERROR MESSAGES

  • 1301: No data files read in.
    • haven't given a list of files to read.
    • none of the files in the list could be read.
  • 1320: Available memory too small to read file
  • 1314: Data file list can't begin with a number.
  • 1315: Maximum number of files in data file list is
  • 6002: No more data-sets available.

WARNING MESSAGES

  • 0101: opening file
  • 0108: File does not exist:
  • 0114: reading file
    • Normally when SAC encounters one of these errors it skips that file and reads the remainder. These errors can be made to be fatal using the READERR command.

HEADER CHANGES

E, DEPMIN, DEPMAX, DEPMEN, B if cut option is on.

LATEST REVISION

Version 102.0
Using SAC Commands: A - Z Functional Subprocesses: SPE SSS SAC/IRIS