Creating A Simple Script

  1. Introduction
  2. A Basic Script
  3. Creating A Background Process With A Script
  4. Script Producing A Display With A Defined Window Title
  5. Display With A Defined Window Placement
  6. Using -name To Load Resources From Wxp.res
  7. Further Comments

  8. Overall Tutorials Table Of Contents

1. Introduction

In this tutorial, we construct a simple shell script that contains a WXP command to produce a data display. We will write the script in the C-Shell scripting language. A good reference for the C-Shell is:

The Unix C Shell Field Guide
Gail Anderson, Paul Anderson (1986)
Prentice Hall, Englewood Cliffs, NJ 07632
ISBN 0-13-937468-X
Before starting this tutorial, there are a few things to know. You will need to know where the data is stored at your site, and how to set your UDRESPATH environment variable. It would help to be familiar with the resources that are held in the site Wxp.res file, and in how to use the WXP Interactive Shell. Knowledge of using WXP programs from the command line will be required. These points are covered in previous tutorials:

If the WXP software resides on a remote machine, you should set your DISPLAY environment variable to your current terminal.

Familiarity with C-Shell commands is also required. The use of an editor (vi or emacs) will be required to edit scripts. If the WXP software resides on a remote machine, you should set your DISPLAY environment variable to your current terminal.

To get the most out of this tutorial, please have your user's manual on hand so that you can refer to the manual pages. As new options are introduced, we will refer to the manual pages for explanations. This process will show how information can be retrieved from the manual.

Notation: In the text below, the percent sign % refers to the system prompt. You will see a similar prompt in your working window. You should type any text following the % sign at your system prompt; you then hit return on the keyboard to enter the command. Text on the lines immediately following will show the expected response to your action. Where the next line starts with the % sign in the text below, type that line at your system prompt.



2. A Basic Script

In the tutorial on using WXP from the command line, we developed a command line that would display a plot of contoured temperature over the U.S. We noted that the line became large, so now we shall put the command into a small script called demo.

First, let's remind ourselves of the command line:

    % sfccalc -region us -variable st -current la -plot_type cf -con_interval 4 
    -device d -file_param calc -message mess
We are using the current option again to get the latest data, la, and have the message level set to give status and error output from sfccalc. For information about sfccalc, see the sfccalc program pages in the Program Reference section of the Users Manual.

We need to create our sample script. You need to create a file in our working directory called demo by typing:

    % touch demo
Make sure the file is executable by typing:
    % chmod 700 demo
This will give you, the owner of demo, read, write and execute privileges on the file. The commands above are unix and are covered in any good unix text. To edit the file, go into an editor, for example vi:

    % vi demo
and insert the following text:

  #!/bin/csh -f
  #
  # demo: a script to show surface temperature contoured over the U.S.
  #
  set reg = us       # specify region covered by plot
  set var = st       # specify variable to plot
  
  sfccalc -region $reg -variable $var -current la -plot_type cf \
          -con_interval 4 -device d -file_param use -message mess
  
  exit
  # end of script
  #################################################################
To run the script, type:

    % demo
and a display will appear. To remove the display, put the cursor in the window and hit return to return to the system prompt.
    %

Notes about the script:

The script uses the backslash (\) to continue command lines thus making the code easier to read. This backslash indicates a continuation of the command line, so the lines:

    sfccalc -region $reg -variable $var -current la -plot_type cf \
            -con_interval 4 -device d -file_param use -message mess
are implemented as one complete command line.

The region and variable options have secondary variables as values, $reg for the region selection and $var for the variable selection. This allows for simple modification of the script to display different regions and data types. These variables are defined with the set command:

    set reg = us       # specify region covered by plot
    set var = st       # specify variable to plot
The $ sign in the sfccalc line indicates that the following string is a variable name to which values have been assigned. In the example, the Continental U.S., us, is assigned to reg, and temperature, st, assigned to var.

The first line of text of a script must be:

    #!/bin/csh
No space should be between the # and ! characters. This first line tells the system to run the script using the C-shell interpreter program csh which should be resident in the /bin/ directory of the machine. The C-shell interpreter loads the contents of your .cshrc file before going through the script. However, the contents of the .cshrc file were loaded when you logged onto the machine, so this reload is redundant. To stop csh from looking at .cshrc, we can add a -f to the line:

    #!/bin/csh -f
for fast invocation. This means csh will ignore .cshrc and just use whatever environment variables are set during your present login session. To see what environment variables are set for your present login session, type the command:

    % env
Once the C-shell interpreter is invoked, it starts to execute each line of the script, and a display of contour temperatures appears.

To remove the display, put the cursor in the window and hit return.



3. Creating A Background Process With A Script

We can put the sfccalc program into the background so the display will come up and stay up (unix background process). Backgrounding is achieved by using the & sign on the command sfccalc as shown below.

Edit your file demo to add the & to sfccalc:

   # background sfccalc with the `&' sign
   #
   sfccalc -region $reg -variable $var -current la -plot_type cf \
           -con_interval 4 -device d -file_param use -message mess &

Run the script by typing:

    % demo
Notice that a display is shown with title sfccalc, and that the window where you invoked demo has returned the system prompt:

    %
