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

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?