[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page][Unidata Home Page]

NetCDF User's Guide for C

6 Dimensions

Dimensions for a netCDF dataset are defined when it is created, while the netCDF dataset is in define mode. Additional dimensions may be added later by reentering define mode. A netCDF dimension has a name and a length. At most one dimension in a netCDF dataset can have the unlimited length, which means variables using this dimension can grow along this dimension.

There is a suggested limit (100) to the number of dimensions that can be defined in a single netCDF dataset. The limit is the value of the predefined macro NC_MAX_DIMS. The purpose of the limit is to make writing generic applications simpler. They need only provide an array of NC_MAX_DIMS dimensions to handle any netCDF dataset. The implementation of the netCDF library does not enforce this advisory maximum, so it is possible to use more dimensions, if necessary, but netCDF utilities that assume the advisory maximums may not be able to handle the resulting netCDF datasets.

Ordinarily, the name and length of a dimension are fixed when the dimension is first defined. The name may be changed later, but the length of a dimension (other than the unlimited dimension) cannot be changed without copying all the data to a new netCDF dataset with a redefined dimension length.

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

A netCDF dimension in an open netCDF dataset is referred to by a small integer called a dimension ID. In the C interface, dimension IDs are 0, 1, 2, ..., in the order in which the dimensions were defined.

Operations supported on dimensions are:

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

6.1 Create a Dimension: `nc_def_dim`

The function nc_def_dim adds a new dimension to an open netCDF dataset in define mode. It returns (as an argument) a dimension ID, given the netCDF ID, the dimension name, and the dimension length. At most one unlimited length dimension, called the record dimension, may be defined for each netCDF dataset.

Usage

int nc_def_dim (int ncid, const char *name, size_t len, int *dimidp);
ncid NetCDF ID, from a previous call to nc_open or nc_create.

name Dimension name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ('_'). Case is significant.

len Length 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 size_t) or the predefined constant NC_UNLIMITED.

dimidp Pointer to location for returned dimension ID.

Errors

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

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

Example

Here is an example using nc_def_dim to create a dimension named lat of length 18 and a unlimited dimension named rec in a new netCDF dataset named foo.nc:

#include <netcdf.h>
   ... 
int status, ncid, latid, recid;
   ... 
status = nc_create("foo.nc", NC_NOCLOBBER, &ncid);
if (status != NC_NOERR) handle_error(status);
   ... 
status = nc_def_dim(ncid, "lat", 18L, &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_def_dim(ncid, "rec", NC_UNLIMITED, &recid);
if (status != NC_NOERR) handle_error(status);

6.2 Get a Dimension ID from Its Name: `nc_inq_dimid`

The function nc_inq_dimid returns (as an argument) the ID of a netCDF dimension, given the name of the dimension. If ndims is the number of dimensions defined for a netCDF dataset, each dimension has an ID between 0 and ndims-1.

Usage

int nc_inq_dimid (int ncid, const char *name, int *dimidp);
ncid NetCDF ID, from a previous call to nc_open or nc_create.

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.

dimidp Pointer to location for the returned dimension ID.

Errors

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

The name that was specified is not the name of a dimension in the netCDF dataset.
The specified netCDF ID does not refer to an open netCDF dataset.

Example

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

#include <netcdf.h>
   ... 
int status, ncid, latid;
   ... 
status = nc_open("foo.nc", NC_NOWRITE, &ncid);  /* open for reading */
if (status != NC_NOERR) handle_error(status);
   ... 
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);

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

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];
   ... 
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);

6.4 Rename a Dimension: `nc_rename_dim`

The function nc_rename_dim renames an existing dimension in a netCDF dataset open for writing. If the new name is longer than the old name, the netCDF dataset must be in define mode. You cannot rename a dimension to have the same name as another dimension.

Usage

int nc_rename_dim(int ncid, int dimid, const char* name);
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 New dimension name.

Errors

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

The new name is the name of another dimension.
The dimension ID is invalid for the specified netCDF dataset.
The specified netCDF ID does not refer to an open netCDF dataset.
The new name is longer than the old name and the netCDF dataset is not in define mode.

Example

Here is an example using nc_rename_dim to rename the dimension lat to latitude in an existing netCDF dataset named foo.nc:

#include <netcdf.h>
   ... 
int status, ncid, latid;
   ... 
status = nc_open("foo.nc", NC_WRITE, &ncid);  /* open for writing */
if (status != NC_NOERR) handle_error(status);
   ... 
status = nc_redef(ncid);  /* put in define mode to rename dimension */
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_rename_dim(ncid, latid, "latitude");
if (status != NC_NOERR) handle_error(status);
status = nc_enddef(ncid); /* leave define mode */
if (status != NC_NOERR) handle_error(status);

6.1 - Create a Dimension: nc_def_dim
Usage -
Example -
6.2 - Get a Dimension ID from Its Name: nc_inq_dimid
Usage -
Example -
6.3 - Inquire about a Dimension: nc_inq_dim Family
Usage -
Example -
6.4 - Rename a Dimension: nc_rename_dim
Usage -
Example -

NetCDF User's Guide for C - 5 JUN 1997

[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page][Unidata Home Page]

`ncid`	NetCDF ID, from a previous call to `nc_open` or `nc_create`.
`name`	Dimension name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ('`_`'). Case is significant.
`len`	Length 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 `size_t`) or the predefined constant `NC_UNLIMITED`.
`dimidp`	Pointer to location for returned dimension ID.

`ncid`	NetCDF ID, from a previous call to `nc_open` or `nc_create`.
`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.
`dimidp`	Pointer to location for the returned dimension ID.

`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`.
`lengthp`	Pointer to location for returned length of dimension. For the unlimited dimension, this is the number of records written so far.

`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`	New dimension name.

6 Dimensions

6.1 Create a Dimension: nc_def_dim

Usage

Example

6.2 Get a Dimension ID from Its Name: nc_inq_dimid

Usage

Example

6.3 Inquire about a Dimension: nc_inq_dim Family

Usage

Example

6.4 Rename a Dimension: nc_rename_dim

Usage

Example

6.1 Create a Dimension: `nc_def_dim`

6.2 Get a Dimension ID from Its Name: `nc_inq_dimid`

6.3 Inquire about a Dimension: `nc_inq_dim` Family

6.4 Rename a Dimension: `nc_rename_dim`