NCL Home > Documentation > Manuals > Reference

NCL API Functions


NclCloseServer

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    void NclCloseServer(
            void
    );
    
Description

    Must be called to shut down the NCL server.


NclFreeDataList

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    void NclFreeDataList (
            NclApiDataList *the_list;
    );
    
Arguments
    the_list
    A pointer to the NclApiDataList to be freed.

Description

    Frees the pointer to an NclApiDataList that was returned by one of the other API functions.


NclFreeExtValue

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    void NclFreeExtValue(
            NclExtValueRec *val
    );
    
Arguments
val
The argument val is a pointer to an NclExtValueRec that was returned by one of the other API functions.

Description

    Frees the data pointed to by val.


NclGetDelHLUObjsList

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclApiDataList *NclGetDelHLUObjsList(
            void
    );
    
Description

    Returns a list of HLU objects that have been deleted since the last call to this function.


NclGetErrorId

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    int NclGetErrorId(
            void
    );
    
Description

    Returns the HLU error object id being used.


NclGetExprValue

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclExtValueRec *NclGetExprValue(
            char *expression
    );
    
Arguments
    expression
    A string representing a valid NCL expression.

Description

    This function submits the string expression to NCL for evaluation. The result of the expression is returned as a pointer to an NclExtValueRec. If the evaluation of the expression fails, NULL is returned. The errors generated by the expression string can be accessed using NclPrintErrorMsgs.


NclGetFileInfo

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclApiDataList *NclGetFileInfo(
            NclQuark file_sym_name
    );
    
Description

This function is analogous to NclGetFileList except that it returns only a single record that pertains to the file named in the argument.


NclGetVarInfo

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    struct NclApiDataList *NclGetVarInfo( 
            NclQuark var_sym_name
    );
    
Description

This function is analogous to NclGetVarList except that it returns only a single record that pertains to the variable named in the argument.


NclGetFileVarInfo

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    struct NclApiDataList *NclGetFileVarInfo( 
             NclQuark file_sym_name, 
             NclQuark file_var_name
    );
    
Description

This function is analogous to NclGetFileVarsList except that it returns only a single record that pertains to the file and variable named in the arguments.


NclGetFileVarCoordInfo

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    struct NclApiDataList *NclGetFileVarCoordInfo( 
      NclQuark file_sym_name,
      NclQuark file_var_name, 
      NclQuark coordname
    );
    
    
Description

Given a file name, a file variable name, and a coordinate name, this function returns an NclApiVarInfoRec structure.


NclGetVarCoordInfo

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    struct NclApiDataList *NclGetVarCoordInfo( 
      NclQuark var_sym_name, 
      NclQuark coordname
    );
    
Description

Given a variable name and a coordinate name, this function returns an NclApiVarInfoRec structure.


NclGetFileSymNames

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclQuark *NclGetFileSymNames(
            int *num_names
    );
    
Description

Returns the file symbol names, by way of NclQuarks. The number of names is *num_names.


NclGetVarSymNames

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclQuark *NclGetVarSymNames(
            int *num_names
    );
    
Description

Returns the variable symbol names, by way of NclQuarks. The number of names is *num_names.


NclGetProcFuncSymNames

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclQuark *NclGetProcFuncSymNames(
            int *num_names
    );
    
Description

Returns all procedure and function names by way of NclQuarks. The number of names is *num_names.


NclGetFileVarNames

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclQuark *NclGetFileVarNames(
            NclQuark file_sym_name, 
            int *num_names
    );
    
Description

Returns the file variable names of the file specified by file_sym_name. The number of names is *num_names.


NclGetHLUVarSymNames

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclQuark *NclGetHLUVarSymNames(
            int *num_names
    );
    
Description

Returns the HLU variable names as NclQuarks. The number of names is *num_names.


NclGetFileList

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclApiDataList *NclGetFileList(
            void
    );
    
Description

This function returns a list of information structures - one for each of the currently opened files. Each record of the list is a structure:

    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;
    };
    typedef struct _NclApiFileInfoRec NclApiFileInfoRec;
where the members of the structure are:
name
The name of the function or procedure as coded as an "NclQuark". NclQuarks are internal integers associated with unique text strings. To get the associated text string from a Quark, use the Ncl function NrmQuarkToString. See Example0 for usage of NrmQuarkToString.
path
The absolute path name of the file.
file_type
Currently to be ignored.
wr_status
The read/write status. Tis is <= 0 if the file is writeable and is 1 for read only.
n_dims
Is the number of defined dimensions in the file.
dim_info
Dimension information as given by an NclDimRec structure.
n_atts
The number of all global file attributes (not file variable attributes).
attnames
A list of NclQuarks for the global attribute names.
n_vars
The number of all variable defined in the file.
var_names
A list of the variable names.

