3.4 Inquire about a Dimension: ncmpi_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 ncmpi_inq_dim, ncmpi_inq_dimname, and ncmpi_inq_dimlen. The function ncmpi_inq_dim returns all the information about a dimension; the other functions each return just one item of information.

Operational Mode

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

Usage

int ncmpi_inq_dim     (int ncid, int dimid, char* name, MPI_Offset* lengthp);
int ncmpi_inq_dimname (int ncid, int dimid, char *name);
int ncmpi_inq_dimlen  (int ncid, int dimid, MPI_Offset *lengthp);

ncid

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

dimid

Dimension ID, from a previous call to ncmpi_inq_dimid or ncmpi_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.

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: The specified netCDF ID does not refer to an opened netCDF file.
• NC_EBADDIM: The dimension ID is invalid for the specified netCDF file.

Example

Here is an example using ncmpi_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 file named foo.nc:

#include <pnetcdf.h>
   ... 
int status, ncid, latid, recid;
MPI_Offset latlength, recs;
char recname[NC_MAX_NAME+1];
   ... 
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL, &ncid);  /* open for reading */
if (status != NC_NOERR) handle_error(status);
status = ncmpi_inq_unlimdim(ncid, &recid); /* get ID of unlimited dimension */
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_inq_dimid(ncid, "lat", &latid);  /* get ID for lat dimension */
if (status != NC_NOERR) handle_error(status);
status = ncmpi_inq_dimlen(ncid, latid, &latlength); /* get lat length */
if (status != NC_NOERR) handle_error(status);
/* get unlimited dimension name and current length */
status = ncmpi_inq_dim(ncid, recid, recname, &recs);
if (status != NC_NOERR) handle_error(status);