GO files are files containing Ferret commands. They can be executed with the command "GO filename". Throughout this manual, these files are referred to as GO scripts or journal files (the file names end in *.jnl). There are two kinds of GO files provided with the distribution (differing in function, not form)—demos and tools. A list of the demonstrations and scripts can be found in Ferret's on-line documentation in "on-line demonstrations".

1.5.1 Demonstration files

Demonstration GO files provide examples of various Ferret capabilities (the tutorial is such a script) . The demonstration GO files may be executed simply by typing the Ferret command

yes? GO demo_name 
example: yes? GO vector_demo

Below is a list of the demo files provided as of 4/99 (located in directory $FER_DIR/examples). The Unix command "Fgo demo" will list all GO scripts containing the string "demo". Use Fgo '*' to see all the scripts that are currently available on your system.

1.5.2 GO tools

GO tools are scripts which contain Ferret commands and perform dataset-independent tasks. For example, "GO land" overlays the outline of the continents on your plot. (Note: In order for Ferret to locate the GO scripts, the environment variable FER_GO must be properly defined. See the chapter "Computing Environment," for guidance.)

To run any GO tool, from the Ferret command line, type,

Yes? GO scriptname

Or if the script has arguments, they follow the script name with optional comma separators.

yes? GO script2 arg1, arg2

To find out about the script, use the /HELP qualifier, which opens the script with the more command to type the first 20 lines of the script and allow you to see the documentation at the start of the script.

yes? GO/HELP scriptname

To omit arguments from a GO script,

yes? GO script arg1, , arg3

Or double quotes with a space to indicate the missing item.

yes? GO script arg1 " " arg3

The Unix command Fgo has been provided to assist with locating tools within the Unix directory hierarchy. For example,

% Fgo grid displays all tools with the substring "grid" in their names
% Fgo '*' displays all GO tools and demonstrations

When passing arguments to GO commands sometimes it is necessary to pass enclosing quotation marks. An common example is the passing of the argument to the CONTOUR/LEVELS qualifier in cases such as

CONTOUR/LEVELS="(-100) (-10,10,2) (100)" my_var

where there may be blanks embeddd inside of the string. There are 3 methods to embed quotations inside of strings

1. use "\" to protect the quotation marks in the GO command line

yes? go my_go_script "\"(-100) (-10,10,2) (100)"\"

with the script containing the line

CONTOUR/LEVELS=$1 my_var

2. use "\" to define a symbol which contains the quotation marks

yes? DEFINE my_quoted_string \"$1\"
yes? CONTOUR/LEVELS=($my_quoted_string) my_var

3. use the symbol substitution syntax to add quotes to theGO argument

Yes? CONTOUR/LEVELS=$1&|*>"*"&

Of course, in the above examples one could also simply use

yes? CONTOUR/LEVELS="$1" my_var

Below is a table of the tools provided with your Ferret installation. Some tools accept optional arguments to control details. Use Fgo -more script_name for details on a script.

1.5.3 Writing GO tools

A GO tool ("GO script," "journal file," ...) is simply a sequence of Ferret commands stored in a file and executed with the GO command. Writing a simple GO tool requires nothing more than typing normal commands into a file.

To write a robust GO tool that may be shared, however, certain guidelines should be followed:

1) the GO tool should be well documented

2) the GO tool should leave the Ferret context unmodified

3) the GO tool may need to run "silently"

4) the GO tool may need to accept arguments (a maximum of 99 parameters)

1.5.3.1 Documenting GO tools

Documentation consists primarily of well-chosen comment lines (lines beginning with an exclamation mark). In addition, a line of this form should be included:

! Description: [one-line summary of your GO tool]

This line is displayed by the Fgo tool.

1.5.3.2 Preserving the Ferret state in GO tools

Often a complex GO tool requires setting data sets, modifying the current region, etc. But to a user executing this tool its behavior may seem erratic if the user's previous context is modified by running the tool. A tool can restore the previous state of Ferret by these means:

1.5.3.3 Silent GO tools

If a user has set mode "verify" then by default every line of your GO tool, including comment lines, will be displayed at the screen as Ferret processes it. To make your GO tool run silently include the command CANCEL MODE VERIFY at the beginning of the GO tool and SET MODE/LAST VERIFY at the end. If the backslash character "\" is found at the beginning of any line that single line will not be displayed regardless of the state of MODE VERIFY. Thus the command "\CANCEL MODE VERIFY" is often the first line of a GO tool. Note also that the command LET/SILENT is useful in GO tools which need to define variables.

1.5.3.4 Arguments to GO tools

Arguments (parameters) may be passed to GO tools on the command line. There is an upper limit of 99 arguments allowed. For example,

yes? GO land red

passes the string "red" into the GO file named land.jnl. Inside the GO tool the argument string "red" is substituted for the string "$1" wherever it occurs. The "1" signifies that this is the first argument—similar logic can be applied to $1,... $99 or $0 where $0 is replaced by the name of the GO tool itself. "$*" is replaced by all the arguments as a single string, separated by spaces.

If there are more than 9 arguments, the syntax $nn (nn may be 1 through 99) is equivalent to to ($nn), however the parentheses enclosed form is generally preferred as it avoids ambiguities. Specifying $12.dat is equivalent to ($12).dat but is less clear.

