next up previous contents
Next: Executing shell programs Up: Understanding and using SU Previous: Understanding and using SU   Contents


A simple SU processing flow example

Most SU programs read from standard input and write to standard output. Therefore, one can build complex processing flows by simply connecting SU programs with UNIX pipes. Most flows will end with one of the SU plotting programs. Because typical processing flows are lengthy and involve many parameter settings, it is convenient to put the SU commands in a shell file.

Remark: All the UNIX shells, Bourne (sh), Cshell (csh), Korn (ksh), ..., include a programming language. In this document, we exclusively use the Bourne shell programming language.

Our first example is a simple shell program called Plot. The numbers in square brackets at the end of the lines in the following listing are not part of the shell program--we added them as keys to the discussion that follows the listing.

#! /bin/sh                                              [1]
# Plot:   Plot a range of cmp gathers
# Author: Jane Doe
# Usage:  Plot cdpmin cdpmax

data=$HOME/data/cmgs                                    [2]

# Plot the cmp gather.
suwind <$data key=cdp min=$1 max=$2 |                   [3]
sugain tpow=2 gpow=.5 |
suximage f2=0 d2=1 \                                    [4]
        label1="Time (sec)" label2="Trace number" \
        title="CMP Gathers $1 to $2" \
        perc=99 grid1=solid &                           [5]
Discussion of numbered lines:

  1. The symbol # is the comment symbol--anything on the remainder of the line is not executed by the UNIX shell. The combination #! is an exception to this rule: the shell uses the file name following this symbol as a path to the program that is to execute the remainder of the shell program.

  2. The author apparently intends that the shell be edited if it is necessary to change the data set--she made this easier to do by introducing the shell variable data and assigning to it the full pathname of the data file. The assigned value of this parameter is accessed as $data within the shell program. The parameter $HOME appearing as the first component of the file path name is a UNIX maintained environment variable containing the path of the user's home directory. In general, there is no need for the data to be located in the user's home directory, but the user would need ``read permission'' on the data file for the shell program to succeed.

    WARNING! Spaces are significant to the UNIX shell--it uses them to parse command lines. So despite all we've learned about making code easy to read, do not put spaces next to the = symbol. (Somewhere around 1977, one author's (Jack) first attempt to learn UNIX was derailed for several weeks by making this mistake.)

  3. The main pipeline of this shell code selects a certain set of cmp gathers with suwind, gains this subset with sugain and pipes the result into the plotting program suximage. As indicated in the Usage comment, the cmp range is specified by command line arguments. Within the shell program, these arguments are referenced as $1, $2 (i.e., first argument, second argument).

  4. The lines within the suximage command are continued by the backslash escape character.

    WARNING! The line continuation backslash must be the final character on the line--an invisible space or tab following the backslash is one of the most common and frustrating bugs in UNIX shell programming.

  5. The final & in the shell program puts the plot window into ``background'' so we can continue working in our main window. This is the X-Windows usage--the & should not be used with the analogous PostScript plotting programs (e.g., supsimage). For example, with supsimage in place of suximage, the & might be replaced by | lpr.

    The SU plotting programs are special--their self-doc doesn't show all the parameters accepted. For example, most of the parameters accepted by suximage are actually specified in the self-documentation for the generic CWP plotting program ximage. This apparent flaw in the self-documentation is actually a side effect of a key SU design decision. The SU graphics programs call on the generic plotting programs to do the actual plotting. The alternative design was to have tuned graphics programs for various seismic applications. Our design choice keeps things simple, but it implies a basic limitation in SU's graphical capabilities.

    The plotting programs are the vehicle for presenting your results. Therefore you should take the time to carefully look through the self-documentation for both the ``SU jacket'' programs (suximage, suxwigb, ...) and the generic plotting programs (ximage, xwigb, ...).


next up previous contents
Next: Executing shell programs Up: Understanding and using SU Previous: Understanding and using SU   Contents
John Stockwell 2007-04-10