A second display can be put up in addition to the present sfccalc window. To see this, run demo again by typing:

    % demo
To remove the displays, put the cursor into each display and hit return.



4. Script Producing A Display With A Defined Window Title

Let's name the window demo instead of the default sfccalc. This is done using the title option on the sfccalc command line. Edit the command line in the script to include -title demo:

    sfccalc -region $reg -variable $var -current la -plot_type cf \
            -con_interval 4 -device d -file_param use -message mess \
            -title demo &
Run the script, then remove the display.

A second way to name a window is to use the name option. Change the sfccalc line to include -name demo and remove the -title option:

    sfccalc -region $reg -variable $var -current la -plot_type cf \
            -con_interval 4 -device d -file_param use -message mess \
            -name demo &
Run the script, and remove the window when ready.

The difference between using title and name is that:

-title < string >
just titles the window with string.
-name < string >
titles the window with string and also looks for resources pre-appended by string in the Wxp.res file.
The -name < string > option loads resources from the site Wxp.res file and from a user's Wxp.res file if the user has a Wxp.res file in their home directory. Only those resources in the Wxp.res files pre-appended by string will be loaded by this invocation of the program sfccalc using the -name < string > option.

In using the -name < string > option, a command line can be set up to use resources from the Wxp.res files. The program looks for resources first in the site Wxp.res file and then supplements (or overwrites) with those it finds in your personal copy of Wxp.res in your home directory. A personal Wxp.res file is not required for the proper functioning of WXP. The UDRESPATH environment variable defines the paths searched when a WXP program looks for Wxp.res files.

Thus, if a user has a personal Wxp.res file, the user can have custom resources that differ from the site defaults by entering the custom values for the resources into their personal Wxp.res file.



5. Display With A Defined Window Placement

We can place the display window in a specific location using the geometry option in the command line in the following manner:

    sfccalc -region $reg -variable $var -current la -plot_type cf \
            -con_interval 4 -device d -file_param use -name demo \
            -message mess -geometry 800x600+200+200 &
Edit your script demo by including the -geometry 800x600+200+200 option to the sfccalc command line. Then run the script and note where the display is placed. Remove the window.

Try changing the numbers on the geometry option and note how the size and placing of the window is affected. The geometry option is explained in the sfccalc program pages of the Program Reference.

We can use the Wxp.res file as a resource location for the geometry option by adding a line to a personal Wxp.res. If you don't already have a Wxp.res file in you home directory, create one by typing:

    % touch Wxp.res 
and, using an editor, insert the following lines into it:

   ###################################################################
   #
   # Wxp.res file: custom options for 
   #
   #
   ###################################################################

   demo.geometry: 800x600+200+200

   # end of Wxp.res
   ###################################################################
Note the line demo.geometry: 800x600+200+200 where the option geometry is specified. The use of demo in the line gives the resource an identifier, thus only when demo is used in the -name < string > option as -name demo will the resource demo.geometry: 800x600+200+200 be used. Run the script, then remove the window.



6. Using -name To Load Resources From Wxp.res

In the previous section, we put the geometry option into a Wxp.res file as a resource. In a similar manner, we can put other options into a Wxp.res file. Add the following lines to your personal Wxp.res file:

  demo.plot_type: cf
  demo.con_interval: 4
  demo.file_param: use
With these entries in our personal Wxp.res, we can now reduce the command line options in our script demo by removing the -plot_type cf, -file_param use, and -con_interval 4 options from the command line. The new sfccalc command line should look like this:

    sfccalc -region $reg -variable $var -current la -device d -name demo \
            -title "US surface temperature contour" -message mess &
Run the script after editing the sfccalc command.

The -name demo tells sfccalc to search the site Wxp.res file for resources pre-appended by the name demo and keep a copy of them. Then sfccalc will search your home copy of Wxp.res for resources pre-appended by the name demo. If the same resource is found, the value assigned in your home Wxp.res overrides the one found in the site Wxp.res. This is forced by the order of directories assigned to the UDRESPATH environment variable which is set in your home account, for example:

    setenv UDRESPATH ${HOME}:/usr/local/ldm/etc
We can override the resources set in any of the Wxp.res files by again putting a value back on the command line. We see above that we specified contour fill demo.plot_type: cf in the Wxp.res file. We can override this to give a line plot by putting the option for the -plot_type ln (line) back in the script as shown in the sfccalc line below:

  sfccalc -region $reg -variable $var -current la -device d -plot_type ln \
          -name demo -title "US surface temperature contour" -message mess &
If you now run the script with this option a plot showing contours as lines will be created.



7. Further Comments

With the basic demo script, you can use other commands to see different plots. At this point, you are encouraged to look at other programs such as upcalc, contour, rad, grbcalc, etc. Don't forget, you can find out which parameters are required to run the program by typing:

    %  -batch
and you will get the following type of output (this is for grbcalc):

    Unable to run on batch mode
      Need: -current [hour] or file
        and -time time, -level level, -variable var,
        -file_param param, -plot_type type,
        -con_interval intrvl, -device dev[,name]


For further information about WXP from Unidata, email support@unidata.ucar.edu
Last updated by Mike Wright on July 20, 1994