Overview
How to set up and use User Defined Plug-ins
How to compile User Defined Plug-ins
The User Defined Plug-in Table
The environment variable GAUDPT
Example: Add a number to a variable
User Defined Plug-ins were introduced in version 2.1.1.b0 and are intended to replace the old User Defined Functions, which were disabled when version 2.0 was introduced. The function arguments and data grids are no longer passed between GrADS and the user's program through data files written out to disk. With plug-ins, the user's code is dynamically loaded into GrADS when invoked by the user, and the data is operated on while still sitting in memory. The use of plug-ins will be an improvement in performance and flexibility for users who want to create customized functions. Please read the documentation carefully.
User Defined Plug-ins are compiled as dynamic libraries or shared object files and are loaded by GrADS using the dlopen(), dlsym(), and dlclose() functions. Compiling these dynamic object files is a two-step process that requires a slightly different syntax than what is normally used to compile a stand-alone executable. Consider an example plug-in program called addthis.c:
Compile the
plug-in source code (addthis.c
) and create the object file.
gcc -fPIC -Wall -g -c addthis.c
Note that this program requies the inclusion of grads.h
, which is part of the GrADS source code. Use the environment variable CFLAGS to specify the directory where grads.h
resides (e.g. $HOME/grads/src/grads.h):
setenv CFLAGS -I$HOME/grads/src gcc -fPIC -Wall -g -c addthis.c $CFLAGS
If you get an error message that the compiler cannot find additional include files such as shapefil.h
, then try adding the supplibs include directory where the file is located to the CFLAGS
environment variable, or use the -D option to disable the USESHP macro:
gcc -fPIC -Wall -g -c addthis.c $CFLAGS -DUSESHP=0
addthis.o
, you must create the dynamic library/shared object file that will be loaded by GrADS. More ```` than one object file can be packaged in a dynamic library/shared object file. The synatx for this step is different for Linux systems and for Mac OS X:
For Linux:
gcc -fPIC -g -shared -rdynamic addthis.o -o addthis.so
For Mac OS X:
libtool -dynamic -flat_namespace -undefined suppress addthis.o -o addthis.dylib
The user defined function table (UDFT) is a simple text file that contains information about each user defined plug-in function. There is one record (line) in the file for each plug-in, and the file may contain multiple records for any number of plug-ins. Each plug-in record contains three blank delimited fields:
Field 1: The type of the plug-in, which is either function
or defop
. (N.B.: The defop
type will be for operations on previously defined variables, and hasn't yet been implemented.) For now, the only working option for this field is function
.
Field 2: The name of the function, which must meet the following criteria: it must start with a letter, be less than 16 characters long, and consist of letters or numbers or underscore. All letters must be lower case.
Field 3: The file name (including the full path) of the shared object file (a dynamic library) that contains the function's executable routine. GrADS will use the 'dlopen' command to load the library file, and the 'dlsym' command to point to the named function. The man pages for dlopen and dlsym have more information about how these routines work.
An example of a record for our example plug-in addthis.c
might look like this:
function addthis /home/username/grads/udp/addthis.so
GrADS will look for user defined plug-in function definitions in two places: the file name pointed to by the environment variable GAUDPT, and a file named "udpt" in the directory named by the GADDIR environment variable. An example of setting the GAUDPT environment variable is:
setenv GAUDPT $HOME/grads/udpt
addthis.c
is a sample user defined plug-in function for use with GrADS that does a very basic task: it adds a number to all the non-missing values in a GrADS expression, which may be for gridded or station data. Additional information may be found in the comments of the source code.