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


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