gsudf.gex - Writing Expression Functions as GrADS Scripts

- NAME
- SYNOPSIS
- DESCRIPTION
- EXAMPLES

- Using gsudf for Computing Wind Speed
- Returning defined variables
- Returning an error condition

- FUNCTION PROVIDED

- gsudf [ARGUMENTS]

- BUGS
- SEE ALSO
- AUTHOR
- COPYRIGHT

# NAME

gsudf.gex - Writing Expression Functions as GrADS Scripts

# SYNOPSIS

      ga-> display myfunc(args)

where myfunc is implemented in a GrADS script file named `myfunc.gsf`

# DESCRIPTION

Traditionally, there are two kinds of functions in GrADS: script functions and expression functions, and up to now these two did not mix. Scripting functions are user defined and called from any GrADS script. Such functions are not directly available at the command line, or cannot be used inside GrADS expressions. Expression functions are usually used in conjunction with the `display` and `define` commands such as

       ga-> display aave(myfunc(u), global)

where `aave` is an intrinsic function and `myfunc` is a user defined function.

The dynamic extension gsudf allows you to write expression functions as GrADS script functions. This is better explained with the following examples.

# EXAMPLES

## Using gsudf for Computing Wind Speed

Let us reimplement the intrinsic function `mag` which compute the wind speed given the `u` and `v` components of the wind; we will call this new function `speed`. The first step is to create a text file called `speed.gsf` with the implementation of this function:

       function speed ( u, v )
          expr = 'sqrt(' u '*' u '+' v '*' v ')'
          return expr

Notice that this function simply returns a string which will eventually be evaluated by the GrADS expression parser; more on that later. The second step in the implementation of this function is to add an entry for this function in your User Defined eXtenfion (UDXT) file:

          Type  API   Name      Function       Library
         ------ --- ---------  -----------  --------------
          udf    0    speed      f_gsudf     gsudf.gex.so

The generic handler `f_gsudf` in the shared library `gsudf.gex` executes the file `speed.gsf`, evaluates the string output of this function using the GrADS expression parser and returns the result. The net effect is that `speed.gsf`, with the help of its agent `gsudf`, implements a bonafide GrADS expression function.

Finally, you no longer need to initialize the gsudf package in GrADS v2.0.

       ga-> open model.ctl
       ga-> display speed(ua,va)

## Returning defined variables

Although your GrADS script must always return a string, it does not mean that all it can do is string maniputation. By using the `define` command one can always pre-computed intermediate values, and return the name of the defined variable. Here is an example where the dimension environment is modified, a variable defined in this enlarged dimension environment, and then the dimension reset to its original state:

       function x_cdiff ( var, dim )
          'set x 0 74'
          'define gsudf = cdiff('var','dim')'
          'set x 1 73'
          return 'gsudf'

This function enlarges the domain as to avoid missing undefined values on the longitudinal boundaries (but not at the latitudinal boundary.) A more generic version of this function is included with the source distribution for this extension.

## Returning an error condition

Returning an empty string will signal an error condition

       function errfunc(arg)
          say 'errfunc: error found, cannot proceed'
          return

# FUNCTION PROVIDED

## gsudf [ARGUMENTS]

This function is not directly callable as such from GrADS. Rather it works as a proxy for the user defined functions written as GrADS scripts. There 2 steps involved in defining your user defined function through gsudf:

1. For each function named $func, create a script library file called $func.gsf and placed in a directory where GrADS can locate scripts (for example, in a directory listed in your `GASCRP` environment variable.) The GrADS script must return a string with a valid GrADS expression, or an empty string in case of an abnormal exit.

2. Have a corresponding entry in your User Defined eXtension (UDXT) file, e.g.,

        #      A
        #      P   GrADS     Library      Library                 Short
        # Type I  Function   Function      Path                Description
        # ---- - ---------- ---------- -------------- -------------------------------
          udf  0   speed     f_gsudf    ^gsudf.gex    "The mag() function as gsUDF"

# BUGS

There is not much in terms of garbage collection. Any local variable defined by the GrADS script implementing the expression function stays around until explicitly undefined. To minimize memory usage explicitly undefine any variabled you defined, and when defined variables are involved, return your result in defined variable called gsudf.

# SEE ALSO

- http://opengrads.org/ - OpenGrADS Home Page

- http://opengrads.org/wiki/index.php - OpenGrADS User Defined Extensions

- http://www.iges.org/grads/ - Official GrADS Home Page

# AUTHOR

Arlindo da Silva (dasilva@opengrads.org)

# COPYRIGHT

Copyright (C) 2007-2009 Arlindo da Silva; All Rights Reserved.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

gsudf.gex - Writing Expression Functions as GrADS Scripts