2 1 Use of the NetCDF Library {#f90-use-of-the-
netcdf-library}
7 In
this chapter we provide templates of common sequences of netCDF calls
8 needed
for common uses. For clarity we present only the names of
9 routines; omit declarations and error checking; omit the type-specific
10 suffixes of routine names
for variables and attributes; indent
11 statements that are typically invoked multiple times; and use ... to
12 represent arbitrary sequences of other statements. Full parameter lists
13 are described in later chapters.
15 1.1 Creating a NetCDF Dataset {#f90-creating-a-
netcdf-dataset}
18 Here is a typical sequence of netCDF calls used to create a
new netCDF
24 NF90_CREATE ! create netCDF dataset: enter define mode
26 NF90_DEF_DIM ! define dimensions: from name and length
28 NF90_DEF_VAR ! define variables: from name, type, dims
30 NF90_PUT_ATT ! assign attribute values
32 NF90_ENDDEF ! end definitions: leave define mode
34 NF90_PUT_VAR ! provide values
for variable
36 NF90_CLOSE ! close: save
new netCDF dataset
41 Only one call is needed to create a netCDF dataset, at which point you
42 will be in the first of two netCDF modes. When accessing an open netCDF
43 dataset, it is either in define mode or data mode. In define mode, you
44 can create dimensions, variables, and
new attributes, but you cannot
45 read or write variable data. In data mode, you can access data and
46 change existing attributes, but you are not permitted to create
new
47 dimensions, variables, or attributes.
49 One call to NF90\_DEF\_DIM is needed
for each dimension created.
50 Similarly, one call to NF90\_DEF\_VAR is needed
for each variable
51 creation, and one call to a member of the NF90\_PUT\_ATT family is
52 needed
for each attribute defined and assigned a value. To leave define
53 mode and enter data mode, call NF90\_ENDDEF.
55 Once in data mode, you can add
new data to variables, change old values,
56 and change values of existing attributes (so
long as the attribute
57 changes
do not require more storage space). Data of all types is written
58 to a netCDF variable
using the NF90\_PUT\_VAR subroutine. Single values,
59 arrays, or array sections may be supplied to NF90\_PUT\_VAR; optional
60 arguments allow the writing of subsampled or mapped portions of the
61 variable. (Subsampled and mapped access are general forms of data access
62 that are explained later.)
64 Finally, you should explicitly close all netCDF datasets that have been
65 opened
for writing by calling NF90\_CLOSE. By
default, access to the
66 file system is buffered by the netCDF library. If a program terminates
67 abnormally with netCDF datasets open
for writing, your most recent
68 modifications may be lost. This
default buffering of data is disabled by
69 setting the NF90\_SHARE flag when opening the dataset. But even
if this
70 flag is set, changes to attribute values or changes made in define mode
71 are not written out until NF90\_SYNC or NF90\_CLOSE is called.
73 1.2 Reading a NetCDF Dataset with Known Names {#f90-reading-a-
netcdf-dataset-with-known-names}
75 Here we consider the
case where you know the names of not only the
76 netCDF datasets, but also the names of their dimensions, variables, and
77 attributes. (Otherwise you would have to
do "inquire" calls.) The order
78 of typical C calls to read data from those variables in a netCDF dataset
86 NF90_OPEN ! open existing netCDF dataset
88 NF90_INQ_DIMID !
get dimension IDs
90 NF90_INQ_VARID !
get variable IDs
92 NF90_GET_ATT !
get attribute values
94 NF90_GET_VAR !
get values of variables
96 NF90_CLOSE ! close netCDF dataset
103 First, a single call opens the netCDF dataset, given the dataset name,
104 and returns a netCDF ID that is used to refer to the open netCDF dataset
105 in all subsequent calls.
107 Next, a call to NF90\_INQ\_DIMID
for each dimension of interest gets the
108 dimension ID from the dimension name. Similarly, each required variable
109 ID is determined from its name by a call to NF90\_INQ\_VARID. Once
110 variable IDs are known, variable attribute values can be retrieved
using
111 the netCDF ID, the variable ID, and the desired attribute name as input
112 to NF90\_GET\_ATT
for each desired attribute. Variable data values can
113 be directly accessed from the netCDF dataset with calls to
116 Finally, the netCDF dataset is closed with NF90\_CLOSE. There is no need
117 to close a dataset open only
for reading.
119 1.3 Reading a netCDF Dataset with Unknown Names {#f90-reading-a-
netcdf-dataset-with-unknown-names}
120 =====================
122 It is possible to write programs (e.g.,
generic software) which do such
123 things as processing every variable, without needing to know in advance
124 the names of these variables. Similarly, the names of dimensions and
125 attributes may be unknown.
127 Names and other information about netCDF objects may be obtained from
128 netCDF datasets by calling inquire functions. These return information
129 about a whole netCDF dataset, a dimension, a variable, or an attribute.
130 The following template illustrates how they are used:
136 NF90_OPEN ! open existing netCDF dataset
138 NF90_INQUIRE ! find out what is in it
140 NF90_INQUIRE_DIMENSION ! get dimension names, lengths
142 NF90_INQUIRE_VARIABLE ! get variable names, types, shapes
144 NF90_INQ_ATTNAME ! get attribute names
146 NF90_INQUIRE_ATTRIBUTE ! get other attribute information
148 NF90_GET_ATT ! get attribute values
150 NF90_GET_VAR ! get values of variables
152 NF90_CLOSE ! close netCDF dataset
158 As in the previous example, a single call opens the existing netCDF
159 dataset, returning a netCDF ID. This netCDF ID is given to the
160 NF90\_INQUIRE routine, which returns the number of dimensions, the
161 number of variables, the number of global attributes, and the ID of the
162 unlimited dimension, if there is one.
164 All the inquire functions are inexpensive to use and require no I/O,
165 since the information they provide is stored in memory when a netCDF
166 dataset is first opened.
168 Dimension IDs use consecutive integers, beginning at 1. Also dimensions,
169 once created, cannot be deleted. Therefore, knowing the number of
170 dimension IDs in a netCDF dataset means knowing all the dimension IDs:
171 they are the integers 1, 2, 3, ...up to the number of dimensions. For
172 each dimension ID, a call to the inquire function
173 NF90\_INQUIRE\_DIMENSION returns the dimension name and length.
175 Variable IDs are also assigned from consecutive integers 1, 2, 3, ... up
176 to the number of variables. These can be used in NF90\_INQUIRE\_VARIABLE
177 calls to find out the names, types, shapes, and the number of attributes
178 assigned to each variable.
180 Once the number of attributes for a variable is known, successive calls
181 to NF90\_INQ\_ATTNAME return the name for each attribute given the
182 netCDF ID, variable ID, and attribute number. Armed with the attribute
183 name, a call to NF90\_INQUIRE\_ATTRIBUTE returns its type and length.
184 Given the type and length, you can allocate enough space to hold the
185 attribute values. Then a call to NF90\_GET\_ATT returns the attribute
188 Once the IDs and shapes of netCDF variables are known, data values can
189 be accessed by calling NF90\_GET\_VAR.
192 1.4 Writing Data in an Existing NetCDF Dataset {#f90-writing-data-in-an-existing-
netcdf-dataset}
193 =====================
195 With write access to an existing netCDF dataset, you can overwrite data
196 values in existing variables or append more data to record variables
197 along the unlimited (record) dimension. To append more data to
198 non-record variables requires changing the shape of such variables,
199 which means creating a new netCDF dataset, defining new variables with
200 the desired shape, and copying data. The netCDF data model was not
201 designed to make such "schema changes" efficient or easy, so it is best
202 to specify the shapes of variables correctly when you create a netCDF
203 dataset, and to anticipate which variables will later grow by using the
204 unlimited dimension in their definition.
206 The following code template lists a typical sequence of calls to
207 overwrite some existing values and add some new records to record
208 variables in an existing netCDF dataset with known variable names:
214 NF90_OPEN ! open existing netCDF dataset
216 NF90_INQ_VARID ! get variable IDs
218 NF90_PUT_VAR ! provide new values for variables, if any
220 NF90_PUT_ATT ! provide new values for attributes, if any
222 NF90_CLOSE ! close netCDF dataset
228 A netCDF dataset is first opened by the NF90\_OPEN call. This call puts
229 the open dataset in data mode, which means existing data values can be
230 accessed and changed, existing attributes can be changed, but no new
231 dimensions, variables, or attributes can be added.
233 Next, calls to NF90\_INQ\_VARID get the variable ID from the name, for
234 each variable you want to write. Then each call to NF90\_PUT\_VAR writes
235 data into a specified variable, either a single value at a time, or a
236 whole set of values at a time, depending on which variant of the
237 interface is used. The calls used to overwrite values of non-record
238 variables are the same as are used to overwrite values of record
239 variables or append new data to record variables. The difference is
240 that, with record variables, the record dimension is extended by writing
241 values that don’t yet exist in the dataset. This extends all record
242 variables at once, writing "fill values" for record variables for which
243 the data has not yet been written (but see section [Fill
244 Values](
#Fill-Values) to specify different behavior).
246 Calls to NF90\_PUT\_ATT may be used to change the values of existing
247 attributes, although data that changes after a file is created is
248 typically stored in variables rather than attributes.
250 Finally, you should explicitly close any netCDF datasets into which data
251 has been written by calling NF90\_CLOSE before program termination.
252 Otherwise, modifications to the dataset may be lost.
254 1.5 Adding New Dimensions, Variables, Attributes {#f90-adding-
new-dimensions-variables-attributes}
255 =====================
257 An existing netCDF dataset can be extensively altered. New dimensions,
258 variables, and attributes can be added or existing ones renamed, and
259 existing attributes can be deleted. Existing dimensions, variables, and
260 attributes can be renamed. The following code
template lists a typical
261 sequence of calls to add
new netCDF components to an existing dataset:
267 NF90_OPEN ! open existing netCDF dataset
269 NF90_REDEF ! put it into define mode
271 NF90_DEF_DIM ! define additional dimensions (
if any)
273 NF90_DEF_VAR ! define additional variables (
if any)
275 NF90_PUT_ATT ! define other attributes (
if any)
277 NF90_ENDDEF !
check definitions, leave define mode
279 NF90_PUT_VAR ! provide
new variable values
281 NF90_CLOSE ! close netCDF dataset
287 A netCDF dataset is first opened by the NF90\_OPEN call. This call puts
288 the open dataset in data mode, which means existing data values can be
289 accessed and changed, existing attributes can be changed (so
long as
290 they
do not grow), but nothing can be added. To add
new netCDF
291 dimensions, variables, or attributes you must enter define mode, by
292 calling NF90\_REDEF. In define mode, call NF90\_DEF\_DIM to define
new
293 dimensions, NF90\_DEF\_VAR to define
new variables, and NF90\_PUT\_ATT
294 to assign
new attributes to variables or enlarge old attributes.
296 You can leave define mode and reenter data mode, checking all the
new
297 definitions
for consistency and committing the changes to disk, by
298 calling NF90\_ENDDEF. If you
do not wish to reenter data mode, just call
299 NF90\_CLOSE, which will have the effect of first calling NF90\_ENDDEF.
301 Until the NF90\_ENDDEF call, you may back out of all the redefinitions
302 made in define mode and restore the previous state of the netCDF dataset
303 by calling NF90\_ABORT. You may also use the NF90\_ABORT call to restore
304 the netCDF dataset to a consistent state
if the call to NF90\_ENDDEF
305 fails. If you have called NF90\_CLOSE from definition mode and the
306 implied call to NF90\_ENDDEF fails, NF90\_ABORT will automatically be
307 called to close the netCDF dataset and leave it in its previous
308 consistent state (before you entered define mode).
310 At most one process should have a netCDF dataset open
for writing at one
311 time. The library is designed to provide limited support
for multiple
312 concurrent readers with one writer, via disciplined use of the
313 NF90\_SYNC
function and the NF90\_SHARE flag. If a writer makes changes
314 in define mode, such as the addition of
new variables, dimensions, or
315 attributes, some means external to the library is necessary to prevent
316 readers from making concurrent accesses and to inform readers to call
317 NF90\_SYNC before the next access.
320 1.6 Error Handling {#f90-error-handling}
321 =====================
323 The netCDF library provides the facilities needed to handle errors in a
324 flexible way. Each netCDF
function returns an integer status value. If
325 the returned status value indicates an error, you may handle it in any
326 way desired, from printing an associated error message and exiting to
327 ignoring the error indication and proceeding (not recommended!). For
328 simplicity, the examples in
this guide
check the error status and call a
329 separate
function to handle any errors.
331 The NF90\_STRERROR
function is available to convert a returned integer
332 error status into an error message
string.
334 Occasionally, low-level I/O errors may occur in a layer below the netCDF
335 library. For example,
if a write operation causes you to exceed disk
336 quotas or to attempt to write to a device that is no longer available,
337 you may
get an error from a layer below the netCDF library, but the
338 resulting write error will still be reflected in the returned status
341 1.7 Compiling and Linking with the NetCDF Library {#f90-compiling-and-linking-with-the-
netcdf-library}
342 =====================
343 Details of how to compile and link a program that uses the netCDF C or
344 Fortran interfaces differ, depending on the operating system, the
345 available compilers, and where the netCDF library and include files are
346 installed. Nevertheless, we provide here examples of how to compile and
347 link a program that uses the netCDF library on a Unix platform, so that
348 you can adjust these examples to fit your installation.
350 Every Fortran 90 procedure or module which references netCDF constants
351 or procedures must have access to the module information created when
352 the netCDF module was compiled. The suffix
for this file is “MOD” (or
355 Most F90 compilers allow the user to specify the location of .MOD files,
356 usually with the -I flag.
361 $ f90 -c -I/usr/local/include mymodule.f90
366 Starting with version 3.6.2, another method of building the netCDF
367 fortran libraries became available. With the –enable-separate-fortran
368 option to configure, the user can specify that the C library should not
369 contain the fortran functions. In these cases an additional library,
370 libnetcdff.a (note the extra “f”) will be built. This library contains
371 the Fortran functions. Since verion 4.1.3, the netCDF Fortran software
372 and library is always distinct from the netCDF C library, but depends on
373 it. If it is installed as a shared library, you need only use
374 ‘-lnetcdff’ to specify the Fortran library
for linking.
376 For more information about configure options, See [Specifying the
377 Environment
for Building](
netcdf-install.html#Specifying-the-Environment-
for-Building)
378 in {No value
for ‘i-man’}.
380 If installed as a shared library, link,
using something like:
385 $ f90 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff
390 If installed as a
static library, you will at least need to mention the
391 netCDF C library and perhaps other libraries, such as hdf5 or curl,
392 depending on how the C library was built. For example:
397 $ f90 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff -lnetcdf
402 Use of the nf-config utility program, installed as part of the
403 netcdf-fortran software, provides an easier way to compile and link,
404 without needing to know the details of where the library has been
405 installed, or whether it is installed as a shared or
static library.
407 To see all the options
for ‘nf-config’, invoke it with the ‘–help’
410 Here’s an example of how you could use ‘nf-config’ to compile and link a
411 Fortran program in one step:
416 $ f90 myprogram.f90 -o myprogram `nf-config --fflags --flibs`
421 If it is installed on your system, you could also use the ‘pkg-config’
422 utility to compile and link Fortran programs with the netCDF libraries.
423 This is especially useful in Makefiles, to insulate them from changes to
424 library versions and dependencies. Here is an example of how you could
425 compile and link a Fortran program with netCDF libraries
using
431 $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
432 $ f90 myprogram.f90 -o myprogram `pkg-config --cflags --libs
netcdf-fortran`
437 where here ‘–cflags’ means compiler flags and ‘libs’ requests that the
438 approriate libraries be linked in.