NCL Home > Documentation > Manuals > Reference

NCL API

NCL has an Applications Programming Interface (API) for invoking certain NCL functionality from a C program. In particular, this API allows for submitting NCL scripts and commands from a C program.

You will need to load the library "libnclapi.a" to use the NCL API (you should be able to find this library in the installation directory for NCAR Graphics). The API function NclInitServer must be called before using the API and NclCloseServer must be called at the end of use.

NclQuarks are are internal integers associated with unique text strings. The functions NrmQuarkToString and NrmStringToQuark can be used to go back and forth between NclQuarks and the strings they represent. See the Examples.

NCL structures are defined with an underscore as the sentinal character for the structure name, and then a typedef is executed to assign as an alternate name the name without the underscore.

Reading the following three topics will help you understand how to use the API:

Data structures
Functions
Examples

Data structures

NclApiDataList: The main informational data structure.
NclExtValueRec: Primary interface to calling environment.
NclApiScalar: A union defining the primitive data types.

Functions

Functions that produce symbol lists

Symbol names functions

Single symbol information functions

Data reading functions

Miscellaneous functions

Alphabetical list of all functions

Functions that produce symbol lists

NclGetDelHLUObjsList: Returns a list of HLU objects that have been deleted since the last call to this function.
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.

Symbol names functions

NclGetFileSymNames: Returns an array of NclQuarks as symbol name references for all file symbol names.
NclGetFileVarNames: Returns an array of NclQuarks as symbol name references for all file variable names.
NclGetHLUVarSymNames: Returns an array of NclQuarks as symbol name references for all HLU variable names.
NclGetProcFuncSymNames: Returns an array of NclQuarks as symbol name references for all function and procedure names.
NclGetVarSymNames: Returns an array of NclQuarks as symbol name references for all variable names.

Single symbol information functions

NclGetFileInfo: Evaluates and returns the result of an NCL expression.
NclGetFileVarCoordInfo: Returns information on file coordinate variables.
NclGetFileVarInfo: Returns information on file variables.
NclGetVarCoordInfo: Returns information on coordinate variables.
NclGetVarInfo: Returns information on a single variable.

Data reading functions

NclGetVarValue: Returns a record containing the value of data reference by a variable.
NclReadFileAtt: Reads file attributes.
NclReadFileVar: Reads file variables.
NclReadFileVarAtt: Reads file variable attributes
NclReadFileVarCoord: Reads file coordinate variables.
NclReadVar: Reads NCL variables.
NclReadVarAtt: Reads variable attributes.
NclReadVarCoord: Reads coordinate variables.
NclReadVarCoordAtt: Reads coordinate variable attributes.

Miscellaneous functions

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.
NclGetErrorId: Returns the HLU error object id being used by the NCL server.
NclGetExprValue: Evaluates and returns the result of an NCL expression.
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.
NclTypeToString: Converts a value to a string.

Alphabetical list of all functions

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.
NclGetFileInfo: Evaluates and returns the result of an NCL expression.
NclGetFileList: Returns a list of currently opened files and information about their contents.
NclGetFileSymNames: Returns an array of NclQuarks as symbol name references for all file symbol names.
NclGetFileVarCoordInfo: Returns information on file coordinate variables.
NclGetFileVarInfo: Returns information on file variables.
NclGetFileVarNames: Returns an array of NclQuarks as symbol name references for all file variable names.
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.
NclGetHLUVarSymNames: Returns an array of NclQuarks as symbol name references for all HLU variable names.
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.
NclGetProcFuncSymNames: Returns an array of NclQuarks as symbol name references for all function and procedure names.
NclGetVarCoordInfo: Returns information on coordinate variables.
NclGetVarInfo: Returns information on a single variable.
NclGetVarList: Returns a list of variables and their related information for all variables currently defined in NCL.
NclGetVarSymNames: Returns an array of NclQuarks as symbol name references for all variable names.
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.
NclReadFileAtt: Reads file attributes.
NclReadFileVar: Reads file variables.
NclReadFileVarAtt: Reads file variable attributes
NclReadFileVarCoord: Reads file coordinate variables.
NclReadVar: Reads NCL variables.
NclReadVarAtt: Reads variable attributes.
NclReadVarCoord: Reads coordinate variables.
NclReadVarCoordAtt: Reads coordinate variable attributes.
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.
NclTypeToString: Converts a value to a string.

