THE HISTORY FILE

The 15 parameters above, and many more parameters defined by authors of cube processing programs lie on the history file (which is ASCI so you 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'll 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 subroutine names begining 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. Your 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 you are given, and myshort.H is the history file you will create. The moment the Window program, or any other seplib program, begins, it copies mygiven.H to myshort.H and from then on, information can only be appended to myshort.H. When Window learns that you want the the 1-axis on your 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 your name, the date, the name of the computer you are using, and Window's name (which is Window), and append those to myshort.H. Then, seplib's internals will scan mygiven.H for in=somewhere to find the input data cube itself, and then it will figure out where you want to keep the output cube. It 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 data sets. A lot of experience and skill went into designing datapath to save you from many aggravating real-world difficulties.

When a cube processing filter wonders what is the value 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. The window program also needs to find a different n1, the one you 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 you want to take input parameters from a file instead of from the command line, you can use something like, ``<in.H Window par=myparfile.p > out.H''. The ``.p'' is my naming convention and it 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).

Finally, I'll mention pipelineing. We can slice a plane out of a data cube, make a contour plot, and display the plot, all on one command line with this:

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

where like UNIX pipes, the ``|'' denotes the passage of information from one program to the next. The history files do flow down UNIX pipes. You may not have noticed that someplace had to be assigned to the data at the intermediate stages, and when you typed the line 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@"