You can use the netCDF library without knowing about all of the netCDF
interface. If you are creating a netCDF file, only a handful of
routines are required to define the necessary dimensions, variables, and
attributes, and to write the data to the netCDF file.
(Even less are needed if you use the ncgen
utility to create the file
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 file and access the data. Authors of generic
applications that access arbitrary netCDF files need to be familiar with
more of the netCDF library.
In this chapter we provide templates of common sequences of netCDF
subroutine calls needed for common uses. For clarity we present only
the names of routines; omit declarations and error checking; indent
statements that are typically invoked multiple times; and use
...
to represent arbitrary sequences of other statements.
Full argument lists for the procedures and subroutines are described in
later chapters.
The typical sequences of netCDF calls used to create a new netCDF file follows.
nccreate /* create netCDF file: enter define mode */ ... ncdimdef /* define dimension: from name and size */ ... ncvardef /* define variable: from name, type, dimensions */ ... ncattput /* put attribute: assign attribute values */ ... ncendef /* end definitions: leave define mode */ ... ncvarput /* put variable: provide values for variables */ ... ncclose /* close: save new netCDF file */
In FORTRAN, the corresponding sequence looks like this:
NCCRE ! create netCDF file: enter define mode ... NCDDEF ! define dimensions: from name and size ... NCVDEF ! define variables: from name, type, dimensions ... NCAPT or NCAPTC ! put attribute: assign attribute values ... NCENDF ! end definitions: leave define mode ... NCVPT or NCVPTC ! put variable: provide values for variables ... NCCLOS ! close: save new netCDF file
Only one call is needed to create a netCDF file, at which point you will be in the first of two netCDF modes. When accessing an open netCDF file, 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 ncdimdef
(or NCDDEF
) is needed for each
dimension created. Similarly, one call to ncvardef
(or
NCVDEF
) is needed for each variable creation, and one call to
ncattput
(or NCAPT
or NCAPTC
) is needed for each
attribute defined and assigned a value. To leave define
mode and enter data mode, call ncendef
(or
NCENDF
).
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).
The FORTRAN interface provides two subroutines for defining attributes
and providing values for variables, depending on whether a numeric or
character string value is used.
Single
values are written to a variable with ncvarput1
(or NCVPT1
or NCVP1C
); while arbitrary arrays of data are written using
ncvarput
or ncvarputg
(or NCVPT
, NCVPTC
,
NCVPTG
, or NCVPGC
) instead. Multi-variable records of
data may be written using multiple calls to ncvarput
(or NCVPT
)
or with a single call to ncrecput
.
Finally, you should explicitly close all netCDF
files that have been opened for writing by calling ncclose
(or
NCCLOS
). If a program terminates
abnormally with netCDF files open for writing, you may lose one or more
records of the most recently written record variable data as well as any
attribute changes since the last call to ncsync
(or
NCSNC
). It is possible to reduce the chance of losing data due
to abnormal termination by explicitly calling ncsync
(NCSNC
) after every write to netCDF variables or change to
attribute values. This can be expensive in computer resources, so
such calls should ordinarily be omitted unless they are really needed.
Here we consider the case where you know the names of not only the netCDF files, but also the names of their dimensions, variables, and attributes. (Otherwise you would have to do "inquire" calls.) The order of typical C calls to read data from those variables in a netCDF file is:
ncopen /* open existing netCDF file */ ... ncdimid /* get dimension IDs */ ... ncvarid /* get variable IDs */ ... ncattget /* get attribute values */ ... ncvarget /* get values of variables */ ... ncclose /* close netCDF file */
In FORTRAN, the corresponding sequence looks like this:
NCOPN ! open existing netCDF file ... NCDID ! get dimension IDs ... NCVID ! get variable IDs ... NCAGT or NCAGTC ! get attribute values ... NCVGT or NCVGTC ! get values of variables ... NCCLOS ! close netCDF file
First, a single call opens the netCDF file, given the file name, and returns a netCDF ID that is used to refer to the open netCDF file in all subsequent calls.
Next, a call to ncdimid
(or NCDID
) 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 ncvarid
(or NCVID
). 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 ncattget
(or NCAGT
or NCAGTC
) for each desired
attribute. Variable data values can be directly accessed from the
netCDF file with ncvarget1
(or NCVGT1
or NCVG1C
)
for single values, ncvarget
or ncvargetg
(or NCVGT
,
NCVGTC
, NCVGTG
, or NCVGGC
) for cross-sections of
values, or ncrecget
for records of values.
Finally, the netCDF file is closed with ncclose
(or NCCLOS
).
There is no need to close a file open only for reading.
Many programs (e.g. generic software) need to get It is possible to write programs (e.g. generic software) which do such things as processing every variable (except perhaps coordinate variables) in some way, without needing to know in advance the names of these variables. Even the names of dimensions and attributes may be unknown.
Names and other information may be obtained from netCDF files by calling inquire functions. These return information about a whole netCDF file, a dimension, a variable, or an attribute. The following template illustrates how they are used:
ncopen /* open existing netCDF file */ ... ncinquire /* find out what is in it */ ... ncdiminq /* get dimension names, sizes */ ... ncvarinq /* get variable names, types, shapes */ ... ncattname /* get attribute names */ ... ncattinq /* get attribute types and lengths */ ... ncattget /* get attribute values */ ... ncvarget /* get values of variables */ ... ncclose /* close netCDF file */
In FORTRAN, the corresponding sequence looks like this:
NCOPN ! open existing netCDF file ... NCINQ ! find out what is in it ... NCDINQ ! get dimension names, sizes ... NCVINQ ! get variable names, types, shapes ... NCANAM ! get attribute names ... NCAINQ ! get attribute values ... NCAGT or NCAGTC ! get attribute values ... NCVGT or NCVGTC ! get values of variables ... NCCLOS ! close netCDF file
As in the previous example, a single call opens the existing netCDF
file, returning a netCDF ID. This netCDF ID is given to the
ncinquire
(or NCINQ
) 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.
Another inquire function, ncrecinq
, provides a convenient way of
obtaining information about record variables, although the information
can also be obtained using the other inquire functions. The
ncrecinq
function returns the number of record variables, their
variable IDs, and how much memory is needed for a data record.
All the inquire functions are quite inexpensive to use and require no I/O, since the information they provide is stored in memory. In the C interface, the inquire functions also support getting a subset of information, by providing null pointers instead of valid addresses, for undesired information.
Dimension IDs are assigned by using consecutive integers (beginning at 0
in C, 1 in FORTRAN). Also dimensions, once created, cannot be deleted.
Therefore, knowing the number of dimension IDs in a netCDF file means knowing
all the dimension IDs: they are the integers 0, 1, 2, ..., (or 1, 2,
3, ... in FORTRAN). For each dimension ID, a call to the inquire
function ncdiminq
(or NCDINQ
) returns the dimension name
and size.
Variable IDs are also assigned from consecutive integers 0, 1, 2,
..., (or 1, 2, 3,
... in FORTRAN). These can be used in ncvarinq
(or
NCVINQ
) 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 ncattname
(or NCANAM
) return the name for
each attribute given the netCDF ID, variable ID, and attribute number.
Armed with the attribute name, a call to ncattinq
(or
NCAINQ
) returns its type and length. Given the type
and length, you can allocate enough space to hold
the attribute values. Then a call to ncattget
(or NCAGT
or NCAGTC
) returns the attribute values.
Once the names, IDs, types, shapes, and lengths of all netCDF components
are known, data values can be accessed by calling ncvarget1
(or
NCVGT1
or NCVG1C
) for single values, ncvarget
or
ncvargetg
(or NCVGT
, NCVGTC
, NCVGTG
, or NCVGGC
) for
aggregates of values using array access, or ncrecget
for
aggregates of values using record access.
An existing netCDF file can be extensively altered. New dimensions, variables, and attributes can be added or existing ones renamed, and existing attributes can be deleted. Existing dimensions, variables, and attributes can be renamed. The following code template lists a typical sequence of calls to add new netCDF components to an existing file:
ncopen /* open existing netCDF file */ ... ncredef /* put it into define mode */ ... ncdimdef /* define additional dimensions (if any) */ ... ncvardef /* define additional variables (if any) */ ... ncattput /* define additional attributes (if any) */ ... ncendef /* check definitions, leave define mode */ ... ncvarput /* provide values for new variables */ ... ncclose /* close netCDF file */
In FORTRAN, the corresponding sequence looks like this:
NCOPN ! open existing netCDF file ... NCREDF ! put it into define mode ... NCDDEF ! define additional dimensions (if any) ... NCVDEF ! define additional variables (if any) ... NCAPT or NCAPTC ! define additional attributes (if any) ... NCENDF ! check definitions, leave define mode ... NCVPT or NCVPTC ! provide values for new variables ... NCCLOS ! close netCDF file
A netCDF file is first opened by the ncopen
(or NCOPN
)
call. This call puts you 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 leave data mode and
enter define mode, by calling ncredef
(or NCREDF
).
In define mode, call ncdimdef
(or NCDDEF
) to define new
dimensions, ncvardef
(or NCVDEF
) to define new variables,
and ncattput
(or NCAPT
or
NCAPTC
) 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 ncendef
(or NCENDF
). If you do not wish
to reenter data mode, just call ncclose
(or NCCLOS
), which
will have the effect of first calling ncendef
(or NCENDF
).
Until the ncendef
(or NCENDF
) call, you may back out of
all the redefinitions made in define mode and restore the previous state
of the netCDF dataset by calling ncabort
(or NCABOR
). You
may also use the ncabort
call to restore the netCDF dataset to a
consistent state if the call to ncendef
(or NCENDF
) fails.
If you have called ncclose
(or NCCLOS
) from definition
mode and the implied call to ncendef
(or NCENDF
) fails,
ncabort
(or NCABOR
) will automatically be called to close
the netCDF file and leave it in its previous consistent state (before
you entered define mode).
The netCDF library provides the facilities needed to handle errors in a flexible way. However it is often unnecessary to specify anything about error handling, since by default all netCDF library routines just print an error message and exit when an error occurs. If this (admittedly drastic) error behavior is acceptable, you never need to check return values, since any condition that would result in an error will print an explanatory message and exit. For simplicity, the examples in this guide assume this default error-handling behavior, so there is no checking of return values.
In the C interface, errors may be handled more flexibly by setting the
external integer ncopts
, declared in the file `netcdf.h'.
Two aspects of the error-handling behavior can be modified
independently: the suppression of error messages, and the fatality of
errors. The default behavior, that errors are both verbose and fatal,
is specified by the assignment
ncopts = NC_VERBOSE | NC_FATAL;
where NC_VERBOSE
and NC_FATAL
are predefined constants
from the include file `netcdf.h'.
If you want error messages but do not wish errors to be fatal, turn off the fatal error flag with:
ncopts = NC_VERBOSE;
If you want neither error messages nor fatal errors, turn off both flags with:
ncopts = 0;
In non-fatal mode you should check the return value after each call to a
netCDF function.
This value is 0
normally and -1
if an error occurs.
Another externally-defined integer,
ncerr
, contains a netCDF-specific error code that is available
after an error has occurred to determine the nature of the error.
The names and descriptions of netCDF error codes are included in
the file `netcdf.h'.
In the FORTRAN interface, the error options described above can be accessed by using the routines NCPOPT and NCGOPT. The default error- handling behavior is equivalent to the statement
CALL NCPOPT(NCVERBOS+NCFATAL)
where the values of NCVERBOS and NCFATAL are predefined constants from the FORTRAN include file `netcdf.inc'. If you want error messages, but do not wish errors to be fatal, turn off the fatal error flag with:
CALL NCPOPT(NCVERBOS)
If you want neither error messages nor fatal errors, turn off both flags with:
CALL NCPOPT(0)
To get the current value of the error options, use:
CALL NCGOPT(NCOPTS)
In either case, the integer return code (the last parameter in all of the FORTRAN subroutines and functions) contains the non-zero netCDF-specific error number that can be used to determine the nature of the error. Names and descriptions of netCDF error codes are included in the file `netcdf.inc'.
Occasionally, low-level write errors may occur in the XDR library 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 message from one of the XDR functions rather than from the netCDF library.
Details of how to compile and link a program that uses the netCDF C or FORTRAN interfaces differ, depending on the operating system, the available compilers, and where the netCDF library and include files are installed. Nevertheless, we provide here examples of how to compile and link a program that uses the netCDF library on a Unix platform, so that you can adjust these examples to fit your installation.
Every C file that references netCDF functions or constants must contain
an appropriate #include
statement before the first such reference:
#include <netcdf.h>
Unless the `netcdf.h' file is installed in a standard directory
where the C compiler always looks, you must use the -I
option when invoking the compiler, to specify a directory where
`netcdf.h' is installed, for example:
cc -c -I/usr/local/netcdf/include myprogram.c
Alternatively, you could specify an absolute pathname 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:
cc -o myprogram myprogram.o -L/usr/local/netcdf/lib -lnetcdf
Alternatively, you could specify an absolute pathname for the library:
cc -o myprogram myprogram.o -l/usr/local/netcdf/lib/libnetcdf.a
On some systems, you must specify an additional library after the netCDF library where the system XDR libraries are found.
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.f
Alternatively, you could specify an absolute pathname 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 -lnetcdf
Alternatively, you could specify an absolute pathname for the library:
f77 -o myprogram myprogram.o -l/usr/local/netcdf/lib/libnetcdf.a
On some systems, you must specify an additional library after the netCDF library where the system XDR libraries are found.
Go to the first, previous, next, last section, table of contents.