Go to the previous, next section.

Dimensions

Dimensions for a netCDF file are defined when it is created, while the netCDF file is in define mode. Additional dimensions may be added later by reentering define mode. A netCDF dimension has a name and a size. At most one dimension in a netCDF file can have the NC_UNLIMITED size, which means a variable using this dimension can grow to any length (like a record number in a file).

There is a suggested limit (currently 32) to the number of dimensions that can be defined in a single netCDF file. The limit is the value of the predefined macro MAX_NC_DIMS (MAXNCDIM for FORTRAN). The purpose of the limit is to make writing generic applications simpler. They need only provide an array of MAX_NC_DIMS dimensions to handle any netCDF file. The implementation of the netCDF library does not enforce this advisory maximium, so it is possible to use more dimensions, if necessary; just don't expect generic applications or netCDF utilities to be able to handle the resulting netCDF files.

Ordinarily, the name and size of a dimension are fixed when the dimension is first defined. The name may be changed later, but the size of a dimension cannot be changed without copying the netCDF to a new netCDF with a redefined dimension size.

Dimension sizes in the C interface are type long rather than type int to make it possible to access all the data in a netCDF file on a platform that only supports a 16-bit int data types, for example MSDOS. If dimension sizes were type int instead, it would not be possible to access data from variables with a dimension size greater than a 16-bit int can accommodate.

Operations supported on dimensions are:

Create a dimension, given its name and size.
Get a dimension ID from its name.
Get a dimension's name and size from its ID.
Rename a dimension.

Create a Dimension

The function ncdimdef (or NCDDEF for FORTRAN) adds a new dimension to an open netCDF file in define mode. It returns a dimension ID, given the netCDF ID, the dimension name, and the dimension size. At most one unlimited size dimension, called the record dimension, may be defined for each netCDF file.

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

The netCDF file is not in definition mode.
The specified dimension name is the name of another existing dimension.
The specified size is not greater than zero.
The specified size is unlimited, but there is already an unlimited size dimension defined for this netCDF file.
The specified netCDF ID does not refer to an open netCDF file.

ncdimdef: C Interface

int ncdimdef(int ncid, const char* name, long size);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
name: Dimension name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant.
size: Size of dimension; that is, number of values for this dimension as an index to variables that use it. This should be either a positive integer (of type long) or the predefined constant NC_UNLIMITED.

Here is an example using ncdimdef to create a dimension named lat of size 18 and a record dimension named rec in a new netCDF file named `foo.nc':

#include "netcdf.h"
   ...
int ncid, latid, recid;
   ...
ncid = nccreate("foo.nc", NC_NOCLOBBER);
   ...
latid = ncdimdef(ncid, "lat", 18L);
recid = ncdimdef(ncid, "rec", NC_UNLIMITED);

NCDDEF: FORTRAN Interface

      INTEGER FUNCTION NCDDEF (INTEGER NCID,
     +                   CHARACTER*(*) DIMNAM,
     +                   INTEGER DIMSIZ,
     +                   INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
DIMNAM: Dimension name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant.
DIMSIZ: Size of dimension; that is, number of values for this dimension as an index to variables that use it. This should be either a positive integer or the predefined constant NCUNLIM.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCDDEF to create a dimension named lat of size 18 and a record dimension named rec in a new netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE, LATID, RECID
         ...
      NCID = NCCRE('foo.nc', NCNOCLOB, RCODE)
         ...
      LATID = NCDDEF(NCID, 'lat', 18, RCODE)
      RECID = NCDDEF(NCID, 'rec', NCUNLIM, RCODE)

Get a Dimension ID from Its Name

The function ncdimid (or NCDID for FORTRAN) returns the ID of a netCDF dimension, given the name of the dimension. If ndims is the number of dimensions defined for a netCDF file, each dimension has an ID between 0 and ndims-1 (or 1 and ndims for FORTRAN).

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

The name that was specified is not the name of any currently defined dimension in the netCDF file.
The specified netCDF ID does not refer to an open netCDF file.

ncdimid: C Interface

int ncdimid(int ncid, const char* name);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
name: Dimension name, a character string beginning with a letter and followed by any sequence of letters, digits, or underscore (`_') characters. Case is significant in dimension names.

Here is an example using ncdimid to determine the dimension ID of a dimension named lat, assumed to have been defined previously in an existing netCDF file named `foo.nc':

#include "netcdf.h"
   ...
int ncid, latid;
   ...
ncid = ncopen("foo.nc", NC_NOWRITE);  /* open for reading */
   ...
latid = ncdimid(ncid, "lat");

NCDID: FORTRAN Interface

      INTEGER FUNCTION NCDID (INTEGER NCID,
     +                        CHARACTER*(*) DIMNAME,
     +                        INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
DIMNAME: Dimension name, a character string beginning with a letter and followed by any sequence of letters, digits, or underscore (`_') characters. Case is significant in dimension names.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCDID to determine the dimension ID of a dimension named lat, assumed to have been defined previously in an existing netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE, LATID
         ...
      NCID = NCOPN('foo.nc', NCNOWRIT, RCODE)
         ...
      LATID = NCDID(NCID, 'lat', RCODE)

