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.
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_eofGrads 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")For example, if our main script "do_eof.gs" is executed with the command:
run /usr/local/gradslib/do_eofand 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: