4.8 Get Information about a Variable from Its ID: ncmpi_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 ncmpi_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 ncmpi_inq_varname, ncmpi_inq_vartype, ncmpi_inq_varndims, ncmpi_inq_vardimid, and ncmpi_inq_varnatts.

Operational Mode

These APIs are independent subroutines.

These APIs can be called while the file is in either define or data mode (collective or independent).

Usage

int ncmpi_inq_var       (int ncid, int varid, char *name, nc_type *xtypep,
                         int *ndimsp, int dimids[], int *nattsp);
int ncmpi_inq_varname   (int ncid, int varid, char *name);
int ncmpi_inq_vartype   (int ncid, int varid, nc_type *xtypep);
int ncmpi_inq_varndims  (int ncid, int varid, int *ndimsp);
int ncmpi_inq_vardimid  (int ncid, int varid, int dimids[]);
int ncmpi_inq_varnatts  (int ncid, int varid, int *nattsp);
int ncmpi_inq_varoffset (int ncid, int varid, MPI_Offset *offset);

ncid

NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.

varid

Variable ID. Different MPI processes may use different variable IDs.

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. For CDF-5 file format, the following data types are also supported: NC_UBYTE, NC _USHORT, NC_UINT, NC_INT64, and NC_UINT64.

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.

offset

Pointer to the location for returned starting file offset of this variable.

Return Error Codes

APIs in this group return the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

• NC_EBADID: Bad ncid. The specified netCDF ID does not refer to an opened netCDF file.
• NC_ENOTVAR: The variable ID is invalid for the specified netCDF file.
• NC_EGLOBAL: NC_GLOBAL is considered invalid for these APIs, except ncmpi_inq_varnatts().
• NC_ENOTSUPPORT: This API for NetCDF-4 files is not yet supported.

Example

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

#include <pnetcdf.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_dimids[NC_MAX_VAR_DIMS];    /* dimension ids */
int rh_natts                       /* number of attributes */
   ...
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL,  &ncid);
if (status != NC_NOERR) handle_error(status);
   ...
status = ncmpi_inq_varid(ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
/* we don't need name, since we already know it */
status = ncmpi_inq_var(ncid, rh_id, 0, &rh_type, &rh_ndims, rh_dimids, &rh_natts);
if (status != NC_NOERR) handle_error(status);