[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page] [Unidata Home Page]
NetCDF User's Guide for FORTRAN
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 NF_MAX_DIMS
. The purpose of the limit is to make writing generic applications simpler. They need only provide an array of NF_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.
A netCDF dimension in an open netCDF dataset is referred to by a small integer called a dimension ID. In the FORTRAN interface, dimension IDs are 1, 2, 3, ..., in the order in which the dimensions were defined.
Operations supported on dimensions are:
NF_DEF_DIM
The function NF_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.
INTEGER FUNCTION NF_DEF_DIM (INTEGER NCID, CHARACTER*(*) NAME, INTEGER LEN, INTEGER dimid)
NF_DEF_DIM
returns the value NF_NOERR
if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF_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.inc' ... INTEGER STATUS, NCID, LATID, RECID ... STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ... STATUS = NF_DEF_DIM(NCID, 'lat', 18, LATID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) STATUS = NF_DEF_DIM(NCID, 'rec', NF_UNLIMITED, RECID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_INQ_DIMID
The function NF_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 1 and ndims.
INTEGER FUNCTION NF_INQ_DIMID (INTEGER NCID, CHARACTER*(*) NAME, INTEGER dimid)
| 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 (' |
| Returned dimension ID. |
NF_INQ_DIMID
returns the value NF_NOERR
if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF_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.inc' ... INTEGER STATUS, NCID, LATID ... STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ... STATUS = NF_INQ_DIMID(NCID, 'lat', LATID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_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 NF_INQ_DIM
, NF_INQ_DIMNAME
, and NF_INQ_DIMLEN
. The function NF_INQ_DIM
returns all the information about a dimension; the other functions each return just one item of information.
INTEGER FUNCTION NF_INQ_DIM (INTEGER NCID, INTEGER DIMID, CHARACTER*(*) name, INTEGER len) INTEGER FUNCTION NF_INQ_DIMNAME (INTEGER NCID, INTEGER DIMID, CHARACTER*(*) name) INTEGER FUNCTION NF_INQ_DIMLEN (INTEGER NCID, INTEGER DIMID, INTEGER len)
These functions return the value NF_NOERR
if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF_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.inc' ... INTEGER STATUS, NCID, LATID, LATLEN, RECID, NRECS CHARACTER*(NF_MAX_NAME) LATNAM, RECNAM ... STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ! get ID of unlimited dimension STATUS = NF_INQ_UNLIMDIM(NCID, RECID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ... STATUS = NF_INQ_DIMID(NCID, 'lat', LATID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ! get lat length STATUS = NF_INQ_DIMLEN(NCID, LATID, LATLEN) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ! get unlimited dimension name and current length STATUS = NF_INQ_DIM(NCID, RECID, RECNAME, NRECS) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_RENAME_DIM
The function NF_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.
INTEGER FUNCTION NF_RENAME_DIM (INTEGER NCID, INTEGER DIMID, CHARACTER*(*) NAME)
NCID | NetCDF ID, from a previous call to |
DIMID | Dimension ID, from a previous call to |
NAME | New name for the dimension. |
NF_RENAME_DIM
returns the value NF_NOERR
if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF_RENAME_DIM
to rename the dimension lat
to latitude
in an existing netCDF dataset named foo.nc
:
INCLUDE 'netcdf.inc' ... INTEGER STATUS, NCID, LATID ... STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ... ! put in define mode to rename dimension STATUS = NF_REDEF(NCID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) STATUS = NF_INQ_DIMID(NCID, 'lat', LATID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) STATUS = NF_RENAME_DIM(NCID, LATID, 'latitude') IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ! leave define mode STATUS = NF_ENDDEF(NCID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page] [Unidata Home Page]