NetCDF-Fortran  4.4.4
netcdf-f90-sec1-usage.md
Go to the documentation of this file.
1 
2 1 Use of the NetCDF Library {#f90-use-of-the-netcdf-library}
3 =====================
4 
5 [TOC]
6 
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.
14 
15 1.1 Creating a NetCDF Dataset {#f90-creating-a-netcdf-dataset}
16 =====================
17 
18 Here is a typical sequence of netCDF calls used to create a new netCDF
19 dataset:
20 
21 ~~~~.fortran
22 
23 
24  NF90_CREATE ! create netCDF dataset: enter define mode
25  ...
26  NF90_DEF_DIM ! define dimensions: from name and length
27  ...
28  NF90_DEF_VAR ! define variables: from name, type, dims
29  ...
30  NF90_PUT_ATT ! assign attribute values
31  ...
32  NF90_ENDDEF ! end definitions: leave define mode
33  ...
34  NF90_PUT_VAR ! provide values for variable
35  ...
36  NF90_CLOSE ! close: save new netCDF dataset
37 
38 ~~~~
39 
40 
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.
48 
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.
54 
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.)
63 
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.
72 
73 1.2 Reading a NetCDF Dataset with Known Names {#f90-reading-a-netcdf-dataset-with-known-names}
74 =====================
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
79 is:
80 
81 ~~~~.fortran
82 
83 
84 
85 
86  NF90_OPEN ! open existing netCDF dataset
87  ...
88  NF90_INQ_DIMID ! get dimension IDs
89  ...
90  NF90_INQ_VARID ! get variable IDs
91  ...
92  NF90_GET_ATT ! get attribute values
93  ...
94  NF90_GET_VAR ! get values of variables
95  ...
96  NF90_CLOSE ! close netCDF dataset
97 
98 
99 
100 ~~~~
101 
102 
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.
106 
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
114 NF90\_GET\_VAR.
115 
116 Finally, the netCDF dataset is closed with NF90\_CLOSE. There is no need
117 to close a dataset open only for reading.
118 
119 1.3 Reading a netCDF Dataset with Unknown Names {#f90-reading-a-netcdf-dataset-with-unknown-names}
120 =====================
121 
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.
126 
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:
131 
132 
133 
134 ~~~~.fortran
135 
136  NF90_OPEN ! open existing netCDF dataset
137  ...
138  NF90_INQUIRE ! find out what is in it
139  ...
140  NF90_INQUIRE_DIMENSION ! get dimension names, lengths
141  ...
142  NF90_INQUIRE_VARIABLE ! get variable names, types, shapes
143  ...
144  NF90_INQ_ATTNAME ! get attribute names
145  ...
146  NF90_INQUIRE_ATTRIBUTE ! get other attribute information
147  ...
148  NF90_GET_ATT ! get attribute values
149  ...
150  NF90_GET_VAR ! get values of variables
151  ...
152  NF90_CLOSE ! close netCDF dataset
153 
154 
155 ~~~~
156 
157 
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.
163 
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.
167 
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.
174 
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.
179 
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
186 values.
187 
188 Once the IDs and shapes of netCDF variables are known, data values can
189 be accessed by calling NF90\_GET\_VAR.
190 
191 
192 1.4 Writing Data in an Existing NetCDF Dataset {#f90-writing-data-in-an-existing-netcdf-dataset}
193 =====================
194 
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.
205 
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:
209 
210 
211 ~~~~.fortran
212 
213 
214  NF90_OPEN ! open existing netCDF dataset
215  ...
216  NF90_INQ_VARID ! get variable IDs
217  ...
218  NF90_PUT_VAR ! provide new values for variables, if any
219  ...
220  NF90_PUT_ATT ! provide new values for attributes, if any
221  ...
222  NF90_CLOSE ! close netCDF dataset
223 
224 
225 
226 ~~~~
227 
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.
232 
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).
245 
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.
249 
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.
253 
254 1.5 Adding New Dimensions, Variables, Attributes {#f90-adding-new-dimensions-variables-attributes}
255 =====================
256 
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:
262 
263 
264 ~~~~.fortran
265 
266 
267  NF90_OPEN ! open existing netCDF dataset
268  ...
269  NF90_REDEF ! put it into define mode
270  ...
271  NF90_DEF_DIM ! define additional dimensions (if any)
272  ...
273  NF90_DEF_VAR ! define additional variables (if any)
274  ...
275  NF90_PUT_ATT ! define other attributes (if any)
276  ...
277  NF90_ENDDEF ! check definitions, leave define mode
278  ...
279  NF90_PUT_VAR ! provide new variable values
280  ...
281  NF90_CLOSE ! close netCDF dataset
282 
283 
284 ~~~~
285 
286 
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.
295 
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.
300 
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).
309 
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.
318 
319 
320 1.6 Error Handling {#f90-error-handling}
321 =====================
322 
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.
330 
331 The NF90\_STRERROR function is available to convert a returned integer
332 error status into an error message string.
333 
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
339 value.
340 
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.
349 
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
353 sometimes “mod”).
354 
355 Most F90 compilers allow the user to specify the location of .MOD files,
356 usually with the -I flag.
357 
358 
359 
360 
361  $ f90 -c -I/usr/local/include mymodule.f90
362 
363 
364 
365 
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.
375 
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’}.
379 
380 If installed as a shared library, link, using something like:
381 
382 
383 
384 
385  $ f90 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff
386 
387 
388 
389 
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:
393 
394 
395 
396 
397  $ f90 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff -lnetcdf
398 
399 
400 
401 
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.
406 
407 To see all the options for ‘nf-config’, invoke it with the ‘–help’
408 argument.
409 
410 Here’s an example of how you could use ‘nf-config’ to compile and link a
411 Fortran program in one step:
412 
413 
414 
415 
416  $ f90 myprogram.f90 -o myprogram `nf-config --fflags --flibs`
417 
418 
419 
420 
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
426 pkg-config:
427 
428 
429 
430 
431  $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
432  $ f90 myprogram.f90 -o myprogram `pkg-config --cflags --libs netcdf-fortran`
433 
434 
435 
436 
437 where here ‘–cflags’ means compiler flags and ‘libs’ requests that the
438 approriate libraries be linked in.

Return to the Main Unidata NetCDF page.
Generated on Fri Oct 27 2017 08:12:17 for NetCDF-Fortran. NetCDF is a Unidata library.