| • |
|
|
|
|||
|
||||
[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page] [Unidata Home Page]
NetCDF User's Guide for C
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:
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.
int nc_def_dim (int ncid, const char *name, size_t len, int *dimidp);
nc_def_dim returns the value NC_NOERR
if no errors occurred. Otherwise, the returned
status indicates an error. Possible causes of errors include:
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);
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.
int nc_inq_dimid (int ncid, const char *name, int *dimidp);
|
NetCDF ID, from a previous call to |
|
Dimension name, a character string beginning with a letter and followed
by any sequence of letters, digits, or underscore (' |
|
Pointer to location for the returned dimension ID. |
nc_inq_dimid returns the value NC_NOERR
if no errors occurred. Otherwise, the returned
status indicates an error. Possible causes of errors include:
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);
nc_inq_dim
FamilyThis 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.
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);
These functions return the value NC_NOERR if
no errors occurred. Otherwise, the returned status indicates an error. Possible
causes of errors include:
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);
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.
int nc_rename_dim(int ncid, int dimid, const char* name);
|
NetCDF ID, from a previous call to |
|
Dimension ID, from a previous call to |
|
New dimension name. |
nc_rename_dim returns the value NC_NOERR
if no errors occurred. Otherwise, the returned
status indicates an error. Possible causes of errors include:
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);
[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page] [Unidata Home Page]
| Contact Us • Site Map • Search • Terms and Conditions • Privacy Policy • Participation Policy | ||||||
|
||||||
