3.4 Inquire about a Dimension: nc_inq_dim Family

This family of functions returns information about a netCDF dimension. Information about a dimension includes its name and its length. The length for the unlimited dimension, if any, is the number of records written so far.

The functions in this family include nc_inq_dim, nc_inq_dimname, and nc_inq_dimlen. The function nc_inq_dim returns all the information about a dimension; the other functions each return just one item of information.

Usage

     int nc_inq_dim     (int ncid, int dimid, char* name, size_t* lengthp);
     int nc_inq_dimname (int ncid, int dimid, char *name);
     int nc_inq_dimlen  (int ncid, int dimid, size_t *lengthp);

ncid

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

dimid

Dimension ID, from a previous call to nc_inq_dimid or nc_def_dim.

name

Returned dimension name. The caller must allocate space for the returned name. The maximum possible length, in characters, of a dimension 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.

lengthp

Pointer to location for returned length of dimension. For the unlimited dimension, this is the number of records written so far.

Errors

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

• The dimension 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_dim to determine the length of a dimension named lat, and the name and current maximum length of the unlimited dimension for an existing netCDF dataset named foo.nc:

     #include <netcdf.h>
        ...
     int status, ncid, latid, recid;
     size_t latlength, recs;
     char recname[NC_MAX_NAME+1];
        ...
     status = nc_open("foo.nc", NC_NOWRITE, &ncid);  /* open for reading */
     if (status != NC_NOERR) handle_error(status);
     status = nc_inq_unlimdim(ncid, &recid); /* get ID of unlimited dimension */
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_dimid(ncid, "lat", &latid);  /* get ID for lat dimension */
     if (status != NC_NOERR) handle_error(status);
     status = nc_inq_dimlen(ncid, latid, &latlength); /* get lat length */
     if (status != NC_NOERR) handle_error(status);
     /* get unlimited dimension name and current length */
     status = nc_inq_dim(ncid, recid, recname, &recs);
     if (status != NC_NOERR) handle_error(status);