The User-Defined Plug-in Table (UDPT)

The user defined plug-in table (UDPT) is a simple stand-alone text file that contains all the information that GrADS requires in order to use plug-ins for user-defined functions and graphics display and printing. There is one record (line) in the file for each plug-in. A record contains three blank delimited fields: a Type, a Name, and the Filename, which is the full path to the shared object file (a dynamic library) that contains the plug-in's exectuable routines. Starting with version 2.2.1, an optional fourth entry (an Alias for the function name) may be included if necessary. The UDPT may also contain comments, which can begin with * or #.

1. The Type must be one of these three keywords:
   
   function   (for user-defined functions)
   gxdisplay  (for graphics display)
   gxprint    (for graphics printing)
   
   
2. The Name is how the plug-in is referred to by the user.
   
   For plug-ins of type function, the name should match the subroutine that gets called when the function is invoked, it is the actual name of the function in the user's source code. Because the function name gets parsed by the GrADS expression handler, it must meet the following criteria: it must start with a letter, must be 15 characters or less, and may only contain letters, numbers or underscore. All letters must be lower case. If the user's source code function names cannot meet these criteria, an alias may be used (see #4 below).
   
   For plug-ins of type gxdisplay or gxprint, the name is more like a nickname that is used with the -d or -h arguments on startup to tell GrADS which plug-in to use. For these plug-in types, the rules outlined above still hold, except the name may be mixed case.
   
   
3. The Filename of the shared object file (.so) or dynamic library (.so) must include the full path. The filename can be mixed case but cannot contain any spaces. 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.
   
   
4. (Version 2.2.1) The optional Alias is a workaround in case the function names in the plug-in are incompatible with the requirements for GrADS function names. The alias is appended to the UDPT file entry for the plug-in function and contains the actual function name as it appears in the source code. The name is used for invoking the function inside GrADS, but the alias is the name of the routine that gets loaded from the shared object file.

GrADS will look for UDPT records in two places:

1. The user-specified plug-in table named by the GAUDPT environment variable
2. The default plug-in table (a file called 'udpt') in the directory named by the GADDIR environment variable

Entries in the file named by GAUDPT take precedence over entries the default udpt with the same Type and Name.

Example

Query the UDPT

The 'q udpt' command will show you the complete list of plug-in records that GrADS parsed on startup.

ga-> q udpt
gxdisplay  Cairo      /usr/local/lib/grads/libgxdCairo.so
gxdisplay  X11        /usr/local/lib/grads/libgxdX11.so
gxdisplay  gxdummy    /usr/local/lib/grads/libgxdummy.so
gxprint    Cairo      /usr/local/lib/grads/libgxpCairo.so
gxprint    GD         /usr/local/lib/grads/libgxpGD.so
gxprint    gxdummy    /usr/local/lib/grads/libgxdummy.so
function   dothis     /home/username/grads/udp/dothis.so