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