NCL API

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.

NclApiScalar

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

NclExtValueRec

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;

NclApiDataList


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;
};

NclCloseServer
Closes the connection to the NCL server.
NclFreeDataList
Frees the data list records returned by several of the API functions.
NclFreeExtValue
Frees value records returned by several of the API functions.
NclGetDelHLUObjsList
Returns a list of HLU objects that have been deleted since the last call to this function.
NclGetErrorId
Returns the HLU error object id being used by the NCL server.
NclGetExprValue
Evaluates and returns the result of an NCL expression.
NclGetFileList
Returns a list of currently opened files and information about their contents.
NclGetFileVarsList
Returns a list of variable names and information for a given file.
NclGetHLUObjId
Returns the id of an HLU object that is referenced by an NCL variable.
NclGetHLUObjsList
Returns a list of all HLU objects and related information referenced by NCL variables.
NclGetNewHLUObjsList
Returns a list of all HLU objects created since the last call to this function.
NclGetProcFuncList
Returns a list of functions and parameter types for all functions currently defined in the NCL interpreter.
NclGetVarList
Returns a list of variables and their related information for all variables currently defined in NCL.
NclGetVarValue
Returns a record containing the value of data reference by a variable.
NclInitServer
Must be called at the beginning of the program to initialize NCL.
NclPrintErrorMsgs
Prints out buffered error messages.
NclSubmitBlock1
Submits a block of NCL source that is a contiguous block of text.
NclSubmitBlock2
Submits a block of NCL commands that are each individual lines of source.
NclSubmitCommand
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 $