Inquire about a Dimension

The function ncdiminq (or NCDINQ for FORTRAN) returns the name and size of a dimension, given its ID. The size for the unlimited dimension, if any, is the maximum value used so far in writing data for that dimension (which is the same as the current maximum record number).

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

The dimension ID is invalid for the specified netCDF file.
The specified netCDF ID does not refer to an open netCDF file.

ncdiminq: C Interface

int ncdiminq(int ncid, int dimid, char* name, long* size);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
dimid: Dimension ID, as returned from a previous call to ncdimid or ncdimdef.
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 MAX_NC_NAME. If the name parameter is given as `(char *) 0', no name will be returned so no space needs to be allocated.
size: Returned size of dimension. For the unlimited dimension, this is the current maximum value used for writing any variables with this dimension, that is the maximum record number. If this parameter is given as `(long *) 0', the size will not be returned, so no space for this information need be declared or allocated.

Here is an example using ncdiminq to determine the size of a dimension named lat, and the name and current maximum size of the unlimited (or record) dimension for an existing netCDF file named `foo.nc':

#include "netcdf.h"
   ...
int ncid, latid, ndims, nvars, ngatts, recid;
long latsize, recs;
char recname[MAX_NC_NAME];
   ...
ncid = ncopen("foo.nc", NC_NOWRITE);  /* open for reading */
   ...
latid = ncdimid(ncid, "lat");
/* get lat size, but don't get name, since we already know it */
ncdiminq(ncid, latid, (char *) 0, &latsize);
/* get ID of record dimension (among other things) */
ncinquire(ncid, &ndims, &nvars, &ngatts, &recid);
/* get record dimension name and current size */
ncdiminq(ncid, recid, recname, &recs);

NCDINQ: FORTRAN Interface

      SUBROUTINE NCDINQ (INTEGER NCID, INTEGER DIMID,
     +                   CHARACTER*(*) DIMNAM, INTEGER DIMSIZ,
     +                   INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
DIMID: Dimension ID, as returned from a previous call to NCDID or NCDDEF.
DIMNAM: 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 MAXNCNAM.
DIMSIZ: Returned size of dimension. For the unlimited dimension, this is the current maximum value used for writing any variables with this dimension, that is the maximum record number.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCDINQ to determine the size of a dimension named lat, and the name and current maximum size of the unlimited (or record) dimension for an existing netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE, LATID, LATSIZ
      INTEGER NDIMS, NVARS, NGATTS, RECID, NRECS
* 31 in following statement is parameter MAXNCNAM
      CHARACTER*31 LATNAM, RECNAM
         ...
      NCID = NCOPN('foo.nc', NCNOWRIT, RCODE)
         ...
      LATID = NCDID(NCID, 'lat', RCODE)
* get lat name and size, (even though we already know name)
      CALL NCDINQ(NCID, LATID, LATNAM, LATSIZ, RCODE)
* get ID of record dimension (among other things)
      CALL NCINQ(NCID, NDIMS, NVARS, NGATTS, RECID, RCODE)
* get record dimension name and current size
      CALL NCDINQ(NCID, RECID, RECNAME, NRECS, RCODE)

Rename a Dimension

The function ncdimrename (or NCDREN for FORTRAN) renames an existing dimension in a netCDF file open for writing. If the new name is longer than the old name, the netCDF must be in define mode. You cannot rename a dimension to have the same name as another dimension.

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

The new name is the name of another dimension.
The dimension ID is invalid for the specified netCDF file.
The specified netCDF ID does not refer to an open netCDF file.

ncdimrename: C Interface

int ncdimrename(int ncid, int dimid, const char* name);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
dimid: Dimension ID, as returned from a previous call to ncdimid or ncdimdef.
name: New dimension name.

Here is an example using ncdimrename to rename the dimension lat to latitude in an existing netCDF file named `foo.nc':

#include "netcdf.h"
   ...
int ncid, latid;
   ...
ncid = ncopen("foo.nc", NC_WRITE);  /* open for writing */
   ...
ncredef(ncid);  /* put in define mode to rename dimension */
latid = ncdimid(ncid, "lat");
ncdimrename(ncid, latid, "latitude");
ncendef(ncid);  /* leave define mode */

NCDREN: FORTRAN Interface

      SUBROUTINE NCDREN (INTEGER NCID, INTEGER DIMID,
     +                   CHARACTER*(*) DIMNAME, INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
DIMID: Dimension ID, as returned from a previous call to NCDID or NCDDEF.
DIMNAM: New name for the dimension.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCDREN to rename the dimension "lat" to "latitude" in an existing netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE, LATID
         ...
      NCID = NCOPN('foo.nc', NCWRITE, RCODE)
         ...
* put in define mode to rename dimension
      CALL NCREDF(NCID, RCODE)
      LATID = NCDID(NCID, 'lat', RCODE)
      CALL NCDREN(NCID, LATID, 'latitude', RCODE)
* leave define mode
      CALL NCENDF(NCID, RCODE)

Go to the previous, next section.