4.5 Get Information about a Variable from Its ID: nc_inq_var

family A family of functions that returns information about a netCDF variable, given its ID. Information about a variable includes its name, type, number of dimensions, a list of dimension IDs describing the shape of the variable, and the number of variable attributes that have been assigned to the variable.

The function nc_inq_var returns all the information about a netCDF variable, given its ID. The other functions each return just one item of information about a variable.

These other functions include nc_inq_varname, nc_inq_vartype, nc_inq_varndims, nc_inq_vardimid, and nc_inq_varnatts.

Usage

     int nc_inq_var      (int ncid, int varid, char *name, nc_type *xtypep,
                          int *ndimsp, int dimids[], int *nattsp);
     int nc_inq_varname  (int ncid, int varid, char *name);
     int nc_inq_vartype  (int ncid, int varid, nc_type *xtypep);
     int nc_inq_varndims (int ncid, int varid, int *ndimsp);
     int nc_inq_vardimid (int ncid, int varid, int dimids[]);
     int nc_inq_varnatts (int ncid, int varid, int *nattsp);

ncid

NetCDF ID, from a previous call to nc_open or nc_create.

varid

Variable ID.

name

Returned variable name. The caller must allocate space for the returned name. The maximum possible length, in characters, of a variable name is given by the predefined constant NC_MAX_NAME. (This doesn't include the null terminator, so declare your array to be size NC_MAX_NAME+1). The returned character array will be null-terminated.

xtypep

Pointer to location for returned variable type, one of the set of predefined netCDF external data types. The type of this parameter, nc_type, is defined in the netCDF header file. The valid netCDF external data types are NC_BYTE, NC_CHAR, NC_SHORT, NC_INT, NC_FLOAT, and NC_DOUBLE.

ndimsp

Pointer to location for returned number of dimensions the variable was defined as using. For example, 2 indicates a matrix, 1 indicates a vector, and 0 means the variable is a scalar with no dimensions.

dimids

Returned vector of *ndimsp dimension IDs corresponding to the variable dimensions. The caller must allocate enough space for a vector of at least *ndimsp integers to be returned. The maximum possible number of dimensions for a variable is given by the predefined constant NC_MAX_VAR_DIMS.

nattsp

Pointer to location for returned number of variable attributes assigned to this variable.

These functions return the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

The variable ID is invalid for the specified netCDF dataset. The specified netCDF ID does not refer to an open netCDF dataset.

Example

Here is an example using nc_inq_var to find out about a variable named rh in an existing netCDF dataset named foo.nc:

     #include <netcdf.h>
        ...
     int  status                        /* error status */
     int  ncid;                         /* netCDF ID */
     int  rh_id;                        /* variable ID */
     nc_type rh_type;                   /* variable type */
     int rh_ndims;                      /* number of dims */
     int  rh_dims[NC_MAX_VAR_DIMS];     /* variable shape */
     int rh_natts                       /* number of attributes */
        ...
     status = nc_open ("foo.nc", NC_NOWRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
     /* we don't need name, since we already know it */
     status = nc_inq_var (ncid, rh_id, 0, &rh_type, &rh_ndims, rh_dims,
                          &rh_natts);
     if (status != NC_NOERR) handle_error(status);