
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.
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.
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.
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.
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.
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; };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.
-
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.
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.
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.
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.
Works like both the block functions, except only a single statement is submitted.