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)