In addition to functioning as a command line interpreter, NCL has an API for submitting NCL scripts from within an application. The API provides GUI and application writers a uniform way to do data access, manipulation, and visualization from within their application using NCL scripts. This should simplify the implementation of application-specific GUIs by reducing design time spent on the visualization code and the data access code.

There are several functions and a special NCL library needed to use the API. The name of the library is libnclapi.a. It should be located in the same directory that NCAR Graphics is installed in. To use the API, you must link to this library and use the following functions. NclInitServer and NclCloseServer must be called at the beginning and end of the application respectively.

Data structures

The following are descriptions of the data structures returned by the NCL API functions.


typedef union _NclApiScalar {
        double  doubleval;
        float   floatval;
        int     intval;
        long    longval;
        short   shortval;
        char    charval;
        string  stringval;
        byte    byteval;
        logical logicalval;
        obj     objval;


struct _NclExtValueRec {
        int type;
        int constant;
        void *value;
	NclApiScalar missing;
        int elem_size;
        int totalelements;
        int n_dims;
        int dim_sizes[NCL_MAX_DIMENSIONS];

typedef struct _NclExtValueRec NclExtValueRec;


struct  _NclApiDataList {
        int kind;
        struct _NclApiDataList *next;
        union {
                struct _NclApiFuncInfoRec *func;
                struct _NclApiVarInfoRec *var;
                struct _NclApiFileInfoRec *file;
                struct _NclApiHLUVarInfoRec *hlu;
                struct _NclApiHLUObjInfoRec *hlu_obj;
        } u;

struct _NclApiHLUObjInfoRec {
        NclQuark name;
        int obj_id;
        NhlClass obj_class;

struct _NclApiHLUVarInfoRec {
        NclQuark name;
        int     n_objs;
        struct _NclApiHLUInfoRec* objs;

struct _NclApiHLUInfoRec {
        NclQuark obj_name;
        NclQuark obj_class;
        int     obj_id;

struct _NclApiFuncInfoRec {
        NclQuark name;
        int     kind;
        int     nparams;
        struct _NclArgTemplate *theargs;

struct _NclApiVarInfoRec {
        NclQuark name;
        NclQuark data_type_quark;
        NclVarTypes     type;   /* value, hlu, file */
        int     n_dims;
        NclDimRec *dim_info;
        int     n_atts;
        NclQuark        *attnames;

struct _NclApiFileInfoRec {
        NclQuark name;
        NclQuark path;
        int file_type;
        int wr_status;
        int     n_dims;
        NclDimRec *dim_info;
        int     n_atts;
        NclQuark *attnames;
        int     n_vars;
        NclQuark *var_names;

Closes the connection to the NCL server.
Frees the data list records returned by several of the API functions.
Frees value records returned by several of the API functions.
Returns a list of HLU objects that have been deleted since the last call to this function.
Returns the HLU error object id being used by the NCL server.
Evaluates and returns the result of an NCL expression.
Returns a list of currently opened files and information about their contents.
Returns a list of variable names and information for a given file.
Returns the id of an HLU object that is referenced by an NCL variable.
Returns a list of all HLU objects and related information referenced by NCL variables.
Returns a list of all HLU objects created since the last call to this function.
Returns a list of functions and parameter types for all functions currently defined in the NCL interpreter.
Returns a list of variables and their related information for all variables currently defined in NCL.
Returns a record containing the value of data reference by a variable.
Must be called at the beginning of the program to initialize NCL.
Prints out buffered error messages.
Submits a block of NCL source that is a contiguous block of text.
Submits a block of NCL commands that are each individual lines of source.
Submits a single NCL command.

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?

$Revision: 1.9 $ $Date: 1998/06/15 21:28:10 $