4.3 Create a Variable: NF_DEF_VAR
The function NF_DEF_VAR adds a new variable to an open netCDF dataset
in define mode. It returns (as an argument) a variable ID, given the
netCDF ID, the variable name, the variable type, the number of
dimensions, and a list of the dimension IDs.
Usage
INTEGER FUNCTION NF_DEF_VAR(INTEGER NCID, CHARACTER*(*) NAME,
INTEGER XTYPE, INTEGER NVDIMS,
INTEGER VDIMS(*), INTEGER varid)
NCID
- NetCDF ID, from a previous call to NF_OPEN or NF_CREATE.
NAME
- Variable name. Must begin with an alphabetic character, followed by
zero or more alphanumeric characters including the underscore
('_'). Case is significant.
XTYPE
- One of the set of predefined netCDF external data types. The type of
this parameter, NF_TYPE, is defined in the netCDF header file. The
valid netCDF external data types are NF_BYTE, NF_CHAR, NF_SHORT,
NF_INT, NF_FLOAT, and NF_DOUBLE.
NVDIMS
- 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. Must not be negative or greater than the
predefined constant NF_MAX_VAR_DIMS.
VDIMS
- Vector of ndims dimension IDs corresponding to the variable
dimensions. If the ID of the unlimited dimension is included, it must
be last. This argument is ignored if ndims is 0.
varid
- Returned variable ID.
Errors
NF_DEF_VAR returns the value NF_NOERR if no errors
occurred. Otherwise, the returned status indicates an error. Possible
causes of errors include:
- The netCDF dataset is not in define mode.
- The specified variable name is the name of another existing variable.
- The specified type is not a valid netCDF type.
- The specified number of dimensions is negative or more than the
constant NF_MAX_VAR_DIMS, the maximum number of dimensions permitted
for a netCDF variable.
- One or more of the dimension IDs in the list of dimensions is not a
valid dimension ID for the netCDF dataset.
- The number of variables would exceed the constant NF_MAX_VARS, the
maximum number of variables permitted in a netCDF dataset.
- The specified netCDF ID does not refer to an open netCDF dataset.
Example
Here is an example using NF_DEF_VAR to create a variable named rh of
type double with three dimensions, time, lat, and lon in a new netCDF
dataset named foo.nc:
INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID
INTEGER LATDIM, LONDIM, TIMDIM ! dimension IDs
INTEGER RHID ! variable ID
INTEGER RHDIMS(3) ! variable shape
...
STATUS = NF_CREATE ('foo.nc', NF_NOCLOBBER, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
! define dimensions
STATUS = NF_DEF_DIM(NCID, 'lat', 5, LATDIM)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, 'lon', 10, LONDIM)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, 'time', NF_UNLIMITED, TIMDIM)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
! define variable
RHDIMS(1) = LONDIM
RHDIMS(2) = LATDIM
RHDIMS(3) = TIMDIM
STATUS = NF_DEF_VAR (NCID, 'rh', NF_DOUBLE, 3, RHDIMS, RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)