NclGetFileVarsList

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclApiDataList* NclGetFileVarsList(
            NclQuark filevar
    );
    
Arguments
    filevar
    An NclQuark representation of a variable name.

Description

Given a file symbol (an NclQuark) this function returns information on every variable in the file. For each variable there is a structure:

      struct _NclApiVarInfoRec {
        NclQuark    name;
        int         data_type;
        NclVarTypes type;
        int         n_dims;
        NclDimRec   *dim_info;
        NclQuark    coordnames[NCL_MAX_DIMENSIONS];
        int         n_atts;
        NclQuark    *attnames;
      };
      typedef struct _NclApiVarInfoRec NclApiVarInfoRec;

where the members of the structure are:
name
The name of the variable as coded as an "NclQuark". NclQuarks are internal integers associated with unique text strings. To get the associated text string from a Quark, use the Ncl function NrmQuarkToString. See Example0 for usage of NrmQuarkToString.
data_type
This is an identifier that flags the primitive data type of the data values as per the following internal (non-public) defines:
        #define NCLAPI_none     0
        #define NCLAPI_short    01
        #define NCLAPI_int      02
        #define NCLAPI_long     04
        #define NCLAPI_float    010
        #define NCLAPI_double   020
        #define NCLAPI_char     040
        #define NCLAPI_byte     0100
        #define NCLAPI_string   0200
        #define NCLAPI_numeric  0400
        #define NCLAPI_logical  01000
        #define NCLAPI_obj      02000
       
type
The variable type, as per:
  typedef enum { NORMAL, VARSUBSEL , COORD, COORDSUBSEL, 
                 FILEVAR, FILEVARSUBSEL, PARAM, RETURNVAR,
                 HLUOBJ } NclVarTypes;
  
n_dims
Is the number of dimensions of the variable.
dim_info
Dimension information as given by an NclDimRec structure.
coordnames
The coordinate variable names (if a coordinate variable exists). If no coordinate variable exists, then a -1 is assigned to the specific index of "coordnames".
n_atts
The number of attrubutes associated with the variable.
attnames
A list of NclQuarks for the attribute names.

NclGetHLUObjId

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclExtValueRec NclGetHLUObjId(
            char *var_name
    );
    
Arguments
    var_name
    Name of variable referencing an HLU object.

Description

    For a given HLU variable, this function returns a record of type NclExtValueRec that contains a multi-dimensional array of HLU object ids for that variable, provided the variable is in fact an HLU variable.


NclGetHLUObjsList

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclApiDataList *NclGetHLUObjsList(
            void
    );
    
    
Description

This function returns a list of all variables that reference HLU objects.

        struct NclApiDataList *NclGetHLUObjsList(void);
  
In this case the structure returned in the union member of NclApiDataList is an array of NclApiHLUVarInfoRec structures:
        struct _NclApiHLUVarInfoRec {
          NclQuark name;
          int      n_objs;
          struct   _NclApiHLUInfoRec *objs;
        };
        typedef struct _NclApiHLUInfoRec NclApiHLUInfoRec;
        typedef struct _NclApiHLUVarInfoRec NclApiHLUVarInfoRec;
   
where the structure members are:
name
The name of the variable as coded as a "Quark". Quarks are internal integers associated with unique text strings. To get the associated text string from a Quark, use the Ncl function NrmQuarkToString. See Example 0 for usage of NrmQuarkToString.
n_objs
The number of objects referenced by the variable.
objs
Pointer to an array of records of type NclApiHLUObjInfoRec:
       struct _NclApiHLUObjInfoRec {
         NclQuark name;
         int obj_id;
         NhlClass obj_class;
       };
       typedef struct _NclApiHLUObjInfoRec NclApiHLUObjInfoRec;
       
which contain the object name, the HLU ID, and the HLU class.

NclGetNewHLUObjsList

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclApiDataList *NclGetNewHLUObjsList(
            void
    );
    
    
Description

NclGetProcFuncList

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclApiDataList *NclGetProcFuncList(
            (void)
    );
    
    
Description

    This function returns a list of all defined functions and procedures. The structure returned in the union member of NclApiDataList is:

            struct NclApiFuncInfoRec {
              NclQuark name;
              int     kind;
              int     nparams;
              struct  _NclArgTemplate *theargs;
            };
       
    where the members of the NclApiFuncInfoRec structure are:
    name
    The name of the function or procedure as coded as a "Quark". Quarks are internal integers associated with unique text strings. To get the associated text string from a Quark, use the Ncl function NrmQuarkToString. See Example0 for usage of NrmQuarkToString.
    kind
    Is "0" for procedures and "1" for functions.
    params
    The number of parameters.
    theargs
    Currently to be ignored.

NclGetVarList

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclApiDataList *NclGetVarList(
            void
    );
    
Description