Examples

Example 0 - submit script and retrieve information.

NclApiDataList

This is the main informational data structure. The kind member determines which union member to use. If this structure is returned from any of the functions with "List" in their names, a multi-node linked list is possible, otherwise the "next" member is NULL.

  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;
  };
  typedef struct _NclApiDataList NclApiDataList;

Possible values for the kind member in NclApiDataList are:

  #define VARIABLE_LIST 1
  #define PROCFUNC_LIST 2
  #define FILE_LIST 3
  #define FILEVAR_LIST 4
  #define HLU_LIST 5
  #define HLUOBJ_LIST 6

NclDimRec

This structure is used to provide file dimension information.

        typedef struct _NclDimRec {
          int   dim_quark;
          long  dim_num;
          int   dim_size;
        } NclDimRec;

dim_quark: An NclQuark value for the dimension name.
dim_num: The dimension number.
dim_size: The dimension size.

NclExtValueRec

NCL exports its data to the calling interface using this structure. All functions with "Read" in the name of the function return this data structure. The "type" member contains an identifier to determine which primitive data type the data is stored in. The type field is an enumerated type defined in NclDataDefs.h. This is not a public data file so it should not be included. Therefore the field is of type integer the following are #define in NclApi.h and match the values in NclDataDefs.h:


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

The members of this structure are:

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

constant

This member is set to 0 if the pointer member "value" is freeable by the calling environment, otherwise the the "value" member should not be freed.

value

A pointer to the data requested.

has_missing

If non-zero, then the member "missing" contains the missing value.

missing

Contains the missing value if "has_missing" is non-zero. The data type NclApiScalar is defined below.

elem_size

the size in bytes of each data value.

totalelements

The total number of values in "value".

n_dims

The number of dimensions of "value".

dim_sizes

The dimension sizes of "value". "dim_sizes" should be dimensioned for at least n_dims; dim_sizes[i] should be larger than one for 0 < i <= n_dims. The largest that dim_sizes should be is NCL_MAX_DIMENSIONS.

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;

Examples

Example 0 - submit script and retrieve information.

/*
 *  Example 0 - submit an NCL script and retrieve information.
 *
 *  Include the necessary header files.
 */
#include <ncarg/hlu/hlu.h>
#include <ncarg/hlu/NresDB.h>
#include <ncarg/ncl/defs.h>
#include <ncarg/ncl/NclDataDefs.h>
#include <ncarg/ncl/ApiRecords.h>
#include <ncarg/ncl/NclApi.h>
#include <ncarg/ncl/NclCallBacksI.h>

extern FILE *stdout_fp;

/*
 *  Code the following NCL lines into a string array
 *  and submit it to NCL:
 *
 *     ncargdir = getenv("NCARG_ROOT")
 *     f = ncargdir + "/lib/ncarg/data/cdf/Tstorm.cdf"
 *     a = addfile(f,"r")
 *     b = a->t
 *     x = create "x" xWorkstationClass noparent end create
 *     sf = create "sf" scalarFieldClass noparent
 *             "sfDataArray" : b(0,:,:)
 *             "sfMissingValueV" : b@_FillValue
 *     end create
 *     cn = create "cn" contourPlotClass x
 *             "cnScalarFieldData" : sf
 *     end create
 *     draw(cn)
 *     print(x)
 *     ;frame(x)
 *
 */
