GrADS Script Functions

## Dynamic Loading of Script Functions

Script variables are generally local to the functions (scripts) they are contained in; they exist in memory only while the function is executing. If a variable name starts with an underscore (_), then it becomes a global script variable and keeps its value throughout the execution of the main script file. The drawback to global variables was that the functions they are defined in had to be included in the main script file. With a new capability that comes with GrADS version 1.8, that is no longer the case.

Dynamic loading of script functions means that when your main script calls a function (subscript), all global variables from that function will be retained in memory and can continue to be used by main script. Commonly used functions do not have to be copied into every script that calls them.

The names of GrADS script functions may now have 16 characters and include the underscore, although they still must begin with an alphabetic character. Grads script function names are case sensitive.

Error messages will include the file name where the error ocurred -- in this case, the full path name of the file that was actually opened.

### Using GrADS Script Functions

The tricks to using GrADS script functions are (1) to enable dynamic loading and (2) to teach GrADS how to find the script functions you call from your main script.

To enable the dynamic loading of script functions, put this at the top of your script:

`rc = gsfallow("on")`

To teach Grads how to find the script functions you call from your main script, you must first know how Grads searches for main script file names.

How GrADS searches for main script file names

Let's assume the user wants to run a script called `do_eof.gs` and gives the Grads command:

`ga-> do_eof`

Grads will search in the currently directory for the script name, as provided. If it doesn't find the script, it appends .gs to the script name and tries again. If the script is still not found, then the environment variable GASCRP is examined. GrADS attemps to open the script file in all the directories listed in the GASCRP variable, first with the provided name, then with the .gs appended.

If GASCRP contains "`/usr/local/gradslib /usr/homes/myhome`", then GrADS will search for the script `do_eof` in the following order:

`
- do_eof
- do_eof.gs
- /usr/local/gradslib/do_eof
- /usr/local/gradslib/do_eof.gs
- /usr/homes/myhome/do_eof
- /usr/homes/myhome/do_eof.gs
`

GrADS uses the first file it finds. Once found, the directory that contains the script file is remembered as the "main function prefix".

How GrADS searches for script function file names

Continuing with our example, let's further assume that GrADS encounters a function in `do_eof.gs` that is not included in the stuff already loaded from the main script file. GrADS will look for a .gsf file to load, using the following search path:

`
- <main-function-prefix>/<function-name>.gsf
- <main-function-prefix>/<private-paths>/<function-name>.gsf
- <GASCRP-paths>/<function-name>.gsf
`

The private path directory list is an optional list that is provided via the `gsfpath` function:

`rc = gsfpath("dirlist")`

If used, the declaration of the private path directory list should appear at the top of the main script just underneath the statement enabling the dynamic script loading.

For example, if our main script "do_eof.gs" is executed with the command:

`run /usr/local/gradslib/do_eof`

and this script file contains the following lines at the front:

`rc = gsfallow("on")
rc = gsfpath("math1 string2")`

and the script calls a function `str_chop` which is not found in the main script, then the search path would be:

1. /usr/local/gradslib/str_chop.gsf
2. /usr/local/gradslib/math1/str_chop.gsf
3. /usr/local/gradslib/string2/str_chop.gsf