1 The NetCDF Fortran 77 Interface Guide {#nc_f77_interface_guide}
2 =====================================
6 This document describes the FORTRAN-77 interface to the netCDF library.
8 1 Use of the NetCDF Library {#f77_Use_of_the_NetCDF_Library}
9 =============================
11 You can use the netCDF library without knowing about all of the netCDF
12 interface. If you are creating a netCDF dataset, only a handful of
13 routines are required to define the necessary dimensions, variables, and
14 attributes, and to write the data to the netCDF dataset. (Even less are
15 needed if you use the ncgen utility to create the dataset before running
16 a program using netCDF library calls to write data. See
17 section ‘ncgen’ in The NetCDF Users
18 Guide.) Similarly, if you are writing software to access data stored in
19 a particular netCDF object, only a smallbset of the netCDF library is
20 required to open the netCDF dataset and access the data. Authors of
21 generic applications that access arbitrary netCDF datasets need to be
22 familiar with more of the netCDF library.
24 In this we provide templates of common sequences of netCDF calls
25 needed for common uses. For clarity we present only the names of
26 routines; omit declarations and error checking; omit the type-specific
27 suffixes of routine names for variables and attributes; indent
28 statements that are typically invoked multiple times; and use ... to
29 represent arbitrary sequences of other statements. Full parameter lists
30 are described in laters.
34 1.1 Creating a NetCDF Dataset {#f77_Creating_a_NetCDF_Dataset}
35 -----------------------------
37 Here is a typical sequence of netCDF calls used to create a new netCDF
43 NF_CREATE ! create netCDF dataset: enter define mode
45 NF_DEF_DIM ! define dimensions: from name and length
47 NF_DEF_VAR ! define variables: from name, type, dims
49 NF_PUT_ATT ! assign attribute values
51 NF_ENDDEF ! end definitions: leave define mode
53 NF_PUT_VAR ! provide values for variable
55 NF_CLOSE ! close: save new netCDF dataset
58 Only one call is needed to create a netCDF dataset, at which point you
59 will be in the first of two netCDF modes. When accessing an open netCDF
60 dataset, it is either in define mode or data mode. In define mode, you
61 can create dimensions, variables, and new attributes, but you cannot
62 read or write variable data. In data mode, you can access data and
63 change existing attributes, but you are not permitted to create new
64 dimensions, variables, or attributes.
66 One call to NF\_DEF\_DIM is needed for each dimension created.
67 Similarly, one call to NF\_DEF\_VAR is needed for each variable
68 creation, and one call to a member of the NF\_PUT\_ATT family is needed
69 for each attribute defined and assigned a value. To leave define mode
70 and enter data mode, call NF\_ENDDEF.
72 Once in data mode, you can add new data to variables, change old values,
73 and change values of existing attributes (so long as the attribute
74 changes do not require more storage space). Single values may be written
75 to a netCDF variable with one of the members of the NF\_PUT\_VAR1
76 family, depending on what type of data you have to write. All the values
77 of a variable may be written at once with one of the members of the
78 NF\_PUT\_VAR family. Arrays or array crosss of a variable may be
79 written using members of the NF\_PUT\_VARA family. Subsampled array
80 sections may be written using members of the NF\_PUT\_VARS family.
81 Mapped arrays may be written using members of the NF\_PUT\_VARM
82 family. (Subsampled and mapped access are general forms of data access
83 that are explained later.)
85 Finally, you should explicitly close all netCDF datasets that have been
86 opened for writing by calling NF\_CLOSE. By default, access to the file
87 system is buffered by the netCDF library. If a program terminates
88 abnormally with netCDF datasets open for writing, your most recent
89 modifications may be lost. This default buffering of data is disabled by
90 setting the NF\_SHARE flag when opening the dataset. But even if this
91 flag is set, changes to attribute values or changes made in define mode
92 are not written out until NF\_SYNC or NF\_CLOSE is called.
94 1.2 Reading a NetCDF Dataset with Known Names {#f77_Reading_a_NetCDF_Dataset_with_Known_Names}
95 ---------------------------------------------
97 Here we consider the case where you know the names of not only the
98 netCDF datasets, but also the names of their dimensions, variables, and
99 attributes. (Otherwise you would have to do "inquire" calls.) The order
100 of typical C calls to read data from those variables in a netCDF dataset
106 NF_OPEN ! open existing netCDF dataset
108 NF_INQ_DIMID ! get dimension IDs
110 NF_INQ_VARID ! get variable IDs
112 NF_GET_ATT ! get attribute values
114 NF_GET_VAR ! get values of variables
116 NF_CLOSE ! close netCDF dataset
119 First, a single call opens the netCDF dataset, given the dataset name,
120 and returns a netCDF ID that is used to refer to the open netCDF dataset
121 in allbsequent calls.
123 Next, a call to NF\_INQ\_DIMID for each dimension of interest gets the
124 dimension ID from the dimension name. Similarly, each required variable
125 ID is determined from its name by a call to NF\_INQ\_VARID.Once variable
126 IDs are known, variable attribute values can be retrieved using the
127 netCDF ID, the variable ID, and the desired attribute name as input to a
128 member of the NF\_GET\_ATT family (typically NF\_GET\_ATT\_TEXT or
129 NF\_GET\_ATT\_DOUBLE) for each desired attribute. Variable data values
130 can be directly accessed from the netCDF dataset with calls to members
131 of the NF\_GET\_VAR1 family for single values, the NF\_GET\_VAR family
132 for entire variables, or various other members of the NF\_GET\_VARA,
133 NF\_GET\_VARS, or NF\_GET\_VARM families for array,bsampled or mapped
136 Finally, the netCDF dataset is closed with NF\_CLOSE. There is no need
137 to close a dataset open only for reading.
140 1.3 Reading a netCDF Dataset with Unknown Names {#f77_Reading_a_netCDF_Dataset_with_Unknown_Names}
141 -----------------------------------------------
143 It is possible to write programs (e.g., generic software) which doch
144 things as processing every variable, without needing to know in advance
145 the names of these variables. Similarly, the names of dimensions and
146 attributes may be unknown.
148 Names and other information about netCDF objects may be obtained from
149 netCDF datasets by calling inquire functions. These return information
150 about a whole netCDF dataset, a dimension, a variable, or an attribute.
151 The following template illustrates how they are used:
156 NF_OPEN ! open existing netCDF dataset
158 NF_INQ ! find out what is in it
160 NF_INQ_DIM ! get dimension names, lengths
162 NF_INQ_VAR ! get variable names, types, shapes
164 NF_INQ_ATTNAME ! get attribute names
166 NF_INQ_ATT ! get attribute values
168 NF_GET_ATT ! get attribute values
170 NF_GET_VAR ! get values of variables
172 NF_CLOSE ! close netCDF dataset
175 As in the previous example, a single call opens the existing netCDF
176 dataset, returning a netCDF ID. This netCDF ID is given to the NF\_INQ
177 routine, which returns the number of dimensions, the number of
178 variables, the number of global attributes, and the ID of the unlimited
179 dimension, if there is one.
181 All the inquire functions are inexpensive to use and require no I/O,
182 since the information they provide is stored in memory when a netCDF
183 dataset is first opened.
185 Dimension IDs use consecutive integers, beginning at 1. Also dimensions,
186 once created, cannot be deleted. Therefore, knowing the number of
187 dimension IDs in a netCDF dataset means knowing all the dimension IDs:
188 they are the integers 1, 2, 3, ... up to the number of dimensions. For
189 each dimension ID, a call to the inquire function NF\_INQ\_DIM returns
190 the dimension name and length.
192 Variable IDs are also assigned from consecutive integers 1, 2, 3, ... up
193 to the number of variables. These can be used in NF\_INQ\_VAR calls to
194 find out the names, types, shapes, and the number of attributes assigned
197 Once the number of attributes for a variable is known,ccessive calls
198 to NF\_INQ\_ATTNAME return the name for each attribute given the netCDF
199 ID, variable ID, and attribute number. Armed with the attribute name, a
200 call to NF\_INQ\_ATT returns its type and length. Given the type and
201 length, you can allocate enough space to hold the attribute values. Then
202 a call to a member of the NF\_GET\_ATT family returns the attribute
205 Once the IDs and shapes of netCDF variables are known, data values can
206 be accessed by calling a member of the NF\_GET\_VAR1 family for single
207 values, or members of the NF\_GET\_VAR, NF\_GET\_VARA, NF\_GET\_VARS, or
208 NF\_GET\_VARM for various kinds of array access.
210 1.4 Adding New Dimensions, Variables, Attributes {#f77_Adding_New_Dimensions__Variables__Attributes}
211 ------------------------------------------------
213 An existing netCDF dataset can be extensively altered. New dimensions,
214 variables, and attributes can be added or existing ones renamed, and
215 existing attributes can be deleted. Existing dimensions, variables, and
216 attributes can be renamed. The following code template lists a typical
217 sequence of calls to add new netCDF components to an existing dataset:
222 NF_OPEN ! open existing netCDF dataset
224 NF_REDEF ! put it into define mode
226 NF_DEF_DIM ! define additional dimensions (if any)
228 NF_DEF_VAR ! define additional variables (if any)
230 NF_PUT_ATT ! define other attributes (if any)
232 NF_ENDDEF ! check definitions, leave define mode
234 NF_PUT_VAR ! provide new variable values
236 NF_CLOSE ! close netCDF dataset
239 A netCDF dataset is first opened by the NF\_OPEN call. This call puts
240 the open dataset in data mode, which means existing data values can be
241 accessed and changed, existing attributes can be changed (so long as
242 they do not grow), but nothing can be added. To add new netCDF
243 dimensions, variables, or attributes you must enter define mode, by
244 calling NF\_REDEF.In define mode, call NF\_DEF\_DIM to define new
245 dimensions, NF\_DEF\_VAR to define new variables, and a member of the
246 NF\_PUT\_ATT family to assign new attributes to variables or enlarge old
249 You can leave define mode and reenter data mode, checking all the new
250 definitions for consistency and committing the changes to disk, by
251 calling NF\_ENDDEF. If you do not wish to reenter data mode, just call
252 NF\_CLOSE, which will have the effect of first calling NF\_ENDDEF.
254 Until the NF\_ENDDEF call, you may back out of all the redefinitions
255 made in define mode and restore the previous state of the netCDF dataset
256 by calling NF\_ABORT. You may also use the NF\_ABORT call to restore the
257 netCDF dataset to a consistent state if the call to NF\_ENDDEF fails. If
258 you have called NF\_CLOSE from definition mode and the implied call to
259 NF\_ENDDEF fails, NF\_ABORT will automatically be called to close the
260 netCDF dataset and leave it in its previous consistent state (before you
261 entered define mode).
263 At most one process should have a netCDF dataset open for writing at one
264 time. The library is designed to provide limitedpport for multiple
265 concurrent readers with one writer, via disciplined use of the NF\_SYNC
266 function and the NF\_SHARE flag. If a writer makes changes in define
267 mode,ch as the addition of new variables, dimensions, or attributes,
268 some means external to the library is necessary to prevent readers from
269 making concurrent accesses and to inform readers to call NF\_SYNC before
272 1.5 Error Handling {#f77_Error_Handling_1_5}
275 The netCDF library provides the facilities needed to handle errors in a
276 flexible way. Each netCDF function returns an integer status value. If
277 the returned status value indicates an error, you may handle it in any
278 way desired, from printing an associated error message and exiting to
279 ignoring the error indication and proceeding (not recommended!). For
280 simplicity, the examples in this guide check the error status and call a
281 separate function to handle any errors.
283 The NF\_STRERROR function is available to convert a returned integer
284 error status into an error message string.
286 Occasionally, low-level I/O errors may occur in a layer below the netCDF
287 library. For example, if a write operation causes you to exceed disk
288 quotas or to attempt to write to a device that is no longer available,
289 you may get an error from a layer below the netCDF library, but the
290 rlting write error will still be reflected in the returned status
293 1.6 Compiling and Linking with the NetCDF Library {#f77_Compiling_and_Linking_with_the_NetCDF_Library}
294 -------------------------------------------------
296 Details of how to compile and link a program that uses the netCDF C or
297 FORTRAN interfaces differ, depending on the operating system, the
298 available compilers, and where the netCDF library and include files are
299 installed. Nevertheless, we provide here examples of how to compile and
300 link a program that uses the netCDF library on a Unix platform, so that
301 you can adjust these examples to fit your installation.
303 Every FORTRAN file that references netCDF functions or constants must
304 contain an appropriate INCLUDE statement before the first
310 Unless the netcdf.inc file is installed in a standard directory where
311 the FORTRAN compiler always looks, you must use the -I option when
312 invoking the compiler, to specify a directory where netcdf.inc is
313 installed, for example:
315 f77 -c -I/usr/local/include myprogram.f
318 Unless the netCDF library is installed in a standard directory where the
319 linker always looks, you must use the -L and -l options to link an
320 object file that uses the netCDF library. Since version 4.1.3, the
321 netCDF Fortran library (named ‘libnetcdff’) is distinct from the netCDF
322 C library (named ‘libnetcdf’), but depends on it. If it is installed as
323 a shared library, you need only use ‘-lnetcdff’ to specify the Fortran
326 For example, if installed as a shared library, use something like:
329 f77 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff
332 If installed as a static library, you will at least need to mention the
333 netCDF C library and perhaps other libraries,ch as hdf5 or curl,
334 depending on how the C library was built. For example:
339 f77 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff -lnetcdf
342 Use of the nf-config utility program, installed as part of the
343 netcdf-fortran software, provides an easier way to compile and link,
344 without needing to know the details of where the library has been
345 installed, or whether it is installed as a shared or static library.
347 To see all the options for ‘nf-config’, invoke it with the ‘–help’
350 Here’s an example of how you could use ‘nf-config’ to compile and link a
351 Fortran program in one step:
356 f77 myprogram.f -o myprogram `nf-config --fflags --flibs`
359 If it is installed on your system, you could also use the ‘pkg-config’
360 utility to compile and link Fortran programs with the netCDF libraries.
361 This is especially useful in Makefiles, to ilate them from changes to
362 library versions and dependencies. Here is an example of how you could
363 compile and link a Fortran program with netCDF libraries using
369 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
370 f77 myprogram.f -o myprogram `pkg-config --cflags --libs netcdf-fortran`
373 where here ‘–cflags’ means compiler flags and ‘libs’ requests that the
374 approriate libraries be linked in.
378 2. Datasets {#f77_Datasets}
381 2.1 Datasets Introduction {#f77_Datasets_Introduction}
382 -------------------------
384 This presents the interfaces of the netCDF functions that deal
385 with a netCDF dataset or the whole netCDF library.
387 A netCDF dataset that has not yet been opened can only be referred to by
388 its dataset name. Once a netCDF dataset is opened, it is referred to by
389 a netCDF ID, which is a small nonnegative integer returned when you
390 create or open the dataset. A netCDF ID is much like a file descriptor
391 in C or a logical unit number in FORTRAN. In any single program, the
392 netCDF IDs of distinct open netCDF datasets are distinct. A single
393 netCDF dataset may be opened multiple times and will then have multiple
394 distinct netCDF IDs; however at most one of the open instances of a
395 single netCDF dataset should permit writing. When an open netCDF dataset
396 is closed, the ID is no longer associated with a netCDF dataset.
398 Functions that deal with the netCDF library include:
400 - Get version of library.
401 - Get error message corresponding to a returned error code.
403 The operationspported on a netCDF dataset as a single object are:
405 - Create, given dataset name and whether to overwrite or not.
406 - Open for access, given dataset name and read or write intent.
407 - Put into define mode, to add dimensions, variables, or attributes.
408 - Take out of define mode, checking consistency of additions.
409 - Close, writing to disk if required.
410 - Inquire about the number of dimensions, number of variables, number
411 of global attributes, and ID of the unlimited dimension, if any.
412 - Synchronize to disk to makere it is current.
413 - Set and unset nofill mode for optimized sequential writes.
414 - After ammary of conventions used in describing the netCDF
415 interfaces, the rest of this presents a detailed description
416 of the interfaces for these operations.
418 2.2 NetCDF Library Interface Descriptions {#f77_NetCDF_Library_Interface_Descriptions}
419 -----------------------------------------
421 Each interface description for a particular netCDF function in this and
424 - a description of the purpose of the function;
425 - a FORTRAN function prototype that presents the type and order of the
426 formal parameters to the function;
427 - a description of each formal parameter in the C interface;
428 - a list of possible error conditions; and
429 - an example of a FORTRAN program fragment calling the netCDF function
430 (and perhaps other netCDF functions).
432 The examples follow a simple convention for error handling, always
433 checking the error status returned from each netCDF function call and
434 calling a handle\_error function in case an error was detected. For an
435 example ofch a function, see Section 5.2 "Get error message
436 corresponding to error status: nf\_strerror".
438 2.3 NF_STRERROR {#f77_NF_STRERROR}
441 The function NF\_STRERROR returns a static reference to an error message
442 string corresponding to an integer netCDF error status or to a system
443 error number, prmably returned by a previous call to some other
444 netCDF function. The list of netCDF error status codes is available in
445 the appropriate include file for each language binding.
450 CHARACTER*80 FUNCTION NF_STRERROR(INTEGER NCERR)
454 : An error status that might have been returned from a previous call
455 to some netCDF function.
460 If you provide an invalid integer error status that does not correspond
461 to any netCDF error message or or to any system error message (as
462 understood by the system strerror function), NF\_STRERROR returns a
463 string indicating that there is noch error status.
467 Here is an example of a simple error handling function that uses
468 NF\_STRERROR to print the error message corresponding to the netCDF
469 error status returned from any netCDF function call and then exit:
476 SUBROUTINE HANDLE_ERR(STATUS)
478 IF (STATUS .NE. NF_NOERR) THEN
479 PRINT *, NF_STRERROR(STATUS)
486 2.4 Get netCDF library version: NF_INQ_LIBVERS {#f77_Get_netCDF_library_version_NF_INQ_LIBVERS}
487 ------------------------------------------------
489 The function NF\_INQ\_LIBVERS returns a string identifying the version
490 of the netCDF library, and when it was built.
495 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
500 This function takes no arguments, and thus no errors are possible in its
505 Here is an example using nf\_inq\_libvers to print the version of the
506 netCDF library with which the program is linked:
512 PRINT *, NF_INQ_LIBVERS()
515 2.5 NF_CREATE {#f77_NF_CREATE}
518 This function creates a new netCDF dataset, returning a netCDF ID that
519 can sequently be used to refer to the netCDF dataset in other netCDF
520 function calls. The new netCDF dataset opened for write access and
521 placed in define mode, ready for you to add dimensions, variables, and
524 A creation mode flag specifies whether to overwrite any existing dataset
525 with the same name and whether access to the dataset is shared.
530 INTEGER FUNCTION NF_CREATE (CHARACTER*(*) PATH, INTEGER CMODE,
534 `PATH`: The file name of the new netCDF dataset.
536 `CMODE`: The creation mode flag. The following flags are available:
537 NF\_NOCLOBBER, NF\_SHARE, NF\_64BIT\_OFFSET, NF\_NETCDF4 and
538 NF\_CLASSIC\_MODEL. You can combine the affect of multiple flags in
539 a single argument by using the bitwise OR operator. For example, to
540 specify both NF\_NOCLOBBER and NF\_SHARE, you could provide the
541 argument OR(NF\_NOCLOBBER, NF\_SHARE).
544 A zero value (defined for convenience as NF_CLOBBER) specifies the
545 default behavior: overwrite any existing dataset with the same file
546 name and buffer and cache accesses for efficiency. The dataset will
547 be in netCDF classic format. See 'NetCDF Classic Format Limitations'
548 in The NetCDF Users Guide.
550 Setting NF\_NOCLOBBER means you do not want to clobber (overwrite)
551 an existing dataset; an error (NF_EEXIST) is returned if the
552 specified dataset already exists.
554 The NF\_SHARE flag is appropriate when one process may be writing
555 the dataset and one or more other processes reading the dataset
556 concurrently; it means that dataset accesses are not buffered and
557 caching is limited. Since the buffering scheme is optimized for
558 sequential access, programs that do not access data sequentially may
559 see some performance improvement by setting the NF\_SHARE flag. This
560 only applied to classic and 64-bit offset format files.
562 Setting NF\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
563 format file, instead of a netCDF classic format file. The 64-bit
564 offset format imposes far fewer restrictions on very large (i.e.
565 over 2 GB) data files. See [(netcdf)Large File
566 Support](netcdf.html#Large-File-Support) ‘Large File
567 Support’ in The NetCDF Users Guide.
569 Setting NF\_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format
570 file. Oring NF\_CLASSIC\_MODEL with NF\_NETCDF4 causes the netCDF
571 library to create a netCDF-4/HDF5 data file, with the netCDF classic
572 model enforced - none of the new features of the netCDF-4 data model
573 may be usedinch a file, for example groups and user-defined
577 : Returned netCDF ID.
581 NF\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
582 causes of errors include:
584 - Passing a dataset name that includes a directory that does not
586 - Specifying a dataset name of a file that exists and also specifying
588 - Specifying a meaningless value for the creation mode.
589 - Attempting to create a netCDF dataset in a directory where you don’t
590 have permission to create files.
594 In this example we create a netCDF dataset named foo.nc; we want the
595 dataset to be created in the current directory only if a dataset with
596 that name does not already exist:
605 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
606 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
609 2.6 NF__CREATE {#f77_F__CREATE}
612 This function is a variant of NF\_CREATE, NF\_\_CREATE (note the double
613 underscore) allows users to specify two tuning parameters for the file
614 that it is creating. These tuning parameters are not written to the data
615 file, they are only used for so long as the file remains open after an
618 This function creates a new netCDF dataset, returning a netCDF ID that
619 canbsequently be used to refer to the netCDF dataset in other netCDF
620 function calls. The new netCDF dataset opened for write access and
621 placed in define mode, ready for you to add dimensions, variables, and
624 A creation mode flag specifies whether to overwrite any existing dataset
625 with the same name and whether access to the dataset is shared.
630 INTEGER FUNCTION NF__CREATE (CHARACTER*(*) PATH, INTEGER CMODE, INTEGER INITIALSZ,
631 INTEGER BUFRSIZEHINT, INTEGER ncid)
635 : The file name of the new netCDF dataset.
638 : The creation mode flag. The following flags are available:
639 NF\_NOCLOBBER, NF\_SHARE, NF\_64BIT\_OFFSET, NF\_NETCDF4, and
642 Setting NF\_NOCLOBBER means you do not want to clobber (overwrite)
643 an existing dataset; an error (NF\_EEXIST) is returned if the
644 specified dataset already exists.
646 The NF\_SHARE flag is appropriate when one process may be writing
647 the dataset and one or more other processes reading the dataset
648 concurrently; it means that dataset accesses are not buffered and
649 caching is limited. Since the buffering scheme is optimized for
650 sequential access, programs that do not access data sequentially may
651 see some performance improvement by setting the NF\_SHARE flag. This
652 flag has no effect with netCDF-4/HDF5 files.
654 Setting NF\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
655 format file, instead of a netCDF classic format file. The 64-bit
656 offset format imposes far fewer restrictions on very large (i.e.
657 over 2 GB) data files. See [(netcdf)Large File
658 Support](netcdf.html#Large-File-Support) ‘Large File
659 Support’ in The NetCDF Users Guide.
661 Setting NF\_CLASSIC\_MODEL causes netCDF to enforce the classic data
662 model in this file. (This only has effect for netCDF-4/HDF5 files,
663 as classic and 64-bit offset files always use the classic model.)
664 When used with NF\_NETCDF4, this flag eres that the rlting
665 netCDF-4/HDF5 file may never contain any new constructs from the
666 enhanced data model. That is, it cannot contain groups, user defined
667 types, multiple unlimited dimensions, or new atomic types. The
668 advantage of this restriction is thatch files are guarenteed to
669 work with existing netCDF software.
671 A zero value (defined for convenience as NF\_CLOBBER) specifies the
672 default behavior: overwrite any existing dataset with the same file
673 name and buffer and cache accesses for efficiency. The dataset will
674 be in netCDF classic format. See [(netcdf)NetCDF Classic Format
675 Limitations](netcdf.html#NetCDF-Classic-Format-Limitations)
676 ‘NetCDF Classic Format Limitations’ in The NetCDF Users Guide.
679 : This parameter sets the initial size of the file at creation time.
682 : The argument referenced by BUFRSIZEHINT controls a space ves time
683 tradeoff, memory allocated in the netcdf library ves number of
686 Because of internal requirements, the value may not be set to
687 exactly the value requested. The actual value chosen is returned by
690 Using the value NF\_SIZEHINT\_DEFAULT causes the library to choose a
691 default. How the system chooses the default depends on the system.
692 On many systems, the "preferred I/O block size" is available from
693 the stat() system call, struct stat member st\_blksize. If this is
694 available it is used. Lacking that, twice the system pagesize is
697 Lacking a call to discover the system pagesize, we just set default
700 The BUFRSIZE is a property of a given open netcdf descriptor ncid,
701 it is not a persistent property of the netcdf dataset.
704 : Returned netCDF ID.
708 NF\_\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
709 causes of errors include:
711 - Passing a dataset name that includes a directory that does not
713 - Specifying a dataset name of a file that exists and also specifying
715 - Specifying a meaningless value for the creation mode.
716 - Attempting to create a netCDF dataset in a directory where you don’t
717 have permission to create files.
721 In this example we create a netCDF dataset named foo.nc; we want the
722 dataset to be created in the current directory only if a dataset with
723 that name does not already exist:
730 INTEGER NCID, STATUS, INITIALSZ, BUFRSIZEHINT
734 STATUS = NF__CREATE('foo.nc', NF_NOCLOBBER, INITIALSZ, BUFRSIZEHINT, NCID)
735 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
738 2.7 NF_CREATE_PAR {#f77_NF_CREATE_PAR}
741 This function is a variant of nf\_create, nf\_create\_par allows users
742 to open a file on a MPI/IO or MPI/Posix parallel file system.
744 The parallel parameters are not written to the data file, they are only
745 used for so long as the file remains open after an nf\_create\_par.
747 This function is only available if the netCDF library was built with
750 This function creates a new netCDF dataset, returning a netCDF ID that
751 canbsequently be used to refer to the netCDF dataset in other netCDF
752 function calls. The new netCDF dataset opened for write access and
753 placed in define mode, ready for you to add dimensions, variables, and
756 When a netCDF-4 file is created for parallel access, independent
757 operations are the default. To use collective access on a variable, See
758 section [Change between Collective and Independent Parallel Access:
759 NF\_VAR\_PAR\_ACCESS](#NF_005fVAR_005fPAR_005fACCESS).
764 INTEGER FUNCTION NF_CREATE_PAR(CHARACTER*(*) PATH, INTEGER CMODE,
765 INTEGER MPI_COMM, INTEGER MPI_INFO,
770 : The file name of the new netCDF dataset.
773 : The creation mode flag. The following flags are available:
774 NF\_NOCLOBBER, NF\_NETCDF4 and NF\_CLASSIC\_MODEL. You can combine
775 the affect of multiple flags in a single argument by using the
776 bitwise OR operator. For example, to specify both NF\_NOCLOBBER and
777 NF\_NETCDF4, you could provide the argument OR(NF\_NOCLOBBER,
780 Setting NF\_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format
781 file. Oring NF\_CLASSIC\_MODEL with NF\_NETCDF4 causes the netCDF
782 library to create a netCDF-4/HDF5 data file, with the netCDF classic
783 model enforced - none of the new features of the netCDF-4 data model
784 may be usedinch a file, for example groups and user-defined
787 Only netCDF-4/HDF5 files may be used with parallel I/O.
790 : The MPI communicator.
796 : Returned netCDF ID.
801 NF\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
802 causes of errors include:
804 - Passing a dataset name that includes a directory that does not
806 - Specifying a dataset name of a file that exists and also specifying
808 - Specifying a meaningless value for the creation mode.
809 - Attempting to create a netCDF dataset in a directory where you don’t
810 have permission to create files.
815 This example is from test program nf\_test/ftst\_parallel.F.
820 ! Create the netCDF file.
821 mode_flag = IOR(nf_netcdf4, nf_classic_model)
822 retval = nf_create_par(FILE_NAME, mode_flag, MPI_COMM_WORLD,
823 $ MPI_INFO_NULL, ncid)
824 if (retval .ne. nf_noerr) stop 2
828 2.8 NF_OPEN {#f77_NF_OPEN_}
831 The function NF\_OPEN opens an existing netCDF dataset for access.
836 INTEGER FUNCTION NF_OPEN(CHARACTER*(*) PATH, INTEGER OMODE, INTEGER ncid)
840 : File name for netCDF dataset to be opened. This may be an OPeNDAP
841 URL if DAPpport is enabled.
844 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
845 read-only access, buffering and caching accesses for efficiency.
847 Otherwise, the creation mode is NF\_WRITE, NF\_SHARE, or
848 OR(NF\_WRITE, NF\_SHARE). Setting the NF\_WRITE flag opens the
849 dataset with read-write access. ("Writing" means any kind of change
850 to the dataset, including appending or changing data, adding or
851 renaming dimensions, variables, and attributes, or deleting
852 attributes.) The NF\_SHARE flag is appropriate when one process may
853 be writing the dataset and one or more other processes reading the
854 dataset concurrently; it means that dataset accesses are not
855 buffered and caching is limited. Since the buffering scheme is
856 optimized for sequential access, programs that do not access data
857 sequentially may see some performance improvement by setting the
861 : Returned netCDF ID.
866 NF\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
867 the returned status indicates an error. Possible causes of errors
870 - The specified netCDF dataset does not exist.
871 - A meaningless mode was specified.
875 Here is an example using NF\_OPEN to open an existing netCDF dataset
876 named foo.nc for read-only, non-shared access:
883 STATUS = NF_OPEN('foo.nc', 0, NCID)
884 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
887 2.9 NF__OPEN {#NF__OPEN_}
890 The function NF\_OPEN opens an existing netCDF dataset for access, with
891 a performance tuning parameter.
896 INTEGER FUNCTION NF_OPEN(CHARACTER*(*) PATH, INTEGER OMODE, INTEGER
897 BUFRSIZEHINT, INTEGER ncid)
901 : File name for netCDF dataset to be opened.
904 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
905 read-only access, buffering and caching accesses for efficiency
907 Otherwise, the creation mode is NF\_WRITE, NF\_SHARE, or
908 OR(NF\_WRITE,NF\_SHARE). Setting the NF\_WRITE flag opens the
909 dataset with read-write access. ("Writing" means any kind of change
910 to the dataset, including appending or changing data, adding or
911 renaming dimensions, variables, and attributes, or deleting
912 attributes.) The NF\_SHARE flag is appropriate when one process may
913 be writing the dataset and one or more other processes reading the
914 dataset concurrently; it means that dataset accesses are not
915 buffered and caching is limited. Since the buffering scheme is
916 optimized for sequential access, programs that do not access data
917 sequentially may see some performance improvement by setting the
921 : This argument controls a space ves time tradeoff, memory
922 allocated in the netcdf library ves number of system calls.
924 Because of internal requirements, the value may not be set to
925 exactly the value requested. The actual value chosen is returned by
928 Using the value NF\_SIZEHINT\_DEFAULT causes the library to choose a
929 default. How the system chooses the default depends on the system.
930 On many systems, the "preferred I/O block size" is available from
931 the stat() system call, struct stat member st\_blksize. If this is
932 available it is used. Lacking that, twice the system pagesize is
935 Lacking a call to discover the system pagesize, we just set default
938 The bufrsize is a property of a given open netcdf descriptor ncid,
939 it is not a persistent property of the netcdf dataset.
942 : Returned netCDF ID.
947 NF\_\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
948 the returned status indicates an error. Possible causes of errors
951 - The specified netCDF dataset does not exist.
952 - A meaningless mode was specified.
956 Here is an example using NF\_\_OPEN to open an existing netCDF dataset
957 named foo.nc for read-only, non-shared access:
963 INTEGER NCID, STATUS, BUFRSIZEHINT
966 STATUS = NF_OPEN('foo.nc', 0, BUFRSIZEHINT, NCID)
967 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
970 2.10 NF_OPEN_PAR {#f77_NF_OPEN_PAR}
973 This function opens a netCDF-4 dataset for parallel access.
975 This function is only available if the netCDF library was built with a
976 HDF5 library for which –enable-parallel was used, and which was linked
977 (like HDF5) to MPI libraries.
979 This opens the file using either MPI-IO or MPI-POSIX. The file must be a
980 netCDF-4 file. (That is, it must have been created using NF\_NETCDF4 in
983 This function is only available if netCDF-4 was build with a version of
984 the HDF5 library which was built with –enable-parallel.
986 Before either HDF5 or netCDF-4 can be installed withpport for
987 parallel programming, and MPI layer must also be installed on the
988 machine, and ally a parallel file system.
990 NetCDF-4 exposes the parallel access functionality of HDF5. For more
991 information about what is required to install and use the parallel
992 access functions, see the HDF5 web site.
994 When a netCDF-4 file is opened for parallel access, collective
995 operations are the default. To use independent access on a variable, See
996 section [Change between Collective and Independent Parallel Access:
997 NF\_VAR\_PAR\_ACCESS](#NF_005fVAR_005fPAR_005fACCESS).
1003 INTEGER FUNCTION NF_OPEN_PAR(CHARACTER*(*) PATH, INTEGER OMODE,
1004 INTEGER MPI_COMM, INTEGER MPI_INFO,
1009 : File name for netCDF dataset to be opened.
1012 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
1015 Otherwise, the mode may be NF\_WRITE. Setting the NF\_WRITE flag
1016 opens the dataset with read-write access. ("Writing" means any kind
1017 of change to the dataset, including appending or changing data,
1018 adding or renaming dimensions, variables, and attributes, or
1019 deleting attributes.)
1021 Setting NF\_NETCDF4 is not necessary (or allowed). The file type is
1022 detected automatically.
1025 : The MPI communicator.
1031 : Returned netCDF ID.
1036 NF\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
1037 the returned status indicates an error. Possible causes of errors
1040 - The specified netCDF dataset does not exist.
1041 - A meaningless mode was specified.
1042 - Not a netCDF-4 file.
1047 This example is from the test program nf\_test/ftst\_parallel.F.
1053 retval = nf_open_par(FILE_NAME, nf_nowrite, MPI_COMM_WORLD,
1054 $ MPI_INFO_NULL, ncid)
1055 if (retval .ne. nf_noerr) stop 2
1058 2.11 NF_REDEF {#f77_NF-REDEF}
1061 The function NF\_REDEF puts an open netCDF dataset into define mode, so
1062 dimensions, variables, and attributes can be added or renamed and
1063 attributes can be deleted.
1071 INTEGER FUNCTION NF_REDEF(INTEGER NCID)
1075 : netCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1080 NF\_REDEF returns the value NF\_NOERR if no errors occurred. Otherwise,
1081 the returned status indicates an error. Possible causes of errors
1084 - The specified netCDF dataset is already in define mode.
1085 - The specified netCDF dataset was opened for read-only.
1086 - The specified netCDF ID does not refer to an open netCDF dataset.
1091 Here is an example using NF\_REDEF to open an existing netCDF dataset
1092 named foo.nc and put it into define mode:
1097 INCLUDE 'netcdf.inc'
1099 INTEGER NCID, STATUS
1101 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID) ! open dataset
1102 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1104 STATUS = NF_REDEF(NCID) ! put in define mode
1105 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1109 2.12 NF_ENDDEF {#f77_NF-ENDDEF}
1112 The function NF\_ENDDEF takes an open netCDF dataset out of define mode.
1113 The changes made to the netCDF dataset while it was in define mode are
1114 checked and committed to disk if no problems occurred. Non-record
1115 variables may be initialized to a "fill value" as well (see
1116 [NF\_SET\_FILL](#NF_005fSET_005fFILL)). The netCDF dataset is then
1117 placed in data mode, so variable data can be read or written.
1119 This call may involve copying data under some circumstances. See
1120 [(netcdf)File Structure and
1121 Performance](netcdf.html#File-Structure-and-Performance) ‘File
1122 Structure and Performance’ in NetCDF Users’ Guide.
1130 INTEGER FUNCTION NF_ENDDEF(INTEGER NCID)
1134 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1139 NF\_ENDDEF returns the value NF\_NOERR if no errors occurred. Otherwise,
1140 the returned status indicates an error. Possible causes of errors
1143 - The specified netCDF dataset is not in define mode.
1144 - The specified netCDF ID does not refer to an open netCDF dataset.
1145 The size of one or more variables exceed the size constraints for
1146 whichever variant of the file format is in use). See [(netcdf)Large
1147 File Support](netcdf.html#Large-File-Support) ‘Large File
1148 Support’ in The NetCDF Users Guide.
1153 Here is an example using NF\_ENDDEF to finish the definitions of a new
1154 netCDF dataset named foo.nc and put it into data mode:
1158 INCLUDE 'netcdf.inc'
1160 INTEGER NCID, STATUS
1162 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1163 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1165 ... ! create dimensions, variables, attributes
1167 STATUS = NF_ENDDEF(NCID)
1168 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1173 2.13 NF__ENDDEF {#f77_NF__ENDDEF}
1176 The function NF\_\_ENDDEF takes an open netCDF dataset out of define
1177 mode. The changes made to the netCDF dataset while it was in define mode
1178 are checked and committed to disk if no problems occurred. Non-record
1179 variables may be initialized to a "fill value" as well (see
1180 [NF\_SET\_FILL](#NF_005fSET_005fFILL)). The netCDF dataset is then
1181 placed in data mode, so variable data can be read or written.
1183 This call may involve copying data under some circumstances. See
1184 [(netcdf)File Structure and
1185 Performance](netcdf.html#File-Structure-and-Performance) ‘File
1186 Structure and Performance’ in NetCDF Users’ Guide.
1188 This function ames specific characteristics of the netcdf version 1
1189 and version 2 file formats. Users should use nf\_enddef in most
1190 circumstances. Although this function will be available in future netCDF
1191 implementations, it may not continue to have any effect on performance.
1193 The current netcdf file format has threes, the "header",
1194 the data for fixed size variables, and the data for
1195 variables which have an unlimited dimension (record variables).
1197 The header begins at the beginning of the file. The index (offset) of
1198 the beginning of the other twos is contained in the header.
1199 Typically, there is no space between thes. This causes copying
1200 overhead to accrue if one wishes to change the size of thes, as
1201 may happen when changing names of things, text attribute values, adding
1202 attributes or adding variables. Also, for buffered i/o, there may be
1203 advantages to alignings in certain ways.
1205 The minfree parameters allow one to control costs of future calls to
1206 nf\_redef, nf\_enddef by requesting that minfree bytes be available at
1209 The align parameters allow one to set the alignment of the beginning of
1210 the correspondings. The beginning of the is rounded up
1211 to an index which is a multiple of the align parameter. The flag value
1212 ALIGN\_CHUNK tells the library to use the bufrsize (see above) as the
1215 The file format requires mod 4 alignment, so the align parameters are
1216 silently rounded up to multiples of 4. The al call,
1227 nf_enddef(ncid, 0, 4, 0, 4);
1230 The file format does not contain a "record size" value, this is
1231 calculated from the sizes of the record variables. This unfortunate fact
1232 prevents us from providing minfree and alignment control of the
1233 "records" in a netcdf file. If you add a variable which has an unlimited
1234 dimension, the third will always be copied with the new variable
1243 INTEGER FUNCTION NF_ENDDEF(INTEGER NCID, INTEGER H_MINFREE, INTEGER V_ALIGN,
1244 INTEGER V_MINFREE, INTEGER R_ALIGN)
1248 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1251 : Sets the pad at the end of the "header".
1254 : Controls the alignment of the beginning of the data for
1255 fixed size variables.
1258 : Sets the pad at the end of the data for fixed size
1262 : Controls the alignment of the beginning of the data for
1263 variables which have an unlimited dimension (record variables).
1268 NF\_\_ENDDEF returns the value NF\_NOERR if no errors occurred.
1269 Otherwise, the returned status indicates an error. Possible causes of
1272 - The specified netCDF dataset is not in define mode.
1273 - The specified netCDF ID does not refer to an open netCDF dataset.
1274 - The size of one or more variables exceed the size constraints for
1275 whichever variant of the file format is in use). See [(netcdf)Large
1276 File Support](netcdf.html#Large-File-Support) ‘Large File
1277 Support’ in The NetCDF Users Guide.
1282 Here is an example using NF\_\_ENDDEF to finish the definitions of a new
1283 netCDF dataset named foo.nc and put it into data mode:
1287 INCLUDE 'netcdf.inc'
1289 INTEGER NCID, STATUS, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN
1291 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1292 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1294 ... ! create dimensions, variables, attributes
1300 STATUS = NF_ENDDEF(NCID, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN)
1301 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1305 2.14 NF_CLOSE {#f77_NF-CLOSE}
1308 The function NF\_CLOSE closes an open netCDF dataset. If the dataset is
1309 in define mode, NF\_ENDDEF will be called before closing. (In this case,
1310 if NF\_ENDDEF returns an error, NF\_ABORT will automatically be called
1311 to restore the dataset to the consistent state before define mode was
1312 last entered.) After an open netCDF dataset is closed, its netCDF ID may
1313 be reassigned to the next netCDF dataset that is opened or created.
1321 INTEGER FUNCTION NF_CLOSE(INTEGER NCID)
1325 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1330 NF\_CLOSE returns the value NF\_NOERR if no errors occurred. Otherwise,
1331 the returned status indicates an error. Possible causes of errors
1334 - Define mode was entered and the automatic call made to NF\_ENDDEF
1336 - The specified netCDF ID does not refer to an open netCDF dataset.
1341 Here is an example using NF\_CLOSE to finish the definitions of a new
1342 netCDF dataset named foo.nc and release its netCDF ID:
1347 INCLUDE 'netcdf.inc'
1349 INTEGER NCID, STATUS
1351 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1352 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1354 ... ! create dimensions, variables, attributes
1356 STATUS = NF_CLOSE(NCID)
1357 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1360 2.15 NF_INQ Family {#f77_NF-INQ-Family}
1363 Members of the NF\_INQ family of functions return information about an
1364 open netCDF dataset, given its netCDF ID. Dataset inquire functions may
1365 be called from either define mode or data mode. The first function,
1366 NF\_INQ, returns values for the number of dimensions, the number of
1367 variables, the number of global attributes, and the dimension ID of the
1368 dimension defined with unlimited length, if any. The other functions in
1369 the family each return just one of these items of information.
1371 For FORTRAN, these functions include NF\_INQ, NF\_INQ\_NDIMS,
1372 NF\_INQ\_NVARS, NF\_INQ\_NATTS, and NF\_INQ\_UNLIMDIM. An additional
1373 function, NF\_INQ\_FORMAT, returns the (rarely needed) format version.
1375 No I/O is performed when these functions are called, since the required
1376 information is available in memory for each open netCDF dataset.
1384 INTEGER FUNCTION NF_INQ (INTEGER NCID, INTEGER ndims,
1385 INTEGER nvars,INTEGER ngatts,
1387 INTEGER FUNCTION NF_INQ_NDIMS (INTEGER NCID, INTEGER ndims)
1388 INTEGER FUNCTION NF_INQ_NVARS (INTEGER NCID, INTEGER nvars)
1389 INTEGER FUNCTION NF_INQ_NATTS (INTEGER NCID, INTEGER ngatts)
1390 INTEGER FUNCTION NF_INQ_UNLIMDIM (INTEGER NCID, INTEGER unlimdimid)
1391 INTEGER FUNCTION NF_INQ_FORMAT (INTEGER NCID, INTEGER format)
1395 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1398 : Returned number of dimensions defined for this netCDF dataset.
1401 : Returned number of variables defined for this netCDF dataset.
1404 : Returned number of global attributes defined for this netCDF
1408 : Returned ID of the unlimited dimension, if there is one for this
1409 netCDF dataset. If no unlimited length dimension has been defined,
1413 : Returned format version, one of NF\_FORMAT\_CLASSIC,
1414 NF\_FORMAT\_64BIT, NF\_FORMAT\_NETCDF4,
1415 NF\_FORMAT\_NETCDF4\_CLASSIC.
1420 All members of the NF\_INQ family return the value NF\_NOERR if no
1421 errors occurred. Otherwise, the returned status indicates an error.
1422 Possible causes of errors include:
1424 - The specified netCDF ID does not refer to an open netCDF dataset.
1429 Here is an example using NF\_INQ to find out about a netCDF dataset
1434 INCLUDE 'netcdf.inc'
1436 INTEGER STATUS, NCID, NDIMS, NVARS, NGATTS, UNLIMDIMID
1438 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
1439 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1441 STATUS = NF_INQ(NCID, NDIMS, NVARS, NGATTS, UNLIMDIMID)
1442 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1446 2.16 NF_SYNC {#f77_NF-SYNC}
1449 The function NF\_SYNC offers a way to synchronize the disk copy of a
1450 netCDF dataset with in-memory buffers. There are two reasons you might
1451 want to synchronize after writes:
1453 - To minimize data loss in case of abnormal termination, or
1454 - To make data available to other processes for reading immediately
1455 after it is written. But note that a process that already had the
1456 dataset open for reading would not see the number of records
1457 increase when the writing process calls NF\_SYNC; to accomplish
1458 this, the reading process must call NF\_SYNC.
1460 This function is backward-compatible with previous versions of the
1461 netCDF library. The intent was to allow sharing of a netCDF dataset
1462 among multiple readers and one writer, by having the writer call
1463 NF\_SYNC after writing and the readers call NF\_SYNC before each read.
1464 For a writer, this flushes buffers to disk. For a reader, it makesre
1465 that the next read will be from disk rather than from previously cached
1466 buffers, so that the reader will see changes made by the writing process
1467 (e.g., the number of records written) without having to close and reopen
1468 the dataset. If you are only accessing a small amount of data, it can be
1469 expensive in computer resources to always synchronize to disk after
1470 every write, since you are giving up the benefits of buffering.
1472 An easier way to accomplish sharing (and what is now recommended) is to
1473 have the writer and readers open the dataset with the NF\_SHARE flag,
1474 and then it will not be necessary to call NF\_SYNC at all. However, the
1475 NF\_SYNC function still provides finer granularity than the NF\_SHARE
1476 flag, if only a few netCDF accesses need to be synchronized among
1479 It is important to note that changes to the ancillary data,ch as
1480 attribute values, are not propagated automatically by use of the
1481 NF\_SHARE flag. Use of the NF\_SYNC function is still required for this
1484 Sharing datasets when the writer enters define mode to change the data
1485 schema requires extra care. In previous releases, after the writer left
1486 define mode, the readers were left looking at an old copy of the
1487 dataset, since the changes were made to a new copy. The only way readers
1488 could see the changes was by closing and reopening the dataset. Now the
1489 changes are made in place, but readers have no knowledge that their
1490 internal tables are now inconsistent with the new dataset schema. If
1491 netCDF datasets are shared across redefinition, some mechanism external
1492 to the netCDF library must be provided that prevents access by readers
1493 during redefinition and causes the readers to call NF\_SYNC before any
1496 When calling NF\_SYNC, the netCDF dataset must be in data mode. A netCDF
1497 dataset in define mode is synchronized to disk only when NF\_ENDDEF is
1498 called. A process that is reading a netCDF dataset that another process
1499 is writing may call NF\_SYNC to get updated with the changes made to the
1500 data by the writing process (e.g., the number of records written),
1501 without having to close and reopen the dataset.
1503 Data is automatically synchronized to disk when a netCDF dataset is
1504 closed, or whenever you leave define mode.
1512 INTEGER FUNCTION NF_SYNC(INTEGER NCID)
1516 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1521 NF\_SYNC returns the value NF\_NOERR if no errors occurred. Otherwise,
1522 the returned status indicates an error. Possible causes of errors
1525 - The netCDF dataset is in define mode.
1526 - The specified netCDF ID does not refer to an open netCDF dataset.
1531 Here is an example using NF\_SYNC to synchronize the disk writes of a
1532 netCDF dataset named foo.nc:
1537 INCLUDE 'netcdf.inc'
1539 INTEGER STATUS, NCID
1541 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1542 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1544 ! write data or change attributes
1546 STATUS = NF_SYNC(NCID)
1547 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1550 2.17 NF_ABORT {#f77_NF-ABORT}
1553 You no longer need to call this function, since it is called
1554 automatically by NF\_CLOSE in case the dataset is in define mode and
1555 something goes wrong with committing the changes. The function NF\_ABORT
1556 just closes the netCDF dataset, if not in define mode. If the dataset is
1557 being created and is still in define mode, the dataset is deleted. If
1558 define mode was entered by a call to NF\_REDEF, the netCDF dataset is
1559 restored to its state before definition mode was entered and the dataset
1568 INTEGER FUNCTION NF_ABORT(INTEGER NCID)
1572 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1577 NF\_ABORT returns the value NF\_NOERR if no errors occurred. Otherwise,
1578 the returned status indicates an error. Possible causes of errors
1581 - When called from define mode while creating a netCDF dataset,
1582 deletion of the dataset failed.
1583 - The specified netCDF ID does not refer to an open netCDF dataset.
1588 Here is an example using NF\_ABORT to back out of redefinitions of a
1589 dataset named foo.nc:
1593 INCLUDE 'netcdf.inc'
1595 INTEGER STATUS, NCID, LATID
1597 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1598 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1600 STATUS = NF_REDEF(NCID)
1601 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1603 STATUS = NF_DEF_DIM(NCID, 'LAT', 18, LATID)
1604 IF (STATUS .NE. NF_NOERR) THEN ! dimension definition failed
1605 CALL HANDLE_ERR(STATUS)
1606 STATUS = NF_ABORT(NCID) ! abort redefinitions
1607 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1613 2.18 NF_SET_FILL {#f77_NF-SET-FILL}
1616 This function is intended for advanced usage, to optimize writes under
1617 some circumstances described below. The function NF\_SET\_FILL sets the
1618 fill mode for a netCDF dataset open for writing and returns the current
1619 fill mode in a return parameter. The fill mode can be specified as
1620 either NF\_FILL or NF\_NOFILL. The default behavior corresponding to
1621 NF\_FILL is that data is pre-filled with fill values, that is fill
1622 values are written when you create non-record variables or when you
1623 write a value beyond data that has not yet been written. This makes it
1624 possible to detect attempts to read data before it was written. See
1625 section [Fill Values](#Fill-Values), for more information on the use of
1626 fill values. See [(netcdf)Attribute
1627 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
1628 Conventions’ in The NetCDF Users Guide, for information about how to
1629 define your own fill values.
1631 The behavior corresponding to NF\_NOFILL overrides the default behavior
1632 of prefilling data with fill values. This can be used to enhance
1633 performance, because it avoids the duplicate writes that occur when the
1634 netCDF library writes fill values that are later overwritten with data.
1636 A value indicating which mode the netCDF dataset was already in is
1637 returned. You can use this value to temporarily change the fill mode of
1638 an open netCDF dataset and then restore it to the previous mode.
1640 After you turn on NF\_NOFILL mode for an open netCDF dataset, you must
1641 be certain to write valid data in all the positions that will later be
1642 read. Note that nofill mode is only a transient property of a netCDF
1643 dataset open for writing: if you close and reopen the dataset, it will
1644 revert to the default behavior. You can also revert to the default
1645 behavior by calling NF\_SET\_FILL again to explicitly set the fill mode
1648 There are three situations where it is advantageous to set nofill mode:
1650 1. Creating and initializing a netCDF dataset. In this case, you should
1651 set nofill mode before calling NF\_ENDDEF and then write completely
1652 all non-record variables and the initial records of all the record
1653 variables you want to initialize.
1654 2. Extending an existing record-oriented netCDF dataset. Set nofill
1655 mode after opening the dataset for writing, then append the
1656 additional records to the dataset completely, leaving no intervening
1658 3. Adding new variables that you are going to initialize to an existing
1659 netCDF dataset. Set nofill mode before calling NF\_ENDDEF then write
1660 all the new variables completely.
1662 If the netCDF dataset has an unlimited dimension and the last record was
1663 written while in nofill mode, then the dataset may be shorter than if
1664 nofill mode was not set, but this will be completely transparent if you
1665 access the data only through the netCDF interfaces.
1667 The use of this feature may not be available (or even needed) in future
1668 releases. Programmers are cautioned against heavy reliance upon this
1677 INTEGER FUNCTION NF_SET_FILL(INTEGER NCID, INTEGER FILLMODE,
1682 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1685 : Desired fill mode for the dataset, either NF\_NOFILL or NF\_FILL.
1688 : Returned current fill mode of the dataset before this call, either
1689 NF\_NOFILL or NF\_FILL.
1694 NF\_SET\_FILL returns the value NF\_NOERR if no errors occurred.
1695 Otherwise, the returned status indicates an error. Possible causes of
1698 - The specified netCDF ID does not refer to an open netCDF dataset.
1699 - The specified netCDF ID refers to a dataset open for read-only
1701 - The fill mode argument is neither NF\_NOFILL nor NF\_FILL..
1706 Here is an example using NF\_SET\_FILL to set nofill mode forbsequent
1707 writes of a netCDF dataset named foo.nc:
1711 INCLUDE 'netcdf.inc'
1713 INTEGER NCID, STATUS, OMODE
1715 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1716 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1718 ! write data with default prefilling behavior
1720 STATUS = NF_SET_FILL(NCID, NF_NOFILL, OMODE)
1721 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1723 ! write data with no prefilling
1728 2.19 NF_SET_DEFAULT_FORMAT {#f77_NF-SET-DEFAULT-FORMAT}
1729 -----------------------------
1731 This function is intended for advanced users.
1733 In version 3.6, netCDF introduced a new data format, the first change in
1734 the underlying binary data format since the netCDF interface was
1735 released. The new format, 64-bit offset format, was introduced to
1736 greatly relax the limitations on creating very large files.
1738 In version 4.0, another new binary format was introduced: netCDF-4/HDF5.
1740 Users are warned that creating files in the 64-bit offset format makes
1741 them unreadable by the netCDF library prior to version 3.6.0, and
1742 creating files in netcdf-4/HDF5 format makes them unreadable by the
1743 netCDF library prior to version 4.0. For reasons of compatibility, users
1744 should continue to create files in netCDF classic format.
1746 Users who do want to use 64-bit offset or netCDF-4/HDF5 format files can
1747 create them directory from NF\_CREATE, using the proper cmode flag. (see
1748 section [NF\_CREATE](#NF_005fCREATE)).
1750 The function NF\_SET\_DEFAULT\_FORMAT allows the user to change the
1751 format of the netCDF file to be created by future calls to NF\_CREATE
1752 without changing the cmode flag.
1754 This allows the user to convert a program to use the new formats without
1755 changing all calls the NF\_CREATE.
1757 Once the default format is set, all future created files will be in the
1760 Constants are provided in the netcdf.inc file to be used with this
1761 function: nf\_format\_classic, nf\_format\_64bit, nf\_format\_netcdf4
1762 and nf\_format\_netcdf4\_classic.
1770 INTEGER FUNCTION NF_SET_DEFAULT_FORMAT(INTEGER FORMAT, INTEGER OLD_FORMT)
1774 : Either nf\_format\_classic, nf\_format\_64bit, nf\_format\_netcdf4
1775 or nf\_format\_netcdf4\_classic.
1778 : The default format at the time the function is called is returned
1784 The following error codes may be returned by this function:
1786 - An NF\_EINVAL error is returned if an invalid default format is
1795 INCLUDE 'netcdf.inc'
1797 INTEGER STATUS, OLD_FORMAT
1799 STATUS = NF_SET_DEFAULT_FORMAT(nf_format_64bit, OLD_FORMAT)
1800 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1804 2.20 Set HDF5 Chunk Cache for Future File Opens/Creates: NF_SET_CHUNK_CACHE {#f77_Set-HDF5-Chunk}
1805 ------------------------------------------------------------------------------
1807 This function changes the chunk cache settings in the HDF5 library. The
1808 settings apply forbsequent file opens/creates. This function does not
1809 change the chunk cache settings of already open files.
1811 This affects the per-file chunk cache which the HDF5 layer maintains.
1812 The chunk cache size can be tuned for better performance.
1814 For more information, see the documentation for the H5Pset\_cache()
1815 function in the HDF5 library at the HDF5 website:
1816 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
1824 INTEGER NF_SET_CHUNK_CACHE(INTEGER SIZE, INTEGER NELEMS, INTEGER PREEMPTION);
1828 : The total size of the raw data chunk cache in MegaBytes.
1831 : The number slots in the per-variable chunk cache (should be a prime
1832 number larger than the number of chunks in the cache).
1835 : The preemtion value must be between 0 and 100 inclusive and
1836 indicates how much chunks that have been fully read are favored for
1837 preemption. A value of zero means fully read chunks are treated no
1838 differently than other chunks (the preemption is strictly LRU) while
1839 a value of 100 means fully read chunks are always preempted before
1849 : Parameters size and nelems must be non-zero positive integers, and
1850 preemption must be between zero and 100 (inclusive). An NF\_EINVAL
1851 will be returned otherwise.
1855 2.21 Get the HDF5 Chunk Cache Settings for Future File Opens/Creates: NF_GET_CHUNK_CACHE {#f77_NF-GET-CHUNK-CACHE}
1856 -------------------------------------------------------------------------------------------
1858 This function gets the chunk cache settings for the HDF5 library. The
1859 settings apply forbsequent file opens/creates.
1861 This affects the per-file chunk cache which the HDF5 layer maintains.
1862 The chunk cache size can be tuned for better performance.
1864 For more information, see the documentation for the H5Pget\_cache()
1865 function in the HDF5 library at the HDF5 website:
1866 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
1874 INTEGER NC_GET_CHUNK_CACHE(INTEGER SIZE, INTEGER NELEMS, INTEGER PREEMPTION);
1878 : The total size of the raw data chunk cache will be put here.
1881 : The number of chunk slots in the raw data chunk cache hash table
1885 : The preemption will be put here. The preemtion value is between 0
1886 and 100 inclusive and indicates how much chunks that have been fully
1887 read are favored for preemption. A value of zero means fully read
1888 chunks are treated no differently than other chunks (the preemption
1889 is strictly LRU) while a value of 100 means fully read chunks are
1890 always preempted before other chunks.
1898 3. Groups {#f77_Groups}
1901 NetCDF-4 addedpport for hierarchical groups within netCDF datasets.
1903 Groups are identified with a ncid, which identifies both the open file,
1904 and the group within that file. When a file is opened with NF\_OPEN or
1905 NF\_CREATE, the ncid for the root group of that file is provided. Using
1906 that as a starting point, users can add new groups, or list and navigate
1909 All netCDF calls take a ncid which determines where the call will take
1910 its action. For example, the NF\_DEF\_VAR function takes a ncid as its
1911 first parameter. It will create a variable in whichever group its ncid
1912 refers to. Use the root ncid provided by NF\_CREATE or NF\_OPEN to
1913 create a variable in the root group. Or use NF\_DEF\_GRP to create a
1914 group and use its ncid to define a variable in the new group.
1916 Variable are only visible in the group in which they are defined. The
1917 same applies to attributes. “Global” attributes are defined in whichever
1918 group is refered to by the ncid.
1920 Dimensions are visible in their groups, and all child groups.
1922 Group operations are only permitted on netCDF-4 files - that is, files
1923 created with the HDF5 flag in nf\_create. (see
1924 [NF\_CREATE](#NF_005fCREATE)). Groups are not compatible with the netCDF
1925 classic data model, so files created with the NF\_CLASSIC\_MODEL file
1926 cannot contain groups (except the root group).
1928 3.1 Find a Group ID: NF_INQ_NCID {#f77_NF-INQ-NCID}
1929 ----------------------------------
1931 Given an ncid and group name (NULL or "" gets root group), return ncid
1940 INTEGER FUNCTION NF_INQ_NCID(INTEGER NCID, CHARACTER*(*) NAME, INTEGER GRPID)
1944 : The group id for this operation.
1947 : A character array that holds the name of the desired group. Must be
1948 less then NF\_MAX\_NAME.
1951 : The ID of the group will go here.
1963 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
1964 operations can only be performed on files defined with a create mode
1965 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
1968 : This file was created with the strict netcdf-3 flag, therefore
1969 netcdf-4 operations are not allowed. (see
1970 [NF\_OPEN](#NF_005fOPEN)).
1973 : An error was reported by the HDF5 layer.
1978 This example is from nf\_test/ftst\_groups.F.
1983 C Check getting the group by name
1984 retval = nf_inq_ncid(ncid, group_name, grpid_in)
1985 if (retval .ne. nf_noerr) call handle_err(retval)
1988 3.2 Get a List of Groups in a Group: NF_INQ_GRPS {#f77_NF-INQ-GRPS}
1989 --------------------------------------------------
1991 Given a location id, return the number of groups it contains, and an
1992 array of their ncids.
2000 INTEGER FUNCTION NF_INQ_GRPS(INTEGER NCID, INTEGER NUMGRPS, INTEGER NCIDS)
2004 : The group id for this operation.
2007 : An integer which will get number of groups in this group.
2010 : An array of ints which will receive the IDs of all the groups in
2023 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2024 operations can only be performed on files defined with a create mode
2025 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2028 : This file was created with the strict netcdf-3 flag, therefore
2029 netcdf-4 operations are not allowed. (see
2030 [NF\_OPEN](#NF_005fOPEN)).
2033 : An error was reported by the HDF5 layer.
2038 This example is from nf\_test/ftst\_groups.F.
2043 C What groups are there from the root group?
2044 retval = nf_inq_grps(ncid, ngroups_in, grpids)
2045 if (retval .ne. nf_noerr) call handle_err(retval)
2048 3.3 Find all the Variables in a Group: NF_INQ_VARIDS {#f77_NF-INQ-VARIDS}
2049 ------------------------------------------------------
2051 Find all varids for a location.
2059 INTEGER FUNCTION NF_INQ_VARIDS(INTEGER NCID, INTEGERS VARIDS)
2063 : The group id for this operation.
2066 : An already allocated array to store the list of varids. Use
2067 nf\_inq\_nvars to find out how many variables there are. (see
2068 [NF\_INQ Family](#NF_005fINQ-Family)).
2080 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2081 operations can only be performed on files defined with a create mode
2082 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2085 : This file was created with the strict netcdf-3 flag, therefore
2086 netcdf-4 operations are not allowed. (see
2087 [NF\_OPEN](#NF_005fOPEN)).
2090 : An error was reported by the HDF5 layer.
2095 This example is from nf\_test/ftst\_groups.F.
2100 C Check varids inbgroup.
2101 retval = nf_inq_varidsbgrp_in, nvars, varids_in)
2102 if (retval .ne. nf_noerr) call handle_err(retval)
2105 3.4 Find all Dimensions Visible in a Group: NF_INQ_DIMIDS {#f77_NF-INQ-DIMIDS}
2106 -----------------------------------------------------------
2108 Find all dimids for a location. This finds all dimensions in a group, or
2117 INTEGER FUNCTION NF_INQ_DIMIDS(INTEGER NCID, INTEGER NDIMS, INTEGER DIMIDS, INTEGER INCLUDE_PARENTS)
2121 : The group id for this operation.
2124 : Returned number of dimensions for this location. If INCLUDE\_PARENTS
2125 is non-zero, number of dimensions visible from this group, which
2126 includes dimensions in parent groups.
2129 : An array of ints when the dimids of the visible dimensions will be
2130 stashed. Use nf\_inq\_ndims to find out how many dims are visible
2131 from this group. (see [NF\_INQ Family](#NF_005fINQ-Family)).
2134 : If zero, only the group specified by NCID will be searched for
2135 dimensions. Otherwise parent groups will be searched too.
2147 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2148 operations can only be performed on files defined with a create mode
2149 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2152 : This file was created with the strict netcdf-3 flag, therefore
2153 netcdf-4 operations are not allowed. (see
2154 [NF\_OPEN](#NF_005fOPEN)).
2157 : An error was reported by the HDF5 layer.
2162 This example is from nf\_test/ftst\_groups.F.
2167 C Check dimids inbgroup.
2168 retval = nf_inq_dimidsbgrp_in, ndims, dimids_in, 0)
2169 if (retval .ne. nf_noerr) call handle_err(retval)
2170 if (ndims .ne. 2 .or. dimids_in(1) .ne. dimids(1) .or.
2171 & dimids_in(2) .ne. dimids(2)) stop 2
2174 3.5 Find the Length of a Group’s Name: NF_INQ_GRPNAME_LE {#f77_NF-INQ-GRPNAME-LE}
2175 ------------------------------------------------------------
2177 Given ncid, find length of the full name. (Root group is named "/", with
2186 INTEGER FUNCTION NF_INQ_GRPNAME_LEN(INTEGER NCID, INTEGER LEN)
2190 : The group id for this operation.
2193 : An integer where the length will be placed.
2205 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2206 operations can only be performed on files defined with a create mode
2207 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2210 : This file was created with the strict netcdf-3 flag, therefore
2211 netcdf-4 operations are not allowed. (see
2212 [NF\_OPEN](#NF_005fOPEN)).
2215 : An error was reported by the HDF5 layer.
2220 This example is from nf\_test/ftst\_groups.F.
2225 C Check the length of the full name.
2226 retval = nf_inq_grpname_len(grpids(1), full_name_len)
2227 if (retval .ne. nf_noerr) call handle_err(retval)
2230 3.6 Find a Group’s Name: NF_INQ_GRPNAME {#f77_NF-INQ-GRPNAME}
2231 -----------------------------------------
2233 Given ncid, find relative name of group. (Root group is named "/").
2235 The name provided by this function is relative to the parent group. For
2236 a full path name for the group is, with all parent groups included,
2237 separated with a forward slash (as in Unix directory names) See
2238 [Find a Group’s Full Name:
2239 NF\_INQ\_GRPNAME\_FULL](#NF_005fINQ_005fGRPNAME_005fFULL).
2247 INTEGER FUNCTION NF_INQ_GRPNAME(INTEGER NCID, CHARACTER*(*) NAME)
2252 The group id for this operation.
2256 The name of the group will be copied to this character array. The name
2257 will be less than NF\_MAX\_NAME in length.
2271 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2272 operations can only be performed on files defined with a create mode
2273 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2276 : This file was created with the strict netcdf-3 flag, therefore
2277 netcdf-4 operations are not allowed. (see
2278 [NF\_OPEN](#NF_005fOPEN)).
2281 : An error was reported by the HDF5 layer.
2286 This example is from nf\_test/ftst\_groups.F.
2291 C Check the name of the root group.
2292 retval = nf_inq_grpname(ncid, name_in)
2293 if (retval .ne. nf_noerr) call handle_err(retval)
2294 if (name_in(1:1) .ne. '/') stop 2
2298 3.7 Find a Group’s Full Name: NF_INQ_GRPNAME_FULL {#f77_NF-INQ-GRPNAME-FULL}
2299 ----------------------------------------------------
2301 Given ncid, find complete name of group. (Root group is named "/").
2303 The name provided by this function is a full path name for the group is,
2304 with all parent groups included, separated with a forward slash (as in
2305 Unix directory names). For a name relative to the parent group See
2306 section [Find a Group’s Name:
2307 NF\_INQ\_GRPNAME](#NF_005fINQ_005fGRPNAME).
2309 To find the length of the full name See [Find the Length of a
2310 Group’s Name: NF\_INQ\_GRPNAME\_LEN](#NF_005fINQ_005fGRPNAME_005fLEN).
2318 INTEGER FUNCTION NF_INQ_GRPNAME_FULL(INTEGER NCID, INTEGER LEN, CHARACTER*(*) NAME)
2322 : The group id for this operation.
2325 : The length of the full group name will go here.
2328 : The name of the group will be copied to this character array.
2340 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2341 operations can only be performed on files defined with a create mode
2342 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2345 : This file was created with the strict netcdf-3 flag, therefore
2346 netcdf-4 operations are not allowed. (see
2347 [NF\_OPEN](#NF_005fOPEN)).
2350 : An error was reported by the HDF5 layer.
2355 This example is from nf\_test/ftst\_groups.F.
2360 C Check the full name.
2361 retval = nf_inq_grpname_full(grpids(1), full_name_len, name_in2)
2362 if (retval .ne. nf_noerr) call handle_err(retval)
2365 3.8 Find a Group’s Parent: NF_INQ_GRP_PARENT {#f77_NF-INQ-GRP-PARENT}
2366 -----------------------------------------------
2368 Given ncid, find the ncid of the parent group.
2370 When used with the root group, this function returns the NF\_ENOGRP
2371 error (since the root group has no parent.)
2379 INTEGER FUNCTION NF_INQ_GRP_PARENT(INTEGER NCID, INTEGER PARENT_NCID)
2386 : The ncid of the parent group will be copied here.
2398 : No parent group found (i.e. this is the root group).
2401 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2402 operations can only be performed on files defined with a create mode
2403 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2406 : This file was created with the strict netcdf-3 flag, therefore
2407 netcdf-4 operations are not allowed. (see
2408 [NF\_OPEN](#NF_005fOPEN)).
2411 : An error was reported by the HDF5 layer.
2416 This example is from nf\_test/ftst\_groups.F.
2421 C Check the parent ncid.
2422 retval = nf_inq_grp_parent(grpids(1), grpid_in)
2423 if (retval .ne. nf_noerr) call handle_err(retval)
2426 3.9 Find a Group by Name: NF_INQ_GRP_NCID {#f77_NF-INQ-GRP-NCID}
2427 --------------------------------------------
2429 Given a group name an an ncid, find the ncid of the group id.
2437 INTEGER FUNCTION NF_INQ_GRP_NCID(INTEGER NCID, CHARACTER GRP_NAME, INTEGER GRP_NCID)
2441 : The group id to look in.
2444 : The name of the group that should be found.
2447 : This will get the group id, if it is found.
2452 The following return codes may be returned by this function.
2461 : No name provided or name longer than NF\_MAX\_NAME.
2464 : Named group not found.
2467 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2468 operations can only be performed on files defined with a create mode
2469 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2472 : This file was created with the strict netcdf-3 flag, therefore
2473 netcdf-4 operations are not allowed. (see
2474 [NF\_OPEN](#NF_005fOPEN)).
2477 : An error was reported by the HDF5 layer.
2482 This example is from nf\_test/ftst\_types3.F.
2487 C Go to a child group and find the id of our type.
2488 retval = nf_inq_grp_ncid(ncid, group_name,b_grpid)
2489 if (retval .ne. nf_noerr) call handle_err(retval)
2492 3.10 Find a Group by its Fully-qualified Name: NF_INQ_GRP_FULL_NCID {#f77_NF-INQ-GRP-FULL-NCID}
2493 -----------------------------------------------------------------------
2495 Given a fully qualified group name an an ncid, find the ncid of the
2504 INTEGER FUNCTION NF_INQ_GRP_FULL_NCID(INTEGER NCID, CHARACTER FULL_NAME, INTEGER GRP_NCID)
2508 : The group id to look in.
2511 : The fully-qualified group name.
2514 : This will get the group id, if it is found.
2519 The following return codes may be returned by this function.
2528 : No name provided or name longer than NF\_MAX\_NAME.
2531 : Named group not found.
2534 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2535 operations can only be performed on files defined with a create mode
2536 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2539 : This file was created with the strict netcdf-3 flag, therefore
2540 netcdf-4 operations are not allowed. (see
2541 [NF\_OPEN](#NF_005fOPEN)).
2544 : An error was reported by the HDF5 layer.
2549 This example is from nf\_test/ftst\_groups.F.
2554 C Check the full name of the root group (also "/").
2555 retval = nf_inq_grpname_full(ncid, full_name_len, name_in)
2556 if (retval .ne. nf_noerr) call handle_err(retval)
2559 3.11 Create a New Group: NF_DEF_GRP {#f77_NF-DEF-GRP}
2560 -------------------------------------
2562 Create a group. Its location id is returned in new\_ncid.
2570 INTEGER FUNCTION NF_DEF_GRP(INTEGER PARENT_NCID, CHARACTER*(*) NAME,
2575 : The group id of the parent group.
2578 : The name of the new group, which must be different from the name of
2579 any variable within the same parent group.
2582 : The ncid of the new group will be placed there.
2594 : That name is in use. Group names must be unique within a group.
2597 : Name exceed max length NF\_MAX\_NAME.
2600 : Name contains illegal characters.
2603 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2604 operations can only be performed on files defined with a create mode
2605 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2608 : This file was created with the strict netcdf-3 flag, therefore
2609 netcdf-4 operations are not allowed. (see
2610 [NF\_OPEN](#NF_005fOPEN)).
2613 : An error was reported by the HDF5 layer.
2616 : Attempt to write to a read-only file.
2619 : Not in define mode.
2624 In this exampe rom nf\_test/ftst\_groups.F, a groups is reated, and then
2625 ab-group is created in that group.
2630 C Create the netCDF file.
2631 retval = nf_create(file_name, NF_NETCDF4, ncid)
2632 if (retval .ne. nf_noerr) call handle_err(retval)
2634 C Create a group and abgroup.
2635 retval = nf_def_grp(ncid, group_name, grpid)
2636 if (retval .ne. nf_noerr) call handle_err(retval)
2637 retval = nf_def_grp(grpid,b_group_name,b_grpid)
2638 if (retval .ne. nf_noerr) call handle_err(retval)
2641 4. Dimensions {#f77_Dimensions}
2644 4.1 Dimensions Introduction {#f77_Dimensions-Introduction}
2645 ---------------------------
2647 Dimensions for a netCDF dataset are defined when it is created, while
2648 the netCDF dataset is in define mode. Additional dimensions may be added
2649 later by reentering define mode. A netCDF dimension has a name and a
2650 length. At most one dimension in a netCDF dataset can have the unlimited
2651 length, which means variables using this dimension can grow along this
2654 There is aggested limit (100) to the number of dimensions that can be
2655 defined in a single netCDF dataset. The limit is the value of the
2656 predefined macro NF\_MAX\_DIMS. The purpose of the limit is to make
2657 writing generic applications simpler. They need only provide an array of
2658 NF\_MAX\_DIMS dimensions to handle any netCDF dataset. The
2659 implementation of the netCDF library does not enforce this advisory
2660 maximum, so it is possible to use more dimensions, if necessary, but
2661 netCDF utilities that ame the advisory maximums may not be able to
2662 handle the rlting netCDF datasets.
2664 Ordinarily, the name and length of a dimension are fixed when the
2665 dimension is first defined. The name may be changed later, but the
2666 length of a dimension (other than the unlimited dimension) cannot be
2667 changed without copying all the data to a new netCDF dataset with a
2668 redefined dimension length.
2670 A netCDF dimension in an open netCDF dataset is referred to by a small
2671 integer called a dimension ID. In the FORTRAN interface, dimension IDs
2672 are 1, 2, 3, ..., in the order in which the dimensions were defined.
2674 Operationspported on dimensions are:
2676 - Create a dimension, given its name and length.
2677 - Get a dimension ID from its name.
2678 - Get a dimension’s name and length from its ID.
2679 - Rename a dimension.
2681 4.2 NF_DEF_DIM {#f77_NF-DEF-DIM}
2684 The function NF\_DEF\_DIM adds a new dimension to an open netCDF dataset
2685 in define mode. It returns (as an argument) a dimension ID, given the
2686 netCDF ID, the dimension name, and the dimension length. At most one
2687 unlimited length dimension, called the record dimension, may be defined
2688 for each netCDF dataset.
2696 INTEGER FUNCTION NF_DEF_DIM (INTEGER NCID, CHARACTER*(*) NAME,
2697 INTEGER LEN, INTEGER dimid)
2701 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2707 : Length of dimension; that is, number of values for this dimension as
2708 an index to variables that use it. This should be either a positive
2709 integer or the predefined constant NF\_UNLIMITED.
2712 : Returned dimension ID.
2717 NF\_DEF\_DIM returns the value NF\_NOERR if no errors occurred.
2718 Otherwise, the returned status indicates an error. Possible causes of
2721 - The netCDF dataset is not in definition mode.
2722 - The specified dimension name is the name of another existing
2724 - The specified length is not greater than zero.
2725 - The specified length is unlimited, but there is already an unlimited
2726 length dimension defined for this netCDF dataset.
2727 - The specified netCDF ID does not refer to an open netCDF dataset.
2732 Here is an example using NF\_DEF\_DIM to create a dimension named lat of
2733 length 18 and a unlimited dimension named rec in a new netCDF dataset
2739 INCLUDE 'netcdf.inc'
2741 INTEGER STATUS, NCID, LATID, RECID
2743 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
2744 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2746 STATUS = NF_DEF_DIM(NCID, 'lat', 18, LATID)
2747 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2748 STATUS = NF_DEF_DIM(NCID, 'rec', NF_UNLIMITED, RECID)
2749 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2752 4.3 NF_INQ_DIMID {#f77_NF-INQ-DIMID}
2755 The function NF\_INQ\_DIMID returns (as an argument) the ID of a netCDF
2756 dimension, given the name of the dimension. If ndims is the number of
2757 dimensions defined for a netCDF dataset, each dimension has an ID
2758 between 1 and ndims.
2766 INTEGER FUNCTION NF_INQ_DIMID (INTEGER NCID, CHARACTER*(*) NAME,
2771 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2777 : Returned dimension ID.
2782 NF\_INQ\_DIMID returns the value NF\_NOERR if no errors occurred.
2783 Otherwise, the returned status indicates an error. Possible causes of
2786 - The name that was specified is not the name of a dimension in the
2788 - The specified netCDF ID does not refer to an open netCDF dataset.
2793 Here is an example using NF\_INQ\_DIMID to determine the dimension ID of
2794 a dimension named lat, amed to have been defined previously in an
2795 existing netCDF dataset named foo.nc:
2800 INCLUDE 'netcdf.inc'
2802 INTEGER STATUS, NCID, LATID
2804 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
2805 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2807 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2808 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2811 4.4 NF_INQ_DIM Family {#f77_NF-INQ-DIM-Family}
2812 -----------------------
2814 This family of functions returns information about a netCDF dimension.
2815 Information about a dimension includes its name and its length. The
2816 length for the unlimited dimension, if any, is the number of records
2819 The functions in this family include NF\_INQ\_DIM, NF\_INQ\_DIMNAME, and
2820 NF\_INQ\_DIMLEN. The function NF\_INQ\_DIM returns all the information
2821 about a dimension; the other functions each return just one item of
2830 INTEGER FUNCTION NF_INQ_DIM (INTEGER NCID, INTEGER DIMID,
2831 CHARACTER*(*) name, INTEGER len)
2832 INTEGER FUNCTION NF_INQ_DIMNAME (INTEGER NCID, INTEGER DIMID,
2834 INTEGER FUNCTION NF_INQ_DIMLEN (INTEGER NCID, INTEGER DIMID,
2839 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2842 : Dimension ID, from a previous call to NF\_INQ\_DIMID or
2846 : Returned dimension name. The caller must allocate space for the
2847 returned name. The maximum possible length, in characters, of a
2848 dimension name is given by the predefined constant NF\_MAX\_NAME.
2851 : Returned length of dimension. For the unlimited dimension, this is
2852 the current maximum value used for writing any variables with this
2853 dimension, that is the maximum record number.
2858 These functions return the value NF\_NOERR if no errors occurred.
2859 Otherwise, the returned status indicates an error. Possible causes of
2862 - The dimension ID is invalid for the specified netCDF dataset.
2863 - The specified netCDF ID does not refer to an open netCDF dataset.
2868 Here is an example using NF\_INQ\_DIM to determine the length of a
2869 dimension named lat, and the name and current maximum length of the
2870 unlimited dimension for an existing netCDF dataset named foo.nc:
2875 INCLUDE 'netcdf.inc'
2877 INTEGER STATUS, NCID, LATID, LATLEN, RECID, NRECS
2878 CHARACTER*(NF_MAX_NAME) LATNAM, RECNAM
2880 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
2881 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2882 ! get ID of unlimited dimension
2883 STATUS = NF_INQ_UNLIMDIM(NCID, RECID)
2884 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2886 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2887 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2889 STATUS = NF_INQ_DIMLEN(NCID, LATID, LATLEN)
2890 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2891 ! get unlimited dimension name and current length
2892 STATUS = NF_INQ_DIM(NCID, RECID, RECNAME, NRECS)
2893 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2896 4.5 NF_RENAME_DIM {#f77_NF-RENAME-DIM}
2899 The function NF\_RENAME\_DIM renames an existing dimension in a netCDF
2900 dataset open for writing. If the new name is longer than the old name,
2901 the netCDF dataset must be in define mode. You cannot rename a dimension
2902 to have the same name as another dimension.
2910 INTEGER FUNCTION NF_RENAME_DIM (INTEGER NCID, INTEGER DIMID,
2915 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2918 : Dimension ID, from a previous call to NF\_INQ\_DIMID or
2922 : New dimension name.
2927 NF\_RENAME\_DIM returns the value NF\_NOERR if no errors occurred.
2928 Otherwise, the returned status indicates an error. Possible causes of
2931 - The new name is the name of another dimension.
2932 - The dimension ID is invalid for the specified netCDF dataset.
2933 - The specified netCDF ID does not refer to an open netCDF dataset.
2934 - The new name is longer than the old name and the netCDF dataset is
2940 Here is an example using NF\_RENAME\_DIM to rename the dimension lat to
2941 latitude in an existing netCDF dataset named foo.nc:
2946 INCLUDE 'netcdf.inc'
2948 INTEGER STATUS, NCID, LATID
2950 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
2951 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2953 ! put in define mode to rename dimension
2954 STATUS = NF_REDEF(NCID)
2955 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2956 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2957 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2958 STATUS = NF_RENAME_DIM(NCID, LATID, 'latitude')
2959 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2961 STATUS = NF_ENDDEF(NCID)
2962 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2965 5. User Defined Data Types {#f77_User-Defined-Data-Types}
2966 ==========================
2968 5.1 User Defined Types Introduction {#f77_User-Defined-Types-Introduction}
2969 -----------------------------------
2971 NetCDF-4 has added support for four different user defined data types.
2974 : Like a C struct, a compound type is a collection of types, including
2975 other user defined types, in one package.
2977 `variable length array type`
2978 : The variable length array may be used to store ragged arrays.
2981 : This type has only a size per element, and no other type
2985 : Like an enumeration in C, this type lets you assign text values to
2986 integer values, and store the integer values.
2988 Users may construct user defined type with the various NF\_DEF\_\*
2989 functions described in this. They may learn about user defined
2990 types by using the NF\_INQ\_ functions defined in this.
2992 Once types are constructed, define variables of the new type with
2993 NF\_DEF\_VAR (see [Create a Variable:
2994 `NF_DEF_VAR`](#NF_005fDEF_005fVAR)). Write to them with NF\_PUT\_VAR1,
2995 NF\_PUT\_VAR, NF\_PUT\_VARA, or NF\_PUT\_VARS (see
2996 [Variables](#Variables)). Read data of user-defined type with
2997 NF\_GET\_VAR1, NF\_GET\_VAR, NF\_GET\_VARA, or NF\_GET\_VARS (see
2998 section [Variables](#Variables)).
3000 Create attributes of the new type with NF\_PUT\_ATT (see
3001 [NF\_PUT\_ATT\_ type](#NF_005fPUT_005fATT_005f-type)). Read attributes
3002 of the new type with NF\_GET\_ATT (see [NF\_GET\_ATT\_
3003 type](#NF_005fGET_005fATT_005f-type)).
3005 5.2 Learn the IDs of All Types in Group: NF_INQ_TYPEIDS {#f77_NF-INQ-TYPEIDS}
3006 ---------------------------------------------------------
3008 Learn the number of types defined in a group, and their IDs.
3015 INTEGER FUNCTION NF_INQ_TYPEIDS(INTEGER NCID, INTEGER NTYPES,
3023 : A pointer to int which will get the number of types defined in the
3024 group. If NULL, ignored.
3027 : A pointer to an int array which will get the typeids. If NULL,
3042 The following example is from the test program nf\_test/ftst\_vars3.F.
3047 retval = nf_inq_typeids(ncid, num_types, typeids)
3048 if (retval .ne. nf_noerr) call handle_err(retval)
3052 5.3 Find a Typeid from Group and Name: NF_INQ_TYPEID {#f77_NF-INQ-TYPEID}
3053 ------------------------------------------------------
3055 Given a group ID and a type name, find the ID of the type. If the type
3056 is not found in the group, then the parents are searched. If still not
3057 found, the entire file is searched.
3065 INTEGER FUNCTION NF_INQ_TYPEID(INTEGER NCID, CHARACTER NAME, NF_TYPE TYPEIDP)
3072 : The name of a type.
3075 : The typeid of the named type (if found).
3092 The following example is from nf\_test/ftst\_types3.F:
3097 C Go to a child group and find the id of our type.
3098 retval = nf_inq_grp_ncid(ncid, group_name,b_grpid)
3099 if (retval .ne. nf_noerr) call handle_err(retval)
3100 retval = nf_inq_typeidb_grpid, type_name, typeid_in)
3101 if (retval .ne. nf_noerr) call handle_err(retval)
3104 5.4 Learn About a User Defined Type: NF_INQ_TYPE {#f77_NF-INQ-TYPE}
3105 --------------------------------------------------
3107 Given an ncid and a typeid, get the information about a type. This
3108 function will work on any type, including atomic and any user defined
3109 type, whether compound, opaque, enumeration, or variable length array.
3111 For even more information about a user defined type [Learn About a User
3112 Defined Type: NF\_INQ\_USER\_TYPE](#NF_005fINQ_005fUSER_005fTYPE).
3120 INTEGER FUNCTION NF_INQ_TYPE(INTEGER NCID, INTEGER XTYPE,
3121 CHARACTER*(*) NAME, INTEGER SIZE)
3125 : The ncid for the group containing the type (ignored for atomic
3129 : The typeid for this type, as returned by NF\_DEF\_COMPOUND,
3130 NF\_DEF\_OPAQUE, NF\_DEF\_ENUM, NF\_DEF\_VLEN, or NF\_INQ\_VAR, or
3131 as found in netcdf.inc in the list of atomic types (NF\_CHAR,
3135 : The name of the user defined type will be copied here. It will be
3136 NF\_MAX\_NAME bytes or less. For atomic types, the type name from
3140 : The (in-memory) size of the type (in bytes) will be copied here.
3141 VLEN type size is the size of one vlen sturture (i.e. the sice of
3142 nc\_vlen\_t). String size is returned as the size of one C character
3155 : Seeking a user-defined type in a netCDF-3 file.
3158 : Seeking a user-defined type in a netCDF-4 file for which classic
3159 model has been turned on.
3162 : Bad group ID in ncid.
3165 : Type ID not found.
3168 : An error was reported by the HDF5 layer.
3173 This example is from the test program nf\_test/ftst\_vars3.F, and it
3174 uses all the possible inquiry functions on an enum type.
3179 C Check the enum type.
3180 retval = NF_INQ_TYPEIDS(ncid, num_types, typeids)
3181 if (retval .ne. nf_noerr) call handle_err(retval)
3182 if (num_types .ne. MAX_TYPES) stop 2
3183 retval = nf_inq_enum(ncid, typeids(1), type_name, base_type,
3184 & base_size, num_members)
3185 if (retval .ne. nf_noerr) call handle_err(retval)
3186 if (base_type .ne. NF_INT .or. num_members .ne. 2) stop 2
3187 retval = nf_inq_enum_member(ncid, typeids(1), 1, member_name,
3189 if (retval .ne. nf_noerr) call handle_err(retval)
3190 if (member_name(1:len(one_name)) .ne. one_name) stop 2
3193 5.5 Learn About a User Defined Type: NF_INQ_USER_TYPE {#f77_NF-INQ-USER-TYPE}
3194 --------------------------------------------------------
3196 Given an ncid and a typeid, get the information about a user defined
3197 type. This function will work on any user defined type, whether
3198 compound, opaque, enumeration, or variable length array.
3206 INTEGER FUNCTION NF_INQ_USER_TYPE(INTEGER NCID, INTEGER XTYPE,
3207 CHARACTER*(*) NAME, INTEGER SIZE, INTEGER BASE_NF_TYPE,
3208 INTEGER NFIELDS, INTEGER CLASS)
3212 : The ncid for the group containing the user defined type.
3215 : The typeid for this type, as returned by NF\_DEF\_COMPOUND,
3216 NF\_DEF\_OPAQUE, NF\_DEF\_ENUM, NF\_DEF\_VLEN, or NF\_INQ\_VAR.
3219 : The name of the user defined type will be copied here. It will be
3220 NF\_MAX\_NAME bytes or less.
3223 : The (in-memory) size of the user defined type will be copied here.
3226 : The base typeid will be copied here for vlen and enum types.
3229 : The number of fields will be copied here for enum and compound
3233 : The class of the user defined type, NF\_VLEN, NF\_OPAQUE, NF\_ENUM,
3234 or NF\_COMPOUND, will be copied here.
3249 : An error was reported by the HDF5 layer.
3254 This example is from nf\_test/ftst\_types2.F.
3260 retval = nf_inq_user_type(ncid, typeids(1), name_in, size_in,
3261 & base_type_in, nfields_in, class_in)
3262 if (retval .ne. nf_noerr) call handle_err(retval)
3265 5.6 Compound Types Introduction {#f77_Compound-Types-Introduction}
3266 -------------------------------
3268 NetCDF-4 addedpport for compound types, which allow users to
3269 construct a new type - a combination of other types, like a C struct.
3271 Compound types are notpported in classic or 64-bit offset format
3274 To write data in a compound type, first use nf\_def\_compound to create
3275 the type, multiple calls to nf\_insert\_compound to add to the compound
3276 type, and then write data with the appropriate nf\_put\_var1,
3277 nf\_put\_vara, nf\_put\_vars, or nf\_put\_varm call.
3279 To read data written in a compound type, you must know its structure.
3280 Use the NF\_INQ\_COMPOUND functions to learn about the compound type.
3282 In Fortran a character buffer must be used for the compound data. The
3283 user must read the data from within that buffer in the same way that the
3284 C compiler which compiled netCDF would store the structure.
3286 The use of compound types introduces challenges and portability ies
3289 ### 5.6.1 Creating a Compound Type: NF_DEF_COMPOUND {#f77_NF-DEF-COMPOUND}
3291 Create a compound type. Provide an ncid, a name, and a total size (in
3292 bytes) of one element of the completed compound type.
3294 After calling this function, fill out the type with repeated calls to
3295 NF\_INSERT\_COMPOUND (see [Inserting a Field into a Compound
3296 Type: NF\_INSERT\_COMPOUND](#NF_005fINSERT_005fCOMPOUND)). Call
3297 NF\_INSERT\_COMPOUND once for each field you wish to insert into the
3300 Note that there does not seem to be a way to readch types into
3301 structures in Fortran 90 (and there are no structures in Fortran 77).
3303 Fortran users may use character buffers to read and write compound
3312 INTEGER FUNCTION NF_DEF_COMPOUND(INTEGER NCID, INTEGER SIZE,
3313 CHARACTER*(*) NAME, INTEGER TYPEIDP)
3317 : The groupid where this compound type will be created.
3320 : The size, in bytes, of the compound type.
3323 : The name of the new compound type.
3326 : The typeid of the new type will be placed here.
3338 : That name is in use. Compound type names must be unique in the data
3342 : Name exceeds max length NF\_MAX\_NAME.
3345 : Name contains illegal characters.
3348 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3349 operations can only be performed on files defined with a create mode
3350 which includes flag NF\_NETCDF4. (see
3351 [NF\_OPEN](#NF_005fOPEN)).
3354 : This file was created with the strict netcdf-3 flag, therefore
3355 netcdf-4 operations are not allowed. (see
3356 [NF\_OPEN](#NF_005fOPEN)).
3359 : An error was reported by the HDF5 layer.
3362 : Attempt to write to a read-only file.
3365 : Not in define mode.
3370 This example is from nf\_test/ftst\_types2.F.
3375 C Define a compound type.
3376 retval = nf_def_compound(ncid, cmp_size, type_name,
3378 if (retval .ne. nf_noerr) call handle_err(retval)
3381 ### 5.6.2 Inserting a Field into a Compound Type: NF_INSERT_COMPOUND {#f77_NF-INSERT-COMPOUND}
3383 Insert a named field into a compound type.
3391 INTEGER FUNTION NF_INSERT_COMPOUND(INTEGER TYPEID, CHARACTER*(*) NAME, INTEGER OFFSET,
3392 INTEGER FIELD_TYPEID)
3396 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3400 : The name of the new field.
3403 : Offset in byte from the beginning of the compound type for this
3407 : The type of the field to be inserted.
3419 : That name is in use. Field names must be unique within a compound
3423 : Name exceed max length NF\_MAX\_NAME.
3426 : Name contains illegal characters.
3429 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3430 operations can only be performed on files defined with a create mode
3431 which includes flag NF\_NETCDF4. (see
3432 [NF\_OPEN](#NF_005fOPEN)).
3435 : This file was created with the strict netcdf-3 flag, therefore
3436 netcdf-4 operations are not allowed. (see
3437 [NF\_OPEN](#NF_005fOPEN)).
3440 : An error was reported by the HDF5 layer.
3443 : Not in define mode.
3448 This example is from nf\_test/ftst\_types.F.
3453 C Define a compound type.
3454 retval = nf_def_compound(ncid, WIND_T_SIZE, type_name,
3456 if (retval .ne. nf_noerr) call handle_err(retval)
3457 retval = nf_insert_compound(ncid, wind_typeid, u_name, 0, NF_INT)
3458 if (retval .ne. nf_noerr) call handle_err(retval)
3459 retval = nf_insert_compound(ncid, wind_typeid, v_name, 4, NF_INT)
3460 if (retval .ne. nf_noerr) call handle_err(retval)
3464 ### 5.6.3 Inserting an Array Field into a Compound Type: NF_INSERT_ARRAY_COMPOUND {#f77_NF-INSERT-ARRAY-COMPOUND}
3466 Insert a named array field into a compound type.
3474 INTEGER FUNCTION NF_INSERT_ARRAY_COMPOUND(INTEGER NCID, INTEGER XTYPE,
3475 CHARACTER*(*) NAME, INTEGER OFFSET, INTEGER FIELD_TYPEID,
3476 INTEGER NDIMS, INTEGER DIM_SIZES)
3480 : The ID of the file that contains the array type and the compound
3484 : The typeid for this compound type, as returned by nf\_def\_compound,
3488 : The name of the new field.
3491 : Offset in byte from the beginning of the compound type for this
3495 : The base type of the array to be inserted.
3498 : The number of dimensions for the array to be inserted.
3501 : An array containing the sizes of each dimension.
3513 : That name is in use. Field names must be unique within a compound
3517 : Name exceed max length NF\_MAX\_NAME.
3520 : Name contains illegal characters.
3523 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3524 operations can only be performed on files defined with a create mode
3525 which includes flag NF\_NETCDF4. (see
3526 [NF\_OPEN](#NF_005fOPEN)).
3529 : This file was created with the strict netcdf-3 flag, therefore
3530 netcdf-4 operations are not allowed. (see
3531 [NF\_OPEN](#NF_005fOPEN)).
3534 : An error was reported by the HDF5 layer.
3537 : Not in define mode.
3540 : Attempt to change type that has already been committed. The first
3541 time the file leaves define mode, all defined types are committed,
3542 and can’t be changed. If you wish to add an array to a compound
3543 type, you must do so before the compound type is committed.
3548 This example is from nf\_test/ftst\_types2.F.
3553 C Define a compound type.
3554 retval = nf_def_compound(ncid, cmp_size, type_name,
3556 if (retval .ne. nf_noerr) call handle_err(retval)
3561 retval = nf_insert_array_compound(ncid, cmp_typeid, ary_name, 0,
3562 & NF_INT, NDIMS, dim_sizes)
3563 if (retval .ne. nf_noerr) call handle_err(retval)
3566 ### 5.6.4 Learn About a Compound Type: NF_INQ_COMPOUND {#f77_NF-INQ-COMPOUND}
3568 Get the number of fields, length in bytes, and name of a compound type.
3570 In addtion to the NF\_INQ\_COMPOUND function, three additional functions
3571 are provided which get only the name, size, and number of fields.
3579 INTEGER FUNCTION NF_INQ_COMPOUND(INTEGER NCID, INTEGER XTYPE,
3580 CHARACTER*(*) NAME, INTEGER SIZEP, INTEGER NFIELDSP)
3582 INTEGER FUNCTION NF_INQ_COMPOUND_NAME(INTEGER NCID, INTEGER XTYPE,
3585 INTEGER FUNCTION NF_INQ_COMPOUND_SIZE(INTEGER NCID, INTEGER XTYPE,
3588 INTEGER FUNCTION NF_INQ_COMPOUND_NFIELDS(INTEGER NCID, INTEGER XTYPE,
3593 : The ID of any group in the file that contains the compound type.
3596 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3600 : Character array which will get the name of the compound type. It
3601 will have a maximum length of NF\_MAX\_NAME.
3604 : The size of the compound type in bytes will be put here.
3607 : The number of fields in the compound type will be placed here.
3616 : Couldn’t find this ncid.
3619 : Not a netCDF-4/HDF5 file.
3622 : A netCDF-4/HDF5 file, but with CLASSIC\_MODEL. No user defined types
3623 are allowed in the classic model.
3626 : This type not a compound type.
3632 : An error was reported by the HDF5 layer.
3637 This example is from nf\_test/ftst\_types.F.
3642 C Check it differently.
3643 retval = nf_inq_compound(ncid, typeids(1), name_in, size_in,
3645 if (retval .ne. nf_noerr) call handle_err(retval)
3646 if (name_in(1:len(type_name)) .ne. type_name .or.
3647 & size_in .ne. WIND_T_SIZE .or. nfields_in .ne. 2) stop 2
3649 C Check it one piece at a time.
3650 retval = nf_inq_compound_nfields(ncid, typeids(1), nfields_in)
3651 if (retval .ne. nf_noerr) call handle_err(retval)
3652 if (nfields_in .ne. 2) stop 2
3653 retval = nf_inq_compound_size(ncid, typeids(1), size_in)
3654 if (retval .ne. nf_noerr) call handle_err(retval)
3655 if (size_in .ne. WIND_T_SIZE) stop 2
3656 retval = nf_inq_compound_name(ncid, typeids(1), name_in)
3657 if (retval .ne. nf_noerr) call handle_err(retval)
3658 if (name_in(1:len(type_name)) .ne. type_name) stop 2
3661 ### 5.6.5 Learn About a Field of a Compound Type: NF_INQ_COMPOUND_FIELD {#f77_NF-INQ-COMPOUND-FIELD}
3663 Get information about one of the fields of a compound type.
3671 INTEGER FUNCTION NF_INQ_COMPOUND_FIELD(INTEGER NCID, INTEGER XTYPE,
3672 INTEGER FIELDID, CHARACTER*(*) NAME, INTEGER OFFSETP,
3673 INTEGER FIELD_TYPEIDP, INTEGER NDIMSP, INTEGER DIM_SIZESP)
3675 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDNAME(INTEGER TYPEID,
3676 INTEGER FIELDID, CHARACTER*(*) NAME)
3678 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDINDEX(INTEGER TYPEID,
3679 CHARACTER*(*) NAME, INTEGER FIELDIDP)
3681 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDOFFSET(INTEGER TYPEID,
3682 INTEGER FIELDID, INTEGER OFFSETP)
3684 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDTYPE(INTEGER TYPEID,
3685 INTEGER FIELDID, INTEGER FIELD_TYPEIDP)
3687 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDNDIMS(INTEGER NCID,
3688 INTEGER XTYPE, INTEGER FIELDID, INTEGER NDIMSP)
3690 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDDIM_SIZES(INTEGER NCID,
3691 INTEGER XTYPE, INTEGER FIELDID, INTEGER DIM_SIZES)
3695 : The groupid where this compound type exists.
3698 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3702 : A one-based index number specifying a field in the compound type.
3705 : A character array which will get the name of the field. The name
3706 will be NF\_MAX\_NAME characters, at most.
3709 : An integer which will get the offset of the field.
3712 : An integer which will get the typeid of the field.
3715 : An integer which will get the number of dimensions of the field.
3718 : An integer array which will get the dimension sizes of the field.
3730 : An error was reported by the HDF5 layer.
3735 This example is from nf\_test/fst\_types.F.
3740 C Check the first field of the compound type.
3741 retval = nf_inq_compound_field(ncid, typeids(1), 1, name_in,
3742 & offset_in, field_typeid_in, ndims_in, dim_sizes_in)
3743 if (retval .ne. nf_noerr) call handle_err(retval)
3744 if (name_in(1:len(u_name)) .ne. u_name .or. offset_in .ne. 0 .or.
3745 & field_typeid_in .ne. NF_INT .or. ndims_in .ne. 0) stop 2
3746 retval = nf_inq_compound_fieldname(ncid, typeids(1), 1, name_in)
3747 if (retval .ne. nf_noerr) call handle_err(retval)
3748 if (name_in(1:len(u_name)) .ne. u_name) stop 2
3749 retval = nf_inq_compound_fieldoffset(ncid, typeids(1), 1,
3751 if (retval .ne. nf_noerr) call handle_err(retval)
3752 if (offset_in .ne. 0) stop 2
3753 retval = nf_inq_compound_fieldtype(ncid, typeids(1), 1,
3755 if (retval .ne. nf_noerr) call handle_err(retval)
3756 if (field_typeid_in .ne. NF_INT) stop 2
3757 retval = nf_inq_compound_fieldndims(ncid, typeids(1), 1,
3759 if (retval .ne. nf_noerr) call handle_err(retval)
3760 if (ndims_in .ne. 0) stop 2
3763 5.7 Variable Length Array Introduction
3764 --------------------------------------
3766 NetCDF-4 addedpport for a variable length array type. This is not
3767 supported in classic or 64-bit offset files, or in netCDF-4 files which
3768 were created with the NF\_CLASSIC\_MODEL flag.
3770 A variable length array is represented in C as a structure from HDF5,
3771 the nf\_vlen\_t structure. It contains a len member, which contains the
3772 length of that array, and a pointer to the array.
3774 So an array of VLEN in C is an array of nc\_vlen\_t structures. The only
3775 way to handle this in Fortran is with a character buffer sized correctly
3778 The extra access functions NF\_GET\_VLEN\_ELEMENT and
3779 NF\_PUT\_VLEN\_ELEMENT to get and put one VLEN element. (That is, one
3780 array of variable length.) When calling the put, the data are not copied
3781 from the source. When calling the get the data are copied from VLEN
3782 allocated memory, which must still be freed (see below).
3784 VLEN arrays are handled differently with respect to allocation of
3785 memory. Generally, when reading data, it is up to the user to malloc
3786 (andbsequently free) the memory needed to hold the data. It is up to
3787 the user to ere that enough memory is allocated.
3789 With VLENs, this is impossible. The user cannot know the size of an
3790 array of VLEN until after reading the array. Therefore when reading VLEN
3791 arrays, the netCDF library will allocate the memory for the data within
3794 It is up to the user, however, to eventually free this memory. This is
3795 not just a matter of one call to free, with the pointer to the array of
3796 VLENs; each VLEN contains a pointer which must be freed.
3798 Compression is permitted but may not be effective for VLEN data, because
3799 the compression is applied to the nc\_vlen\_t structures, rather than
3802 ### 5.7.1 Define a Variable Length Array (VLEN): NF\_DEF\_VLEN
3804 Use this function to define a variable length array type.
3812 INTEGER FUNCTION NF_DEF_VLEN(INTEGER NCID, CHARACTER*(*) NAME,
3813 INTEGER BASE_TYPEID, INTEGER XTYPEP)
3817 : The ncid of the file to create the VLEN type in.
3820 : A name for the VLEN type.
3823 : The typeid of the base type of the VLEN. For example, for a VLEN of
3824 shorts, the base type is NF\_SHORT. This can be a user defined type.
3827 : The typeid of the new VLEN type will be set here.
3836 : NF\_MAX\_NAME exceeded.
3839 : Name is already in use.
3842 : Attribute or variable name contains illegal characters.
3848 : Group ID part of ncid was invalid.
3859 This example is from nf\_test/ftst\_vars4.F.
3864 C Create the vlen type.
3865 retval = nf_def_vlen(ncid, vlen_type_name, nf_int, vlen_typeid)
3866 if (retval .ne. nf_noerr) call handle_err(retval)
3869 ### 5.7.2 Learning about a Variable Length Array (VLEN) Type: NF\_INQ\_VLEN
3871 Use this type to learn about a vlen.
3879 INTEGER FUNCTION NF_INQ_VLEN(INTEGER NCID, INTEGER XTYPE,
3880 CHARACTER*(*) NAME, INTEGER DATUM_SIZEP, INTEGER
3885 : The ncid of the file that contains the VLEN type.
3888 : The type of the VLEN to inquire about.
3891 : The name of the VLEN type. The name will be NF\_MAX\_NAME characters
3895 : A pointer to a size\_t, this will get the size of one element of
3899 : An integer that will get the type of the VLEN base type. (In other
3900 words, what type is this a VLEN of?)
3909 : Can’t find the typeid.
3915 : Group ID part of ncid was invalid.
3920 This example is from nf\_test/ftst\_vars4.F.
3925 C Use nf_inq_vlen and makere we get the same answers as we did
3926 C with nf_inq_user_type.
3927 retval = nf_inq_vlen(ncid, typeids(1), type_name, base_size,
3929 if (retval .ne. nf_noerr) call handle_err(retval)
3932 ### 5.7.3 Releasing Memory for a Variable Length Array (VLEN) Type: NF\_FREE\_VLEN
3934 When a VLEN is read into user memory from the file, the HDF5 library
3935 performs memory allocations for each of the variable length arrays
3936 contained within the VLEN structure. This memory must be freed by the
3937 user to avoid memory leaks.
3939 This violates the normal netCDF expectation that the user is responsible
3940 for all memory allocation. But, with VLEN arrays, the underlying HDF5
3941 library allocates the memory for the user, and the user is responsible
3942 for deallocating that memory.
3950 INTEGER FUNCTION NF_FREE_VLEN(CHARACTER VL);
3954 : The variable length array structure which is to be freed.
3963 : Can’t find the typeid.
3968 ### 5.7.4 Set a Variable Length Array with NF\_PUT\_VLEN\_ELEMENT
3970 Use this to set the element of the (potentially) n-dimensional array of
3971 VLEN. That is, this sets the data in one variable length array.
3979 INTEGER FUNCTION NF_PUT_VLEN_ELEMENT(INTEGER NCID, INTEGER XTYPE,
3980 CHARACTER*(*) VLEN_ELEMENT, INTEGER LEN, DATA)
3984 : The ncid of the file that contains the VLEN type.
3987 : The type of the VLEN.
3990 : The VLEN element to be set.
3993 : The number of entries in this array.
3996 : The data to be stored. Must match the base type of this VLEN.
4005 : Can’t find the typeid.
4011 : Group ID part of ncid was invalid.
4016 This example is from nf\_test/ftst\_vars4.F.
4021 C Set up the vlen with this helper function, since F77 can't deal
4023 retval = nf_put_vlen_element(ncid, vlen_typeid, vlen,
4025 if (retval .ne. nf_noerr) call handle_err(retval)
4028 ### 5.7.5 Set a Variable Length Array with NF\_GET\_VLEN\_ELEMENT
4030 Use this to set the element of the (potentially) n-dimensional array of
4031 VLEN. That is, this sets the data in one variable length array.
4039 INTEGER FUNCTION NF_GET_VLEN_ELEMENT(INTEGER NCID, INTEGER XTYPE,
4040 CHARACTER*(*) VLEN_ELEMENT, INTEGER LEN, DATA)
4044 : The ncid of the file that contains the VLEN type.
4047 : The type of the VLEN.
4050 : The VLEN element to be set.
4053 : This will be set to the number of entries in this array.
4056 : The data will be copied here. Sufficient storage must be available
4057 or bad things will happen to you.
4066 : Can’t find the typeid.
4072 : Group ID part of ncid was invalid.
4077 This example is from nf\_test/ftst\_vars4.F.
4082 C Read the vlen attribute.
4083 retval = nf_get_att(ncid, NF_GLOBAL, 'att1', vlen_in)
4084 if (retval .ne. nf_noerr) call handle_err(retval)
4086 C Get the data from the vlen we just read.
4087 retval = nf_get_vlen_element(ncid, vlen_typeid, vlen_in,
4088 & vlen_len_in, data1_in)
4089 if (retval .ne. nf_noerr) call handle_err(retval)
4092 5.8 Opaque Type Introduction
4093 ----------------------------
4095 NetCDF-4 addedpport for the opaque type. This is notpported in
4096 classic or 64-bit offset files.
4098 The opaque type is a type which is a collection of objects of a known
4099 size. (And each object is the same size). Nothing is known to netCDF
4100 about the contents of these blobs of data, except their size in bytes,
4101 and the name of the type.
4103 To use an opaque type, first define it with [Creating Opaque Types:
4104 NF\_DEF\_OPAQUE](#NF_005fDEF_005fOPAQUE). If encountering an enum type
4105 in a new data file, use [Learn About an Opaque Type:
4106 NF\_INQ\_OPAQUE](#NF_005fINQ_005fOPAQUE) to learn its name and size.
4108 ### 5.8.1 Creating Opaque Types: NF\_DEF\_OPAQUE
4110 Create an opaque type. Provide a size and a name.
4118 INTEGER FUNCTION NF_DEF_OPAQUE(INTEGER NCID, INTEGER SIZE,
4119 CHARACTER*(*) NAME, INTEGER TYPEIDP)
4123 : The groupid where the type will be created. The type may be used
4124 anywhere in the file, no matter what group it is in.
4127 : The size of each opaque object.
4130 : The name for this type. Must be shorter than NF\_MAX\_NAME.
4133 : Pointer where the new typeid for this type is returned. Use this
4134 typeid when defining variables of this type with [Create a Variable:
4135 `NF_DEF_VAR`](#NF_005fDEF_005fVAR).
4150 : An error was reported by the HDF5 layer.
4155 This example is from nf\_test/ftst\_vars3.F.
4160 C Create the opaque type.
4161 retval = nf_def_opaque(ncid, opaque_size, opaque_type_name,
4163 if (retval .ne. nf_noerr) call handle_err(retval)
4166 ### 5.8.2 Learn About an Opaque Type: NF\_INQ\_OPAQUE
4168 Given a typeid, get the information about an opaque type.
4176 INTEGER FUNCTION NF_INQ_OPAQUE(INTEGER NCID, INTEGER XTYPE,
4177 CHARACTER*(*) NAME, INTEGER SIZEP)
4181 : The ncid for the group containing the opaque type.
4184 : The typeid for this opaque type, as returned by NF\_DEF\_COMPOUND,
4188 : The name of the opaque type will be copied here. It will be
4189 NF\_MAX\_NAME bytes or less.
4192 : The size of the opaque type will be copied here.
4207 : An error was reported by the HDF5 layer.
4212 This example is from nf\_test/ftst\_vars3.F.
4217 C Use nf_inq_opaque and makere we get the same answers as we did
4218 C with nf_inq_user_type.
4219 retval = nf_inq_opaque(ncid, typeids(2), type_name, base_size)
4220 if (retval .ne. nf_noerr) call handle_err(retval)
4223 5.9 Enum Type Introduction
4224 --------------------------
4226 NetCDF-4 addedpport for the enum type. This is notpported in
4227 classic or 64-bit offset files.
4229 ### 5.9.1 Creating a Enum Type: NF\_DEF\_ENUM
4231 Create an enum type. Provide an ncid, a name, and a base integer type.
4233 After calling this function, fill out the type with repeated calls to
4234 NF\_INSERT\_ENUM (see [Inserting a Field into a Enum Type:
4235 NF\_INSERT\_ENUM](#NF_005fINSERT_005fENUM)). Call NF\_INSERT\_ENUM once
4236 for each value you wish to make part of the enumeration.
4244 INTEGER FUNCTION NF_DEF_ENUM(INTEGER NCID, INTEGER BASE_TYPEID,
4245 CHARACTER*(*) NAME, INTEGER TYPEIDP)
4249 : The groupid where this compound type will be created.
4252 : The base integer type for this enum. Must be one of: NF\_BYTE,
4253 NF\_UBYTE, NF\_SHORT, NF\_USHORT, NF\_INT, NF\_UINT, NF\_INT64,
4257 : The name of the new enum type.
4260 : The typeid of the new type will be placed here.
4272 : That name is in use. Compound type names must be unique in the data
4276 : Name exceeds max length NF\_MAX\_NAME.
4279 : Name contains illegal characters.
4282 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
4283 operations can only be performed on files defined with a create mode
4284 which includes flag NF\_NETCDF4. (see
4285 [NF\_OPEN](#NF_005fOPEN)).
4288 : This file was created with the strict netcdf-3 flag, therefore
4289 netcdf-4 operations are not allowed. (see
4290 [NF\_OPEN](#NF_005fOPEN)).
4293 : An error was reported by the HDF5 layer.
4296 : Attempt to write to a read-only file.
4299 : Not in define mode.
4301 This example is from nf\_test/ftst\_vars3.F.
4306 C Create the enum type.
4307 retval = nf_def_enum(ncid, NF_INT, enum_type_name, enum_typeid)
4308 if (retval .ne. nf_noerr) call handle_err(retval)
4311 ### 5.9.2 Inserting a Field into a Enum Type: NF\_INSERT\_ENUM
4313 Insert a named member into a enum type.
4321 INTEGER FUNCTION NF_INSERT_ENUM(INTEGER NCID, INTEGER XTYPE,
4322 CHARACTER IDENTIFIER, INTEGER VALUE)
4326 : The ncid of the group which contains the type.
4329 : The typeid for this enum type, as returned by nf\_def\_enum, or
4333 : The identifier of the new member.
4336 : The value that is to be associated with this member.
4348 : That name is in use. Field names must be unique within a enum type.
4351 : Name exceed max length NF\_MAX\_NAME.
4354 : Name contains illegal characters.
4357 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
4358 operations can only be performed on files defined with a create mode
4359 which includes flag NF\_NETCDF4. (see
4360 [NF\_OPEN](#NF_005fOPEN)).
4363 : This file was created with the strict netcdf-3 flag, therefore
4364 netcdf-4 operations are not allowed. (see
4365 [NF\_OPEN](#NF_005fOPEN)).
4368 : An error was reported by the HDF5 layer.
4371 : Not in define mode.
4376 This example is from nf\_test/ftst\_vars3.F.
4383 retval = nf_insert_enum(ncid, enum_typeid, zero_name, zero)
4384 if (retval .ne. nf_noerr) call handle_err(retval)
4385 retval = nf_insert_enum(ncid, enum_typeid, one_name, one)
4386 if (retval .ne. nf_noerr) call handle_err(retval)
4389 ### 5.9.3 Learn About a Enum Type: NF\_INQ\_ENUM
4391 Get information about a user-defined enumeration type.
4399 INTEGER FUNCTION NF_INQ_ENUM(INTEGER NCID, INTEGER XTYPE,
4400 CHARACTER*(*) NAME, INTEGER BASE_NF_TYPE, INTEGER BASE_SIZE,
4401 INTEGER NUM_MEMBERS)
4405 : The group ID of the group which holds the enum type.
4408 : The typeid for this enum type, as returned by NF\_DEF\_ENUM, or
4412 : Character array which will get the name. It will have a maximum
4413 length of NF\_MAX\_NAME.
4416 : An integer which will get the base integer type of this enum.
4419 : An integer which will get the size (in bytes) of the base integer
4423 : An integer which will get the number of members defined for this
4436 : An error was reported by the HDF5 layer.
4441 In this example from nf\_test/ftst\_vars3.F, an enum type is created and
4447 retval = nf_inq_enum(ncid, typeids(1), type_name, base_type,
4448 & base_size, num_members)
4449 if (retval .ne. nf_noerr) call handle_err(retval)
4450 if (base_type .ne. NF_INT .or. num_members .ne. 2) stop 2
4453 ### 5.9.4 Learn the Name of a Enum Type: nf\_inq\_enum\_member
4455 Get information about a member of an enum type.
4463 INTEGER FUNCTION NF_INQ_ENUM_MEMBER(INTEGER NCID, INTEGER XTYPE,
4464 INTEGER IDX, CHARACTER*(*) NAME, INTEGER VALUE)
4468 : The groupid where this enum type exists.
4471 : The typeid for this enum type.
4474 : The one-based index number for the member of interest.
4477 : A character array which will get the name of the member. It will
4478 have a maximum length of NF\_MAX\_NAME.
4481 : An integer that will get the value associated with this member.
4493 : An error was reported by the HDF5 layer.
4498 This example is from nf\_test/ftst\_vars3.F:
4503 C Check the members of the enum type.
4504 retval = nf_inq_enum_member(ncid, typeids(1), 1, member_name,
4506 if (retval .ne. nf_noerr) call handle_err(retval)
4507 if (member_name(1:len(zero_name)) .ne. zero_name .or.
4508 & member_value .ne. 0) stop 2
4509 retval = nf_inq_enum_member(ncid, typeids(1), 2, member_name,
4511 if (retval .ne. nf_noerr) call handle_err(retval)
4512 if (member_name(1:len(one_name)) .ne. one_name .or.
4513 & member_value .ne. 1) stop 2
4516 ### 5.9.5 Learn the Name of a Enum Type: NF\_INQ\_ENUM\_IDENT
4518 Get the name which is associated with an enum member value.
4520 This is similar to NF\_INQ\_ENUM\_MEMBER, but instead of using the index
4521 of the member, you use the value of the member.
4529 INTEGER FUNCTION NF_INQ_ENUM_IDENT(INTEGER NCID, INTEGER XTYPE,
4530 INTEGER VALUE, CHARACTER*(*) IDENTIFIER)
4534 : The groupid where this enum type exists.
4537 : The typeid for this enum type.
4540 : The value for which an identifier is sought.
4543 : A character array that will get the identifier. It will have a
4544 maximum length of NF\_MAX\_NAME.
4553 : Bad type id, or not an enum type.
4556 : An error was reported by the HDF5 layer.
4559 : The value was not found in the enum.
4564 In this example from nf\_test/ftst\_vars3.F, the values for 0 and 1 are
4570 retval = nf_inq_enum_ident(ncid, typeids(1), 0, member_name)
4571 if (retval .ne. nf_noerr) call handle_err(retval)
4572 if (member_name(1:len(zero_name)) .ne. zero_name) stop 2
4573 retval = nf_inq_enum_ident(ncid, typeids(1), 1, member_name)
4574 if (retval .ne. nf_noerr) call handle_err(retval)
4575 if (member_name(1:len(one_name)) .ne. one_name) stop 2
4581 6.1 Variables Introduction
4582 --------------------------
4584 Variables for a netCDF dataset are defined when the dataset is created,
4585 while the netCDF dataset is in define mode. Other variables may be added
4586 later by reentering define mode. A netCDF variable has a name, a type,
4587 and a shape, which are specified when it is defined. A variable may also
4588 have values, which are established later in data mode.
4590 Ordinarily, the name, type, and shape are fixed when the variable is
4591 first defined. The name may be changed, but the type and shape of a
4592 variable cannot be changed. However, a variable defined in terms of the
4593 unlimited dimension can grow without bound in that dimension.
4595 A netCDF variable in an open netCDF dataset is referred to by a small
4596 integer called a variable ID.
4598 Variable IDs reflect the order in which variables were defined within a
4599 netCDF dataset. Variable IDs are 1, 2, 3,..., in the order in which the
4600 variables were defined. A function is available for getting the variable
4601 ID from the variable name and vice-versa.
4603 Attributes (see [Attributes](#Attributes)) may be associated with a
4604 variable to specifych properties as units.
4606 Operationspported on variables are:
4608 - Create a variable, given its name, data type, and shape.
4609 - Get a variable ID from its name.
4610 - Get a variable’s name, data type, shape, and number of attributes
4612 - Put a data value into a variable, given variable ID, indices, and
4614 - Put an array of values into a variable, given variable ID, corner
4615 indices, edge lengths, and a block of values.
4616 - Put absampled or mapped array of values into a variable,
4617 given variable ID, corner indices, edge lengths, stride vector,
4618 index mapping vector, and a block of values.
4619 - Get a data value from a variable, given variable ID and indices.
4620 - Get an array of values from a variable, given variable ID, corner
4621 indices, and edge lengths.
4622 - Get absampled or mapped array of values from a variable,
4623 given variable ID, corner indices, edge lengths, stride vector, and
4624 index mapping vector.
4625 - Rename a variable.
4628 6.2 Language Types Corresponding to netCDF external data types
4629 --------------------------------------------------------------
4631 The following table gives the netCDF external data types and the
4632 corresponding type constants for defining variables in the FORTRAN
4635 -------- ---------------------- ------
4636 Type FORTRAN API Mnemonic Bits
4642 double NF\_DOUBLE 64
4643 -------- ---------------------- ------
4645 The first column gives the netCDF external data type, which is the same
4646 as the CDL data type. The next column gives the corresponding FORTRAN
4647 parameter for use in netCDF functions (the parameters are defined in the
4648 netCDF FORTRAN include-file netcdf.inc). The last column gives the
4649 number of bits used in the external representation of values of the
4652 Note that there are no netCDF types corresponding to 64-bit integers or
4653 to characters wider than 8 bits in the current version of the netCDF
4656 6.3 Create a Variable: `NF_DEF_VAR`
4657 -----------------------------------
4659 The function NF\_DEF\_VAR adds a new variable to an open netCDF dataset
4660 in define mode. It returns (as an argument) a variable ID, given the
4661 netCDF ID, the variable name, the variable type, the number of
4662 dimensions, and a list of the dimension IDs.
4670 INTEGER FUNCTION NF_DEF_VAR(INTEGER NCID, CHARACTER*(*) NAME,
4671 INTEGER XTYPE, INTEGER NVDIMS,
4672 INTEGER VDIMS(*), INTEGER varid)
4676 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4682 : One of the set of predefined netCDF external data types. The type of
4683 this parameter, NF\_TYPE, is defined in the netCDF header file. The
4684 valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
4685 NF\_INT, NF\_FLOAT, and NF\_DOUBLE. If the file is a NetCDF-4/HDF5
4686 file, the additional types NF\_UBYTE, NF\_USHORT, NF\_UINT,
4687 NF\_INT64, NF\_UINT64, and NF\_STRING may be used, as well as a user
4691 : Number of dimensions for the variable. For example, 2 specifies a
4692 matrix, 1 specifies a vector, and 0 means the variable is a scalar
4693 with no dimensions. Must not be negative or greater than the
4694 predefined constant NF\_MAX\_VAR\_DIMS.
4697 : Vector of ndims dimension IDs corresponding to the variable
4698 dimensions. If the ID of the unlimited dimension is included, it
4699 must be first. This argument is ignored if ndims is 0. For expanded
4700 model netCDF4/HDF5 files, there may be any number of unlimited
4701 dimensions, and they may be used in any element of the dimids array.
4704 : Returned variable ID.
4709 NF\_DEF\_VAR returns the value NF\_NOERR if no errors occurred.
4710 Otherwise, the returned status indicates an error. Possible causes of
4713 - The netCDF dataset is not in define mode.
4714 - The specified variable name is the name of another existing
4716 - The specified type is not a valid netCDF type.
4717 - The specified number of dimensions is negative or more than the
4718 constant NF\_MAX\_VAR\_DIMS, the maximum number of dimensions
4719 permitted for a netCDF variable.
4720 - One or more of the dimension IDs in the list of dimensions is not a
4721 valid dimension ID for the netCDF dataset.
4722 - The number of variables would exceed the constant NF\_MAX\_VARS, the
4723 maximum number of variables permitted in a netCDF dataset.
4724 - The specified netCDF ID does not refer to an open netCDF dataset.
4729 Here is an example using NF\_DEF\_VAR to create a variable named rh of
4730 type double with three dimensions, time, lat, and lon in a new netCDF
4731 dataset named foo.nc:
4736 INCLUDE 'netcdf.inc'
4738 INTEGER STATUS, NCID
4739 INTEGER LATDIM, LONDIM, TIMDIM ! dimension IDs
4740 INTEGER RHID ! variable ID
4741 INTEGER RHDIMS(3) ! variable shape
4743 STATUS = NF_CREATE ('foo.nc', NF_NOCLOBBER, NCID)
4744 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4747 STATUS = NF_DEF_DIM(NCID, 'lat', 5, LATDIM)
4748 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4749 STATUS = NF_DEF_DIM(NCID, 'lon', 10, LONDIM)
4750 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4751 STATUS = NF_DEF_DIM(NCID, 'time', NF_UNLIMITED, TIMDIM)
4752 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4758 STATUS = NF_DEF_VAR (NCID, 'rh', NF_DOUBLE, 3, RHDIMS, RHID)
4759 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4762 6.4 Define Chunking Parameters for a Variable: `NF_DEF_VAR_CHUNKING`
4763 --------------------------------------------------------------------
4765 The function NF\_DEF\_VAR\_CHUNKING sets the storage parameters for a
4766 variable in a netCDF-4 file. It can set the chunk sizes to get chunked
4767 storage, or it can set the contiguous flag to get contiguous storage.
4769 Variables that make use of one or more unlimited dimensions,
4770 compression, or checms must use chunking. Such variables are created
4771 with default chunk sizes of 1 for each unlimited dimension and the
4772 dimension length for other dimensions, except that if the rlting
4773 chunks are too large, the default chunk sizes for non-record dimensions
4776 The total size of a chunk must be less than 4 GiB. That is, the product
4777 of all chunksizes and the size of the data (or the size of nc\_vlen\_t
4778 for VLEN types) must be less than 4 GiB.
4780 This function may only be called after the variable is defined, but
4781 before nc\_enddef is called. Once the chunking parameters are set for a
4782 variable, they cannot be changed. This function can be used to change
4783 the default chunking for record, compressed, or checmmed variables
4784 before nc\_enddef is called.
4786 Note that you cannot set chunking for scalar variables. Only non-scalar
4787 variables can have chunking.
4795 NF_DEF_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES)
4799 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4805 : If NF\_CONTIGUOUS, then contiguous storage is used for this
4806 variable. Variables with compression, shuffle filter, checms, or
4807 one or more unlimited dimensions cannot use contiguous storage. If
4808 contiguous storage is turned on, the chunksizes parameter is
4811 If NF\_CHUNKED, then chunked storage is used for this variable.
4812 Chunk sizes may be specified with the chunksizes parameter. Default
4813 sizes will be used if chunking is required and this function is not
4816 By default contiguous storage is used for fix-sized variables when
4817 conpression, chunking, checms, or endianness control are not
4821 : An array of chunk sizes. The array must have the one chunksize for
4822 each dimension in the variable. If contiguous storage is used, then
4823 the chunksizes parameter is ignored.
4828 NF\_DEF\_VAR\_CHUNKING returns the value NF\_NOERR if no errors
4829 occurred. Otherwise, the returned status indicates an error.
4831 Possible return codes include:
4840 : Invalid input. This can occur when the user attempts to set
4841 contiguous storage for a variable with compression or checms, or
4842 one or more unlimited dimensions.
4845 : Not a netCDF-4 file.
4848 : Can’t find this variable.
4851 : This variable has already been thebject of a NF\_ENDDEF call. In
4852 netCDF-4 files NF\_ENDDEF will be called automatically for any data
4853 read or write. Once enddef has been called, it is impossible to set
4854 the chunking for a variable.
4857 : Not in define mode. This is returned for netCDF classic or 64-bit
4858 offset files, or for netCDF-4 files, when they were been created
4859 with NF\_STRICT\_NC3 flag. (see
4860 [NF\_CREATE](#NF_005fCREATE)).
4863 : Trying to create a var some place other than the root group in a
4864 netCDF file with NF\_STRICT\_NC3 turned on.
4869 In this example from nf\_test/ftst\_vars.F, a file is created, two
4870 dimensions and a variable are defined, and the chunksizes of the data
4871 are set to the size of the data (that is, data will be written in one
4877 C Create the netCDF file.
4878 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
4879 if (retval .ne. nf_noerr) call handle_err(retval)
4881 C Define the dimensions.
4882 retval = nf_def_dim(ncid, "x", NX, x_dimid)
4883 if (retval .ne. nf_noerr) call handle_err(retval)
4884 retval = nf_def_dim(ncid, "y", NY, y_dimid)
4885 if (retval .ne. nf_noerr) call handle_err(retval)
4887 C Define the variable.
4890 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
4891 if (retval .ne. nf_noerr) call handle_err(retval)
4896 retval = NF_DEF_VAR_chunking(ncid, varid, NF_CHUNKED, chunks)
4897 if (retval .ne. nf_noerr) call handle_err(retval)
4900 6.5 Learn About Chunking Parameters for a Variable: `NF_INQ_VAR_CHUNKING`
4901 -------------------------------------------------------------------------
4903 The function NF\_INQ\_VAR\_CHUNKING returns the chunking settings for a
4904 variable in a netCDF-4 file.
4912 NF_INQ_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES);
4916 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4922 : On return, set to NF\_CONTIGUOUS if this variable uses contiguous
4923 storage, NF\_CHUNKED if it uses chunked storage.
4926 : An array of chunk sizes. The length of CHUNKSIZES must be the same
4927 as the number of dimensions of the variable.
4932 NF\_INQ\_VAR\_CHUNKING returns the value NF\_NOERR if no errors
4933 occurred. Otherwise, the returned status indicates an error.
4935 Possible return codes include:
4944 : Not a netCDF-4 file.
4947 : Can’t find this variable.
4952 In this example from nf\_test/ftst\_vars.F, a variable with chunked
4953 storage is checked to ere that the chunksizes are set to expected
4959 C Is everything set that ispposed to be?
4960 retval = nf_inq_var_chunking(ncid, varid, storage, chunks_in)
4961 if (retval .ne. nf_noerr) call handle_err(retval)
4962 if (storage .ne. NF_CHUNKED) stop 2
4963 if (chunks(1) .ne. chunks_in(1)) stop 2
4964 if (chunks(2) .ne. chunks_in(2)) stop 2
4967 6.6 Set HDF5 Chunk Cache for a Variable: NF\_SET\_VAR\_CHUNK\_CACHE
4968 -------------------------------------------------------------------
4970 This function changes the chunk cache settings for a variable. The
4971 change in cache size happens immediately. This is a property of the open
4972 file - it does not persist the next time you open the file.
4974 For more information, see the documentation for the H5Pset\_cache()
4975 function in the HDF5 library at the HDF5 website:
4976 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
4984 NF_SET_VAR_CHUNK_CACHE(INTEGER NCID, INTEGER VARID, INTEGER SIZE, INTEGER NELEMS,
4985 INTEGER PREEMPTION);
4989 : NetCDF ID, from a previous call to nc\_open or nc\_create.
4995 : The total size of the raw data chunk cache, in megabytes. This
4996 should be big enough to hold multiple chunks of data. (Note that the
4997 C API uses bytes, but the Fortran APIs uses megabytes to avoid
4998 numbers that can’t fit in 4-byte integers.)
5001 : The number of chunk slots in the raw data chunk cache hash table.
5002 This should be a prime number larger than the number of chunks that
5003 will be in the cache.
5006 : The preemption value must be between 0 and 100 inclusive and
5007 indicates the degreee to which chunks that have been fully read are
5008 favored for kicking out of the chunk cache, when needed. A value of
5009 zero means fully read chunks are treated no differently than other
5010 chunks (the preemption is strictly Least Recently Used) while a
5011 value of 100 means fully read chunks are always preempted before
5012 other chunks. (The C API uses a float between 0 and 1 for this
5022 : Preemption must be between zero and 100 (inclusive).
5027 This example is from nf\_test/ftst\_vars2.F:
5032 include 'netcdf.inc'
5034 C These will be used to set the per-variable chunk cache.
5035 integer CACHE_SIZE, CACHE_NELEMS, CACHE_PREEMPTION
5036 parameter (CACHE_SIZE = 8, CACHE_NELEMS = 571)
5037 parameter (CACHE_PREEMPTION = 42)
5039 C Set variable caches.
5040 retval = nf_set_var_chunk_cache(ncid, varid(i), CACHE_SIZE,
5041 & CACHE_NELEMS, CACHE_PREEMPTION)
5042 if (retval .ne. nf_noerr) call handle_err(retval)
5045 6.7 Get the HDF5 Chunk Cache Settings for a variable: NF\_GET\_VAR\_CHUNK\_CACHE
5046 --------------------------------------------------------------------------------
5048 This function gets the current chunk cache settings for a variable in a
5051 For more information, see the documentation for the H5Pget\_cache()
5052 function in the HDF5 library at the HDF5 website:
5053 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
5061 INTEGER NF_GET_VAR_CHUNK_CACHE(INTEGER NCID, INTEGER VARID, INTEGER SIZE, INTEGER NELEMS,
5062 INTEGER PREEMPTION);
5066 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5072 : The total size of the raw data chunk cache, in megabytes, will be
5076 : The number of chunk slots in the raw data chunk cache hash table
5080 : The preemption will be put here. The preemtion value is between 0
5081 and 100 inclusive and indicates how much chunks that have been fully
5082 read are favored for preemption. A value of zero means fully read
5083 chunks are treated no differently than other chunks (the preemption
5084 is strictly LRU) while a value of 100 means fully read chunks are
5085 always preempted before other chunks.
5096 This example is from nf\_test/ftst\_vars2.c:
5101 include 'netcdf.inc'
5103 C These will be used to set the per-variable chunk cache.
5104 integer CACHE_SIZE, CACHE_NELEMS, CACHE_PREEMPTION
5105 parameter (CACHE_SIZE = 8, CACHE_NELEMS = 571)
5106 parameter (CACHE_PREEMPTION = 42)
5108 C These will be used to check the setting of the per-variable chunk
5110 integer cache_size_in, cache_nelems_in, cache_preemption_in
5113 retval = nf_get_var_chunk_cache(ncid, varid(i), cache_size_in,
5114 & cache_nelems_in, cache_preemption_in)
5115 if (retval .ne. nf_noerr) call handle_err(retval)
5116 if (cache_size_in .ne. CACHE_SIZE .or. cache_nelems_in .ne.
5117 & CACHE_NELEMS .or. cache_preemption .ne. CACHE_PREEMPTION)
5121 6.8 Define Fill Parameters for a Variable: `nf_def_var_fill`
5122 ------------------------------------------------------------
5124 The function NF\_DEF\_VAR\_FILL sets the fill parameters for a variable
5127 This function must be called after the variable is defined, but before
5128 NF\_ENDDEF is called.
5136 NF_DEF_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE);
5140 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5146 : Set to non-zero value to set no\_fill mode on a variable. When this
5147 mode is on, fill values will not be written for the variable. This
5148 is helpful in high performance applications. For netCDF-4/HDF5 files
5149 (whether classic model or not), this may only be changed after the
5150 variable is defined, but before it is committed to disk (i.e. before
5151 the first NF\_ENDDEF after the NF\_DEF\_VAR.) For classic and 64-bit
5152 offset file, the no\_fill mode may be turned on and off at any time.
5155 : A value which will be used as the fill value for the variable. Must
5156 be the same type as the variable. This will be written to a
5157 \_FillValue attribute, created for this purpose. If NULL, this
5158 argument will be ignored.
5170 : Not a netCDF-4 file.
5173 : Can’t find this variable.
5176 : This variable has already been thebject of a NF\_ENDDEF call. In
5177 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5178 read or write. Once enddef has been called, it is impossible to set
5179 the fill for a variable.
5182 : Not in define mode. This is returned for netCDF classic or 64-bit
5183 offset files, or for netCDF-4 files, when they were been created
5184 with NF\_STRICT\_NC3 flag. (see
5185 [NF\_CREATE](#NF_005fCREATE)).
5188 : Attempt to create object in read-only file.
5193 6.9 Learn About Fill Parameters for a Variable: `NF_INQ_VAR_FILL`
5194 -----------------------------------------------------------------
5196 The function NF\_INQ\_VAR\_FILL returns the fill settings for a variable
5205 NF_INQ_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE)
5209 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5215 : An integer which will get a 1 if no\_fill mode is set for this
5216 variable, and a zero if it is not set
5219 : This will get the fill value for this variable. This parameter will
5220 be ignored if it is NULL.
5232 : Not a netCDF-4 file.
5235 : Can’t find this variable.
5240 6.10 Define Compression Parameters for a Variable: `NF_DEF_VAR_DEFLATE`
5241 -----------------------------------------------------------------------
5243 The function NF\_DEF\_VAR\_DEFLATE sets the deflate parameters for a
5244 variable in a netCDF-4 file.
5246 When using parallel I/O for writing data, deflate cannot be used. This
5247 is because the compression makes it impossible for the HDF5 library to
5248 exactly map the data to disk location.
5250 (Deflated data can be read with parallel I/O).
5252 NF\_DEF\_VAR\_DEFLATE must be called after the variable is defined, but
5253 before NF\_ENDDEF is called.
5261 NF_DEF_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE, INTEGER DEFLATE,
5262 INTEGER DEFLATE_LEVEL);
5266 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5272 : If non-zero, turn on the shuffle filter.
5275 : If non-zero, turn on the deflate filter at the level specified by
5276 the deflate\_level parameter.
5279 : Must be between 0 (no deflate, the default) and 9 (slowest, but
5282 If set to zero, no deflation takes place and the def\_var\_deflate
5283 call is ignored. This is slightly different from HDF5 handing of 0
5284 deflate, which turns on the filter but makes only trivial changes to
5287 Informal testing at NetCDF World Headquartersggests that there is
5288 little to be gained (with the limited set of test data used here),
5289 in setting the deflate level above 2 or 3.
5294 NF\_DEF\_VAR\_DEFLATE returns the value NF\_NOERR if no errors occurred.
5295 Otherwise, the returned status indicates an error.
5297 Possible return codes include:
5306 : Not a netCDF-4 file.
5309 : Can’t find this variable.
5312 : This variable has already been thebject of a NF\_ENDDEF call. In
5313 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5314 read or write. Once enddef has been called, it is impossible to set
5315 the deflate for a variable.
5318 : Not in define mode. This is returned for netCDF classic or 64-bit
5319 offset files, or for netCDF-4 files, when they were been created
5320 with NF\_STRICT\_NC3 flag. (see
5321 [NF\_CREATE](#NF_005fCREATE)).
5324 : Attempt to create object in read-only file.
5327 : Invalid deflate\_level. The deflate level must be between 0 and 9,
5333 In this example from nf\_test/ftst\_vars.F, a file is created with two
5334 dimensions and one variable. Chunking, deflate, and the fletcher32
5335 filter are turned on. The deflate level is set to 4 below.
5340 C Create the netCDF file.
5341 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5342 if (retval .ne. nf_noerr) call handle_err(retval)
5344 C Define the dimensions.
5345 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5346 if (retval .ne. nf_noerr) call handle_err(retval)
5347 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5348 if (retval .ne. nf_noerr) call handle_err(retval)
5350 C Define the variable.
5353 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5354 if (retval .ne. nf_noerr) call handle_err(retval)
5359 retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
5360 if (retval .ne. nf_noerr) call handle_err(retval)
5362 C Turn on deflate compression, fletcher32 checm.
5363 retval = NF_DEF_VAR_deflate(ncid, varid, 0, 1, 4)
5364 if (retval .ne. nf_noerr) call handle_err(retval)
5365 retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
5366 if (retval .ne. nf_noerr) call handle_err(retval)
5369 6.11 Learn About Deflate Parameters for a Variable: `NF_INQ_VAR_DEFLATE`
5370 ------------------------------------------------------------------------
5372 The function NF\_INQ\_VAR\_DEFLATE returns the deflate settings for a
5373 variable in a netCDF-4 file.
5375 It is not necessary to know the deflate settings to read the variable.
5376 (Deflate is completely transparent to readers of the data).
5384 NF_INQ_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE,
5385 INTEGER DEFLATE, INTEGER DEFLATE_LEVEL);
5389 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5395 : NF\_INQ\_VAR\_DEFLATE will set this to a 1 if the shuffle filter is
5396 turned on for this variable, and a 0 otherwise.
5399 : NF\_INQ\_VAR\_DEFLATE will set this to a 1 if the deflate filter is
5400 turned on for this variable, and a 0 otherwise.
5403 : NF\_INQ\_VAR\_DEFLATE function will write the deflate\_level here,
5404 if deflate is in use.
5409 NF\_INQ\_VAR\_DEFLATE returns the value NF\_NOERR if no errors occurred.
5410 Otherwise, the returned status indicates an error.
5412 Possible return codes include:
5421 : Not a netCDF-4 file.
5424 : Can’t find this variable.
5429 In this example code from nf\_test/ftst\_vars.F, a file with a variable
5430 using deflate is opened, and the deflate level checked.
5435 C Is everything set that ispposed to be?
5436 retval = nf_inq_var_deflate(ncid, varid, shuffle, deflate,
5438 if (retval .ne. nf_noerr) call handle_err(retval)
5439 if (shuffle .ne. 0 .or. deflate .ne. 1 .or.
5440 + deflate_level .ne. 4) stop 2
5443 6.12 Learn About Szip Parameters for a Variable: `NF_INQ_VAR_SZIP`
5444 ------------------------------------------------------------------
5446 The function NF\_INQ\_VAR\_SZIP returns the szip settings for a variable
5449 It is not necessary to know the szip settings to read the variable.
5450 (Szip is completely transparent to readers of the data).
5458 NF_INQ_VAR_SZIP(INTEGER NCID, INTEGER VARID, INTEGER OPTION_MASK,
5463 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5469 : This will be set to the option\_mask value.
5472 : The number of bits per pixel will be put here.
5477 NF\_INQ\_VAR\_SZIP returns the value NF\_NOERR if no errors occurred.
5478 Otherwise, the returned status indicates an error.
5480 Possible return codes include:
5489 : Not a netCDF-4 file.
5492 : Can’t find this variable.
5495 6.13 Define Checm Parameters for a Variable: `NF_DEF_VAR_FLETCHER32`
5496 -----------------------------------------------------------------------
5498 The function NF\_DEF\_VAR\_FLETCHER32 sets the checm property for a
5499 variable in a netCDF-4 file.
5501 This function may only be called after the variable is defined, but
5502 before NF\_ENDDEF is called.
5510 NF_DEF_VAR_FLETCHER32(INTEGER NCID, INTEGER VARID, INTEGER CHECKSUM);
5514 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5520 : If this is NF\_FLETCHER32, fletcher32 checms will be turned on
5526 NF\_DEF\_VAR\_FLETCHER32 returns the value NF\_NOERR if no errors
5527 occurred. Otherwise, the returned status indicates an error.
5529 Possible return codes include:
5538 : Not a netCDF-4 file.
5541 : Can’t find this variable.
5544 : This variable has already been thebject of a NF\_ENDDEF call. In
5545 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5546 read or write. Once enddef has been called, it is impossible to set
5547 the checm property for a variable.
5550 : Not in define mode. This is returned for netCDF classic or 64-bit
5551 offset files, or for netCDF-4 files, when they were been created
5552 with NF\_STRICT\_NC3 flag. (see
5553 [NF\_CREATE](#NF_005fCREATE)).
5556 : Attempt to create object in read-only file.
5561 In this example from nf\_test/ftst\_vars.F, the variable in a file has
5562 the Fletcher32 checm filter turned on.
5567 C Create the netCDF file.
5568 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5569 if (retval .ne. nf_noerr) call handle_err(retval)
5571 C Define the dimensions.
5572 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5573 if (retval .ne. nf_noerr) call handle_err(retval)
5574 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5575 if (retval .ne. nf_noerr) call handle_err(retval)
5577 C Define the variable.
5580 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5581 if (retval .ne. nf_noerr) call handle_err(retval)
5586 retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
5587 if (retval .ne. nf_noerr) call handle_err(retval)
5589 C Turn on deflate compression, fletcher32 checms.
5590 retval = NF_DEF_VAR_DEFLATE(ncid, varid, 0, 1, 4)
5591 if (retval .ne. nf_noerr) call handle_err(retval)
5592 retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
5593 if (retval .ne. nf_noerr) call handle_err(retval)
5597 6.14 Learn About Checm Parameters for a Variable: `NF_INQ_VAR_FLETCHER32`
5598 ----------------------------------------------------------------------------
5600 The function NF\_INQ\_VAR\_FLETCHER32 returns the checm settings for
5601 a variable in a netCDF-4 file.
5609 NF_INQ_VAR_FLETCHER32(INTEGER NCID, INTEGER VARID, INTEGER CHECKSUM);
5613 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5619 : NF\_INQ\_VAR\_FLETCHER32 will set this to NF\_FLETCHER32 if the
5620 fletcher32 filter is turned on for this variable, and NF\_NOCHECKSUM
5626 NF\_INQ\_VAR\_FLETCHER32 returns the value NF\_NOERR if no errors
5627 occurred. Otherwise, the returned status indicates an error.
5629 Possible return codes include:
5638 : Not a netCDF-4 file.
5641 : Can’t find this variable.
5646 In this example from nf\_test/ftst\_vars.F the checm filter is
5647 checked for a file. Since it was turned on for this variable, the
5648 checm variable is set to NF\_FLETCHER32.
5653 retval = nf_inq_var_fletcher32(ncid, varid, checm)
5654 if (retval .ne. nf_noerr) call handle_err(retval)
5655 if (checm .ne. NF_FLETCHER32) stop 2
5658 6.15 Define Endianness of a Variable: `NF_DEF_VAR_ENDIAN`
5659 ---------------------------------------------------------
5661 The function NF\_DEF\_VAR\_ENDIAN sets the endianness for a variable in
5664 This function must be called after the variable is defined, but before
5665 NF\_ENDDEF is called.
5667 By default, netCDF-4 variables are in native endianness. That is, they
5668 are big-endian on a big-endian machine, and little-endian on a little
5671 In some cases a user might wish to change from native endianness to
5672 either big or little-endianness. This function allows them to do that.
5680 NF_DEF_VAR_ENDIAN(INTEGER NCID, INTEGER VARID, INTEGER ENDIAN)
5684 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5690 : Set to NF\_ENDIAN\_NATIVE for native endianness. (This is the
5691 default). Set to NF\_ENDIAN\_LITTLE for little endian, or
5692 NF\_ENDIAN\_BIG for big endian.
5697 NF\_DEF\_VAR\_ENDIAN returns the value NF\_NOERR if no errors occurred.
5698 Otherwise, the returned status indicates an error.
5700 Possible return codes include:
5709 : Not a netCDF-4 file.
5712 : Can’t find this variable.
5715 : This variable has already been thebject of a NF\_ENDDEF call. In
5716 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5717 read or write. Once enddef has been called, it is impossible to set
5718 the endianness of a variable.
5721 : Not in define mode. This is returned for netCDF classic or 64-bit
5722 offset files, or for netCDF-4 files, when they were been created
5723 with NF\_STRICT\_NC3 flag, and the file is not in define mode. (see
5724 [NF\_CREATE](#NF_005fCREATE)).
5727 : Attempt to create object in read-only file.
5732 In this example from nf\_test/ftst\_vars.c, a file is created with one
5733 variable, and its endianness is set to NF\_ENDIAN\_BIG.
5738 C Create the netCDF file.
5739 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5740 if (retval .ne. nf_noerr) call handle_err(retval)
5742 C Define the dimensions.
5743 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5744 if (retval .ne. nf_noerr) call handle_err(retval)
5745 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5746 if (retval .ne. nf_noerr) call handle_err(retval)
5748 C Define the variable.
5751 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5752 if (retval .ne. nf_noerr) call handle_err(retval)
5757 retval = NF_DEF_VAR_chunking(ncid, varid, 0, chunks)
5758 if (retval .ne. nf_noerr) call handle_err(retval)
5760 C Set variable to big-endian (default is whatever is native to
5762 retval = NF_DEF_VAR_endian(ncid, varid, NF_ENDIAN_BIG)
5763 if (retval .ne. nf_noerr) call handle_err(retval)
5766 6.16 Learn About Endian Parameters for a Variable: `NF_INQ_VAR_ENDIAN`
5767 ----------------------------------------------------------------------
5769 The function NF\_INQ\_VAR\_ENDIAN returns the endianness settings for a
5770 variable in a netCDF-4 file.
5778 NF_INQ_VAR_ENDIAN(INTEGER NCID, INTEGER VARID, INTEGER ENDIAN)
5782 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5788 : NF\_INQ\_VAR\_ENDIAN will set this to NF\_ENDIAN\_LITTLE if this
5789 variable is stored in little-endian format, NF\_ENDIAN\_BIG if it is
5790 stored in big-endian format, and NF\_ENDIAN\_NATIVE if the
5791 endianness is not set, and the variable is not created yet.
5796 NF\_INQ\_VAR\_ENDIAN returns the value NF\_NOERR if no errors occurred.
5797 Otherwise, the returned status indicates an error.
5799 Possible return codes include:
5808 : Not a netCDF-4 file.
5811 : Can’t find this variable.
5816 In this example from nf\_test/ftst\_vars.F, the endianness of a variable
5817 is checked to makere it is NF\_ENDIAN\_BIG.
5822 retval = nf_inq_var_endian(ncid, varid, endianness)
5823 if (retval .ne. nf_noerr) call handle_err(retval)
5824 if (endianness .ne. NF_ENDIAN_BIG) stop 2
5828 6.17 Get a Variable ID from Its Name: NF\_INQ\_VARID
5829 ----------------------------------------------------
5831 The function NF\_INQ\_VARID returns the ID of a netCDF variable, given
5840 INTEGER FUNCTION NF_INQ_VARID(INTEGER NCID, CHARACTER*(*) NAME,
5845 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5848 : Variable name for which ID is desired.
5851 : Returned variable ID.
5856 NF\_INQ\_VARID returns the value NF\_NOERR if no errors occurred.
5857 Otherwise, the returned status indicates an error. Possible causes of
5860 - The specified variable name is not a valid name for a variable in
5861 the specified netCDF dataset.
5862 - The specified netCDF ID does not refer to an open netCDF dataset.
5867 Here is an example using NF\_INQ\_VARID to find out the ID of a variable
5868 named rh in an existing netCDF dataset named foo.nc:
5873 INCLUDE 'netcdf.inc'
5875 INTEGER STATUS, NCID, RHID
5877 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
5878 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5880 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
5881 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5885 6.18 Get Information about a Variable from Its ID: NF\_INQ\_VAR family
5886 ----------------------------------------------------------------------
5888 A family of functions that returns information about a netCDF variable,
5889 given its ID. Information about a variable includes its name, type,
5890 number of dimensions, a list of dimension IDs describing the shape of
5891 the variable, and the number of variable attributes that have been
5892 assigned to the variable.
5894 The function NF\_INQ\_VAR returns all the information about a netCDF
5895 variable, given its ID. The other functions each return just one item of
5896 information about a variable.
5898 These other functions include NF\_INQ\_VARNAME, NF\_INQ\_VARTYPE,
5899 NF\_INQ\_VARNDIMS, NF\_INQ\_VARDIMID, and NF\_INQ\_VARNATTS.
5907 INTEGER FUNCTION NF_INQ_VAR (INTEGER NCID, INTEGER VARID,
5908 CHARACTER*(*) name, INTEGER xtype,
5909 INTEGER ndims, INTEGER dimids(*),
5911 INTEGER FUNCTION NF_INQ_VARNAME (INTEGER NCID, INTEGER VARID,
5913 INTEGER FUNCTION NF_INQ_VARTYPE (INTEGER NCID, INTEGER VARID,
5915 INTEGER FUNCTION NF_INQ_VARNDIMS (INTEGER NCID, INTEGER VARID,
5917 INTEGER FUNCTION NF_INQ_VARDIMID (INTEGER NCID, INTEGER VARID,
5919 INTEGER FUNCTION NF_INQ_VARNATTS (INTEGER NCID, INTEGER VARID,
5924 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5930 : Returned variable name. The caller must allocate space for the
5931 returned name. The maximum possible length, in characters, of a
5932 variable name is given by the predefined constant NF\_MAX\_NAME.
5935 : Returned variable type, one of the set of predefined netCDF external
5936 data types. The type of this parameter, NF\_TYPE, is defined in the
5937 netCDF header file. The valid netCDF external data types are
5938 NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, AND NF\_DOUBLE.
5941 : Returned number of dimensions the variable was defined as using. For
5942 example, 2 indicates a matrix, 1 indicates a vector, and 0 means the
5943 variable is a scalar with no dimensions.
5946 : Returned vector of \*ndimsp dimension IDs corresponding to the
5947 variable dimensions. The caller must allocate enough space for a
5948 vector of at least \*ndimsp integers to be returned. The maximum
5949 possible number of dimensions for a variable is given by the
5950 predefined constant NF\_MAX\_VAR\_DIMS.
5953 : Returned number of variable attributes assigned to this variable.
5955 These functions return the value NF\_NOERR if no errors occurred.
5956 Otherwise, the returned status indicates an error. Possible causes of
5959 - The variable ID is invalid for the specified netCDF dataset.
5960 - The specified netCDF ID does not refer to an open netCDF dataset.
5965 Here is an example using NF\_INQ\_VAR to find out about a variable named
5966 rh in an existing netCDF dataset named foo.nc:
5971 INCLUDE 'netcdf.inc'
5973 INTEGER STATUS, NCID
5974 INTEGER RHID ! variable ID
5975 CHARACTER*31 RHNAME ! variable name
5976 INTEGER RHTYPE ! variable type
5977 INTEGER RHN ! number of dimensions
5978 INTEGER RHDIMS(NF_MAX_VAR_DIMS) ! variable shape
5979 INTEGER RHNATT ! number of attributes
5981 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
5982 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5984 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
5985 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5986 STATUS = NF_INQ_VAR (NCID, RHID, RHNAME, RHTYPE, RHN, RHDIMS, RHNATT)
5987 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5990 6.19 Write a Single Data Value: NF\_PUT\_VAR1\_ type
5991 ----------------------------------------------------
5993 The functions NF\_PUT\_VAR1\_type (for various types) put a single data
5994 value of the specified type into a variable of an open netCDF dataset
5995 that is in data mode. Inputs are the netCDF ID, the variable ID, an
5996 index that specifies which value to add or alter, and the data value.
5997 The value is converted to the external data type of the variable, if
6006 INTEGER FUNCTION NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6007 INTEGER INDEX(*), CHARACTER CHVAL)
6008 INTEGER FUNCTION NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6009 INTEGER INDEX(*), INTEGER*1 I1VAL)
6010 INTEGER FUNCTION NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6011 INTEGER INDEX(*), INTEGER*2 I2VAL)
6012 INTEGER FUNCTION NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
6013 INTEGER INDEX(*), INTEGER IVAL)
6014 INTEGER FUNCTION NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6015 INTEGER INDEX(*), REAL RVAL)
6016 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6017 INTEGER INDEX(*), DOUBLE DVAL)
6018 INTEGER FUNCTION NF_PUT_VAR1(INTEGER NCID, INTEGER VARID,
6019 INTEGER INDEX(*), *)
6023 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6029 : The index of the data value to be written. The indices are relative
6030 to 1, so for example, the first data value of a two-dimensional
6031 variable would have index (1,1). The elements of index must
6032 correspond to the variable’s dimensions. Hence, if the variable uses
6033 the unlimited dimension, the last index would correspond to the
6042 : Pointer to the data value to be written. If the type of data values
6043 differs from the netCDF variable type, type conversion will occur.
6044 See [(netcdf)Type Conversion](netcdf.html#Type-Conversion)
6045 ‘Type Conversion’ in The NetCDF Users Guide.
6050 NF\_PUT\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6051 Otherwise, the returned status indicates an error. Possible causes of
6054 - The variable ID is invalid for the specified netCDF dataset.
6055 - The specified indices were out of range for the rank of the
6056 specified variable. For example, a negative index or an index that
6057 is larger than the corresponding dimension length will cause an
6059 - The specified value is out of the range of values representable by
6060 the external data type of the variable.
6061 - The specified netCDF is in define mode rather than data mode.
6062 - The specified netCDF ID does not refer to an open netCDF dataset.
6067 Here is an example using NF\_PUT\_VAR1\_DOUBLE to set the (4,3,2)
6068 element of the variable named rh to 0.5 in an existing netCDF dataset
6069 named foo.nc. For simplicity in this example, we ame that we know
6070 that rh is dimensioned with lon, lat, and time, so we want to set the
6071 value of rh that corresponds to the fourth lon value, the third lat
6072 value, and the second time value:
6077 INCLUDE 'netcdf.inc'
6079 INTEGER STATUS ! error status
6081 INTEGER RHID ! variable ID
6082 INTEGER RHINDX(3) ! where to put value
6083 DATA RHINDX /4, 3, 2/
6085 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6086 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6088 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
6089 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6090 STATUS = NF_PUT_VAR1_DOUBLE (NCID, RHID, RHINDX, 0.5)
6091 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6094 6.20 Write an Entire Variable: NF\_PUT\_VAR\_ type
6095 --------------------------------------------------
6097 The NF\_PUT\_VAR\_ type family of functions write all the values of a
6098 variable into a netCDF variable of an open netCDF dataset. This is the
6099 simplest interface to use for writing a value in a scalar variable or
6100 whenever all the values of a multidimensional variable can all be
6101 written at once. The values to be written are associated with the netCDF
6102 variable by aming that the last dimension of the netCDF variable
6103 varies fastest in the C interface. The values are converted to the
6104 external data type of the variable, if necessary.
6106 Take care when using the simplest forms of this interface with record
6107 variables (variables that use the NF\_UNLIMITED dimension) when you
6108 don’t specify how many records are to be written. If you try to write
6109 all the values of a record variable into a netCDF file that has no
6110 record data yet (hence has 0 records), nothing will be written.
6111 Similarly, if you try to write all the values of a record variable from
6112 an array but there are more records in the file than you ame, more
6113 in-memory data will be accessed than you expect, which may cause a
6114 segmentation violation. To avoidch problems, it is better to use the
6115 NF\_PUT\_VARA\_type interfaces for variables that use the NF\_UNLIMITED
6116 dimension. See [Write an Array of Values: NF\_PUT\_VARA\_
6117 type](#NF_005fPUT_005fVARA_005f-type).
6125 INTEGER FUNCTION NF_PUT_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6127 INTEGER FUNCTION NF_PUT_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6128 INTEGER*1 I1VALS(*))
6129 INTEGER FUNCTION NF_PUT_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6130 INTEGER*2 I2VALS(*))
6131 INTEGER FUNCTION NF_PUT_VAR_INT (INTEGER NCID, INTEGER VARID,
6133 INTEGER FUNCTION NF_PUT_VAR_REAL (INTEGER NCID, INTEGER VARID,
6135 INTEGER FUNCTION NF_PUT_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6137 INTEGER FUNCTION NF_PUT_VAR (INTEGER NCID, INTEGER VARID,
6142 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6154 : The block of data values to be written. The data should be of the
6155 type appropriate for the function called. You cannot put CHARACTER
6156 data into a numeric variable or numeric data into a text variable.
6157 For numeric data, if the type of data differs from the netCDF
6158 variable type, type conversion will occur (see [(netcdf)Type
6159 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6160 in The NetCDF Users Guide). The order in which the data will be
6161 written into the specified variable is with the first dimension
6162 varying fastest (like the ordinary FORTRAN convention).
6167 Members of the NF\_PUT\_VAR\_ type family return the value NF\_NOERR if
6168 no errors occurred. Otherwise, the returned status indicates an error.
6169 Possible causes of errors include:
6171 - The variable ID is invalid for the specified netCDF dataset.
6172 - One or more of the specified values are out of the range of values
6173 representable by the external data type of the variable.
6174 - One or more of the specified values are out of the range of values
6175 representable by the external data type of the variable.
6176 - The specified netCDF dataset is in define mode rather than data
6178 - The specified netCDF ID does not refer to an open netCDF dataset.
6183 Here is an example using NF\_PUT\_VAR\_DOUBLE to add or change all the
6184 values of the variable named rh to 0.5 in an existing netCDF dataset
6185 named foo.nc. For simplicity in this example, we ame that we know
6186 that rh is dimensioned with lon and lat, and that there are ten lon
6187 values and five lat values.
6192 INCLUDE 'netcdf.inc'
6194 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6195 INTEGER STATUS, NCID
6196 INTEGER RHID ! variable ID
6197 DOUBLE RHVALS(LONS, LATS)
6199 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6200 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6202 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6203 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6204 DO 10 ILON = 1, LONS
6205 DO 10 ILAT = 1, LATS
6206 RHVALS(ILON, ILAT) = 0.5
6208 STATUS = NF_PUT_var_DOUBLE (NCID, RHID, RHVALS)
6209 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6213 6.21 Write an Array of Values: NF\_PUT\_VARA\_ type
6214 ---------------------------------------------------
6216 The function NF\_PUT\_VARA\_ type writes values into a netCDF variable
6217 of an open netCDF dataset. The part of the netCDF variable to write is
6218 specified by giving a corner and a vector of edge lengths that refer to
6219 an array of the netCDF variable. The values to be written are
6220 associated with the netCDF variable by aming that the first dimension
6221 of the netCDF variable varies fastest in the FORTRAN interface. The
6222 netCDF dataset must be in data mode.
6230 INTEGER FUNCTION NF_PUT_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6231 INTEGER START(*), INTEGER COUNT(*),
6233 INTEGER FUNCTION NF_PUT_VARA_INT1(INTEGER NCID, INTEGER VARID,
6234 INTEGER START(*), INTEGER COUNT(*),
6235 INTEGER*1 I1VALS(*))
6236 INTEGER FUNCTION NF_PUT_VARA_INT2(INTEGER NCID, INTEGER VARID,
6237 INTEGER START(*), INTEGER COUNT(*),
6238 INTEGER*2 I2VALS(*))
6239 INTEGER FUNCTION NF_PUT_VARA_INT (INTEGER NCID, INTEGER VARID,
6240 INTEGER START(*), INTEGER COUNT(*),
6242 INTEGER FUNCTION NF_PUT_VARA_REAL(INTEGER NCID, INTEGER VARID,
6243 INTEGER START(*), INTEGER COUNT(*),
6245 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6246 INTEGER START(*), INTEGER COUNT(*),
6248 INTEGER FUNCTION NF_PUT_VARA (INTEGER NCID, INTEGER VARID,
6249 INTEGER START(*), INTEGER COUNT(*),
6254 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6260 : A vector of integers specifying the index in the variable where the
6261 first of the data values will be written. The indices are relative
6262 to 1, so for example, the first data value of a variable would have
6263 index (1, 1, ..., 1). The length of START must be the same as the
6264 number of dimensions of the specified variable. The elements of
6265 START must correspond to the variable’s dimensions in order. Hence,
6266 if the variable is a record variable, the last index would
6267 correspond to the starting record number for writing the data
6271 : A vector of integers specifying the edge lengths along each
6272 dimension of the block of data values to written. To write a single
6273 value, for example, specify COUNT as (1, 1, ..., 1). The length of
6274 COUNT is the number of dimensions of the specified variable. The
6275 elements of COUNT correspond to the variable’s dimensions. Hence, if
6276 the variable is a record variable, the last element of COUNT
6277 corresponds to a count of the number of records to write.
6279 Note: setting any element of the count array to zero causes the
6280 function to exit without error, and without doing anything.
6289 : The block of data values to be written. The data should be of the
6290 type appropriate for the function called. You cannot put CHARACTER
6291 data into a numeric variable or numeric data into a text variable.
6292 For numeric data, if the type of data differs from the netCDF
6293 variable type, type conversion will occur (see [(netcdf)Type
6294 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6295 in The NetCDF Users Guide).
6300 NF\_PUT\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
6301 Otherwise, the returned status indicates an error. Possible causes of
6304 - The variable ID is invalid for the specified netCDF dataset.
6305 - The specified corner indices were out of range for the rank of the
6306 specified variable. For example, a negative index, or an index that
6307 is larger than the corresponding dimension length will cause an
6309 - The specified edge lengths added to the specified corner would have
6310 referenced data out of range for the rank of the specified variable.
6311 For example, an edge length that is larger than the corresponding
6312 dimension length minus the corner index will cause an error.
6313 - One or more of the specified values are out of the range of values
6314 representable by the external data type of the variable.
6315 - The specified netCDF dataset is in define mode rather than data
6317 - The specified netCDF ID does not refer to an open netCDF dataset.
6322 Here is an example using NF\_PUT\_VARA\_DOUBLE to add or change all the
6323 values of the variable named rh to 0.5 in an existing netCDF dataset
6324 named foo.nc. For simplicity in this example, we ame that we know
6325 that rh is dimensioned with time, lat, and lon, and that there are three
6326 time values, five lat values, and ten lon values.
6331 INCLUDE 'netcdf.inc'
6333 PARAMETER (NDIMS=3) ! number of dimensions
6334 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
6335 INTEGER STATUS, NCID, TIMES
6336 INTEGER RHID ! variable ID
6337 INTEGER START(NDIMS), COUNT(NDIMS)
6338 DOUBLE RHVALS(LONS, LATS, TIMES)
6339 DATA START /1, 1, 1/ ! start at first value
6340 DATA COUNT /LONS, LATS, TIMES/
6342 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6343 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6345 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6346 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6347 DO 10 ILON = 1, LONS
6348 DO 10 ILAT = 1, LATS
6349 DO 10 ITIME = 1, TIMES
6350 RHVALS(ILON, ILAT, ITIME) = 0.5
6352 STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
6353 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6357 6.22 NF\_PUT\_VARS\_ type
6358 -------------------------
6360 Each member of the family of functions NF\_PUT\_VARS\_ type writes a
6361 subsampled (strided) array of values into a netCDF variable of
6362 an open netCDF dataset. Thebsampled array is specified by
6363 giving a corner, a vector of counts, and a stride vector. The netCDF
6364 dataset must be in data mode.
6372 INTEGER FUNCTION NF_PUT_VARS_TEXT (INTEGER NCID, INTEGER VARID,
6373 INTEGER START(*), INTEGER COUNT(*),
6374 INTEGER STRIDE(*),CHARACTER*(*) TEXT)
6375 INTEGER FUNCTION NF_PUT_VARS_INT1 (INTEGER NCID, INTEGER VARID,
6376 INTEGER START(*), INTEGER COUNT(*),
6377 INTEGER STRIDE(*),INTEGER*1 I1VALS(*))
6378 INTEGER FUNCTION NF_PUT_VARS_INT2 (INTEGER NCID, INTEGER VARID,
6379 INTEGER START(*), INTEGER COUNT(*),
6380 INTEGER STRIDE(*),INTEGER*2 I2VALS(*))
6381 INTEGER FUNCTION NF_PUT_VARS_INT (INTEGER NCID, INTEGER VARID,
6382 INTEGER START(*), INTEGER COUNT(*),
6383 INTEGER STRIDE(*), INTEGER IVALS(*))
6384 INTEGER FUNCTION NF_PUT_VARS_REAL (INTEGER NCID, INTEGER VARID,
6385 INTEGER START(*), INTEGER COUNT(*),
6386 INTEGER STRIDE(*), REAL RVALS(*))
6387 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
6388 INTEGER START(*), INTEGER COUNT(*),
6389 INTEGER STRIDE(*), DOUBLE DVALS(*))
6390 INTEGER FUNCTION NF_PUT_VARS (INTEGER NCID, INTEGER VARID,
6391 INTEGER START(*), INTEGER COUNT(*),
6392 INTEGER STRIDE(*), VALS(*))
6396 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6402 : A vector of integers specifying the index in the variable where the
6403 first of the data values will be written. The indices are relative
6404 to 1, so for example, the first data value of a variable would have
6405 index (1, 1, ..., 1). The elements of START correspond, in order, to
6406 the variable’s dimensions. Hence, if the variable is a record
6407 variable, the last index would correspond to the starting record
6408 number for writing the data values.
6411 : A vector of integers specifying the number of indices selected along
6412 each dimension. To write a single value, for example, specify COUNT
6413 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6414 the variable’s dimensions. Hence, if the variable is a record
6415 variable, the last element of COUNT corresponds to a count of the
6416 number of records to write.
6418 Note: setting any element of the count array to zero causes the
6419 function to exit without error, and without doing anything.
6422 : A vector of integers that specifies the sampling interval along each
6423 dimension of the netCDF variable. The elements of the stride vector
6424 correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6425 gives the sampling interval along the most rapidly varying dimension
6426 of the netCDF variable). Sampling intervals are specified in
6427 type-independent units of elements (a value of 1 selects consecutive
6428 elements of the netCDF variable along the corresponding dimension, a
6429 value of 2 selects every other element, etc.).
6438 : The block of data values to be written. The data should be of the
6439 type appropriate for the function called. You cannot put CHARACTER
6440 data into a numeric variable or numeric data into a text variable.
6441 For numeric data, if the type of data differs from the netCDF
6442 variable type, type conversion will occur (see [(netcdf)Type
6443 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6444 in The NetCDF Users Guide).
6449 NF\_PUT\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
6450 Otherwise, the returned status indicates an error. Possible causes of
6453 - The variable ID is invalid for the specified netCDF dataset.
6454 - The specified start, count and stride generate an index which is out
6456 - One or more of the specified values are out of the range of values
6457 representable by the external data type of the variable.
6458 - The specified netCDF is in define mode rather than data mode.
6459 - The specified netCDF ID does not refer to an open netCDF dataset.
6464 Here is an example of using NF\_PUT\_VARS\_REAL to write – from an
6465 internal array – every other point of a netCDF variable named rh which
6466 is described by the FORTRAN declaration REAL RH(6,4) (note the size of
6472 INCLUDE 'netcdf.inc'
6474 PARAMETER (NDIM=2) ! rank of netCDF variable
6475 INTEGER NCID ! netCDF dataset ID
6476 INTEGER STATUS ! return code
6477 INTEGER RHID ! variable ID
6478 INTEGER START(NDIM) ! netCDF variable start point
6479 INTEGER COUNT(NDIM) ! size of internal array
6480 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6481 REAL RH(3,2) ! notebsampled sizes for netCDF variable
6483 DATA START /1, 1/ ! start at first netCDF variable value
6484 DATA COUNT /3, 2/ ! size of internal array: entire bsampled)
6486 DATA STRIDE /2, 2/ ! access every other netCDF element
6488 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6489 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6491 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6492 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6494 STATUS = NF_PUT_VARS_REAL(NCID, RHID, START, COUNT, STRIDE, RH)
6495 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6497 6.23 NF\_PUT\_VARM\_ type
6498 -------------------------
6500 The NF\_PUT\_VARM\_ type family of functions writes a mapped array
6501 section of values into a netCDF variable of an open netCDF dataset. The
6502 mapped array is specified by giving a corner, a vector of
6503 counts, a stride vector, and an index mapping vector. The index mapping
6504 vector is a vector of integers that specifies the mapping between the
6505 dimensions of a netCDF variable and the in-memory structure of the
6506 internal data array. No amptions are made about the ordering or
6507 length of the dimensions of the data array. The netCDF dataset must be
6516 INTEGER FUNCTION NF_PUT_VARM_TEXT (INTEGER NCID, INTEGER VARID,
6517 INTEGER START(*), INTEGER COUNT(*),
6518 INTEGER STRIDE(*), INTEGER IMAP(*),
6520 INTEGER FUNCTION NF_PUT_VARM_INT1 (INTEGER NCID, INTEGER VARID,
6521 INTEGER START(*), INTEGER COUNT(*),
6522 INTEGER STRIDE(*), INTEGER IMAP(*),
6523 INTEGER*1 I1VALS(*))
6524 INTEGER FUNCTION NF_PUT_VARM_INT2 (INTEGER NCID, INTEGER VARID,
6525 INTEGER START(*), INTEGER COUNT(*),
6526 INTEGER STRIDE(*), INTEGER IMAP(*),
6527 INTEGER*2 I2VALS(*))
6528 INTEGER FUNCTION NF_PUT_VARM_INT (INTEGER NCID, INTEGER VARID,
6529 INTEGER START(*), INTEGER COUNT(*),
6530 INTEGER STRIDE(*), INTEGER IMAP(*),
6532 INTEGER FUNCTION NF_PUT_VARM_REAL (INTEGER NCID, INTEGER VARID,
6533 INTEGER START(*), INTEGER COUNT(*),
6534 INTEGER STRIDE(*), INTEGER IMAP(*),
6536 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
6537 INTEGER START(*), INTEGER COUNT(*),
6538 INTEGER STRIDE(*), INTEGER IMAP(*),
6543 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6549 : A vector of integers specifying the index in the variable where the
6550 first of the data values will be written. The indices are relative
6551 to 1, so for example, the first data value of a variable would have
6552 index (1, 1, ..., 1). The elements of START correspond, in order, to
6553 the variable’s dimensions. Hence, if the variable is a record
6554 variable, the last index would correspond to the starting record
6555 number for writing the data values.
6558 : A vector of integers specifying the number of indices selected along
6559 each dimension. To write a single value, for example, specify COUNT
6560 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6561 the variable’s dimensions. Hence, if the variable is a record
6562 variable, the last element of COUNT corresponds to a count of the
6563 number of records to write.
6565 Note: setting any element of the count array to zero causes the
6566 function to exit without error, and without doing anything.
6569 : A vector of integers that specifies the sampling interval along each
6570 dimension of the netCDF variable. The elements of the stride vector
6571 correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6572 gives the sampling interval along the most rapidly varying dimension
6573 of the netCDF variable). Sampling intervals are specified in
6574 type-independent units of elements (a value of 1 selects consecutive
6575 elements of the netCDF variable along the corresponding dimension, a
6576 value of 2 selects every other element, etc.).
6579 : A vector of integers that specifies the mapping between the
6580 dimensions of a netCDF variable and the in-memory structure of the
6581 internal data array. The elements of the index mapping vector
6582 correspond, in order, to the netCDF variable’s dimensions (IMAP(1)
6583 gives the distance between elements of the internal array
6584 corresponding to the most rapidly varying dimension of the netCDF
6585 variable). Distances between elements are specified in units of
6586 elements (the distance between internal elements that occupy
6587 adjacent memory locations is 1 and not the element’s byte-length as
6596 : The data values to be written. The data should be of the type
6597 appropriate for the function called. You cannot put CHARACTER data
6598 into a numeric variable or numeric data into a text variable. For
6599 numeric data, if the type of data differs from the netCDF variable
6600 type, type conversion will occur (see [(netcdf)Type
6601 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6602 in The NetCDF Users Guide).
6607 NF\_PUT\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
6608 Otherwise, the returned status indicates an error. Possible causes of
6611 - The variable ID is invalid for the specified netCDF dataset.
6612 - The specified START, COUNT, and STRIDE generate an index which is
6613 out of range. Note that no error checking is possible on the imap
6615 - One or more of the specified values are out of the range of values
6616 representable by the external data type of the variable.
6617 - The specified netCDF is in define mode rather than data mode.
6618 - The specified netCDF ID does not refer to an open netCDF dataset.
6623 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
6624 variable and an internal array of the same shape:
6629 REAL A(2,3,4) ! same shape as netCDF variable
6631 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
6632 ! ---------------- ----------------------
6633 ! most rapidly varying 1
6634 ! intermediate 2 (=IMAP(1)*2)
6635 ! most slowly varying 6 (=IMAP(2)*3)
6638 Using the IMAP vector above with NF\_PUT\_VARM\_REAL obtains the same
6639 rlt as simply using NF\_PUT\_VAR\_REAL.
6641 Here is an example of using NF\_PUT\_VARM\_REAL to write – from a
6642 transposed, internal array – a netCDF variable named rh which is
6643 described by the FORTRAN declaration REAL RH(4,6) (note the size and
6644 order of the dimensions):
6649 INCLUDE 'netcdf.inc'
6651 PARAMETER (NDIM=2) ! rank of netCDF variable
6652 INTEGER NCID ! netCDF ID
6653 INTEGER STATUS ! return code
6654 INTEGER RHID ! variable ID
6655 INTEGER START(NDIM) ! netCDF variable start point
6656 INTEGER COUNT(NDIM) ! size of internal array
6657 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6658 INTEGER IMAP(NDIM) ! internal array inter-element distances
6659 REAL RH(6,4) ! note transposition of netCDF variable dimensions
6660 DATA START /1, 1/ ! start at first netCDF variable element
6661 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
6662 ! to netCDF variable -- not internal array
6663 DATA STRIDE /1, 1/ ! sample every netCDF element
6664 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
6666 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6667 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6669 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6670 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6672 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6673 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6676 Here is another example of using NF\_PUT\_VARM\_REAL to write – from a
6677 transposed, internal array – absample of the same netCDF variable, by
6678 writing every other point of the netCDF variable:
6683 INCLUDE 'netcdf.inc'
6685 PARAMETER (NDIM=2) ! rank of netCDF variable
6686 INTEGER NCID ! netCDF dataset ID
6687 INTEGER STATUS ! return code
6688 INTEGER RHID ! variable ID
6689 INTEGER START(NDIM) ! netCDF variable start point
6690 INTEGER COUNT(NDIM) ! size of internal array
6691 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6692 INTEGER IMAP(NDIM) ! internal array inter-element distances
6693 REAL RH(3,2) ! note transposition of bsampled) dimensions
6694 DATA START /1, 1/ ! start at first netCDF variable value
6695 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
6696 ! to netCDF variable -- not internal array
6697 DATA STRIDE /2, 2/ ! sample every other netCDF element
6698 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
6700 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6701 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6703 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6704 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6706 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6707 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6710 6.24 NF\_GET\_VAR1\_ type
6711 -------------------------
6713 The functions NF\_GET\_VAR1\_ type get a single data value from a
6714 variable of an open netCDF dataset that is in data mode. Inputs are the
6715 netCDF ID, the variable ID, a multidimensional index that specifies
6716 which value to get, and the address of a location into which the data
6717 value will be read. The value is converted from the external data type
6718 of the variable, if necessary.
6726 INTEGER FUNCTION NF_GET_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6727 INTEGER INDEX(*), CHARACTER CHVAL)
6728 INTEGER FUNCTION NF_GET_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6729 INTEGER INDEX(*), INTEGER*1 I1VAL)
6730 INTEGER FUNCTION NF_GET_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6731 INTEGER INDEX(*), INTEGER*2 I2VAL)
6732 INTEGER FUNCTION NF_GET_VAR1_INT (INTEGER NCID, INTEGER VARID,
6733 INTEGER INDEX(*), INTEGER IVAL)
6734 INTEGER FUNCTION NF_GET_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6735 INTEGER INDEX(*), REAL RVAL)
6736 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6737 INTEGER INDEX(*), DOUBLE DVAL)
6738 INTEGER FUNCTION NF_GET_VAR1(INTEGER NCID, INTEGER VARID,
6739 INTEGER INDEX(*), VAL)
6743 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6749 : The index of the data value to be read. The indices are relative to
6750 1, so for example, the first data value of a two-dimensional
6751 variable has index (1,1). The elements of index correspond to the
6752 variable’s dimensions. Hence, if the variable is a record variable,
6753 the last index is the record number.
6762 : The location into which the data value will be read. You cannot get
6763 CHARACTER data from a numeric variable or numeric data from a
6764 character variable. For numeric data, if the type of data differs
6765 from the netCDF variable type, type conversion will occur. (see
6766 [(netcdf)Type Conversion](netcdf.html#Type-Conversion) ‘Type
6767 Conversion’ in The NetCDF Users Guide).
6772 NF\_GET\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6773 Otherwise, the returned status indicates an error. Possible causes of
6776 - The variable ID is invalid for the specified netCDF dataset.
6777 - The specified indices were out of range for the rank of the
6778 specified variable. For example, a negative index or an index that
6779 is larger than the corresponding dimension length will cause an
6781 - The value is out of the range of values representable by the desired
6783 - The specified netCDF is in define mode rather than data mode.
6784 - The specified netCDF ID does not refer to an open netCDF dataset.
6789 Here is an example using NF\_GET\_VAR1\_DOUBLE to get the (4,3,2)
6790 element of the variable named rh in an existing netCDF dataset named
6791 foo.nc. For simplicity in this example, we ame that we know that rh
6792 is dimensioned with lon, lat, and time, so we want to get the value of
6793 rh that corresponds to the fourth lon value, the third lat value, and
6794 the second time value:
6799 INCLUDE 'netcdf.inc'
6801 INTEGER STATUS, NCID
6802 INTEGER RHID ! variable ID
6803 INTEGER RHINDX(3) ! where to get value
6804 DOUBLE PRECISION RHVAL ! put it here
6805 DATA RHINDX /4, 3, 2/
6807 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6808 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6810 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6811 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6812 STATUS = NF_GET_VAR1_DOUBLE (NCID, RHID, RHINDX, RHVAL)
6813 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6816 6.25 NF\_GET\_VAR\_ type
6817 ------------------------
6819 The members of the NF\_GET\_VAR\_ type family of functions read all the
6820 values from a netCDF variable of an open netCDF dataset. This is the
6821 simplest interface to use for reading the value of a scalar variable or
6822 when all the values of a multidimensional variable can be read at once.
6823 The values are read into consecutive locations with the first dimension
6824 varying fastest. The netCDF dataset must be in data mode.
6826 Take care when using the simplest forms of this interface with record
6827 variables (variables that use the NF\_UNLIMITED dimension) when you
6828 don’t specify how many records are to be read. If you try to read all
6829 the values of a record variable into an array but there are more records
6830 in the file than you ame, more data will be read than you expect,
6831 which may cause a segmentation violation. To avoidch problems, it is
6832 better to use the NF\_GET\_VARA\_type interfaces for variables that use
6833 the NF\_UNLIMITED dimension. See [NF\_GET\_VARA\_
6834 type](#NF_005fGET_005fVARA_005f-type).
6842 INTEGER FUNCTION NF_GET_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6844 INTEGER FUNCTION NF_GET_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6845 INTEGER*1 i1vals(*))
6846 INTEGER FUNCTION NF_GET_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6847 INTEGER*2 i2vals(*))
6848 INTEGER FUNCTION NF_GET_VAR_INT (INTEGER NCID, INTEGER VARID,
6850 INTEGER FUNCTION NF_GET_VAR_REAL (INTEGER NCID, INTEGER VARID,
6852 INTEGER FUNCTION NF_GET_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6854 INTEGER FUNCTION NF_GET_VAR (INTEGER NCID, INTEGER VARID,
6859 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6871 : The block of data values to be read. The data should be of the type
6872 appropriate for the function called. You cannot read CHARACTER data
6873 from a numeric variable or numeric data from a text variable. For
6874 numeric data, if the type of data differs from the netCDF variable
6875 type, type conversion will occur (see [(netcdf)Type
6876 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6877 in The NetCDF Users Guide).
6882 NF\_GET\_VAR\_ type returns the value NF\_NOERR if no errors occurred.
6883 Otherwise, the returned status indicates an error. Possible causes of
6886 - The variable ID is invalid for the specified netCDF dataset.
6887 - One or more of the values are out of the range of values
6888 representable by the desired type.
6889 - The specified netCDF is in define mode rather than data mode.
6890 - The specified netCDF ID does not refer to an open netCDF dataset.
6895 Here is an example using NF\_GET\_VAR\_DOUBLE to read all the values of
6896 the variable named rh from an existing netCDF dataset named foo.nc. For
6897 simplicity in this example, we ame that we know that rh is
6898 dimensioned with lon and lat, and that there are ten lon values and five
6904 INCLUDE 'netcdf.inc'
6906 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6907 INTEGER STATUS, NCID
6908 INTEGER RHID ! variable ID
6909 DOUBLE RHVALS(LONS, LATS)
6911 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6912 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6914 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6915 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6916 STATUS = NF_GET_VAR_DOUBLE (NCID, RHID, RHVALS)
6917 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6920 6.26 NF\_GET\_VARA\_ type
6921 -------------------------
6923 The members of the NF\_GET\_VARA\_ type family of functions read an
6924 array of values from a netCDF variable of an open netCDF dataset. The
6925 array is specified by giving a corner and a vector of edge lengths. The
6926 values are read into consecutive locations with the first dimension
6927 varying fastest. The netCDF dataset must be in data mode.
6935 INTEGER FUNCTION NF_GET_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6936 INTEGER START(*), INTEGER COUNT(*),
6938 INTEGER FUNCTION NF_GET_VARA_INT1(INTEGER NCID, INTEGER VARID,
6939 INTEGER START(*), INTEGER COUNT(*),
6940 INTEGER*1 i1vals(*))
6941 INTEGER FUNCTION NF_GET_VARA_INT2(INTEGER NCID, INTEGER VARID,
6942 INTEGER START(*), INTEGER COUNT(*),
6943 INTEGER*2 i2vals(*))
6944 INTEGER FUNCTION NF_GET_VARA_INT (INTEGER NCID, INTEGER VARID,
6945 INTEGER START(*), INTEGER COUNT(*),
6947 INTEGER FUNCTION NF_GET_VARA_REAL(INTEGER NCID, INTEGER VARID,
6948 INTEGER START(*), INTEGER COUNT(*),
6950 INTEGER FUNCTION NF_GET_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6951 INTEGER START(*), INTEGER COUNT(*),
6956 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6962 : A vector of integers specifying the index in the variable where the
6963 first of the data values will be read. The indices are relative to
6964 1, so for example, the first data value of a variable would have
6965 index (1, 1, ..., 1). The length of START must be the same as the
6966 number of dimensions of the specified variable. The elements of
6967 START correspond, in order, to the variable’s dimensions. Hence, if
6968 the variable is a record variable, the last index would correspond
6969 to the starting record number for reading the data values.
6972 : A vector of integers specifying the edge lengths along each
6973 dimension of the block of data values to be read. To read a single
6974 value, for example, specify COUNT as (1, 1, ..., 1). The length of
6975 COUNT is the number of dimensions of the specified variable. The
6976 elements of COUNT correspond, in order, to the variable’s
6977 dimensions. Hence, if the variable is a record variable, the last
6978 element of COUNT corresponds to a count of the number of records to
6981 Note: setting any element of the count array to zero causes the
6982 function to exit without error, and without doing anything.
6990 : The block of data values to be read. The data should be of the type
6991 appropriate for the function called. You cannot read CHARACTER data
6992 from a numeric variable or numeric data from a text variable. For
6993 numeric data, if the type of data differs from the netCDF variable
6994 type, type conversion will occur (see [(netcdf)Type
6995 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6996 in The NetCDF Users Guide).
7001 NF\_GET\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
7002 Otherwise, the returned status indicates an error. Possible causes of
7005 - The variable ID is invalid for the specified netCDF dataset.
7006 - The specified corner indices were out of range for the rank of the
7007 specified variable. For example, a negative index or an index that
7008 is larger than the corresponding dimension length will cause an
7010 - The specified edge lengths added to the specified corner would have
7011 referenced data out of range for the rank of the specified variable.
7012 For example, an edge length that is larger than the corresponding
7013 dimension length minus the corner index will cause an error.
7014 - One or more of the values are out of the range of values
7015 representable by the desired type.
7016 - The specified netCDF is in define mode rather than data mode.
7017 - The specified netCDF ID does not refer to an open netCDF dataset.
7022 Here is an example using NF\_GET\_VARA\_DOUBLE to read all the values of
7023 the variable named rh from an existing netCDF dataset named foo.nc. For
7024 simplicity in this example, we ame that we know that rh is
7025 dimensioned with lon, lat, and time, and that there are ten lon values,
7026 five lat values, and three time values.
7031 INCLUDE 'netcdf.inc'
7033 PARAMETER (NDIMS=3) ! number of dimensions
7034 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7035 INTEGER STATUS, NCID
7036 INTEGER RHID ! variable ID
7037 INTEGER START(NDIMS), COUNT(NDIMS)
7038 DOUBLE RHVALS(LONS, LATS, TIMES)
7039 DATA START /1, 1, 1/ ! start at first value
7040 DATA COUNT /LONS, LATS, TIMES/ ! get all the values
7042 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7043 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7045 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7046 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7047 STATUS = NF_GET_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
7048 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7051 6.27 NF\_GET\_VARS\_ type
7052 -------------------------
7054 The NF\_GET\_VARS\_ type family of functions read absampled (strided)
7055 array of values from a netCDF variable of an open netCDF
7056 dataset. Thebsampled array is specified by giving a corner, a
7057 vector of edge lengths, and a stride vector. The values are read with
7058 the first dimension of the netCDF variable varying fastest. The netCDF
7059 dataset must be in data mode.
7067 INTEGER FUNCTION NF_GET_VARS_TEXT (INTEGER NCID, INTEGER VARID,
7068 INTEGER START(*), INTEGER COUNT(*),
7069 INTEGER STRIDE(*),CHARACTER*(*) text)
7070 INTEGER FUNCTION NF_GET_VARS_INT1 (INTEGER NCID, INTEGER VARID,
7071 INTEGER START(*), INTEGER COUNT(*),
7072 INTEGER STRIDE(*),INTEGER*1 i1vals(*))
7073 INTEGER FUNCTION NF_GET_VARS_INT2 (INTEGER NCID, INTEGER VARID,
7074 INTEGER START(*), INTEGER COUNT(*),
7075 INTEGER STRIDE(*),INTEGER*2 i2vals(*))
7076 INTEGER FUNCTION NF_GET_VARS_INT (INTEGER NCID, INTEGER VARID,
7077 INTEGER START(*), INTEGER COUNT(*),
7078 INTEGER STRIDE(*), INTEGER ivals(*))
7079 INTEGER FUNCTION NF_GET_VARS_REAL (INTEGER NCID, INTEGER VARID,
7080 INTEGER START(*), INTEGER COUNT(*),
7081 INTEGER STRIDE(*), REAL rvals(*))
7082 INTEGER FUNCTION NF_GET_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
7083 INTEGER START(*), INTEGER COUNT(*),
7084 INTEGER STRIDE(*), DOUBLE dvals(*))
7088 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7094 : A vector of integers specifying the index in the variable from which
7095 the first of the data values will be read. The indices are relative
7096 to 1, so for example, the first data value of a variable would have
7097 index (1, 1, ..., 1). The elements of START correspond, in order, to
7098 the variable’s dimensions. Hence, if the variable is a record
7099 variable, the last index would correspond to the starting record
7100 number for reading the data values.
7103 : A vector of integers specifying the number of indices selected along
7104 each dimension. To read a single value, for example, specify COUNT
7105 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7106 the variable’s dimensions. Hence, if the variable is a record
7107 variable, the last element of COUNT corresponds to a count of the
7108 number of records to read.
7110 Note: setting any element of the count array to zero causes the
7111 function to exit without error, and without doing anything.
7114 : A vector of integers specifying, for each dimension, the interval
7115 between selected indices or the value 0. The elements of the vector
7116 correspond, in order, to the variable’s dimensions. A value of 1
7117 accesses adjacent values of the netCDF variable in the corresponding
7118 dimension; a value of 2 accesses every other value of the netCDF
7119 variable in the corresponding dimension; and so on. A 0 argument is
7120 treated as (1, 1, ..., 1).
7128 : The block of data values to be read. The data should be of the type
7129 appropriate for the function called. You cannot read CHARACTER data
7130 from a numeric variable or numeric data from a text variable. For
7131 numeric data, if the type of data differs from the netCDF variable
7132 type, type conversion will occur (see [(netcdf)Type
7133 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7134 in The NetCDF Users Guide).
7139 NF\_GET\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
7140 Otherwise, the returned status indicates an error. Possible causes of
7143 - The variable ID is invalid for the specified netCDF dataset.
7144 - The specified start, count and stride generate an index which is out
7146 - One or more of the values are out of the range of values
7147 representable by the desired type.
7148 - The specified netCDF is in define mode rather than data mode.
7149 - The specified netCDF ID does not refer to an open netCDF dataset.
7154 Here is an example using NF\_GET\_VARS\_DOUBLE to read every other value
7155 in each dimension of the variable named rh from an existing netCDF
7156 dataset named foo.nc. Values are assigned, using the same dimensional
7157 strides, to a 2-parameter array. For simplicity in this example, we
7158 ame that we know that rh is dimensioned with lon, lat, and time, and
7159 that there are ten lon values, five lat values, and three time values.
7164 INCLUDE 'netcdf.inc'
7166 PARAMETER (NDIMS=3) ! number of dimensions
7167 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7168 INTEGER STATUS, NCID
7169 INTEGER RHID ! variable ID
7170 INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
7171 DOUBLE DATA(LONS, LATS, TIMES)
7172 DATA START /1, 1, 1/ ! start at first value
7173 DATA COUNT /LONS, LATS, TIMES/
7174 DATA STRIDE /2, 2, 2/
7176 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7177 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7179 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7180 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7181 STATUS = NF_GET_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
7182 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7185 6.28 NF\_GET\_VARM\_ type
7186 -------------------------
7188 The NF\_GET\_VARM\_ type family of functions reads a mapped array
7189 section of values from a netCDF variable of an open netCDF dataset. The
7190 mapped array is specified by giving a corner, a vector of edge
7191 lengths, a stride vector, and an index mapping vector. The index mapping
7192 vector is a vector of integers that specifies the mapping between the
7193 dimensions of a netCDF variable and the in-memory structure of the
7194 internal data array. No amptions are made about the ordering or
7195 length of the dimensions of the data array. The netCDF dataset must be
7204 INTEGER FUNCTION NF_GET_VARM_TEXT (INTEGER NCID, INTEGER VARID,
7205 INTEGER START(*), INTEGER COUNT(*),
7206 INTEGER STRIDE(*), INTEGER IMAP(*),
7208 INTEGER FUNCTION NF_GET_VARM_INT1 (INTEGER NCID, INTEGER VARID,
7209 INTEGER START(*), INTEGER COUNT(*),
7210 INTEGER STRIDE(*), INTEGER IMAP(*),
7211 INTEGER*1 i1vals(*))
7212 INTEGER FUNCTION NF_GET_VARM_INT2 (INTEGER NCID, INTEGER VARID,
7213 INTEGER START(*), INTEGER COUNT(*),
7214 INTEGER STRIDE(*), INTEGER IMAP(*),
7215 INTEGER*2 i2vals(*))
7216 INTEGER FUNCTION NF_GET_VARM_INT (INTEGER NCID, INTEGER VARID,
7217 INTEGER START(*), INTEGER COUNT(*),
7218 INTEGER STRIDE(*), INTEGER IMAP(*),
7220 INTEGER FUNCTION NF_GET_VARM_REAL (INTEGER NCID, INTEGER VARID,
7221 INTEGER START(*), INTEGER COUNT(*),
7222 INTEGER STRIDE(*), INTEGER IMAP(*),
7224 INTEGER FUNCTION NF_GET_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
7225 INTEGER START(*), INTEGER COUNT(*),
7226 INTEGER STRIDE(*), INTEGER IMAP(*),
7231 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7237 : A vector of integers specifying the index in the variable from which
7238 the first of the data values will be read. The indices are relative
7239 to 1, so for example, the first data value of a variable would have
7240 index (1, 1, ..., 1). The elements of START correspond, in order, to
7241 the variable’s dimensions. Hence, if the variable is a record
7242 variable, the last index would correspond to the starting record
7243 number for reading the data values.
7246 : A vector of integers specifying the number of indices selected along
7247 each dimension. To read a single value, for example, specify COUNT
7248 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7249 the variable’s dimensions. Hence, if the variable is a record
7250 variable, the last element of COUNT corresponds to a count of the
7251 number of records to read.
7253 Note: setting any element of the count array to zero causes the
7254 function to exit without error, and without doing anything.
7257 : A vector of integers specifying, for each dimension, the interval
7258 between selected indices or the value 0. The elements of the vector
7259 correspond, in order, to the variable’s dimensions. A value of 1
7260 accesses adjacent values of the netCDF variable in the corresponding
7261 dimension; a value of 2 accesses every other value of the netCDF
7262 variable in the corresponding dimension; and so on. A 0 argument is
7263 treated as (1, 1, ..., 1).
7266 : A vector of integers that specifies the mapping between the
7267 dimensions of a netCDF variable and the in-memory structure of the
7268 internal data array. IMAP(1) gives the distance between elements of
7269 the internal array corresponding to the most rapidly varying
7270 dimension of the netCDF variable. IMAP(N) (where N is the rank of
7271 the netCDF variable) gives the distance between elements of the
7272 internal array corresponding to the most slowly varying dimension of
7273 the netCDF variable. Intervening IMAP elements correspond to other
7274 dimensions of the netCDF variable in the obvious way. Distances
7275 between elements are specified in units of elements (the distance
7276 between internal elements that occupy adjacent memory locations is 1
7277 and not the element’s byte-length as in netCDF 2).
7285 : The block of data values to be read. The data should be of the type
7286 appropriate for the function called. You cannot read CHARACTER data
7287 from a numeric variable or numeric data from a text variable. For
7288 numeric data, if the type of data differs from the netCDF variable
7289 type, type conversion will occur (see [(netcdf)Type
7290 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7291 in The NetCDF Users Guide).
7296 NF\_GET\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
7297 Otherwise, the returned status indicates an error. Possible causes of
7300 - The variable ID is invalid for the specified netCDF dataset.
7301 - The specified START, COUNT, and STRIDE generate an index which is
7302 out of range. Note that no error checking is possible on the imap
7304 - One or more of the values are out of the range of values
7305 representable by the desired type.
7306 - The specified netCDF is in define mode rather than data mode.
7307 - The specified netCDF ID does not refer to an open netCDF dataset.
7312 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
7313 variable and an internal array of the same shape:
7318 REAL A(2,3,4) ! same shape as netCDF variable
7320 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
7321 ! ---------------- ----------------------
7322 ! most rapidly varying 1
7323 ! intermediate 2 (=IMAP(1)*2)
7324 ! most slowly varying 6 (=IMAP(2)*3)
7327 Using the IMAP vector above with NF\_GET\_VARM\_REAL obtains the same
7328 rlt as simply using NF\_GET\_VAR\_REAL.
7330 Here is an example of using NF\_GET\_VARM\_REAL to transpose a netCDF
7331 variable named rh which is described by the FORTRAN declaration REAL
7332 RH(4,6) (note the size and order of the dimensions):
7337 INCLUDE 'netcdf.inc'
7339 PARAMETER (NDIM=2) ! rank of netCDF variable
7340 INTEGER NCID ! netCDF dataset ID
7341 INTEGER STATUS ! return code
7342 INTEGER RHID ! variable ID
7343 INTEGER START(NDIM) ! netCDF variable start point
7344 INTEGER COUNT(NDIM) ! size of internal array
7345 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7346 INTEGER IMAP(NDIM) ! internal array inter-element distances
7347 REAL RH(6,4) ! note transposition of netCDF variable dimensions
7348 DATA START /1, 1/ ! start at first netCDF variable element
7349 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
7350 ! to netCDF variable -- not internal array
7351 DATA STRIDE /1, 1/ ! sample every netCDF element
7352 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
7354 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7355 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7357 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7358 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7360 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7361 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7364 Here is another example of using NF\_GET\_VARM\_REAL to simultaneously
7365 transpose andbsample the same netCDF variable, by accessing every
7366 other point of the netCDF variable:
7371 INCLUDE 'netcdf.inc'
7373 PARAMETER (NDIM=2) ! rank of netCDF variable
7374 INTEGER NCID ! netCDF dataset ID
7375 INTEGER STATUS ! return code
7376 INTEGER RHID ! variable ID
7377 INTEGER START(NDIM) ! netCDF variable start point
7378 INTEGER COUNT(NDIM) ! size of internal array
7379 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7380 INTEGER IMAP(NDIM) ! internal array inter-element distances
7381 REAL RH(3,2) ! note transposition of bsampled) dimensions
7382 DATA START /1, 1/ ! start at first netCDF variable value
7383 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
7384 ! to netCDF variable -- not internal array
7385 DATA STRIDE /2, 2/ ! sample every other netCDF element
7386 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
7388 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7389 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7391 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7392 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7394 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7395 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7398 6.29 Reading and Writing Character String Values
7399 ------------------------------------------------
7401 Character strings are not a primitive netCDF external data type, in part
7402 because FORTRAN does notpport the abstraction of variable-length
7403 character strings (the FORTRAN LEN function returns the static length of
7404 a character string, not its dynamic length). As a rlt, a character
7405 string cannot be written or read as a single object in the netCDF
7406 interface. Instead, a character string must be treated as an array of
7407 characters, and array access must be used to read and write character
7408 strings as variable data in netCDF datasets. Furthermore,
7409 variable-length strings are notpported by the netCDF interface except
7410 by convention; for example, you may treat a zero byte as terminating a
7411 character string, but you must explicitly specify the length of strings
7412 to be read from and written to netCDF variables.
7414 Character strings as attribute values are easier to use, since the
7415 strings are treated as a single unit for access. However, the value of a
7416 character-string attribute is still an array of characters with an
7417 explicit length that must be specified when the attribute is defined.
7419 When you define a variable that will have character-string values, use a
7420 character-position dimension as the most quickly varying dimension for
7421 the variable (the first dimension for the variable in FORTRAN). The
7422 length of the character-position dimension will be the maximum string
7423 length of any value to be stored in the character-string variable. Space
7424 for maximum-length strings will be allocated in the disk representation
7425 of character-string variables whether you use the space or not. If two
7426 or more variables have the same maximum length, the same
7427 character-position dimension may be used in defining the variable
7430 To write a character-string value into a character-string variable, use
7431 either entire variable access or array access. The latter requires that
7432 you specify both a corner and a vector of edge lengths. The
7433 character-position dimension at the corner should be one for FORTRAN. If
7434 the length of the string to be written is n, then the vector of edge
7435 lengths will specify n in the character-position dimension, and one for
7436 all the other dimensions:(n, 1, 1, ..., 1).
7438 In FORTRAN, fixed-length strings may be written to a netCDF dataset
7439 without a terminating character, to save space. Variable-length strings
7440 should follow the C convention of writing strings with a terminating
7441 zero byte so that the intended length of the string can be determined
7442 when it is later read by either C or FORTRAN programs.
7444 The FORTRAN interface for reading and writing strings requires the use
7445 of different functions for accessing string values and numeric values,
7446 because standard FORTRAN does not permit the same formal parameter to be
7447 used for both character values and numeric values. An additional
7448 argument, specifying the declared length of the character string passed
7449 as a value, is required for NF\_PUT\_VARA\_TEXT and NF\_GET\_VARA\_TEXT.
7450 The actual length of the string is specified as the value of the
7451 edge-length vector corresponding to the character-position dimension.
7453 Here is an example that defines a record variable, tx, for character
7454 strings and stores a character-string value into the third record using
7455 NF\_PUT\_VARA\_TEXT. In this example, we ame the string variable and
7456 data are to be added to an existing netCDF dataset named foo.nc that
7457 already has an unlimited record dimension time.
7462 INCLUDE 'netcdf.inc'
7464 INTEGER TDIMS, TXLEN
7465 PARAMETER (TDIMS=2) ! number of TX dimensions
7466 PARAMETER (TXLEN = 15) ! length of example string
7468 INTEGER CHID ! char position dimension id
7469 INTEGER TIMEID ! record dimension id
7470 INTEGER TXID ! variable ID
7471 INTEGER TXDIMS(TDIMS) ! variable shape
7472 INTEGER TSTART(TDIMS), TCOUNT(TDIMS)
7473 CHARACTER*40 TXVAL ! max length 40
7474 DATA TXVAL /'example string'/
7476 TXVAL(TXLEN:TXLEN) = CHAR(0) ! null terminate
7478 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
7479 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7480 STATUS = NF_REDEF(NCID) ! enter define mode
7481 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7483 ! define character-position dimension for strings of max length 40
7484 STATUS = NF_DEF_DIM(NCID, "chid", 40, CHID)
7485 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7487 ! define a character-string variable
7488 TXDIMS(1) = CHID ! character-position dimension first
7490 STATUS = NF_DEF_VAR(NCID, "tx", NF_CHAR, TDIMS, TXDIMS, TXID)
7491 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7493 STATUS = NF_ENDDEF(NCID) ! leave define mode
7494 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7496 ! write txval into tx netCDF variable in record 3
7497 TSTART(1) = 1 ! start at beginning of variable
7498 TSTART(2) = 3 ! record number to write
7499 TCOUNT(1) = TXLEN ! number of chars to write
7500 TCOUNT(2) = 1 ! only write one record
7501 STATUS = NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL)
7502 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7508 What happens when you try to read a value that was never written in an
7509 open netCDF dataset? You might expect that this should always be an
7510 error, and that you should get an error message or an error status
7511 returned. You do get an error if you try to read data from a netCDF
7512 dataset that is not open for reading, if the variable ID is invalid for
7513 the specified netCDF dataset, or if the specified indices are not
7514 properly within the range defined by the dimension lengths of the
7515 specified variable. Otherwise, reading a value that was not written
7516 returns a special fill value used to fill in any undefined values when a
7517 netCDF variable is first written.
7519 You may ignore fill values and use the entire range of a netCDF external
7520 data type, but in this case you should makere you write all data
7521 values before reading them. If you know you will be writing all the data
7522 before reading it, you can specify that no prefilling of variables with
7523 fill values will occur by calling NF\_SET\_FILL before writing. This may
7524 provide a significant performance gain for netCDF writes.
7526 The variable attribute \_FillValue may be used to specify the fill value
7527 for a variable. Their are default fill values for each type, defined in
7528 the include file netcdf.inc: NF\_FILL\_CHAR, NF\_FILL\_INT1 (same as
7529 NF\_FILL\_BYTE), NF\_FILL\_INT2 (same as NF\_FILL\_SHORT),
7530 NF\_FILL\_INT, NF\_FILL\_REAL (same as NF\_FILL\_FLOAT), and
7533 The netCDF byte and character types have different default fill values.
7534 The default fill value for characters is the zero byte, a useful value
7535 for detecting the end of variable-length C character strings. If you
7536 need a fill value for a byte variable, it is recommended that you
7537 explicitly define an appropriate \_FillValue attribute, as generic
7538 utilitiesch as ncdump will not ame a default fill value for byte
7541 Type conversion for fill values is identical to type conversion for
7542 other values: attempting to convert a value from one type to another
7543 type that can’t represent the value rlts in a range error. Such
7544 errors may occur on writing or reading values from a larger type ch
7545 as double) to a smaller type ch as float), if the fill value for the
7546 larger type cannot be represented in the smaller type.
7548 6.31 NF\_RENAME\_VAR
7549 --------------------
7551 The function NF\_RENAME\_VAR changes the name of a netCDF variable in an
7552 open netCDF dataset. If the new name is longer than the old name, the
7553 netCDF dataset must be in define mode. You cannot rename a variable to
7554 have the name of any existing variable.
7562 INTEGER FUNCTION NF_RENAME_VAR (INTEGER NCID, INTEGER VARID,
7563 CHARACTER*(*) NEWNAM)
7567 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7573 : New name for the specified variable.
7578 NF\_RENAME\_VAR returns the value NF\_NOERR if no errors occurred.
7579 Otherwise, the returned status indicates an error. Possible causes of
7582 - The new name is in use as the name of another variable.
7583 - The variable ID is invalid for the specified netCDF dataset.
7584 - The specified netCDF ID does not refer to an open netCDF dataset.
7589 Here is an example using NF\_RENAME\_VAR to rename the variable rh to
7590 rel\_hum in an existing netCDF dataset named foo.nc:
7595 INCLUDE 'netcdf.inc'
7597 INTEGER STATUS, NCID
7598 INTEGER RHID ! variable ID
7600 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7601 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7603 STATUS = NF_REDEF (NCID) ! enter definition mode
7604 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7605 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7606 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7607 STATUS = NF_RENAME_VAR (NCID, RHID, 'rel_hum')
7608 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7609 STATUS = NF_ENDDEF (NCID) ! leave definition mode
7610 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7614 6.32 Change between Collective and Independent Parallel Access: NF\_VAR\_PAR\_ACCESS
7615 ------------------------------------------------------------------------------------
7617 The function NF\_VAR\_PAR\_ACCESS changes whether read/write operations
7618 on a parallel file system are performed collectively or independently
7619 (the default) on the variable. This function can only be called if the
7620 file was created with NF\_CREATE\_PAR (see
7621 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)) or opened with NF\_OPEN\_PAR
7622 (see [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)).
7624 This function is only available if the netCDF library was built with a
7625 HDF5 library for which –enable-parallel was used, and which was linked
7626 (like HDF5) to MPI libraries.
7628 Calling this function affects only the open file - information about
7629 whether a variable is to be accessed collectively or independently is
7630 not written to the data file. Every time you open a file on a parallel
7631 file system, all variables default to independent operations. The change
7632 a variable to collective lasts only as long as that file is open.
7634 The variable can be changed from collective to independent, and back, as
7643 INTEGER NF_VAR_PAR_ACCESS(INTEGER NCID, INTEGER VARID, INTEGER ACCESS);
7647 : NetCDF ID, from a previous call to NF\_OPEN\_PAR (see
7648 [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)) or NF\_CREATE\_PAR (see
7649 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)).
7655 : NF\_INDEPENDENT to set this variable to independent operations.
7656 NF\_COLLECTIVE to set it to collective operations.
7665 : No variable found.
7668 : Not a netCDF-4 file.
7671 : File not opened for parallel access.
7676 This example comes from test program nf\_test/ftst\_parallel.F. For this
7677 test to be run, netCDF must have been built with a parallel-enabled
7678 HDF5, and –enable-parallel-tests must have been used when configuring
7684 retval = nf_var_par_access(ncid, varid, nf_collective)
7685 if (retval .ne. nf_noerr) stop 2
7692 7.1 Attributes Introduction
7693 ---------------------------
7695 Attributes may be associated with each netCDF variable to specifych
7696 properties as units, special values, maximum and minimum valid values,
7697 scaling factors, and offsets. Attributes for a netCDF dataset are
7698 defined when the dataset is first created, while the netCDF dataset is
7699 in define mode. Additional attributes may be added later by reentering
7700 define mode. A netCDF attribute has a netCDF variable to which it is
7701 assigned, a name, a type, a length, and a sequence of one or more
7702 values. An attribute is designated by its variable ID and name. When an
7703 attribute name is not known, it may be designated by its variable ID and
7704 number in order to determine its name, using the function
7707 The attributes associated with a variable are typically defined
7708 immediately after the variable is created, while still in define mode.
7709 The data type, length, and value of an attribute may be changed even
7710 when in data mode, as long as the changed attribute requires no more
7711 space than the attribute as originally defined.
7713 It is also possible to have attributes that are not associated with any
7714 variable. These are called global attributes and are identified by using
7715 NF\_GLOBAL as a variable pseudo-ID. Global attributes are ally
7716 related to the netCDF dataset as a whole and may be used for purposes
7717 such as providing a title or processing history for a netCDF dataset.
7719 Attributes are much more useful when they follow established community
7720 conventions. See [(netcdf)Attribute
7721 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
7722 Conventions’ in The NetCDF Users Guide.
7724 Operationspported on attributes are:
7726 - Create an attribute, given its variable ID, name, data type, length,
7728 - Get attribute’s data type and length from its variable ID and name.
7729 - Get attribute’s value from its variable ID and name.
7730 - Copy attribute from one netCDF variable to another.
7731 - Get name of attribute from its number.
7732 - Rename an attribute.
7733 - Delete an attribute.
7735 7.2 NF\_PUT\_ATT\_ type
7736 -----------------------
7738 The function NF\_PUT\_ATT\_ type adds or changes a variable attribute or
7739 global attribute of an open netCDF dataset. If this attribute is new, or
7740 if the space required to store the attribute is greater than before, the
7741 netCDF dataset must be in define mode.
7746 Although it’s possible to create attributes of all types, text and
7747 double attributes are adequate for most purposes.
7752 INTEGER FUNCTION NF_PUT_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7753 CHARACTER*(*) NAME, INTEGER LEN,
7755 INTEGER FUNCTION NF_PUT_ATT_INT1 (INTEGER NCID, INTEGER VARID,
7756 CHARACTER*(*) NAME, INTEGER XTYPE,
7757 LEN, INTEGER*1 I1VALS(*))
7758 INTEGER FUNCTION NF_PUT_ATT_INT2 (INTEGER NCID, INTEGER VARID,
7759 CHARACTER*(*) NAME, INTEGER XTYPE,
7760 LEN, INTEGER*2 I2VALS(*))
7761 INTEGER FUNCTION NF_PUT_ATT_INT (INTEGER NCID, INTEGER VARID,
7762 CHARACTER*(*) NAME, INTEGER XTYPE,
7763 LEN, INTEGER IVALS(*))
7764 INTEGER FUNCTION NF_PUT_ATT_REAL (INTEGER NCID, INTEGER VARID,
7765 CHARACTER*(*) NAME, INTEGER XTYPE,
7767 INTEGER FUNCTION NF_PUT_ATT_DOUBLE(INTEGER NCID, INTEGER VARID,
7768 CHARACTER*(*) NAME, INTEGER XTYPE,
7769 LEN, DOUBLE DVALS(*))
7770 INTEGER FUNCTION NF_PUT_ATT (INTEGER NCID, INTEGER VARID,
7771 CHARACTER*(*) NAME, INTEGER XTYPE,
7776 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7779 : Variable ID of the variable to which the attribute will be assigned
7780 or NF\_GLOBAL for a global attribute.
7783 : Attribute name. Attribute name conventions are amed by some
7784 netCDF generic applications, e.g., ‘units’ as the name for a string
7785 attribute that gives the units for a netCDF variable. See
7786 [(netcdf)Attribute Conventions](netcdf.html#Attribute-Conventions)
7787 ‘Attribute Conventions’ in The NetCDF Users Guide.
7790 : One of the set of predefined netCDF external data types. The type of
7791 this parameter, NF\_TYPE, is defined in the netCDF header file. The
7792 valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
7793 NF\_INT, NF\_FLOAT, and NF\_DOUBLE. Although it’s possible to create
7794 attributes of all types, NF\_CHAR and NF\_DOUBLE attributes are
7795 adequate for most purposes.
7798 : Number of values provided for the attribute.
7807 : An array of LEN attribute values. The data should be of a type
7808 appropriate for the function called. You cannot write CHARACTER data
7809 into a numeric attribute or numeric data into a text attribute. For
7810 numeric data, if the type of data differs from the attribute type,
7811 type conversion will occur See [(netcdf)Type
7812 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7813 in The NetCDF Users Guide.
7818 NF\_PUT\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
7819 Otherwise, the returned status indicates an error. Possible causes of
7822 - The variable ID is invalid for the specified netCDF dataset.
7823 - The specified netCDF type is invalid.
7824 - The specified length is negative.
7825 - The specified open netCDF dataset is in data mode and the specified
7826 attribute would expand.
7827 - The specified open netCDF dataset is in data mode and the specified
7828 attribute does not already exist.
7829 - The specified netCDF ID does not refer to an open netCDF dataset.
7830 - The number of attributes for this variable exceeds NF\_MAX\_ATTRS.
7835 Here is an example using NF\_PUT\_ATT\_DOUBLE to add a variable
7836 attribute named valid\_range for a netCDF variable named rh and a global
7837 attribute named title to an existing netCDF dataset named foo.nc:
7842 INCLUDE 'netcdf.inc'
7844 INTEGER STATUS, NCID
7845 INTEGER RHID ! variable ID
7847 DATA RHRNGE /0.0D0, 100.0D0/
7849 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7850 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7852 STATUS = NF_REDEF (NCID) ! enter define mode
7853 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7854 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7855 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7857 STATUS = NF_PUT_ATT_DOUBLE (NCID, RHID, 'valid_range', NF_DOUBLE, &
7859 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7860 STATUS = NF_PUT_ATT_TEXT (NCID, NF_GLOBAL, 'title', 19,
7861 'example netCDF dataset')
7862 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7864 STATUS = NF_ENDDEF (NCID) ! leave define mode
7865 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7868 7.3 NF\_INQ\_ATT Family
7869 -----------------------
7871 This family of functions returns information about a netCDF attribute.
7872 All but one of these functions require the variable ID and attribute
7873 name; the exception is NF\_INQ\_ATTNAME. Information about an attribute
7874 includes its type, length, name, and number. See the NF\_GET\_ATT family
7875 for getting attribute values.
7877 The function NF\_INQ\_ATTNAME gets the name of an attribute, given its
7878 variable ID and number. This function is useful in generic applications
7879 that need to get the names of all the attributes associated with a
7880 variable, since attributes are accessed by name rather than number in
7881 all other attribute functions. The number of an attribute is more
7882 volatile than the name, since it can change when other attributes of the
7883 same variable are deleted. This is why an attribute number is not called
7886 The function NF\_INQ\_ATT returns the attribute’s type and length. The
7887 other functions each return just one item of information about an
7896 INTEGER FUNCTION NF_INQ_ATT (INTEGER NCID, INTEGER VARID,
7897 CHARACTER*(*) NAME, INTEGER xtype,
7899 INTEGER FUNCTION NF_INQ_ATTTYPE(INTEGER NCID, INTEGER VARID,
7900 CHARACTER*(*) NAME, INTEGER xtype)
7901 INTEGER FUNCTION NF_INQ_ATTLEN (INTEGER NCID, INTEGER VARID,
7902 CHARACTER*(*) NAME, INTEGER len)
7903 INTEGER FUNCTION NF_INQ_ATTNAME(INTEGER NCID, INTEGER VARID,
7904 INTEGER ATTNUM, CHARACTER*(*) name)
7905 INTEGER FUNCTION NF_INQ_ATTID (INTEGER NCID, INTEGER VARID,
7906 CHARACTER*(*) NAME, INTEGER attnum)
7910 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7913 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
7917 : Attribute name. For NF\_INQ\_ATTNAME, this is a pointer to the
7918 location for the returned attribute name.
7921 : Returned attribute type, one of the set of predefined netCDF
7922 external data types. The valid netCDF external data types are
7923 NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, and NF\_DOUBLE.
7926 : Returned number of values currently stored in the attribute. For a
7927 string-valued attribute, this is the number of characters in the
7931 : For NF\_INQ\_ATTNAME, the input attribute number; for
7932 NF\_INQ\_ATTID, the returned attribute number. The attributes for
7933 each variable are numbered from 1 (the first attribute) to NATTS,
7934 where NATTS is the number of attributes for the variable, as
7935 returned from a call to NF\_INQ\_VARNATTS.
7937 (If you already know an attribute name, knowing its number is not
7938 very useful, because accessing information about an attribute
7944 Each function returns the value NF\_NOERR if no errors occurred.
7945 Otherwise, the returned status indicates an error. Possible causes of
7948 - The variable ID is invalid for the specified netCDF dataset.
7949 - The specified attribute does not exist.
7950 - The specified netCDF ID does not refer to an open netCDF dataset.
7951 - For NF\_INQ\_ATTNAME, the specified attribute number is negative or
7952 more than the number of attributes defined for the specified
7958 Here is an example using NF\_INQ\_ATT to find out the type and length of
7959 a variable attribute named valid\_range for a netCDF variable named rh
7960 and a global attribute named title in an existing netCDF dataset named
7966 INCLUDE 'netcdf.inc'
7968 INTEGER STATUS, NCID
7969 INTEGER RHID ! variable ID
7970 INTEGER VRLEN, TLEN ! attribute lengths
7972 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7973 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7975 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7976 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7978 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
7979 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7980 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
7981 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7984 7.4 NF\_GET\_ATT\_ type
7985 -----------------------
7987 Members of the NF\_GET\_ATT\_ type family of functions get the value(s)
7988 of a netCDF attribute, given its variable ID and name.
7996 INTEGER FUNCTION NF_GET_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7999 INTEGER FUNCTION NF_GET_ATT_INT1 (INTEGER NCID, INTEGER VARID,
8001 INTEGER*1 i1vals(*))
8002 INTEGER FUNCTION NF_GET_ATT_INT2 (INTEGER NCID, INTEGER VARID,
8004 INTEGER*2 i2vals(*))
8005 INTEGER FUNCTION NF_GET_ATT_INT (INTEGER NCID, INTEGER VARID,
8008 INTEGER FUNCTION NF_GET_ATT_REAL (INTEGER NCID, INTEGER VARID,
8011 INTEGER FUNCTION NF_GET_ATT_DOUBLE (INTEGER NCID, INTEGER VARID,
8014 INTEGER FUNCTION NF_GET_ATT (INTEGER NCID, INTEGER VARID,
8015 CHARACTER*(*) NAME, * vals(*))
8019 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8022 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
8035 : Returned attribute values. All elements of the vector of attribute
8036 values are returned, so you must provide enough space to hold them.
8037 If you don’t know how much space to reserve, call NF\_INQ\_ATTLEN
8038 first to find out the length of the attribute. You cannot read
8039 character data from a numeric variable or numeric data from a text
8040 variable. For numeric data, if the type of data differs from the
8041 netCDF variable type, type conversion will occur. See [(netcdf)Type
8042 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
8043 in The The NetCDF Users Guide.
8048 NF\_GET\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
8049 Otherwise, the returned status indicates an error. Possible causes of
8052 - The variable ID is invalid for the specified netCDF dataset.
8053 - The specified attribute does not exist.
8054 - The specified netCDF ID does not refer to an open netCDF dataset.
8055 - One or more of the attribute values are out of the range of values
8056 representable by the desired type.
8061 Here is an example using NF\_GET\_ATT\_DOUBLE to determine the values of
8062 a variable attribute named valid\_range for a netCDF variable named rh
8063 and a global attribute named title in an existing netCDF dataset named
8064 foo.nc. In this example, it is amed that we don’t know how many
8065 values will be returned, but that we do know the types of the
8066 attributes. Hence, to allocate enough space to store them, we must first
8067 inquire about the length of the attributes.
8072 INCLUDE 'netcdf.inc'
8074 PARAMETER (MVRLEN=3) ! max number of "valid_range" values
8075 PARAMETER (MTLEN=80) ! max length of "title" attribute
8076 INTEGER STATUS, NCID
8077 INTEGER RHID ! variable ID
8078 INTEGER VRLEN, TLEN ! attribute lengths
8079 DOUBLE PRECISION VRVAL(MVRLEN) ! vr attribute values
8080 CHARACTER*80 TITLE ! title attribute values
8082 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8083 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8085 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8086 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8088 ! find out attribute lengths, to makere we have enough space
8089 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
8090 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8091 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
8092 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8093 ! get attribute values, if not too big
8094 IF (VRLEN .GT. MVRLEN) THEN
8095 WRITE (*,*) 'valid_range attribute too big!'
8098 STATUS = NF_GET_ATT_DOUBLE (NCID, RHID, 'valid_range', VRVAL)
8099 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8101 IF (TLEN .GT. MTLEN) THEN
8102 WRITE (*,*) 'title attribute too big!'
8105 STATUS = NF_GET_ATT_TEXT (NCID, NF_GLOBAL, 'title', TITLE)
8106 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8113 The function NF\_COPY\_ATT copies an attribute from one open netCDF
8114 dataset to another. It can also be used to copy an attribute from one
8115 variable to another within the same netCDF.
8117 If used to copy an attribute of user-defined type, then that
8118 user-defined type must already be defined in the target file. In the
8119 case of user-defined attributes, enddef/redef is called for ncid\_in and
8120 ncid\_out if they are in define mode. (This is the ere that all
8121 user-defined types are committed to the file(s) before the copy is
8130 INTEGER FUNCTION NF_COPY_ATT (INTEGER NCID_IN, INTEGER VARID_IN,
8131 CHARACTER*(*) NAME, INTEGER NCID_OUT,
8136 : The netCDF ID of an input netCDF dataset from which the attribute
8137 will be copied, from a previous call to NF\_OPEN or NF\_CREATE.
8140 : ID of the variable in the input netCDF dataset from which the
8141 attribute will be copied, or NF\_GLOBAL for a global attribute.
8144 : Name of the attribute in the input netCDF dataset to be copied.
8147 : The netCDF ID of the output netCDF dataset to which the attribute
8148 will be copied, from a previous call to NF\_OPEN or NF\_CREATE. It
8149 is permissible for the input and output netCDF IDs to be the same.
8150 The output netCDF dataset should be in define mode if the attribute
8151 to be copied does not already exist for the target variable, or if
8152 it would cause an existing target attribute to grow.
8155 : ID of the variable in the output netCDF dataset to which the
8156 attribute will be copied, or NF\_GLOBAL to copy to a global
8162 NF\_COPY\_ATT returns the value NF\_NOERR if no errors occurred.
8163 Otherwise, the returned status indicates an error. Possible causes of
8166 - The input or output variable ID is invalid for the specified netCDF
8168 - The specified attribute does not exist.
8169 - The output netCDF is not in define mode and the attribute is new for
8170 the output dataset is larger than the existing attribute.
8171 - The input or output netCDF ID does not refer to an open netCDF
8177 Here is an example using NF\_COPY\_ATT to copy the variable attribute
8178 units from the variable rh in an existing netCDF dataset named foo.nc to
8179 the variable avgrh in another existing netCDF dataset named bar.nc,
8180 aming that the variable avgrh already exists, but does not yet have a
8186 INCLUDE 'netcdf.inc'
8188 INTEGER STATUS ! error status
8189 INTEGER NCID1, NCID2 ! netCDF IDs
8190 INTEGER RHID, AVRHID ! variable IDs
8192 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID1)
8193 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8194 STATUS = NF_OPEN ('bar.nc', NF_WRITE, NCID2)
8195 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8197 STATUS = NF_INQ_VARID (NCID1, 'rh', RHID)
8198 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8199 STATUS = NF_INQ_VARID (NCID2, 'avgrh', AVRHID)
8200 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8202 STATUS = NF_REDEF (NCID2) ! enter define mode
8203 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8204 ! copy variable attribute from "rh" to "avgrh"
8205 STATUS = NF_COPY_ATT (NCID1, RHID, 'units', NCID2, AVRHID)
8206 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8208 STATUS = NF_ENDDEF (NCID2) ! leave define mode
8209 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8215 The function NF\_RENAME\_ATT changes the name of an attribute. If the
8216 new name is longer than the original name, the netCDF dataset must be in
8217 define mode. You cannot rename an attribute to have the same name as
8218 another attribute of the same variable.
8226 INTEGER FUNCTION NF_RENAME_ATT (INTEGER NCID, INTEGER VARID,
8228 CHARACTER*(*) NEWNAME)
8232 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE
8235 : ID of the attribute’s variable, or NF\_GLOBAL for a global attribute
8238 : The current attribute name.
8241 : The new name to be assigned to the specified attribute. If the new
8242 name is longer than the current name, the netCDF dataset must be in
8248 NF\_RENAME\_ATT returns the value NF\_NOERR if no errors occurred.
8249 Otherwise, the returned status indicates an error. Possible causes of
8252 - The specified variable ID is not valid.
8253 - The new attribute name is already in use for another attribute of
8254 the specified variable.
8255 - The specified netCDF dataset is in data mode and the new name is
8256 longer than the old name.
8257 - The specified attribute does not exist.
8258 - The specified netCDF ID does not refer to an open netCDF dataset.
8263 Here is an example using NF\_RENAME\_ATT to rename the variable
8264 attribute units to Units for a variable rh in an existing netCDF dataset
8270 INCLUDE "netcdf.inc"
8272 INTEGER STATUS ! error status
8273 INTEGER NCID ! netCDF ID
8274 INTEGER RHID ! variable ID
8276 STATUS = NF_OPEN ("foo.nc", NF_NOWRITE, NCID)
8277 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8279 STATUS = NF_INQ_VARID (NCID, "rh", RHID)
8280 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8283 STATUS = NF_RENAME_ATT (NCID, RHID, "units", "Units")
8284 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8290 The function NF\_DEL\_ATT deletes a netCDF attribute from an open netCDF
8291 dataset. The netCDF dataset must be in define mode.
8296 INTEGER FUNCTION NF\_DEL\_ATT (INTEGER NCID, INTEGER VARID,
8297 CHARACTER\*(\*) NAME)
8300 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8303 : ID of the attribute’s variable, or NF\_GLOBAL for a global
8307 : The name of the attribute to be deleted.
8312 NF\_DEL\_ATT returns the value NF\_NOERR if no errors occurred.
8313 Otherwise, the returned status indicates an error. Possible causes of
8316 - The specified variable ID is not valid.
8317 - The specified netCDF dataset is in data mode.
8318 - The specified attribute does not exist.
8319 - The specified netCDF ID does not refer to an open netCDF dataset.
8324 Here is an example using NF\_DEL\_ATT to delete the variable attribute
8325 Units for a variable rh in an existing netCDF dataset named foo.nc:
8330 INCLUDE 'netcdf.inc'
8332 INTEGER STATUS ! error status
8333 INTEGER NCID ! netCDF ID
8334 INTEGER RHID ! variable ID
8336 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8337 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8339 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8340 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8343 STATUS = NF_REDEF (NCID) ! enter define mode
8344 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8345 STATUS = NF_DEL_ATT (NCID, RHID, 'Units')
8346 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8347 STATUS = NF_ENDDEF (NCID) ! leave define mode
8348 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8351 A. NetCDF 2 to NetCDF 3 Fortran 77 Transition Guide {#f77_nc2_to_nc3_transition_guide}
8352 ===================================================
8354 A.1 Overview of FORTRAN interface changes {#f77_overview_of_interface_changes}
8355 -----------------------------------------
8357 NetCDF version 3 includes a complete rewrite of the netCDF library. It
8358 is about twice as fast as the previous version. The netCDF file format
8359 is unchanged, so files written with version 3 can be read with version 2
8360 code and vice versa.
8362 The core library is now written in ANSI C. You must have an ANSI C
8363 compiler to compile this version. The FORTRAN interface is layered on
8364 top of the C interface using a different technique than was used in
8367 Rewriting the library offered an opportunity to implement improved C and
8368 FORTRAN interfaces that provide some significant benefits:
8370 - type safety, by eliminating the need to use type punning in
8372 - automatic type conversions, by eliminating the undesirable coupling
8373 between the language-independent external netCDF types (NF\_BYTE,
8374 ..., NF\_DOUBLE) and language-dependent internal data types (INT\*1,
8375 ..., DOUBLE PRECISION);
8376 - pport for future enhancements, by eliminating obstacles to the
8377 clean addition ofpport for packed data and multithreading;
8378 - more standard error behavior, by uniformly communicating an error
8379 status back to the calling program in the return value of each
8382 It is not necessary to rewrite programs that use the version 2 FORTRAN
8383 interface, because the netCDF-3 library includes a backward
8384 compatibility interface thatpports all the old functions, globals,
8385 and behavior. We are hoping that the benefits of the new interface will
8386 be an incentive to use it in new netCDF applications. It is possible to
8387 convert old applications to the new interface incrementally, replacing
8388 netCDF-2 calls with the corresponding netCDF-3 calls one at a time.
8390 Other changes in the implementation of netCDF rlt in improved
8391 portability, maintainability, and performance on most platforms. A clean
8392 separation between I/O and type layers facilitates platform-specific
8393 optimizations. The new library no longer uses a vendor-provided XDR
8394 library, which simplifies linking programs that use netCDF and speeds up
8395 data access significantly in most cases.
8397 A.2 The New FORTRAN Interface {#f77_new_fortran_interface}
8398 -----------------------------
8400 First, here’s an example of FORTRAN code that uses the netCDF-2
8406 ! Use a buffer big enough for values of any type
8407 DOUBLE PRECISION DBUF(NDATA)
8410 EQUIVALENCE (RBUF, DBUF), ...
8411 INT XTYPE ! to hold the actual type of the data
8412 INT STATUS ! for error status
8413 ! Get the actual data type
8414 CALL NCVINQ(NCID, VARID, ...,XTYPE, ...)
8417 CALL NCVGT(NCID, VARID, START, COUNT, DBUF, STATUS)
8418 IF(STATUS .NE. NCNOERR) THEN
8419 PRINT *, 'Cannot get data, error code =', STATUS
8423 IF (XTYPE .EQ. NCDOUBLE) THEN
8425 ELSEIF (XTYPE .EQ. NCFLOAT) THEN
8431 Here’s how you might handle this with the new netCDF-3 FORTRAN
8437 ! I want to use doubles for my analysis
8438 DOUBLE PRECISION DBUF(NDATA)
8440 ! So I use a function that gets the data as doubles.
8441 STATUS = NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, DBUF)
8442 IF(STATUS .NE. NF_NOERR) THEN
8443 PRINT *, 'Cannot get data, ', NF_STRERROR(STATUS)
8450 The example above illustrates changes in function names, data type
8451 conversion, and error handling, discussed in detail in thes
8454 A.3 Function Naming Conventions {#f77_function_naming_conventions}
8455 -------------------------------
8457 The netCDF-3 Fortran 77 library employs a naming convention intended to
8458 make netCDF programs more readable. For example, the name of the
8459 function to rename a variable is now NF\_RENAME\_VAR instead of the
8462 All netCDF-3 FORTRAN function names begin with the NF\_ prefix. The
8463 second part of the name is a verb, like GET, PUT, INQ (for inquire), or
8464 OPEN. The third part of the name is typically the object of the verb:
8465 for example DIM, VAR, or ATT for functions dealing with dimensions,
8466 variables, or attributes. To distinguish the various I/O operations for
8467 variables, a single character modifier is appended to VAR:
8469 - VAR entire variable access
8470 - VAR1 single value access
8471 - VARA array or array access
8472 - VARS strided access to absample of values
8473 - VARM mapped access to values not contiguous in memory
8475 At the end of the name for variable and attribute functions, there is a
8476 component indicating the type of the final argument: TEXT, INT1, INT2,
8477 INT, REAL, or DOUBLE. This part of the function name indicates the type
8478 of the data container you are using in your program: character string,
8479 1-byte integer, and so on.
8481 Also, all PARAMETER names in the public FORTRAN interface begin with the
8482 prefix NF\_. For example, the PARAMETER which was formerly MAXNCNAM is
8483 now NF\_MAX\_NAME, and the former FILFLOAT is now NF\_FILL\_FLOAT.
8485 As previously mentioned, all the old names are stillpported for
8486 backward compatibility.
8488 A.4 Type Conversion {#f77_type_conversion}
8491 With the new interface, users need not be aware of the external type of
8492 numeric variables, since automatic conversion to or from any desired
8493 numeric type is now available. You can use this feature to simplify
8494 code, by making it independent of external types. The elimination of
8495 type punning prevents some kinds of type errors that could occur with
8496 the previous interface. Programs may be made more robust with the new
8497 interface, because they need not be changed to accommodate a change to
8498 the external type of a variable.
8500 If conversion to or from an external numeric type is necessary, it is
8501 handled by the library. This automatic conversion and separation of
8502 external data representation from internal data types will become even
8503 more important in netCDF version 4, when new external types will be
8504 added for packed data for which there is no natural corresponding
8505 internal type, for example, arrays of 11-bit values.
8507 Converting from one numeric type to another may rlt in an error if
8508 the target type is not capable of representing the converted value. (In
8509 netCDF-2,ch overflows can only happen in the XDR layer.) For example,
8510 a REAL may not be able to hold data stored externally as an NF\_DOUBLE
8511 (an IEEE floating-point number). When accessing an array of values, an
8512 NF\_ERANGE error is returned if one or more values are out of the range
8513 of representable values, but other values are converted properly.
8515 Note that mere loss of precision in type conversion does not return an
8516 error. Thus, if you read double precision values into an INTEGER, for
8517 example, no error rlts unless the magnitude of the double precision
8518 value exceeds the representable range of INTEGERs on your platform.
8519 Similarly, if you read a large integer into a REAL incapable of
8520 representing all the bits of the integer in its mantissa, this loss
8521 There are two new functions in netCDF-3 that don’t correspond to any
8522 netCDF-2 functions: NF\_INQ\_LIBVERS and NF\_STRERROR. The version ation
8523 The previous implementation returned an error when the same dimension
8524 was used more than once in specifying the shape of a variable in
8525 ncvardef. This restriction is relaxed in the netCDF-3 implementation,
8526 because an autocorrelation matrix is a good example where using the same
8527 dimension twice makes sense.
8529 In the new interface, units for the IMAP argument to the NF\_PUT\_VARM
8530 and NF\_GET\_VARM families of functions are now in terms of the number
8531 of data elements of the desired internal type, not in terms of bytes as
8532 in the netCDF version-2 mapped access interfaces.
8534 Following is a table of netCDF-2 function names and names of the
8535 corresponding netCDF-3 functions. For parameter lists of netCDF-2
8536 functions, see the netCDF-2 User’s Guide.
8548 : NF\_GET\_ATT\_DOUBLE, NF\_GET\_ATT\_REAL, NF\_GET\_ATT\_INT,
8549 NF\_GET\_ATT\_INT1, NF\_GET\_ATT\_INT2
8552 : NF\_GET\_ATT\_TEXT
8555 : NF\_INQ\_ATT, NF\_INQ\_ATTID, NF\_INQ\_ATTLEN, NF\_INQ\_ATTTYPE
8561 : NF\_PUT\_ATT\_DOUBLE, NF\_PUT\_ATT\_REAL, NF\_PUT\_ATT\_INT,
8562 NF\_PUT\_ATT\_INT1NF\_PUT
8564 B. Summary of FORTRAN 77 Interface {#f77_interface_summary}
8565 ==================================
8567 Input parameters are in upper case, output parameters are in lower case.
8568 The FORTRAN types of all the parameters are listed alphabetically by
8569 parameter name below the function declarations.
8575 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
8576 CHARACTER*80 FUNCTION NF_STRERROR (NCERR)
8577 INTEGER FUNCTION NF_CREATE (PATH, CMODE, ncid)
8578 INTEGER FUNCTION NF_OPEN (PATH, MODE, ncid)
8579 INTEGER FUNCTION NF_SET_FILL (NCID, FILLMODE, old_mode)
8580 INTEGER FUNCTION NF_REDEF (NCID)
8581 INTEGER FUNCTION NF_ENDDEF (NCID)
8582 INTEGER FUNCTION NF_SYNC (NCID)
8583 INTEGER FUNCTION NF_ABORT (NCID)
8584 INTEGER FUNCTION NF_CLOSE (NCID)
8585 INTEGER FUNCTION NF_INQ (NCID, ndims, nvars, ngatts,
8587 INTEGER FUNCTION NF_INQ_NDIMS (NCID, ndims)
8588 INTEGER FUNCTION NF_INQ_NVARS (NCID, nvars)
8589 INTEGER FUNCTION NF_INQ_NATTS (NCID, ngatts)
8590 INTEGER FUNCTION NF_INQ_UNLIMDIM (NCID, unlimdimid)
8591 INTEGER FUNCTION NF_DEF_DIM (NCID, NAME, LEN, dimid)
8592 INTEGER FUNCTION NF_INQ_DIMID (NCID, NAME, dimid)
8593 INTEGER FUNCTION NF_INQ_DIM (NCID, DIMID, name, len)
8594 INTEGER FUNCTION NF_INQ_DIMNAME (NCID, DIMID, name)
8595 INTEGER FUNCTION NF_INQ_DIMLEN (NCID, DIMID, len)
8596 INTEGER FUNCTION NF_RENAME_DIM (NCID, DIMID, NAME)
8598 INTEGER FUNCTION NF_DEF_VAR (NCID, NAME, XTYPE, NDIMS, DIMIDS,
8600 INTEGER FUNCTION NF_INQ_VAR (NCID, VARID, name, xtype, ndims,
8602 INTEGER FUNCTION NF_INQ_VARID (NCID, NAME, varid)
8603 INTEGER FUNCTION NF_INQ_VARNAME (NCID, VARID, name)
8604 INTEGER FUNCTION NF_INQ_VARTYPE (NCID, VARID, xtype)
8605 INTEGER FUNCTION NF_INQ_VARNDIMS (NCID, VARID, ndims)
8606 INTEGER FUNCTION NF_INQ_VARDIMID (NCID, VARID, DIMIDS)
8607 INTEGER FUNCTION NF_INQ_VARNATTS (NCID, VARID, natts)
8608 INTEGER FUNCTION NF_RENAME_VAR (NCID, VARID, NAME)
8609 INTEGER FUNCTION NF_PUT_VAR_TEXT (NCID, VARID, TEXT)
8610 INTEGER FUNCTION NF_GET_VAR_TEXT (NCID, VARID, text)
8611 INTEGER FUNCTION NF_PUT_VAR_INT1 (NCID, VARID, I1VAL)
8612 INTEGER FUNCTION NF_GET_VAR_INT1 (NCID, VARID, i1val)
8613 INTEGER FUNCTION NF_PUT_VAR_INT2 (NCID, VARID, I2VAL)
8614 INTEGER FUNCTION NF_GET_VAR_INT2 (NCID, VARID, i2val)
8615 INTEGER FUNCTION NF_PUT_VAR_INT (NCID, VARID, IVAL)
8616 INTEGER FUNCTION NF_GET_VAR_INT (NCID, VARID, ival)
8617 INTEGER FUNCTION NF_PUT_VAR_REAL (NCID, VARID, RVAL)
8618 INTEGER FUNCTION NF_GET_VAR_REAL (NCID, VARID, rval)
8619 INTEGER FUNCTION NF_PUT_VAR_DOUBLE (NCID, VARID, DVAL)
8620 INTEGER FUNCTION NF_GET_VAR_DOUBLE (NCID, VARID, dval)
8621 INTEGER FUNCTION NF_PUT_VAR1_TEXT (NCID, VARID, INDEX, TEXT)
8622 INTEGER FUNCTION NF_GET_VAR1_TEXT (NCID, VARID, INDEX, text)
8623 INTEGER FUNCTION NF_PUT_VAR1_INT1 (NCID, VARID, INDEX, I1VAL)
8624 INTEGER FUNCTION NF_GET_VAR1_INT1 (NCID, VARID, INDEX, i1val)
8625 INTEGER FUNCTION NF_PUT_VAR1_INT2 (NCID, VARID, INDEX, I2VAL)
8626 INTEGER FUNCTION NF_GET_VAR1_INT2 (NCID, VARID, INDEX, i2val)
8627 INTEGER FUNCTION NF_PUT_VAR1_INT (NCID, VARID, INDEX, IVAL)
8628 INTEGER FUNCTION NF_GET_VAR1_INT (NCID, VARID, INDEX, ival)
8629 INTEGER FUNCTION NF_PUT_VAR1_REAL (NCID, VARID, INDEX, RVAL)
8630 INTEGER FUNCTION NF_GET_VAR1_REAL (NCID, VARID, INDEX, rval)
8631 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(NCID, VARID, INDEX, DVAL)
8632 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(NCID, VARID, INDEX, dval)
8633 INTEGER FUNCTION NF_PUT_VARA_TEXT (NCID, VARID, START, COUNT, TEXT)
8634 INTEGER FUNCTION NF_GET_VARA_TEXT (NCID, VARID, START, COUNT, text)
8635 INTEGER FUNCTION NF_PUT_VARA_INT1 (NCID, VARID, START, COUNT, I1VALS)
8636 INTEGER FUNCTION NF_GET_VARA_INT1 (NCID, VARID, START, COUNT, i1vals)
8637 INTEGER FUNCTION NF_PUT_VARA_INT2 (NCID, VARID, START, COUNT, I2VALS)
8638 INTEGER FUNCTION NF_GET_VARA_INT2 (NCID, VARID, START, COUNT, i2vals)
8639 INTEGER FUNCTION NF_PUT_VARA_INT (NCID, VARID, START, COUNT, IVALS)
8640 INTEGER FUNCTION NF_GET_VARA_INT (NCID, VARID, START, COUNT, ivals)
8641 INTEGER FUNCTION NF_PUT_VARA_REAL (NCID, VARID, START, COUNT, RVALS)
8642 INTEGER FUNCTION NF_GET_VARA_REAL (NCID, VARID, START, COUNT, rvals)
8643 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(NCID, VARID, START, COUNT, DVALS)
8644 INTEGER FUNCTION NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, dvals)
8645 INTEGER FUNCTION NF_PUT_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8647 INTEGER FUNCTION NF_GET_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8649 INTEGER FUNCTION NF_PUT_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8651 INTEGER FUNCTION NF_GET_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8653 INTEGER FUNCTION NF_PUT_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8655 INTEGER FUNCTION NF_GET_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8657 INTEGER FUNCTION NF_PUT_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8659 INTEGER FUNCTION NF_GET_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8661 INTEGER FUNCTION NF_PUT_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8663 INTEGER FUNCTION NF_GET_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8665 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8667 INTEGER FUNCTION NF_GET_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8669 INTEGER FUNCTION NF_PUT_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8671 INTEGER FUNCTION NF_GET_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8673 INTEGER FUNCTION NF_PUT_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8675 INTEGER FUNCTION NF_GET_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8677 INTEGER FUNCTION NF_PUT_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8679 INTEGER FUNCTION NF_GET_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8681 INTEGER FUNCTION NF_PUT_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8683 INTEGER FUNCTION NF_GET_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8685 INTEGER FUNCTION NF_PUT_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8687 INTEGER FUNCTION NF_GET_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8689 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8691 INTEGER FUNCTION NF_GET_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8694 INTEGER FUNCTION NF_INQ_ATT (NCID, VARID, NAME, xtype, len)
8695 INTEGER FUNCTION NF_INQ_ATTID (NCID, VARID, NAME, attnum)
8696 INTEGER FUNCTION NF_INQ_ATTTYPE (NCID, VARID, NAME, xtype)
8697 INTEGER FUNCTION NF_INQ_ATTLEN (NCID, VARID, NAME, len)
8698 INTEGER FUNCTION NF_INQ_ATTNAME (NCID, VARID, ATTNUM, name)
8699 INTEGER FUNCTION NF_COPY_ATT (NCID_IN, VARID_IN, NAME,
8700 NCID_OUT, VARID_OUT)
8701 INTEGER FUNCTION NF_RENAME_ATT (NCID, VARID, CURNAME, NEWNAME)
8702 INTEGER FUNCTION NF_DEL_ATT (NCID, VARID, NAME)
8703 INTEGER FUNCTION NF_PUT_ATT_TEXT (NCID, VARID, NAME, LEN, TEXT)
8704 INTEGER FUNCTION NF_GET_ATT_TEXT (NCID, VARID, NAME, text)
8705 INTEGER FUNCTION NF_PUT_ATT_INT1 (NCID, VARID, NAME, XTYPE, LEN,
8707 INTEGER FUNCTION NF_GET_ATT_INT1 (NCID, VARID, NAME, i1vals)
8708 INTEGER FUNCTION NF_PUT_ATT_INT2 (NCID, VARID, NAME, XTYPE, LEN,
8710 INTEGER FUNCTION NF_GET_ATT_INT2 (NCID, VARID, NAME, i2vals)
8711 INTEGER FUNCTION NF_PUT_ATT_INT (NCID, VARID, NAME, XTYPE, LEN,
8713 INTEGER FUNCTION NF_GET_ATT_INT (NCID, VARID, NAME, ivals)
8714 INTEGER FUNCTION NF_PUT_ATT_REAL (NCID, VARID, NAME, XTYPE, LEN,
8716 INTEGER FUNCTION NF_GET_ATT_REAL (NCID, VARID, NAME, rvals)
8717 INTEGER FUNCTION NF_PUT_ATT_DOUBLE (NCID, VARID, NAME, XTYPE, LEN,
8719 INTEGER FUNCTION NF_GET_ATT_DOUBLE (NCID, VARID, NAME, dvals)
8721 INTEGER ATTNUM ! attribute number
8722 INTEGER attnum ! returned attribute number
8723 INTEGER CMODE ! NF_NOCLOBBER, NF_SHARE flags expression
8724 INTEGER COUNT ! array of edge lengths of block of values
8725 CHARACTER(*) CURNAME ! current name (before renaming)
8726 INTEGER DIMID ! dimension ID
8727 INTEGER dimid ! returned dimension ID
8728 INTEGER DIMIDS ! list of dimension IDs
8729 INTEGER dimids ! list of returned dimension IDs
8730 DOUBLEPRECISION DVAL ! single data value
8731 DOUBLEPRECISION dval ! returned single data value
8732 DOUBLEPRECISION DVALS ! array of data values
8733 DOUBLEPRECISION dvals ! array of returned data values
8734 INTEGER FILLMODE ! NF_NOFILL or NF_FILL, for setting fill mode
8735 INTEGER*1 I1VAL ! single data value
8736 INTEGER*1 I1val ! returned single data value
8737 INTEGER*1 I1VALS ! array of data values
8738 INTEGER*1 i1vals ! array of returned data values
8739 INTEGER*2 I2VAL ! single data value
8740 INTEGER*2 i2val ! returned single data value
8741 INTEGER*2 I2VALS ! array of data values
8742 INTEGER*2 i2vals ! array of returned data values
8743 INTEGER IMAP ! index mapping vector
8744 INTEGER INDEX ! variable array index vector
8745 INTEGER IVAL ! single data value
8746 INTEGER ival ! returned single data value
8747 INTEGER IVALS ! array of data values
8748 INTEGER ivals ! array of returned data values
8749 INTEGER LEN ! dimension or attribute length
8750 INTEGER len ! returned dimension or attribute length
8751 INTEGER MODE ! open mode, one of NF_WRITE or NF_NOWRITE
8752 CHARACTER(*) NAME ! dimension, variable, or attribute name
8753 CHARACTER(*) name ! returned dim, var, or att name
8754 INTEGER natts ! returned number of attributes
8755 INTEGER NCERR ! error returned from NF_xxx function call
8756 INTEGER NCID ! netCDF ID of an open netCDF dataset
8757 INTEGER ncid ! returned netCDF ID
8758 INTEGER NCID_IN ! netCDF ID of open source netCDF dataset
8759 INTEGER NCID_OUT ! netCDF ID of open destination netCDF dataset
8760 INTEGER NDIMS ! number of dimensions
8761 INTEGER ndims ! returned number of dimensions
8762 CHARACTER(*) NEWNAME ! new name for dim, var, or att
8763 INTEGER ngatts ! returned number of global attributes
8764 INTEGER nvars ! returned number of variables
8765 INTEGER old_mode ! previous fill mode, NF_NOFILL or NF_FILL,
8766 CHARACTER(*) PATH ! name of netCDF dataset
8767 REAL RVAL ! single data value
8768 REAL rval ! returned single data value
8769 REAL RVALS ! array of data values
8770 REAL rvals ! array of returned data values
8771 INTEGER START ! variable array indices of first value
8772 INTEGER STRIDE ! variable array dimensional strides
8773 CHARACTER(*) TEXT ! input text value
8774 CHARACTER(*) text ! returned text value
8775 INTEGER unlimdimid ! returned ID of unlimited dimension
8776 INTEGER VARID ! variable ID
8777 INTEGER varid ! returned variable ID
8778 INTEGER VARID_IN ! variable ID
8779 INTEGER VARID_OUT ! variable ID
8780 INTEGER XTYPE ! external type: NF_BYTE, NF_CHAR, ... ,
8781 INTEGER xtype ! returned external type