This function returns a list of data variables that are NOT files or HLU objects. The structure returned in the union member of NclApiDataList is an array of NclApiHLUVarInfoRec structures:

        struct _NclApiVarInfoRec {
          NclQuark name;
          int data_type;
          NclVarTypes     type;
          int     n_dims;
          NclDimRec *dim_info;
          NclQuark        coordnames[NCL_MAX_DIMENSIONS];
          int     n_atts;
          NclQuark        *attnames;
        };
        typedef struct _NclApiVarInfoRec NclApiVarInfoRec;

   
where this structure is described above.

NclTypeToString

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    char *NclTypeToString(
            void *val, 
            int data_type
    );
    
Arguments
val
A pointer to a single variable of the type indicated in the data_type argument below.
data_type
An interger flagging a primitive data type.
Description
    This function is used to convert a single element of an array to its string representation. "data_type" is the value of the type field in the NclExtValueRec and "val" is pointer to a single element of the type.

NclGetVarValue

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    NclExtValueRec *NclGetVarValue(
            char* var_name,
            int copy_data
    );
    
    
Arguments
    var_name

    The name of the variable whose data are to be returned.

    copy_data

    True or False value. Specifies whether the data referenced by the variable should be copied before it is returned.

Description

    This function returns the data portion of an NCL variable. The data portion is the actual multidimensional array and its dimensionality.


NclInitServer

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    int     NclInitServer(
            void
    );
    
Description

    Initializes the NCL server. This must be called before any HLU calls or calls to any of the other functions listed here. The error level parameter allows the user to set what level of messages will be printed by NclPrintErrorMsgs.


NclPrintErrorMsgs

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    void NclPrintErrorMsgs(
            void
    );
    
    
Description

    Prints out the currently buffered error messages to whatever the errFileName or errFilePtr resources are set to.


NclSubmitBlock1

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    int NclSubmitBlock1(
            char* script,
            int script_size
    );
    
    
Arguments
    script

    A single block of memory containing one or more '\n'-terminated lines of NCL source.

    script_size

    Size of the block of memory.

Description

    Submits a script for execution to the NCL server. If the return value is 0, the script failed and error messages may need to be printed out using the NclPrintErrorMsgs function. A nonzero number means the script completed correctly.


Reading functions

Each of the following functions reads the requested data item and returns an NclExtValueRec record to the calling environment. The existance of a specific symbol name is determined from the NclGet*Names functions. For functions that read a variable's value, the delimiters start, finish and stride arrays can be provided. If all the delimiter are left NULL, then the entire array is read. When just start is provided, it represents a single scalar selection. When just stride is give, the entire array is selected but stridden using the stride values. When start and finish are provided, a sub-range is selected. Finish should be the terminal reading index. The start-finish range is inclusve. Reverse selection is possible by swapping start and finish.
struct NclExtValueRec *NclReadFileAtt( 
      NclQuark file_sym_name, 
      NclQuark attname
);

struct NclExtValueRec *NclReadFileVar( 
      NclQuark file_sym_name, 
      NclQuark file_var_name, 
      long *start,  
      long *finish, 
      long* stride
);

struct NclExtValueRec *NclReadFileVarAtt( 
      NclQuark file_sym_name, 
      NclQuark file_var_name, 
      NclQuark attname
);

struct NclExtValueRec *NclReadFileVarCoord( 
      NclQuark file_sym_name, 
      NclQuark file_var_name, 
      NclQuark coordname, 
      long *start, 
      long *finish, 
      long *stride
);

struct NclExtValueRec *NclReadVar( 
      NclQuark var_sym_name, 
      long *start, 
      long *finish, 
      long *stride
);

struct NclExtValueRec *NclReadVarAtt( 
      NclQuark var_sym_name, 
      NclQuark attname
);

struct NclExtValueRec *NclReadVarCoord( 
      NclQuark var_sym_name, 
      NclQuark coordname, 
      long *start, 
      long *finish, 
      long *stride
);

struct NclExtValueRec *NclReadVarCoordAtt( 
      NclQuark var_sym_name, 
      NclQuark coordname, 
      NclQuark attname
);

NclSubmitBlock2

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    int NclSubmitBlock2(
            char *script[]
    );
    
Arguments
    script

    An array of NULL terminated lines of NCL source.

Description

    Functions similar to the NclSubmitBlock1 function call with the exception that the input script is an array of strings rather than a block of text. For hard-coded script, this is the ideal form to submit scripts. For files, however, it is easier to use the NclSubmitBlock1.


NclSubmitCommand

Synopsis
    #include <ncarg/ncl/defs.h>
    #include <ncarg/ncl/ApiRecords.h>
    #include <ncarg/ncl/NclApi.h>
    
    int NclSubmitCommand(
            char *command;
    );
    
Arguments
    command

    A single NCL statement.

Description

    Works like both the block functions, except only a single statement is submitted.