2.13 Inquire about an Open NetCDF File: ncmpi_inq Family

Members of the ncmpi_inq family of functions return information about an opened netCDF file, given its netCDF ID. These inquiry functions may be called from either define mode or data mode. The first function, ncmpi_inq, returns values for the number of dimensions, the number of variables, the number of global attributes, and the dimension ID of the dimension defined with unlimited length, if any. Other functions in the family each return just single items of information.

No file I/O is actually performed when these functions are called, because the information in request is stored in the file header which is already cached in memory.

Operational Mode

These APIs are independent subroutines.

They can be called in either define or data mode (collective or independent).

Usage

int ncmpi_inq             (int ncid, int *ndimsp, int *nvarsp, int *ngattsp, int *unlimdimidp);
int ncmpi_inq_ndims       (int ncid, int *ndimsp);
int ncmpi_inq_nvars       (int ncid, int *nvarsp);
int ncmpi_inq_natts       (int ncid, int *ngattsp);
int ncmpi_inq_unlimdim    (int ncid, int *unlimdimidp);
int ncmpi_inq_format      (int ncid, int *formatp);

int ncmpi_inq_version     (int ncid, int *nc_mode);
int ncmpi_inq_file_format (const char *filename, int *formatp);
int ncmpi_inq_path        (int ncid, int *pathlen, char *path);                 (1.8.0 and later)
int ncmpi_inq_striping    (int ncid, int *striping_size, int *striping_count);  (1.5.0 and later)
int ncmpi_inq_num_rec_vars(int ncid, int *num_rec_varsp);                       (1.6.0 and later)
int ncmpi_inq_num_fix_vars(int ncid, int *num_fix_varsp);                       (1.6.0 and later)
int ncmpi_inq_recsize     (int ncid, MPI_Offset *recsize);                      (1.6.0 and later)

ncid

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

ndimsp

Pointer to location for returned number of dimensions defined for this netCDF file.

nvarsp

Pointer to location for returned number of variables defined for this netCDF file.

ngattsp

Pointer to location for returned number of global attributes defined for this netCDF file.

unlimdimidp

Pointer to location for returned ID of the unlimited dimension, if there is one for this netCDF file. If no unlimited length dimension has been defined, -1 is returned.

formatp

Pointer to location for returned format version, one of the following constants define in the header file pnetcdf.h.

• NC_FORMAT_CLASSIC (CDF-1 format),
• NC_FORMAT_CDF2 (CDF-2 format),
• NC_FORMAT_64BIT_OFFSET (alias of NC_FORMAT_CDF2, also CDF-2 format),
• NC_FORMAT_64BIT(alias of NC_FORMAT_CDF2, also CDF-2 format),
• NC_FORMAT_CDF5 (CDF-5 format),
• NC_FORMAT_64BIT_DATA (alias of NC_FORMAT_CDF5, also CDF-5 format).
• NC_FORMAT_NETCDF4 (HDF-based NetCDF-4 format).
• NC_FORMAT_BP (BP format).

Note the names of the returned constants are different from the ones returned by ncmpi_inq_version().

nc_mode

Pointer to location for returned format version, one of NC_CLASSIC_MODEL, NC_64BIT_OFFSET, NC_64BIT_DATA, NC_NETCDF4, (NC_NETCDF4 | NC_CLASSIC_MODEL), and NC_BP. Note the names of the returned constants are different from the ones returned by ncmpi_inq_format().

filename

A char string specifies the name of file in inquiry.

path

Pointer where path name will be copied. Space must already be allocated. Ignored if NULL. ncmpi_inq_path can be used to obtain the file path name, given a ncid.

pathlen

Pointer where length of path will be returned. Ignored if NULL.

striping_size

File system striping size. This argument can be NULL.

striping_count

(version 1.5.0 and later) File system striping count. This argument can be NULL.

num_rec_varsp

(version 1.6.0, and later) Pointer to location for returned number of record variables defined for this netCDF file.

num_fix_varsp

(version 1.6.0, and later) Pointer to location for returned number of fixed-size variables defined for this netCDF file.

recsize

(version 1.6.0, and later) Pointer to location for returned size of record block, sum of individual record sizes (one record each) of all record variables, for this netCDF file.

Return Error Codes

All members of the ncmpi_inq family 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_ENOTNC3: The file is not a classic netCDF file, but an HDF file.
• NC_ENOTNC: The file is not a classic netCDF file.
• NC_ENOENT: The specified netCDF file does not exist.
• NC_EACCESS: Permission denied.
• NC_EBAD_FILE: Invalid file name.
• NC_EFILE: other unknown I/O error.

Example

Here is an example using ncmpi_inq to find out about a netCDF file named foo.nc:

#include <pnetcdf.h>
   ... 
int err, ncid, ndims, nvars, ngatts, unlimdimid;
   ... 
err = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL,  &ncid);
if (err != NC_NOERR) printf("Error: %s\n",ncmpi_strerror(err));
   ... 
err = ncmpi_inq(ncid, &ndims, &nvars, &ngatts, &unlimdimid);
if (err != NC_NOERR) printf("Error: %s\n",ncmpi_strerror(err));