Go to the previous, next section.

Get Information about a Variable from Its ID

The function ncvarinq (or NCVINQ for FORTRAN) returns information about a netCDF variable, given its ID. The information returned is the 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.

In case of an error, ncvarinq returns -1; NCVINQ returns a nonzero value in rcode. Possible causes of errors include:

• The variable ID is invalid for the specified netCDF file.

• The specified netCDF ID does not refer to an open netCDF file.

ncvarinq: C Interface

int ncvarinq(int ncid, int varid, char* name, nc_type* datatype,
             int* ndims, int dimids[], int* natts);

ncid

NetCDF ID, returned from a previous call to ncopen or nccreate.

varid

Variable ID, returned from a previous call to ncvardef or ncvarid.

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 MAX_NC_NAME. If the name parameter is given as `(char *) 0', no name will be returned so no space needs to be allocated.

datatype

Returned variable type, one of the set of predefined netCDF data types. The type of this parameter, nc_type, is defined in the netCDF header file. The valid netCDF data types are NC_BYTE, NC_CHAR, NC_SHORT, NC_LONG, NC_FLOAT, and NC_DOUBLE. If this parameter is given as `(nc_type *) 0', no type will be returned so no variable to hold the type needs to be declared.

ndims

Returned number of dimensions the variable was defined as using. For example, 2 specifies a matrix, 1 specifies a vector, and 0 means the variable is a scalar with no dimensions. If this parameter is given as `(int *) 0', no number of dimensions will be returned so no variable to hold this information needs to be declared.

dimids

Returned vector of ndims dimension IDs corresponding to the variable dimensions. The caller must allocate enough space for a vector of at least ndims integers to be returned. The maximum possible number of dimensions for a variable is given by the predefined constant MAX_VAR_DIMS. If this parameter is given as `(int *) 0', no vector will be returned so no space to hold the dimension IDs needs to be declared or allocated.

natts

Returned number of variable attributes assigned to this variable. If this parameter is given as `(int *) 0', the number of attributes will not be returned so no space to hold this information needs to be declared or allocated.

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

#include "netcdf.h"
   ...
int  ncid;                         /* netCDF ID */
int  rh_id;                        /* variable ID */
nc_type rh_type;                   /* variable type */
int rh_ndims;                      /* number of dims */
int  rh_dims[MAX_VAR_DIMS];        /* variable shape */
int rh_natts                       /* number of attributes */
   ...
ncid = ncopen ("foo.nc", NC_NOWRITE);
   ...
rh_id = ncvarid (ncid, "rh");
/* we don't need name, since we already know it */
ncvarinq (ncid, rh_id, (char *) 0, &rh_type, &rh_ndims, rh_dims,
          &rh_natts);

NCVINQ: FORTRAN Interface

      SUBROUTINE NCVINQ (INTEGER NCID, INTEGER VARID,
     +                   CHARACTER*(*) VARNAM, INTEGER VARTYP,
     +                   INTEGER NVDIMS, INTEGER VDIMS(*),
     +                   INTEGER NVATTS, INTEGER RCODE)

NCID

NetCDF ID, returned from a previous call to NCOPN or NCCRE.

VARID

Variable ID, returned from a previous call to NCVDEF or NCVID.

VARNAM

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 MAXNCNAM.

VARTYP

Returned variable type, one of the set of predefined netCDF data types. The valid netCDF data types are NCBYTE, NCCHAR, NCSHORT, NCLONG, NCFLOAT, and NCDOUBLE.

NVDIMS

Returned number of dimensions for the variable. For example, 2 specifies a matrix, 1 specifies a vector, and 0 means the variable is a scalar with no dimensions.

VDIMS

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

NVATTS

Returned number of variable attributes assigned to this variable.

RCODE

Returned error code. If no errors occurred, 0 is returned.

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

      INCLUDE 'netcdf.inc'
         ...
      INTEGER  NCID, RCODE
      INTEGER  RHID               ! variable ID
      CHARACTER*31 RHNAME         ! variable name
      INTEGER  RHTYPE             ! variable type
      INTEGER  RHN                ! number of dimensions
      INTEGER  RHDIMS(MAXVDIMS)   ! variable shape
      INTEGER  RHNATT             ! number of attributes
         ...
      NCID = NCOPN ('foo.nc', NCNOWRIT, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE)! get ID
      CALL NCVINQ (NCID, RHID, RHNAME, RHTYPE, RHN, RHDIMS, RHNATT,
     +             RCODE)

Go to the previous, next section.