char *testscript[] = {
  "ncargdir = getenv(\"NCARG_ROOT\")",
  "f = ncargdir + \"/lib/ncarg/data/cdf/Tstorm.cdf\"",
  "a = addfile(f,\"r\")",
  "b = a->t",
  "x = create \"x\" xWorkstationClass noparent end create",
  "sf = create \"sf\" scalarFieldClass noparent",
  "       \"sfDataArray\" : b(0,:,:)",
  "       \"sfMissingValueV\" : b@_FillValue",
  "end create",
  "cn = create \"cn\" contourPlotClass x",
  "       \"cnScalarFieldData\" : sf",
  "end create",
  "draw(cn)",
  "print(x)",
  ";frame(x)",
  NULL
};


/*
 *  Submit the test script, retrieve and print information.
 */
main()
{
  NclExtValueRec *tmp_rec;
  NclApiDataList *tmp_api,*tmp_api1;
/*
 *  NclQuarks are are internal integers associated with unique text 
 *  strings.  The functions NrmQuarkToString and NrmStringToQuark
 *  can be used to go back and forth between NclQuarks and the
 *  strings they represent.
 */
  NclQuark *tmp_quark;
  int n_names;
  int i;
  int j;
  long start[10];
  long finish[10];
  long stride[10];

  stdout_fp = stdout;

/*
 *  Initialize the server.  This call must be made before
 *  using any of the API procedures.
 */
  NclInitServer();

  NclSubmitBlock2(testscript);
        
  tmp_quark = NclGetFileSymNames(&n_names);       
  printf("NclGetFileSymNames: %d names\n",n_names);
  for (i = 0; i < n_names; i++) 
    printf("\ttmp_quark[%d]: %s\n",
            i,NrmQuarkToString(tmp_quark[i]));
  free(tmp_quark);
  tmp_quark = NclGetVarSymNames(&n_names);        
  printf("NclGetVarSymNames: %d names\n",n_names);
  for (i = 0; i < n_names; i++) 
    printf("\ttmp_quark[%d]: %s\n",
            i,NrmQuarkToString(tmp_quark[i]));
  free(tmp_quark);
  tmp_quark = NclGetHLUVarSymNames(&n_names);     
  printf("NclGetHLUVarSymNames: %d names\n",n_names);
  for (i = 0; i < n_names; i++) 
    printf("\ttmp_quark[%d]: %s\n",
            i,NrmQuarkToString(tmp_quark[i]));
  free(tmp_quark);
  tmp_quark = NclGetProcFuncSymNames(&n_names);   
  printf("NclGetProcFuncSymNames: %d names\n",n_names);
  for (i = 0; i < n_names; i++) 
    printf("\ttmp_quark[%d]: %s\n",i,NrmQuarkToString(tmp_quark[i]));
  free(tmp_quark);

  tmp_api = NclGetVarInfo(NrmStringToQuark("b"));
  printf("b var coord info\n");
  for(j = 0; j < tmp_api->u.var->n_dims; j ++) {
    tmp_api1 = 
      NclGetVarCoordInfo(NrmStringToQuark("b"),tmp_api->u.var->coordnames[j]);
    printf("\tcoord %d name: %s\n",j,
            NrmQuarkToString(tmp_api1->u.var->name));
    NclFreeDataList(tmp_api1);
  }
  NclFreeDataList(tmp_api);
  tmp_api = NclGetFileInfo(NrmStringToQuark("a"));
  for(j = 0; j < tmp_api->u.file->n_atts; j++) {
    tmp_rec = 
      NclReadFileAtt(NrmStringToQuark("a"),tmp_api->u.file->attnames[j]);
    NclFreeExtValue(tmp_rec);
  }
  NclFreeDataList(tmp_api);
  tmp_quark = NclGetFileVarNames(NrmStringToQuark("a"),&n_names); 
  for(i = 0; i < n_names; i++) {
    tmp_api = NclGetFileVarInfo(NrmStringToQuark("a"),tmp_quark[i]);
    for(j =0; j < tmp_api->u.var->n_dims; j++) {
      if(tmp_api->u.var->coordnames[j] != -1) {
        tmp_api1 = 
          NclGetFileVarCoordInfo(NrmStringToQuark("a"),
                                 tmp_quark[i],
                                 tmp_api->u.var->coordnames[j]);
          NclFreeDataList(tmp_api1);
      }
    }
    for(j = 0; j < tmp_api->u.var->n_atts; j++) {
      tmp_rec = 
        NclReadFileVarAtt(NrmStringToQuark("a"),
                          tmp_quark[i],  
                          tmp_api->u.var->attnames[j]);
      NclFreeExtValue(tmp_rec);
    }
    tmp_rec = NclReadFileVar(NrmStringToQuark("a"),tmp_quark[i],NULL,NULL,NULL);
    NclFreeExtValue(tmp_rec);
    NclFreeDataList(tmp_api);
  }
  tmp_api = NclGetVarInfo(NrmStringToQuark("b"));
  start[0] = 0;
  start[1] = 0;
  start[2] = 0;
  finish[0] = 0;
  finish[1] = 9;
  finish[2] = 9;
  stride[0] = 1;
  stride[1] = 2;
  stride[2] = 2;
  tmp_rec = NclReadVar(NrmStringToQuark("b"),NULL,NULL,NULL);
  NclFreeExtValue(tmp_rec);
  tmp_rec = NclReadVar(NrmStringToQuark("b"),start,NULL,NULL);
  NclFreeExtValue(tmp_rec);
  tmp_rec = NclReadVar(NrmStringToQuark("b"),NULL,NULL,stride);
  NclFreeExtValue(tmp_rec);
  tmp_rec = NclReadVar(NrmStringToQuark("b"),start,finish,NULL);
  NclFreeExtValue(tmp_rec);
  tmp_rec = NclReadVar(NrmStringToQuark("b"),start,finish,stride);
  NclFreeExtValue(tmp_rec);

  tmp_rec = NclReadFileVar(NrmStringToQuark("a"),
                           NrmStringToQuark("t"),
                           NULL,NULL,NULL);
  NclFreeExtValue(tmp_rec);
  tmp_rec = NclReadFileVar(NrmStringToQuark("a"),
                           NrmStringToQuark("t"),
                           start,NULL,NULL);
  NclFreeExtValue(tmp_rec);
  tmp_rec = NclReadFileVar(NrmStringToQuark("a"),
                           NrmStringToQuark("t"),
                           NULL,NULL,stride);
  NclFreeExtValue(tmp_rec);
  tmp_rec = NclReadFileVar(NrmStringToQuark("a"),
                           NrmStringToQuark("t"),
                           start,finish,NULL);
  NclFreeExtValue(tmp_rec);
  tmp_rec = NclReadFileVar(NrmStringToQuark("a"),
                           NrmStringToQuark("t"),
                           start,finish,stride);
  NclFreeExtValue(tmp_rec);

  for(i = 0; i < tmp_api->u.var->n_atts; i++) {
    tmp_rec = NclReadVarAtt(NrmStringToQuark("b"),
                            tmp_api->u.var->attnames[i]);
    NclFreeExtValue(tmp_rec);
  }
  for(i = 0; i < tmp_api->u.var->n_dims; i++) {
    tmp_api1 = NclGetVarCoordInfo(NrmStringToQuark("b"),
                                  tmp_api->u.var->coordnames[i]);
    for(j = 0; j < tmp_api1->u.var->n_atts; j++) {
      tmp_rec = NclReadVarCoordAtt(NrmStringToQuark("b"),
                                   tmp_api->u.var->coordnames[i],
                                   tmp_api1->u.var->attnames[j]);
      NclFree(tmp_rec);
    }
    tmp_rec = NclReadVarCoord(NrmStringToQuark("b"),
                              tmp_api->u.var->coordnames[i],
                              NULL,NULL,NULL);
    NclFreeExtValue(tmp_rec);
    NclFreeDataList(tmp_api1);
  }
  NclFreeDataList(tmp_api);

/*
 *  Close the server.
 */
  NclCloseServer();
}