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

Returns a list of HLU objects that have been created since a previous call to this function. For details on the return value, see the description of NclGetHLUObjsList.

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

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

type field in the NclExtValueRec

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.

NclReadFileAtt
NclReadFileVar
NclReadFileVarAtt
NclReadFileVarCoord
NclReadVar
NclReadVarAtt
NclReadVarCoord
NclReadVarCoordAtt

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.