Parameter handling

Parameters can be read from the command line or a parameter file, specified with par=parfile on the command line. To read a parameter, use from_par, reading command-line parameters

call from_par ("clip",c)

where clip is the parameter name, and c is a variable that get the parameter value. For example, if the command line (or a parameter file) has clip=0.75, the variable c get assigned the value of 0.75. By making use of function overloading, we can avoid specifying an additional parameter for the data type. Which format to use for reading the parameter value is determined directly from the type of variable c. For example, if c is a character string, it will be assigned the value of "0.75" (a string of four characters). A call to from_par shown above will result in an error message if the parameter was not specified by the user. You can avoid this situation by specifying a default value for c, as follows:

call from_par ("clip",c,0.8)

Now if clip= is not present in the parameter list, c will be assigned the value of 0.8. The types of the second and third parameter to from_par should match (if they don't, you will get a compile-time error). All parameter values, read by from_par, are also written to the output history file.

Another common source of parameters is the input history file. To read a parameter from the history file, use from_history, reading history file parameters

call from_history ("clip",c)

Again, the reading format is defined by the type of c (real, integer, or character), and you can specify an optional value with something like

call from_history ("clip",c,0.8)

The most important information that we normally read from a history file is the data size. We can read the size parameters in the normal manner

call from_history ("n1",nt)
call from_history ("n2",nx)
call from_history ("n3",ny)

but the sep module provides also a handy shortcut:

call from_history (nt,nx,ny)

is equivalent to three calls above. In this form of from_history, only the first parameter is mandatory. Thus, if you use

call from_history (nt,nx)

it will read only the first two dimensions from the history file. This form of from_history also reads the esize parameter and checks if it has the right value. By default, it assumes esize=4, which corresponds to real-valued data. If you work with a different type of data, just add the esize parameter to the call. For example,

call from_history (nt,nx,esize=8)

will work with complex data. Another useful parameter is compress. Sometimes it doesn't really matter for your processing what the cube dimensions are. An example is program Clip , where it is easier to treat the data as a one or two-dimensional array. If you use

call from_history (n1,n2,compress=.true.)

or just

call from_history (n1,compress=.true.)

it will read all dimensions, specified in the history file and ``compress'' them to one or two for easier processing.

Sometimes, you may need more than one input to your program. A typical example is a migration program, which reads the data cube from one file, and the velocity cube from another file. To read parameters from another history file, use from_aux, reading auxiliary file parameters

call from_aux ("velocity","d1",dz)

The syntax of from_aux is exactly the same as that of from_history except for the additional first parameter, which specifies the label of the auxiliary file. In the call above, it is assumed that the command line (or parameter file) has something like velocity=vel.H.

How can you test if an auxiliary file was actually specified? Use exist_file test parameter existence

if (exist_file ("velocity")) then

The function exist_file accepts one arguments and returns a logical value. It can be used equally well for testing parameters (other than file names), although the latter is more commonly done with default arguments.

Another parameter-access subroutine is from_old from_old, reading old history. This subroutine works exactly like from_history except that it reads not the latest value of the parameter, but the one before it. This has to do with the old-fashioned way of coding adjoint operators, which is hardly ever used in our current practice.

A more useful variation is from_either from_either, reading for either par or history. This one allows you to search for the parameter either in the history file or on the command line (with latter having a priority). The interface syntax is similar to that of from_history.

Writing a parameter to the output history file is done with to_history, writing parameters

call to_history ("n1",nt)

How do you write to another history file? Just add an optional parameter with the file tag

call to_history ("n1",nt,"velocity")