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 runninga program using netCDF library calls to write data. See
16 section ‘ncgen’ in The NetCDF Users
17 Guide.) Similarly, if you are writing software to access data stored in
18 a particular netCDF object, only a smallbset of the netCDF library is
19 required to open the netCDF dataset and access the data. Authors of
20 generic applications that access arbitrary netCDF datasets need to be
21 familiar with more of the netCDF library.
23 In this we provide templates of common sequences of netCDF calls
24 needed for common uses. For clarity we present only the names of
25 routines; omit declarations and error checking; omit the type-specific
26 suffixes of routine names for variables and attributes; indent
27 statements that are typically invoked multiple times; and use ... to
28 represent arbitrary sequences of other statements. Full parameter lists
29 are described in laters.
31 1.1 Creating a NetCDF Dataset {#f77_Creating_a_NetCDF_Dataset}
32 -----------------------------
34 Here is a typical sequence of netCDF calls used to create a new netCDF
40 NF_CREATE ! create netCDF dataset: enter define mode
42 NF_DEF_DIM ! define dimensions: from name and length
44 NF_DEF_VAR ! define variables: from name, type, dims
46 NF_PUT_ATT ! assign attribute values
48 NF_ENDDEF ! end definitions: leave define mode
50 NF_PUT_VAR ! provide values for variable
52 NF_CLOSE ! close: save new netCDF dataset
55 Only one call is needed to create a netCDF dataset, at which point you
56 will be in the first of two netCDF modes. When accessing an open netCDF
57 dataset, it is either in define mode or data mode. In define mode, you
58 can create dimensions, variables, and new attributes, but you cannot
59 read or write variable data. In data mode, you can access data and
60 change existing attributes, but you are not permitted to create new
61 dimensions, variables, or attributes.
63 One call to NF\_DEF\_DIM is needed for each dimension created.
64 Similarly, one call to NF\_DEF\_VAR is needed for each variable
65 creation, and one call to a member of the NF\_PUT\_ATT family is needed
66 for each attribute defined and assigned a value. To leave define mode
67 and enter data mode, call NF\_ENDDEF.
69 Once in data mode, you can add new data to variables, change old values,
70 and change values of existing attributes (so long as the attribute
71 changes do not require more storage space). Single values may be written
72 to a netCDF variable with one of the members of the NF\_PUT\_VAR1
73 family, depending on what type of data you have to write. All the values
74 of a variable may be written at once with one of the members of the
75 NF\_PUT\_VAR family. Arrays or array crosss of a variable may be
76 written using members of the NF\_PUT\_VARA family. Subsampled array
77 sections may be written using members of the NF\_PUT\_VARS family.
78 Mapped arrays may be written using members of the NF\_PUT\_VARM
79 family. (Subsampled and mapped access are general forms of data access
80 that are explained later.)
82 Finally, you should explicitly close all netCDF datasets that have been
83 opened for writing by calling NF\_CLOSE. By default, access to the file
84 system is buffered by the netCDF library. If a program terminates
85 abnormally with netCDF datasets open for writing, your most recent
86 modifications may be lost. This default buffering of data is disabled by
87 setting the NF\_SHARE flag when opening the dataset. But even if this
88 flag is set, changes to attribute values or changes made in define mode
89 are not written out until NF\_SYNC or NF\_CLOSE is called.
91 1.2 Reading a NetCDF Dataset with Known Names {#f77_Reading_a_NetCDF_Dataset_with_Known_Names}
92 ---------------------------------------------
94 Here we consider the case where you know the names of not only the
95 netCDF datasets, but also the names of their dimensions, variables, and
96 attributes. (Otherwise you would have to do "inquire" calls.) The order
97 of typical C calls to read data from those variables in a netCDF dataset
103 NF_OPEN ! open existing netCDF dataset
105 NF_INQ_DIMID ! get dimension IDs
107 NF_INQ_VARID ! get variable IDs
109 NF_GET_ATT ! get attribute values
111 NF_GET_VAR ! get values of variables
113 NF_CLOSE ! close netCDF dataset
116 First, a single call opens the netCDF dataset, given the dataset name,
117 and returns a netCDF ID that is used to refer to the open netCDF dataset
118 in allbsequent calls.
120 Next, a call to NF\_INQ\_DIMID for each dimension of interest gets the
121 dimension ID from the dimension name. Similarly, each required variable
122 ID is determined from its name by a call to NF\_INQ\_VARID.Once variable
123 IDs are known, variable attribute values can be retrieved using the
124 netCDF ID, the variable ID, and the desired attribute name as input to a
125 member of the NF\_GET\_ATT family (typically NF\_GET\_ATT\_TEXT or
126 NF\_GET\_ATT\_DOUBLE) for each desired attribute. Variable data values
127 can be directly accessed from the netCDF dataset with calls to members
128 of the NF\_GET\_VAR1 family for single values, the NF\_GET\_VAR family
129 for entire variables, or various other members of the NF\_GET\_VARA,
130 NF\_GET\_VARS, or NF\_GET\_VARM families for array,bsampled or mapped
133 Finally, the netCDF dataset is closed with NF\_CLOSE. There is no need
134 to close a dataset open only for reading.
137 1.3 Reading a netCDF Dataset with Unknown Names {#f77_Reading_a_netCDF_Dataset_with_Unknown_Names}
138 -----------------------------------------------
140 It is possible to write programs (e.g., generic software) which doch
141 things as processing every variable, without needing to know in advance
142 the names of these variables. Similarly, the names of dimensions and
143 attributes may be unknown.
145 Names and other information about netCDF objects may be obtained from
146 netCDF datasets by calling inquire functions. These return information
147 about a whole netCDF dataset, a dimension, a variable, or an attribute.
148 The following template illustrates how they are used:
153 NF_OPEN ! open existing netCDF dataset
155 NF_INQ ! find out what is in it
157 NF_INQ_DIM ! get dimension names, lengths
159 NF_INQ_VAR ! get variable names, types, shapes
161 NF_INQ_ATTNAME ! get attribute names
163 NF_INQ_ATT ! get attribute values
165 NF_GET_ATT ! get attribute values
167 NF_GET_VAR ! get values of variables
169 NF_CLOSE ! close netCDF dataset
172 As in the previous example, a single call opens the existing netCDF
173 dataset, returning a netCDF ID. This netCDF ID is given to the NF\_INQ
174 routine, which returns the number of dimensions, the number of
175 variables, the number of global attributes, and the ID of the unlimited
176 dimension, if there is one.
178 All the inquire functions are inexpensive to use and require no I/O,
179 since the information they provide is stored in memory when a netCDF
180 dataset is first opened.
182 Dimension IDs use consecutive integers, beginning at 1. Also dimensions,
183 once created, cannot be deleted. Therefore, knowing the number of
184 dimension IDs in a netCDF dataset means knowing all the dimension IDs:
185 they are the integers 1, 2, 3, ... up to the number of dimensions. For
186 each dimension ID, a call to the inquire function NF\_INQ\_DIM returns
187 the dimension name and length.
189 Variable IDs are also assigned from consecutive integers 1, 2, 3, ... up
190 to the number of variables. These can be used in NF\_INQ\_VAR calls to
191 find out the names, types, shapes, and the number of attributes assigned
194 Once the number of attributes for a variable is known,ccessive calls
195 to NF\_INQ\_ATTNAME return the name for each attribute given the netCDF
196 ID, variable ID, and attribute number. Armed with the attribute name, a
197 call to NF\_INQ\_ATT returns its type and length. Given the type and
198 length, you can allocate enough space to hold the attribute values. Then
199 a call to a member of the NF\_GET\_ATT family returns the attribute
202 Once the IDs and shapes of netCDF variables are known, data values can
203 be accessed by calling a member of the NF\_GET\_VAR1 family for single
204 values, or members of the NF\_GET\_VAR, NF\_GET\_VARA, NF\_GET\_VARS, or
205 NF\_GET\_VARM for various kinds of array access.
207 1.4 Adding New Dimensions, Variables, Attributes {#f77_Adding_New_Dimensions__Variables__Attributes}
208 ------------------------------------------------
210 An existing netCDF dataset can be extensively altered. New dimensions,
211 variables, and attributes can be added or existing ones renamed, and
212 existing attributes can be deleted. Existing dimensions, variables, and
213 attributes can be renamed. The following code template lists a typical
214 sequence of calls to add new netCDF components to an existing dataset:
219 NF_OPEN ! open existing netCDF dataset
221 NF_REDEF ! put it into define mode
223 NF_DEF_DIM ! define additional dimensions (if any)
225 NF_DEF_VAR ! define additional variables (if any)
227 NF_PUT_ATT ! define other attributes (if any)
229 NF_ENDDEF ! check definitions, leave define mode
231 NF_PUT_VAR ! provide new variable values
233 NF_CLOSE ! close netCDF dataset
236 A netCDF dataset is first opened by the NF\_OPEN call. This call puts
237 the open dataset in data mode, which means existing data values can be
238 accessed and changed, existing attributes can be changed (so long as
239 they do not grow), but nothing can be added. To add new netCDF
240 dimensions, variables, or attributes you must enter define mode, by
241 calling NF\_REDEF.In define mode, call NF\_DEF\_DIM to define new
242 dimensions, NF\_DEF\_VAR to define new variables, and a member of the
243 NF\_PUT\_ATT family to assign new attributes to variables or enlarge old
246 You can leave define mode and reenter data mode, checking all the new
247 definitions for consistency and committing the changes to disk, by
248 calling NF\_ENDDEF. If you do not wish to reenter data mode, just call
249 NF\_CLOSE, which will have the effect of first calling NF\_ENDDEF.
251 Until the NF\_ENDDEF call, you may back out of all the redefinitions
252 made in define mode and restore the previous state of the netCDF dataset
253 by calling NF\_ABORT. You may also use the NF\_ABORT call to restore the
254 netCDF dataset to a consistent state if the call to NF\_ENDDEF fails. If
255 you have called NF\_CLOSE from definition mode and the implied call to
256 NF\_ENDDEF fails, NF\_ABORT will automatically be called to close the
257 netCDF dataset and leave it in its previous consistent state (before you
258 entered define mode).
260 At most one process should have a netCDF dataset open for writing at one
261 time. The library is designed to provide limitedpport for multiple
262 concurrent readers with one writer, via disciplined use of the NF\_SYNC
263 function and the NF\_SHARE flag. If a writer makes changes in define
264 mode,ch as the addition of new variables, dimensions, or attributes,
265 some means external to the library is necessary to prevent readers from
266 making concurrent accesses and to inform readers to call NF\_SYNC before
269 1.5 Error Handling {#f77_Error_Handling_1_5}
272 The netCDF library provides the facilities needed to handle errors in a
273 flexible way. Each netCDF function returns an integer status value. If
274 the returned status value indicates an error, you may handle it in any
275 way desired, from printing an associated error message and exiting to
276 ignoring the error indication and proceeding (not recommended!). For
277 simplicity, the examples in this guide check the error status and call a
278 separate function to handle any errors.
280 The NF\_STRERROR function is available to convert a returned integer
281 error status into an error message string.
283 Occasionally, low-level I/O errors may occur in a layer below the netCDF
284 library. For example, if a write operation causes you to exceed disk
285 quotas or to attempt to write to a device that is no longer available,
286 you may get an error from a layer below the netCDF library, but the
287 rlting write error will still be reflected in the returned status
290 1.6 Compiling and Linking with the NetCDF Library {#f77_Compiling_and_Linking_with_the_NetCDF_Library}
291 -------------------------------------------------
293 Details of how to compile and link a program that uses the netCDF C or
294 FORTRAN interfaces differ, depending on the operating system, the
295 available compilers, and where the netCDF library and include files are
296 installed. Nevertheless, we provide here examples of how to compile and
297 link a program that uses the netCDF library on a Unix platform, so that
298 you can adjust these examples to fit your installation.
300 Every FORTRAN file that references netCDF functions or constants must
301 contain an appropriate INCLUDE statement before the first
307 Unless the netcdf.inc file is installed in a standard directory where
308 the FORTRAN compiler always looks, you must use the -I option when
309 invoking the compiler, to specify a directory where netcdf.inc is
310 installed, for example:
312 f77 -c -I/usr/local/include myprogram.f
315 Unless the netCDF library is installed in a standard directory where the
316 linker always looks, you must use the -L and -l options to link an
317 object file that uses the netCDF library. Since version 4.1.3, the
318 netCDF Fortran library (named ‘libnetcdff’) is distinct from the netCDF
319 C library (named ‘libnetcdf’), but depends on it. If it is installed as
320 a shared library, you need only use ‘-lnetcdff’ to specify the Fortran
323 For example, if installed as a shared library, use something like:
326 f77 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff
329 If installed as a static library, you will at least need to mention the
330 netCDF C library and perhaps other libraries,ch as hdf5 or curl,
331 depending on how the C library was built. For example:
336 f77 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff -lnetcdf
339 Use of the nf-config utility program, installed as part of the
340 netcdf-fortran software, provides an easier way to compile and link,
341 without needing to know the details of where the library has been
342 installed, or whether it is installed as a shared or static library.
344 To see all the options for ‘nf-config’, invoke it with the ‘–help’
347 Here’s an example of how you could use ‘nf-config’ to compile and link a
348 Fortran program in one step:
353 f77 myprogram.f -o myprogram `nf-config --fflags --flibs`
356 If it is installed on your system, you could also use the ‘pkg-config’
357 utility to compile and link Fortran programs with the netCDF libraries.
358 This is especially useful in Makefiles, to ilate them from changes to
359 library versions and dependencies. Here is an example of how you could
360 compile and link a Fortran program with netCDF libraries using
366 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
367 f77 myprogram.f -o myprogram `pkg-config --cflags --libs netcdf-fortran`
370 where here ‘–cflags’ means compiler flags and ‘libs’ requests that the
371 approriate libraries be linked in.
375 2. Datasets {#f77_Datasets}
378 2.1 Datasets Introduction {#f77_Datasets_Introduction}
379 -------------------------
381 This presents the interfaces of the netCDF functions that deal
382 with a netCDF dataset or the whole netCDF library.
384 A netCDF dataset that has not yet been opened can only be referred to by
385 its dataset name. Once a netCDF dataset is opened, it is referred to by
386 a netCDF ID, which is a small nonnegative integer returned when you
387 create or open the dataset. A netCDF ID is much like a file descriptor
388 in C or a logical unit number in FORTRAN. In any single program, the
389 netCDF IDs of distinct open netCDF datasets are distinct. A single
390 netCDF dataset may be opened multiple times and will then have multiple
391 distinct netCDF IDs; however at most one of the open instances of a
392 single netCDF dataset should permit writing. When an open netCDF dataset
393 is closed, the ID is no longer associated with a netCDF dataset.
395 Functions that deal with the netCDF library include:
397 - Get version of library.
398 - Get error message corresponding to a returned error code.
400 The operationspported on a netCDF dataset as a single object are:
402 - Create, given dataset name and whether to overwrite or not.
403 - Open for access, given dataset name and read or write intent.
404 - Put into define mode, to add dimensions, variables, or attributes.
405 - Take out of define mode, checking consistency of additions.
406 - Close, writing to disk if required.
407 - Inquire about the number of dimensions, number of variables, number
408 of global attributes, and ID of the unlimited dimension, if any.
409 - Synchronize to disk to makere it is current.
410 - Set and unset nofill mode for optimized sequential writes.
411 - After ammary of conventions used in describing the netCDF
412 interfaces, the rest of this presents a detailed description
413 of the interfaces for these operations.
415 2.2 NetCDF Library Interface Descriptions {#f77_NetCDF_Library_Interface_Descriptions}
416 -----------------------------------------
418 Each interface description for a particular netCDF function in this and
421 - a description of the purpose of the function;
422 - a FORTRAN function prototype that presents the type and order of the
423 formal parameters to the function;
424 - a description of each formal parameter in the C interface;
425 - a list of possible error conditions; and
426 - an example of a FORTRAN program fragment calling the netCDF function
427 (and perhaps other netCDF functions).
429 The examples follow a simple convention for error handling, always
430 checking the error status returned from each netCDF function call and
431 calling a handle\_error function in case an error was detected. For an
432 example ofch a function, see Section 5.2 "Get error message
433 corresponding to error status: nf\_strerror".
435 2.3 NF_STRERROR {#f77_NF_STRERROR}
438 The function NF\_STRERROR returns a static reference to an error message
439 string corresponding to an integer netCDF error status or to a system
440 error number, prmably returned by a previous call to some other
441 netCDF function. The list of netCDF error status codes is available in
442 the appropriate include file for each language binding.
447 CHARACTER*80 FUNCTION NF_STRERROR(INTEGER NCERR)
451 : An error status that might have been returned from a previous call
452 to some netCDF function.
457 If you provide an invalid integer error status that does not correspond
458 to any netCDF error message or or to any system error message (as
459 understood by the system strerror function), NF\_STRERROR returns a
460 string indicating that there is noch error status.
464 Here is an example of a simple error handling function that uses
465 NF\_STRERROR to print the error message corresponding to the netCDF
466 error status returned from any netCDF function call and then exit:
473 SUBROUTINE HANDLE_ERR(STATUS)
475 IF (STATUS .NE. NF_NOERR) THEN
476 PRINT *, NF_STRERROR(STATUS)
483 2.4 Get netCDF library version: NF_INQ_LIBVERS {#f77_Get_netCDF_library_version_NF_INQ_LIBVERS}
484 ------------------------------------------------
486 The function NF\_INQ\_LIBVERS returns a string identifying the version
487 of the netCDF library, and when it was built.
492 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
497 This function takes no arguments, and thus no errors are possible in its
502 Here is an example using nf\_inq\_libvers to print the version of the
503 netCDF library with which the program is linked:
509 PRINT *, NF_INQ_LIBVERS()
512 2.5 NF_CREATE {#f77_NF_CREATE}
515 This function creates a new netCDF dataset, returning a netCDF ID that
516 can sequently be used to refer to the netCDF dataset in other netCDF
517 function calls. The new netCDF dataset opened for write access and
518 placed in define mode, ready for you to add dimensions, variables, and
521 A creation mode flag specifies whether to overwrite any existing dataset
522 with the same name and whether access to the dataset is shared.
527 INTEGER FUNCTION NF_CREATE (CHARACTER*(*) PATH, INTEGER CMODE,
531 `PATH`: The file name of the new netCDF dataset.
533 `CMODE`: The creation mode flag. The following flags are available:
534 NF\_NOCLOBBER, NF\_SHARE, NF\_64BIT\_OFFSET, NF\_NETCDF4 and
535 NF\_CLASSIC\_MODEL. You can combine the affect of multiple flags in
536 a single argument by using the bitwise OR operator. For example, to
537 specify both NF\_NOCLOBBER and NF\_SHARE, you could provide the
538 argument OR(NF\_NOCLOBBER, NF\_SHARE).
541 A zero value (defined for convenience as NF_CLOBBER) specifies the
542 default behavior: overwrite any existing dataset with the same file
543 name and buffer and cache accesses for efficiency. The dataset will
544 be in netCDF classic format. See 'NetCDF Classic Format Limitations'
545 in The NetCDF Users Guide.
547 Setting NF\_NOCLOBBER means you do not want to clobber (overwrite)
548 an existing dataset; an error (NF_EEXIST) is returned if the
549 specified dataset already exists.
551 The NF\_SHARE flag is appropriate when one process may be writing
552 the dataset and one or more other processes reading the dataset
553 concurrently; it means that dataset accesses are not buffered and
554 caching is limited. Since the buffering scheme is optimized for
555 sequential access, programs that do not access data sequentially may
556 see some performance improvement by setting the NF\_SHARE flag. This
557 only applied to classic and 64-bit offset format files.
559 Setting NF\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
560 format file, instead of a netCDF classic format file. The 64-bit
561 offset format imposes far fewer restrictions on very large (i.e.
562 over 2 GB) data files. See [(netcdf)Large File
563 Support](netcdf.html#Large-File-Support) ‘Large File
564 Support’ in The NetCDF Users Guide.
566 Setting NF\_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format
567 file. Oring NF\_CLASSIC\_MODEL with NF\_NETCDF4 causes the netCDF
568 library to create a netCDF-4/HDF5 data file, with the netCDF classic
569 model enforced - none of the new features of the netCDF-4 data model
570 may be usedinch a file, for example groups and user-defined
574 : Returned netCDF ID.
578 NF\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
579 causes of errors include:
581 - Passing a dataset name that includes a directory that does not
583 - Specifying a dataset name of a file that exists and also specifying
585 - Specifying a meaningless value for the creation mode.
586 - Attempting to create a netCDF dataset in a directory where you don’t
587 have permission to create files.
591 In this example we create a netCDF dataset named foo.nc; we want the
592 dataset to be created in the current directory only if a dataset with
593 that name does not already exist:
602 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
603 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
606 2.6 NF__CREATE {#f77_F__CREATE}
609 This function is a variant of NF\_CREATE, NF\_\_CREATE (note the double
610 underscore) allows users to specify two tuning parameters for the file
611 that it is creating. These tuning parameters are not written to the data
612 file, they are only used for so long as the file remains open after an
615 This function creates a new netCDF dataset, returning a netCDF ID that
616 canbsequently be used to refer to the netCDF dataset in other netCDF
617 function calls. The new netCDF dataset opened for write access and
618 placed in define mode, ready for you to add dimensions, variables, and
621 A creation mode flag specifies whether to overwrite any existing dataset
622 with the same name and whether access to the dataset is shared.
627 INTEGER FUNCTION NF__CREATE (CHARACTER*(*) PATH, INTEGER CMODE, INTEGER INITIALSZ,
628 INTEGER BUFRSIZEHINT, INTEGER ncid)
632 : The file name of the new netCDF dataset.
635 : The creation mode flag. The following flags are available:
636 NF\_NOCLOBBER, NF\_SHARE, NF\_64BIT\_OFFSET, NF\_NETCDF4, and
639 Setting NF\_NOCLOBBER means you do not want to clobber (overwrite)
640 an existing dataset; an error (NF\_EEXIST) is returned if the
641 specified dataset already exists.
643 The NF\_SHARE flag is appropriate when one process may be writing
644 the dataset and one or more other processes reading the dataset
645 concurrently; it means that dataset accesses are not buffered and
646 caching is limited. Since the buffering scheme is optimized for
647 sequential access, programs that do not access data sequentially may
648 see some performance improvement by setting the NF\_SHARE flag. This
649 flag has no effect with netCDF-4/HDF5 files.
651 Setting NF\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
652 format file, instead of a netCDF classic format file. The 64-bit
653 offset format imposes far fewer restrictions on very large (i.e.
654 over 2 GB) data files. See [(netcdf)Large File
655 Support](netcdf.html#Large-File-Support) ‘Large File
656 Support’ in The NetCDF Users Guide.
658 Setting NF\_CLASSIC\_MODEL causes netCDF to enforce the classic data
659 model in this file. (This only has effect for netCDF-4/HDF5 files,
660 as classic and 64-bit offset files always use the classic model.)
661 When used with NF\_NETCDF4, this flag eres that the rlting
662 netCDF-4/HDF5 file may never contain any new constructs from the
663 enhanced data model. That is, it cannot contain groups, user defined
664 types, multiple unlimited dimensions, or new atomic types. The
665 advantage of this restriction is thatch files are guarenteed to
666 work with existing netCDF software.
668 A zero value (defined for convenience as NF\_CLOBBER) specifies the
669 default behavior: overwrite any existing dataset with the same file
670 name and buffer and cache accesses for efficiency. The dataset will
671 be in netCDF classic format. See [(netcdf)NetCDF Classic Format
672 Limitations](netcdf.html#NetCDF-Classic-Format-Limitations)
673 ‘NetCDF Classic Format Limitations’ in The NetCDF Users Guide.
676 : This parameter sets the initial size of the file at creation time.
679 : The argument referenced by BUFRSIZEHINT controls a space ves time
680 tradeoff, memory allocated in the netcdf library ves number of
683 Because of internal requirements, the value may not be set to
684 exactly the value requested. The actual value chosen is returned by
687 Using the value NF\_SIZEHINT\_DEFAULT causes the library to choose a
688 default. How the system chooses the default depends on the system.
689 On many systems, the "preferred I/O block size" is available from
690 the stat() system call, struct stat member st\_blksize. If this is
691 available it is used. Lacking that, twice the system pagesize is
694 Lacking a call to discover the system pagesize, we just set default
697 The BUFRSIZE is a property of a given open netcdf descriptor ncid,
698 it is not a persistent property of the netcdf dataset.
701 : Returned netCDF ID.
705 NF\_\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
706 causes of errors include:
708 - Passing a dataset name that includes a directory that does not
710 - Specifying a dataset name of a file that exists and also specifying
712 - Specifying a meaningless value for the creation mode.
713 - Attempting to create a netCDF dataset in a directory where you don’t
714 have permission to create files.
718 In this example we create a netCDF dataset named foo.nc; we want the
719 dataset to be created in the current directory only if a dataset with
720 that name does not already exist:
727 INTEGER NCID, STATUS, INITIALSZ, BUFRSIZEHINT
731 STATUS = NF__CREATE('foo.nc', NF_NOCLOBBER, INITIALSZ, BUFRSIZEHINT, NCID)
732 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
735 2.7 NF_CREATE_PAR {#f77_NF_CREATE_PAR}
738 This function is a variant of nf\_create, nf\_create\_par allows users
739 to open a file on a MPI/IO or MPI/Posix parallel file system.
741 The parallel parameters are not written to the data file, they are only
742 used for so long as the file remains open after an nf\_create\_par.
744 This function is only available if the netCDF library was built with
747 This function creates a new netCDF dataset, returning a netCDF ID that
748 canbsequently be used to refer to the netCDF dataset in other netCDF
749 function calls. The new netCDF dataset opened for write access and
750 placed in define mode, ready for you to add dimensions, variables, and
753 When a netCDF-4 file is created for parallel access, independent
754 operations are the default. To use collective access on a variable, See
755 section [Change between Collective and Independent Parallel Access:
756 NF\_VAR\_PAR\_ACCESS](#NF_005fVAR_005fPAR_005fACCESS).
761 INTEGER FUNCTION NF_CREATE_PAR(CHARACTER*(*) PATH, INTEGER CMODE,
762 INTEGER MPI_COMM, INTEGER MPI_INFO,
767 : The file name of the new netCDF dataset.
770 : The creation mode flag. The following flags are available:
771 NF\_NOCLOBBER, NF\_NETCDF4 and NF\_CLASSIC\_MODEL. You can combine
772 the affect of multiple flags in a single argument by using the
773 bitwise OR operator. For example, to specify both NF\_NOCLOBBER and
774 NF\_NETCDF4, you could provide the argument OR(NF\_NOCLOBBER,
777 Setting NF\_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format
778 file. Oring NF\_CLASSIC\_MODEL with NF\_NETCDF4 causes the netCDF
779 library to create a netCDF-4/HDF5 data file, with the netCDF classic
780 model enforced - none of the new features of the netCDF-4 data model
781 may be usedinch a file, for example groups and user-defined
784 Only netCDF-4/HDF5 files may be used with parallel I/O.
787 : The MPI communicator.
793 : Returned netCDF ID.
798 NF\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
799 causes of errors include:
801 - Passing a dataset name that includes a directory that does not
803 - Specifying a dataset name of a file that exists and also specifying
805 - Specifying a meaningless value for the creation mode.
806 - Attempting to create a netCDF dataset in a directory where you don’t
807 have permission to create files.
812 This example is from test program nf\_test/ftst\_parallel.F.
817 ! Create the netCDF file.
818 mode_flag = IOR(nf_netcdf4, nf_classic_model)
819 retval = nf_create_par(FILE_NAME, mode_flag, MPI_COMM_WORLD,
820 $ MPI_INFO_NULL, ncid)
821 if (retval .ne. nf_noerr) stop 2
825 2.8 NF_OPEN {#f77_NF_OPEN_}
828 The function NF\_OPEN opens an existing netCDF dataset for access.
833 INTEGER FUNCTION NF_OPEN(CHARACTER*(*) PATH, INTEGER OMODE, INTEGER ncid)
837 : File name for netCDF dataset to be opened. This may be an OPeNDAP
838 URL if DAPpport is enabled.
841 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
842 read-only access, buffering and caching accesses for efficiency.
844 Otherwise, the creation mode is NF\_WRITE, NF\_SHARE, or
845 OR(NF\_WRITE, NF\_SHARE). Setting the NF\_WRITE flag opens the
846 dataset with read-write access. ("Writing" means any kind of change
847 to the dataset, including appending or changing data, adding or
848 renaming dimensions, variables, and attributes, or deleting
849 attributes.) The NF\_SHARE flag is appropriate when one process may
850 be writing the dataset and one or more other processes reading the
851 dataset concurrently; it means that dataset accesses are not
852 buffered and caching is limited. Since the buffering scheme is
853 optimized for sequential access, programs that do not access data
854 sequentially may see some performance improvement by setting the
858 : Returned netCDF ID.
863 NF\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
864 the returned status indicates an error. Possible causes of errors
867 - The specified netCDF dataset does not exist.
868 - A meaningless mode was specified.
872 Here is an example using NF\_OPEN to open an existing netCDF dataset
873 named foo.nc for read-only, non-shared access:
880 STATUS = NF_OPEN('foo.nc', 0, NCID)
881 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
884 2.9 NF__OPEN {#NF__OPEN_}
887 The function NF\_OPEN opens an existing netCDF dataset for access, with
888 a performance tuning parameter.
893 INTEGER FUNCTION NF_OPEN(CHARACTER*(*) PATH, INTEGER OMODE, INTEGER
894 BUFRSIZEHINT, INTEGER ncid)
898 : File name for netCDF dataset to be opened.
901 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
902 read-only access, buffering and caching accesses for efficiency
904 Otherwise, the creation mode is NF\_WRITE, NF\_SHARE, or
905 OR(NF\_WRITE,NF\_SHARE). Setting the NF\_WRITE flag opens the
906 dataset with read-write access. ("Writing" means any kind of change
907 to the dataset, including appending or changing data, adding or
908 renaming dimensions, variables, and attributes, or deleting
909 attributes.) The NF\_SHARE flag is appropriate when one process may
910 be writing the dataset and one or more other processes reading the
911 dataset concurrently; it means that dataset accesses are not
912 buffered and caching is limited. Since the buffering scheme is
913 optimized for sequential access, programs that do not access data
914 sequentially may see some performance improvement by setting the
918 : This argument controls a space ves time tradeoff, memory
919 allocated in the netcdf library ves number of system calls.
921 Because of internal requirements, the value may not be set to
922 exactly the value requested. The actual value chosen is returned by
925 Using the value NF\_SIZEHINT\_DEFAULT causes the library to choose a
926 default. How the system chooses the default depends on the system.
927 On many systems, the "preferred I/O block size" is available from
928 the stat() system call, struct stat member st\_blksize. If this is
929 available it is used. Lacking that, twice the system pagesize is
932 Lacking a call to discover the system pagesize, we just set default
935 The bufrsize is a property of a given open netcdf descriptor ncid,
936 it is not a persistent property of the netcdf dataset.
939 : Returned netCDF ID.
944 NF\_\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
945 the returned status indicates an error. Possible causes of errors
948 - The specified netCDF dataset does not exist.
949 - A meaningless mode was specified.
953 Here is an example using NF\_\_OPEN to open an existing netCDF dataset
954 named foo.nc for read-only, non-shared access:
960 INTEGER NCID, STATUS, BUFRSIZEHINT
963 STATUS = NF_OPEN('foo.nc', 0, BUFRSIZEHINT, NCID)
964 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
967 2.10 NF_OPEN_PAR {#f77_NF_OPEN_PAR}
970 This function opens a netCDF-4 dataset for parallel access.
972 This function is only available if the netCDF library was built with a
973 HDF5 library for which –enable-parallel was used, and which was linked
974 (like HDF5) to MPI libraries.
976 This opens the file using either MPI-IO or MPI-POSIX. The file must be a
977 netCDF-4 file. (That is, it must have been created using NF\_NETCDF4 in
980 This function is only available if netCDF-4 was build with a version of
981 the HDF5 library which was built with –enable-parallel.
983 Before either HDF5 or netCDF-4 can be installed withpport for
984 parallel programming, and MPI layer must also be installed on the
985 machine, and ally a parallel file system.
987 NetCDF-4 exposes the parallel access functionality of HDF5. For more
988 information about what is required to install and use the parallel
989 access functions, see the HDF5 web site.
991 When a netCDF-4 file is opened for parallel access, collective
992 operations are the default. To use independent access on a variable, See
993 section [Change between Collective and Independent Parallel Access:
994 NF\_VAR\_PAR\_ACCESS](#NF_005fVAR_005fPAR_005fACCESS).
1000 INTEGER FUNCTION NF_OPEN_PAR(CHARACTER*(*) PATH, INTEGER OMODE,
1001 INTEGER MPI_COMM, INTEGER MPI_INFO,
1006 : File name for netCDF dataset to be opened.
1009 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
1012 Otherwise, the mode may be NF\_WRITE. Setting the NF\_WRITE flag
1013 opens the dataset with read-write access. ("Writing" means any kind
1014 of change to the dataset, including appending or changing data,
1015 adding or renaming dimensions, variables, and attributes, or
1016 deleting attributes.)
1018 Setting NF\_NETCDF4 is not necessary (or allowed). The file type is
1019 detected automatically.
1022 : The MPI communicator.
1028 : Returned netCDF ID.
1033 NF\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
1034 the returned status indicates an error. Possible causes of errors
1037 - The specified netCDF dataset does not exist.
1038 - A meaningless mode was specified.
1039 - Not a netCDF-4 file.
1044 This example is from the test program nf\_test/ftst\_parallel.F.
1050 retval = nf_open_par(FILE_NAME, nf_nowrite, MPI_COMM_WORLD,
1051 $ MPI_INFO_NULL, ncid)
1052 if (retval .ne. nf_noerr) stop 2
1055 2.11 NF_REDEF {#f77_NF-REDEF}
1058 The function NF\_REDEF puts an open netCDF dataset into define mode, so
1059 dimensions, variables, and attributes can be added or renamed and
1060 attributes can be deleted.
1068 INTEGER FUNCTION NF_REDEF(INTEGER NCID)
1072 : netCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1077 NF\_REDEF returns the value NF\_NOERR if no errors occurred. Otherwise,
1078 the returned status indicates an error. Possible causes of errors
1081 - The specified netCDF dataset is already in define mode.
1082 - The specified netCDF dataset was opened for read-only.
1083 - The specified netCDF ID does not refer to an open netCDF dataset.
1088 Here is an example using NF\_REDEF to open an existing netCDF dataset
1089 named foo.nc and put it into define mode:
1094 INCLUDE 'netcdf.inc'
1096 INTEGER NCID, STATUS
1098 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID) ! open dataset
1099 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1101 STATUS = NF_REDEF(NCID) ! put in define mode
1102 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1106 2.12 NF_ENDDEF {#f77_NF-ENDDEF}
1109 The function NF\_ENDDEF takes an open netCDF dataset out of define mode.
1110 The changes made to the netCDF dataset while it was in define mode are
1111 checked and committed to disk if no problems occurred. Non-record
1112 variables may be initialized to a "fill value" as well (see
1113 [NF\_SET\_FILL](#NF_005fSET_005fFILL)). The netCDF dataset is then
1114 placed in data mode, so variable data can be read or written.
1116 This call may involve copying data under some circumstances. See
1117 [(netcdf)File Structure and
1118 Performance](netcdf.html#File-Structure-and-Performance) ‘File
1119 Structure and Performance’ in NetCDF Users’ Guide.
1127 INTEGER FUNCTION NF_ENDDEF(INTEGER NCID)
1131 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1136 NF\_ENDDEF returns the value NF\_NOERR if no errors occurred. Otherwise,
1137 the returned status indicates an error. Possible causes of errors
1140 - The specified netCDF dataset is not in define mode.
1141 - The specified netCDF ID does not refer to an open netCDF dataset.
1142 The size of one or more variables exceed the size constraints for
1143 whichever variant of the file format is in use). See [(netcdf)Large
1144 File Support](netcdf.html#Large-File-Support) ‘Large File
1145 Support’ in The NetCDF Users Guide.
1150 Here is an example using NF\_ENDDEF to finish the definitions of a new
1151 netCDF dataset named foo.nc and put it into data mode:
1155 INCLUDE 'netcdf.inc'
1157 INTEGER NCID, STATUS
1159 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1160 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1162 ... ! create dimensions, variables, attributes
1164 STATUS = NF_ENDDEF(NCID)
1165 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1170 2.13 NF__ENDDEF {#f77_NF__ENDDEF}
1173 The function NF\_\_ENDDEF takes an open netCDF dataset out of define
1174 mode. The changes made to the netCDF dataset while it was in define mode
1175 are checked and committed to disk if no problems occurred. Non-record
1176 variables may be initialized to a "fill value" as well (see
1177 [NF\_SET\_FILL](#NF_005fSET_005fFILL)). The netCDF dataset is then
1178 placed in data mode, so variable data can be read or written.
1180 This call may involve copying data under some circumstances. See
1181 [(netcdf)File Structure and
1182 Performance](netcdf.html#File-Structure-and-Performance) ‘File
1183 Structure and Performance’ in NetCDF Users’ Guide.
1185 This function ames specific characteristics of the netcdf version 1
1186 and version 2 file formats. Users should use nf\_enddef in most
1187 circumstances. Although this function will be available in future netCDF
1188 implementations, it may not continue to have any effect on performance.
1190 The current netcdf file format has threes, the "header",
1191 the data for fixed size variables, and the data for
1192 variables which have an unlimited dimension (record variables).
1194 The header begins at the beginning of the file. The index (offset) of
1195 the beginning of the other twos is contained in the header.
1196 Typically, there is no space between thes. This causes copying
1197 overhead to accrue if one wishes to change the size of thes, as
1198 may happen when changing names of things, text attribute values, adding
1199 attributes or adding variables. Also, for buffered i/o, there may be
1200 advantages to alignings in certain ways.
1202 The minfree parameters allow one to control costs of future calls to
1203 nf\_redef, nf\_enddef by requesting that minfree bytes be available at
1206 The align parameters allow one to set the alignment of the beginning of
1207 the correspondings. The beginning of the is rounded up
1208 to an index which is a multiple of the align parameter. The flag value
1209 ALIGN\_CHUNK tells the library to use the bufrsize (see above) as the
1212 The file format requires mod 4 alignment, so the align parameters are
1213 silently rounded up to multiples of 4. The al call,
1224 nf_enddef(ncid, 0, 4, 0, 4);
1227 The file format does not contain a "record size" value, this is
1228 calculated from the sizes of the record variables. This unfortunate fact
1229 prevents us from providing minfree and alignment control of the
1230 "records" in a netcdf file. If you add a variable which has an unlimited
1231 dimension, the third will always be copied with the new variable
1240 INTEGER FUNCTION NF_ENDDEF(INTEGER NCID, INTEGER H_MINFREE, INTEGER V_ALIGN,
1241 INTEGER V_MINFREE, INTEGER R_ALIGN)
1245 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1248 : Sets the pad at the end of the "header".
1251 : Controls the alignment of the beginning of the data for
1252 fixed size variables.
1255 : Sets the pad at the end of the data for fixed size
1259 : Controls the alignment of the beginning of the data for
1260 variables which have an unlimited dimension (record variables).
1265 NF\_\_ENDDEF returns the value NF\_NOERR if no errors occurred.
1266 Otherwise, the returned status indicates an error. Possible causes of
1269 - The specified netCDF dataset is not in define mode.
1270 - The specified netCDF ID does not refer to an open netCDF dataset.
1271 - The size of one or more variables exceed the size constraints for
1272 whichever variant of the file format is in use). See [(netcdf)Large
1273 File Support](netcdf.html#Large-File-Support) ‘Large File
1274 Support’ in The NetCDF Users Guide.
1279 Here is an example using NF\_\_ENDDEF to finish the definitions of a new
1280 netCDF dataset named foo.nc and put it into data mode:
1284 INCLUDE 'netcdf.inc'
1286 INTEGER NCID, STATUS, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN
1288 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1289 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1291 ... ! create dimensions, variables, attributes
1297 STATUS = NF_ENDDEF(NCID, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN)
1298 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1302 2.14 NF_CLOSE {#f77_NF-CLOSE}
1305 The function NF\_CLOSE closes an open netCDF dataset. If the dataset is
1306 in define mode, NF\_ENDDEF will be called before closing. (In this case,
1307 if NF\_ENDDEF returns an error, NF\_ABORT will automatically be called
1308 to restore the dataset to the consistent state before define mode was
1309 last entered.) After an open netCDF dataset is closed, its netCDF ID may
1310 be reassigned to the next netCDF dataset that is opened or created.
1318 INTEGER FUNCTION NF_CLOSE(INTEGER NCID)
1322 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1327 NF\_CLOSE returns the value NF\_NOERR if no errors occurred. Otherwise,
1328 the returned status indicates an error. Possible causes of errors
1331 - Define mode was entered and the automatic call made to NF\_ENDDEF
1333 - The specified netCDF ID does not refer to an open netCDF dataset.
1338 Here is an example using NF\_CLOSE to finish the definitions of a new
1339 netCDF dataset named foo.nc and release its netCDF ID:
1344 INCLUDE 'netcdf.inc'
1346 INTEGER NCID, STATUS
1348 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1349 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1351 ... ! create dimensions, variables, attributes
1353 STATUS = NF_CLOSE(NCID)
1354 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1357 2.15 NF_INQ Family {#f77_NF-INQ-Family}
1360 Members of the NF\_INQ family of functions return information about an
1361 open netCDF dataset, given its netCDF ID. Dataset inquire functions may
1362 be called from either define mode or data mode. The first function,
1363 NF\_INQ, returns values for the number of dimensions, the number of
1364 variables, the number of global attributes, and the dimension ID of the
1365 dimension defined with unlimited length, if any. The other functions in
1366 the family each return just one of these items of information.
1368 For FORTRAN, these functions include NF\_INQ, NF\_INQ\_NDIMS,
1369 NF\_INQ\_NVARS, NF\_INQ\_NATTS, and NF\_INQ\_UNLIMDIM. An additional
1370 function, NF\_INQ\_FORMAT, returns the (rarely needed) format version.
1372 No I/O is performed when these functions are called, since the required
1373 information is available in memory for each open netCDF dataset.
1381 INTEGER FUNCTION NF_INQ (INTEGER NCID, INTEGER ndims,
1382 INTEGER nvars,INTEGER ngatts,
1384 INTEGER FUNCTION NF_INQ_NDIMS (INTEGER NCID, INTEGER ndims)
1385 INTEGER FUNCTION NF_INQ_NVARS (INTEGER NCID, INTEGER nvars)
1386 INTEGER FUNCTION NF_INQ_NATTS (INTEGER NCID, INTEGER ngatts)
1387 INTEGER FUNCTION NF_INQ_UNLIMDIM (INTEGER NCID, INTEGER unlimdimid)
1388 INTEGER FUNCTION NF_INQ_FORMAT (INTEGER NCID, INTEGER format)
1392 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1395 : Returned number of dimensions defined for this netCDF dataset.
1398 : Returned number of variables defined for this netCDF dataset.
1401 : Returned number of global attributes defined for this netCDF
1405 : Returned ID of the unlimited dimension, if there is one for this
1406 netCDF dataset. If no unlimited length dimension has been defined,
1410 : Returned format version, one of NF\_FORMAT\_CLASSIC,
1411 NF\_FORMAT\_64BIT, NF\_FORMAT\_NETCDF4,
1412 NF\_FORMAT\_NETCDF4\_CLASSIC.
1417 All members of the NF\_INQ family return the value NF\_NOERR if no
1418 errors occurred. Otherwise, the returned status indicates an error.
1419 Possible causes of errors include:
1421 - The specified netCDF ID does not refer to an open netCDF dataset.
1426 Here is an example using NF\_INQ to find out about a netCDF dataset
1431 INCLUDE 'netcdf.inc'
1433 INTEGER STATUS, NCID, NDIMS, NVARS, NGATTS, UNLIMDIMID
1435 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
1436 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1438 STATUS = NF_INQ(NCID, NDIMS, NVARS, NGATTS, UNLIMDIMID)
1439 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1443 2.16 NF_SYNC {#f77_NF-SYNC}
1446 The function NF\_SYNC offers a way to synchronize the disk copy of a
1447 netCDF dataset with in-memory buffers. There are two reasons you might
1448 want to synchronize after writes:
1450 - To minimize data loss in case of abnormal termination, or
1451 - To make data available to other processes for reading immediately
1452 after it is written. But note that a process that already had the
1453 dataset open for reading would not see the number of records
1454 increase when the writing process calls NF\_SYNC; to accomplish
1455 this, the reading process must call NF\_SYNC.
1457 This function is backward-compatible with previous versions of the
1458 netCDF library. The intent was to allow sharing of a netCDF dataset
1459 among multiple readers and one writer, by having the writer call
1460 NF\_SYNC after writing and the readers call NF\_SYNC before each read.
1461 For a writer, this flushes buffers to disk. For a reader, it makesre
1462 that the next read will be from disk rather than from previously cached
1463 buffers, so that the reader will see changes made by the writing process
1464 (e.g., the number of records written) without having to close and reopen
1465 the dataset. If you are only accessing a small amount of data, it can be
1466 expensive in computer resources to always synchronize to disk after
1467 every write, since you are giving up the benefits of buffering.
1469 An easier way to accomplish sharing (and what is now recommended) is to
1470 have the writer and readers open the dataset with the NF\_SHARE flag,
1471 and then it will not be necessary to call NF\_SYNC at all. However, the
1472 NF\_SYNC function still provides finer granularity than the NF\_SHARE
1473 flag, if only a few netCDF accesses need to be synchronized among
1476 It is important to note that changes to the ancillary data,ch as
1477 attribute values, are not propagated automatically by use of the
1478 NF\_SHARE flag. Use of the NF\_SYNC function is still required for this
1481 Sharing datasets when the writer enters define mode to change the data
1482 schema requires extra care. In previous releases, after the writer left
1483 define mode, the readers were left looking at an old copy of the
1484 dataset, since the changes were made to a new copy. The only way readers
1485 could see the changes was by closing and reopening the dataset. Now the
1486 changes are made in place, but readers have no knowledge that their
1487 internal tables are now inconsistent with the new dataset schema. If
1488 netCDF datasets are shared across redefinition, some mechanism external
1489 to the netCDF library must be provided that prevents access by readers
1490 during redefinition and causes the readers to call NF\_SYNC before any
1493 When calling NF\_SYNC, the netCDF dataset must be in data mode. A netCDF
1494 dataset in define mode is synchronized to disk only when NF\_ENDDEF is
1495 called. A process that is reading a netCDF dataset that another process
1496 is writing may call NF\_SYNC to get updated with the changes made to the
1497 data by the writing process (e.g., the number of records written),
1498 without having to close and reopen the dataset.
1500 Data is automatically synchronized to disk when a netCDF dataset is
1501 closed, or whenever you leave define mode.
1509 INTEGER FUNCTION NF_SYNC(INTEGER NCID)
1513 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1518 NF\_SYNC returns the value NF\_NOERR if no errors occurred. Otherwise,
1519 the returned status indicates an error. Possible causes of errors
1522 - The netCDF dataset is in define mode.
1523 - The specified netCDF ID does not refer to an open netCDF dataset.
1528 Here is an example using NF\_SYNC to synchronize the disk writes of a
1529 netCDF dataset named foo.nc:
1534 INCLUDE 'netcdf.inc'
1536 INTEGER STATUS, NCID
1538 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1539 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1541 ! write data or change attributes
1543 STATUS = NF_SYNC(NCID)
1544 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1547 2.17 NF_ABORT {#f77_NF-ABORT}
1550 You no longer need to call this function, since it is called
1551 automatically by NF\_CLOSE in case the dataset is in define mode and
1552 something goes wrong with committing the changes. The function NF\_ABORT
1553 just closes the netCDF dataset, if not in define mode. If the dataset is
1554 being created and is still in define mode, the dataset is deleted. If
1555 define mode was entered by a call to NF\_REDEF, the netCDF dataset is
1556 restored to its state before definition mode was entered and the dataset
1565 INTEGER FUNCTION NF_ABORT(INTEGER NCID)
1569 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1574 NF\_ABORT returns the value NF\_NOERR if no errors occurred. Otherwise,
1575 the returned status indicates an error. Possible causes of errors
1578 - When called from define mode while creating a netCDF dataset,
1579 deletion of the dataset failed.
1580 - The specified netCDF ID does not refer to an open netCDF dataset.
1585 Here is an example using NF\_ABORT to back out of redefinitions of a
1586 dataset named foo.nc:
1590 INCLUDE 'netcdf.inc'
1592 INTEGER STATUS, NCID, LATID
1594 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1595 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1597 STATUS = NF_REDEF(NCID)
1598 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1600 STATUS = NF_DEF_DIM(NCID, 'LAT', 18, LATID)
1601 IF (STATUS .NE. NF_NOERR) THEN ! dimension definition failed
1602 CALL HANDLE_ERR(STATUS)
1603 STATUS = NF_ABORT(NCID) ! abort redefinitions
1604 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1610 2.18 NF_SET_FILL {#f77_NF-SET-FILL}
1613 This function is intended for advanced usage, to optimize writes under
1614 some circumstances described below. The function NF\_SET\_FILL sets the
1615 fill mode for a netCDF dataset open for writing and returns the current
1616 fill mode in a return parameter. The fill mode can be specified as
1617 either NF\_FILL or NF\_NOFILL. The default behavior corresponding to
1618 NF\_FILL is that data is pre-filled with fill values, that is fill
1619 values are written when you create non-record variables or when you
1620 write a value beyond data that has not yet been written. This makes it
1621 possible to detect attempts to read data before it was written. See
1622 section [Fill Values](#Fill-Values), for more information on the use of
1623 fill values. See [(netcdf)Attribute
1624 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
1625 Conventions’ in The NetCDF Users Guide, for information about how to
1626 define your own fill values.
1628 The behavior corresponding to NF\_NOFILL overrides the default behavior
1629 of prefilling data with fill values. This can be used to enhance
1630 performance, because it avoids the duplicate writes that occur when the
1631 netCDF library writes fill values that are later overwritten with data.
1633 A value indicating which mode the netCDF dataset was already in is
1634 returned. You can use this value to temporarily change the fill mode of
1635 an open netCDF dataset and then restore it to the previous mode.
1637 After you turn on NF\_NOFILL mode for an open netCDF dataset, you must
1638 be certain to write valid data in all the positions that will later be
1639 read. Note that nofill mode is only a transient property of a netCDF
1640 dataset open for writing: if you close and reopen the dataset, it will
1641 revert to the default behavior. You can also revert to the default
1642 behavior by calling NF\_SET\_FILL again to explicitly set the fill mode
1645 There are three situations where it is advantageous to set nofill mode:
1647 1. Creating and initializing a netCDF dataset. In this case, you should
1648 set nofill mode before calling NF\_ENDDEF and then write completely
1649 all non-record variables and the initial records of all the record
1650 variables you want to initialize.
1651 2. Extending an existing record-oriented netCDF dataset. Set nofill
1652 mode after opening the dataset for writing, then append the
1653 additional records to the dataset completely, leaving no intervening
1655 3. Adding new variables that you are going to initialize to an existing
1656 netCDF dataset. Set nofill mode before calling NF\_ENDDEF then write
1657 all the new variables completely.
1659 If the netCDF dataset has an unlimited dimension and the last record was
1660 written while in nofill mode, then the dataset may be shorter than if
1661 nofill mode was not set, but this will be completely transparent if you
1662 access the data only through the netCDF interfaces.
1664 The use of this feature may not be available (or even needed) in future
1665 releases. Programmers are cautioned against heavy reliance upon this
1674 INTEGER FUNCTION NF_SET_FILL(INTEGER NCID, INTEGER FILLMODE,
1679 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1682 : Desired fill mode for the dataset, either NF\_NOFILL or NF\_FILL.
1685 : Returned current fill mode of the dataset before this call, either
1686 NF\_NOFILL or NF\_FILL.
1691 NF\_SET\_FILL returns the value NF\_NOERR if no errors occurred.
1692 Otherwise, the returned status indicates an error. Possible causes of
1695 - The specified netCDF ID does not refer to an open netCDF dataset.
1696 - The specified netCDF ID refers to a dataset open for read-only
1698 - The fill mode argument is neither NF\_NOFILL nor NF\_FILL..
1703 Here is an example using NF\_SET\_FILL to set nofill mode forbsequent
1704 writes of a netCDF dataset named foo.nc:
1708 INCLUDE 'netcdf.inc'
1710 INTEGER NCID, STATUS, OMODE
1712 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1713 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1715 ! write data with default prefilling behavior
1717 STATUS = NF_SET_FILL(NCID, NF_NOFILL, OMODE)
1718 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1720 ! write data with no prefilling
1725 2.19 NF_SET_DEFAULT_FORMAT {#f77_NF-SET-DEFAULT-FORMAT}
1726 -----------------------------
1728 This function is intended for advanced users.
1730 In version 3.6, netCDF introduced a new data format, the first change in
1731 the underlying binary data format since the netCDF interface was
1732 released. The new format, 64-bit offset format, was introduced to
1733 greatly relax the limitations on creating very large files.
1735 In version 4.0, another new binary format was introduced: netCDF-4/HDF5.
1737 Users are warned that creating files in the 64-bit offset format makes
1738 them unreadable by the netCDF library prior to version 3.6.0, and
1739 creating files in netcdf-4/HDF5 format makes them unreadable by the
1740 netCDF library prior to version 4.0. For reasons of compatibility, users
1741 should continue to create files in netCDF classic format.
1743 Users who do want to use 64-bit offset or netCDF-4/HDF5 format files can
1744 create them directory from NF\_CREATE, using the proper cmode flag. (see
1745 section [NF\_CREATE](#NF_005fCREATE)).
1747 The function NF\_SET\_DEFAULT\_FORMAT allows the user to change the
1748 format of the netCDF file to be created by future calls to NF\_CREATE
1749 without changing the cmode flag.
1751 This allows the user to convert a program to use the new formats without
1752 changing all calls the NF\_CREATE.
1754 Once the default format is set, all future created files will be in the
1757 Constants are provided in the netcdf.inc file to be used with this
1758 function: nf\_format\_classic, nf\_format\_64bit, nf\_format\_netcdf4
1759 and nf\_format\_netcdf4\_classic.
1767 INTEGER FUNCTION NF_SET_DEFAULT_FORMAT(INTEGER FORMAT, INTEGER OLD_FORMT)
1771 : Either nf\_format\_classic, nf\_format\_64bit, nf\_format\_netcdf4
1772 or nf\_format\_netcdf4\_classic.
1775 : The default format at the time the function is called is returned
1781 The following error codes may be returned by this function:
1783 - An NF\_EINVAL error is returned if an invalid default format is
1792 INCLUDE 'netcdf.inc'
1794 INTEGER STATUS, OLD_FORMAT
1796 STATUS = NF_SET_DEFAULT_FORMAT(nf_format_64bit, OLD_FORMAT)
1797 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1801 2.20 Set HDF5 Chunk Cache for Future File Opens/Creates: NF_SET_CHUNK_CACHE {#f77_Set-HDF5-Chunk}
1802 ------------------------------------------------------------------------------
1804 This function changes the chunk cache settings in the HDF5 library. The
1805 settings apply forbsequent file opens/creates. This function does not
1806 change the chunk cache settings of already open files.
1808 This affects the per-file chunk cache which the HDF5 layer maintains.
1809 The chunk cache size can be tuned for better performance.
1811 For more information, see the documentation for the H5Pset\_cache()
1812 function in the HDF5 library at the HDF5 website:
1813 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
1821 INTEGER NF_SET_CHUNK_CACHE(INTEGER SIZE, INTEGER NELEMS, INTEGER PREEMPTION);
1825 : The total size of the raw data chunk cache in MegaBytes.
1828 : The number slots in the per-variable chunk cache (should be a prime
1829 number larger than the number of chunks in the cache).
1832 : The preemtion value must be between 0 and 100 inclusive and
1833 indicates how much chunks that have been fully read are favored for
1834 preemption. A value of zero means fully read chunks are treated no
1835 differently than other chunks (the preemption is strictly LRU) while
1836 a value of 100 means fully read chunks are always preempted before
1846 : Parameters size and nelems must be non-zero positive integers, and
1847 preemption must be between zero and 100 (inclusive). An NF\_EINVAL
1848 will be returned otherwise.
1852 2.21 Get the HDF5 Chunk Cache Settings for Future File Opens/Creates: NF_GET_CHUNK_CACHE {#f77_NF-GET-CHUNK-CACHE}
1853 -------------------------------------------------------------------------------------------
1855 This function gets the chunk cache settings for the HDF5 library. The
1856 settings apply forbsequent file opens/creates.
1858 This affects the per-file chunk cache which the HDF5 layer maintains.
1859 The chunk cache size can be tuned for better performance.
1861 For more information, see the documentation for the H5Pget\_cache()
1862 function in the HDF5 library at the HDF5 website:
1863 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
1871 INTEGER NC_GET_CHUNK_CACHE(INTEGER SIZE, INTEGER NELEMS, INTEGER PREEMPTION);
1875 : The total size of the raw data chunk cache will be put here.
1878 : The number of chunk slots in the raw data chunk cache hash table
1882 : The preemption will be put here. The preemtion value is between 0
1883 and 100 inclusive and indicates how much chunks that have been fully
1884 read are favored for preemption. A value of zero means fully read
1885 chunks are treated no differently than other chunks (the preemption
1886 is strictly LRU) while a value of 100 means fully read chunks are
1887 always preempted before other chunks.
1895 3. Groups {#f77_Groups}
1898 NetCDF-4 addedpport for hierarchical groups within netCDF datasets.
1900 Groups are identified with a ncid, which identifies both the open file,
1901 and the group within that file. When a file is opened with NF\_OPEN or
1902 NF\_CREATE, the ncid for the root group of that file is provided. Using
1903 that as a starting point, users can add new groups, or list and navigate
1906 All netCDF calls take a ncid which determines where the call will take
1907 its action. For example, the NF\_DEF\_VAR function takes a ncid as its
1908 first parameter. It will create a variable in whichever group its ncid
1909 refers to. Use the root ncid provided by NF\_CREATE or NF\_OPEN to
1910 create a variable in the root group. Or use NF\_DEF\_GRP to create a
1911 group and use its ncid to define a variable in the new group.
1913 Variable are only visible in the group in which they are defined. The
1914 same applies to attributes. “Global” attributes are defined in whichever
1915 group is refered to by the ncid.
1917 Dimensions are visible in their groups, and all child groups.
1919 Group operations are only permitted on netCDF-4 files - that is, files
1920 created with the HDF5 flag in nf\_create. (see
1921 [NF\_CREATE](#NF_005fCREATE)). Groups are not compatible with the netCDF
1922 classic data model, so files created with the NF\_CLASSIC\_MODEL file
1923 cannot contain groups (except the root group).
1925 3.1 Find a Group ID: NF_INQ_NCID {#f77_NF-INQ-NCID}
1926 ----------------------------------
1928 Given an ncid and group name (NULL or "" gets root group), return ncid
1937 INTEGER FUNCTION NF_INQ_NCID(INTEGER NCID, CHARACTER*(*) NAME, INTEGER GRPID)
1941 : The group id for this operation.
1944 : A character array that holds the name of the desired group. Must be
1945 less then NF\_MAX\_NAME.
1948 : The ID of the group will go here.
1960 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
1961 operations can only be performed on files defined with a create mode
1962 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
1965 : This file was created with the strict netcdf-3 flag, therefore
1966 netcdf-4 operations are not allowed. (see
1967 [NF\_OPEN](#NF_005fOPEN)).
1970 : An error was reported by the HDF5 layer.
1975 This example is from nf\_test/ftst\_groups.F.
1980 C Check getting the group by name
1981 retval = nf_inq_ncid(ncid, group_name, grpid_in)
1982 if (retval .ne. nf_noerr) call handle_err(retval)
1985 3.2 Get a List of Groups in a Group: NF_INQ_GRPS {#f77_NF-INQ-GRPS}
1986 --------------------------------------------------
1988 Given a location id, return the number of groups it contains, and an
1989 array of their ncids.
1997 INTEGER FUNCTION NF_INQ_GRPS(INTEGER NCID, INTEGER NUMGRPS, INTEGER NCIDS)
2001 : The group id for this operation.
2004 : An integer which will get number of groups in this group.
2007 : An array of ints which will receive the IDs of all the groups in
2020 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2021 operations can only be performed on files defined with a create mode
2022 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2025 : This file was created with the strict netcdf-3 flag, therefore
2026 netcdf-4 operations are not allowed. (see
2027 [NF\_OPEN](#NF_005fOPEN)).
2030 : An error was reported by the HDF5 layer.
2035 This example is from nf\_test/ftst\_groups.F.
2040 C What groups are there from the root group?
2041 retval = nf_inq_grps(ncid, ngroups_in, grpids)
2042 if (retval .ne. nf_noerr) call handle_err(retval)
2045 3.3 Find all the Variables in a Group: NF_INQ_VARIDS {#f77_NF-INQ-VARIDS}
2046 ------------------------------------------------------
2048 Find all varids for a location.
2056 INTEGER FUNCTION NF_INQ_VARIDS(INTEGER NCID, INTEGERS VARIDS)
2060 : The group id for this operation.
2063 : An already allocated array to store the list of varids. Use
2064 nf\_inq\_nvars to find out how many variables there are. (see
2065 [NF\_INQ Family](#NF_005fINQ-Family)).
2077 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2078 operations can only be performed on files defined with a create mode
2079 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2082 : This file was created with the strict netcdf-3 flag, therefore
2083 netcdf-4 operations are not allowed. (see
2084 [NF\_OPEN](#NF_005fOPEN)).
2087 : An error was reported by the HDF5 layer.
2092 This example is from nf\_test/ftst\_groups.F.
2097 C Check varids inbgroup.
2098 retval = nf_inq_varidsbgrp_in, nvars, varids_in)
2099 if (retval .ne. nf_noerr) call handle_err(retval)
2102 3.4 Find all Dimensions Visible in a Group: NF_INQ_DIMIDS {#f77_NF-INQ-DIMIDS}
2103 -----------------------------------------------------------
2105 Find all dimids for a location. This finds all dimensions in a group, or
2114 INTEGER FUNCTION NF_INQ_DIMIDS(INTEGER NCID, INTEGER NDIMS, INTEGER DIMIDS, INTEGER INCLUDE_PARENTS)
2118 : The group id for this operation.
2121 : Returned number of dimensions for this location. If INCLUDE\_PARENTS
2122 is non-zero, number of dimensions visible from this group, which
2123 includes dimensions in parent groups.
2126 : An array of ints when the dimids of the visible dimensions will be
2127 stashed. Use nf\_inq\_ndims to find out how many dims are visible
2128 from this group. (see [NF\_INQ Family](#NF_005fINQ-Family)).
2131 : If zero, only the group specified by NCID will be searched for
2132 dimensions. Otherwise parent groups will be searched too.
2144 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2145 operations can only be performed on files defined with a create mode
2146 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2149 : This file was created with the strict netcdf-3 flag, therefore
2150 netcdf-4 operations are not allowed. (see
2151 [NF\_OPEN](#NF_005fOPEN)).
2154 : An error was reported by the HDF5 layer.
2159 This example is from nf\_test/ftst\_groups.F.
2164 C Check dimids inbgroup.
2165 retval = nf_inq_dimidsbgrp_in, ndims, dimids_in, 0)
2166 if (retval .ne. nf_noerr) call handle_err(retval)
2167 if (ndims .ne. 2 .or. dimids_in(1) .ne. dimids(1) .or.
2168 & dimids_in(2) .ne. dimids(2)) stop 2
2171 3.5 Find the Length of a Group’s Name: NF_INQ_GRPNAME_LE {#f77_NF-INQ-GRPNAME-LE}
2172 ------------------------------------------------------------
2174 Given ncid, find length of the full name. (Root group is named "/", with
2183 INTEGER FUNCTION NF_INQ_GRPNAME_LEN(INTEGER NCID, INTEGER LEN)
2187 : The group id for this operation.
2190 : An integer where the length will be placed.
2202 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2203 operations can only be performed on files defined with a create mode
2204 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2207 : This file was created with the strict netcdf-3 flag, therefore
2208 netcdf-4 operations are not allowed. (see
2209 [NF\_OPEN](#NF_005fOPEN)).
2212 : An error was reported by the HDF5 layer.
2217 This example is from nf\_test/ftst\_groups.F.
2222 C Check the length of the full name.
2223 retval = nf_inq_grpname_len(grpids(1), full_name_len)
2224 if (retval .ne. nf_noerr) call handle_err(retval)
2227 3.6 Find a Group’s Name: NF_INQ_GRPNAME {#f77_NF-INQ-GRPNAME}
2228 -----------------------------------------
2230 Given ncid, find relative name of group. (Root group is named "/").
2232 The name provided by this function is relative to the parent group. For
2233 a full path name for the group is, with all parent groups included,
2234 separated with a forward slash (as in Unix directory names) See
2235 [Find a Group’s Full Name:
2236 NF\_INQ\_GRPNAME\_FULL](#NF_005fINQ_005fGRPNAME_005fFULL).
2244 INTEGER FUNCTION NF_INQ_GRPNAME(INTEGER NCID, CHARACTER*(*) NAME)
2249 The group id for this operation.
2253 The name of the group will be copied to this character array. The name
2254 will be less than NF\_MAX\_NAME in length.
2268 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2269 operations can only be performed on files defined with a create mode
2270 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2273 : This file was created with the strict netcdf-3 flag, therefore
2274 netcdf-4 operations are not allowed. (see
2275 [NF\_OPEN](#NF_005fOPEN)).
2278 : An error was reported by the HDF5 layer.
2283 This example is from nf\_test/ftst\_groups.F.
2288 C Check the name of the root group.
2289 retval = nf_inq_grpname(ncid, name_in)
2290 if (retval .ne. nf_noerr) call handle_err(retval)
2291 if (name_in(1:1) .ne. '/') stop 2
2295 3.7 Find a Group’s Full Name: NF_INQ_GRPNAME_FULL {#f77_NF-INQ-GRPNAME-FULL}
2296 ----------------------------------------------------
2298 Given ncid, find complete name of group. (Root group is named "/").
2300 The name provided by this function is a full path name for the group is,
2301 with all parent groups included, separated with a forward slash (as in
2302 Unix directory names). For a name relative to the parent group See
2303 section [Find a Group’s Name:
2304 NF\_INQ\_GRPNAME](#NF_005fINQ_005fGRPNAME).
2306 To find the length of the full name See [Find the Length of a
2307 Group’s Name: NF\_INQ\_GRPNAME\_LEN](#NF_005fINQ_005fGRPNAME_005fLEN).
2315 INTEGER FUNCTION NF_INQ_GRPNAME_FULL(INTEGER NCID, INTEGER LEN, CHARACTER*(*) NAME)
2319 : The group id for this operation.
2322 : The length of the full group name will go here.
2325 : The name of the group will be copied to this character array.
2337 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2338 operations can only be performed on files defined with a create mode
2339 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2342 : This file was created with the strict netcdf-3 flag, therefore
2343 netcdf-4 operations are not allowed. (see
2344 [NF\_OPEN](#NF_005fOPEN)).
2347 : An error was reported by the HDF5 layer.
2352 This example is from nf\_test/ftst\_groups.F.
2357 C Check the full name.
2358 retval = nf_inq_grpname_full(grpids(1), full_name_len, name_in2)
2359 if (retval .ne. nf_noerr) call handle_err(retval)
2362 3.8 Find a Group’s Parent: NF_INQ_GRP_PARENT {#f77_NF-INQ-GRP-PARENT}
2363 -----------------------------------------------
2365 Given ncid, find the ncid of the parent group.
2367 When used with the root group, this function returns the NF\_ENOGRP
2368 error (since the root group has no parent.)
2376 INTEGER FUNCTION NF_INQ_GRP_PARENT(INTEGER NCID, INTEGER PARENT_NCID)
2383 : The ncid of the parent group will be copied here.
2395 : No parent group found (i.e. this is the root group).
2398 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2399 operations can only be performed on files defined with a create mode
2400 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2403 : This file was created with the strict netcdf-3 flag, therefore
2404 netcdf-4 operations are not allowed. (see
2405 [NF\_OPEN](#NF_005fOPEN)).
2408 : An error was reported by the HDF5 layer.
2413 This example is from nf\_test/ftst\_groups.F.
2418 C Check the parent ncid.
2419 retval = nf_inq_grp_parent(grpids(1), grpid_in)
2420 if (retval .ne. nf_noerr) call handle_err(retval)
2423 3.9 Find a Group by Name: NF_INQ_GRP_NCID {#f77_NF-INQ-GRP-NCID}
2424 --------------------------------------------
2426 Given a group name an an ncid, find the ncid of the group id.
2434 INTEGER FUNCTION NF_INQ_GRP_NCID(INTEGER NCID, CHARACTER GRP_NAME, INTEGER GRP_NCID)
2438 : The group id to look in.
2441 : The name of the group that should be found.
2444 : This will get the group id, if it is found.
2449 The following return codes may be returned by this function.
2458 : No name provided or name longer than NF\_MAX\_NAME.
2461 : Named group not found.
2464 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2465 operations can only be performed on files defined with a create mode
2466 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2469 : This file was created with the strict netcdf-3 flag, therefore
2470 netcdf-4 operations are not allowed. (see
2471 [NF\_OPEN](#NF_005fOPEN)).
2474 : An error was reported by the HDF5 layer.
2479 This example is from nf\_test/ftst\_types3.F.
2484 C Go to a child group and find the id of our type.
2485 retval = nf_inq_grp_ncid(ncid, group_name,b_grpid)
2486 if (retval .ne. nf_noerr) call handle_err(retval)
2489 3.10 Find a Group by its Fully-qualified Name: NF_INQ_GRP_FULL_NCID {#f77_NF-INQ-GRP-FULL-NCID}
2490 -----------------------------------------------------------------------
2492 Given a fully qualified group name an an ncid, find the ncid of the
2501 INTEGER FUNCTION NF_INQ_GRP_FULL_NCID(INTEGER NCID, CHARACTER FULL_NAME, INTEGER GRP_NCID)
2505 : The group id to look in.
2508 : The fully-qualified group name.
2511 : This will get the group id, if it is found.
2516 The following return codes may be returned by this function.
2525 : No name provided or name longer than NF\_MAX\_NAME.
2528 : Named group not found.
2531 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2532 operations can only be performed on files defined with a create mode
2533 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2536 : This file was created with the strict netcdf-3 flag, therefore
2537 netcdf-4 operations are not allowed. (see
2538 [NF\_OPEN](#NF_005fOPEN)).
2541 : An error was reported by the HDF5 layer.
2546 This example is from nf\_test/ftst\_groups.F.
2551 C Check the full name of the root group (also "/").
2552 retval = nf_inq_grpname_full(ncid, full_name_len, name_in)
2553 if (retval .ne. nf_noerr) call handle_err(retval)
2556 3.11 Create a New Group: NF_DEF_GRP {#f77_NF-DEF-GRP}
2557 -------------------------------------
2559 Create a group. Its location id is returned in new\_ncid.
2567 INTEGER FUNCTION NF_DEF_GRP(INTEGER PARENT_NCID, CHARACTER*(*) NAME,
2572 : The group id of the parent group.
2575 : The name of the new group, which must be different from the name of
2576 any variable within the same parent group.
2579 : The ncid of the new group will be placed there.
2591 : That name is in use. Group names must be unique within a group.
2594 : Name exceed max length NF\_MAX\_NAME.
2597 : Name contains illegal characters.
2600 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2601 operations can only be performed on files defined with a create mode
2602 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2605 : This file was created with the strict netcdf-3 flag, therefore
2606 netcdf-4 operations are not allowed. (see
2607 [NF\_OPEN](#NF_005fOPEN)).
2610 : An error was reported by the HDF5 layer.
2613 : Attempt to write to a read-only file.
2616 : Not in define mode.
2621 In this exampe rom nf\_test/ftst\_groups.F, a groups is reated, and then
2622 ab-group is created in that group.
2627 C Create the netCDF file.
2628 retval = nf_create(file_name, NF_NETCDF4, ncid)
2629 if (retval .ne. nf_noerr) call handle_err(retval)
2631 C Create a group and abgroup.
2632 retval = nf_def_grp(ncid, group_name, grpid)
2633 if (retval .ne. nf_noerr) call handle_err(retval)
2634 retval = nf_def_grp(grpid,b_group_name,b_grpid)
2635 if (retval .ne. nf_noerr) call handle_err(retval)
2638 4. Dimensions {#f77_Dimensions}
2641 4.1 Dimensions Introduction {#f77_Dimensions-Introduction}
2642 ---------------------------
2644 Dimensions for a netCDF dataset are defined when it is created, while
2645 the netCDF dataset is in define mode. Additional dimensions may be added
2646 later by reentering define mode. A netCDF dimension has a name and a
2647 length. At most one dimension in a netCDF dataset can have the unlimited
2648 length, which means variables using this dimension can grow along this
2651 There is aggested limit (100) to the number of dimensions that can be
2652 defined in a single netCDF dataset. The limit is the value of the
2653 predefined macro NF\_MAX\_DIMS. The purpose of the limit is to make
2654 writing generic applications simpler. They need only provide an array of
2655 NF\_MAX\_DIMS dimensions to handle any netCDF dataset. The
2656 implementation of the netCDF library does not enforce this advisory
2657 maximum, so it is possible to use more dimensions, if necessary, but
2658 netCDF utilities that ame the advisory maximums may not be able to
2659 handle the rlting netCDF datasets.
2661 Ordinarily, the name and length of a dimension are fixed when the
2662 dimension is first defined. The name may be changed later, but the
2663 length of a dimension (other than the unlimited dimension) cannot be
2664 changed without copying all the data to a new netCDF dataset with a
2665 redefined dimension length.
2667 A netCDF dimension in an open netCDF dataset is referred to by a small
2668 integer called a dimension ID. In the FORTRAN interface, dimension IDs
2669 are 1, 2, 3, ..., in the order in which the dimensions were defined.
2671 Operationspported on dimensions are:
2673 - Create a dimension, given its name and length.
2674 - Get a dimension ID from its name.
2675 - Get a dimension’s name and length from its ID.
2676 - Rename a dimension.
2678 4.2 NF_DEF_DIM {#f77_NF-DEF-DIM}
2681 The function NF\_DEF\_DIM adds a new dimension to an open netCDF dataset
2682 in define mode. It returns (as an argument) a dimension ID, given the
2683 netCDF ID, the dimension name, and the dimension length. At most one
2684 unlimited length dimension, called the record dimension, may be defined
2685 for each netCDF dataset.
2693 INTEGER FUNCTION NF_DEF_DIM (INTEGER NCID, CHARACTER*(*) NAME,
2694 INTEGER LEN, INTEGER dimid)
2698 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2704 : Length of dimension; that is, number of values for this dimension as
2705 an index to variables that use it. This should be either a positive
2706 integer or the predefined constant NF\_UNLIMITED.
2709 : Returned dimension ID.
2714 NF\_DEF\_DIM returns the value NF\_NOERR if no errors occurred.
2715 Otherwise, the returned status indicates an error. Possible causes of
2718 - The netCDF dataset is not in definition mode.
2719 - The specified dimension name is the name of another existing
2721 - The specified length is not greater than zero.
2722 - The specified length is unlimited, but there is already an unlimited
2723 length dimension defined for this netCDF dataset.
2724 - The specified netCDF ID does not refer to an open netCDF dataset.
2729 Here is an example using NF\_DEF\_DIM to create a dimension named lat of
2730 length 18 and a unlimited dimension named rec in a new netCDF dataset
2736 INCLUDE 'netcdf.inc'
2738 INTEGER STATUS, NCID, LATID, RECID
2740 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
2741 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2743 STATUS = NF_DEF_DIM(NCID, 'lat', 18, LATID)
2744 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2745 STATUS = NF_DEF_DIM(NCID, 'rec', NF_UNLIMITED, RECID)
2746 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2749 4.3 NF_INQ_DIMID {#f77_NF-INQ-DIMID}
2752 The function NF\_INQ\_DIMID returns (as an argument) the ID of a netCDF
2753 dimension, given the name of the dimension. If ndims is the number of
2754 dimensions defined for a netCDF dataset, each dimension has an ID
2755 between 1 and ndims.
2763 INTEGER FUNCTION NF_INQ_DIMID (INTEGER NCID, CHARACTER*(*) NAME,
2768 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2774 : Returned dimension ID.
2779 NF\_INQ\_DIMID returns the value NF\_NOERR if no errors occurred.
2780 Otherwise, the returned status indicates an error. Possible causes of
2783 - The name that was specified is not the name of a dimension in the
2785 - The specified netCDF ID does not refer to an open netCDF dataset.
2790 Here is an example using NF\_INQ\_DIMID to determine the dimension ID of
2791 a dimension named lat, amed to have been defined previously in an
2792 existing netCDF dataset named foo.nc:
2797 INCLUDE 'netcdf.inc'
2799 INTEGER STATUS, NCID, LATID
2801 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
2802 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2804 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2805 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2808 4.4 NF_INQ_DIM Family {#f77_NF-INQ-DIM-Family}
2809 -----------------------
2811 This family of functions returns information about a netCDF dimension.
2812 Information about a dimension includes its name and its length. The
2813 length for the unlimited dimension, if any, is the number of records
2816 The functions in this family include NF\_INQ\_DIM, NF\_INQ\_DIMNAME, and
2817 NF\_INQ\_DIMLEN. The function NF\_INQ\_DIM returns all the information
2818 about a dimension; the other functions each return just one item of
2827 INTEGER FUNCTION NF_INQ_DIM (INTEGER NCID, INTEGER DIMID,
2828 CHARACTER*(*) name, INTEGER len)
2829 INTEGER FUNCTION NF_INQ_DIMNAME (INTEGER NCID, INTEGER DIMID,
2831 INTEGER FUNCTION NF_INQ_DIMLEN (INTEGER NCID, INTEGER DIMID,
2836 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2839 : Dimension ID, from a previous call to NF\_INQ\_DIMID or
2843 : Returned dimension name. The caller must allocate space for the
2844 returned name. The maximum possible length, in characters, of a
2845 dimension name is given by the predefined constant NF\_MAX\_NAME.
2848 : Returned length of dimension. For the unlimited dimension, this is
2849 the current maximum value used for writing any variables with this
2850 dimension, that is the maximum record number.
2855 These functions return the value NF\_NOERR if no errors occurred.
2856 Otherwise, the returned status indicates an error. Possible causes of
2859 - The dimension ID is invalid for the specified netCDF dataset.
2860 - The specified netCDF ID does not refer to an open netCDF dataset.
2865 Here is an example using NF\_INQ\_DIM to determine the length of a
2866 dimension named lat, and the name and current maximum length of the
2867 unlimited dimension for an existing netCDF dataset named foo.nc:
2872 INCLUDE 'netcdf.inc'
2874 INTEGER STATUS, NCID, LATID, LATLEN, RECID, NRECS
2875 CHARACTER*(NF_MAX_NAME) LATNAM, RECNAM
2877 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
2878 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2879 ! get ID of unlimited dimension
2880 STATUS = NF_INQ_UNLIMDIM(NCID, RECID)
2881 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2883 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2884 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2886 STATUS = NF_INQ_DIMLEN(NCID, LATID, LATLEN)
2887 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2888 ! get unlimited dimension name and current length
2889 STATUS = NF_INQ_DIM(NCID, RECID, RECNAME, NRECS)
2890 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2893 4.5 NF_RENAME_DIM {#f77_NF-RENAME-DIM}
2896 The function NF\_RENAME\_DIM renames an existing dimension in a netCDF
2897 dataset open for writing. If the new name is longer than the old name,
2898 the netCDF dataset must be in define mode. You cannot rename a dimension
2899 to have the same name as another dimension.
2907 INTEGER FUNCTION NF_RENAME_DIM (INTEGER NCID, INTEGER DIMID,
2912 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2915 : Dimension ID, from a previous call to NF\_INQ\_DIMID or
2919 : New dimension name.
2924 NF\_RENAME\_DIM returns the value NF\_NOERR if no errors occurred.
2925 Otherwise, the returned status indicates an error. Possible causes of
2928 - The new name is the name of another dimension.
2929 - The dimension ID is invalid for the specified netCDF dataset.
2930 - The specified netCDF ID does not refer to an open netCDF dataset.
2931 - The new name is longer than the old name and the netCDF dataset is
2937 Here is an example using NF\_RENAME\_DIM to rename the dimension lat to
2938 latitude in an existing netCDF dataset named foo.nc:
2943 INCLUDE 'netcdf.inc'
2945 INTEGER STATUS, NCID, LATID
2947 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
2948 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2950 ! put in define mode to rename dimension
2951 STATUS = NF_REDEF(NCID)
2952 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2953 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2954 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2955 STATUS = NF_RENAME_DIM(NCID, LATID, 'latitude')
2956 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2958 STATUS = NF_ENDDEF(NCID)
2959 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2962 5. User Defined Data Types {#f77_User-Defined-Data-Types}
2963 ==========================
2965 5.1 User Defined Types Introduction {#f77_User-Defined-Types-Introduction}
2966 -----------------------------------
2968 NetCDF-4 has added support for four different user defined data types.
2971 : Like a C struct, a compound type is a collection of types, including
2972 other user defined types, in one package.
2974 `variable length array type`
2975 : The variable length array may be used to store ragged arrays.
2978 : This type has only a size per element, and no other type
2982 : Like an enumeration in C, this type lets you assign text values to
2983 integer values, and store the integer values.
2985 Users may construct user defined type with the various NF\_DEF\_\*
2986 functions described in this. They may learn about user defined
2987 types by using the NF\_INQ\_ functions defined in this.
2989 Once types are constructed, define variables of the new type with
2990 NF\_DEF\_VAR (see [Create a Variable:
2991 `NF_DEF_VAR`](#NF_005fDEF_005fVAR)). Write to them with NF\_PUT\_VAR1,
2992 NF\_PUT\_VAR, NF\_PUT\_VARA, or NF\_PUT\_VARS (see
2993 [Variables](#Variables)). Read data of user-defined type with
2994 NF\_GET\_VAR1, NF\_GET\_VAR, NF\_GET\_VARA, or NF\_GET\_VARS (see
2995 section [Variables](#Variables)).
2997 Create attributes of the new type with NF\_PUT\_ATT (see
2998 [NF\_PUT\_ATT\_ type](#NF_005fPUT_005fATT_005f-type)). Read attributes
2999 of the new type with NF\_GET\_ATT (see [NF\_GET\_ATT\_
3000 type](#NF_005fGET_005fATT_005f-type)).
3002 5.2 Learn the IDs of All Types in Group: NF_INQ_TYPEIDS {#f77_NF-INQ-TYPEIDS}
3003 ---------------------------------------------------------
3005 Learn the number of types defined in a group, and their IDs.
3012 INTEGER FUNCTION NF_INQ_TYPEIDS(INTEGER NCID, INTEGER NTYPES,
3020 : A pointer to int which will get the number of types defined in the
3021 group. If NULL, ignored.
3024 : A pointer to an int array which will get the typeids. If NULL,
3039 The following example is from the test program nf\_test/ftst\_vars3.F.
3044 retval = nf_inq_typeids(ncid, num_types, typeids)
3045 if (retval .ne. nf_noerr) call handle_err(retval)
3049 5.3 Find a Typeid from Group and Name: NF_INQ_TYPEID {#f77_NF-INQ-TYPEID}
3050 ------------------------------------------------------
3052 Given a group ID and a type name, find the ID of the type. If the type
3053 is not found in the group, then the parents are searched. If still not
3054 found, the entire file is searched.
3062 INTEGER FUNCTION NF_INQ_TYPEID(INTEGER NCID, CHARACTER NAME, NF_TYPE TYPEIDP)
3069 : The name of a type.
3072 : The typeid of the named type (if found).
3089 The following example is from nf\_test/ftst\_types3.F:
3094 C Go to a child group and find the id of our type.
3095 retval = nf_inq_grp_ncid(ncid, group_name,b_grpid)
3096 if (retval .ne. nf_noerr) call handle_err(retval)
3097 retval = nf_inq_typeidb_grpid, type_name, typeid_in)
3098 if (retval .ne. nf_noerr) call handle_err(retval)
3101 5.4 Learn About a User Defined Type: NF_INQ_TYPE {#f77_NF-INQ-TYPE}
3102 --------------------------------------------------
3104 Given an ncid and a typeid, get the information about a type. This
3105 function will work on any type, including atomic and any user defined
3106 type, whether compound, opaque, enumeration, or variable length array.
3108 For even more information about a user defined type [Learn About a User
3109 Defined Type: NF\_INQ\_USER\_TYPE](#NF_005fINQ_005fUSER_005fTYPE).
3117 INTEGER FUNCTION NF_INQ_TYPE(INTEGER NCID, INTEGER XTYPE,
3118 CHARACTER*(*) NAME, INTEGER SIZE)
3122 : The ncid for the group containing the type (ignored for atomic
3126 : The typeid for this type, as returned by NF\_DEF\_COMPOUND,
3127 NF\_DEF\_OPAQUE, NF\_DEF\_ENUM, NF\_DEF\_VLEN, or NF\_INQ\_VAR, or
3128 as found in netcdf.inc in the list of atomic types (NF\_CHAR,
3132 : The name of the user defined type will be copied here. It will be
3133 NF\_MAX\_NAME bytes or less. For atomic types, the type name from
3137 : The (in-memory) size of the type (in bytes) will be copied here.
3138 VLEN type size is the size of one vlen sturture (i.e. the sice of
3139 nc\_vlen\_t). String size is returned as the size of one C character
3152 : Seeking a user-defined type in a netCDF-3 file.
3155 : Seeking a user-defined type in a netCDF-4 file for which classic
3156 model has been turned on.
3159 : Bad group ID in ncid.
3162 : Type ID not found.
3165 : An error was reported by the HDF5 layer.
3170 This example is from the test program nf\_test/ftst\_vars3.F, and it
3171 uses all the possible inquiry functions on an enum type.
3176 C Check the enum type.
3177 retval = NF_INQ_TYPEIDS(ncid, num_types, typeids)
3178 if (retval .ne. nf_noerr) call handle_err(retval)
3179 if (num_types .ne. MAX_TYPES) stop 2
3180 retval = nf_inq_enum(ncid, typeids(1), type_name, base_type,
3181 & base_size, num_members)
3182 if (retval .ne. nf_noerr) call handle_err(retval)
3183 if (base_type .ne. NF_INT .or. num_members .ne. 2) stop 2
3184 retval = nf_inq_enum_member(ncid, typeids(1), 1, member_name,
3186 if (retval .ne. nf_noerr) call handle_err(retval)
3187 if (member_name(1:len(one_name)) .ne. one_name) stop 2
3190 5.5 Learn About a User Defined Type: NF_INQ_USER_TYPE {#f77_NF-INQ-USER-TYPE}
3191 --------------------------------------------------------
3193 Given an ncid and a typeid, get the information about a user defined
3194 type. This function will work on any user defined type, whether
3195 compound, opaque, enumeration, or variable length array.
3203 INTEGER FUNCTION NF_INQ_USER_TYPE(INTEGER NCID, INTEGER XTYPE,
3204 CHARACTER*(*) NAME, INTEGER SIZE, INTEGER BASE_NF_TYPE,
3205 INTEGER NFIELDS, INTEGER CLASS)
3209 : The ncid for the group containing the user defined type.
3212 : The typeid for this type, as returned by NF\_DEF\_COMPOUND,
3213 NF\_DEF\_OPAQUE, NF\_DEF\_ENUM, NF\_DEF\_VLEN, or NF\_INQ\_VAR.
3216 : The name of the user defined type will be copied here. It will be
3217 NF\_MAX\_NAME bytes or less.
3220 : The (in-memory) size of the user defined type will be copied here.
3223 : The base typeid will be copied here for vlen and enum types.
3226 : The number of fields will be copied here for enum and compound
3230 : The class of the user defined type, NF\_VLEN, NF\_OPAQUE, NF\_ENUM,
3231 or NF\_COMPOUND, will be copied here.
3246 : An error was reported by the HDF5 layer.
3251 This example is from nf\_test/ftst\_types2.F.
3257 retval = nf_inq_user_type(ncid, typeids(1), name_in, size_in,
3258 & base_type_in, nfields_in, class_in)
3259 if (retval .ne. nf_noerr) call handle_err(retval)
3262 5.6 Compound Types Introduction {#f77_Compound-Types-Introduction}
3263 -------------------------------
3265 NetCDF-4 addedpport for compound types, which allow users to
3266 construct a new type - a combination of other types, like a C struct.
3268 Compound types are notpported in classic or 64-bit offset format
3271 To write data in a compound type, first use nf\_def\_compound to create
3272 the type, multiple calls to nf\_insert\_compound to add to the compound
3273 type, and then write data with the appropriate nf\_put\_var1,
3274 nf\_put\_vara, nf\_put\_vars, or nf\_put\_varm call.
3276 To read data written in a compound type, you must know its structure.
3277 Use the NF\_INQ\_COMPOUND functions to learn about the compound type.
3279 In Fortran a character buffer must be used for the compound data. The
3280 user must read the data from within that buffer in the same way that the
3281 C compiler which compiled netCDF would store the structure.
3283 The use of compound types introduces challenges and portability ies
3286 ### 5.6.1 Creating a Compound Type: NF_DEF_COMPOUND {#f77_NF-DEF-COMPOUND}
3288 Create a compound type. Provide an ncid, a name, and a total size (in
3289 bytes) of one element of the completed compound type.
3291 After calling this function, fill out the type with repeated calls to
3292 NF\_INSERT\_COMPOUND (see [Inserting a Field into a Compound
3293 Type: NF\_INSERT\_COMPOUND](#NF_005fINSERT_005fCOMPOUND)). Call
3294 NF\_INSERT\_COMPOUND once for each field you wish to insert into the
3297 Note that there does not seem to be a way to readch types into
3298 structures in Fortran 90 (and there are no structures in Fortran 77).
3300 Fortran users may use character buffers to read and write compound
3309 INTEGER FUNCTION NF_DEF_COMPOUND(INTEGER NCID, INTEGER SIZE,
3310 CHARACTER*(*) NAME, INTEGER TYPEIDP)
3314 : The groupid where this compound type will be created.
3317 : The size, in bytes, of the compound type.
3320 : The name of the new compound type.
3323 : The typeid of the new type will be placed here.
3335 : That name is in use. Compound type names must be unique in the data
3339 : Name exceeds max length NF\_MAX\_NAME.
3342 : Name contains illegal characters.
3345 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3346 operations can only be performed on files defined with a create mode
3347 which includes flag NF\_NETCDF4. (see
3348 [NF\_OPEN](#NF_005fOPEN)).
3351 : This file was created with the strict netcdf-3 flag, therefore
3352 netcdf-4 operations are not allowed. (see
3353 [NF\_OPEN](#NF_005fOPEN)).
3356 : An error was reported by the HDF5 layer.
3359 : Attempt to write to a read-only file.
3362 : Not in define mode.
3367 This example is from nf\_test/ftst\_types2.F.
3372 C Define a compound type.
3373 retval = nf_def_compound(ncid, cmp_size, type_name,
3375 if (retval .ne. nf_noerr) call handle_err(retval)
3378 ### 5.6.2 Inserting a Field into a Compound Type: NF_INSERT_COMPOUND {#f77_NF-INSERT-COMPOUND}
3380 Insert a named field into a compound type.
3388 INTEGER FUNTION NF_INSERT_COMPOUND(INTEGER TYPEID, CHARACTER*(*) NAME, INTEGER OFFSET,
3389 INTEGER FIELD_TYPEID)
3393 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3397 : The name of the new field.
3400 : Offset in byte from the beginning of the compound type for this
3404 : The type of the field to be inserted.
3416 : That name is in use. Field names must be unique within a compound
3420 : Name exceed max length NF\_MAX\_NAME.
3423 : Name contains illegal characters.
3426 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3427 operations can only be performed on files defined with a create mode
3428 which includes flag NF\_NETCDF4. (see
3429 [NF\_OPEN](#NF_005fOPEN)).
3432 : This file was created with the strict netcdf-3 flag, therefore
3433 netcdf-4 operations are not allowed. (see
3434 [NF\_OPEN](#NF_005fOPEN)).
3437 : An error was reported by the HDF5 layer.
3440 : Not in define mode.
3445 This example is from nf\_test/ftst\_types.F.
3450 C Define a compound type.
3451 retval = nf_def_compound(ncid, WIND_T_SIZE, type_name,
3453 if (retval .ne. nf_noerr) call handle_err(retval)
3454 retval = nf_insert_compound(ncid, wind_typeid, u_name, 0, NF_INT)
3455 if (retval .ne. nf_noerr) call handle_err(retval)
3456 retval = nf_insert_compound(ncid, wind_typeid, v_name, 4, NF_INT)
3457 if (retval .ne. nf_noerr) call handle_err(retval)
3461 ### 5.6.3 Inserting an Array Field into a Compound Type: NF_INSERT_ARRAY_COMPOUND {#f77_NF-INSERT-ARRAY-COMPOUND}
3463 Insert a named array field into a compound type.
3471 INTEGER FUNCTION NF_INSERT_ARRAY_COMPOUND(INTEGER NCID, INTEGER XTYPE,
3472 CHARACTER*(*) NAME, INTEGER OFFSET, INTEGER FIELD_TYPEID,
3473 INTEGER NDIMS, INTEGER DIM_SIZES)
3477 : The ID of the file that contains the array type and the compound
3481 : The typeid for this compound type, as returned by nf\_def\_compound,
3485 : The name of the new field.
3488 : Offset in byte from the beginning of the compound type for this
3492 : The base type of the array to be inserted.
3495 : The number of dimensions for the array to be inserted.
3498 : An array containing the sizes of each dimension.
3510 : That name is in use. Field names must be unique within a compound
3514 : Name exceed max length NF\_MAX\_NAME.
3517 : Name contains illegal characters.
3520 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3521 operations can only be performed on files defined with a create mode
3522 which includes flag NF\_NETCDF4. (see
3523 [NF\_OPEN](#NF_005fOPEN)).
3526 : This file was created with the strict netcdf-3 flag, therefore
3527 netcdf-4 operations are not allowed. (see
3528 [NF\_OPEN](#NF_005fOPEN)).
3531 : An error was reported by the HDF5 layer.
3534 : Not in define mode.
3537 : Attempt to change type that has already been committed. The first
3538 time the file leaves define mode, all defined types are committed,
3539 and can’t be changed. If you wish to add an array to a compound
3540 type, you must do so before the compound type is committed.
3545 This example is from nf\_test/ftst\_types2.F.
3550 C Define a compound type.
3551 retval = nf_def_compound(ncid, cmp_size, type_name,
3553 if (retval .ne. nf_noerr) call handle_err(retval)
3558 retval = nf_insert_array_compound(ncid, cmp_typeid, ary_name, 0,
3559 & NF_INT, NDIMS, dim_sizes)
3560 if (retval .ne. nf_noerr) call handle_err(retval)
3563 ### 5.6.4 Learn About a Compound Type: NF_INQ_COMPOUND {#f77_NF-INQ-COMPOUND}
3565 Get the number of fields, length in bytes, and name of a compound type.
3567 In addtion to the NF\_INQ\_COMPOUND function, three additional functions
3568 are provided which get only the name, size, and number of fields.
3576 INTEGER FUNCTION NF_INQ_COMPOUND(INTEGER NCID, INTEGER XTYPE,
3577 CHARACTER*(*) NAME, INTEGER SIZEP, INTEGER NFIELDSP)
3579 INTEGER FUNCTION NF_INQ_COMPOUND_NAME(INTEGER NCID, INTEGER XTYPE,
3582 INTEGER FUNCTION NF_INQ_COMPOUND_SIZE(INTEGER NCID, INTEGER XTYPE,
3585 INTEGER FUNCTION NF_INQ_COMPOUND_NFIELDS(INTEGER NCID, INTEGER XTYPE,
3590 : The ID of any group in the file that contains the compound type.
3593 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3597 : Character array which will get the name of the compound type. It
3598 will have a maximum length of NF\_MAX\_NAME.
3601 : The size of the compound type in bytes will be put here.
3604 : The number of fields in the compound type will be placed here.
3613 : Couldn’t find this ncid.
3616 : Not a netCDF-4/HDF5 file.
3619 : A netCDF-4/HDF5 file, but with CLASSIC\_MODEL. No user defined types
3620 are allowed in the classic model.
3623 : This type not a compound type.
3629 : An error was reported by the HDF5 layer.
3634 This example is from nf\_test/ftst\_types.F.
3639 C Check it differently.
3640 retval = nf_inq_compound(ncid, typeids(1), name_in, size_in,
3642 if (retval .ne. nf_noerr) call handle_err(retval)
3643 if (name_in(1:len(type_name)) .ne. type_name .or.
3644 & size_in .ne. WIND_T_SIZE .or. nfields_in .ne. 2) stop 2
3646 C Check it one piece at a time.
3647 retval = nf_inq_compound_nfields(ncid, typeids(1), nfields_in)
3648 if (retval .ne. nf_noerr) call handle_err(retval)
3649 if (nfields_in .ne. 2) stop 2
3650 retval = nf_inq_compound_size(ncid, typeids(1), size_in)
3651 if (retval .ne. nf_noerr) call handle_err(retval)
3652 if (size_in .ne. WIND_T_SIZE) stop 2
3653 retval = nf_inq_compound_name(ncid, typeids(1), name_in)
3654 if (retval .ne. nf_noerr) call handle_err(retval)
3655 if (name_in(1:len(type_name)) .ne. type_name) stop 2
3658 ### 5.6.5 Learn About a Field of a Compound Type: NF_INQ_COMPOUND_FIELD {#f77_NF-INQ-COMPOUND-FIELD}
3660 Get information about one of the fields of a compound type.
3668 INTEGER FUNCTION NF_INQ_COMPOUND_FIELD(INTEGER NCID, INTEGER XTYPE,
3669 INTEGER FIELDID, CHARACTER*(*) NAME, INTEGER OFFSETP,
3670 INTEGER FIELD_TYPEIDP, INTEGER NDIMSP, INTEGER DIM_SIZESP)
3672 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDNAME(INTEGER TYPEID,
3673 INTEGER FIELDID, CHARACTER*(*) NAME)
3675 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDINDEX(INTEGER TYPEID,
3676 CHARACTER*(*) NAME, INTEGER FIELDIDP)
3678 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDOFFSET(INTEGER TYPEID,
3679 INTEGER FIELDID, INTEGER OFFSETP)
3681 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDTYPE(INTEGER TYPEID,
3682 INTEGER FIELDID, INTEGER FIELD_TYPEIDP)
3684 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDNDIMS(INTEGER NCID,
3685 INTEGER XTYPE, INTEGER FIELDID, INTEGER NDIMSP)
3687 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDDIM_SIZES(INTEGER NCID,
3688 INTEGER XTYPE, INTEGER FIELDID, INTEGER DIM_SIZES)
3692 : The groupid where this compound type exists.
3695 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3699 : A one-based index number specifying a field in the compound type.
3702 : A character array which will get the name of the field. The name
3703 will be NF\_MAX\_NAME characters, at most.
3706 : An integer which will get the offset of the field.
3709 : An integer which will get the typeid of the field.
3712 : An integer which will get the number of dimensions of the field.
3715 : An integer array which will get the dimension sizes of the field.
3727 : An error was reported by the HDF5 layer.
3732 This example is from nf\_test/fst\_types.F.
3737 C Check the first field of the compound type.
3738 retval = nf_inq_compound_field(ncid, typeids(1), 1, name_in,
3739 & offset_in, field_typeid_in, ndims_in, dim_sizes_in)
3740 if (retval .ne. nf_noerr) call handle_err(retval)
3741 if (name_in(1:len(u_name)) .ne. u_name .or. offset_in .ne. 0 .or.
3742 & field_typeid_in .ne. NF_INT .or. ndims_in .ne. 0) stop 2
3743 retval = nf_inq_compound_fieldname(ncid, typeids(1), 1, name_in)
3744 if (retval .ne. nf_noerr) call handle_err(retval)
3745 if (name_in(1:len(u_name)) .ne. u_name) stop 2
3746 retval = nf_inq_compound_fieldoffset(ncid, typeids(1), 1,
3748 if (retval .ne. nf_noerr) call handle_err(retval)
3749 if (offset_in .ne. 0) stop 2
3750 retval = nf_inq_compound_fieldtype(ncid, typeids(1), 1,
3752 if (retval .ne. nf_noerr) call handle_err(retval)
3753 if (field_typeid_in .ne. NF_INT) stop 2
3754 retval = nf_inq_compound_fieldndims(ncid, typeids(1), 1,
3756 if (retval .ne. nf_noerr) call handle_err(retval)
3757 if (ndims_in .ne. 0) stop 2
3760 5.7 Variable Length Array Introduction
3761 --------------------------------------
3763 NetCDF-4 addedpport for a variable length array type. This is not
3764 supported in classic or 64-bit offset files, or in netCDF-4 files which
3765 were created with the NF\_CLASSIC\_MODEL flag.
3767 A variable length array is represented in C as a structure from HDF5,
3768 the nf\_vlen\_t structure. It contains a len member, which contains the
3769 length of that array, and a pointer to the array.
3771 So an array of VLEN in C is an array of nc\_vlen\_t structures. The only
3772 way to handle this in Fortran is with a character buffer sized correctly
3775 The extra access functions NF\_GET\_VLEN\_ELEMENT and
3776 NF\_PUT\_VLEN\_ELEMENT to get and put one VLEN element. (That is, one
3777 array of variable length.) When calling the put, the data are not copied
3778 from the source. When calling the get the data are copied from VLEN
3779 allocated memory, which must still be freed (see below).
3781 VLEN arrays are handled differently with respect to allocation of
3782 memory. Generally, when reading data, it is up to the user to malloc
3783 (andbsequently free) the memory needed to hold the data. It is up to
3784 the user to ere that enough memory is allocated.
3786 With VLENs, this is impossible. The user cannot know the size of an
3787 array of VLEN until after reading the array. Therefore when reading VLEN
3788 arrays, the netCDF library will allocate the memory for the data within
3791 It is up to the user, however, to eventually free this memory. This is
3792 not just a matter of one call to free, with the pointer to the array of
3793 VLENs; each VLEN contains a pointer which must be freed.
3795 Compression is permitted but may not be effective for VLEN data, because
3796 the compression is applied to the nc\_vlen\_t structures, rather than
3799 ### 5.7.1 Define a Variable Length Array (VLEN): NF\_DEF\_VLEN
3801 Use this function to define a variable length array type.
3809 INTEGER FUNCTION NF_DEF_VLEN(INTEGER NCID, CHARACTER*(*) NAME,
3810 INTEGER BASE_TYPEID, INTEGER XTYPEP)
3814 : The ncid of the file to create the VLEN type in.
3817 : A name for the VLEN type.
3820 : The typeid of the base type of the VLEN. For example, for a VLEN of
3821 shorts, the base type is NF\_SHORT. This can be a user defined type.
3824 : The typeid of the new VLEN type will be set here.
3833 : NF\_MAX\_NAME exceeded.
3836 : Name is already in use.
3839 : Attribute or variable name contains illegal characters.
3845 : Group ID part of ncid was invalid.
3856 This example is from nf\_test/ftst\_vars4.F.
3861 C Create the vlen type.
3862 retval = nf_def_vlen(ncid, vlen_type_name, nf_int, vlen_typeid)
3863 if (retval .ne. nf_noerr) call handle_err(retval)
3866 ### 5.7.2 Learning about a Variable Length Array (VLEN) Type: NF\_INQ\_VLEN
3868 Use this type to learn about a vlen.
3876 INTEGER FUNCTION NF_INQ_VLEN(INTEGER NCID, INTEGER XTYPE,
3877 CHARACTER*(*) NAME, INTEGER DATUM_SIZEP, INTEGER
3882 : The ncid of the file that contains the VLEN type.
3885 : The type of the VLEN to inquire about.
3888 : The name of the VLEN type. The name will be NF\_MAX\_NAME characters
3892 : A pointer to a size\_t, this will get the size of one element of
3896 : An integer that will get the type of the VLEN base type. (In other
3897 words, what type is this a VLEN of?)
3906 : Can’t find the typeid.
3912 : Group ID part of ncid was invalid.
3917 This example is from nf\_test/ftst\_vars4.F.
3922 C Use nf_inq_vlen and makere we get the same answers as we did
3923 C with nf_inq_user_type.
3924 retval = nf_inq_vlen(ncid, typeids(1), type_name, base_size,
3926 if (retval .ne. nf_noerr) call handle_err(retval)
3929 ### 5.7.3 Releasing Memory for a Variable Length Array (VLEN) Type: NF\_FREE\_VLEN
3931 When a VLEN is read into user memory from the file, the HDF5 library
3932 performs memory allocations for each of the variable length arrays
3933 contained within the VLEN structure. This memory must be freed by the
3934 user to avoid memory leaks.
3936 This violates the normal netCDF expectation that the user is responsible
3937 for all memory allocation. But, with VLEN arrays, the underlying HDF5
3938 library allocates the memory for the user, and the user is responsible
3939 for deallocating that memory.
3947 INTEGER FUNCTION NF_FREE_VLEN(CHARACTER VL);
3951 : The variable length array structure which is to be freed.
3960 : Can’t find the typeid.
3965 ### 5.7.4 Set a Variable Length Array with NF\_PUT\_VLEN\_ELEMENT
3967 Use this to set the element of the (potentially) n-dimensional array of
3968 VLEN. That is, this sets the data in one variable length array.
3976 INTEGER FUNCTION NF_PUT_VLEN_ELEMENT(INTEGER NCID, INTEGER XTYPE,
3977 CHARACTER*(*) VLEN_ELEMENT, INTEGER LEN, DATA)
3981 : The ncid of the file that contains the VLEN type.
3984 : The type of the VLEN.
3987 : The VLEN element to be set.
3990 : The number of entries in this array.
3993 : The data to be stored. Must match the base type of this VLEN.
4002 : Can’t find the typeid.
4008 : Group ID part of ncid was invalid.
4013 This example is from nf\_test/ftst\_vars4.F.
4018 C Set up the vlen with this helper function, since F77 can't deal
4020 retval = nf_put_vlen_element(ncid, vlen_typeid, vlen,
4022 if (retval .ne. nf_noerr) call handle_err(retval)
4025 ### 5.7.5 Set a Variable Length Array with NF\_GET\_VLEN\_ELEMENT
4027 Use this to set the element of the (potentially) n-dimensional array of
4028 VLEN. That is, this sets the data in one variable length array.
4036 INTEGER FUNCTION NF_GET_VLEN_ELEMENT(INTEGER NCID, INTEGER XTYPE,
4037 CHARACTER*(*) VLEN_ELEMENT, INTEGER LEN, DATA)
4041 : The ncid of the file that contains the VLEN type.
4044 : The type of the VLEN.
4047 : The VLEN element to be set.
4050 : This will be set to the number of entries in this array.
4053 : The data will be copied here. Sufficient storage must be available
4054 or bad things will happen to you.
4063 : Can’t find the typeid.
4069 : Group ID part of ncid was invalid.
4074 This example is from nf\_test/ftst\_vars4.F.
4079 C Read the vlen attribute.
4080 retval = nf_get_att(ncid, NF_GLOBAL, 'att1', vlen_in)
4081 if (retval .ne. nf_noerr) call handle_err(retval)
4083 C Get the data from the vlen we just read.
4084 retval = nf_get_vlen_element(ncid, vlen_typeid, vlen_in,
4085 & vlen_len_in, data1_in)
4086 if (retval .ne. nf_noerr) call handle_err(retval)
4089 5.8 Opaque Type Introduction
4090 ----------------------------
4092 NetCDF-4 addedpport for the opaque type. This is notpported in
4093 classic or 64-bit offset files.
4095 The opaque type is a type which is a collection of objects of a known
4096 size. (And each object is the same size). Nothing is known to netCDF
4097 about the contents of these blobs of data, except their size in bytes,
4098 and the name of the type.
4100 To use an opaque type, first define it with [Creating Opaque Types:
4101 NF\_DEF\_OPAQUE](#NF_005fDEF_005fOPAQUE). If encountering an enum type
4102 in a new data file, use [Learn About an Opaque Type:
4103 NF\_INQ\_OPAQUE](#NF_005fINQ_005fOPAQUE) to learn its name and size.
4105 ### 5.8.1 Creating Opaque Types: NF\_DEF\_OPAQUE
4107 Create an opaque type. Provide a size and a name.
4115 INTEGER FUNCTION NF_DEF_OPAQUE(INTEGER NCID, INTEGER SIZE,
4116 CHARACTER*(*) NAME, INTEGER TYPEIDP)
4120 : The groupid where the type will be created. The type may be used
4121 anywhere in the file, no matter what group it is in.
4124 : The size of each opaque object.
4127 : The name for this type. Must be shorter than NF\_MAX\_NAME.
4130 : Pointer where the new typeid for this type is returned. Use this
4131 typeid when defining variables of this type with [Create a Variable:
4132 `NF_DEF_VAR`](#NF_005fDEF_005fVAR).
4147 : An error was reported by the HDF5 layer.
4152 This example is from nf\_test/ftst\_vars3.F.
4157 C Create the opaque type.
4158 retval = nf_def_opaque(ncid, opaque_size, opaque_type_name,
4160 if (retval .ne. nf_noerr) call handle_err(retval)
4163 ### 5.8.2 Learn About an Opaque Type: NF\_INQ\_OPAQUE
4165 Given a typeid, get the information about an opaque type.
4173 INTEGER FUNCTION NF_INQ_OPAQUE(INTEGER NCID, INTEGER XTYPE,
4174 CHARACTER*(*) NAME, INTEGER SIZEP)
4178 : The ncid for the group containing the opaque type.
4181 : The typeid for this opaque type, as returned by NF\_DEF\_COMPOUND,
4185 : The name of the opaque type will be copied here. It will be
4186 NF\_MAX\_NAME bytes or less.
4189 : The size of the opaque type will be copied here.
4204 : An error was reported by the HDF5 layer.
4209 This example is from nf\_test/ftst\_vars3.F.
4214 C Use nf_inq_opaque and makere we get the same answers as we did
4215 C with nf_inq_user_type.
4216 retval = nf_inq_opaque(ncid, typeids(2), type_name, base_size)
4217 if (retval .ne. nf_noerr) call handle_err(retval)
4220 5.9 Enum Type Introduction
4221 --------------------------
4223 NetCDF-4 addedpport for the enum type. This is notpported in
4224 classic or 64-bit offset files.
4226 ### 5.9.1 Creating a Enum Type: NF\_DEF\_ENUM
4228 Create an enum type. Provide an ncid, a name, and a base integer type.
4230 After calling this function, fill out the type with repeated calls to
4231 NF\_INSERT\_ENUM (see [Inserting a Field into a Enum Type:
4232 NF\_INSERT\_ENUM](#NF_005fINSERT_005fENUM)). Call NF\_INSERT\_ENUM once
4233 for each value you wish to make part of the enumeration.
4241 INTEGER FUNCTION NF_DEF_ENUM(INTEGER NCID, INTEGER BASE_TYPEID,
4242 CHARACTER*(*) NAME, INTEGER TYPEIDP)
4246 : The groupid where this compound type will be created.
4249 : The base integer type for this enum. Must be one of: NF\_BYTE,
4250 NF\_UBYTE, NF\_SHORT, NF\_USHORT, NF\_INT, NF\_UINT, NF\_INT64,
4254 : The name of the new enum type.
4257 : The typeid of the new type will be placed here.
4269 : That name is in use. Compound type names must be unique in the data
4273 : Name exceeds max length NF\_MAX\_NAME.
4276 : Name contains illegal characters.
4279 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
4280 operations can only be performed on files defined with a create mode
4281 which includes flag NF\_NETCDF4. (see
4282 [NF\_OPEN](#NF_005fOPEN)).
4285 : This file was created with the strict netcdf-3 flag, therefore
4286 netcdf-4 operations are not allowed. (see
4287 [NF\_OPEN](#NF_005fOPEN)).
4290 : An error was reported by the HDF5 layer.
4293 : Attempt to write to a read-only file.
4296 : Not in define mode.
4298 This example is from nf\_test/ftst\_vars3.F.
4303 C Create the enum type.
4304 retval = nf_def_enum(ncid, NF_INT, enum_type_name, enum_typeid)
4305 if (retval .ne. nf_noerr) call handle_err(retval)
4308 ### 5.9.2 Inserting a Field into a Enum Type: NF\_INSERT\_ENUM
4310 Insert a named member into a enum type.
4318 INTEGER FUNCTION NF_INSERT_ENUM(INTEGER NCID, INTEGER XTYPE,
4319 CHARACTER IDENTIFIER, INTEGER VALUE)
4323 : The ncid of the group which contains the type.
4326 : The typeid for this enum type, as returned by nf\_def\_enum, or
4330 : The identifier of the new member.
4333 : The value that is to be associated with this member.
4345 : That name is in use. Field names must be unique within a enum type.
4348 : Name exceed max length NF\_MAX\_NAME.
4351 : Name contains illegal characters.
4354 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
4355 operations can only be performed on files defined with a create mode
4356 which includes flag NF\_NETCDF4. (see
4357 [NF\_OPEN](#NF_005fOPEN)).
4360 : This file was created with the strict netcdf-3 flag, therefore
4361 netcdf-4 operations are not allowed. (see
4362 [NF\_OPEN](#NF_005fOPEN)).
4365 : An error was reported by the HDF5 layer.
4368 : Not in define mode.
4373 This example is from nf\_test/ftst\_vars3.F.
4380 retval = nf_insert_enum(ncid, enum_typeid, zero_name, zero)
4381 if (retval .ne. nf_noerr) call handle_err(retval)
4382 retval = nf_insert_enum(ncid, enum_typeid, one_name, one)
4383 if (retval .ne. nf_noerr) call handle_err(retval)
4386 ### 5.9.3 Learn About a Enum Type: NF\_INQ\_ENUM
4388 Get information about a user-defined enumeration type.
4396 INTEGER FUNCTION NF_INQ_ENUM(INTEGER NCID, INTEGER XTYPE,
4397 CHARACTER*(*) NAME, INTEGER BASE_NF_TYPE, INTEGER BASE_SIZE,
4398 INTEGER NUM_MEMBERS)
4402 : The group ID of the group which holds the enum type.
4405 : The typeid for this enum type, as returned by NF\_DEF\_ENUM, or
4409 : Character array which will get the name. It will have a maximum
4410 length of NF\_MAX\_NAME.
4413 : An integer which will get the base integer type of this enum.
4416 : An integer which will get the size (in bytes) of the base integer
4420 : An integer which will get the number of members defined for this
4433 : An error was reported by the HDF5 layer.
4438 In this example from nf\_test/ftst\_vars3.F, an enum type is created and
4444 retval = nf_inq_enum(ncid, typeids(1), type_name, base_type,
4445 & base_size, num_members)
4446 if (retval .ne. nf_noerr) call handle_err(retval)
4447 if (base_type .ne. NF_INT .or. num_members .ne. 2) stop 2
4450 ### 5.9.4 Learn the Name of a Enum Type: nf\_inq\_enum\_member
4452 Get information about a member of an enum type.
4460 INTEGER FUNCTION NF_INQ_ENUM_MEMBER(INTEGER NCID, INTEGER XTYPE,
4461 INTEGER IDX, CHARACTER*(*) NAME, INTEGER VALUE)
4465 : The groupid where this enum type exists.
4468 : The typeid for this enum type.
4471 : The one-based index number for the member of interest.
4474 : A character array which will get the name of the member. It will
4475 have a maximum length of NF\_MAX\_NAME.
4478 : An integer that will get the value associated with this member.
4490 : An error was reported by the HDF5 layer.
4495 This example is from nf\_test/ftst\_vars3.F:
4500 C Check the members of the enum type.
4501 retval = nf_inq_enum_member(ncid, typeids(1), 1, member_name,
4503 if (retval .ne. nf_noerr) call handle_err(retval)
4504 if (member_name(1:len(zero_name)) .ne. zero_name .or.
4505 & member_value .ne. 0) stop 2
4506 retval = nf_inq_enum_member(ncid, typeids(1), 2, member_name,
4508 if (retval .ne. nf_noerr) call handle_err(retval)
4509 if (member_name(1:len(one_name)) .ne. one_name .or.
4510 & member_value .ne. 1) stop 2
4513 ### 5.9.5 Learn the Name of a Enum Type: NF\_INQ\_ENUM\_IDENT
4515 Get the name which is associated with an enum member value.
4517 This is similar to NF\_INQ\_ENUM\_MEMBER, but instead of using the index
4518 of the member, you use the value of the member.
4526 INTEGER FUNCTION NF_INQ_ENUM_IDENT(INTEGER NCID, INTEGER XTYPE,
4527 INTEGER VALUE, CHARACTER*(*) IDENTIFIER)
4531 : The groupid where this enum type exists.
4534 : The typeid for this enum type.
4537 : The value for which an identifier is sought.
4540 : A character array that will get the identifier. It will have a
4541 maximum length of NF\_MAX\_NAME.
4550 : Bad type id, or not an enum type.
4553 : An error was reported by the HDF5 layer.
4556 : The value was not found in the enum.
4561 In this example from nf\_test/ftst\_vars3.F, the values for 0 and 1 are
4567 retval = nf_inq_enum_ident(ncid, typeids(1), 0, member_name)
4568 if (retval .ne. nf_noerr) call handle_err(retval)
4569 if (member_name(1:len(zero_name)) .ne. zero_name) stop 2
4570 retval = nf_inq_enum_ident(ncid, typeids(1), 1, member_name)
4571 if (retval .ne. nf_noerr) call handle_err(retval)
4572 if (member_name(1:len(one_name)) .ne. one_name) stop 2
4578 6.1 Variables Introduction
4579 --------------------------
4581 Variables for a netCDF dataset are defined when the dataset is created,
4582 while the netCDF dataset is in define mode. Other variables may be added
4583 later by reentering define mode. A netCDF variable has a name, a type,
4584 and a shape, which are specified when it is defined. A variable may also
4585 have values, which are established later in data mode.
4587 Ordinarily, the name, type, and shape are fixed when the variable is
4588 first defined. The name may be changed, but the type and shape of a
4589 variable cannot be changed. However, a variable defined in terms of the
4590 unlimited dimension can grow without bound in that dimension.
4592 A netCDF variable in an open netCDF dataset is referred to by a small
4593 integer called a variable ID.
4595 Variable IDs reflect the order in which variables were defined within a
4596 netCDF dataset. Variable IDs are 1, 2, 3,..., in the order in which the
4597 variables were defined. A function is available for getting the variable
4598 ID from the variable name and vice-versa.
4600 Attributes (see [Attributes](#Attributes)) may be associated with a
4601 variable to specifych properties as units.
4603 Operationspported on variables are:
4605 - Create a variable, given its name, data type, and shape.
4606 - Get a variable ID from its name.
4607 - Get a variable’s name, data type, shape, and number of attributes
4609 - Put a data value into a variable, given variable ID, indices, and
4611 - Put an array of values into a variable, given variable ID, corner
4612 indices, edge lengths, and a block of values.
4613 - Put absampled or mapped array of values into a variable,
4614 given variable ID, corner indices, edge lengths, stride vector,
4615 index mapping vector, and a block of values.
4616 - Get a data value from a variable, given variable ID and indices.
4617 - Get an array of values from a variable, given variable ID, corner
4618 indices, and edge lengths.
4619 - Get absampled or mapped array of values from a variable,
4620 given variable ID, corner indices, edge lengths, stride vector, and
4621 index mapping vector.
4622 - Rename a variable.
4625 6.2 Language Types Corresponding to netCDF external data types
4626 --------------------------------------------------------------
4628 The following table gives the netCDF external data types and the
4629 corresponding type constants for defining variables in the FORTRAN
4632 -------- ---------------------- ------
4633 Type FORTRAN API Mnemonic Bits
4639 double NF\_DOUBLE 64
4640 -------- ---------------------- ------
4642 The first column gives the netCDF external data type, which is the same
4643 as the CDL data type. The next column gives the corresponding FORTRAN
4644 parameter for use in netCDF functions (the parameters are defined in the
4645 netCDF FORTRAN include-file netcdf.inc). The last column gives the
4646 number of bits used in the external representation of values of the
4649 Note that there are no netCDF types corresponding to 64-bit integers or
4650 to characters wider than 8 bits in the current version of the netCDF
4653 6.3 Create a Variable: `NF_DEF_VAR`
4654 -----------------------------------
4656 The function NF\_DEF\_VAR adds a new variable to an open netCDF dataset
4657 in define mode. It returns (as an argument) a variable ID, given the
4658 netCDF ID, the variable name, the variable type, the number of
4659 dimensions, and a list of the dimension IDs.
4667 INTEGER FUNCTION NF_DEF_VAR(INTEGER NCID, CHARACTER*(*) NAME,
4668 INTEGER XTYPE, INTEGER NVDIMS,
4669 INTEGER VDIMS(*), INTEGER varid)
4673 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4679 : One of the set of predefined netCDF external data types. The type of
4680 this parameter, NF\_TYPE, is defined in the netCDF header file. The
4681 valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
4682 NF\_INT, NF\_FLOAT, and NF\_DOUBLE. If the file is a NetCDF-4/HDF5
4683 file, the additional types NF\_UBYTE, NF\_USHORT, NF\_UINT,
4684 NF\_INT64, NF\_UINT64, and NF\_STRING may be used, as well as a user
4688 : Number of dimensions for the variable. For example, 2 specifies a
4689 matrix, 1 specifies a vector, and 0 means the variable is a scalar
4690 with no dimensions. Must not be negative or greater than the
4691 predefined constant NF\_MAX\_VAR\_DIMS.
4694 : Vector of ndims dimension IDs corresponding to the variable
4695 dimensions. If the ID of the unlimited dimension is included, it
4696 must be first. This argument is ignored if ndims is 0. For expanded
4697 model netCDF4/HDF5 files, there may be any number of unlimited
4698 dimensions, and they may be used in any element of the dimids array.
4701 : Returned variable ID.
4706 NF\_DEF\_VAR returns the value NF\_NOERR if no errors occurred.
4707 Otherwise, the returned status indicates an error. Possible causes of
4710 - The netCDF dataset is not in define mode.
4711 - The specified variable name is the name of another existing
4713 - The specified type is not a valid netCDF type.
4714 - The specified number of dimensions is negative or more than the
4715 constant NF\_MAX\_VAR\_DIMS, the maximum number of dimensions
4716 permitted for a netCDF variable.
4717 - One or more of the dimension IDs in the list of dimensions is not a
4718 valid dimension ID for the netCDF dataset.
4719 - The number of variables would exceed the constant NF\_MAX\_VARS, the
4720 maximum number of variables permitted in a netCDF dataset.
4721 - The specified netCDF ID does not refer to an open netCDF dataset.
4726 Here is an example using NF\_DEF\_VAR to create a variable named rh of
4727 type double with three dimensions, time, lat, and lon in a new netCDF
4728 dataset named foo.nc:
4733 INCLUDE 'netcdf.inc'
4735 INTEGER STATUS, NCID
4736 INTEGER LATDIM, LONDIM, TIMDIM ! dimension IDs
4737 INTEGER RHID ! variable ID
4738 INTEGER RHDIMS(3) ! variable shape
4740 STATUS = NF_CREATE ('foo.nc', NF_NOCLOBBER, NCID)
4741 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4744 STATUS = NF_DEF_DIM(NCID, 'lat', 5, LATDIM)
4745 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4746 STATUS = NF_DEF_DIM(NCID, 'lon', 10, LONDIM)
4747 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4748 STATUS = NF_DEF_DIM(NCID, 'time', NF_UNLIMITED, TIMDIM)
4749 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4755 STATUS = NF_DEF_VAR (NCID, 'rh', NF_DOUBLE, 3, RHDIMS, RHID)
4756 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4759 6.4 Define Chunking Parameters for a Variable: `NF_DEF_VAR_CHUNKING`
4760 --------------------------------------------------------------------
4762 The function NF\_DEF\_VAR\_CHUNKING sets the storage parameters for a
4763 variable in a netCDF-4 file. It can set the chunk sizes to get chunked
4764 storage, or it can set the contiguous flag to get contiguous storage.
4766 Variables that make use of one or more unlimited dimensions,
4767 compression, or checms must use chunking. Such variables are created
4768 with default chunk sizes of 1 for each unlimited dimension and the
4769 dimension length for other dimensions, except that if the rlting
4770 chunks are too large, the default chunk sizes for non-record dimensions
4773 The total size of a chunk must be less than 4 GiB. That is, the product
4774 of all chunksizes and the size of the data (or the size of nc\_vlen\_t
4775 for VLEN types) must be less than 4 GiB.
4777 This function may only be called after the variable is defined, but
4778 before nc\_enddef is called. Once the chunking parameters are set for a
4779 variable, they cannot be changed. This function can be used to change
4780 the default chunking for record, compressed, or checmmed variables
4781 before nc\_enddef is called.
4783 Note that you cannot set chunking for scalar variables. Only non-scalar
4784 variables can have chunking.
4792 NF_DEF_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES)
4796 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4802 : If NF\_CONTIGUOUS, then contiguous storage is used for this
4803 variable. Variables with compression, shuffle filter, checms, or
4804 one or more unlimited dimensions cannot use contiguous storage. If
4805 contiguous storage is turned on, the chunksizes parameter is
4808 If NF\_CHUNKED, then chunked storage is used for this variable.
4809 Chunk sizes may be specified with the chunksizes parameter. Default
4810 sizes will be used if chunking is required and this function is not
4813 By default contiguous storage is used for fix-sized variables when
4814 conpression, chunking, checms, or endianness control are not
4818 : An array of chunk sizes. The array must have the one chunksize for
4819 each dimension in the variable. If contiguous storage is used, then
4820 the chunksizes parameter is ignored.
4825 NF\_DEF\_VAR\_CHUNKING returns the value NF\_NOERR if no errors
4826 occurred. Otherwise, the returned status indicates an error.
4828 Possible return codes include:
4837 : Invalid input. This can occur when the user attempts to set
4838 contiguous storage for a variable with compression or checms, or
4839 one or more unlimited dimensions.
4842 : Not a netCDF-4 file.
4845 : Can’t find this variable.
4848 : This variable has already been thebject of a NF\_ENDDEF call. In
4849 netCDF-4 files NF\_ENDDEF will be called automatically for any data
4850 read or write. Once enddef has been called, it is impossible to set
4851 the chunking for a variable.
4854 : Not in define mode. This is returned for netCDF classic or 64-bit
4855 offset files, or for netCDF-4 files, when they were been created
4856 with NF\_STRICT\_NC3 flag. (see
4857 [NF\_CREATE](#NF_005fCREATE)).
4860 : Trying to create a var some place other than the root group in a
4861 netCDF file with NF\_STRICT\_NC3 turned on.
4866 In this example from nf\_test/ftst\_vars.F, a file is created, two
4867 dimensions and a variable are defined, and the chunksizes of the data
4868 are set to the size of the data (that is, data will be written in one
4874 C Create the netCDF file.
4875 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
4876 if (retval .ne. nf_noerr) call handle_err(retval)
4878 C Define the dimensions.
4879 retval = nf_def_dim(ncid, "x", NX, x_dimid)
4880 if (retval .ne. nf_noerr) call handle_err(retval)
4881 retval = nf_def_dim(ncid, "y", NY, y_dimid)
4882 if (retval .ne. nf_noerr) call handle_err(retval)
4884 C Define the variable.
4887 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
4888 if (retval .ne. nf_noerr) call handle_err(retval)
4893 retval = NF_DEF_VAR_chunking(ncid, varid, NF_CHUNKED, chunks)
4894 if (retval .ne. nf_noerr) call handle_err(retval)
4897 6.5 Learn About Chunking Parameters for a Variable: `NF_INQ_VAR_CHUNKING`
4898 -------------------------------------------------------------------------
4900 The function NF\_INQ\_VAR\_CHUNKING returns the chunking settings for a
4901 variable in a netCDF-4 file.
4909 NF_INQ_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES);
4913 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4919 : On return, set to NF\_CONTIGUOUS if this variable uses contiguous
4920 storage, NF\_CHUNKED if it uses chunked storage.
4923 : An array of chunk sizes. The length of CHUNKSIZES must be the same
4924 as the number of dimensions of the variable.
4929 NF\_INQ\_VAR\_CHUNKING returns the value NF\_NOERR if no errors
4930 occurred. Otherwise, the returned status indicates an error.
4932 Possible return codes include:
4941 : Not a netCDF-4 file.
4944 : Can’t find this variable.
4949 In this example from nf\_test/ftst\_vars.F, a variable with chunked
4950 storage is checked to ere that the chunksizes are set to expected
4956 C Is everything set that ispposed to be?
4957 retval = nf_inq_var_chunking(ncid, varid, storage, chunks_in)
4958 if (retval .ne. nf_noerr) call handle_err(retval)
4959 if (storage .ne. NF_CHUNKED) stop 2
4960 if (chunks(1) .ne. chunks_in(1)) stop 2
4961 if (chunks(2) .ne. chunks_in(2)) stop 2
4964 6.6 Set HDF5 Chunk Cache for a Variable: NF\_SET\_VAR\_CHUNK\_CACHE
4965 -------------------------------------------------------------------
4967 This function changes the chunk cache settings for a variable. The
4968 change in cache size happens immediately. This is a property of the open
4969 file - it does not persist the next time you open the file.
4971 For more information, see the documentation for the H5Pset\_cache()
4972 function in the HDF5 library at the HDF5 website:
4973 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
4981 NF_SET_VAR_CHUNK_CACHE(INTEGER NCID, INTEGER VARID, INTEGER SIZE, INTEGER NELEMS,
4982 INTEGER PREEMPTION);
4986 : NetCDF ID, from a previous call to nc\_open or nc\_create.
4992 : The total size of the raw data chunk cache, in megabytes. This
4993 should be big enough to hold multiple chunks of data. (Note that the
4994 C API uses bytes, but the Fortran APIs uses megabytes to avoid
4995 numbers that can’t fit in 4-byte integers.)
4998 : The number of chunk slots in the raw data chunk cache hash table.
4999 This should be a prime number larger than the number of chunks that
5000 will be in the cache.
5003 : The preemption value must be between 0 and 100 inclusive and
5004 indicates the degreee to which chunks that have been fully read are
5005 favored for kicking out of the chunk cache, when needed. A value of
5006 zero means fully read chunks are treated no differently than other
5007 chunks (the preemption is strictly Least Recently Used) while a
5008 value of 100 means fully read chunks are always preempted before
5009 other chunks. (The C API uses a float between 0 and 1 for this
5019 : Preemption must be between zero and 100 (inclusive).
5024 This example is from nf\_test/ftst\_vars2.F:
5029 include 'netcdf.inc'
5031 C These will be used to set the per-variable chunk cache.
5032 integer CACHE_SIZE, CACHE_NELEMS, CACHE_PREEMPTION
5033 parameter (CACHE_SIZE = 8, CACHE_NELEMS = 571)
5034 parameter (CACHE_PREEMPTION = 42)
5036 C Set variable caches.
5037 retval = nf_set_var_chunk_cache(ncid, varid(i), CACHE_SIZE,
5038 & CACHE_NELEMS, CACHE_PREEMPTION)
5039 if (retval .ne. nf_noerr) call handle_err(retval)
5042 6.7 Get the HDF5 Chunk Cache Settings for a variable: NF\_GET\_VAR\_CHUNK\_CACHE
5043 --------------------------------------------------------------------------------
5045 This function gets the current chunk cache settings for a variable in a
5048 For more information, see the documentation for the H5Pget\_cache()
5049 function in the HDF5 library at the HDF5 website:
5050 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
5058 INTEGER NF_GET_VAR_CHUNK_CACHE(INTEGER NCID, INTEGER VARID, INTEGER SIZE, INTEGER NELEMS,
5059 INTEGER PREEMPTION);
5063 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5069 : The total size of the raw data chunk cache, in megabytes, will be
5073 : The number of chunk slots in the raw data chunk cache hash table
5077 : The preemption will be put here. The preemtion value is between 0
5078 and 100 inclusive and indicates how much chunks that have been fully
5079 read are favored for preemption. A value of zero means fully read
5080 chunks are treated no differently than other chunks (the preemption
5081 is strictly LRU) while a value of 100 means fully read chunks are
5082 always preempted before other chunks.
5093 This example is from nf\_test/ftst\_vars2.c:
5098 include 'netcdf.inc'
5100 C These will be used to set the per-variable chunk cache.
5101 integer CACHE_SIZE, CACHE_NELEMS, CACHE_PREEMPTION
5102 parameter (CACHE_SIZE = 8, CACHE_NELEMS = 571)
5103 parameter (CACHE_PREEMPTION = 42)
5105 C These will be used to check the setting of the per-variable chunk
5107 integer cache_size_in, cache_nelems_in, cache_preemption_in
5110 retval = nf_get_var_chunk_cache(ncid, varid(i), cache_size_in,
5111 & cache_nelems_in, cache_preemption_in)
5112 if (retval .ne. nf_noerr) call handle_err(retval)
5113 if (cache_size_in .ne. CACHE_SIZE .or. cache_nelems_in .ne.
5114 & CACHE_NELEMS .or. cache_preemption .ne. CACHE_PREEMPTION)
5118 6.8 Define Fill Parameters for a Variable: `nf_def_var_fill`
5119 ------------------------------------------------------------
5121 The function NF\_DEF\_VAR\_FILL sets the fill parameters for a variable
5124 This function must be called after the variable is defined, but before
5125 NF\_ENDDEF is called.
5133 NF_DEF_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE);
5137 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5143 : Set to non-zero value to set no\_fill mode on a variable. When this
5144 mode is on, fill values will not be written for the variable. This
5145 is helpful in high performance applications. For netCDF-4/HDF5 files
5146 (whether classic model or not), this may only be changed after the
5147 variable is defined, but before it is committed to disk (i.e. before
5148 the first NF\_ENDDEF after the NF\_DEF\_VAR.) For classic and 64-bit
5149 offset file, the no\_fill mode may be turned on and off at any time.
5152 : A value which will be used as the fill value for the variable. Must
5153 be the same type as the variable. This will be written to a
5154 \_FillValue attribute, created for this purpose. If NULL, this
5155 argument will be ignored.
5167 : Not a netCDF-4 file.
5170 : Can’t find this variable.
5173 : This variable has already been thebject of a NF\_ENDDEF call. In
5174 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5175 read or write. Once enddef has been called, it is impossible to set
5176 the fill for a variable.
5179 : Not in define mode. This is returned for netCDF classic or 64-bit
5180 offset files, or for netCDF-4 files, when they were been created
5181 with NF\_STRICT\_NC3 flag. (see
5182 [NF\_CREATE](#NF_005fCREATE)).
5185 : Attempt to create object in read-only file.
5190 6.9 Learn About Fill Parameters for a Variable: `NF_INQ_VAR_FILL`
5191 -----------------------------------------------------------------
5193 The function NF\_INQ\_VAR\_FILL returns the fill settings for a variable
5202 NF_INQ_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE)
5206 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5212 : An integer which will get a 1 if no\_fill mode is set for this
5213 variable, and a zero if it is not set
5216 : This will get the fill value for this variable. This parameter will
5217 be ignored if it is NULL.
5229 : Not a netCDF-4 file.
5232 : Can’t find this variable.
5237 6.10 Define Compression Parameters for a Variable: `NF_DEF_VAR_DEFLATE`
5238 -----------------------------------------------------------------------
5240 The function NF\_DEF\_VAR\_DEFLATE sets the deflate parameters for a
5241 variable in a netCDF-4 file.
5243 When using parallel I/O for writing data, deflate cannot be used. This
5244 is because the compression makes it impossible for the HDF5 library to
5245 exactly map the data to disk location.
5247 (Deflated data can be read with parallel I/O).
5249 NF\_DEF\_VAR\_DEFLATE must be called after the variable is defined, but
5250 before NF\_ENDDEF is called.
5258 NF_DEF_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE, INTEGER DEFLATE,
5259 INTEGER DEFLATE_LEVEL);
5263 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5269 : If non-zero, turn on the shuffle filter.
5272 : If non-zero, turn on the deflate filter at the level specified by
5273 the deflate\_level parameter.
5276 : Must be between 0 (no deflate, the default) and 9 (slowest, but
5279 If set to zero, no deflation takes place and the def\_var\_deflate
5280 call is ignored. This is slightly different from HDF5 handing of 0
5281 deflate, which turns on the filter but makes only trivial changes to
5284 Informal testing at NetCDF World Headquartersggests that there is
5285 little to be gained (with the limited set of test data used here),
5286 in setting the deflate level above 2 or 3.
5291 NF\_DEF\_VAR\_DEFLATE returns the value NF\_NOERR if no errors occurred.
5292 Otherwise, the returned status indicates an error.
5294 Possible return codes include:
5303 : Not a netCDF-4 file.
5306 : Can’t find this variable.
5309 : This variable has already been thebject of a NF\_ENDDEF call. In
5310 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5311 read or write. Once enddef has been called, it is impossible to set
5312 the deflate for a variable.
5315 : Not in define mode. This is returned for netCDF classic or 64-bit
5316 offset files, or for netCDF-4 files, when they were been created
5317 with NF\_STRICT\_NC3 flag. (see
5318 [NF\_CREATE](#NF_005fCREATE)).
5321 : Attempt to create object in read-only file.
5324 : Invalid deflate\_level. The deflate level must be between 0 and 9,
5330 In this example from nf\_test/ftst\_vars.F, a file is created with two
5331 dimensions and one variable. Chunking, deflate, and the fletcher32
5332 filter are turned on. The deflate level is set to 4 below.
5337 C Create the netCDF file.
5338 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5339 if (retval .ne. nf_noerr) call handle_err(retval)
5341 C Define the dimensions.
5342 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5343 if (retval .ne. nf_noerr) call handle_err(retval)
5344 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5345 if (retval .ne. nf_noerr) call handle_err(retval)
5347 C Define the variable.
5350 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5351 if (retval .ne. nf_noerr) call handle_err(retval)
5356 retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
5357 if (retval .ne. nf_noerr) call handle_err(retval)
5359 C Turn on deflate compression, fletcher32 checm.
5360 retval = NF_DEF_VAR_deflate(ncid, varid, 0, 1, 4)
5361 if (retval .ne. nf_noerr) call handle_err(retval)
5362 retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
5363 if (retval .ne. nf_noerr) call handle_err(retval)
5366 6.11 Learn About Deflate Parameters for a Variable: `NF_INQ_VAR_DEFLATE`
5367 ------------------------------------------------------------------------
5369 The function NF\_INQ\_VAR\_DEFLATE returns the deflate settings for a
5370 variable in a netCDF-4 file.
5372 It is not necessary to know the deflate settings to read the variable.
5373 (Deflate is completely transparent to readers of the data).
5381 NF_INQ_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE,
5382 INTEGER DEFLATE, INTEGER DEFLATE_LEVEL);
5386 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5392 : NF\_INQ\_VAR\_DEFLATE will set this to a 1 if the shuffle filter is
5393 turned on for this variable, and a 0 otherwise.
5396 : NF\_INQ\_VAR\_DEFLATE will set this to a 1 if the deflate filter is
5397 turned on for this variable, and a 0 otherwise.
5400 : NF\_INQ\_VAR\_DEFLATE function will write the deflate\_level here,
5401 if deflate is in use.
5406 NF\_INQ\_VAR\_DEFLATE returns the value NF\_NOERR if no errors occurred.
5407 Otherwise, the returned status indicates an error.
5409 Possible return codes include:
5418 : Not a netCDF-4 file.
5421 : Can’t find this variable.
5426 In this example code from nf\_test/ftst\_vars.F, a file with a variable
5427 using deflate is opened, and the deflate level checked.
5432 C Is everything set that ispposed to be?
5433 retval = nf_inq_var_deflate(ncid, varid, shuffle, deflate,
5435 if (retval .ne. nf_noerr) call handle_err(retval)
5436 if (shuffle .ne. 0 .or. deflate .ne. 1 .or.
5437 + deflate_level .ne. 4) stop 2
5440 6.12 Learn About Szip Parameters for a Variable: `NF_INQ_VAR_SZIP`
5441 ------------------------------------------------------------------
5443 The function NF\_INQ\_VAR\_SZIP returns the szip settings for a variable
5446 It is not necessary to know the szip settings to read the variable.
5447 (Szip is completely transparent to readers of the data). But an
5448 Szip compatible library must be installed.
5456 NF_INQ_VAR_SZIP(INTEGER NCID, INTEGER VARID, INTEGER OPTION_MASK,
5461 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5467 : This will be set to the option\_mask value.
5470 : The number of bits per pixel will be put here.
5475 NF\_INQ\_VAR\_SZIP returns the value NF\_NOERR if no errors occurred.
5476 Otherwise, the returned status indicates an error.
5478 Possible return codes include:
5487 : Not a netCDF-4 file.
5490 : Can’t find this variable.
5493 6.13 Define Checm Parameters for a Variable: `NF_DEF_VAR_FLETCHER32`
5494 -----------------------------------------------------------------------
5496 The function NF\_DEF\_VAR\_FLETCHER32 sets the checm property for a
5497 variable in a netCDF-4 file.
5499 This function may only be called after the variable is defined, but
5500 before NF\_ENDDEF is called.
5508 NF_DEF_VAR_FLETCHER32(INTEGER NCID, INTEGER VARID, INTEGER CHECKSUM);
5512 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5518 : If this is NF\_FLETCHER32, fletcher32 checms will be turned on
5524 NF\_DEF\_VAR\_FLETCHER32 returns the value NF\_NOERR if no errors
5525 occurred. Otherwise, the returned status indicates an error.
5527 Possible return codes include:
5536 : Not a netCDF-4 file.
5539 : Can’t find this variable.
5542 : This variable has already been thebject of a NF\_ENDDEF call. In
5543 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5544 read or write. Once enddef has been called, it is impossible to set
5545 the checm property for a variable.
5548 : Not in define mode. This is returned for netCDF classic or 64-bit
5549 offset files, or for netCDF-4 files, when they were been created
5550 with NF\_STRICT\_NC3 flag. (see
5551 [NF\_CREATE](#NF_005fCREATE)).
5554 : Attempt to create object in read-only file.
5559 In this example from nf\_test/ftst\_vars.F, the variable in a file has
5560 the Fletcher32 checm filter turned on.
5565 C Create the netCDF file.
5566 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5567 if (retval .ne. nf_noerr) call handle_err(retval)
5569 C Define the dimensions.
5570 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5571 if (retval .ne. nf_noerr) call handle_err(retval)
5572 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5573 if (retval .ne. nf_noerr) call handle_err(retval)
5575 C Define the variable.
5578 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5579 if (retval .ne. nf_noerr) call handle_err(retval)
5584 retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
5585 if (retval .ne. nf_noerr) call handle_err(retval)
5587 C Turn on deflate compression, fletcher32 checms.
5588 retval = NF_DEF_VAR_DEFLATE(ncid, varid, 0, 1, 4)
5589 if (retval .ne. nf_noerr) call handle_err(retval)
5590 retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
5591 if (retval .ne. nf_noerr) call handle_err(retval)
5595 6.14 Learn About Checm Parameters for a Variable: `NF_INQ_VAR_FLETCHER32`
5596 ----------------------------------------------------------------------------
5598 The function NF\_INQ\_VAR\_FLETCHER32 returns the checm settings for
5599 a variable in a netCDF-4 file.
5607 NF_INQ_VAR_FLETCHER32(INTEGER NCID, INTEGER VARID, INTEGER CHECKSUM);
5611 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5617 : NF\_INQ\_VAR\_FLETCHER32 will set this to NF\_FLETCHER32 if the
5618 fletcher32 filter is turned on for this variable, and NF\_NOCHECKSUM
5624 NF\_INQ\_VAR\_FLETCHER32 returns the value NF\_NOERR if no errors
5625 occurred. Otherwise, the returned status indicates an error.
5627 Possible return codes include:
5636 : Not a netCDF-4 file.
5639 : Can’t find this variable.
5644 In this example from nf\_test/ftst\_vars.F the checm filter is
5645 checked for a file. Since it was turned on for this variable, the
5646 checm variable is set to NF\_FLETCHER32.
5651 retval = nf_inq_var_fletcher32(ncid, varid, checm)
5652 if (retval .ne. nf_noerr) call handle_err(retval)
5653 if (checm .ne. NF_FLETCHER32) stop 2
5656 6.15 Define Endianness of a Variable: `NF_DEF_VAR_ENDIAN`
5657 ---------------------------------------------------------
5659 The function NF\_DEF\_VAR\_ENDIAN sets the endianness for a variable in
5662 This function must be called after the variable is defined, but before
5663 NF\_ENDDEF is called.
5665 By default, netCDF-4 variables are in native endianness. That is, they
5666 are big-endian on a big-endian machine, and little-endian on a little
5669 In some cases a user might wish to change from native endianness to
5670 either big or little-endianness. This function allows them to do that.
5678 NF_DEF_VAR_ENDIAN(INTEGER NCID, INTEGER VARID, INTEGER ENDIAN)
5682 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5688 : Set to NF\_ENDIAN\_NATIVE for native endianness. (This is the
5689 default). Set to NF\_ENDIAN\_LITTLE for little endian, or
5690 NF\_ENDIAN\_BIG for big endian.
5695 NF\_DEF\_VAR\_ENDIAN returns the value NF\_NOERR if no errors occurred.
5696 Otherwise, the returned status indicates an error.
5698 Possible return codes include:
5707 : Not a netCDF-4 file.
5710 : Can’t find this variable.
5713 : This variable has already been thebject of a NF\_ENDDEF call. In
5714 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5715 read or write. Once enddef has been called, it is impossible to set
5716 the endianness of a variable.
5719 : Not in define mode. This is returned for netCDF classic or 64-bit
5720 offset files, or for netCDF-4 files, when they were been created
5721 with NF\_STRICT\_NC3 flag, and the file is not in define mode. (see
5722 [NF\_CREATE](#NF_005fCREATE)).
5725 : Attempt to create object in read-only file.
5730 In this example from nf\_test/ftst\_vars.c, a file is created with one
5731 variable, and its endianness is set to NF\_ENDIAN\_BIG.
5736 C Create the netCDF file.
5737 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5738 if (retval .ne. nf_noerr) call handle_err(retval)
5740 C Define the dimensions.
5741 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5742 if (retval .ne. nf_noerr) call handle_err(retval)
5743 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5744 if (retval .ne. nf_noerr) call handle_err(retval)
5746 C Define the variable.
5749 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5750 if (retval .ne. nf_noerr) call handle_err(retval)
5755 retval = NF_DEF_VAR_chunking(ncid, varid, 0, chunks)
5756 if (retval .ne. nf_noerr) call handle_err(retval)
5758 C Set variable to big-endian (default is whatever is native to
5760 retval = NF_DEF_VAR_endian(ncid, varid, NF_ENDIAN_BIG)
5761 if (retval .ne. nf_noerr) call handle_err(retval)
5764 6.16 Learn About Endian Parameters for a Variable: `NF_INQ_VAR_ENDIAN`
5765 ----------------------------------------------------------------------
5767 The function NF\_INQ\_VAR\_ENDIAN returns the endianness settings for a
5768 variable in a netCDF-4 file.
5776 NF_INQ_VAR_ENDIAN(INTEGER NCID, INTEGER VARID, INTEGER ENDIAN)
5780 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5786 : NF\_INQ\_VAR\_ENDIAN will set this to NF\_ENDIAN\_LITTLE if this
5787 variable is stored in little-endian format, NF\_ENDIAN\_BIG if it is
5788 stored in big-endian format, and NF\_ENDIAN\_NATIVE if the
5789 endianness is not set, and the variable is not created yet.
5794 NF\_INQ\_VAR\_ENDIAN returns the value NF\_NOERR if no errors occurred.
5795 Otherwise, the returned status indicates an error.
5797 Possible return codes include:
5806 : Not a netCDF-4 file.
5809 : Can’t find this variable.
5814 In this example from nf\_test/ftst\_vars.F, the endianness of a variable
5815 is checked to makere it is NF\_ENDIAN\_BIG.
5820 retval = nf_inq_var_endian(ncid, varid, endianness)
5821 if (retval .ne. nf_noerr) call handle_err(retval)
5822 if (endianness .ne. NF_ENDIAN_BIG) stop 2
5826 6.17 Define Filter for a Variable: `NF_DEF_VAR_FILTER`
5827 ---------------------------------------------------------
5829 The function NF\_DEF\_VAR\_FILTER sets a filter (i.e. compression filter)
5830 for a variable in a netCDF-4 file.
5832 This function must be called after the variable is defined, but before
5833 NF\_ENDDEF is called.
5835 In order to use a custom filter (other than zip or szip), it is necessary
5836 to install the custom filter into some directory and then to specify
5837 the path to that directory by setting the environment variable named
5838 __HDF5_PLUGIN_PATH__. For details, see the netcdf-c library documentation
5839 for filters: https://www.unidata.ucar.edu/software/netcdf/docs/.
5847 NF_DEF_VAR_FILTER(INTEGER NCID, INTEGER VARID, INTEGER FILTERID, INTEGER NPARAMS, INTEGER PARAMS(*))
5851 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5860 : Number of parameters expected by the filter.
5863 : A vector of integers representing the parameters to the Filter.
5868 NF\_DEF\_VAR\_FILTER returns the value NF\_NOERR if no errors occurred.
5869 Otherwise, the returned status indicates an error.
5871 Possible return codes include:
5880 : Not a netCDF-4 file.
5883 : Can’t find this variable.
5886 : This variable has already been thebject of a NF\_ENDDEF call. In
5887 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5888 read or write. Once enddef has been called, it is impossible to set
5889 the filterness of a variable.
5892 : Not in define mode. This is returned for netCDF classic or 64-bit
5893 offset files, or for netCDF-4 files, when they were been created
5894 with NF\_STRICT\_NC3 flag, and the file is not in define mode. (see
5895 [NF\_CREATE](#NF_005fCREATE)).
5898 : Some kind of error in defining the filter: bad id or parameters or filter library non-existent
5903 In this example from nf\_test/ftst\_vars.c, a file is created with one
5904 variable, and its filter is set to filter id 307 (bzip).
5910 C Create the netCDF file.
5911 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5912 if (retval .ne. nf_noerr) call handle_err(retval)
5914 C Define the dimensions.
5915 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5916 if (retval .ne. nf_noerr) call handle_err(retval)
5917 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5918 if (retval .ne. nf_noerr) call handle_err(retval)
5920 C Define the variable.
5923 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5924 if (retval .ne. nf_noerr) call handle_err(retval)
5929 retval = NF_DEF_VAR_chunking(ncid, varid, 0, chunks)
5930 if (retval .ne. nf_noerr) call handle_err(retval)
5932 C Set variable filter
5933 retval = NF_DEF_VAR_filter(ncid, varid, 307, 1, params)
5934 if (retval .ne. nf_noerr) call handle_err(retval)
5937 6.18 Learn About Filter Parameters for a Variable: `NF_INQ_VAR_FILTER`
5938 ----------------------------------------------------------------------
5940 The function NF\_INQ\_VAR\_FILTER returns the filter settings for a
5941 variable in a netCDF-4 file.
5949 NF_INQ_VAR_FILTER(INTEGER NCID, INTEGER VARID, INTEGER FILTERID, INTEGER NPARAMS, INTEGER PARAMS(*))
5953 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5962 : Number of parameters required by the filter.
5965 : Parameter values used by the filter.
5970 NF\_INQ\_VAR\_FILTER returns the value NF\_NOERR if no errors occurred.
5971 Otherwise, the returned status indicates an error.
5973 Possible return codes include:
5982 : Not a netCDF-4 file.
5985 : Can’t find this variable.
5988 : Some kind of error in defining the filter: bad id or parameters or filter library non-existent
5993 In this example from nf\_test/ftst\_vars.F, the filter for a variable
6000 integer filterid, nparams
6001 retval = nf_inq_var_filter(ncid, varid, filterid, nparams, params)
6002 if (retval .ne. nf_noerr) call handle_err(retval)
6003 if (filterid .ne. 307) call handle_err(NF_EFILTER)
6004 if (nparams .ne. 1) call handle_err(NF_EFILTER)
6007 6.19 Get a Variable ID from Its Name: NF\_INQ\_VARID
6008 ----------------------------------------------------
6010 The function NF\_INQ\_VARID returns the ID of a netCDF variable, given
6019 INTEGER FUNCTION NF_INQ_VARID(INTEGER NCID, CHARACTER*(*) NAME,
6024 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6027 : Variable name for which ID is desired.
6030 : Returned variable ID.
6035 NF\_INQ\_VARID returns the value NF\_NOERR if no errors occurred.
6036 Otherwise, the returned status indicates an error. Possible causes of
6039 - The specified variable name is not a valid name for a variable in
6040 the specified netCDF dataset.
6041 - The specified netCDF ID does not refer to an open netCDF dataset.
6046 Here is an example using NF\_INQ\_VARID to find out the ID of a variable
6047 named rh in an existing netCDF dataset named foo.nc:
6052 INCLUDE 'netcdf.inc'
6054 INTEGER STATUS, NCID, RHID
6056 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6057 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6059 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6060 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6064 6.20 Get Information about a Variable from Its ID: NF\_INQ\_VAR family
6065 ----------------------------------------------------------------------
6067 A family of functions that returns information about a netCDF variable,
6068 given its ID. Information about a variable includes its name, type,
6069 number of dimensions, a list of dimension IDs describing the shape of
6070 the variable, and the number of variable attributes that have been
6071 assigned to the variable.
6073 The function NF\_INQ\_VAR returns all the information about a netCDF
6074 variable, given its ID. The other functions each return just one item of
6075 information about a variable.
6077 These other functions include NF\_INQ\_VARNAME, NF\_INQ\_VARTYPE,
6078 NF\_INQ\_VARNDIMS, NF\_INQ\_VARDIMID, and NF\_INQ\_VARNATTS.
6086 INTEGER FUNCTION NF_INQ_VAR (INTEGER NCID, INTEGER VARID,
6087 CHARACTER*(*) name, INTEGER xtype,
6088 INTEGER ndims, INTEGER dimids(*),
6090 INTEGER FUNCTION NF_INQ_VARNAME (INTEGER NCID, INTEGER VARID,
6092 INTEGER FUNCTION NF_INQ_VARTYPE (INTEGER NCID, INTEGER VARID,
6094 INTEGER FUNCTION NF_INQ_VARNDIMS (INTEGER NCID, INTEGER VARID,
6096 INTEGER FUNCTION NF_INQ_VARDIMID (INTEGER NCID, INTEGER VARID,
6098 INTEGER FUNCTION NF_INQ_VARNATTS (INTEGER NCID, INTEGER VARID,
6103 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6109 : Returned variable name. The caller must allocate space for the
6110 returned name. The maximum possible length, in characters, of a
6111 variable name is given by the predefined constant NF\_MAX\_NAME.
6114 : Returned variable type, one of the set of predefined netCDF external
6115 data types. The type of this parameter, NF\_TYPE, is defined in the
6116 netCDF header file. The valid netCDF external data types are
6117 NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, AND NF\_DOUBLE.
6120 : Returned number of dimensions the variable was defined as using. For
6121 example, 2 indicates a matrix, 1 indicates a vector, and 0 means the
6122 variable is a scalar with no dimensions.
6125 : Returned vector of \*ndimsp dimension IDs corresponding to the
6126 variable dimensions. The caller must allocate enough space for a
6127 vector of at least \*ndimsp integers to be returned. The maximum
6128 possible number of dimensions for a variable is given by the
6129 predefined constant NF\_MAX\_VAR\_DIMS.
6132 : Returned number of variable attributes assigned to this variable.
6134 These functions return the value NF\_NOERR if no errors occurred.
6135 Otherwise, the returned status indicates an error. Possible causes of
6138 - The variable ID is invalid for the specified netCDF dataset.
6139 - The specified netCDF ID does not refer to an open netCDF dataset.
6144 Here is an example using NF\_INQ\_VAR to find out about a variable named
6145 rh in an existing netCDF dataset named foo.nc:
6150 INCLUDE 'netcdf.inc'
6152 INTEGER STATUS, NCID
6153 INTEGER RHID ! variable ID
6154 CHARACTER*31 RHNAME ! variable name
6155 INTEGER RHTYPE ! variable type
6156 INTEGER RHN ! number of dimensions
6157 INTEGER RHDIMS(NF_MAX_VAR_DIMS) ! variable shape
6158 INTEGER RHNATT ! number of attributes
6160 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6161 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6163 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
6164 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6165 STATUS = NF_INQ_VAR (NCID, RHID, RHNAME, RHTYPE, RHN, RHDIMS, RHNATT)
6166 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6169 6.21 Write a Single Data Value: NF\_PUT\_VAR1\_ type
6170 ----------------------------------------------------
6172 The functions NF\_PUT\_VAR1\_type (for various types) put a single data
6173 value of the specified type into a variable of an open netCDF dataset
6174 that is in data mode. Inputs are the netCDF ID, the variable ID, an
6175 index that specifies which value to add or alter, and the data value.
6176 The value is converted to the external data type of the variable, if
6185 INTEGER FUNCTION NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6186 INTEGER INDEX(*), CHARACTER CHVAL)
6187 INTEGER FUNCTION NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6188 INTEGER INDEX(*), INTEGER*1 I1VAL)
6189 INTEGER FUNCTION NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6190 INTEGER INDEX(*), INTEGER*2 I2VAL)
6191 INTEGER FUNCTION NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
6192 INTEGER INDEX(*), INTEGER IVAL)
6193 INTEGER FUNCTION NF_PUT_VAR1_INT64(INTEGER NCID, INTEGER VARID,
6194 INTEGER INDEX(*), INTEGER*8 I8VAL)
6195 INTEGER FUNCTION NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6196 INTEGER INDEX(*), REAL RVAL)
6197 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6198 INTEGER INDEX(*), DOUBLE DVAL)
6199 INTEGER FUNCTION NF_PUT_VAR1(INTEGER NCID, INTEGER VARID,
6200 INTEGER INDEX(*), *)
6204 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6210 : The index of the data value to be written. The indices are relative
6211 to 1, so for example, the first data value of a two-dimensional
6212 variable would have index (1,1). The elements of index must
6213 correspond to the variable’s dimensions. Hence, if the variable uses
6214 the unlimited dimension, the last index would correspond to the
6224 : Pointer to the data value to be written. If the type of data values
6225 differs from the netCDF variable type, type conversion will occur.
6226 See [(netcdf)Type Conversion](netcdf.html#Type-Conversion)
6227 ‘Type Conversion’ in The NetCDF Users Guide.
6232 NF\_PUT\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6233 Otherwise, the returned status indicates an error. Possible causes of
6236 - The variable ID is invalid for the specified netCDF dataset.
6237 - The specified indices were out of range for the rank of the
6238 specified variable. For example, a negative index or an index that
6239 is larger than the corresponding dimension length will cause an
6241 - The specified value is out of the range of values representable by
6242 the external data type of the variable.
6243 - The specified netCDF is in define mode rather than data mode.
6244 - The specified netCDF ID does not refer to an open netCDF dataset.
6249 Here is an example using NF\_PUT\_VAR1\_DOUBLE to set the (4,3,2)
6250 element of the variable named rh to 0.5 in an existing netCDF dataset
6251 named foo.nc. For simplicity in this example, we ame that we know
6252 that rh is dimensioned with lon, lat, and time, so we want to set the
6253 value of rh that corresponds to the fourth lon value, the third lat
6254 value, and the second time value:
6259 INCLUDE 'netcdf.inc'
6261 INTEGER STATUS ! error status
6263 INTEGER RHID ! variable ID
6264 INTEGER RHINDX(3) ! where to put value
6265 DATA RHINDX /4, 3, 2/
6267 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6268 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6270 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
6271 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6272 STATUS = NF_PUT_VAR1_DOUBLE (NCID, RHID, RHINDX, 0.5)
6273 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6276 6.22 Write an Entire Variable: NF\_PUT\_VAR\_ type
6277 --------------------------------------------------
6279 The NF\_PUT\_VAR\_ type family of functions write all the values of a
6280 variable into a netCDF variable of an open netCDF dataset. This is the
6281 simplest interface to use for writing a value in a scalar variable or
6282 whenever all the values of a multidimensional variable can all be
6283 written at once. The values to be written are associated with the netCDF
6284 variable by aming that the last dimension of the netCDF variable
6285 varies fastest in the C interface. The values are converted to the
6286 external data type of the variable, if necessary.
6288 Take care when using the simplest forms of this interface with record
6289 variables (variables that use the NF\_UNLIMITED dimension) when you
6290 don’t specify how many records are to be written. If you try to write
6291 all the values of a record variable into a netCDF file that has no
6292 record data yet (hence has 0 records), nothing will be written.
6293 Similarly, if you try to write all the values of a record variable from
6294 an array but there are more records in the file than you ame, more
6295 in-memory data will be accessed than you expect, which may cause a
6296 segmentation violation. To avoidch problems, it is better to use the
6297 NF\_PUT\_VARA\_type interfaces for variables that use the NF\_UNLIMITED
6298 dimension. See [Write an Array of Values: NF\_PUT\_VARA\_
6299 type](#NF_005fPUT_005fVARA_005f-type).
6307 INTEGER FUNCTION NF_PUT_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6309 INTEGER FUNCTION NF_PUT_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6310 INTEGER*1 I1VALS(*))
6311 INTEGER FUNCTION NF_PUT_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6312 INTEGER*2 I2VALS(*))
6313 INTEGER FUNCTION NF_PUT_VAR_INT (INTEGER NCID, INTEGER VARID,
6315 INTEGER FUNCTION NF_PUT_VAR_INT64 (INTEGER NCID, INTEGER VARID,
6316 INTEGER*8 I8VALS(*))
6317 INTEGER FUNCTION NF_PUT_VAR_REAL (INTEGER NCID, INTEGER VARID,
6319 INTEGER FUNCTION NF_PUT_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6321 INTEGER FUNCTION NF_PUT_VAR (INTEGER NCID, INTEGER VARID,
6326 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6339 : The block of data values to be written. The data should be of the
6340 type appropriate for the function called. You cannot put CHARACTER
6341 data into a numeric variable or numeric data into a text variable.
6342 For numeric data, if the type of data differs from the netCDF
6343 variable type, type conversion will occur (see [(netcdf)Type
6344 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6345 in The NetCDF Users Guide). The order in which the data will be
6346 written into the specified variable is with the first dimension
6347 varying fastest (like the ordinary FORTRAN convention).
6352 Members of the NF\_PUT\_VAR\_ type family return the value NF\_NOERR if
6353 no errors occurred. Otherwise, the returned status indicates an error.
6354 Possible causes of errors include:
6356 - The variable ID is invalid for the specified netCDF dataset.
6357 - One or more of the specified values are out of the range of values
6358 representable by the external data type of the variable.
6359 - One or more of the specified values are out of the range of values
6360 representable by the external data type of the variable.
6361 - The specified netCDF dataset is in define mode rather than data
6363 - The specified netCDF ID does not refer to an open netCDF dataset.
6368 Here is an example using NF\_PUT\_VAR\_DOUBLE to add or change all the
6369 values of the variable named rh to 0.5 in an existing netCDF dataset
6370 named foo.nc. For simplicity in this example, we ame that we know
6371 that rh is dimensioned with lon and lat, and that there are ten lon
6372 values and five lat values.
6377 INCLUDE 'netcdf.inc'
6379 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6380 INTEGER STATUS, NCID
6381 INTEGER RHID ! variable ID
6382 DOUBLE RHVALS(LONS, LATS)
6384 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6385 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6387 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6388 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6389 DO 10 ILON = 1, LONS
6390 DO 10 ILAT = 1, LATS
6391 RHVALS(ILON, ILAT) = 0.5
6393 STATUS = NF_PUT_var_DOUBLE (NCID, RHID, RHVALS)
6394 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6398 6.23 Write an Array of Values: NF\_PUT\_VARA\_ type
6399 ---------------------------------------------------
6401 The function NF\_PUT\_VARA\_ type writes values into a netCDF variable
6402 of an open netCDF dataset. The part of the netCDF variable to write is
6403 specified by giving a corner and a vector of edge lengths that refer to
6404 an array of the netCDF variable. The values to be written are
6405 associated with the netCDF variable by aming that the first dimension
6406 of the netCDF variable varies fastest in the FORTRAN interface. The
6407 netCDF dataset must be in data mode.
6415 INTEGER FUNCTION NF_PUT_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6416 INTEGER START(*), INTEGER COUNT(*),
6418 INTEGER FUNCTION NF_PUT_VARA_INT1(INTEGER NCID, INTEGER VARID,
6419 INTEGER START(*), INTEGER COUNT(*),
6420 INTEGER*1 I1VALS(*))
6421 INTEGER FUNCTION NF_PUT_VARA_INT2(INTEGER NCID, INTEGER VARID,
6422 INTEGER START(*), INTEGER COUNT(*),
6423 INTEGER*2 I2VALS(*))
6424 INTEGER FUNCTION NF_PUT_VARA_INT (INTEGER NCID, INTEGER VARID,
6425 INTEGER START(*), INTEGER COUNT(*),
6427 INTEGER FUNCTION NF_PUT_VARA_INT64(INTEGER NCID, INTEGER VARID,
6428 INTEGER START(*), INTEGER COUNT(*),
6429 INTEGER*8 I8VALS(*))
6430 INTEGER FUNCTION NF_PUT_VARA_REAL(INTEGER NCID, INTEGER VARID,
6431 INTEGER START(*), INTEGER COUNT(*),
6433 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6434 INTEGER START(*), INTEGER COUNT(*),
6436 INTEGER FUNCTION NF_PUT_VARA (INTEGER NCID, INTEGER VARID,
6437 INTEGER START(*), INTEGER COUNT(*),
6442 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6448 : A vector of integers specifying the index in the variable where the
6449 first of the data values will be written. The indices are relative
6450 to 1, so for example, the first data value of a variable would have
6451 index (1, 1, ..., 1). The length of START must be the same as the
6452 number of dimensions of the specified variable. The elements of
6453 START must correspond to the variable’s dimensions in order. Hence,
6454 if the variable is a record variable, the last index would
6455 correspond to the starting record number for writing the data
6459 : A vector of integers specifying the edge lengths along each
6460 dimension of the block of data values to written. To write a single
6461 value, for example, specify COUNT as (1, 1, ..., 1). The length of
6462 COUNT is the number of dimensions of the specified variable. The
6463 elements of COUNT correspond to the variable’s dimensions. Hence, if
6464 the variable is a record variable, the last element of COUNT
6465 corresponds to a count of the number of records to write.
6467 Note: setting any element of the count array to zero causes the
6468 function to exit without error, and without doing anything.
6478 : The block of data values to be written. The data should be of the
6479 type appropriate for the function called. You cannot put CHARACTER
6480 data into a numeric variable or numeric data into a text variable.
6481 For numeric data, if the type of data differs from the netCDF
6482 variable type, type conversion will occur (see [(netcdf)Type
6483 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6484 in The NetCDF Users Guide).
6489 NF\_PUT\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
6490 Otherwise, the returned status indicates an error. Possible causes of
6493 - The variable ID is invalid for the specified netCDF dataset.
6494 - The specified corner indices were out of range for the rank of the
6495 specified variable. For example, a negative index, or an index that
6496 is larger than the corresponding dimension length will cause an
6498 - The specified edge lengths added to the specified corner would have
6499 referenced data out of range for the rank of the specified variable.
6500 For example, an edge length that is larger than the corresponding
6501 dimension length minus the corner index will cause an error.
6502 - One or more of the specified values are out of the range of values
6503 representable by the external data type of the variable.
6504 - The specified netCDF dataset is in define mode rather than data
6506 - The specified netCDF ID does not refer to an open netCDF dataset.
6511 Here is an example using NF\_PUT\_VARA\_DOUBLE to add or change all the
6512 values of the variable named rh to 0.5 in an existing netCDF dataset
6513 named foo.nc. For simplicity in this example, we ame that we know
6514 that rh is dimensioned with time, lat, and lon, and that there are three
6515 time values, five lat values, and ten lon values.
6520 INCLUDE 'netcdf.inc'
6522 PARAMETER (NDIMS=3) ! number of dimensions
6523 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
6524 INTEGER STATUS, NCID, TIMES
6525 INTEGER RHID ! variable ID
6526 INTEGER START(NDIMS), COUNT(NDIMS)
6527 DOUBLE RHVALS(LONS, LATS, TIMES)
6528 DATA START /1, 1, 1/ ! start at first value
6529 DATA COUNT /LONS, LATS, TIMES/
6531 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6532 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6534 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6535 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6536 DO 10 ILON = 1, LONS
6537 DO 10 ILAT = 1, LATS
6538 DO 10 ITIME = 1, TIMES
6539 RHVALS(ILON, ILAT, ITIME) = 0.5
6541 STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
6542 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6546 6.24 NF\_PUT\_VARS\_ type
6547 -------------------------
6549 Each member of the family of functions NF\_PUT\_VARS\_ type writes a
6550 subsampled (strided) array of values into a netCDF variable of
6551 an open netCDF dataset. Thebsampled array is specified by
6552 giving a corner, a vector of counts, and a stride vector. The netCDF
6553 dataset must be in data mode.
6561 INTEGER FUNCTION NF_PUT_VARS_TEXT (INTEGER NCID, INTEGER VARID,
6562 INTEGER START(*), INTEGER COUNT(*),
6563 INTEGER STRIDE(*),CHARACTER*(*) TEXT)
6564 INTEGER FUNCTION NF_PUT_VARS_INT1 (INTEGER NCID, INTEGER VARID,
6565 INTEGER START(*), INTEGER COUNT(*),
6566 INTEGER STRIDE(*),INTEGER*1 I1VALS(*))
6567 INTEGER FUNCTION NF_PUT_VARS_INT2 (INTEGER NCID, INTEGER VARID,
6568 INTEGER START(*), INTEGER COUNT(*),
6569 INTEGER STRIDE(*),INTEGER*2 I2VALS(*))
6570 INTEGER FUNCTION NF_PUT_VARS_INT (INTEGER NCID, INTEGER VARID,
6571 INTEGER START(*), INTEGER COUNT(*),
6572 INTEGER STRIDE(*), INTEGER IVALS(*))
6573 INTEGER FUNCTION NF_PUT_VARS_INT64 (INTEGER NCID, INTEGER VARID,
6574 INTEGER START(*), INTEGER COUNT(*),
6575 INTEGER STRIDE(*), INTEGER*8 I8VALS(*))
6576 INTEGER FUNCTION NF_PUT_VARS_REAL (INTEGER NCID, INTEGER VARID,
6577 INTEGER START(*), INTEGER COUNT(*),
6578 INTEGER STRIDE(*), REAL RVALS(*))
6579 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
6580 INTEGER START(*), INTEGER COUNT(*),
6581 INTEGER STRIDE(*), DOUBLE DVALS(*))
6582 INTEGER FUNCTION NF_PUT_VARS (INTEGER NCID, INTEGER VARID,
6583 INTEGER START(*), INTEGER COUNT(*),
6584 INTEGER STRIDE(*), VALS(*))
6588 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6594 : A vector of integers specifying the index in the variable where the
6595 first of the data values will be written. The indices are relative
6596 to 1, so for example, the first data value of a variable would have
6597 index (1, 1, ..., 1). The elements of START correspond, in order, to
6598 the variable’s dimensions. Hence, if the variable is a record
6599 variable, the last index would correspond to the starting record
6600 number for writing the data values.
6603 : A vector of integers specifying the number of indices selected along
6604 each dimension. To write a single value, for example, specify COUNT
6605 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6606 the variable’s dimensions. Hence, if the variable is a record
6607 variable, the last element of COUNT corresponds to a count of the
6608 number of records to write.
6610 Note: setting any element of the count array to zero causes the
6611 function to exit without error, and without doing anything.
6614 : A vector of integers that specifies the sampling interval along each
6615 dimension of the netCDF variable. The elements of the stride vector
6616 correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6617 gives the sampling interval along the most rapidly varying dimension
6618 of the netCDF variable). Sampling intervals are specified in
6619 type-independent units of elements (a value of 1 selects consecutive
6620 elements of the netCDF variable along the corresponding dimension, a
6621 value of 2 selects every other element, etc.).
6631 : The block of data values to be written. The data should be of the
6632 type appropriate for the function called. You cannot put CHARACTER
6633 data into a numeric variable or numeric data into a text variable.
6634 For numeric data, if the type of data differs from the netCDF
6635 variable type, type conversion will occur (see [(netcdf)Type
6636 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6637 in The NetCDF Users Guide).
6642 NF\_PUT\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
6643 Otherwise, the returned status indicates an error. Possible causes of
6646 - The variable ID is invalid for the specified netCDF dataset.
6647 - The specified start, count and stride generate an index which is out
6649 - One or more of the specified values are out of the range of values
6650 representable by the external data type of the variable.
6651 - The specified netCDF is in define mode rather than data mode.
6652 - The specified netCDF ID does not refer to an open netCDF dataset.
6657 Here is an example of using NF\_PUT\_VARS\_REAL to write – from an
6658 internal array – every other point of a netCDF variable named rh which
6659 is described by the FORTRAN declaration REAL RH(6,4) (note the size of
6665 INCLUDE 'netcdf.inc'
6667 PARAMETER (NDIM=2) ! rank of netCDF variable
6668 INTEGER NCID ! netCDF dataset ID
6669 INTEGER STATUS ! return code
6670 INTEGER RHID ! variable ID
6671 INTEGER START(NDIM) ! netCDF variable start point
6672 INTEGER COUNT(NDIM) ! size of internal array
6673 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6674 REAL RH(3,2) ! notebsampled sizes for netCDF variable
6676 DATA START /1, 1/ ! start at first netCDF variable value
6677 DATA COUNT /3, 2/ ! size of internal array: entire bsampled)
6679 DATA STRIDE /2, 2/ ! access every other netCDF element
6681 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6682 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6684 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6685 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6687 STATUS = NF_PUT_VARS_REAL(NCID, RHID, START, COUNT, STRIDE, RH)
6688 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6690 6.25 NF\_PUT\_VARM\_ type
6691 -------------------------
6693 The NF\_PUT\_VARM\_ type family of functions writes a mapped array
6694 section of values into a netCDF variable of an open netCDF dataset. The
6695 mapped array is specified by giving a corner, a vector of
6696 counts, a stride vector, and an index mapping vector. The index mapping
6697 vector is a vector of integers that specifies the mapping between the
6698 dimensions of a netCDF variable and the in-memory structure of the
6699 internal data array. No amptions are made about the ordering or
6700 length of the dimensions of the data array. The netCDF dataset must be
6709 INTEGER FUNCTION NF_PUT_VARM_TEXT (INTEGER NCID, INTEGER VARID,
6710 INTEGER START(*), INTEGER COUNT(*),
6711 INTEGER STRIDE(*), INTEGER IMAP(*),
6713 INTEGER FUNCTION NF_PUT_VARM_INT1 (INTEGER NCID, INTEGER VARID,
6714 INTEGER START(*), INTEGER COUNT(*),
6715 INTEGER STRIDE(*), INTEGER IMAP(*),
6716 INTEGER*1 I1VALS(*))
6717 INTEGER FUNCTION NF_PUT_VARM_INT2 (INTEGER NCID, INTEGER VARID,
6718 INTEGER START(*), INTEGER COUNT(*),
6719 INTEGER STRIDE(*), INTEGER IMAP(*),
6720 INTEGER*2 I2VALS(*))
6721 INTEGER FUNCTION NF_PUT_VARM_INT (INTEGER NCID, INTEGER VARID,
6722 INTEGER START(*), INTEGER COUNT(*),
6723 INTEGER STRIDE(*), INTEGER IMAP(*),
6725 INTEGER FUNCTION NF_PUT_VARM_INT64 (INTEGER NCID, INTEGER VARID,
6726 INTEGER START(*), INTEGER COUNT(*),
6727 INTEGER STRIDE(*), INTEGER IMAP(*),
6728 INTEGER*8 I8VALS(*))
6729 INTEGER FUNCTION NF_PUT_VARM_REAL (INTEGER NCID, INTEGER VARID,
6730 INTEGER START(*), INTEGER COUNT(*),
6731 INTEGER STRIDE(*), INTEGER IMAP(*),
6733 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
6734 INTEGER START(*), INTEGER COUNT(*),
6735 INTEGER STRIDE(*), INTEGER IMAP(*),
6740 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6746 : A vector of integers specifying the index in the variable where the
6747 first of the data values will be written. The indices are relative
6748 to 1, so for example, the first data value of a variable would have
6749 index (1, 1, ..., 1). The elements of START correspond, in order, to
6750 the variable’s dimensions. Hence, if the variable is a record
6751 variable, the last index would correspond to the starting record
6752 number for writing the data values.
6755 : A vector of integers specifying the number of indices selected along
6756 each dimension. To write a single value, for example, specify COUNT
6757 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6758 the variable’s dimensions. Hence, if the variable is a record
6759 variable, the last element of COUNT corresponds to a count of the
6760 number of records to write.
6762 Note: setting any element of the count array to zero causes the
6763 function to exit without error, and without doing anything.
6766 : A vector of integers that specifies the sampling interval along each
6767 dimension of the netCDF variable. The elements of the stride vector
6768 correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6769 gives the sampling interval along the most rapidly varying dimension
6770 of the netCDF variable). Sampling intervals are specified in
6771 type-independent units of elements (a value of 1 selects consecutive
6772 elements of the netCDF variable along the corresponding dimension, a
6773 value of 2 selects every other element, etc.).
6776 : A vector of integers that specifies the mapping between the
6777 dimensions of a netCDF variable and the in-memory structure of the
6778 internal data array. The elements of the index mapping vector
6779 correspond, in order, to the netCDF variable’s dimensions (IMAP(1)
6780 gives the distance between elements of the internal array
6781 corresponding to the most rapidly varying dimension of the netCDF
6782 variable). Distances between elements are specified in units of
6783 elements (the distance between internal elements that occupy
6784 adjacent memory locations is 1 and not the element’s byte-length as
6794 : The data values to be written. The data should be of the type
6795 appropriate for the function called. You cannot put CHARACTER data
6796 into a numeric variable or numeric data into a text variable. For
6797 numeric data, if the type of data differs from the netCDF variable
6798 type, type conversion will occur (see [(netcdf)Type
6799 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6800 in The NetCDF Users Guide).
6805 NF\_PUT\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
6806 Otherwise, the returned status indicates an error. Possible causes of
6809 - The variable ID is invalid for the specified netCDF dataset.
6810 - The specified START, COUNT, and STRIDE generate an index which is
6811 out of range. Note that no error checking is possible on the imap
6813 - One or more of the specified values are out of the range of values
6814 representable by the external data type of the variable.
6815 - The specified netCDF is in define mode rather than data mode.
6816 - The specified netCDF ID does not refer to an open netCDF dataset.
6821 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
6822 variable and an internal array of the same shape:
6827 REAL A(2,3,4) ! same shape as netCDF variable
6829 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
6830 ! ---------------- ----------------------
6831 ! most rapidly varying 1
6832 ! intermediate 2 (=IMAP(1)*2)
6833 ! most slowly varying 6 (=IMAP(2)*3)
6836 Using the IMAP vector above with NF\_PUT\_VARM\_REAL obtains the same
6837 rlt as simply using NF\_PUT\_VAR\_REAL.
6839 Here is an example of using NF\_PUT\_VARM\_REAL to write – from a
6840 transposed, internal array – a netCDF variable named rh which is
6841 described by the FORTRAN declaration REAL RH(4,6) (note the size and
6842 order of the dimensions):
6847 INCLUDE 'netcdf.inc'
6849 PARAMETER (NDIM=2) ! rank of netCDF variable
6850 INTEGER NCID ! netCDF ID
6851 INTEGER STATUS ! return code
6852 INTEGER RHID ! variable ID
6853 INTEGER START(NDIM) ! netCDF variable start point
6854 INTEGER COUNT(NDIM) ! size of internal array
6855 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6856 INTEGER IMAP(NDIM) ! internal array inter-element distances
6857 REAL RH(6,4) ! note transposition of netCDF variable dimensions
6858 DATA START /1, 1/ ! start at first netCDF variable element
6859 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
6860 ! to netCDF variable -- not internal array
6861 DATA STRIDE /1, 1/ ! sample every netCDF element
6862 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
6864 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6865 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6867 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6868 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6870 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6871 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6874 Here is another example of using NF\_PUT\_VARM\_REAL to write – from a
6875 transposed, internal array – absample of the same netCDF variable, by
6876 writing every other point of the netCDF variable:
6881 INCLUDE 'netcdf.inc'
6883 PARAMETER (NDIM=2) ! rank of netCDF variable
6884 INTEGER NCID ! netCDF dataset ID
6885 INTEGER STATUS ! return code
6886 INTEGER RHID ! variable ID
6887 INTEGER START(NDIM) ! netCDF variable start point
6888 INTEGER COUNT(NDIM) ! size of internal array
6889 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6890 INTEGER IMAP(NDIM) ! internal array inter-element distances
6891 REAL RH(3,2) ! note transposition of bsampled) dimensions
6892 DATA START /1, 1/ ! start at first netCDF variable value
6893 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
6894 ! to netCDF variable -- not internal array
6895 DATA STRIDE /2, 2/ ! sample every other netCDF element
6896 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
6898 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6899 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6901 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6902 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6904 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6905 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6908 6.26 NF\_GET\_VAR1\_ type
6909 -------------------------
6911 The functions NF\_GET\_VAR1\_ type get a single data value from a
6912 variable of an open netCDF dataset that is in data mode. Inputs are the
6913 netCDF ID, the variable ID, a multidimensional index that specifies
6914 which value to get, and the address of a location into which the data
6915 value will be read. The value is converted from the external data type
6916 of the variable, if necessary.
6924 INTEGER FUNCTION NF_GET_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6925 INTEGER INDEX(*), CHARACTER CHVAL)
6926 INTEGER FUNCTION NF_GET_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6927 INTEGER INDEX(*), INTEGER*1 I1VAL)
6928 INTEGER FUNCTION NF_GET_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6929 INTEGER INDEX(*), INTEGER*2 I2VAL)
6930 INTEGER FUNCTION NF_GET_VAR1_INT (INTEGER NCID, INTEGER VARID,
6931 INTEGER INDEX(*), INTEGER IVAL)
6932 INTEGER FUNCTION NF_GET_VAR1_INT64 (INTEGER NCID, INTEGER VARID,
6933 INTEGER INDEX(*), INTEGER*8 I8VAL)
6934 INTEGER FUNCTION NF_GET_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6935 INTEGER INDEX(*), REAL RVAL)
6936 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6937 INTEGER INDEX(*), DOUBLE DVAL)
6938 INTEGER FUNCTION NF_GET_VAR1(INTEGER NCID, INTEGER VARID,
6939 INTEGER INDEX(*), VAL)
6943 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6949 : The index of the data value to be read. The indices are relative to
6950 1, so for example, the first data value of a two-dimensional
6951 variable has index (1,1). The elements of index correspond to the
6952 variable’s dimensions. Hence, if the variable is a record variable,
6953 the last index is the record number.
6963 : The location into which the data value will be read. You cannot get
6964 CHARACTER data from a numeric variable or numeric data from a
6965 character variable. For numeric data, if the type of data differs
6966 from the netCDF variable type, type conversion will occur. (see
6967 [(netcdf)Type Conversion](netcdf.html#Type-Conversion) ‘Type
6968 Conversion’ in The NetCDF Users Guide).
6973 NF\_GET\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6974 Otherwise, the returned status indicates an error. Possible causes of
6977 - The variable ID is invalid for the specified netCDF dataset.
6978 - The specified indices were out of range for the rank of the
6979 specified variable. For example, a negative index or an index that
6980 is larger than the corresponding dimension length will cause an
6982 - The value is out of the range of values representable by the desired
6984 - The specified netCDF is in define mode rather than data mode.
6985 - The specified netCDF ID does not refer to an open netCDF dataset.
6990 Here is an example using NF\_GET\_VAR1\_DOUBLE to get the (4,3,2)
6991 element of the variable named rh in an existing netCDF dataset named
6992 foo.nc. For simplicity in this example, we ame that we know that rh
6993 is dimensioned with lon, lat, and time, so we want to get the value of
6994 rh that corresponds to the fourth lon value, the third lat value, and
6995 the second time value:
7000 INCLUDE 'netcdf.inc'
7002 INTEGER STATUS, NCID
7003 INTEGER RHID ! variable ID
7004 INTEGER RHINDX(3) ! where to get value
7005 DOUBLE PRECISION RHVAL ! put it here
7006 DATA RHINDX /4, 3, 2/
7008 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7009 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7011 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7012 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7013 STATUS = NF_GET_VAR1_DOUBLE (NCID, RHID, RHINDX, RHVAL)
7014 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7017 6.27 NF\_GET\_VAR\_ type
7018 ------------------------
7020 The members of the NF\_GET\_VAR\_ type family of functions read all the
7021 values from a netCDF variable of an open netCDF dataset. This is the
7022 simplest interface to use for reading the value of a scalar variable or
7023 when all the values of a multidimensional variable can be read at once.
7024 The values are read into consecutive locations with the first dimension
7025 varying fastest. The netCDF dataset must be in data mode.
7027 Take care when using the simplest forms of this interface with record
7028 variables (variables that use the NF\_UNLIMITED dimension) when you
7029 don’t specify how many records are to be read. If you try to read all
7030 the values of a record variable into an array but there are more records
7031 in the file than you ame, more data will be read than you expect,
7032 which may cause a segmentation violation. To avoidch problems, it is
7033 better to use the NF\_GET\_VARA\_type interfaces for variables that use
7034 the NF\_UNLIMITED dimension. See [NF\_GET\_VARA\_
7035 type](#NF_005fGET_005fVARA_005f-type).
7043 INTEGER FUNCTION NF_GET_VAR_TEXT (INTEGER NCID, INTEGER VARID,
7045 INTEGER FUNCTION NF_GET_VAR_INT1 (INTEGER NCID, INTEGER VARID,
7046 INTEGER*1 i1vals(*))
7047 INTEGER FUNCTION NF_GET_VAR_INT2 (INTEGER NCID, INTEGER VARID,
7048 INTEGER*2 i2vals(*))
7049 INTEGER FUNCTION NF_GET_VAR_INT (INTEGER NCID, INTEGER VARID,
7051 INTEGER FUNCTION NF_GET_VAR_INT64 (INTEGER NCID, INTEGER VARID,
7052 INTEGER*8 i8vals(*))
7053 INTEGER FUNCTION NF_GET_VAR_REAL (INTEGER NCID, INTEGER VARID,
7055 INTEGER FUNCTION NF_GET_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
7057 INTEGER FUNCTION NF_GET_VAR (INTEGER NCID, INTEGER VARID,
7062 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7075 : The block of data values to be read. The data should be of the type
7076 appropriate for the function called. You cannot read CHARACTER data
7077 from a numeric variable or numeric data from a text variable. For
7078 numeric data, if the type of data differs from the netCDF variable
7079 type, type conversion will occur (see [(netcdf)Type
7080 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7081 in The NetCDF Users Guide).
7086 NF\_GET\_VAR\_ type returns the value NF\_NOERR if no errors occurred.
7087 Otherwise, the returned status indicates an error. Possible causes of
7090 - The variable ID is invalid for the specified netCDF dataset.
7091 - One or more of the values are out of the range of values
7092 representable by the desired type.
7093 - The specified netCDF is in define mode rather than data mode.
7094 - The specified netCDF ID does not refer to an open netCDF dataset.
7099 Here is an example using NF\_GET\_VAR\_DOUBLE to read all the values of
7100 the variable named rh from an existing netCDF dataset named foo.nc. For
7101 simplicity in this example, we ame that we know that rh is
7102 dimensioned with lon and lat, and that there are ten lon values and five
7108 INCLUDE 'netcdf.inc'
7110 PARAMETER (LATS=5, LONS=10) ! dimension lengths
7111 INTEGER STATUS, NCID
7112 INTEGER RHID ! variable ID
7113 DOUBLE RHVALS(LONS, LATS)
7115 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7116 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7118 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7119 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7120 STATUS = NF_GET_VAR_DOUBLE (NCID, RHID, RHVALS)
7121 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7124 6.28 NF\_GET\_VARA\_ type
7125 -------------------------
7127 The members of the NF\_GET\_VARA\_ type family of functions read an
7128 array of values from a netCDF variable of an open netCDF dataset. The
7129 array is specified by giving a corner and a vector of edge lengths. The
7130 values are read into consecutive locations with the first dimension
7131 varying fastest. The netCDF dataset must be in data mode.
7139 INTEGER FUNCTION NF_GET_VARA_TEXT(INTEGER NCID, INTEGER VARID,
7140 INTEGER START(*), INTEGER COUNT(*),
7142 INTEGER FUNCTION NF_GET_VARA_INT1(INTEGER NCID, INTEGER VARID,
7143 INTEGER START(*), INTEGER COUNT(*),
7144 INTEGER*1 i1vals(*))
7145 INTEGER FUNCTION NF_GET_VARA_INT2(INTEGER NCID, INTEGER VARID,
7146 INTEGER START(*), INTEGER COUNT(*),
7147 INTEGER*2 i2vals(*))
7148 INTEGER FUNCTION NF_GET_VARA_INT (INTEGER NCID, INTEGER VARID,
7149 INTEGER START(*), INTEGER COUNT(*),
7151 INTEGER FUNCTION NF_GET_VARA_INT64 (INTEGER NCID, INTEGER VARID,
7152 INTEGER START(*), INTEGER COUNT(*),
7153 INTEGER*8 i8vals(*))
7154 INTEGER FUNCTION NF_GET_VARA_REAL(INTEGER NCID, INTEGER VARID,
7155 INTEGER START(*), INTEGER COUNT(*),
7157 INTEGER FUNCTION NF_GET_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
7158 INTEGER START(*), INTEGER COUNT(*),
7163 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7169 : A vector of integers specifying the index in the variable where the
7170 first of the data values will be read. The indices are relative to
7171 1, so for example, the first data value of a variable would have
7172 index (1, 1, ..., 1). The length of START must be the same as the
7173 number of dimensions of the specified variable. The elements of
7174 START correspond, in order, to the variable’s dimensions. Hence, if
7175 the variable is a record variable, the last index would correspond
7176 to the starting record number for reading the data values.
7179 : A vector of integers specifying the edge lengths along each
7180 dimension of the block of data values to be read. To read a single
7181 value, for example, specify COUNT as (1, 1, ..., 1). The length of
7182 COUNT is the number of dimensions of the specified variable. The
7183 elements of COUNT correspond, in order, to the variable’s
7184 dimensions. Hence, if the variable is a record variable, the last
7185 element of COUNT corresponds to a count of the number of records to
7188 Note: setting any element of the count array to zero causes the
7189 function to exit without error, and without doing anything.
7198 : The block of data values to be read. The data should be of the type
7199 appropriate for the function called. You cannot read CHARACTER data
7200 from a numeric variable or numeric data from a text variable. For
7201 numeric data, if the type of data differs from the netCDF variable
7202 type, type conversion will occur (see [(netcdf)Type
7203 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7204 in The NetCDF Users Guide).
7209 NF\_GET\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
7210 Otherwise, the returned status indicates an error. Possible causes of
7213 - The variable ID is invalid for the specified netCDF dataset.
7214 - The specified corner indices were out of range for the rank of the
7215 specified variable. For example, a negative index or an index that
7216 is larger than the corresponding dimension length will cause an
7218 - The specified edge lengths added to the specified corner would have
7219 referenced data out of range for the rank of the specified variable.
7220 For example, an edge length that is larger than the corresponding
7221 dimension length minus the corner index will cause an error.
7222 - One or more of the values are out of the range of values
7223 representable by the desired type.
7224 - The specified netCDF is in define mode rather than data mode.
7225 - The specified netCDF ID does not refer to an open netCDF dataset.
7230 Here is an example using NF\_GET\_VARA\_DOUBLE to read all the values of
7231 the variable named rh from an existing netCDF dataset named foo.nc. For
7232 simplicity in this example, we ame that we know that rh is
7233 dimensioned with lon, lat, and time, and that there are ten lon values,
7234 five lat values, and three time values.
7239 INCLUDE 'netcdf.inc'
7241 PARAMETER (NDIMS=3) ! number of dimensions
7242 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7243 INTEGER STATUS, NCID
7244 INTEGER RHID ! variable ID
7245 INTEGER START(NDIMS), COUNT(NDIMS)
7246 DOUBLE RHVALS(LONS, LATS, TIMES)
7247 DATA START /1, 1, 1/ ! start at first value
7248 DATA COUNT /LONS, LATS, TIMES/ ! get all the values
7250 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7251 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7253 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7254 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7255 STATUS = NF_GET_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
7256 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7259 6.29 NF\_GET\_VARS\_ type
7260 -------------------------
7262 The NF\_GET\_VARS\_ type family of functions read absampled (strided)
7263 array of values from a netCDF variable of an open netCDF
7264 dataset. Thebsampled array is specified by giving a corner, a
7265 vector of edge lengths, and a stride vector. The values are read with
7266 the first dimension of the netCDF variable varying fastest. The netCDF
7267 dataset must be in data mode.
7275 INTEGER FUNCTION NF_GET_VARS_TEXT (INTEGER NCID, INTEGER VARID,
7276 INTEGER START(*), INTEGER COUNT(*),
7277 INTEGER STRIDE(*),CHARACTER*(*) text)
7278 INTEGER FUNCTION NF_GET_VARS_INT1 (INTEGER NCID, INTEGER VARID,
7279 INTEGER START(*), INTEGER COUNT(*),
7280 INTEGER STRIDE(*),INTEGER*1 i1vals(*))
7281 INTEGER FUNCTION NF_GET_VARS_INT2 (INTEGER NCID, INTEGER VARID,
7282 INTEGER START(*), INTEGER COUNT(*),
7283 INTEGER STRIDE(*),INTEGER*2 i2vals(*))
7284 INTEGER FUNCTION NF_GET_VARS_INT (INTEGER NCID, INTEGER VARID,
7285 INTEGER START(*), INTEGER COUNT(*),
7286 INTEGER STRIDE(*), INTEGER ivals(*))
7287 INTEGER FUNCTION NF_GET_VARS_INT64 (INTEGER NCID, INTEGER VARID,
7288 INTEGER START(*), INTEGER COUNT(*),
7289 INTEGER STRIDE(*), INTEGER*8 i8vals(*))
7290 INTEGER FUNCTION NF_GET_VARS_REAL (INTEGER NCID, INTEGER VARID,
7291 INTEGER START(*), INTEGER COUNT(*),
7292 INTEGER STRIDE(*), REAL rvals(*))
7293 INTEGER FUNCTION NF_GET_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
7294 INTEGER START(*), INTEGER COUNT(*),
7295 INTEGER STRIDE(*), DOUBLE dvals(*))
7299 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7305 : A vector of integers specifying the index in the variable from which
7306 the first of the data values will be read. The indices are relative
7307 to 1, so for example, the first data value of a variable would have
7308 index (1, 1, ..., 1). The elements of START correspond, in order, to
7309 the variable’s dimensions. Hence, if the variable is a record
7310 variable, the last index would correspond to the starting record
7311 number for reading the data values.
7314 : A vector of integers specifying the number of indices selected along
7315 each dimension. To read a single value, for example, specify COUNT
7316 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7317 the variable’s dimensions. Hence, if the variable is a record
7318 variable, the last element of COUNT corresponds to a count of the
7319 number of records to read.
7321 Note: setting any element of the count array to zero causes the
7322 function to exit without error, and without doing anything.
7325 : A vector of integers specifying, for each dimension, the interval
7326 between selected indices or the value 0. The elements of the vector
7327 correspond, in order, to the variable’s dimensions. A value of 1
7328 accesses adjacent values of the netCDF variable in the corresponding
7329 dimension; a value of 2 accesses every other value of the netCDF
7330 variable in the corresponding dimension; and so on. A 0 argument is
7331 treated as (1, 1, ..., 1).
7340 : The block of data values to be read. The data should be of the type
7341 appropriate for the function called. You cannot read CHARACTER data
7342 from a numeric variable or numeric data from a text variable. For
7343 numeric data, if the type of data differs from the netCDF variable
7344 type, type conversion will occur (see [(netcdf)Type
7345 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7346 in The NetCDF Users Guide).
7351 NF\_GET\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
7352 Otherwise, the returned status indicates an error. Possible causes of
7355 - The variable ID is invalid for the specified netCDF dataset.
7356 - The specified start, count and stride generate an index which is out
7358 - One or more of the values are out of the range of values
7359 representable by the desired type.
7360 - The specified netCDF is in define mode rather than data mode.
7361 - The specified netCDF ID does not refer to an open netCDF dataset.
7366 Here is an example using NF\_GET\_VARS\_DOUBLE to read every other value
7367 in each dimension of the variable named rh from an existing netCDF
7368 dataset named foo.nc. Values are assigned, using the same dimensional
7369 strides, to a 2-parameter array. For simplicity in this example, we
7370 ame that we know that rh is dimensioned with lon, lat, and time, and
7371 that there are ten lon values, five lat values, and three time values.
7376 INCLUDE 'netcdf.inc'
7378 PARAMETER (NDIMS=3) ! number of dimensions
7379 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7380 INTEGER STATUS, NCID
7381 INTEGER RHID ! variable ID
7382 INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
7383 DOUBLE DATA(LONS, LATS, TIMES)
7384 DATA START /1, 1, 1/ ! start at first value
7385 DATA COUNT /LONS, LATS, TIMES/
7386 DATA STRIDE /2, 2, 2/
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)
7393 STATUS = NF_GET_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
7394 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7397 6.30 NF\_GET\_VARM\_ type
7398 -------------------------
7400 The NF\_GET\_VARM\_ type family of functions reads a mapped array
7401 section of values from a netCDF variable of an open netCDF dataset. The
7402 mapped array is specified by giving a corner, a vector of edge
7403 lengths, a stride vector, and an index mapping vector. The index mapping
7404 vector is a vector of integers that specifies the mapping between the
7405 dimensions of a netCDF variable and the in-memory structure of the
7406 internal data array. No amptions are made about the ordering or
7407 length of the dimensions of the data array. The netCDF dataset must be
7416 INTEGER FUNCTION NF_GET_VARM_TEXT (INTEGER NCID, INTEGER VARID,
7417 INTEGER START(*), INTEGER COUNT(*),
7418 INTEGER STRIDE(*), INTEGER IMAP(*),
7420 INTEGER FUNCTION NF_GET_VARM_INT1 (INTEGER NCID, INTEGER VARID,
7421 INTEGER START(*), INTEGER COUNT(*),
7422 INTEGER STRIDE(*), INTEGER IMAP(*),
7423 INTEGER*1 i1vals(*))
7424 INTEGER FUNCTION NF_GET_VARM_INT2 (INTEGER NCID, INTEGER VARID,
7425 INTEGER START(*), INTEGER COUNT(*),
7426 INTEGER STRIDE(*), INTEGER IMAP(*),
7427 INTEGER*2 i2vals(*))
7428 INTEGER FUNCTION NF_GET_VARM_INT (INTEGER NCID, INTEGER VARID,
7429 INTEGER START(*), INTEGER COUNT(*),
7430 INTEGER STRIDE(*), INTEGER IMAP(*),
7432 INTEGER FUNCTION NF_GET_VARM_INT64 (INTEGER NCID, INTEGER VARID,
7433 INTEGER START(*), INTEGER COUNT(*),
7434 INTEGER STRIDE(*), INTEGER IMAP(*),
7435 INTEGER*8 i8vals(*))
7436 INTEGER FUNCTION NF_GET_VARM_REAL (INTEGER NCID, INTEGER VARID,
7437 INTEGER START(*), INTEGER COUNT(*),
7438 INTEGER STRIDE(*), INTEGER IMAP(*),
7440 INTEGER FUNCTION NF_GET_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
7441 INTEGER START(*), INTEGER COUNT(*),
7442 INTEGER STRIDE(*), INTEGER IMAP(*),
7447 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7453 : A vector of integers specifying the index in the variable from which
7454 the first of the data values will be read. The indices are relative
7455 to 1, so for example, the first data value of a variable would have
7456 index (1, 1, ..., 1). The elements of START correspond, in order, to
7457 the variable’s dimensions. Hence, if the variable is a record
7458 variable, the last index would correspond to the starting record
7459 number for reading the data values.
7462 : A vector of integers specifying the number of indices selected along
7463 each dimension. To read a single value, for example, specify COUNT
7464 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7465 the variable’s dimensions. Hence, if the variable is a record
7466 variable, the last element of COUNT corresponds to a count of the
7467 number of records to read.
7469 Note: setting any element of the count array to zero causes the
7470 function to exit without error, and without doing anything.
7473 : A vector of integers specifying, for each dimension, the interval
7474 between selected indices or the value 0. The elements of the vector
7475 correspond, in order, to the variable’s dimensions. A value of 1
7476 accesses adjacent values of the netCDF variable in the corresponding
7477 dimension; a value of 2 accesses every other value of the netCDF
7478 variable in the corresponding dimension; and so on. A 0 argument is
7479 treated as (1, 1, ..., 1).
7482 : A vector of integers that specifies the mapping between the
7483 dimensions of a netCDF variable and the in-memory structure of the
7484 internal data array. IMAP(1) gives the distance between elements of
7485 the internal array corresponding to the most rapidly varying
7486 dimension of the netCDF variable. IMAP(N) (where N is the rank of
7487 the netCDF variable) gives the distance between elements of the
7488 internal array corresponding to the most slowly varying dimension of
7489 the netCDF variable. Intervening IMAP elements correspond to other
7490 dimensions of the netCDF variable in the obvious way. Distances
7491 between elements are specified in units of elements (the distance
7492 between internal elements that occupy adjacent memory locations is 1
7493 and not the element’s byte-length as in netCDF 2).
7502 : The block of data values to be read. The data should be of the type
7503 appropriate for the function called. You cannot read CHARACTER data
7504 from a numeric variable or numeric data from a text variable. For
7505 numeric data, if the type of data differs from the netCDF variable
7506 type, type conversion will occur (see [(netcdf)Type
7507 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7508 in The NetCDF Users Guide).
7513 NF\_GET\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
7514 Otherwise, the returned status indicates an error. Possible causes of
7517 - The variable ID is invalid for the specified netCDF dataset.
7518 - The specified START, COUNT, and STRIDE generate an index which is
7519 out of range. Note that no error checking is possible on the imap
7521 - One or more of the values are out of the range of values
7522 representable by the desired type.
7523 - The specified netCDF is in define mode rather than data mode.
7524 - The specified netCDF ID does not refer to an open netCDF dataset.
7529 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
7530 variable and an internal array of the same shape:
7535 REAL A(2,3,4) ! same shape as netCDF variable
7537 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
7538 ! ---------------- ----------------------
7539 ! most rapidly varying 1
7540 ! intermediate 2 (=IMAP(1)*2)
7541 ! most slowly varying 6 (=IMAP(2)*3)
7544 Using the IMAP vector above with NF\_GET\_VARM\_REAL obtains the same
7545 rlt as simply using NF\_GET\_VAR\_REAL.
7547 Here is an example of using NF\_GET\_VARM\_REAL to transpose a netCDF
7548 variable named rh which is described by the FORTRAN declaration REAL
7549 RH(4,6) (note the size and order of the dimensions):
7554 INCLUDE 'netcdf.inc'
7556 PARAMETER (NDIM=2) ! rank of netCDF variable
7557 INTEGER NCID ! netCDF dataset ID
7558 INTEGER STATUS ! return code
7559 INTEGER RHID ! variable ID
7560 INTEGER START(NDIM) ! netCDF variable start point
7561 INTEGER COUNT(NDIM) ! size of internal array
7562 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7563 INTEGER IMAP(NDIM) ! internal array inter-element distances
7564 REAL RH(6,4) ! note transposition of netCDF variable dimensions
7565 DATA START /1, 1/ ! start at first netCDF variable element
7566 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
7567 ! to netCDF variable -- not internal array
7568 DATA STRIDE /1, 1/ ! sample every netCDF element
7569 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
7571 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7572 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7574 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7575 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7577 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7578 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7581 Here is another example of using NF\_GET\_VARM\_REAL to simultaneously
7582 transpose andbsample the same netCDF variable, by accessing every
7583 other point of the netCDF variable:
7588 INCLUDE 'netcdf.inc'
7590 PARAMETER (NDIM=2) ! rank of netCDF variable
7591 INTEGER NCID ! netCDF dataset ID
7592 INTEGER STATUS ! return code
7593 INTEGER RHID ! variable ID
7594 INTEGER START(NDIM) ! netCDF variable start point
7595 INTEGER COUNT(NDIM) ! size of internal array
7596 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7597 INTEGER IMAP(NDIM) ! internal array inter-element distances
7598 REAL RH(3,2) ! note transposition of bsampled) dimensions
7599 DATA START /1, 1/ ! start at first netCDF variable value
7600 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
7601 ! to netCDF variable -- not internal array
7602 DATA STRIDE /2, 2/ ! sample every other netCDF element
7603 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
7605 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7606 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7608 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7609 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7611 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7612 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7615 6.31 Reading and Writing Character String Values
7616 ------------------------------------------------
7618 Character strings are not a primitive netCDF external data type, in part
7619 because FORTRAN does notpport the abstraction of variable-length
7620 character strings (the FORTRAN LEN function returns the static length of
7621 a character string, not its dynamic length). As a rlt, a character
7622 string cannot be written or read as a single object in the netCDF
7623 interface. Instead, a character string must be treated as an array of
7624 characters, and array access must be used to read and write character
7625 strings as variable data in netCDF datasets. Furthermore,
7626 variable-length strings are notpported by the netCDF interface except
7627 by convention; for example, you may treat a zero byte as terminating a
7628 character string, but you must explicitly specify the length of strings
7629 to be read from and written to netCDF variables.
7631 Character strings as attribute values are easier to use, since the
7632 strings are treated as a single unit for access. However, the value of a
7633 character-string attribute is still an array of characters with an
7634 explicit length that must be specified when the attribute is defined.
7636 When you define a variable that will have character-string values, use a
7637 character-position dimension as the most quickly varying dimension for
7638 the variable (the first dimension for the variable in FORTRAN). The
7639 length of the character-position dimension will be the maximum string
7640 length of any value to be stored in the character-string variable. Space
7641 for maximum-length strings will be allocated in the disk representation
7642 of character-string variables whether you use the space or not. If two
7643 or more variables have the same maximum length, the same
7644 character-position dimension may be used in defining the variable
7647 To write a character-string value into a character-string variable, use
7648 either entire variable access or array access. The latter requires that
7649 you specify both a corner and a vector of edge lengths. The
7650 character-position dimension at the corner should be one for FORTRAN. If
7651 the length of the string to be written is n, then the vector of edge
7652 lengths will specify n in the character-position dimension, and one for
7653 all the other dimensions:(n, 1, 1, ..., 1).
7655 In FORTRAN, fixed-length strings may be written to a netCDF dataset
7656 without a terminating character, to save space. Variable-length strings
7657 should follow the C convention of writing strings with a terminating
7658 zero byte so that the intended length of the string can be determined
7659 when it is later read by either C or FORTRAN programs.
7661 The FORTRAN interface for reading and writing strings requires the use
7662 of different functions for accessing string values and numeric values,
7663 because standard FORTRAN does not permit the same formal parameter to be
7664 used for both character values and numeric values. An additional
7665 argument, specifying the declared length of the character string passed
7666 as a value, is required for NF\_PUT\_VARA\_TEXT and NF\_GET\_VARA\_TEXT.
7667 The actual length of the string is specified as the value of the
7668 edge-length vector corresponding to the character-position dimension.
7670 Here is an example that defines a record variable, tx, for character
7671 strings and stores a character-string value into the third record using
7672 NF\_PUT\_VARA\_TEXT. In this example, we ame the string variable and
7673 data are to be added to an existing netCDF dataset named foo.nc that
7674 already has an unlimited record dimension time.
7679 INCLUDE 'netcdf.inc'
7681 INTEGER TDIMS, TXLEN
7682 PARAMETER (TDIMS=2) ! number of TX dimensions
7683 PARAMETER (TXLEN = 15) ! length of example string
7685 INTEGER CHID ! char position dimension id
7686 INTEGER TIMEID ! record dimension id
7687 INTEGER TXID ! variable ID
7688 INTEGER TXDIMS(TDIMS) ! variable shape
7689 INTEGER TSTART(TDIMS), TCOUNT(TDIMS)
7690 CHARACTER*40 TXVAL ! max length 40
7691 DATA TXVAL /'example string'/
7693 TXVAL(TXLEN:TXLEN) = CHAR(0) ! null terminate
7695 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
7696 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7697 STATUS = NF_REDEF(NCID) ! enter define mode
7698 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7700 ! define character-position dimension for strings of max length 40
7701 STATUS = NF_DEF_DIM(NCID, "chid", 40, CHID)
7702 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7704 ! define a character-string variable
7705 TXDIMS(1) = CHID ! character-position dimension first
7707 STATUS = NF_DEF_VAR(NCID, "tx", NF_CHAR, TDIMS, TXDIMS, TXID)
7708 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7710 STATUS = NF_ENDDEF(NCID) ! leave define mode
7711 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7713 ! write txval into tx netCDF variable in record 3
7714 TSTART(1) = 1 ! start at beginning of variable
7715 TSTART(2) = 3 ! record number to write
7716 TCOUNT(1) = TXLEN ! number of chars to write
7717 TCOUNT(2) = 1 ! only write one record
7718 STATUS = NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL)
7719 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7725 What happens when you try to read a value that was never written in an
7726 open netCDF dataset? You might expect that this should always be an
7727 error, and that you should get an error message or an error status
7728 returned. You do get an error if you try to read data from a netCDF
7729 dataset that is not open for reading, if the variable ID is invalid for
7730 the specified netCDF dataset, or if the specified indices are not
7731 properly within the range defined by the dimension lengths of the
7732 specified variable. Otherwise, reading a value that was not written
7733 returns a special fill value used to fill in any undefined values when a
7734 netCDF variable is first written.
7736 You may ignore fill values and use the entire range of a netCDF external
7737 data type, but in this case you should makere you write all data
7738 values before reading them. If you know you will be writing all the data
7739 before reading it, you can specify that no prefilling of variables with
7740 fill values will occur by calling NF\_SET\_FILL before writing. This may
7741 provide a significant performance gain for netCDF writes.
7743 The variable attribute \_FillValue may be used to specify the fill value
7744 for a variable. Their are default fill values for each type, defined in
7745 the include file netcdf.inc: NF\_FILL\_CHAR, NF\_FILL\_INT1 (same as
7746 NF\_FILL\_BYTE), NF\_FILL\_INT2 (same as NF\_FILL\_SHORT),
7747 NF\_FILL\_INT, NF\_FILL\_REAL (same as NF\_FILL\_FLOAT), and
7750 The netCDF byte and character types have different default fill values.
7751 The default fill value for characters is the zero byte, a useful value
7752 for detecting the end of variable-length C character strings. If you
7753 need a fill value for a byte variable, it is recommended that you
7754 explicitly define an appropriate \_FillValue attribute, as generic
7755 utilitiesch as ncdump will not ame a default fill value for byte
7758 Type conversion for fill values is identical to type conversion for
7759 other values: attempting to convert a value from one type to another
7760 type that can’t represent the value rlts in a range error. Such
7761 errors may occur on writing or reading values from a larger type ch
7762 as double) to a smaller type ch as float), if the fill value for the
7763 larger type cannot be represented in the smaller type.
7765 6.33 NF\_RENAME\_VAR
7766 --------------------
7768 The function NF\_RENAME\_VAR changes the name of a netCDF variable in an
7769 open netCDF dataset. If the new name is longer than the old name, the
7770 netCDF dataset must be in define mode. You cannot rename a variable to
7771 have the name of any existing variable.
7779 INTEGER FUNCTION NF_RENAME_VAR (INTEGER NCID, INTEGER VARID,
7780 CHARACTER*(*) NEWNAM)
7784 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7790 : New name for the specified variable.
7795 NF\_RENAME\_VAR returns the value NF\_NOERR if no errors occurred.
7796 Otherwise, the returned status indicates an error. Possible causes of
7799 - The new name is in use as the name of another variable.
7800 - The variable ID is invalid for the specified netCDF dataset.
7801 - The specified netCDF ID does not refer to an open netCDF dataset.
7806 Here is an example using NF\_RENAME\_VAR to rename the variable rh to
7807 rel\_hum in an existing netCDF dataset named foo.nc:
7812 INCLUDE 'netcdf.inc'
7814 INTEGER STATUS, NCID
7815 INTEGER RHID ! variable ID
7817 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7818 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7820 STATUS = NF_REDEF (NCID) ! enter definition mode
7821 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7822 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7823 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7824 STATUS = NF_RENAME_VAR (NCID, RHID, 'rel_hum')
7825 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7826 STATUS = NF_ENDDEF (NCID) ! leave definition mode
7827 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7831 6.34 Change between Collective and Independent Parallel Access: NF\_VAR\_PAR\_ACCESS
7832 ------------------------------------------------------------------------------------
7834 The function NF\_VAR\_PAR\_ACCESS changes whether read/write operations
7835 on a parallel file system are performed collectively or independently
7836 (the default) on the variable. This function can only be called if the
7837 file was created with NF\_CREATE\_PAR (see
7838 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)) or opened with NF\_OPEN\_PAR
7839 (see [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)).
7841 This function is only available if the netCDF library was built with a
7842 HDF5 library for which –enable-parallel was used, and which was linked
7843 (like HDF5) to MPI libraries.
7845 Calling this function affects only the open file - information about
7846 whether a variable is to be accessed collectively or independently is
7847 not written to the data file. Every time you open a file on a parallel
7848 file system, all variables default to independent operations. The change
7849 a variable to collective lasts only as long as that file is open.
7851 The variable can be changed from collective to independent, and back, as
7860 INTEGER NF_VAR_PAR_ACCESS(INTEGER NCID, INTEGER VARID, INTEGER ACCESS);
7864 : NetCDF ID, from a previous call to NF\_OPEN\_PAR (see
7865 [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)) or NF\_CREATE\_PAR (see
7866 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)).
7872 : NF\_INDEPENDENT to set this variable to independent operations.
7873 NF\_COLLECTIVE to set it to collective operations.
7882 : No variable found.
7885 : Not a netCDF-4 file.
7888 : File not opened for parallel access.
7893 This example comes from test program nf\_test/ftst\_parallel.F. For this
7894 test to be run, netCDF must have been built with a parallel-enabled
7895 HDF5, and –enable-parallel-tests must have been used when configuring
7901 retval = nf_var_par_access(ncid, varid, nf_collective)
7902 if (retval .ne. nf_noerr) stop 2
7909 7.1 Attributes Introduction
7910 ---------------------------
7912 Attributes may be associated with each netCDF variable to specifych
7913 properties as units, special values, maximum and minimum valid values,
7914 scaling factors, and offsets. Attributes for a netCDF dataset are
7915 defined when the dataset is first created, while the netCDF dataset is
7916 in define mode. Additional attributes may be added later by reentering
7917 define mode. A netCDF attribute has a netCDF variable to which it is
7918 assigned, a name, a type, a length, and a sequence of one or more
7919 values. An attribute is designated by its variable ID and name. When an
7920 attribute name is not known, it may be designated by its variable ID and
7921 number in order to determine its name, using the function
7924 The attributes associated with a variable are typically defined
7925 immediately after the variable is created, while still in define mode.
7926 The data type, length, and value of an attribute may be changed even
7927 when in data mode, as long as the changed attribute requires no more
7928 space than the attribute as originally defined.
7930 It is also possible to have attributes that are not associated with any
7931 variable. These are called global attributes and are identified by using
7932 NF\_GLOBAL as a variable pseudo-ID. Global attributes are ally
7933 related to the netCDF dataset as a whole and may be used for purposes
7934 such as providing a title or processing history for a netCDF dataset.
7936 Attributes are much more useful when they follow established community
7937 conventions. See [(netcdf)Attribute
7938 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
7939 Conventions’ in The NetCDF Users Guide.
7941 Operationspported on attributes are:
7943 - Create an attribute, given its variable ID, name, data type, length,
7945 - Get attribute’s data type and length from its variable ID and name.
7946 - Get attribute’s value from its variable ID and name.
7947 - Copy attribute from one netCDF variable to another.
7948 - Get name of attribute from its number.
7949 - Rename an attribute.
7950 - Delete an attribute.
7952 7.2 NF\_PUT\_ATT\_ type
7953 -----------------------
7955 The function NF\_PUT\_ATT\_ type adds or changes a variable attribute or
7956 global attribute of an open netCDF dataset. If this attribute is new, or
7957 if the space required to store the attribute is greater than before, the
7958 netCDF dataset must be in define mode.
7963 Although it’s possible to create attributes of all types, text and
7964 double attributes are adequate for most purposes.
7969 INTEGER FUNCTION NF_PUT_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7970 CHARACTER*(*) NAME, INTEGER LEN,
7972 INTEGER FUNCTION NF_PUT_ATT_INT1 (INTEGER NCID, INTEGER VARID,
7973 CHARACTER*(*) NAME, INTEGER XTYPE,
7974 LEN, INTEGER*1 I1VALS(*))
7975 INTEGER FUNCTION NF_PUT_ATT_INT2 (INTEGER NCID, INTEGER VARID,
7976 CHARACTER*(*) NAME, INTEGER XTYPE,
7977 LEN, INTEGER*2 I2VALS(*))
7978 INTEGER FUNCTION NF_PUT_ATT_INT (INTEGER NCID, INTEGER VARID,
7979 CHARACTER*(*) NAME, INTEGER XTYPE,
7980 LEN, INTEGER IVALS(*))
7981 INTEGER FUNCTION NF_PUT_ATT_INT64 (INTEGER NCID, INTEGER VARID,
7982 CHARACTER*(*) NAME, INTEGER XTYPE,
7983 LEN, INTEGER*8 I8VALS(*))
7984 INTEGER FUNCTION NF_PUT_ATT_REAL (INTEGER NCID, INTEGER VARID,
7985 CHARACTER*(*) NAME, INTEGER XTYPE,
7987 INTEGER FUNCTION NF_PUT_ATT_DOUBLE(INTEGER NCID, INTEGER VARID,
7988 CHARACTER*(*) NAME, INTEGER XTYPE,
7989 LEN, DOUBLE DVALS(*))
7990 INTEGER FUNCTION NF_PUT_ATT (INTEGER NCID, INTEGER VARID,
7991 CHARACTER*(*) NAME, INTEGER XTYPE,
7996 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7999 : Variable ID of the variable to which the attribute will be assigned
8000 or NF\_GLOBAL for a global attribute.
8003 : Attribute name. Attribute name conventions are amed by some
8004 netCDF generic applications, e.g., ‘units’ as the name for a string
8005 attribute that gives the units for a netCDF variable. See
8006 [(netcdf)Attribute Conventions](netcdf.html#Attribute-Conventions)
8007 ‘Attribute Conventions’ in The NetCDF Users Guide.
8010 : One of the set of predefined netCDF external data types. The type of
8011 this parameter, NF\_TYPE, is defined in the netCDF header file. The
8012 valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
8013 NF\_INT, NF\_FLOAT, and NF\_DOUBLE. Although it’s possible to create
8014 attributes of all types, NF\_CHAR and NF\_DOUBLE attributes are
8015 adequate for most purposes.
8018 : Number of values provided for the attribute.
8028 : An array of LEN attribute values. The data should be of a type
8029 appropriate for the function called. You cannot write CHARACTER data
8030 into a numeric attribute or numeric data into a text attribute. For
8031 numeric data, if the type of data differs from the attribute type,
8032 type conversion will occur See [(netcdf)Type
8033 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
8034 in The NetCDF Users Guide.
8039 NF\_PUT\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
8040 Otherwise, the returned status indicates an error. Possible causes of
8043 - The variable ID is invalid for the specified netCDF dataset.
8044 - The specified netCDF type is invalid.
8045 - The specified length is negative.
8046 - The specified open netCDF dataset is in data mode and the specified
8047 attribute would expand.
8048 - The specified open netCDF dataset is in data mode and the specified
8049 attribute does not already exist.
8050 - The specified netCDF ID does not refer to an open netCDF dataset.
8051 - The number of attributes for this variable exceeds NF\_MAX\_ATTRS.
8056 Here is an example using NF\_PUT\_ATT\_DOUBLE to add a variable
8057 attribute named valid\_range for a netCDF variable named rh and a global
8058 attribute named title to an existing netCDF dataset named foo.nc:
8063 INCLUDE 'netcdf.inc'
8065 INTEGER STATUS, NCID
8066 INTEGER RHID ! variable ID
8068 DATA RHRNGE /0.0D0, 100.0D0/
8070 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8071 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8073 STATUS = NF_REDEF (NCID) ! enter define mode
8074 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8075 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8076 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8078 STATUS = NF_PUT_ATT_DOUBLE (NCID, RHID, 'valid_range', NF_DOUBLE, &
8080 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8081 STATUS = NF_PUT_ATT_TEXT (NCID, NF_GLOBAL, 'title', 19,
8082 'example netCDF dataset')
8083 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8085 STATUS = NF_ENDDEF (NCID) ! leave define mode
8086 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8089 7.3 NF\_INQ\_ATT Family
8090 -----------------------
8092 This family of functions returns information about a netCDF attribute.
8093 All but one of these functions require the variable ID and attribute
8094 name; the exception is NF\_INQ\_ATTNAME. Information about an attribute
8095 includes its type, length, name, and number. See the NF\_GET\_ATT family
8096 for getting attribute values.
8098 The function NF\_INQ\_ATTNAME gets the name of an attribute, given its
8099 variable ID and number. This function is useful in generic applications
8100 that need to get the names of all the attributes associated with a
8101 variable, since attributes are accessed by name rather than number in
8102 all other attribute functions. The number of an attribute is more
8103 volatile than the name, since it can change when other attributes of the
8104 same variable are deleted. This is why an attribute number is not called
8107 The function NF\_INQ\_ATT returns the attribute’s type and length. The
8108 other functions each return just one item of information about an
8117 INTEGER FUNCTION NF_INQ_ATT (INTEGER NCID, INTEGER VARID,
8118 CHARACTER*(*) NAME, INTEGER xtype,
8120 INTEGER FUNCTION NF_INQ_ATTTYPE(INTEGER NCID, INTEGER VARID,
8121 CHARACTER*(*) NAME, INTEGER xtype)
8122 INTEGER FUNCTION NF_INQ_ATTLEN (INTEGER NCID, INTEGER VARID,
8123 CHARACTER*(*) NAME, INTEGER len)
8124 INTEGER FUNCTION NF_INQ_ATTNAME(INTEGER NCID, INTEGER VARID,
8125 INTEGER ATTNUM, CHARACTER*(*) name)
8126 INTEGER FUNCTION NF_INQ_ATTID (INTEGER NCID, INTEGER VARID,
8127 CHARACTER*(*) NAME, INTEGER attnum)
8131 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8134 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
8138 : Attribute name. For NF\_INQ\_ATTNAME, this is a pointer to the
8139 location for the returned attribute name.
8142 : Returned attribute type, one of the set of predefined netCDF
8143 external data types. The valid netCDF external data types are
8144 NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, and NF\_DOUBLE.
8147 : Returned number of values currently stored in the attribute. For a
8148 string-valued attribute, this is the number of characters in the
8152 : For NF\_INQ\_ATTNAME, the input attribute number; for
8153 NF\_INQ\_ATTID, the returned attribute number. The attributes for
8154 each variable are numbered from 1 (the first attribute) to NATTS,
8155 where NATTS is the number of attributes for the variable, as
8156 returned from a call to NF\_INQ\_VARNATTS.
8158 (If you already know an attribute name, knowing its number is not
8159 very useful, because accessing information about an attribute
8165 Each function returns the value NF\_NOERR if no errors occurred.
8166 Otherwise, the returned status indicates an error. Possible causes of
8169 - The variable ID is invalid for the specified netCDF dataset.
8170 - The specified attribute does not exist.
8171 - The specified netCDF ID does not refer to an open netCDF dataset.
8172 - For NF\_INQ\_ATTNAME, the specified attribute number is negative or
8173 more than the number of attributes defined for the specified
8179 Here is an example using NF\_INQ\_ATT to find out the type and length of
8180 a variable attribute named valid\_range for a netCDF variable named rh
8181 and a global attribute named title in an existing netCDF dataset named
8187 INCLUDE 'netcdf.inc'
8189 INTEGER STATUS, NCID
8190 INTEGER RHID ! variable ID
8191 INTEGER VRLEN, TLEN ! attribute lengths
8193 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
8194 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8196 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8197 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8199 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
8200 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8201 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
8202 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8205 7.4 NF\_GET\_ATT\_ type
8206 -----------------------
8208 Members of the NF\_GET\_ATT\_ type family of functions get the value(s)
8209 of a netCDF attribute, given its variable ID and name.
8217 INTEGER FUNCTION NF_GET_ATT_TEXT (INTEGER NCID, INTEGER VARID,
8220 INTEGER FUNCTION NF_GET_ATT_INT1 (INTEGER NCID, INTEGER VARID,
8222 INTEGER*1 i1vals(*))
8223 INTEGER FUNCTION NF_GET_ATT_INT2 (INTEGER NCID, INTEGER VARID,
8225 INTEGER*2 i2vals(*))
8226 INTEGER FUNCTION NF_GET_ATT_INT (INTEGER NCID, INTEGER VARID,
8229 INTEGER FUNCTION NF_GET_ATT_INT64 (INTEGER NCID, INTEGER VARID,
8231 INTEGER*8 i8vals(*))
8232 INTEGER FUNCTION NF_GET_ATT_REAL (INTEGER NCID, INTEGER VARID,
8235 INTEGER FUNCTION NF_GET_ATT_DOUBLE (INTEGER NCID, INTEGER VARID,
8238 INTEGER FUNCTION NF_GET_ATT (INTEGER NCID, INTEGER VARID,
8239 CHARACTER*(*) NAME, * vals(*))
8243 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8246 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
8260 : Returned attribute values. All elements of the vector of attribute
8261 values are returned, so you must provide enough space to hold them.
8262 If you don’t know how much space to reserve, call NF\_INQ\_ATTLEN
8263 first to find out the length of the attribute. You cannot read
8264 character data from a numeric variable or numeric data from a text
8265 variable. For numeric data, if the type of data differs from the
8266 netCDF variable type, type conversion will occur. See [(netcdf)Type
8267 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
8268 in The The NetCDF Users Guide.
8273 NF\_GET\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
8274 Otherwise, the returned status indicates an error. Possible causes of
8277 - The variable ID is invalid for the specified netCDF dataset.
8278 - The specified attribute does not exist.
8279 - The specified netCDF ID does not refer to an open netCDF dataset.
8280 - One or more of the attribute values are out of the range of values
8281 representable by the desired type.
8286 Here is an example using NF\_GET\_ATT\_DOUBLE to determine the values of
8287 a variable attribute named valid\_range for a netCDF variable named rh
8288 and a global attribute named title in an existing netCDF dataset named
8289 foo.nc. In this example, it is amed that we don’t know how many
8290 values will be returned, but that we do know the types of the
8291 attributes. Hence, to allocate enough space to store them, we must first
8292 inquire about the length of the attributes.
8297 INCLUDE 'netcdf.inc'
8299 PARAMETER (MVRLEN=3) ! max number of "valid_range" values
8300 PARAMETER (MTLEN=80) ! max length of "title" attribute
8301 INTEGER STATUS, NCID
8302 INTEGER RHID ! variable ID
8303 INTEGER VRLEN, TLEN ! attribute lengths
8304 DOUBLE PRECISION VRVAL(MVRLEN) ! vr attribute values
8305 CHARACTER*80 TITLE ! title attribute values
8307 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8308 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8310 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8311 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8313 ! find out attribute lengths, to makere we have enough space
8314 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
8315 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8316 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
8317 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8318 ! get attribute values, if not too big
8319 IF (VRLEN .GT. MVRLEN) THEN
8320 WRITE (*,*) 'valid_range attribute too big!'
8323 STATUS = NF_GET_ATT_DOUBLE (NCID, RHID, 'valid_range', VRVAL)
8324 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8326 IF (TLEN .GT. MTLEN) THEN
8327 WRITE (*,*) 'title attribute too big!'
8330 STATUS = NF_GET_ATT_TEXT (NCID, NF_GLOBAL, 'title', TITLE)
8331 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8338 The function NF\_COPY\_ATT copies an attribute from one open netCDF
8339 dataset to another. It can also be used to copy an attribute from one
8340 variable to another within the same netCDF.
8342 If used to copy an attribute of user-defined type, then that
8343 user-defined type must already be defined in the target file. In the
8344 case of user-defined attributes, enddef/redef is called for ncid\_in and
8345 ncid\_out if they are in define mode. (This is the ere that all
8346 user-defined types are committed to the file(s) before the copy is
8355 INTEGER FUNCTION NF_COPY_ATT (INTEGER NCID_IN, INTEGER VARID_IN,
8356 CHARACTER*(*) NAME, INTEGER NCID_OUT,
8361 : The netCDF ID of an input netCDF dataset from which the attribute
8362 will be copied, from a previous call to NF\_OPEN or NF\_CREATE.
8365 : ID of the variable in the input netCDF dataset from which the
8366 attribute will be copied, or NF\_GLOBAL for a global attribute.
8369 : Name of the attribute in the input netCDF dataset to be copied.
8372 : The netCDF ID of the output netCDF dataset to which the attribute
8373 will be copied, from a previous call to NF\_OPEN or NF\_CREATE. It
8374 is permissible for the input and output netCDF IDs to be the same.
8375 The output netCDF dataset should be in define mode if the attribute
8376 to be copied does not already exist for the target variable, or if
8377 it would cause an existing target attribute to grow.
8380 : ID of the variable in the output netCDF dataset to which the
8381 attribute will be copied, or NF\_GLOBAL to copy to a global
8387 NF\_COPY\_ATT returns the value NF\_NOERR if no errors occurred.
8388 Otherwise, the returned status indicates an error. Possible causes of
8391 - The input or output variable ID is invalid for the specified netCDF
8393 - The specified attribute does not exist.
8394 - The output netCDF is not in define mode and the attribute is new for
8395 the output dataset is larger than the existing attribute.
8396 - The input or output netCDF ID does not refer to an open netCDF
8402 Here is an example using NF\_COPY\_ATT to copy the variable attribute
8403 units from the variable rh in an existing netCDF dataset named foo.nc to
8404 the variable avgrh in another existing netCDF dataset named bar.nc,
8405 aming that the variable avgrh already exists, but does not yet have a
8411 INCLUDE 'netcdf.inc'
8413 INTEGER STATUS ! error status
8414 INTEGER NCID1, NCID2 ! netCDF IDs
8415 INTEGER RHID, AVRHID ! variable IDs
8417 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID1)
8418 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8419 STATUS = NF_OPEN ('bar.nc', NF_WRITE, NCID2)
8420 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8422 STATUS = NF_INQ_VARID (NCID1, 'rh', RHID)
8423 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8424 STATUS = NF_INQ_VARID (NCID2, 'avgrh', AVRHID)
8425 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8427 STATUS = NF_REDEF (NCID2) ! enter define mode
8428 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8429 ! copy variable attribute from "rh" to "avgrh"
8430 STATUS = NF_COPY_ATT (NCID1, RHID, 'units', NCID2, AVRHID)
8431 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8433 STATUS = NF_ENDDEF (NCID2) ! leave define mode
8434 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8440 The function NF\_RENAME\_ATT changes the name of an attribute. If the
8441 new name is longer than the original name, the netCDF dataset must be in
8442 define mode. You cannot rename an attribute to have the same name as
8443 another attribute of the same variable.
8451 INTEGER FUNCTION NF_RENAME_ATT (INTEGER NCID, INTEGER VARID,
8453 CHARACTER*(*) NEWNAME)
8457 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE
8460 : ID of the attribute’s variable, or NF\_GLOBAL for a global attribute
8463 : The current attribute name.
8466 : The new name to be assigned to the specified attribute. If the new
8467 name is longer than the current name, the netCDF dataset must be in
8473 NF\_RENAME\_ATT returns the value NF\_NOERR if no errors occurred.
8474 Otherwise, the returned status indicates an error. Possible causes of
8477 - The specified variable ID is not valid.
8478 - The new attribute name is already in use for another attribute of
8479 the specified variable.
8480 - The specified netCDF dataset is in data mode and the new name is
8481 longer than the old name.
8482 - The specified attribute does not exist.
8483 - The specified netCDF ID does not refer to an open netCDF dataset.
8488 Here is an example using NF\_RENAME\_ATT to rename the variable
8489 attribute units to Units for a variable rh in an existing netCDF dataset
8495 INCLUDE "netcdf.inc"
8497 INTEGER STATUS ! error status
8498 INTEGER NCID ! netCDF ID
8499 INTEGER RHID ! variable ID
8501 STATUS = NF_OPEN ("foo.nc", NF_NOWRITE, NCID)
8502 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8504 STATUS = NF_INQ_VARID (NCID, "rh", RHID)
8505 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8508 STATUS = NF_RENAME_ATT (NCID, RHID, "units", "Units")
8509 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8515 The function NF\_DEL\_ATT deletes a netCDF attribute from an open netCDF
8516 dataset. The netCDF dataset must be in define mode.
8521 INTEGER FUNCTION NF\_DEL\_ATT (INTEGER NCID, INTEGER VARID,
8522 CHARACTER\*(\*) NAME)
8525 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8528 : ID of the attribute’s variable, or NF\_GLOBAL for a global
8532 : The name of the attribute to be deleted.
8537 NF\_DEL\_ATT returns the value NF\_NOERR if no errors occurred.
8538 Otherwise, the returned status indicates an error. Possible causes of
8541 - The specified variable ID is not valid.
8542 - The specified netCDF dataset is in data mode.
8543 - The specified attribute does not exist.
8544 - The specified netCDF ID does not refer to an open netCDF dataset.
8549 Here is an example using NF\_DEL\_ATT to delete the variable attribute
8550 Units for a variable rh in an existing netCDF dataset named foo.nc:
8555 INCLUDE 'netcdf.inc'
8557 INTEGER STATUS ! error status
8558 INTEGER NCID ! netCDF ID
8559 INTEGER RHID ! variable ID
8561 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8562 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8564 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8565 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8568 STATUS = NF_REDEF (NCID) ! enter define mode
8569 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8570 STATUS = NF_DEL_ATT (NCID, RHID, 'Units')
8571 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8572 STATUS = NF_ENDDEF (NCID) ! leave define mode
8573 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8576 A. NetCDF 2 to NetCDF 3 Fortran 77 Transition Guide {#f77_nc2_to_nc3_transition_guide}
8577 ===================================================
8579 A.1 Overview of FORTRAN interface changes {#f77_overview_of_interface_changes}
8580 -----------------------------------------
8582 NetCDF version 3 includes a complete rewrite of the netCDF library. It
8583 is about twice as fast as the previous version. The netCDF file format
8584 is unchanged, so files written with version 3 can be read with version 2
8585 code and vice versa.
8587 The core library is now written in ANSI C. You must have an ANSI C
8588 compiler to compile this version. The FORTRAN interface is layered on
8589 top of the C interface using a different technique than was used in
8592 Rewriting the library offered an opportunity to implement improved C and
8593 FORTRAN interfaces that provide some significant benefits:
8595 - type safety, by eliminating the need to use type punning in
8597 - automatic type conversions, by eliminating the undesirable coupling
8598 between the language-independent external netCDF types (NF\_BYTE,
8599 ..., NF\_DOUBLE) and language-dependent internal data types (INT\*1,
8600 ..., DOUBLE PRECISION);
8601 - pport for future enhancements, by eliminating obstacles to the
8602 clean addition ofpport for packed data and multithreading;
8603 - more standard error behavior, by uniformly communicating an error
8604 status back to the calling program in the return value of each
8607 It is not necessary to rewrite programs that use the version 2 FORTRAN
8608 interface, because the netCDF-3 library includes a backward
8609 compatibility interface thatpports all the old functions, globals,
8610 and behavior. We are hoping that the benefits of the new interface will
8611 be an incentive to use it in new netCDF applications. It is possible to
8612 convert old applications to the new interface incrementally, replacing
8613 netCDF-2 calls with the corresponding netCDF-3 calls one at a time.
8615 Other changes in the implementation of netCDF rlt in improved
8616 portability, maintainability, and performance on most platforms. A clean
8617 separation between I/O and type layers facilitates platform-specific
8618 optimizations. The new library no longer uses a vendor-provided XDR
8619 library, which simplifies linking programs that use netCDF and speeds up
8620 data access significantly in most cases.
8622 A.2 The New FORTRAN Interface {#f77_new_fortran_interface}
8623 -----------------------------
8625 First, here’s an example of FORTRAN code that uses the netCDF-2
8631 ! Use a buffer big enough for values of any type
8632 DOUBLE PRECISION DBUF(NDATA)
8635 EQUIVALENCE (RBUF, DBUF), ...
8636 INT XTYPE ! to hold the actual type of the data
8637 INT STATUS ! for error status
8638 ! Get the actual data type
8639 CALL NCVINQ(NCID, VARID, ...,XTYPE, ...)
8642 CALL NCVGT(NCID, VARID, START, COUNT, DBUF, STATUS)
8643 IF(STATUS .NE. NCNOERR) THEN
8644 PRINT *, 'Cannot get data, error code =', STATUS
8648 IF (XTYPE .EQ. NCDOUBLE) THEN
8650 ELSEIF (XTYPE .EQ. NCFLOAT) THEN
8656 Here’s how you might handle this with the new netCDF-3 FORTRAN
8662 ! I want to use doubles for my analysis
8663 DOUBLE PRECISION DBUF(NDATA)
8665 ! So I use a function that gets the data as doubles.
8666 STATUS = NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, DBUF)
8667 IF(STATUS .NE. NF_NOERR) THEN
8668 PRINT *, 'Cannot get data, ', NF_STRERROR(STATUS)
8675 The example above illustrates changes in function names, data type
8676 conversion, and error handling, discussed in detail in thes
8679 A.3 Function Naming Conventions {#f77_function_naming_conventions}
8680 -------------------------------
8682 The netCDF-3 Fortran 77 library employs a naming convention intended to
8683 make netCDF programs more readable. For example, the name of the
8684 function to rename a variable is now NF\_RENAME\_VAR instead of the
8687 All netCDF-3 FORTRAN function names begin with the NF\_ prefix. The
8688 second part of the name is a verb, like GET, PUT, INQ (for inquire), or
8689 OPEN. The third part of the name is typically the object of the verb:
8690 for example DIM, VAR, or ATT for functions dealing with dimensions,
8691 variables, or attributes. To distinguish the various I/O operations for
8692 variables, a single character modifier is appended to VAR:
8694 - VAR entire variable access
8695 - VAR1 single value access
8696 - VARA array or array access
8697 - VARS strided access to absample of values
8698 - VARM mapped access to values not contiguous in memory
8700 At the end of the name for variable and attribute functions, there is a
8701 component indicating the type of the final argument: TEXT, INT1, INT2,
8702 INT, REAL, or DOUBLE. This part of the function name indicates the type
8703 of the data container you are using in your program: character string,
8704 1-byte integer, and so on.
8706 Also, all PARAMETER names in the public FORTRAN interface begin with the
8707 prefix NF\_. For example, the PARAMETER which was formerly MAXNCNAM is
8708 now NF\_MAX\_NAME, and the former FILFLOAT is now NF\_FILL\_FLOAT.
8710 As previously mentioned, all the old names are stillpported for
8711 backward compatibility.
8713 A.4 Type Conversion {#f77_type_conversion}
8716 With the new interface, users need not be aware of the external type of
8717 numeric variables, since automatic conversion to or from any desired
8718 numeric type is now available. You can use this feature to simplify
8719 code, by making it independent of external types. The elimination of
8720 type punning prevents some kinds of type errors that could occur with
8721 the previous interface. Programs may be made more robust with the new
8722 interface, because they need not be changed to accommodate a change to
8723 the external type of a variable.
8725 If conversion to or from an external numeric type is necessary, it is
8726 handled by the library. This automatic conversion and separation of
8727 external data representation from internal data types will become even
8728 more important in netCDF version 4, when new external types will be
8729 added for packed data for which there is no natural corresponding
8730 internal type, for example, arrays of 11-bit values.
8732 Converting from one numeric type to another may rlt in an error if
8733 the target type is not capable of representing the converted value. (In
8734 netCDF-2,ch overflows can only happen in the XDR layer.) For example,
8735 a REAL may not be able to hold data stored externally as an NF\_DOUBLE
8736 (an IEEE floating-point number). When accessing an array of values, an
8737 NF\_ERANGE error is returned if one or more values are out of the range
8738 of representable values, but other values are converted properly.
8740 Note that mere loss of precision in type conversion does not return an
8741 error. Thus, if you read double precision values into an INTEGER, for
8742 example, no error rlts unless the magnitude of the double precision
8743 value exceeds the representable range of INTEGERs on your platform.
8744 Similarly, if you read a large integer into a REAL incapable of
8745 representing all the bits of the integer in its mantissa, this loss
8746 There are two new functions in netCDF-3 that don’t correspond to any
8747 netCDF-2 functions: NF\_INQ\_LIBVERS and NF\_STRERROR. The version ation
8748 The previous implementation returned an error when the same dimension
8749 was used more than once in specifying the shape of a variable in
8750 ncvardef. This restriction is relaxed in the netCDF-3 implementation,
8751 because an autocorrelation matrix is a good example where using the same
8752 dimension twice makes sense.
8754 In the new interface, units for the IMAP argument to the NF\_PUT\_VARM
8755 and NF\_GET\_VARM families of functions are now in terms of the number
8756 of data elements of the desired internal type, not in terms of bytes as
8757 in the netCDF version-2 mapped access interfaces.
8759 Following is a table of netCDF-2 function names and names of the
8760 corresponding netCDF-3 functions. For parameter lists of netCDF-2
8761 functions, see the netCDF-2 User’s Guide.
8773 : NF\_GET\_ATT\_DOUBLE, NF\_GET\_ATT\_REAL, NF\_GET\_ATT\_INT,
8774 NF\_GET\_ATT\_INT1, NF\_GET\_ATT\_INT2
8777 : NF\_GET\_ATT\_TEXT
8780 : NF\_INQ\_ATT, NF\_INQ\_ATTID, NF\_INQ\_ATTLEN, NF\_INQ\_ATTTYPE
8786 : NF\_PUT\_ATT\_DOUBLE, NF\_PUT\_ATT\_REAL, NF\_PUT\_ATT\_INT,
8787 NF\_PUT\_ATT\_INT1NF\_PUT
8789 B. Summary of FORTRAN 77 Interface {#f77_interface_summary}
8790 ==================================
8792 Input parameters are in upper case, output parameters are in lower case.
8793 The FORTRAN types of all the parameters are listed alphabetically by
8794 parameter name below the function declarations.
8800 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
8801 CHARACTER*80 FUNCTION NF_STRERROR (NCERR)
8802 INTEGER FUNCTION NF_CREATE (PATH, CMODE, ncid)
8803 INTEGER FUNCTION NF_OPEN (PATH, MODE, ncid)
8804 INTEGER FUNCTION NF_SET_FILL (NCID, FILLMODE, old_mode)
8805 INTEGER FUNCTION NF_REDEF (NCID)
8806 INTEGER FUNCTION NF_ENDDEF (NCID)
8807 INTEGER FUNCTION NF_SYNC (NCID)
8808 INTEGER FUNCTION NF_ABORT (NCID)
8809 INTEGER FUNCTION NF_CLOSE (NCID)
8810 INTEGER FUNCTION NF_INQ (NCID, ndims, nvars, ngatts,
8812 INTEGER FUNCTION NF_INQ_NDIMS (NCID, ndims)
8813 INTEGER FUNCTION NF_INQ_NVARS (NCID, nvars)
8814 INTEGER FUNCTION NF_INQ_NATTS (NCID, ngatts)
8815 INTEGER FUNCTION NF_INQ_UNLIMDIM (NCID, unlimdimid)
8816 INTEGER FUNCTION NF_DEF_DIM (NCID, NAME, LEN, dimid)
8817 INTEGER FUNCTION NF_INQ_DIMID (NCID, NAME, dimid)
8818 INTEGER FUNCTION NF_INQ_DIM (NCID, DIMID, name, len)
8819 INTEGER FUNCTION NF_INQ_DIMNAME (NCID, DIMID, name)
8820 INTEGER FUNCTION NF_INQ_DIMLEN (NCID, DIMID, len)
8821 INTEGER FUNCTION NF_RENAME_DIM (NCID, DIMID, NAME)
8823 INTEGER FUNCTION NF_DEF_VAR (NCID, NAME, XTYPE, NDIMS, DIMIDS,
8825 INTEGER FUNCTION NF_INQ_VAR (NCID, VARID, name, xtype, ndims,
8827 INTEGER FUNCTION NF_INQ_VARID (NCID, NAME, varid)
8828 INTEGER FUNCTION NF_INQ_VARNAME (NCID, VARID, name)
8829 INTEGER FUNCTION NF_INQ_VARTYPE (NCID, VARID, xtype)
8830 INTEGER FUNCTION NF_INQ_VARNDIMS (NCID, VARID, ndims)
8831 INTEGER FUNCTION NF_INQ_VARDIMID (NCID, VARID, DIMIDS)
8832 INTEGER FUNCTION NF_INQ_VARNATTS (NCID, VARID, natts)
8833 INTEGER FUNCTION NF_RENAME_VAR (NCID, VARID, NAME)
8834 INTEGER FUNCTION NF_PUT_VAR_TEXT (NCID, VARID, TEXT)
8835 INTEGER FUNCTION NF_GET_VAR_TEXT (NCID, VARID, text)
8836 INTEGER FUNCTION NF_PUT_VAR_INT1 (NCID, VARID, I1VAL)
8837 INTEGER FUNCTION NF_GET_VAR_INT1 (NCID, VARID, i1val)
8838 INTEGER FUNCTION NF_PUT_VAR_INT2 (NCID, VARID, I2VAL)
8839 INTEGER FUNCTION NF_GET_VAR_INT2 (NCID, VARID, i2val)
8840 INTEGER FUNCTION NF_PUT_VAR_INT (NCID, VARID, IVAL)
8841 INTEGER FUNCTION NF_GET_VAR_INT (NCID, VARID, ival)
8842 INTEGER FUNCTION NF_PUT_VAR_INT64 (NCID, VARID, I8VAL)
8843 INTEGER FUNCTION NF_GET_VAR_INT64 (NCID, VARID, i8val)
8844 INTEGER FUNCTION NF_PUT_VAR_REAL (NCID, VARID, RVAL)
8845 INTEGER FUNCTION NF_GET_VAR_REAL (NCID, VARID, rval)
8846 INTEGER FUNCTION NF_PUT_VAR_DOUBLE (NCID, VARID, DVAL)
8847 INTEGER FUNCTION NF_GET_VAR_DOUBLE (NCID, VARID, dval)
8848 INTEGER FUNCTION NF_PUT_VAR1_TEXT (NCID, VARID, INDEX, TEXT)
8849 INTEGER FUNCTION NF_GET_VAR1_TEXT (NCID, VARID, INDEX, text)
8850 INTEGER FUNCTION NF_PUT_VAR1_INT1 (NCID, VARID, INDEX, I1VAL)
8851 INTEGER FUNCTION NF_GET_VAR1_INT1 (NCID, VARID, INDEX, i1val)
8852 INTEGER FUNCTION NF_PUT_VAR1_INT2 (NCID, VARID, INDEX, I2VAL)
8853 INTEGER FUNCTION NF_GET_VAR1_INT2 (NCID, VARID, INDEX, i2val)
8854 INTEGER FUNCTION NF_PUT_VAR1_INT (NCID, VARID, INDEX, IVAL)
8855 INTEGER FUNCTION NF_GET_VAR1_INT (NCID, VARID, INDEX, ival)
8856 INTEGER FUNCTION NF_PUT_VAR1_INT64 (NCID, VARID, INDEX, I8VAL)
8857 INTEGER FUNCTION NF_GET_VAR1_INT64 (NCID, VARID, INDEX, i8val)
8858 INTEGER FUNCTION NF_PUT_VAR1_REAL (NCID, VARID, INDEX, RVAL)
8859 INTEGER FUNCTION NF_GET_VAR1_REAL (NCID, VARID, INDEX, rval)
8860 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(NCID, VARID, INDEX, DVAL)
8861 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(NCID, VARID, INDEX, dval)
8862 INTEGER FUNCTION NF_PUT_VARA_TEXT (NCID, VARID, START, COUNT, TEXT)
8863 INTEGER FUNCTION NF_GET_VARA_TEXT (NCID, VARID, START, COUNT, text)
8864 INTEGER FUNCTION NF_PUT_VARA_INT1 (NCID, VARID, START, COUNT, I1VALS)
8865 INTEGER FUNCTION NF_GET_VARA_INT1 (NCID, VARID, START, COUNT, i1vals)
8866 INTEGER FUNCTION NF_PUT_VARA_INT2 (NCID, VARID, START, COUNT, I2VALS)
8867 INTEGER FUNCTION NF_GET_VARA_INT2 (NCID, VARID, START, COUNT, i2vals)
8868 INTEGER FUNCTION NF_PUT_VARA_INT (NCID, VARID, START, COUNT, IVALS)
8869 INTEGER FUNCTION NF_GET_VARA_INT (NCID, VARID, START, COUNT, ivals)
8870 INTEGER FUNCTION NF_PUT_VARA_INT64 (NCID, VARID, START, COUNT, I8VALS)
8871 INTEGER FUNCTION NF_GET_VARA_INT64 (NCID, VARID, START, COUNT, i8vals)
8872 INTEGER FUNCTION NF_PUT_VARA_REAL (NCID, VARID, START, COUNT, RVALS)
8873 INTEGER FUNCTION NF_GET_VARA_REAL (NCID, VARID, START, COUNT, rvals)
8874 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(NCID, VARID, START, COUNT, DVALS)
8875 INTEGER FUNCTION NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, dvals)
8876 INTEGER FUNCTION NF_PUT_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8878 INTEGER FUNCTION NF_GET_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8880 INTEGER FUNCTION NF_PUT_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8882 INTEGER FUNCTION NF_GET_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8884 INTEGER FUNCTION NF_PUT_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8886 INTEGER FUNCTION NF_GET_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8888 INTEGER FUNCTION NF_PUT_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8890 INTEGER FUNCTION NF_GET_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8892 INTEGER FUNCTION NF_PUT_VARS_INT64 (NCID, VARID, START, COUNT, STRIDE,
8894 INTEGER FUNCTION NF_GET_VARS_INT64 (NCID, VARID, START, COUNT, STRIDE,
8896 INTEGER FUNCTION NF_PUT_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8898 INTEGER FUNCTION NF_GET_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8900 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8902 INTEGER FUNCTION NF_GET_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8904 INTEGER FUNCTION NF_PUT_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8906 INTEGER FUNCTION NF_GET_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8908 INTEGER FUNCTION NF_PUT_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8910 INTEGER FUNCTION NF_GET_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8912 INTEGER FUNCTION NF_PUT_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8914 INTEGER FUNCTION NF_GET_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8916 INTEGER FUNCTION NF_PUT_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8918 INTEGER FUNCTION NF_GET_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8920 INTEGER FUNCTION NF_PUT_VARM_INT64 (NCID, VARID, START, COUNT, STRIDE,
8922 INTEGER FUNCTION NF_GET_VARM_INT64 (NCID, VARID, START, COUNT, STRIDE,
8924 INTEGER FUNCTION NF_PUT_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8926 INTEGER FUNCTION NF_GET_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8928 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8930 INTEGER FUNCTION NF_GET_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8933 INTEGER FUNCTION NF_INQ_ATT (NCID, VARID, NAME, xtype, len)
8934 INTEGER FUNCTION NF_INQ_ATTID (NCID, VARID, NAME, attnum)
8935 INTEGER FUNCTION NF_INQ_ATTTYPE (NCID, VARID, NAME, xtype)
8936 INTEGER FUNCTION NF_INQ_ATTLEN (NCID, VARID, NAME, len)
8937 INTEGER FUNCTION NF_INQ_ATTNAME (NCID, VARID, ATTNUM, name)
8938 INTEGER FUNCTION NF_COPY_ATT (NCID_IN, VARID_IN, NAME,
8939 NCID_OUT, VARID_OUT)
8940 INTEGER FUNCTION NF_RENAME_ATT (NCID, VARID, CURNAME, NEWNAME)
8941 INTEGER FUNCTION NF_DEL_ATT (NCID, VARID, NAME)
8942 INTEGER FUNCTION NF_PUT_ATT_TEXT (NCID, VARID, NAME, LEN, TEXT)
8943 INTEGER FUNCTION NF_GET_ATT_TEXT (NCID, VARID, NAME, text)
8944 INTEGER FUNCTION NF_PUT_ATT_INT1 (NCID, VARID, NAME, XTYPE, LEN,
8946 INTEGER FUNCTION NF_GET_ATT_INT1 (NCID, VARID, NAME, i1vals)
8947 INTEGER FUNCTION NF_PUT_ATT_INT2 (NCID, VARID, NAME, XTYPE, LEN,
8949 INTEGER FUNCTION NF_GET_ATT_INT2 (NCID, VARID, NAME, i2vals)
8950 INTEGER FUNCTION NF_PUT_ATT_INT (NCID, VARID, NAME, XTYPE, LEN,
8952 INTEGER FUNCTION NF_GET_ATT_INT (NCID, VARID, NAME, ivals)
8953 INTEGER FUNCTION NF_PUT_ATT_INT64 (NCID, VARID, NAME, XTYPE, LEN,
8955 INTEGER FUNCTION NF_GET_ATT_INT64 (NCID, VARID, NAME, i8vals)
8956 INTEGER FUNCTION NF_PUT_ATT_REAL (NCID, VARID, NAME, XTYPE, LEN,
8958 INTEGER FUNCTION NF_GET_ATT_REAL (NCID, VARID, NAME, rvals)
8959 INTEGER FUNCTION NF_PUT_ATT_DOUBLE (NCID, VARID, NAME, XTYPE, LEN,
8961 INTEGER FUNCTION NF_GET_ATT_DOUBLE (NCID, VARID, NAME, dvals)
8963 INTEGER ATTNUM ! attribute number
8964 INTEGER attnum ! returned attribute number
8965 INTEGER CMODE ! NF_NOCLOBBER, NF_SHARE flags expression
8966 INTEGER COUNT ! array of edge lengths of block of values
8967 CHARACTER(*) CURNAME ! current name (before renaming)
8968 INTEGER DIMID ! dimension ID
8969 INTEGER dimid ! returned dimension ID
8970 INTEGER DIMIDS ! list of dimension IDs
8971 INTEGER dimids ! list of returned dimension IDs
8972 DOUBLEPRECISION DVAL ! single data value
8973 DOUBLEPRECISION dval ! returned single data value
8974 DOUBLEPRECISION DVALS ! array of data values
8975 DOUBLEPRECISION dvals ! array of returned data values
8976 INTEGER FILLMODE ! NF_NOFILL or NF_FILL, for setting fill mode
8977 INTEGER*1 I1VAL ! single data value
8978 INTEGER*1 I1val ! returned single data value
8979 INTEGER*1 I1VALS ! array of data values
8980 INTEGER*1 i1vals ! array of returned data values
8981 INTEGER*2 I2VAL ! single data value
8982 INTEGER*2 i2val ! returned single data value
8983 INTEGER*2 I2VALS ! array of data values
8984 INTEGER*2 i2vals ! array of returned data values
8985 INTEGER IMAP ! index mapping vector
8986 INTEGER INDEX ! variable array index vector
8987 INTEGER IVAL ! single data value
8988 INTEGER ival ! returned single data value
8989 INTEGER IVALS ! array of data values
8990 INTEGER ivals ! array of returned data values
8991 INTEGER*8 I8VAL ! single data value
8992 INTEGER*8 i8val ! returned single data value
8993 INTEGER*8 I8VALS ! array of data values
8994 INTEGER*8 i8vals ! array of returned data values
8995 INTEGER LEN ! dimension or attribute length
8996 INTEGER len ! returned dimension or attribute length
8997 INTEGER MODE ! open mode, one of NF_WRITE or NF_NOWRITE
8998 CHARACTER(*) NAME ! dimension, variable, or attribute name
8999 CHARACTER(*) name ! returned dim, var, or att name
9000 INTEGER natts ! returned number of attributes
9001 INTEGER NCERR ! error returned from NF_xxx function call
9002 INTEGER NCID ! netCDF ID of an open netCDF dataset
9003 INTEGER ncid ! returned netCDF ID
9004 INTEGER NCID_IN ! netCDF ID of open source netCDF dataset
9005 INTEGER NCID_OUT ! netCDF ID of open destination netCDF dataset
9006 INTEGER NDIMS ! number of dimensions
9007 INTEGER ndims ! returned number of dimensions
9008 CHARACTER(*) NEWNAME ! new name for dim, var, or att
9009 INTEGER ngatts ! returned number of global attributes
9010 INTEGER nvars ! returned number of variables
9011 INTEGER old_mode ! previous fill mode, NF_NOFILL or NF_FILL,
9012 CHARACTER(*) PATH ! name of netCDF dataset
9013 REAL RVAL ! single data value
9014 REAL rval ! returned single data value
9015 REAL RVALS ! array of data values
9016 REAL rvals ! array of returned data values
9017 INTEGER START ! variable array indices of first value
9018 INTEGER STRIDE ! variable array dimensional strides
9019 CHARACTER(*) TEXT ! input text value
9020 CHARACTER(*) text ! returned text value
9021 INTEGER unlimdimid ! returned ID of unlimited dimension
9022 INTEGER VARID ! variable ID
9023 INTEGER varid ! returned variable ID
9024 INTEGER VARID_IN ! variable ID
9025 INTEGER VARID_OUT ! variable ID
9026 INTEGER XTYPE ! external type: NF_BYTE, NF_CHAR, ... ,
9027 INTEGER xtype ! returned external type