THE HISTORY FILE

The 15 parameters above, and many more parameters defined by authors of cube-processing programs, are part of the ``history file" (which is ASCI, so we can print it). A great many cube-processing programs are simple filters--i.e., one cube goes in and one cube comes out--and that is the case I will describe in detail here. For other cases, such as where two go in and one comes out, or none go in and one comes out (synthetic data), or one goes in and none come out (plotting program), I refer you to the manual pages, particularly to subroutine names beginning with aux (as in ``auxiliary").

Let us dissect an example of a simple cube-processing program and its use. Suppose we have a seismogram in a data cube and we want only the first 500 points on it, i.e., the first 500 points on the 1-axis. A utility cube filter named Window will do the job. Our command line looks like

< mygiven.H Window n1=500 > myshort.H

On this command line, mygiven.H is the name of the history file of the data we are given, and myshort.H is the history file we will create. The moment Window, or any other seplib program, begins, it copies mygiven.H to myshort.H; from then on, information can only be appended to myshort.H. When Window learns that we want the 1-axis on our output cube to be 500, it does call putch('n1','i',500), which appends n1=500 to myshort.H. But before this, some other things happen. First, seplib's internals will get our log-in name, the date, the name of the computer we are using, and Window's name (which is Window), and append these to myshort.H. The internals will scan mygiven.H for in=somewhere to find the input data cube itself, and will then figure out where we want to keep the output cube. Seplib will guess that someone named professor wants to keep his data cube at some place like /scr/professor/_Window.H@. You should read the manual page for datapath to see how you can set up the default location for your datasets. The reason datapath exists is to facilitate isolating data from text, which is usually helpful for archiving.

When a cube-processing filter wonders what the value is of n1 for the cube coming in, it makes a subroutine call like call hetch("n1","i",n1). The value returned for n1 will be the last value of n1 found on the history file. Window also needs to find a different n1, the one we put on the command line. For this it will invoke something like call getch("n1","i",n1out). Then, so the next user will know how big the output cube is, it will call putch("n1","i",n1out). For more details, see the manual pages.

If we want to take input parameters from a file instead of from the command line, we type something like <in.H Window par=myparfile.p > out.H. The .p is my naming convention and is wholly optional, as is the .H notation for a history file.

Sepcube programs are self-documenting. When you type the name of the program with no input cube and no command-line arguments, you should see the self-documentation (which comes from the initial comment lines in the program).

SEP software supports ``pipelining.'' For example, we can slice a plane out of a data cube, make a contour plot, and display the plot, all with the command line

<in.H Window n3=1 | Contour | Tube

where, as in UNIX pipes, the ``|'' denotes the passage of information from one program to the next. Pipelining is a convenience for the user because it saves defining a location for necessary intermediate files. The history files do flow down UNIX pipes. You may not have noticed that some location had to be assigned to the data at the intermediate stages, and when you typed the pipeline above, you were spared that clutter. To write seplib programs that allow pipelining, you need to read the manual page on hclose() to keep the history file from intermingling with the data cube itself.

A sample history file follows: this was an old one, so I removed a few anachronisms manually.

# Texaco Subduction Trench: read from tape by Bill Harlan
n1=1900 n2=2274
o1=2.4 it0=600 d1=.004 d2=50.  in=/d5/alaska

Window:   bill   Wed Apr 13 14:27:57 1983
                input() :    in ="/d5/alaska"
                output() : sets next in="/q2/data/Dalw"
                Input:  float   Fortran (1900,2274,1)
                Output: float   Fortran (512,128,1)
         n1=512 n2=128 n3=1

Swab:   root@mazama   Mon Feb 17 03:23:08 1986
#       input history file /r3/q2/data/Halw
                input() :    in ="/q2/data/Dalw"
                output() : sets next in="/q2/data/Dalw_002870_Rcp"
                #ibs=8192 #obs=8192

Rcp: paul Mon Feb 17 03:23:15 PST 1986
        Copying from mazama:/r3/q2/data/Halw
        to hanauma:/q2/data/Halw
        in="/q2/data/Dalw"

Cp:   jon@hanauma   Wed Apr  3 23:18:13 1991
                input() :    in ="/q2/data/Dalw"
                output() : sets next in="/scr/jon/_junk.H@"