NCL Home > Documentation > Manuals > Reference

Loading Default scripts and shared libraries

There are two environment variables which can be set in the user's shell environment which can allow users to customize their NCL environment. The first environment variable NCL_DEF_SCRIPTS_DIR can be used to point to a directory containing scripts the user want to be loaded every time NCL is run by that user. The second environment variable NCL_DEF_LIB_DIR can be used to point to a directory containing specially built shared libraries. These shared libraries can contain the user's custom built C or FORTRAN functions and procedures which will appear upon invocation to be part of NCL's intrinsic function set. Instructions for building custom shared libraries to use with NCL can be found in the NCL Reference Guide under the section titled Extending NCL's function set. The two main sections that apply are using the WRAPIT script and using the wrapit77 application.

Use of NCL_DEF_SCRIPTS_DIR

When using this environment parameter, NCL will attempt to load all files found within the directory pointed to by NCL_DEF_SCRIPTS_DIR. Only files ending with the file extension ".ncl" will be loaded. NCL will not follow any subdirectories. It is recommended that the scripts loaded are functions, procedures and perhaps constant initializations. Loading scripts that load other scripts can be done but if a script defines a function or procedure that is already defined error messages may be generated. (NOTE: as of version 6.0.0 there is an outstanding bug that causes script loading from within other scripts to fail.) The undef procedure can be used to guard against multiple definitions if placed in scripts before function and procedure definitions.

Note that prior to version 6.0.0 it was not possible to control with certainty the order in which the scripts were loaded. Beginning with version 6.0.0, however, the scripts are loaded based on the ascii case-sensitive order (numbers before letters, upper case before lower case) of the script names. Also the error handling has been revised such that files in the directory that do not have the file extension ".ncl" are simply ignored, rather than causing a fatal error. A warning is generated if there are no valid scripts in the directory. A script that fails to load properly does result in a fatal error.

Use of NCL_DEF_LIB_DIR

This environment parameter will cause NCL to load all shared libraries in the directory. These shared libraries must contain a C function called Init which will call either NclRegisterProc or NclRegisterFunc one or more times to register a set of wrapper functions. Information on creating wrapper functions as well as building the shared libraries on a variety of architectures can be found in the NCL Reference Guide section on Extending NCL's function set. The advantage of using this environment parameter over the external statement is that the loaded functions become part of NCL intrinsic function set and can be called without a dynamic library name.