As Ferret performs the substitution of $1 (or other) arguments it offers a number of string processing and error processing options. For example, without these options, if a user failed to supply an argument to "GO land" then Ferret would not know what to substitute for $1 and it would have to issue an error message. A default value can be supplied by the GO tool writer using the syntax

$1%string%

for example,

$1%black%

inside land.jnl would default to "black" if no color were specified. Note that in the example percent signs were used to delimit the default string but any of the characters ! # $ % or & also work as delimiters.

If the argument is a 2-digit number, and we are making a substitution, the replacement text goes inside the parentheses. For example, plot the variable passed as argument 1 with the color given by argument 12, or green if no argument 12 is given:

PLOT/COLOR=($12#green#) $1

In another case it might not be appropriate to supply a default string but instead it would be desirable to issue an instructional error message. The "<" character indicates an error message text:

$1"<you must supply an argument to this GO tool"

In still other cases there are a range of acceptable arguments but all other arguments are illegal. The allowable arguments can be specified following "|" (vertical bar) characters as in this example:

$1"|black|red|<You must specify black or red"

or a default of "black" could be specified together with the options as

$1"black|black|red|"

In the interest of "friendliness" a GO file may want to allow the user to specify a string other than the string actually needed by the GO tool. For example, in older Ferret versions red plot line was actually obtained by the PLOT command qualifier /LINE=2—the string "red" never appeared in this command. To allow a user to specify "red" and yet have the string "2" substituted, Ferret has provided the replacement arrow ">". Thus

$1"1|red>2|"

specifies a default string of "1" if no argument is given but substitutes "2" if "red" is supplied. In a typical GO tool line, defaults, options, substitutions, and an error message are combined like this:

PLOT/LINE=$1"1|red>2|green>3|blue>4|<must be red, green, or blue"

Note that the error message will be issued only if some color other than "red," "green," or "blue" is specified; if no argument is specified then "1" is substituted.

An asterisk (*) can be used to designate that any text whatsoever is acceptable as an option.

PLOT/LINE=$1"1|red>2|green>3|blue>4|*>7"

would never generate an error and would use line style 7 (thick black) if an unrecognized argument string such as "orange" were given.

An asterisk (*) can also be used on the right-hand side of a substitution, in which case it stands for the entire original argument string. For example

SET VARIABLE/TITLE=$1%*>"*"%

will place double quotation marks around the string in argument 1.

1.5.3.5 Documentation and checking arguments to GO tools

A final style note to keep in mind when writing GO tools that use arguments: providing error message feedback and appropriate documentation for the user is essential. In complex GO tools, all arguments should be checked at the beginning of the GO tool using the no-op command (has no effect) "QUERY/IGNORE". Thus the GO tool land.jnl might contain these lines at the beginning:

! check the argument
QUERY/IGNORE $1"1|red|green|blue|<must be red, green, or blue"

Once argument errors have been trapped and reported, the lengthy error text would not be needed again in the GO tool.

GO tools that use arguments should also be carefully documented. There are numerous examples provided with Ferret; try, for example, the Unix commands

% Fgo -more fland.jnl
% Fgo -more stick_vectors

or

% Fgo -more squeeze_colors

1.5.3.6 Flow Control in GO tools

There are several Ferret commands and techniques to assist with flow control in your GO scripts.

GO (subroutines)

The GO command may be used inside of a GO script (tool) to execute another (nested) GO script. If an error occurs inside of a nested GO script and SET MODE IGNORE_ERROR has not been issued then the GO script will be interrupted and control returns to the command line. Note that anytime an error is issued, whether MODE IGNORE_ERROR is set or not, a symbol FER_LAST_ERROR is set, which contains the string that was written to standard error.

REPEAT (looping)

The REPEAT command may be used to execute loops within Ferret. The loop "counter" may be an index (I,J,K, or L) or a world coordinate (longitude, latitude, depth, or time). The increment between loop iterations need not correspond to the spacing of points on a grid. When used in conjunction with the "d" options of SET REGION, such as SET REGION/DI="-5:-5" the loops may be used to zoom in or out of a region or to pan a limited-width window of view across a larger region. See the Advanced Movie-Making section of this manual for further details.

IF-THEN-ELSE (conditional execution)

An IF-THEN-ELSE syntax can be used to conditionally execute Ferret commands. It may be used in two styles—single line and multi-line. See the IF command in the Commands Reference section of this manual for further details.

1.5.3.7 Debugging GO tools

As the complexity of Ferret GO scripts increases it becomes more challenging to locate and correct errors in GO scripts. This is especially true if, as so many GO scripts do, the scripts are made silent by containing the command CANCEL MODE VERIFY. In a silent script it can be unclear from where within the script an error message is originating.

A special VERIFY mode has been provided to assist with locating the source of these error messages

SET MODE VERIFY:ALWAYS

The ALWAYS argument to this command instructs Ferret to ignore CANCEL MODE VERIFY commands inside of command files. All of the script commands that Ferret executes will be echoed when this mode is set. Error messages will appear with the commands that generated them. To restore normal non-debugging operations issue CANCEL MODE VERIFY or SET MODE VERIFY (no argument) interactively from the yes? prompt.

Complex webs of variable definitions (defined with LET or DEFINE VARIABLE) may also create challenges for debugging scripts. See Debugging Complex Hierarchies of Expressions for further discussion of this topic.