NetCDF User's Guide for Fortran
Ordinarily, the name, type, and shape are fixed when the variable is first defined. The name may be changed, but the type and shape of a variable cannot be changed. However, a variable defined in terms of the unlimited dimension can grow without bound in that dimension.
A netCDF variable in an open netCDF dataset is referred to by a small integer called a variable ID.
Variable IDs reflect the order in which variables were defined within a netCDF dataset. Variable IDs are 1, 2, 3,..., in the order in which the variables were defined. A function is available for getting the variable ID from the variable name and vice-versa.
Attributes (see Chapter 8 "Attributes," page 81) may be associated with a variable to specify such properties as units.
Operations supported on variables are:
| netCDF/CDL Data Type | FORTRAN API Mnemonic | Bits |
|---|---|---|
byte | NF_BYTE | 8 |
char | NF_CHAR | 8 |
short | NF_SHORT | 16 |
int | NF_INT | 32 |
float | NF_FLOAT | 32 |
double | NF_DOUBLE | 64 |
The first column gives the netCDF external data type, which is the same as the CDL data type. The next column gives the corresponding FORTRAN parameter for use in netCDF functions (the parameters are defined in the netCDF FORTRAN include-file netcdf.inc). The last column gives the number of bits used in the external representation of values of the corresponding type.
Note that there are no netCDF types corresponding to 64-bit integers or to characters wider than 8 bits in the current version of the netCDF library.
NF_DEF_VAR 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.
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 | Name for this variable. Must begin with an alphabetic character, which is followed by zero or more alphanumeric characters including the underscore ('_'). Case is significant. |
XTYPE | The external type for this variable, one of the set of predefined netCDF external data types: NF_BYTE, NF_CHAR, NF_SHORT, NF_INT, NF_FLOAT, or NF_DOUBLE. |
NVDIMS | Number of dimensions for this 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 NVDIMS dimension IDs corresponding to this variable's dimensions. If the ID of the unlimited dimension is included, it must be last. This argument is ignored if NVDIMS is 0. |
varid | Returned variable ID |
NF_DEF_VAR returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_MAX_VAR_DIMS, the maximum number of dimensions permitted for a netCDF variable.
NF_MAX_VARS, the maximum number of variables permitted in a netCDF dataset.
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)
NF_INQ_VARID NF_INQ_VARID returns the ID of a netCDF variable, given its name.
INTEGER FUNCTION NF_INQ_VARID(INTEGER NCID, CHARACTER*(*) NAME,
INTEGER varid)
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
NAME | Variable name for which ID is desired. |
varid | Returned variable ID. |
NF_INQ_VARID returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_INQ_VARID to find out the ID of a variable named rh in an existing netCDF dataset named foo.nc:
INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID, RHID
...
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_INQ_VAR family
The function NF_INQ_VAR returns all the information about a netCDF variable, given its ID. The other functions each return just one item of information about a variable.
These other functions include NF_INQ_VARNAME, NF_INQ_VARTYPE, NF_INQ_VARNDIMS, NF_INQ_VARDIMID, and NF_INQ_VARNATTS.
INTEGER FUNCTION NF_INQ_VAR (INTEGER NCID, INTEGER VARID,
CHARACTER*(*) name, INTEGER xtype,
INTEGER ndims, INTEGER dimids(*),
INTEGER natts)
INTEGER FUNCTION NF_INQ_VARNAME (INTEGER NCID, INTEGER VARID,
CHARACTER*(*) name)
INTEGER FUNCTION NF_INQ_VARTYPE (INTEGER NCID, INTEGER VARID,
INTEGER xtype)
INTEGER FUNCTION NF_INQ_VARNDIMS (INTEGER NCID, INTEGER VARID,
INTEGER ndims)
INTEGER FUNCTION NF_INQ_VARDIMID (INTEGER NCID, INTEGER VARID,
INTEGER dimids(*))
INTEGER FUNCTION NF_INQ_VARNATTS (INTEGER NCID, INTEGER VARID,
INTEGER natts)
These functions return the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_INQ_VAR to find out about a variable named rh in an existing netCDF dataset named foo.nc:
INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
CHARACTER*31 RHNAME ! variable name
INTEGER RHTYPE ! variable type
INTEGER RHN ! number of dimensions
INTEGER RHDIMS(NF_MAX_VAR_DIMS) ! variable shape
INTEGER RHNATT ! number of attributes
...
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VAR (NCID, RHID, RHNAME, RHTYPE, RHN, RHDIMS, RHNATT)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_PUT_VAR1_type NF_PUT_VAR1_type put a single data value of the specified type into a variable of an open netCDF dataset that is in data mode. Inputs are the netCDF ID, the variable ID, an index that specifies which value to add or alter, and the data value. The value is converted to the external data type of the variable, if necessary.
INTEGER FUNCTION NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), CHARACTER CHVAL)
INTEGER FUNCTION NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), INTEGER*1 I1VAL)
INTEGER FUNCTION NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), INTEGER*2 I2VAL)
INTEGER FUNCTION NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), INTEGER IVAL)
INTEGER FUNCTION NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), REAL RVAL)
INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), DOUBLE DVAL)
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
INDEX | The index of the data value to be written. The indices are relative to 1, so for example, the first data value of a two-dimensional variable would have index (1,1). The elements of index must correspond to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the record number. |
CHVAL, I1VAL, I2VAL, IVAL, RVAL, or DVAL | The data value to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 24, for details. |
NF_PUT_VAR1_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_PUT_VAR1_DOUBLE to set the (4,3,2) element of the variable named rh to 0.5 in an existing netCDF dataset named foo.nc. For simplicity in this example, we assume that we know that rh is dimensioned with lon, lat, and time, so we want to set the value of rh that corresponds to the fourth lon value, the third lat value, and the second time value:
INCLUDE 'netcdf.inc'
...
INTEGER STATUS ! error status
INTEGER NCID
INTEGER RHID ! variable ID
INTEGER RHINDX(3) ! where to put value
DATA RHINDX /4, 3, 2/
...
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_PUT_VAR1_DOUBLE (NCID, RHID, RHINDX, 0.5)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_PUT_VAR_type NF_PUT_VAR_type family of functions write all the values of a variable into a netCDF variable of an open netCDF dataset. This is the simplest interface to use for writing a value in a scalar variable or whenever all the values of a multidimensional variable can all be written at once. The values to be written are associated with the netCDF variable by assuming that the first dimension of the netCDF variable varies fastest in the FORTRAN interface. The values are converted to the external data type of the variable, if necessary.
INTEGER FUNCTION NF_PUT_VAR_TEXT (INTEGER NCID, INTEGER VARID,
CHARACTER*(*) TEXT)
INTEGER FUNCTION NF_PUT_VAR_INT1 (INTEGER NCID, INTEGER VARID,
INTEGER*1 I1VALS(*))
INTEGER FUNCTION NF_PUT_VAR_INT2 (INTEGER NCID, INTEGER VARID,
INTEGER*2 I2VALS(*))
INTEGER FUNCTION NF_PUT_VAR_INT (INTEGER NCID, INTEGER VARID,
INTEGER IVALS(*))
INTEGER FUNCTION NF_PUT_VAR_REAL (INTEGER NCID, INTEGER VARID,
REAL RVALS(*))
INTEGER FUNCTION NF_PUT_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
DOUBLE DVALS(*))
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
TEXT, I1VALS,
I2VALS, IVALS,RVALS, or DVALS | The block of data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). The order in which the data will be written into the specified variable is with the first dimension varying fastest (like the ordinary FORTRAN convention). |
Members of the NF_PUT_VAR_type family return the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_PUT_VAR_DOUBLE to add or change all the values of the variable named rh to 0.5 in an existing netCDF dataset named foo.nc. For simplicity in this example, we assume that we know that rh is dimensioned with lon, lat, and time, and that there are ten lon values, five lat values, and three time values.
INCLUDE 'netcdf.inc'
...
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID, TIMES
INTEGER RHID ! variable ID
DOUBLE RHVALS(LONS, LATS, TIMES)
...
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
DO 10 ILON = 1, LONS
DO 10 ILAT = 1, LATS
DO 10 ITIME = 1, TIMES
RHVALS(ILON, ILAT, ITIME) = 0.5
10 CONTINUE
STATUS = NF_PUT_var_DOUBLE (NCID, RHID, RHVALS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_PUT_VARA_type NF_PUT_VARA_type writes values into a netCDF variable of an open netCDF dataset. The part of the netCDF variable to write is specified by giving a corner and a vector of edge lengths that refer to an array section of the netCDF variable. The values to be written are associated with the netCDF variable by assuming that the first dimension of the netCDF variable varies fastest in the FORTRAN interface. The netCDF dataset must be in data mode.
INTEGER FUNCTION NF_PUT_VARA_TEXT(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
CHARACTER*(*) TEXT)
INTEGER FUNCTION NF_PUT_VARA_INT1(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER*1 I1VALS(*))
INTEGER FUNCTION NF_PUT_VARA_INT2(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER*2 I2VALS(*))
INTEGER FUNCTION NF_PUT_VARA_INT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER IVALS(*))
INTEGER FUNCTION NF_PUT_VARA_REAL(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
REAL RVALS(*))
INTEGER FUNCTION NF_PUT_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
DOUBLE DVALS(*))
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
START | A vector of integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 1, so for example, the first data value of a variable would have index (1, 1, ..., 1). The length of START must be the same as the number of dimensions of the specified variable. The elements of START must correspond to the variable's dimensions in order. Hence, if the variable is a record variable, the last index would correspond to the starting record number for writing the data values. |
COUNT | A vector of integers specifying the edge lengths along each dimension of the block of data values to written. To write a single value, for example, specify COUNT as (1, 1, ..., 1). The length of COUNT is the number of dimensions of the specified variable. The elements of COUNT correspond to the variable's dimensions. Hence, if the variable is a record variable, the last element of COUNT corresponds to a count of the number of records to write. |
TEXT, I1VALS,
I2VALS, IVALS,RVALS, or DVALS | The block of data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). |
NF_PUT_VARA_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_PUT_VARA_DOUBLE to add or change all the values of the variable named rh to 0.5 in an existing netCDF dataset named foo.nc. For simplicity in this example, we assume that we know that rh is dimensioned with lon, lat, and time, and that there are ten lon values, five lat values, and three time values.
INCLUDE 'netcdf.inc'
...
PARAMETER (NDIMS=3) ! number of dimensions
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID, TIMES
INTEGER RHID ! variable ID
INTEGER START(NDIMS), COUNT(NDIMS)
DOUBLE RHVALS(LONS, LATS, TIMES)
DATA START /1, 1, 1/ ! start at first value
DATA COUNT /LONS, LATS, TIMES/
...
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
DO 10 ILON = 1, LONS
DO 10 ILAT = 1, LATS
DO 10 ITIME = 1, TIMES
RHVALS(ILON, ILAT, ITIME) = 0.5
10 CONTINUE
STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_PUT_VARS_type NF_PUT_VARS_type writes a subsampled (strided) array section of values into a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of counts, and a stride vector. The netCDF dataset must be in data mode.
INTEGER FUNCTION NF_PUT_VARS_TEXT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*),CHARACTER*(*) TEXT)
INTEGER FUNCTION NF_PUT_VARS_INT1 (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*),INTEGER*1 I1VALS(*))
INTEGER FUNCTION NF_PUT_VARS_INT2 (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*),INTEGER*2 I2VALS(*))
INTEGER FUNCTION NF_PUT_VARS_INT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IVALS(*))
INTEGER FUNCTION NF_PUT_VARS_REAL (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), REAL RVALS(*))
INTEGER FUNCTION NF_PUT_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), DOUBLE DVALS(*))
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
START | A vector of integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 1, so for example, the first data value of a variable would have index (1, 1, ..., 1). The elements of START correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for writing the data values. |
COUNT | A vector of integers specifying the number of indices selected along each dimension. To write a single value, for example, specify COUNT as (1, 1, ..., 1). The elements of COUNT correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of COUNT corresponds to a count of the number of records to write. |
STRIDE | A vector of integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (STRIDE(1) gives the sampling interval along the most rapidly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.). |
TEXT, I1VALS,
I2VALS, IVALS,RVALS, or DVALS | The block of data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). |
NF_PUT_VARS_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_PUT_VARS_REAL to write -- from an internal array -- every other point of a netCDF variable named rh which is described by the FORTRAN declaration REAL RH(6,4) (note the size of the dimensions):
INCLUDE 'netcdf.inc'
...
PARAMETER (NDIM=2) ! rank of netCDF variable
INTEGER NCID ! netCDF dataset ID
INTEGER STATUS ! return code
INTEGER RHID ! variable ID
INTEGER START(NDIM) ! netCDF variable start point
INTEGER COUNT(NDIM) ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
REAL RH(3,2) ! note subsampled sizes for netCDF variable
! dimensions
DATA START /1, 1/ ! start at first netCDF variable value
DATA COUNT /3, 2/ ! size of internal array: entire (subsampled)
! netCDF variable
DATA STRIDE /2, 2/ ! access every other netCDF element
...
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_PUT_VARS_REAL(NCID, RHID, START, COUNT, STRIDE, RH)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_PUT_VARM_type NF_PUT_VARM_type family of functions writes a mapped array section of values into a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of counts, a stride vector, and an index mapping vector. The index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array. The netCDF dataset must be in data mode.
INTEGER FUNCTION NF _PUT_VARM_TEXT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
CHARACTER*(*) TEXT)
INTEGER FUNCTION NF _PUT_VARM_INT1 (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
INTEGER*1 I1VALS(*))
INTEGER FUNCTION NF _PUT_VARM_INT2 (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
INTEGER*2 I2VALS(*))
INTEGER FUNCTION NF _PUT_VARM_INT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
INTEGER IVALS(*))
INTEGER FUNCTION NF _PUT_VARM_REAL (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
REAL RVALS(*))
INTEGER FUNCTION NF _PUT_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
DOUBLE DVALS(*))
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
START | A vector of integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 1, so for example, the first data value of a variable would have index (1, 1, ..., 1). The elements of START correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for writing the data values. |
COUNT | A vector of integers specifying the number of indices selected along each dimension. To write a single value, for example, specify COUNT as (1, 1, ..., 1). The elements of COUNT correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of COUNT corresponds to a count of the number of records to write. |
STRIDE | A vector of integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (STRIDE(1) gives the sampling interval along the most rapidly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.). |
IMAP | A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. The elements of the index mapping vector correspond, in order, to the netCDF variable's dimensions (IMAP(1) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable). Distances between elements are specified in units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element's byte-length as in netCDF 2). |
TEXT, I1VALS,
I2VALS, IVALS,RVALS, or DVALS | The data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). |
NF_PUT_VARM_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
START, COUNT, and STRIDE generate an index which is out of range. Note that no error checking is possible on the IMAP vector.
IMAP vector maps in the trivial way a 2x3x4 netCDF variable and an internal array of the same shape:
REAL A(2,3,4) ! same shape as netCDF variable
INTEGER IMAP(3)
DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
! ---------------- ----------------------
! most rapidly varying 1
! intermediate 2 (=IMAP(1)*2)
! most slowly varying 6 (=IMAP(2)*3)
Using the IMAP vector above with NF_PUT_VARM_REAL obtains the same result as simply using NF_PUT_VAR_REAL.
Here is an example of using NF_PUT_VARM_REAL to write -- from a transposed, internal array -- a netCDF variable named rh which is described by the FORTRAN declaration REAL RH(4,6) (note the size and order of the dimensions):
INCLUDE 'netcdf.inc'
...
PARAMETER (NDIM=2) ! rank of netCDF variable
INTEGER NCID ! netCDF ID
INTEGER STATUS ! return code
INTEGER RHID ! variable ID
INTEGER START(NDIM) ! netCDF variable start point
INTEGER COUNT(NDIM) ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
INTEGER IMAP(NDIM) ! internal array inter-element distances
REAL RH(6,4) ! note transposition of netCDF variable dimensions
DATA START /1, 1/ ! start at first netCDF variable element
DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
! to netCDF variable -- not internal array
DATA STRIDE /1, 1/ ! sample every netCDF element
DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
Here is another example of using NF_PUT_VARM_REAL to write -- from a transposed, internal array -- a subsample of the same netCDF variable, by writing every other point of the netCDF variable:
INCLUDE 'netcdf.inc'
...
PARAMETER (NDIM=2) ! rank of netCDF variable
INTEGER NCID ! netCDF dataset ID
INTEGER STATUS ! return code
INTEGER RHID ! variable ID
INTEGER START(NDIM) ! netCDF variable start point
INTEGER COUNT(NDIM) ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
INTEGER IMAP(NDIM) ! internal array inter-element distances
REAL RH(3,2) ! note transposition of (subsampled) dimensions
DATA START /1, 1/ ! start at first netCDF variable value
DATA COUNT /2, 3/ ! order of (subsampled) dimensions corresponds
! to netCDF variable -- not internal array
DATA STRIDE /2, 2/ ! sample every other netCDF element
DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
...
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_GET_VAR1_type NF_GET_VAR1_type get a single data value from a variable of an open netCDF dataset that is in data mode. Inputs are the netCDF ID, the variable ID, a multidimensional index that specifies which value to get, and the address of a location into which the data value will be read. The value is converted from the external data type of the variable, if necessary.
INTEGER FUNCTION NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), CHARACTER chval)
INTEGER FUNCTION NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), INTEGER*1 i1val)
INTEGER FUNCTION NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), INTEGER*2 i2val)
INTEGER FUNCTION NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), INTEGER ival)
INTEGER FUNCTION NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), REAL rval)
INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
INTEGER INDEX(*), DOUBLE dval)
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
INDEX | The index of the data value to be read. The indices are relative to 1, so for example, the first data value of a two-dimensional variable has index (1,1). The elements of index correspond to the variable's dimensions. Hence, if the variable is a record variable, the last index is the record number. |
chval, i1val, i2val, ival, rval, or dval
| The location into which the data value will be read. You cannot get CHARACTER data from a numeric variable or numeric data from a character variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 24, for details.
|
NF_GET_VAR1_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_GET_VAR1_DOUBLE to get the (4,3,2) element of the variable named rh in an existing netCDF dataset named foo.nc. For simplicity in this example, we assume that we know that rh is dimensioned with lon, lat, and time, so we want to get the value of rh that corresponds to the fourth lon value, the third lat value, and the second time value:
INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
INTEGER RHINDX(3) ! where to get value
DOUBLE PRECISION RHVAL ! put it here
DATA RHINDX /4, 3, 2/
...
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VAR1_DOUBLE (NCID, RHID, RHINDX, RHVAL)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_GET_VAR_type NF_GET_VAR_type family of functions read all the values from a netCDF variable of an open netCDF dataset. This is the simplest interface to use for reading the value of a scalar variable or when all the values of a multidimensional variable can be read at once. The values are read into consecutive locations with the first dimension varying fastest. The netCDF dataset must be in data mode.
INTEGER FUNCTION NF_GET_VAR_TEXT (INTEGER NCID, INTEGER VARID,
CHARACTER*(*) text)
INTEGER FUNCTION NF_GET_VAR_INT1 (INTEGER NCID, INTEGER VARID,
INTEGER*1 i1vals(*))
INTEGER FUNCTION NF_GET_VAR_INT2 (INTEGER NCID, INTEGER VARID,
INTEGER*2 i2vals(*))
INTEGER FUNCTION NF_GET_VAR_INT (INTEGER NCID, INTEGER VARID,
INTEGER ivals(*))
INTEGER FUNCTION NF_GET_VAR_REAL (INTEGER NCID, INTEGER VARID,
REAL rvals(*))
INTEGER FUNCTION NF_GET_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
DOUBLE dvals(*))
There are six FORTRAN functions for reading an array of values from a netCDF variable.
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
text, i1vals, | The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). |
Errors
NF_GET_VAR_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_GET_VAR_DOUBLE to read all the values of the variable named rh from an existing netCDF dataset named foo.nc. For simplicity in this example, we assume that we know that rh is dimensioned with lon, lat, and time, and that there are ten lon values, five lat values, and three time values.
INCLUDE 'netcdf.inc'
...
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
DOUBLE RHVALS(LONS, LATS, TIMES)
...
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VAR_DOUBLE (NCID, RHID, RHVALS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_GET_VARA_type NF_GET_VARA_type family of functions read an array of values from a netCDF variable of an open netCDF dataset. The array is specified by giving a corner and a vector of edge lengths. The values are read into consecutive locations with the first dimension varying fastest. The netCDF dataset must be in data mode.
INTEGER FUNCTION NF_GET_VARA_TEXT(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
CHARACTER*(*) text)
INTEGER FUNCTION NF_GET_VARA_INT1(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER*1 i1vals(*))
INTEGER FUNCTION NF_GET_VARA_INT2(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER*2 i2vals(*))
INTEGER FUNCTION NF_GET_VARA_INT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER ivals(*))
INTEGER FUNCTION NF_GET_VARA_REAL(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
REAL rvals(*))
INTEGER FUNCTION NF_GET_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
DOUBLE dvals(*))
There are six FORTRAN functions for reading an array of values from a netCDF variable.
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
START | A vector of integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 1, so for example, the first data value of a variable would have index (1, 1, ..., 1). The length of START must be the same as the number of dimensions of the specified variable. The elements of START correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for reading the data values. |
COUNT | A vector of integers specifying the edge lengths along each dimension of the block of data values to be read. To read a single value, for example, specify COUNT as (1, 1, ..., 1). The length of COUNT is the number of dimensions of the specified variable. The elements of COUNT correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of COUNT corresponds to a count of the number of records to read. |
text, i1vals, | The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). |
Errors
NF_GET_VARA_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_GET_VARA_DOUBLE to read all the values of the variable named rh from an existing netCDF dataset named foo.nc. For simplicity in this example, we assume that we know that rh is dimensioned with lon, lat, and time, and that there are ten lon values, five lat values, and three time values.
INCLUDE 'netcdf.inc'
...
PARAMETER (NDIMS=3) ! number of dimensions
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
INTEGER START(NDIMS), COUNT(NDIMS)
DOUBLE RHVALS(LONS, LATS, TIMES)
DATA START /1, 1, 1/ ! start at first value
DATA COUNT /LONS, LATS, TIMES/ ! get all the values
...
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_GET_VARS_type NF_GET_VARS_type family of functions read a subsampled (strided) array section of values from a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of edge lengths, and a stride vector. The values are read with the first dimension of the netCDF variable varying fastest. The netCDF dataset must be in data mode.
INTEGER FUNCTION NF_GET_VARS_TEXT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*),CHARACTER*(*) text)
INTEGER FUNCTION NF_GET_VARS_INT1 (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*),INTEGER*1 i1vals(*))
INTEGER FUNCTION NF_GET_VARS_INT2 (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*),INTEGER*2 i2vals(*))
INTEGER FUNCTION NF_GET_VARS_INT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER ivals(*))
INTEGER FUNCTION NF_GET_VARS_REAL (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), REAL rvals(*))
INTEGER FUNCTION NF_GET_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), DOUBLE dvals(*))
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
START | A vector of integers specifying the index in the variable from which the first of the data values will be read. The indices are relative to 1, so for example, the first data value of a variable would have index (1, 1, ..., 1). The elements of START correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for reading the data values. |
COUNT | A vector of integers specifying the number of indices selected along each dimension. To read a single value, for example, specify COUNT as (1, 1, ..., 1). The elements of COUNT correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of COUNT corresponds to a count of the number of records to read. |
STRIDE | A vector of integers specifying, for each dimension, the interval between selected indices or the value 0. The elements of the vector correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A 0 argument is treated as (1, 1, ..., 1). |
text, i1vals,
i2vals, ivals,rvals, or dvals | The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). |
NF_GET_VARS_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_GET_VARS_DOUBLE to read every other value in each dimension of the variable named rh from an existing netCDF dataset named foo.nc. Values are assigned, using the same dimensional strides, to a 2-parameter array. For simplicity in this example, we assume that we know that rh is dimensioned with lon, lat, and time, and that there are ten lon values, five lat values, and three time values.
INCLUDE 'netcdf.inc'
...
PARAMETER (NDIMS=3) ! number of dimensions
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
DOUBLE DATA(LONS, LATS, TIMES)
DATA START /1, 1, 1/ ! start at first value
DATA COUNT /LONS, LATS, TIMES/
DATA STRIDE /2, 2, 2/
...
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_GET_VARM_type NF_GET_VARM_type family of functions reads a mapped array section of values from a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of edge lengths, a stride vector, and an index mapping vector. The index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array. The netCDF dataset must be in data mode.
INTEGER FUNCTION NF _GET_VARM_TEXT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
CHARACTER*(*) text)
INTEGER FUNCTION NF _GET_VARM_INT1 (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
INTEGER*1 i1vals(*))
INTEGER FUNCTION NF _GET_VARM_INT2 (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
INTEGER*2 i2vals(*))
INTEGER FUNCTION NF _GET_VARM_INT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
INTEGER ivals(*))
INTEGER FUNCTION NF _GET_VARM_REAL (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
REAL rvals(*))
INTEGER FUNCTION NF _GET_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER STRIDE(*), INTEGER IMAP(*),
DOUBLE dvals(*))
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
START | A vector of integers specifying the index in the variable from which the first of the data values will be read. The indices are relative to 1, so for example, the first data value of a variable would have index (1, 1, ..., 1). The elements of START correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for reading the data values. |
COUNT | A vector of integers specifying the number of indices selected along each dimension. To read a single value, for example, specify COUNT as (1, 1, ..., 1). The elements of COUNT correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of COUNT corresponds to a count of the number of records to read. |
STRIDE | A vector of integers specifying, for each dimension, the interval between selected indices or the value 0. The elements of the vector correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A 0 argument is treated as (1, 1, ..., 1). |
IMAP | A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. IMAP(1) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable. IMAP(N) (where N is the rank of the netCDF variable) gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable. Intervening IMAP elements correspond to other dimensions of the netCDF variable in the obvious way. Distances between elements are specified in units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element's byte-length as in netCDF 2). |
text, i1vals,
i2vals, ivals,rvals, or dvals | The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). |
NF_GET_VARM_type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
START, COUNT, and STRIDE generate an index which is out of range. Note that no error checking is possible on the IMAP vector.
IMAP vector maps in the trivial way a 2x3x4 netCDF variable and an internal array of the same shape:
REAL A(2,3,4) ! same shape as netCDF variable
INTEGER IMAP(3)
DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
! ---------------- ----------------------
! most rapidly varying 1
! intermediate 2 (=IMAP(1)*2)
! most slowly varying 6 (=IMAP(2)*3)
Using the IMAP vector above with NF_GET_VARM_REAL obtains the same result as simply using NF_GET_VAR_REAL.
Here is an example of using NF_GET_VARM_REAL to transpose a netCDF variable named rh which is described by the FORTRAN declaration REAL RH(4,6) (note the size and order of the dimensions):
INCLUDE 'netcdf.inc'
...
PARAMETER (NDIM=2) ! rank of netCDF variable
INTEGER NCID ! netCDF dataset ID
INTEGER STATUS ! return code
INTEGER RHID ! variable ID
INTEGER START(NDIM) ! netCDF variable start point
INTEGER COUNT(NDIM) ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
INTEGER IMAP(NDIM) ! internal array inter-element distances
REAL RH(6,4) ! note transposition of netCDF variable dimensions
DATA START /1, 1/ ! start at first netCDF variable element
DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
! to netCDF variable -- not internal array
DATA STRIDE /1, 1/ ! sample every netCDF element
DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
...
STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
Here is another example of using NF_GET_VARM_REAL to simultaneously transpose and subsample the same netCDF variable, by accessing every other point of the netCDF variable:
INCLUDE 'netcdf.inc'
...
PARAMETER (NDIM=2) ! rank of netCDF variable
INTEGER NCID ! netCDF dataset ID
INTEGER STATUS ! return code
INTEGER RHID ! variable ID
INTEGER START(NDIM) ! netCDF variable start point
INTEGER COUNT(NDIM) ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
INTEGER IMAP(NDIM) ! internal array inter-element distances
REAL RH(3,2) ! note transposition of (subsampled) dimensions
DATA START /1, 1/ ! start at first netCDF variable value
DATA COUNT /2, 3/ ! order of (subsampled) dimensions corresponds
! to netCDF variable -- not internal array
DATA STRIDE /2, 2/ ! sample every other netCDF element
DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
...
STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
LEN function returns the static length of a character string, not its dynamic length). As a result, a character string cannot be written or read as a single object in the netCDF interface. Instead, a character string must be treated as an array of characters, and array access must be used to read and write character strings as variable data in netCDF datasets. Furthermore, variable-length strings are not supported by the netCDF interface except by convention; for example, you may treat a zero byte as terminating a character string, but you must explicitly specify the length of strings to be read from and written to netCDF variables. Character strings as attribute values are easier to use, since the strings are treated as a single unit for access. However, the value of a character-string attribute is still an array of characters with an explicit length that must be specified when the attribute is defined.
When you define a variable that will have character-string values, use a character-position dimension as the most quickly varying dimension for the variable (the first dimension for the variable in FORTRAN). The length of the character-position dimension will be the maximum string length of any value to be stored in the character-string variable. Space for maximum-length strings will be allocated in the disk representation of character-string variables whether you use the space or not. If two or more variables have the same maximum length, the same character-position dimension may be used in defining the variable shapes.
To write a character-string value into a character-string variable, use either entire variable access or array access. The latter requires that you specify both a corner and a vector of edge lengths. The character-position dimension at the corner should be one for FORTRAN. If the length of the string to be written is n, then the vector of edge lengths will specify n in the character-position dimension, and one for all the other dimensions:(n, 1, 1, ..., 1).
In FORTRAN, fixed-length strings may be written to a netCDF dataset without a terminating character, to save space. Variable-length strings should follow the C convention of writing strings with a terminating zero byte so that the intended length of the string can be determined when it is later read by either C or FORTRAN programs.
The FORTRAN interface for reading and writing strings requires the use of different functions for accessing string values and numeric values, because standard FORTRAN does not permit the same formal parameter to be used for both character values and numeric values. An additional argument, specifying the declared length of the character string passed as a value, is required for NF_PUT_VARA_TEXT and NF_GET_VARA_TEXT. The actual length of the string is specified as the value of the edge-length vector corresponding to the character-position dimension.
Here is an example that defines a record variable, tx, for character strings and stores a character-string value into the third record using NF_PUT_VARA_TEXT. In this example, we assume the string variable and data are to be added to an existing netCDF dataset named foo.nc that already has an unlimited record dimension time.
INCLUDE 'netcdf.inc'
...
INTEGER TDIMS, TXLEN
PARAMETER (TDIMS=2) ! number of TX dimensions
PARAMETER (TXLEN = 15) ! length of example string
INTEGER NCID
INTEGER CHID ! char position dimension id
INTEGER TIMEID ! record dimension id
INTEGER TXID ! variable ID
INTEGER TXDIMS(TDIMS) ! variable shape
INTEGER TSTART(TDIMS), TCOUNT(TDIMS)
CHARACTER*40 TXVAL ! max length 40
DATA TXVAL /'example string'/
...
TXVAL(TXLEN:TXLEN) = CHAR(0) ! null terminate
...
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_REDEF(NCID) ! enter define mode
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
! define character-position dimension for strings of max length 40
STATUS = NF_DEF_DIM(NCID, "chid", 40, CHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
! define a character-string variable
TXDIMS(1) = CHID ! character-position dimension first
TXDIMS(2) = TIMEID
STATUS = NF_DEF_VAR(NCID, "tx", NF_CHAR, TDIMS, TXDIMS, TXID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_ENDDEF(NCID) ! leave define mode
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
! write txval into tx netCDF variable in record 3
TSTART(1) = 0 ! start at beginning of variable
TSTART(2) = 3 ! record number to write
TCOUNT(1) = TXLEN ! number of chars to write
TCOUNT(2) = 1 ! only write one record
STATUS = NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL, 40)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
You may ignore fill values and use the entire range of a netCDF external data type, but in this case you should make sure you write all data values before reading them. If you know you will be writing all the data before reading it, you can specify that no prefilling of variables with fill values will occur by calling NF_SET_FILL before writing. This may provide a significant performance gain for netCDF writes.
The variable attribute _FillValue may be used to specify the fill value for a variable. Their are default fill values for each type, defined in the include file netcdf.inc: NF_FILL_CHAR, NF_FILL_INT1 (same as NF_FILL_BYTE), NF_FILL_INT2 (same as NF_FILL_SHORT), NF_FILL_INT, NF_FILL_REAL (same as NF_FILL_FLOAT), and NF_FILL_DOUBLE.
The netCDF byte and character types have different default fill values. The default fill value for characters is the zero byte, a useful value for detecting the end of variable-length C character strings. If you need a fill value for a byte variable, it is recommended that you explicitly define an appropriate _FillValue attribute, as generic utilities such as ncdump will not assume a default fill value for byte variables.
Type conversion for fill values is identical to type conversion for other values: attempting to convert a value from one type to another type that can't represent the value results in a range error. Such errors may occur on writing or reading values from a larger type (such as double) to a smaller type (such as float), if the fill value for the larger type cannot be represented in the smaller type.
NF_RENAME_VAR NF_RENAME_VAR changes the name of a netCDF variable in an open netCDF dataset. If the new name is longer than the old name, the netCDF dataset must be in define mode. You cannot rename a variable to have the name of any existing variable.
INTEGER FUNCTION NF_RENAME_VAR (INTEGER NCID, INTEGER VARID,
CHARACTER*(*) NEWNAM)
NCID | NetCDF ID, from a previous call to NF_OPEN or NF_CREATE. |
VARID | Variable ID. |
NEWNAM | New name for the specified variable. |
NF_RENAME_VAR returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NF_RENAME_VAR to rename the variable rh to rel_hum in an existing netCDF dataset named foo.nc:
INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
...
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_REDEF (NCID) ! enter definition mode
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_RENAME_VAR (NCID, RHID, 'rel_hum')
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_ENDDEF (NCID) ! leave definition mode
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)