NetCDF User's Guide for Fortran
ncgen
utility to create the dataset before running a program using netCDF library calls to write data.) Similarly, if you are writing software to access data stored in a particular netCDF object, only a small subset of the netCDF library is required to open the netCDF dataset and access the data. Authors of generic applications that access arbitrary netCDF datasets need to be familiar with more of the netCDF library.
In this chapter we provide templates of common sequences of netCDF calls needed for common uses. For clarity we present only the names of routines; omit declarations and error checking; omit the type-specific suffixes of routine names for variables and attributes; indent statements that are typically invoked multiple times; and use ...
to represent arbitrary sequences of other statements. Full parameter lists are described in later chapters.
NF_CREATE ! create netCDF dataset: enter define mode ... NF_DEF_DIM ! define dimensions: from name and length ... NF_DEF_VAR ! define variables: from name, type, dims ... NF_PUT_ATT ! assign attribute values ... NF_ENDDEF ! end definitions: leave define mode ... NF_PUT_VAR ! provide values for variable ... NF_CLOSE ! close: save new netCDF datasetOnly one call is needed to create a netCDF dataset, at which point you will be in the first of two netCDF modes. When accessing an open netCDF dataset, it is either in define mode or data mode. In define mode, you can create dimensions, variables, and new attributes, but you cannot read or write variable data. In data mode, you can access data and change existing attributes, but you are not permitted to create new dimensions, variables, or attributes.
One call to NF_DEF_DIM
is needed for each dimension created. Similarly, one call to NF_DEF_VAR
is needed for each variable creation, and one call to a member of the NF_PUT_ATT
family is needed for each attribute defined and assigned a value. To leave define mode and enter data mode, call NF_ENDDEF.
Once in data mode, you can add new data to variables, change old values, and change values of existing attributes (so long as the attribute changes do not require more storage space). Single values may be written to a netCDF variable with one of the members of the NF_PUT_VAR1
family, depending on what type of data you have to write. All the values of a variable may be written at once with one of the members of the NF_PUT_VAR
family. Arrays or array cross-sections of a variable may be written using members of the NF_PUT_VARA
family. Subsampled array sections may be written using members of the NF_PUT_VARS
family. Mapped array sections may be written using members of the NF_PUT_VARM
family. (Subsampled and mapped access are general forms of data access that are explained later.)
Finally, you should explicitly close all netCDF datasets that have been opened for writing by calling NF_CLOSE
. By default, access to the file system is buffered by the netCDF library. If a program terminates abnormally with netCDF datasets open for writing, your most recent modifications may be lost. This default buffering of data is disabled by setting the NF_SHARE flag when opening the dataset. But even if this flag is set, changes to attribute values or changes made in define mode are not written out until NF_SYNC
or NF_CLOSE is called.
NF_OPEN ! open existing netCDF dataset
...
NF_INQ_DIMID ! get dimension IDs
...
NF_INQ_VARID ! get variable IDs
...
NF_GET_ATT
! get attribute values
...
NF_GET_VAR ! get values of variables
...
NF_CLOSE ! close netCDF dataset
First, a single call opens the netCDF dataset, given the dataset name, and returns a netCDF ID that is used to refer to the open netCDF dataset in all subsequent calls.
Next, a call to NF_INQ_DIMID
for each dimension of interest gets the dimension ID from the dimension name. Similarly, each required variable ID is determined from its name by a call to NF_INQ_VARID
.Once variable IDs are known, variable attribute values can be retrieved using the netCDF ID, the variable ID, and the desired attribute name as input to a member of the NF_GET_ATT
family (typically NF_GET_ATT_TEXT
or NF_GET_ATT_DOUBLE
) for each desired attribute. Variable data values can be directly accessed from the netCDF dataset with calls to members of the NF_GET_VAR1
family for single values, the NF_GET_VAR
family for entire variables, or various other members of the NF_GET_VARA
, NF_GET_VARS
, or NF_GET_VARM
families for array, subsampled or mapped access.
Finally, the netCDF dataset is closed with NF_CLOSE
. There is no need to close a dataset open only for reading.
Names and other information about netCDF objects may be obtained from netCDF datasets by calling inquire functions. These return information about a whole netCDF dataset, a dimension, a variable, or an attribute. The following template illustrates how they are used:
NF_OPEN ! open existing netCDF dataset ... NF_INQ ! find out what is in it ... NF_INQ_DIM ! get dimension names, lengths ... NF_INQ_VAR ! get variable names, types, shapes ... NF_INQ_ATTNAME ! get attribute names ... NF_INQ_ATT ! get attribute values ... NF_GET_ATT ! get attribute values ... NF_GET_VAR ! get values of variables ... NF_CLOSE ! close netCDF datasetAs in the previous example, a single call opens the existing netCDF dataset, returning a netCDF ID. This netCDF ID is given to the
NF_INQ
routine, which returns the number of dimensions, the number of variables, the number of global attributes, and the ID of the unlimited dimension, if there is one.All the inquire functions are inexpensive to use and require no I/O, since the information they provide is stored in memory when a netCDF dataset is first opened.
Dimension IDs use consecutive integers, beginning at 1. Also dimensions, once created, cannot be deleted. Therefore, knowing the number of dimension IDs in a netCDF dataset means knowing all the dimension IDs: they are the integers 1, 2, 3, ... up to the number of dimensions. For each dimension ID, a call to the inquire function NF_INQ_DIM
returns the dimension name and length.
Variable IDs are also assigned from consecutive integers 1, 2, 3, ... up to the number of variables. These can be used in NF_INQ_VAR
calls to find out the names, types, shapes, and the number of attributes assigned to each variable.
Once the number of attributes for a variable is known, successive calls to NF_INQ_ATTNAME
return the name for each attribute given the netCDF ID, variable ID, and attribute number. Armed with the attribute name, a call to NF_INQ_ATT
returns its type and length. Given the type and length, you can allocate enough space to hold the attribute values. Then a call to a member of the NF_GET_ATT
family returns the attribute values.
Once the IDs and shapes of netCDF variables are known, data values can be accessed by calling a member of the NF_GET_VAR1
family for single values, or members of the NF_GET_VAR, NF_GET_VARA, NF_GET_VARS,
or NF_GET_VARM f
or various kinds of array access.
NF_OPEN ! open existing netCDF dataset
...
NF_REDEF ! put it into define mode
...
NF_DEF_DIM ! define additional dimensions (if any)
...
NF_DEF_VAR ! define additional variables (if any)
...
NF_PUT_ATT
! define other attributes (if any)
...
NF_ENDDEF ! check definitions, leave define mode
...
NF_PUT_VAR ! provide new variable values
...
NF_CLOSE ! close netCDF dataset
A netCDF dataset is first opened by the NF_OPEN
call. This call puts the open dataset in data mode, which means existing data values can be accessed and changed, existing attributes can be changed (so long as they do not grow), but nothing can be added. To add new netCDF dimensions, variables, or attributes you must enter define mode, by calling NF_REDEF
.In define mode, call NF_DEF_DIM
to define new dimensions, NF_DEF_VAR
to define new variables, and a member of the NF_PUT_ATT
family to assign new attributes to variables or enlarge old attributes.
You can leave define mode and reenter data mode, checking all the new definitions for consistency and committing the changes to disk, by calling NF_ENDDEF
. If you do not wish to reenter data mode, just call NF_CLOSE
, which will have the effect of first calling NF_ENDDEF
.
Until the NF_ENDDEF
call, you may back out of all the redefinitions made in define mode and restore the previous state of the netCDF dataset by calling NF_ABORT
. You may also use the NF_ABORT
call to restore the netCDF dataset to a consistent state if the call to NF_ENDDEF
fails. If you have called NF_CLOSE
from definition mode and the implied call to NF_ENDDEF
fails, NF_ABORT
will automatically be called to close the netCDF dataset and leave it in its previous consistent state (before you entered define mode).
At most one process should have a netCDF dataset open for writing at one time. The library is designed to provide limited support for multiple concurrent readers with one writer, via disciplined use of the NF_SYNC function and the NF_SHARE flag. If a writer makes changes in define mode, such as the addition of new variables, dimensions, or attributes, some means external to the library is necessary to prevent readers from making concurrent accesses and to inform readers to call NF_SYNC before the next access.
The NF_STRERROR function is available to convert a returned integer error status into an error message string.
Occasionally, low-level I/O errors may occur in a layer below the netCDF library. For example, if a write operation causes you to exceed disk quotas or to attempt to write to a device that is no longer available, you may get an error from a layer below the netCDF library, but the resulting write error will still be reflected in the returned status value.
Every FORTRAN file that references netCDF functions or constants must contain an appropriate INCLUDE
statement before the first such reference:
INCLUDE 'netcdf.inc'Unless the
netcdf.inc
file is installed in a standard directory where the FORTRAN compiler always looks, you must use the -I
option when invoking the compiler, to specify a directory where netcdf.inc
is installed, for example:
f77 -c -I/usr/local/netcdf/include myprogram.fAlternatively, you could specify an absolute path name in the
INCLUDE
statement, but then your program would not compile on another platform where netCDF is installed in a different location.
Unless the netCDF library is installed in a standard directory where the linker always looks, you must use the -L
and -l
options to link an object file that uses the netCDF library. For example:
f77 -o myprogram myprogram.o -L/usr/local/netcdf/lib -lnetcdfAlternatively, you could specify an absolute path name for the library:
f77 -o myprogram myprogram.o -l/usr/local/netcdf/lib/libnetcdf.