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).
5455 NF_INQ_VAR_SZIP(INTEGER NCID, INTEGER VARID, INTEGER OPTION_MASK,
5460 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5466 : This will be set to the option\_mask value.
5469 : The number of bits per pixel will be put here.
5474 NF\_INQ\_VAR\_SZIP returns the value NF\_NOERR if no errors occurred.
5475 Otherwise, the returned status indicates an error.
5477 Possible return codes include:
5486 : Not a netCDF-4 file.
5489 : Can’t find this variable.
5492 6.13 Define Checm Parameters for a Variable: `NF_DEF_VAR_FLETCHER32`
5493 -----------------------------------------------------------------------
5495 The function NF\_DEF\_VAR\_FLETCHER32 sets the checm property for a
5496 variable in a netCDF-4 file.
5498 This function may only be called after the variable is defined, but
5499 before NF\_ENDDEF is called.
5507 NF_DEF_VAR_FLETCHER32(INTEGER NCID, INTEGER VARID, INTEGER CHECKSUM);
5511 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5517 : If this is NF\_FLETCHER32, fletcher32 checms will be turned on
5523 NF\_DEF\_VAR\_FLETCHER32 returns the value NF\_NOERR if no errors
5524 occurred. Otherwise, the returned status indicates an error.
5526 Possible return codes include:
5535 : Not a netCDF-4 file.
5538 : Can’t find this variable.
5541 : This variable has already been thebject of a NF\_ENDDEF call. In
5542 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5543 read or write. Once enddef has been called, it is impossible to set
5544 the checm property for a variable.
5547 : Not in define mode. This is returned for netCDF classic or 64-bit
5548 offset files, or for netCDF-4 files, when they were been created
5549 with NF\_STRICT\_NC3 flag. (see
5550 [NF\_CREATE](#NF_005fCREATE)).
5553 : Attempt to create object in read-only file.
5558 In this example from nf\_test/ftst\_vars.F, the variable in a file has
5559 the Fletcher32 checm filter turned on.
5564 C Create the netCDF file.
5565 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5566 if (retval .ne. nf_noerr) call handle_err(retval)
5568 C Define the dimensions.
5569 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5570 if (retval .ne. nf_noerr) call handle_err(retval)
5571 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5572 if (retval .ne. nf_noerr) call handle_err(retval)
5574 C Define the variable.
5577 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5578 if (retval .ne. nf_noerr) call handle_err(retval)
5583 retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
5584 if (retval .ne. nf_noerr) call handle_err(retval)
5586 C Turn on deflate compression, fletcher32 checms.
5587 retval = NF_DEF_VAR_DEFLATE(ncid, varid, 0, 1, 4)
5588 if (retval .ne. nf_noerr) call handle_err(retval)
5589 retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
5590 if (retval .ne. nf_noerr) call handle_err(retval)
5594 6.14 Learn About Checm Parameters for a Variable: `NF_INQ_VAR_FLETCHER32`
5595 ----------------------------------------------------------------------------
5597 The function NF\_INQ\_VAR\_FLETCHER32 returns the checm settings for
5598 a variable in a netCDF-4 file.
5606 NF_INQ_VAR_FLETCHER32(INTEGER NCID, INTEGER VARID, INTEGER CHECKSUM);
5610 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5616 : NF\_INQ\_VAR\_FLETCHER32 will set this to NF\_FLETCHER32 if the
5617 fletcher32 filter is turned on for this variable, and NF\_NOCHECKSUM
5623 NF\_INQ\_VAR\_FLETCHER32 returns the value NF\_NOERR if no errors
5624 occurred. Otherwise, the returned status indicates an error.
5626 Possible return codes include:
5635 : Not a netCDF-4 file.
5638 : Can’t find this variable.
5643 In this example from nf\_test/ftst\_vars.F the checm filter is
5644 checked for a file. Since it was turned on for this variable, the
5645 checm variable is set to NF\_FLETCHER32.
5650 retval = nf_inq_var_fletcher32(ncid, varid, checm)
5651 if (retval .ne. nf_noerr) call handle_err(retval)
5652 if (checm .ne. NF_FLETCHER32) stop 2
5655 6.15 Define Endianness of a Variable: `NF_DEF_VAR_ENDIAN`
5656 ---------------------------------------------------------
5658 The function NF\_DEF\_VAR\_ENDIAN sets the endianness for a variable in
5661 This function must be called after the variable is defined, but before
5662 NF\_ENDDEF is called.
5664 By default, netCDF-4 variables are in native endianness. That is, they
5665 are big-endian on a big-endian machine, and little-endian on a little
5668 In some cases a user might wish to change from native endianness to
5669 either big or little-endianness. This function allows them to do that.
5677 NF_DEF_VAR_ENDIAN(INTEGER NCID, INTEGER VARID, INTEGER ENDIAN)
5681 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5687 : Set to NF\_ENDIAN\_NATIVE for native endianness. (This is the
5688 default). Set to NF\_ENDIAN\_LITTLE for little endian, or
5689 NF\_ENDIAN\_BIG for big endian.
5694 NF\_DEF\_VAR\_ENDIAN returns the value NF\_NOERR if no errors occurred.
5695 Otherwise, the returned status indicates an error.
5697 Possible return codes include:
5706 : Not a netCDF-4 file.
5709 : Can’t find this variable.
5712 : This variable has already been thebject of a NF\_ENDDEF call. In
5713 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5714 read or write. Once enddef has been called, it is impossible to set
5715 the endianness of a variable.
5718 : Not in define mode. This is returned for netCDF classic or 64-bit
5719 offset files, or for netCDF-4 files, when they were been created
5720 with NF\_STRICT\_NC3 flag, and the file is not in define mode. (see
5721 [NF\_CREATE](#NF_005fCREATE)).
5724 : Attempt to create object in read-only file.
5729 In this example from nf\_test/ftst\_vars.c, a file is created with one
5730 variable, and its endianness is set to NF\_ENDIAN\_BIG.
5735 C Create the netCDF file.
5736 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5737 if (retval .ne. nf_noerr) call handle_err(retval)
5739 C Define the dimensions.
5740 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5741 if (retval .ne. nf_noerr) call handle_err(retval)
5742 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5743 if (retval .ne. nf_noerr) call handle_err(retval)
5745 C Define the variable.
5748 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5749 if (retval .ne. nf_noerr) call handle_err(retval)
5754 retval = NF_DEF_VAR_chunking(ncid, varid, 0, chunks)
5755 if (retval .ne. nf_noerr) call handle_err(retval)
5757 C Set variable to big-endian (default is whatever is native to
5759 retval = NF_DEF_VAR_endian(ncid, varid, NF_ENDIAN_BIG)
5760 if (retval .ne. nf_noerr) call handle_err(retval)
5763 6.16 Learn About Endian Parameters for a Variable: `NF_INQ_VAR_ENDIAN`
5764 ----------------------------------------------------------------------
5766 The function NF\_INQ\_VAR\_ENDIAN returns the endianness settings for a
5767 variable in a netCDF-4 file.
5775 NF_INQ_VAR_ENDIAN(INTEGER NCID, INTEGER VARID, INTEGER ENDIAN)
5779 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5785 : NF\_INQ\_VAR\_ENDIAN will set this to NF\_ENDIAN\_LITTLE if this
5786 variable is stored in little-endian format, NF\_ENDIAN\_BIG if it is
5787 stored in big-endian format, and NF\_ENDIAN\_NATIVE if the
5788 endianness is not set, and the variable is not created yet.
5793 NF\_INQ\_VAR\_ENDIAN returns the value NF\_NOERR if no errors occurred.
5794 Otherwise, the returned status indicates an error.
5796 Possible return codes include:
5805 : Not a netCDF-4 file.
5808 : Can’t find this variable.
5813 In this example from nf\_test/ftst\_vars.F, the endianness of a variable
5814 is checked to makere it is NF\_ENDIAN\_BIG.
5819 retval = nf_inq_var_endian(ncid, varid, endianness)
5820 if (retval .ne. nf_noerr) call handle_err(retval)
5821 if (endianness .ne. NF_ENDIAN_BIG) stop 2
5825 6.17 Get a Variable ID from Its Name: NF\_INQ\_VARID
5826 ----------------------------------------------------
5828 The function NF\_INQ\_VARID returns the ID of a netCDF variable, given
5837 INTEGER FUNCTION NF_INQ_VARID(INTEGER NCID, CHARACTER*(*) NAME,
5842 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5845 : Variable name for which ID is desired.
5848 : Returned variable ID.
5853 NF\_INQ\_VARID returns the value NF\_NOERR if no errors occurred.
5854 Otherwise, the returned status indicates an error. Possible causes of
5857 - The specified variable name is not a valid name for a variable in
5858 the specified netCDF dataset.
5859 - The specified netCDF ID does not refer to an open netCDF dataset.
5864 Here is an example using NF\_INQ\_VARID to find out the ID of a variable
5865 named rh in an existing netCDF dataset named foo.nc:
5870 INCLUDE 'netcdf.inc'
5872 INTEGER STATUS, NCID, RHID
5874 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
5875 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5877 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
5878 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5882 6.18 Get Information about a Variable from Its ID: NF\_INQ\_VAR family
5883 ----------------------------------------------------------------------
5885 A family of functions that returns information about a netCDF variable,
5886 given its ID. Information about a variable includes its name, type,
5887 number of dimensions, a list of dimension IDs describing the shape of
5888 the variable, and the number of variable attributes that have been
5889 assigned to the variable.
5891 The function NF\_INQ\_VAR returns all the information about a netCDF
5892 variable, given its ID. The other functions each return just one item of
5893 information about a variable.
5895 These other functions include NF\_INQ\_VARNAME, NF\_INQ\_VARTYPE,
5896 NF\_INQ\_VARNDIMS, NF\_INQ\_VARDIMID, and NF\_INQ\_VARNATTS.
5904 INTEGER FUNCTION NF_INQ_VAR (INTEGER NCID, INTEGER VARID,
5905 CHARACTER*(*) name, INTEGER xtype,
5906 INTEGER ndims, INTEGER dimids(*),
5908 INTEGER FUNCTION NF_INQ_VARNAME (INTEGER NCID, INTEGER VARID,
5910 INTEGER FUNCTION NF_INQ_VARTYPE (INTEGER NCID, INTEGER VARID,
5912 INTEGER FUNCTION NF_INQ_VARNDIMS (INTEGER NCID, INTEGER VARID,
5914 INTEGER FUNCTION NF_INQ_VARDIMID (INTEGER NCID, INTEGER VARID,
5916 INTEGER FUNCTION NF_INQ_VARNATTS (INTEGER NCID, INTEGER VARID,
5921 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5927 : Returned variable name. The caller must allocate space for the
5928 returned name. The maximum possible length, in characters, of a
5929 variable name is given by the predefined constant NF\_MAX\_NAME.
5932 : Returned variable type, one of the set of predefined netCDF external
5933 data types. The type of this parameter, NF\_TYPE, is defined in the
5934 netCDF header file. The valid netCDF external data types are
5935 NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, AND NF\_DOUBLE.
5938 : Returned number of dimensions the variable was defined as using. For
5939 example, 2 indicates a matrix, 1 indicates a vector, and 0 means the
5940 variable is a scalar with no dimensions.
5943 : Returned vector of \*ndimsp dimension IDs corresponding to the
5944 variable dimensions. The caller must allocate enough space for a
5945 vector of at least \*ndimsp integers to be returned. The maximum
5946 possible number of dimensions for a variable is given by the
5947 predefined constant NF\_MAX\_VAR\_DIMS.
5950 : Returned number of variable attributes assigned to this variable.
5952 These functions return the value NF\_NOERR if no errors occurred.
5953 Otherwise, the returned status indicates an error. Possible causes of
5956 - The variable ID is invalid for the specified netCDF dataset.
5957 - The specified netCDF ID does not refer to an open netCDF dataset.
5962 Here is an example using NF\_INQ\_VAR to find out about a variable named
5963 rh in an existing netCDF dataset named foo.nc:
5968 INCLUDE 'netcdf.inc'
5970 INTEGER STATUS, NCID
5971 INTEGER RHID ! variable ID
5972 CHARACTER*31 RHNAME ! variable name
5973 INTEGER RHTYPE ! variable type
5974 INTEGER RHN ! number of dimensions
5975 INTEGER RHDIMS(NF_MAX_VAR_DIMS) ! variable shape
5976 INTEGER RHNATT ! number of attributes
5978 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
5979 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5981 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
5982 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5983 STATUS = NF_INQ_VAR (NCID, RHID, RHNAME, RHTYPE, RHN, RHDIMS, RHNATT)
5984 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5987 6.19 Write a Single Data Value: NF\_PUT\_VAR1\_ type
5988 ----------------------------------------------------
5990 The functions NF\_PUT\_VAR1\_type (for various types) put a single data
5991 value of the specified type into a variable of an open netCDF dataset
5992 that is in data mode. Inputs are the netCDF ID, the variable ID, an
5993 index that specifies which value to add or alter, and the data value.
5994 The value is converted to the external data type of the variable, if
6003 INTEGER FUNCTION NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6004 INTEGER INDEX(*), CHARACTER CHVAL)
6005 INTEGER FUNCTION NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6006 INTEGER INDEX(*), INTEGER*1 I1VAL)
6007 INTEGER FUNCTION NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6008 INTEGER INDEX(*), INTEGER*2 I2VAL)
6009 INTEGER FUNCTION NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
6010 INTEGER INDEX(*), INTEGER IVAL)
6011 INTEGER FUNCTION NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6012 INTEGER INDEX(*), REAL RVAL)
6013 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6014 INTEGER INDEX(*), DOUBLE DVAL)
6015 INTEGER FUNCTION NF_PUT_VAR1(INTEGER NCID, INTEGER VARID,
6016 INTEGER INDEX(*), *)
6020 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6026 : The index of the data value to be written. The indices are relative
6027 to 1, so for example, the first data value of a two-dimensional
6028 variable would have index (1,1). The elements of index must
6029 correspond to the variable’s dimensions. Hence, if the variable uses
6030 the unlimited dimension, the last index would correspond to the
6039 : Pointer to the data value to be written. If the type of data values
6040 differs from the netCDF variable type, type conversion will occur.
6041 See [(netcdf)Type Conversion](netcdf.html#Type-Conversion)
6042 ‘Type Conversion’ in The NetCDF Users Guide.
6047 NF\_PUT\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6048 Otherwise, the returned status indicates an error. Possible causes of
6051 - The variable ID is invalid for the specified netCDF dataset.
6052 - The specified indices were out of range for the rank of the
6053 specified variable. For example, a negative index or an index that
6054 is larger than the corresponding dimension length will cause an
6056 - The specified value is out of the range of values representable by
6057 the external data type of the variable.
6058 - The specified netCDF is in define mode rather than data mode.
6059 - The specified netCDF ID does not refer to an open netCDF dataset.
6064 Here is an example using NF\_PUT\_VAR1\_DOUBLE to set the (4,3,2)
6065 element of the variable named rh to 0.5 in an existing netCDF dataset
6066 named foo.nc. For simplicity in this example, we ame that we know
6067 that rh is dimensioned with lon, lat, and time, so we want to set the
6068 value of rh that corresponds to the fourth lon value, the third lat
6069 value, and the second time value:
6074 INCLUDE 'netcdf.inc'
6076 INTEGER STATUS ! error status
6078 INTEGER RHID ! variable ID
6079 INTEGER RHINDX(3) ! where to put value
6080 DATA RHINDX /4, 3, 2/
6082 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6083 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6085 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
6086 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6087 STATUS = NF_PUT_VAR1_DOUBLE (NCID, RHID, RHINDX, 0.5)
6088 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6091 6.20 Write an Entire Variable: NF\_PUT\_VAR\_ type
6092 --------------------------------------------------
6094 The NF\_PUT\_VAR\_ type family of functions write all the values of a
6095 variable into a netCDF variable of an open netCDF dataset. This is the
6096 simplest interface to use for writing a value in a scalar variable or
6097 whenever all the values of a multidimensional variable can all be
6098 written at once. The values to be written are associated with the netCDF
6099 variable by aming that the last dimension of the netCDF variable
6100 varies fastest in the C interface. The values are converted to the
6101 external data type of the variable, if necessary.
6103 Take care when using the simplest forms of this interface with record
6104 variables (variables that use the NF\_UNLIMITED dimension) when you
6105 don’t specify how many records are to be written. If you try to write
6106 all the values of a record variable into a netCDF file that has no
6107 record data yet (hence has 0 records), nothing will be written.
6108 Similarly, if you try to write all the values of a record variable from
6109 an array but there are more records in the file than you ame, more
6110 in-memory data will be accessed than you expect, which may cause a
6111 segmentation violation. To avoidch problems, it is better to use the
6112 NF\_PUT\_VARA\_type interfaces for variables that use the NF\_UNLIMITED
6113 dimension. See [Write an Array of Values: NF\_PUT\_VARA\_
6114 type](#NF_005fPUT_005fVARA_005f-type).
6122 INTEGER FUNCTION NF_PUT_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6124 INTEGER FUNCTION NF_PUT_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6125 INTEGER*1 I1VALS(*))
6126 INTEGER FUNCTION NF_PUT_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6127 INTEGER*2 I2VALS(*))
6128 INTEGER FUNCTION NF_PUT_VAR_INT (INTEGER NCID, INTEGER VARID,
6130 INTEGER FUNCTION NF_PUT_VAR_REAL (INTEGER NCID, INTEGER VARID,
6132 INTEGER FUNCTION NF_PUT_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6134 INTEGER FUNCTION NF_PUT_VAR (INTEGER NCID, INTEGER VARID,
6139 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6151 : The block of data values to be written. The data should be of the
6152 type appropriate for the function called. You cannot put CHARACTER
6153 data into a numeric variable or numeric data into a text variable.
6154 For numeric data, if the type of data differs from the netCDF
6155 variable type, type conversion will occur (see [(netcdf)Type
6156 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6157 in The NetCDF Users Guide). The order in which the data will be
6158 written into the specified variable is with the first dimension
6159 varying fastest (like the ordinary FORTRAN convention).
6164 Members of the NF\_PUT\_VAR\_ type family return the value NF\_NOERR if
6165 no errors occurred. Otherwise, the returned status indicates an error.
6166 Possible causes of errors include:
6168 - The variable ID is invalid for the specified netCDF dataset.
6169 - One or more of the specified values are out of the range of values
6170 representable by the external data type of the variable.
6171 - One or more of the specified values are out of the range of values
6172 representable by the external data type of the variable.
6173 - The specified netCDF dataset is in define mode rather than data
6175 - The specified netCDF ID does not refer to an open netCDF dataset.
6180 Here is an example using NF\_PUT\_VAR\_DOUBLE to add or change all the
6181 values of the variable named rh to 0.5 in an existing netCDF dataset
6182 named foo.nc. For simplicity in this example, we ame that we know
6183 that rh is dimensioned with lon and lat, and that there are ten lon
6184 values and five lat values.
6189 INCLUDE 'netcdf.inc'
6191 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6192 INTEGER STATUS, NCID
6193 INTEGER RHID ! variable ID
6194 DOUBLE RHVALS(LONS, LATS)
6196 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6197 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6199 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6200 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6201 DO 10 ILON = 1, LONS
6202 DO 10 ILAT = 1, LATS
6203 RHVALS(ILON, ILAT) = 0.5
6205 STATUS = NF_PUT_var_DOUBLE (NCID, RHID, RHVALS)
6206 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6210 6.21 Write an Array of Values: NF\_PUT\_VARA\_ type
6211 ---------------------------------------------------
6213 The function NF\_PUT\_VARA\_ type writes values into a netCDF variable
6214 of an open netCDF dataset. The part of the netCDF variable to write is
6215 specified by giving a corner and a vector of edge lengths that refer to
6216 an array of the netCDF variable. The values to be written are
6217 associated with the netCDF variable by aming that the first dimension
6218 of the netCDF variable varies fastest in the FORTRAN interface. The
6219 netCDF dataset must be in data mode.
6227 INTEGER FUNCTION NF_PUT_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6228 INTEGER START(*), INTEGER COUNT(*),
6230 INTEGER FUNCTION NF_PUT_VARA_INT1(INTEGER NCID, INTEGER VARID,
6231 INTEGER START(*), INTEGER COUNT(*),
6232 INTEGER*1 I1VALS(*))
6233 INTEGER FUNCTION NF_PUT_VARA_INT2(INTEGER NCID, INTEGER VARID,
6234 INTEGER START(*), INTEGER COUNT(*),
6235 INTEGER*2 I2VALS(*))
6236 INTEGER FUNCTION NF_PUT_VARA_INT (INTEGER NCID, INTEGER VARID,
6237 INTEGER START(*), INTEGER COUNT(*),
6239 INTEGER FUNCTION NF_PUT_VARA_REAL(INTEGER NCID, INTEGER VARID,
6240 INTEGER START(*), INTEGER COUNT(*),
6242 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6243 INTEGER START(*), INTEGER COUNT(*),
6245 INTEGER FUNCTION NF_PUT_VARA (INTEGER NCID, INTEGER VARID,
6246 INTEGER START(*), INTEGER COUNT(*),
6251 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6257 : A vector of integers specifying the index in the variable where the
6258 first of the data values will be written. The indices are relative
6259 to 1, so for example, the first data value of a variable would have
6260 index (1, 1, ..., 1). The length of START must be the same as the
6261 number of dimensions of the specified variable. The elements of
6262 START must correspond to the variable’s dimensions in order. Hence,
6263 if the variable is a record variable, the last index would
6264 correspond to the starting record number for writing the data
6268 : A vector of integers specifying the edge lengths along each
6269 dimension of the block of data values to written. To write a single
6270 value, for example, specify COUNT as (1, 1, ..., 1). The length of
6271 COUNT is the number of dimensions of the specified variable. The
6272 elements of COUNT correspond to the variable’s dimensions. Hence, if
6273 the variable is a record variable, the last element of COUNT
6274 corresponds to a count of the number of records to write.
6276 Note: setting any element of the count array to zero causes the
6277 function to exit without error, and without doing anything.
6286 : The block of data values to be written. The data should be of the
6287 type appropriate for the function called. You cannot put CHARACTER
6288 data into a numeric variable or numeric data into a text variable.
6289 For numeric data, if the type of data differs from the netCDF
6290 variable type, type conversion will occur (see [(netcdf)Type
6291 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6292 in The NetCDF Users Guide).
6297 NF\_PUT\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
6298 Otherwise, the returned status indicates an error. Possible causes of
6301 - The variable ID is invalid for the specified netCDF dataset.
6302 - The specified corner indices were out of range for the rank of the
6303 specified variable. For example, a negative index, or an index that
6304 is larger than the corresponding dimension length will cause an
6306 - The specified edge lengths added to the specified corner would have
6307 referenced data out of range for the rank of the specified variable.
6308 For example, an edge length that is larger than the corresponding
6309 dimension length minus the corner index will cause an error.
6310 - One or more of the specified values are out of the range of values
6311 representable by the external data type of the variable.
6312 - The specified netCDF dataset is in define mode rather than data
6314 - The specified netCDF ID does not refer to an open netCDF dataset.
6319 Here is an example using NF\_PUT\_VARA\_DOUBLE to add or change all the
6320 values of the variable named rh to 0.5 in an existing netCDF dataset
6321 named foo.nc. For simplicity in this example, we ame that we know
6322 that rh is dimensioned with time, lat, and lon, and that there are three
6323 time values, five lat values, and ten lon values.
6328 INCLUDE 'netcdf.inc'
6330 PARAMETER (NDIMS=3) ! number of dimensions
6331 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
6332 INTEGER STATUS, NCID, TIMES
6333 INTEGER RHID ! variable ID
6334 INTEGER START(NDIMS), COUNT(NDIMS)
6335 DOUBLE RHVALS(LONS, LATS, TIMES)
6336 DATA START /1, 1, 1/ ! start at first value
6337 DATA COUNT /LONS, LATS, TIMES/
6339 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6340 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6342 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6343 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6344 DO 10 ILON = 1, LONS
6345 DO 10 ILAT = 1, LATS
6346 DO 10 ITIME = 1, TIMES
6347 RHVALS(ILON, ILAT, ITIME) = 0.5
6349 STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
6350 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6354 6.22 NF\_PUT\_VARS\_ type
6355 -------------------------
6357 Each member of the family of functions NF\_PUT\_VARS\_ type writes a
6358 subsampled (strided) array of values into a netCDF variable of
6359 an open netCDF dataset. Thebsampled array is specified by
6360 giving a corner, a vector of counts, and a stride vector. The netCDF
6361 dataset must be in data mode.
6369 INTEGER FUNCTION NF_PUT_VARS_TEXT (INTEGER NCID, INTEGER VARID,
6370 INTEGER START(*), INTEGER COUNT(*),
6371 INTEGER STRIDE(*),CHARACTER*(*) TEXT)
6372 INTEGER FUNCTION NF_PUT_VARS_INT1 (INTEGER NCID, INTEGER VARID,
6373 INTEGER START(*), INTEGER COUNT(*),
6374 INTEGER STRIDE(*),INTEGER*1 I1VALS(*))
6375 INTEGER FUNCTION NF_PUT_VARS_INT2 (INTEGER NCID, INTEGER VARID,
6376 INTEGER START(*), INTEGER COUNT(*),
6377 INTEGER STRIDE(*),INTEGER*2 I2VALS(*))
6378 INTEGER FUNCTION NF_PUT_VARS_INT (INTEGER NCID, INTEGER VARID,
6379 INTEGER START(*), INTEGER COUNT(*),
6380 INTEGER STRIDE(*), INTEGER IVALS(*))
6381 INTEGER FUNCTION NF_PUT_VARS_REAL (INTEGER NCID, INTEGER VARID,
6382 INTEGER START(*), INTEGER COUNT(*),
6383 INTEGER STRIDE(*), REAL RVALS(*))
6384 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
6385 INTEGER START(*), INTEGER COUNT(*),
6386 INTEGER STRIDE(*), DOUBLE DVALS(*))
6387 INTEGER FUNCTION NF_PUT_VARS (INTEGER NCID, INTEGER VARID,
6388 INTEGER START(*), INTEGER COUNT(*),
6389 INTEGER STRIDE(*), VALS(*))
6393 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6399 : A vector of integers specifying the index in the variable where the
6400 first of the data values will be written. The indices are relative
6401 to 1, so for example, the first data value of a variable would have
6402 index (1, 1, ..., 1). The elements of START correspond, in order, to
6403 the variable’s dimensions. Hence, if the variable is a record
6404 variable, the last index would correspond to the starting record
6405 number for writing the data values.
6408 : A vector of integers specifying the number of indices selected along
6409 each dimension. To write a single value, for example, specify COUNT
6410 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6411 the variable’s dimensions. Hence, if the variable is a record
6412 variable, the last element of COUNT corresponds to a count of the
6413 number of records to write.
6415 Note: setting any element of the count array to zero causes the
6416 function to exit without error, and without doing anything.
6419 : A vector of integers that specifies the sampling interval along each
6420 dimension of the netCDF variable. The elements of the stride vector
6421 correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6422 gives the sampling interval along the most rapidly varying dimension
6423 of the netCDF variable). Sampling intervals are specified in
6424 type-independent units of elements (a value of 1 selects consecutive
6425 elements of the netCDF variable along the corresponding dimension, a
6426 value of 2 selects every other element, etc.).
6435 : The block of data values to be written. The data should be of the
6436 type appropriate for the function called. You cannot put CHARACTER
6437 data into a numeric variable or numeric data into a text variable.
6438 For numeric data, if the type of data differs from the netCDF
6439 variable type, type conversion will occur (see [(netcdf)Type
6440 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6441 in The NetCDF Users Guide).
6446 NF\_PUT\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
6447 Otherwise, the returned status indicates an error. Possible causes of
6450 - The variable ID is invalid for the specified netCDF dataset.
6451 - The specified start, count and stride generate an index which is out
6453 - One or more of the specified values are out of the range of values
6454 representable by the external data type of the variable.
6455 - The specified netCDF is in define mode rather than data mode.
6456 - The specified netCDF ID does not refer to an open netCDF dataset.
6461 Here is an example of using NF\_PUT\_VARS\_REAL to write – from an
6462 internal array – every other point of a netCDF variable named rh which
6463 is described by the FORTRAN declaration REAL RH(6,4) (note the size of
6469 INCLUDE 'netcdf.inc'
6471 PARAMETER (NDIM=2) ! rank of netCDF variable
6472 INTEGER NCID ! netCDF dataset ID
6473 INTEGER STATUS ! return code
6474 INTEGER RHID ! variable ID
6475 INTEGER START(NDIM) ! netCDF variable start point
6476 INTEGER COUNT(NDIM) ! size of internal array
6477 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6478 REAL RH(3,2) ! notebsampled sizes for netCDF variable
6480 DATA START /1, 1/ ! start at first netCDF variable value
6481 DATA COUNT /3, 2/ ! size of internal array: entire bsampled)
6483 DATA STRIDE /2, 2/ ! access every other netCDF element
6485 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6486 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6488 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6489 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6491 STATUS = NF_PUT_VARS_REAL(NCID, RHID, START, COUNT, STRIDE, RH)
6492 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6494 6.23 NF\_PUT\_VARM\_ type
6495 -------------------------
6497 The NF\_PUT\_VARM\_ type family of functions writes a mapped array
6498 section of values into a netCDF variable of an open netCDF dataset. The
6499 mapped array is specified by giving a corner, a vector of
6500 counts, a stride vector, and an index mapping vector. The index mapping
6501 vector is a vector of integers that specifies the mapping between the
6502 dimensions of a netCDF variable and the in-memory structure of the
6503 internal data array. No amptions are made about the ordering or
6504 length of the dimensions of the data array. The netCDF dataset must be
6513 INTEGER FUNCTION NF_PUT_VARM_TEXT (INTEGER NCID, INTEGER VARID,
6514 INTEGER START(*), INTEGER COUNT(*),
6515 INTEGER STRIDE(*), INTEGER IMAP(*),
6517 INTEGER FUNCTION NF_PUT_VARM_INT1 (INTEGER NCID, INTEGER VARID,
6518 INTEGER START(*), INTEGER COUNT(*),
6519 INTEGER STRIDE(*), INTEGER IMAP(*),
6520 INTEGER*1 I1VALS(*))
6521 INTEGER FUNCTION NF_PUT_VARM_INT2 (INTEGER NCID, INTEGER VARID,
6522 INTEGER START(*), INTEGER COUNT(*),
6523 INTEGER STRIDE(*), INTEGER IMAP(*),
6524 INTEGER*2 I2VALS(*))
6525 INTEGER FUNCTION NF_PUT_VARM_INT (INTEGER NCID, INTEGER VARID,
6526 INTEGER START(*), INTEGER COUNT(*),
6527 INTEGER STRIDE(*), INTEGER IMAP(*),
6529 INTEGER FUNCTION NF_PUT_VARM_REAL (INTEGER NCID, INTEGER VARID,
6530 INTEGER START(*), INTEGER COUNT(*),
6531 INTEGER STRIDE(*), INTEGER IMAP(*),
6533 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
6534 INTEGER START(*), INTEGER COUNT(*),
6535 INTEGER STRIDE(*), INTEGER IMAP(*),
6540 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6546 : A vector of integers specifying the index in the variable where the
6547 first of the data values will be written. The indices are relative
6548 to 1, so for example, the first data value of a variable would have
6549 index (1, 1, ..., 1). The elements of START correspond, in order, to
6550 the variable’s dimensions. Hence, if the variable is a record
6551 variable, the last index would correspond to the starting record
6552 number for writing the data values.
6555 : A vector of integers specifying the number of indices selected along
6556 each dimension. To write a single value, for example, specify COUNT
6557 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6558 the variable’s dimensions. Hence, if the variable is a record
6559 variable, the last element of COUNT corresponds to a count of the
6560 number of records to write.
6562 Note: setting any element of the count array to zero causes the
6563 function to exit without error, and without doing anything.
6566 : A vector of integers that specifies the sampling interval along each
6567 dimension of the netCDF variable. The elements of the stride vector
6568 correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6569 gives the sampling interval along the most rapidly varying dimension
6570 of the netCDF variable). Sampling intervals are specified in
6571 type-independent units of elements (a value of 1 selects consecutive
6572 elements of the netCDF variable along the corresponding dimension, a
6573 value of 2 selects every other element, etc.).
6576 : A vector of integers that specifies the mapping between the
6577 dimensions of a netCDF variable and the in-memory structure of the
6578 internal data array. The elements of the index mapping vector
6579 correspond, in order, to the netCDF variable’s dimensions (IMAP(1)
6580 gives the distance between elements of the internal array
6581 corresponding to the most rapidly varying dimension of the netCDF
6582 variable). Distances between elements are specified in units of
6583 elements (the distance between internal elements that occupy
6584 adjacent memory locations is 1 and not the element’s byte-length as
6593 : The data values to be written. The data should be of the type
6594 appropriate for the function called. You cannot put CHARACTER data
6595 into a numeric variable or numeric data into a text variable. For
6596 numeric data, if the type of data differs from the netCDF variable
6597 type, type conversion will occur (see [(netcdf)Type
6598 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6599 in The NetCDF Users Guide).
6604 NF\_PUT\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
6605 Otherwise, the returned status indicates an error. Possible causes of
6608 - The variable ID is invalid for the specified netCDF dataset.
6609 - The specified START, COUNT, and STRIDE generate an index which is
6610 out of range. Note that no error checking is possible on the imap
6612 - One or more of the specified values are out of the range of values
6613 representable by the external data type of the variable.
6614 - The specified netCDF is in define mode rather than data mode.
6615 - The specified netCDF ID does not refer to an open netCDF dataset.
6620 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
6621 variable and an internal array of the same shape:
6626 REAL A(2,3,4) ! same shape as netCDF variable
6628 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
6629 ! ---------------- ----------------------
6630 ! most rapidly varying 1
6631 ! intermediate 2 (=IMAP(1)*2)
6632 ! most slowly varying 6 (=IMAP(2)*3)
6635 Using the IMAP vector above with NF\_PUT\_VARM\_REAL obtains the same
6636 rlt as simply using NF\_PUT\_VAR\_REAL.
6638 Here is an example of using NF\_PUT\_VARM\_REAL to write – from a
6639 transposed, internal array – a netCDF variable named rh which is
6640 described by the FORTRAN declaration REAL RH(4,6) (note the size and
6641 order of the dimensions):
6646 INCLUDE 'netcdf.inc'
6648 PARAMETER (NDIM=2) ! rank of netCDF variable
6649 INTEGER NCID ! netCDF ID
6650 INTEGER STATUS ! return code
6651 INTEGER RHID ! variable ID
6652 INTEGER START(NDIM) ! netCDF variable start point
6653 INTEGER COUNT(NDIM) ! size of internal array
6654 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6655 INTEGER IMAP(NDIM) ! internal array inter-element distances
6656 REAL RH(6,4) ! note transposition of netCDF variable dimensions
6657 DATA START /1, 1/ ! start at first netCDF variable element
6658 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
6659 ! to netCDF variable -- not internal array
6660 DATA STRIDE /1, 1/ ! sample every netCDF element
6661 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
6663 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6664 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6666 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6667 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6669 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6670 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6673 Here is another example of using NF\_PUT\_VARM\_REAL to write – from a
6674 transposed, internal array – absample of the same netCDF variable, by
6675 writing every other point of the netCDF variable:
6680 INCLUDE 'netcdf.inc'
6682 PARAMETER (NDIM=2) ! rank of netCDF variable
6683 INTEGER NCID ! netCDF dataset ID
6684 INTEGER STATUS ! return code
6685 INTEGER RHID ! variable ID
6686 INTEGER START(NDIM) ! netCDF variable start point
6687 INTEGER COUNT(NDIM) ! size of internal array
6688 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6689 INTEGER IMAP(NDIM) ! internal array inter-element distances
6690 REAL RH(3,2) ! note transposition of bsampled) dimensions
6691 DATA START /1, 1/ ! start at first netCDF variable value
6692 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
6693 ! to netCDF variable -- not internal array
6694 DATA STRIDE /2, 2/ ! sample every other netCDF element
6695 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
6697 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6698 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6700 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6701 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6703 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6704 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6707 6.24 NF\_GET\_VAR1\_ type
6708 -------------------------
6710 The functions NF\_GET\_VAR1\_ type get a single data value from a
6711 variable of an open netCDF dataset that is in data mode. Inputs are the
6712 netCDF ID, the variable ID, a multidimensional index that specifies
6713 which value to get, and the address of a location into which the data
6714 value will be read. The value is converted from the external data type
6715 of the variable, if necessary.
6723 INTEGER FUNCTION NF_GET_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6724 INTEGER INDEX(*), CHARACTER CHVAL)
6725 INTEGER FUNCTION NF_GET_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6726 INTEGER INDEX(*), INTEGER*1 I1VAL)
6727 INTEGER FUNCTION NF_GET_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6728 INTEGER INDEX(*), INTEGER*2 I2VAL)
6729 INTEGER FUNCTION NF_GET_VAR1_INT (INTEGER NCID, INTEGER VARID,
6730 INTEGER INDEX(*), INTEGER IVAL)
6731 INTEGER FUNCTION NF_GET_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6732 INTEGER INDEX(*), REAL RVAL)
6733 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6734 INTEGER INDEX(*), DOUBLE DVAL)
6735 INTEGER FUNCTION NF_GET_VAR1(INTEGER NCID, INTEGER VARID,
6736 INTEGER INDEX(*), VAL)
6740 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6746 : The index of the data value to be read. The indices are relative to
6747 1, so for example, the first data value of a two-dimensional
6748 variable has index (1,1). The elements of index correspond to the
6749 variable’s dimensions. Hence, if the variable is a record variable,
6750 the last index is the record number.
6759 : The location into which the data value will be read. You cannot get
6760 CHARACTER data from a numeric variable or numeric data from a
6761 character variable. For numeric data, if the type of data differs
6762 from the netCDF variable type, type conversion will occur. (see
6763 [(netcdf)Type Conversion](netcdf.html#Type-Conversion) ‘Type
6764 Conversion’ in The NetCDF Users Guide).
6769 NF\_GET\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6770 Otherwise, the returned status indicates an error. Possible causes of
6773 - The variable ID is invalid for the specified netCDF dataset.
6774 - The specified indices were out of range for the rank of the
6775 specified variable. For example, a negative index or an index that
6776 is larger than the corresponding dimension length will cause an
6778 - The value is out of the range of values representable by the desired
6780 - The specified netCDF is in define mode rather than data mode.
6781 - The specified netCDF ID does not refer to an open netCDF dataset.
6786 Here is an example using NF\_GET\_VAR1\_DOUBLE to get the (4,3,2)
6787 element of the variable named rh in an existing netCDF dataset named
6788 foo.nc. For simplicity in this example, we ame that we know that rh
6789 is dimensioned with lon, lat, and time, so we want to get the value of
6790 rh that corresponds to the fourth lon value, the third lat value, and
6791 the second time value:
6796 INCLUDE 'netcdf.inc'
6798 INTEGER STATUS, NCID
6799 INTEGER RHID ! variable ID
6800 INTEGER RHINDX(3) ! where to get value
6801 DOUBLE PRECISION RHVAL ! put it here
6802 DATA RHINDX /4, 3, 2/
6804 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6805 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6807 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6808 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6809 STATUS = NF_GET_VAR1_DOUBLE (NCID, RHID, RHINDX, RHVAL)
6810 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6813 6.25 NF\_GET\_VAR\_ type
6814 ------------------------
6816 The members of the NF\_GET\_VAR\_ type family of functions read all the
6817 values from a netCDF variable of an open netCDF dataset. This is the
6818 simplest interface to use for reading the value of a scalar variable or
6819 when all the values of a multidimensional variable can be read at once.
6820 The values are read into consecutive locations with the first dimension
6821 varying fastest. The netCDF dataset must be in data mode.
6823 Take care when using the simplest forms of this interface with record
6824 variables (variables that use the NF\_UNLIMITED dimension) when you
6825 don’t specify how many records are to be read. If you try to read all
6826 the values of a record variable into an array but there are more records
6827 in the file than you ame, more data will be read than you expect,
6828 which may cause a segmentation violation. To avoidch problems, it is
6829 better to use the NF\_GET\_VARA\_type interfaces for variables that use
6830 the NF\_UNLIMITED dimension. See [NF\_GET\_VARA\_
6831 type](#NF_005fGET_005fVARA_005f-type).
6839 INTEGER FUNCTION NF_GET_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6841 INTEGER FUNCTION NF_GET_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6842 INTEGER*1 i1vals(*))
6843 INTEGER FUNCTION NF_GET_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6844 INTEGER*2 i2vals(*))
6845 INTEGER FUNCTION NF_GET_VAR_INT (INTEGER NCID, INTEGER VARID,
6847 INTEGER FUNCTION NF_GET_VAR_REAL (INTEGER NCID, INTEGER VARID,
6849 INTEGER FUNCTION NF_GET_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6851 INTEGER FUNCTION NF_GET_VAR (INTEGER NCID, INTEGER VARID,
6856 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6868 : The block of data values to be read. The data should be of the type
6869 appropriate for the function called. You cannot read CHARACTER data
6870 from a numeric variable or numeric data from a text variable. For
6871 numeric data, if the type of data differs from the netCDF variable
6872 type, type conversion will occur (see [(netcdf)Type
6873 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6874 in The NetCDF Users Guide).
6879 NF\_GET\_VAR\_ type returns the value NF\_NOERR if no errors occurred.
6880 Otherwise, the returned status indicates an error. Possible causes of
6883 - The variable ID is invalid for the specified netCDF dataset.
6884 - One or more of the values are out of the range of values
6885 representable by the desired type.
6886 - The specified netCDF is in define mode rather than data mode.
6887 - The specified netCDF ID does not refer to an open netCDF dataset.
6892 Here is an example using NF\_GET\_VAR\_DOUBLE to read all the values of
6893 the variable named rh from an existing netCDF dataset named foo.nc. For
6894 simplicity in this example, we ame that we know that rh is
6895 dimensioned with lon and lat, and that there are ten lon values and five
6901 INCLUDE 'netcdf.inc'
6903 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6904 INTEGER STATUS, NCID
6905 INTEGER RHID ! variable ID
6906 DOUBLE RHVALS(LONS, LATS)
6908 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6909 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6911 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6912 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6913 STATUS = NF_GET_VAR_DOUBLE (NCID, RHID, RHVALS)
6914 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6917 6.26 NF\_GET\_VARA\_ type
6918 -------------------------
6920 The members of the NF\_GET\_VARA\_ type family of functions read an
6921 array of values from a netCDF variable of an open netCDF dataset. The
6922 array is specified by giving a corner and a vector of edge lengths. The
6923 values are read into consecutive locations with the first dimension
6924 varying fastest. The netCDF dataset must be in data mode.
6932 INTEGER FUNCTION NF_GET_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6933 INTEGER START(*), INTEGER COUNT(*),
6935 INTEGER FUNCTION NF_GET_VARA_INT1(INTEGER NCID, INTEGER VARID,
6936 INTEGER START(*), INTEGER COUNT(*),
6937 INTEGER*1 i1vals(*))
6938 INTEGER FUNCTION NF_GET_VARA_INT2(INTEGER NCID, INTEGER VARID,
6939 INTEGER START(*), INTEGER COUNT(*),
6940 INTEGER*2 i2vals(*))
6941 INTEGER FUNCTION NF_GET_VARA_INT (INTEGER NCID, INTEGER VARID,
6942 INTEGER START(*), INTEGER COUNT(*),
6944 INTEGER FUNCTION NF_GET_VARA_REAL(INTEGER NCID, INTEGER VARID,
6945 INTEGER START(*), INTEGER COUNT(*),
6947 INTEGER FUNCTION NF_GET_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6948 INTEGER START(*), INTEGER COUNT(*),
6953 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6959 : A vector of integers specifying the index in the variable where the
6960 first of the data values will be read. The indices are relative to
6961 1, so for example, the first data value of a variable would have
6962 index (1, 1, ..., 1). The length of START must be the same as the
6963 number of dimensions of the specified variable. The elements of
6964 START correspond, in order, to the variable’s dimensions. Hence, if
6965 the variable is a record variable, the last index would correspond
6966 to the starting record number for reading the data values.
6969 : A vector of integers specifying the edge lengths along each
6970 dimension of the block of data values to be read. To read a single
6971 value, for example, specify COUNT as (1, 1, ..., 1). The length of
6972 COUNT is the number of dimensions of the specified variable. The
6973 elements of COUNT correspond, in order, to the variable’s
6974 dimensions. Hence, if the variable is a record variable, the last
6975 element of COUNT corresponds to a count of the number of records to
6978 Note: setting any element of the count array to zero causes the
6979 function to exit without error, and without doing anything.
6987 : The block of data values to be read. The data should be of the type
6988 appropriate for the function called. You cannot read CHARACTER data
6989 from a numeric variable or numeric data from a text variable. For
6990 numeric data, if the type of data differs from the netCDF variable
6991 type, type conversion will occur (see [(netcdf)Type
6992 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6993 in The NetCDF Users Guide).
6998 NF\_GET\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
6999 Otherwise, the returned status indicates an error. Possible causes of
7002 - The variable ID is invalid for the specified netCDF dataset.
7003 - The specified corner indices were out of range for the rank of the
7004 specified variable. For example, a negative index or an index that
7005 is larger than the corresponding dimension length will cause an
7007 - The specified edge lengths added to the specified corner would have
7008 referenced data out of range for the rank of the specified variable.
7009 For example, an edge length that is larger than the corresponding
7010 dimension length minus the corner index will cause an error.
7011 - One or more of the values are out of the range of values
7012 representable by the desired type.
7013 - The specified netCDF is in define mode rather than data mode.
7014 - The specified netCDF ID does not refer to an open netCDF dataset.
7019 Here is an example using NF\_GET\_VARA\_DOUBLE to read all the values of
7020 the variable named rh from an existing netCDF dataset named foo.nc. For
7021 simplicity in this example, we ame that we know that rh is
7022 dimensioned with lon, lat, and time, and that there are ten lon values,
7023 five lat values, and three time values.
7028 INCLUDE 'netcdf.inc'
7030 PARAMETER (NDIMS=3) ! number of dimensions
7031 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7032 INTEGER STATUS, NCID
7033 INTEGER RHID ! variable ID
7034 INTEGER START(NDIMS), COUNT(NDIMS)
7035 DOUBLE RHVALS(LONS, LATS, TIMES)
7036 DATA START /1, 1, 1/ ! start at first value
7037 DATA COUNT /LONS, LATS, TIMES/ ! get all the values
7039 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7040 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7042 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7043 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7044 STATUS = NF_GET_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
7045 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7048 6.27 NF\_GET\_VARS\_ type
7049 -------------------------
7051 The NF\_GET\_VARS\_ type family of functions read absampled (strided)
7052 array of values from a netCDF variable of an open netCDF
7053 dataset. Thebsampled array is specified by giving a corner, a
7054 vector of edge lengths, and a stride vector. The values are read with
7055 the first dimension of the netCDF variable varying fastest. The netCDF
7056 dataset must be in data mode.
7064 INTEGER FUNCTION NF_GET_VARS_TEXT (INTEGER NCID, INTEGER VARID,
7065 INTEGER START(*), INTEGER COUNT(*),
7066 INTEGER STRIDE(*),CHARACTER*(*) text)
7067 INTEGER FUNCTION NF_GET_VARS_INT1 (INTEGER NCID, INTEGER VARID,
7068 INTEGER START(*), INTEGER COUNT(*),
7069 INTEGER STRIDE(*),INTEGER*1 i1vals(*))
7070 INTEGER FUNCTION NF_GET_VARS_INT2 (INTEGER NCID, INTEGER VARID,
7071 INTEGER START(*), INTEGER COUNT(*),
7072 INTEGER STRIDE(*),INTEGER*2 i2vals(*))
7073 INTEGER FUNCTION NF_GET_VARS_INT (INTEGER NCID, INTEGER VARID,
7074 INTEGER START(*), INTEGER COUNT(*),
7075 INTEGER STRIDE(*), INTEGER ivals(*))
7076 INTEGER FUNCTION NF_GET_VARS_REAL (INTEGER NCID, INTEGER VARID,
7077 INTEGER START(*), INTEGER COUNT(*),
7078 INTEGER STRIDE(*), REAL rvals(*))
7079 INTEGER FUNCTION NF_GET_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
7080 INTEGER START(*), INTEGER COUNT(*),
7081 INTEGER STRIDE(*), DOUBLE dvals(*))
7085 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7091 : A vector of integers specifying the index in the variable from which
7092 the first of the data values will be read. The indices are relative
7093 to 1, so for example, the first data value of a variable would have
7094 index (1, 1, ..., 1). The elements of START correspond, in order, to
7095 the variable’s dimensions. Hence, if the variable is a record
7096 variable, the last index would correspond to the starting record
7097 number for reading the data values.
7100 : A vector of integers specifying the number of indices selected along
7101 each dimension. To read a single value, for example, specify COUNT
7102 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7103 the variable’s dimensions. Hence, if the variable is a record
7104 variable, the last element of COUNT corresponds to a count of the
7105 number of records to read.
7107 Note: setting any element of the count array to zero causes the
7108 function to exit without error, and without doing anything.
7111 : A vector of integers specifying, for each dimension, the interval
7112 between selected indices or the value 0. The elements of the vector
7113 correspond, in order, to the variable’s dimensions. A value of 1
7114 accesses adjacent values of the netCDF variable in the corresponding
7115 dimension; a value of 2 accesses every other value of the netCDF
7116 variable in the corresponding dimension; and so on. A 0 argument is
7117 treated as (1, 1, ..., 1).
7125 : The block of data values to be read. The data should be of the type
7126 appropriate for the function called. You cannot read CHARACTER data
7127 from a numeric variable or numeric data from a text variable. For
7128 numeric data, if the type of data differs from the netCDF variable
7129 type, type conversion will occur (see [(netcdf)Type
7130 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7131 in The NetCDF Users Guide).
7136 NF\_GET\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
7137 Otherwise, the returned status indicates an error. Possible causes of
7140 - The variable ID is invalid for the specified netCDF dataset.
7141 - The specified start, count and stride generate an index which is out
7143 - One or more of the values are out of the range of values
7144 representable by the desired type.
7145 - The specified netCDF is in define mode rather than data mode.
7146 - The specified netCDF ID does not refer to an open netCDF dataset.
7151 Here is an example using NF\_GET\_VARS\_DOUBLE to read every other value
7152 in each dimension of the variable named rh from an existing netCDF
7153 dataset named foo.nc. Values are assigned, using the same dimensional
7154 strides, to a 2-parameter array. For simplicity in this example, we
7155 ame that we know that rh is dimensioned with lon, lat, and time, and
7156 that there are ten lon values, five lat values, and three time values.
7161 INCLUDE 'netcdf.inc'
7163 PARAMETER (NDIMS=3) ! number of dimensions
7164 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7165 INTEGER STATUS, NCID
7166 INTEGER RHID ! variable ID
7167 INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
7168 DOUBLE DATA(LONS, LATS, TIMES)
7169 DATA START /1, 1, 1/ ! start at first value
7170 DATA COUNT /LONS, LATS, TIMES/
7171 DATA STRIDE /2, 2, 2/
7173 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7174 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7176 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7177 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7178 STATUS = NF_GET_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
7179 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7182 6.28 NF\_GET\_VARM\_ type
7183 -------------------------
7185 The NF\_GET\_VARM\_ type family of functions reads a mapped array
7186 section of values from a netCDF variable of an open netCDF dataset. The
7187 mapped array is specified by giving a corner, a vector of edge
7188 lengths, a stride vector, and an index mapping vector. The index mapping
7189 vector is a vector of integers that specifies the mapping between the
7190 dimensions of a netCDF variable and the in-memory structure of the
7191 internal data array. No amptions are made about the ordering or
7192 length of the dimensions of the data array. The netCDF dataset must be
7201 INTEGER FUNCTION NF_GET_VARM_TEXT (INTEGER NCID, INTEGER VARID,
7202 INTEGER START(*), INTEGER COUNT(*),
7203 INTEGER STRIDE(*), INTEGER IMAP(*),
7205 INTEGER FUNCTION NF_GET_VARM_INT1 (INTEGER NCID, INTEGER VARID,
7206 INTEGER START(*), INTEGER COUNT(*),
7207 INTEGER STRIDE(*), INTEGER IMAP(*),
7208 INTEGER*1 i1vals(*))
7209 INTEGER FUNCTION NF_GET_VARM_INT2 (INTEGER NCID, INTEGER VARID,
7210 INTEGER START(*), INTEGER COUNT(*),
7211 INTEGER STRIDE(*), INTEGER IMAP(*),
7212 INTEGER*2 i2vals(*))
7213 INTEGER FUNCTION NF_GET_VARM_INT (INTEGER NCID, INTEGER VARID,
7214 INTEGER START(*), INTEGER COUNT(*),
7215 INTEGER STRIDE(*), INTEGER IMAP(*),
7217 INTEGER FUNCTION NF_GET_VARM_REAL (INTEGER NCID, INTEGER VARID,
7218 INTEGER START(*), INTEGER COUNT(*),
7219 INTEGER STRIDE(*), INTEGER IMAP(*),
7221 INTEGER FUNCTION NF_GET_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
7222 INTEGER START(*), INTEGER COUNT(*),
7223 INTEGER STRIDE(*), INTEGER IMAP(*),
7228 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7234 : A vector of integers specifying the index in the variable from which
7235 the first of the data values will be read. The indices are relative
7236 to 1, so for example, the first data value of a variable would have
7237 index (1, 1, ..., 1). The elements of START correspond, in order, to
7238 the variable’s dimensions. Hence, if the variable is a record
7239 variable, the last index would correspond to the starting record
7240 number for reading the data values.
7243 : A vector of integers specifying the number of indices selected along
7244 each dimension. To read a single value, for example, specify COUNT
7245 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7246 the variable’s dimensions. Hence, if the variable is a record
7247 variable, the last element of COUNT corresponds to a count of the
7248 number of records to read.
7250 Note: setting any element of the count array to zero causes the
7251 function to exit without error, and without doing anything.
7254 : A vector of integers specifying, for each dimension, the interval
7255 between selected indices or the value 0. The elements of the vector
7256 correspond, in order, to the variable’s dimensions. A value of 1
7257 accesses adjacent values of the netCDF variable in the corresponding
7258 dimension; a value of 2 accesses every other value of the netCDF
7259 variable in the corresponding dimension; and so on. A 0 argument is
7260 treated as (1, 1, ..., 1).
7263 : A vector of integers that specifies the mapping between the
7264 dimensions of a netCDF variable and the in-memory structure of the
7265 internal data array. IMAP(1) gives the distance between elements of
7266 the internal array corresponding to the most rapidly varying
7267 dimension of the netCDF variable. IMAP(N) (where N is the rank of
7268 the netCDF variable) gives the distance between elements of the
7269 internal array corresponding to the most slowly varying dimension of
7270 the netCDF variable. Intervening IMAP elements correspond to other
7271 dimensions of the netCDF variable in the obvious way. Distances
7272 between elements are specified in units of elements (the distance
7273 between internal elements that occupy adjacent memory locations is 1
7274 and not the element’s byte-length as in netCDF 2).
7282 : The block of data values to be read. The data should be of the type
7283 appropriate for the function called. You cannot read CHARACTER data
7284 from a numeric variable or numeric data from a text variable. For
7285 numeric data, if the type of data differs from the netCDF variable
7286 type, type conversion will occur (see [(netcdf)Type
7287 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7288 in The NetCDF Users Guide).
7293 NF\_GET\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
7294 Otherwise, the returned status indicates an error. Possible causes of
7297 - The variable ID is invalid for the specified netCDF dataset.
7298 - The specified START, COUNT, and STRIDE generate an index which is
7299 out of range. Note that no error checking is possible on the imap
7301 - One or more of the values are out of the range of values
7302 representable by the desired type.
7303 - The specified netCDF is in define mode rather than data mode.
7304 - The specified netCDF ID does not refer to an open netCDF dataset.
7309 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
7310 variable and an internal array of the same shape:
7315 REAL A(2,3,4) ! same shape as netCDF variable
7317 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
7318 ! ---------------- ----------------------
7319 ! most rapidly varying 1
7320 ! intermediate 2 (=IMAP(1)*2)
7321 ! most slowly varying 6 (=IMAP(2)*3)
7324 Using the IMAP vector above with NF\_GET\_VARM\_REAL obtains the same
7325 rlt as simply using NF\_GET\_VAR\_REAL.
7327 Here is an example of using NF\_GET\_VARM\_REAL to transpose a netCDF
7328 variable named rh which is described by the FORTRAN declaration REAL
7329 RH(4,6) (note the size and order of the dimensions):
7334 INCLUDE 'netcdf.inc'
7336 PARAMETER (NDIM=2) ! rank of netCDF variable
7337 INTEGER NCID ! netCDF dataset ID
7338 INTEGER STATUS ! return code
7339 INTEGER RHID ! variable ID
7340 INTEGER START(NDIM) ! netCDF variable start point
7341 INTEGER COUNT(NDIM) ! size of internal array
7342 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7343 INTEGER IMAP(NDIM) ! internal array inter-element distances
7344 REAL RH(6,4) ! note transposition of netCDF variable dimensions
7345 DATA START /1, 1/ ! start at first netCDF variable element
7346 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
7347 ! to netCDF variable -- not internal array
7348 DATA STRIDE /1, 1/ ! sample every netCDF element
7349 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
7351 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7352 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7354 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7355 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7357 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7358 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7361 Here is another example of using NF\_GET\_VARM\_REAL to simultaneously
7362 transpose andbsample the same netCDF variable, by accessing every
7363 other point of the netCDF variable:
7368 INCLUDE 'netcdf.inc'
7370 PARAMETER (NDIM=2) ! rank of netCDF variable
7371 INTEGER NCID ! netCDF dataset ID
7372 INTEGER STATUS ! return code
7373 INTEGER RHID ! variable ID
7374 INTEGER START(NDIM) ! netCDF variable start point
7375 INTEGER COUNT(NDIM) ! size of internal array
7376 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7377 INTEGER IMAP(NDIM) ! internal array inter-element distances
7378 REAL RH(3,2) ! note transposition of bsampled) dimensions
7379 DATA START /1, 1/ ! start at first netCDF variable value
7380 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
7381 ! to netCDF variable -- not internal array
7382 DATA STRIDE /2, 2/ ! sample every other netCDF element
7383 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
7385 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7386 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7388 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7389 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7391 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7392 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7395 6.29 Reading and Writing Character String Values
7396 ------------------------------------------------
7398 Character strings are not a primitive netCDF external data type, in part
7399 because FORTRAN does notpport the abstraction of variable-length
7400 character strings (the FORTRAN LEN function returns the static length of
7401 a character string, not its dynamic length). As a rlt, a character
7402 string cannot be written or read as a single object in the netCDF
7403 interface. Instead, a character string must be treated as an array of
7404 characters, and array access must be used to read and write character
7405 strings as variable data in netCDF datasets. Furthermore,
7406 variable-length strings are notpported by the netCDF interface except
7407 by convention; for example, you may treat a zero byte as terminating a
7408 character string, but you must explicitly specify the length of strings
7409 to be read from and written to netCDF variables.
7411 Character strings as attribute values are easier to use, since the
7412 strings are treated as a single unit for access. However, the value of a
7413 character-string attribute is still an array of characters with an
7414 explicit length that must be specified when the attribute is defined.
7416 When you define a variable that will have character-string values, use a
7417 character-position dimension as the most quickly varying dimension for
7418 the variable (the first dimension for the variable in FORTRAN). The
7419 length of the character-position dimension will be the maximum string
7420 length of any value to be stored in the character-string variable. Space
7421 for maximum-length strings will be allocated in the disk representation
7422 of character-string variables whether you use the space or not. If two
7423 or more variables have the same maximum length, the same
7424 character-position dimension may be used in defining the variable
7427 To write a character-string value into a character-string variable, use
7428 either entire variable access or array access. The latter requires that
7429 you specify both a corner and a vector of edge lengths. The
7430 character-position dimension at the corner should be one for FORTRAN. If
7431 the length of the string to be written is n, then the vector of edge
7432 lengths will specify n in the character-position dimension, and one for
7433 all the other dimensions:(n, 1, 1, ..., 1).
7435 In FORTRAN, fixed-length strings may be written to a netCDF dataset
7436 without a terminating character, to save space. Variable-length strings
7437 should follow the C convention of writing strings with a terminating
7438 zero byte so that the intended length of the string can be determined
7439 when it is later read by either C or FORTRAN programs.
7441 The FORTRAN interface for reading and writing strings requires the use
7442 of different functions for accessing string values and numeric values,
7443 because standard FORTRAN does not permit the same formal parameter to be
7444 used for both character values and numeric values. An additional
7445 argument, specifying the declared length of the character string passed
7446 as a value, is required for NF\_PUT\_VARA\_TEXT and NF\_GET\_VARA\_TEXT.
7447 The actual length of the string is specified as the value of the
7448 edge-length vector corresponding to the character-position dimension.
7450 Here is an example that defines a record variable, tx, for character
7451 strings and stores a character-string value into the third record using
7452 NF\_PUT\_VARA\_TEXT. In this example, we ame the string variable and
7453 data are to be added to an existing netCDF dataset named foo.nc that
7454 already has an unlimited record dimension time.
7459 INCLUDE 'netcdf.inc'
7461 INTEGER TDIMS, TXLEN
7462 PARAMETER (TDIMS=2) ! number of TX dimensions
7463 PARAMETER (TXLEN = 15) ! length of example string
7465 INTEGER CHID ! char position dimension id
7466 INTEGER TIMEID ! record dimension id
7467 INTEGER TXID ! variable ID
7468 INTEGER TXDIMS(TDIMS) ! variable shape
7469 INTEGER TSTART(TDIMS), TCOUNT(TDIMS)
7470 CHARACTER*40 TXVAL ! max length 40
7471 DATA TXVAL /'example string'/
7473 TXVAL(TXLEN:TXLEN) = CHAR(0) ! null terminate
7475 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
7476 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7477 STATUS = NF_REDEF(NCID) ! enter define mode
7478 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7480 ! define character-position dimension for strings of max length 40
7481 STATUS = NF_DEF_DIM(NCID, "chid", 40, CHID)
7482 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7484 ! define a character-string variable
7485 TXDIMS(1) = CHID ! character-position dimension first
7487 STATUS = NF_DEF_VAR(NCID, "tx", NF_CHAR, TDIMS, TXDIMS, TXID)
7488 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7490 STATUS = NF_ENDDEF(NCID) ! leave define mode
7491 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7493 ! write txval into tx netCDF variable in record 3
7494 TSTART(1) = 1 ! start at beginning of variable
7495 TSTART(2) = 3 ! record number to write
7496 TCOUNT(1) = TXLEN ! number of chars to write
7497 TCOUNT(2) = 1 ! only write one record
7498 STATUS = NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL)
7499 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7505 What happens when you try to read a value that was never written in an
7506 open netCDF dataset? You might expect that this should always be an
7507 error, and that you should get an error message or an error status
7508 returned. You do get an error if you try to read data from a netCDF
7509 dataset that is not open for reading, if the variable ID is invalid for
7510 the specified netCDF dataset, or if the specified indices are not
7511 properly within the range defined by the dimension lengths of the
7512 specified variable. Otherwise, reading a value that was not written
7513 returns a special fill value used to fill in any undefined values when a
7514 netCDF variable is first written.
7516 You may ignore fill values and use the entire range of a netCDF external
7517 data type, but in this case you should makere you write all data
7518 values before reading them. If you know you will be writing all the data
7519 before reading it, you can specify that no prefilling of variables with
7520 fill values will occur by calling NF\_SET\_FILL before writing. This may
7521 provide a significant performance gain for netCDF writes.
7523 The variable attribute \_FillValue may be used to specify the fill value
7524 for a variable. Their are default fill values for each type, defined in
7525 the include file netcdf.inc: NF\_FILL\_CHAR, NF\_FILL\_INT1 (same as
7526 NF\_FILL\_BYTE), NF\_FILL\_INT2 (same as NF\_FILL\_SHORT),
7527 NF\_FILL\_INT, NF\_FILL\_REAL (same as NF\_FILL\_FLOAT), and
7530 The netCDF byte and character types have different default fill values.
7531 The default fill value for characters is the zero byte, a useful value
7532 for detecting the end of variable-length C character strings. If you
7533 need a fill value for a byte variable, it is recommended that you
7534 explicitly define an appropriate \_FillValue attribute, as generic
7535 utilitiesch as ncdump will not ame a default fill value for byte
7538 Type conversion for fill values is identical to type conversion for
7539 other values: attempting to convert a value from one type to another
7540 type that can’t represent the value rlts in a range error. Such
7541 errors may occur on writing or reading values from a larger type ch
7542 as double) to a smaller type ch as float), if the fill value for the
7543 larger type cannot be represented in the smaller type.
7545 6.31 NF\_RENAME\_VAR
7546 --------------------
7548 The function NF\_RENAME\_VAR changes the name of a netCDF variable in an
7549 open netCDF dataset. If the new name is longer than the old name, the
7550 netCDF dataset must be in define mode. You cannot rename a variable to
7551 have the name of any existing variable.
7559 INTEGER FUNCTION NF_RENAME_VAR (INTEGER NCID, INTEGER VARID,
7560 CHARACTER*(*) NEWNAM)
7564 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7570 : New name for the specified variable.
7575 NF\_RENAME\_VAR returns the value NF\_NOERR if no errors occurred.
7576 Otherwise, the returned status indicates an error. Possible causes of
7579 - The new name is in use as the name of another variable.
7580 - The variable ID is invalid for the specified netCDF dataset.
7581 - The specified netCDF ID does not refer to an open netCDF dataset.
7586 Here is an example using NF\_RENAME\_VAR to rename the variable rh to
7587 rel\_hum in an existing netCDF dataset named foo.nc:
7592 INCLUDE 'netcdf.inc'
7594 INTEGER STATUS, NCID
7595 INTEGER RHID ! variable ID
7597 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7598 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7600 STATUS = NF_REDEF (NCID) ! enter definition mode
7601 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7602 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7603 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7604 STATUS = NF_RENAME_VAR (NCID, RHID, 'rel_hum')
7605 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7606 STATUS = NF_ENDDEF (NCID) ! leave definition mode
7607 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7611 6.32 Change between Collective and Independent Parallel Access: NF\_VAR\_PAR\_ACCESS
7612 ------------------------------------------------------------------------------------
7614 The function NF\_VAR\_PAR\_ACCESS changes whether read/write operations
7615 on a parallel file system are performed collectively or independently
7616 (the default) on the variable. This function can only be called if the
7617 file was created with NF\_CREATE\_PAR (see
7618 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)) or opened with NF\_OPEN\_PAR
7619 (see [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)).
7621 This function is only available if the netCDF library was built with a
7622 HDF5 library for which –enable-parallel was used, and which was linked
7623 (like HDF5) to MPI libraries.
7625 Calling this function affects only the open file - information about
7626 whether a variable is to be accessed collectively or independently is
7627 not written to the data file. Every time you open a file on a parallel
7628 file system, all variables default to independent operations. The change
7629 a variable to collective lasts only as long as that file is open.
7631 The variable can be changed from collective to independent, and back, as
7640 INTEGER NF_VAR_PAR_ACCESS(INTEGER NCID, INTEGER VARID, INTEGER ACCESS);
7644 : NetCDF ID, from a previous call to NF\_OPEN\_PAR (see
7645 [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)) or NF\_CREATE\_PAR (see
7646 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)).
7652 : NF\_INDEPENDENT to set this variable to independent operations.
7653 NF\_COLLECTIVE to set it to collective operations.
7662 : No variable found.
7665 : Not a netCDF-4 file.
7668 : File not opened for parallel access.
7673 This example comes from test program nf\_test/ftst\_parallel.F. For this
7674 test to be run, netCDF must have been built with a parallel-enabled
7675 HDF5, and –enable-parallel-tests must have been used when configuring
7681 retval = nf_var_par_access(ncid, varid, nf_collective)
7682 if (retval .ne. nf_noerr) stop 2
7689 7.1 Attributes Introduction
7690 ---------------------------
7692 Attributes may be associated with each netCDF variable to specifych
7693 properties as units, special values, maximum and minimum valid values,
7694 scaling factors, and offsets. Attributes for a netCDF dataset are
7695 defined when the dataset is first created, while the netCDF dataset is
7696 in define mode. Additional attributes may be added later by reentering
7697 define mode. A netCDF attribute has a netCDF variable to which it is
7698 assigned, a name, a type, a length, and a sequence of one or more
7699 values. An attribute is designated by its variable ID and name. When an
7700 attribute name is not known, it may be designated by its variable ID and
7701 number in order to determine its name, using the function
7704 The attributes associated with a variable are typically defined
7705 immediately after the variable is created, while still in define mode.
7706 The data type, length, and value of an attribute may be changed even
7707 when in data mode, as long as the changed attribute requires no more
7708 space than the attribute as originally defined.
7710 It is also possible to have attributes that are not associated with any
7711 variable. These are called global attributes and are identified by using
7712 NF\_GLOBAL as a variable pseudo-ID. Global attributes are ally
7713 related to the netCDF dataset as a whole and may be used for purposes
7714 such as providing a title or processing history for a netCDF dataset.
7716 Attributes are much more useful when they follow established community
7717 conventions. See [(netcdf)Attribute
7718 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
7719 Conventions’ in The NetCDF Users Guide.
7721 Operationspported on attributes are:
7723 - Create an attribute, given its variable ID, name, data type, length,
7725 - Get attribute’s data type and length from its variable ID and name.
7726 - Get attribute’s value from its variable ID and name.
7727 - Copy attribute from one netCDF variable to another.
7728 - Get name of attribute from its number.
7729 - Rename an attribute.
7730 - Delete an attribute.
7732 7.2 NF\_PUT\_ATT\_ type
7733 -----------------------
7735 The function NF\_PUT\_ATT\_ type adds or changes a variable attribute or
7736 global attribute of an open netCDF dataset. If this attribute is new, or
7737 if the space required to store the attribute is greater than before, the
7738 netCDF dataset must be in define mode.
7743 Although it’s possible to create attributes of all types, text and
7744 double attributes are adequate for most purposes.
7749 INTEGER FUNCTION NF_PUT_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7750 CHARACTER*(*) NAME, INTEGER LEN,
7752 INTEGER FUNCTION NF_PUT_ATT_INT1 (INTEGER NCID, INTEGER VARID,
7753 CHARACTER*(*) NAME, INTEGER XTYPE,
7754 LEN, INTEGER*1 I1VALS(*))
7755 INTEGER FUNCTION NF_PUT_ATT_INT2 (INTEGER NCID, INTEGER VARID,
7756 CHARACTER*(*) NAME, INTEGER XTYPE,
7757 LEN, INTEGER*2 I2VALS(*))
7758 INTEGER FUNCTION NF_PUT_ATT_INT (INTEGER NCID, INTEGER VARID,
7759 CHARACTER*(*) NAME, INTEGER XTYPE,
7760 LEN, INTEGER IVALS(*))
7761 INTEGER FUNCTION NF_PUT_ATT_REAL (INTEGER NCID, INTEGER VARID,
7762 CHARACTER*(*) NAME, INTEGER XTYPE,
7764 INTEGER FUNCTION NF_PUT_ATT_DOUBLE(INTEGER NCID, INTEGER VARID,
7765 CHARACTER*(*) NAME, INTEGER XTYPE,
7766 LEN, DOUBLE DVALS(*))
7767 INTEGER FUNCTION NF_PUT_ATT (INTEGER NCID, INTEGER VARID,
7768 CHARACTER*(*) NAME, INTEGER XTYPE,
7773 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7776 : Variable ID of the variable to which the attribute will be assigned
7777 or NF\_GLOBAL for a global attribute.
7780 : Attribute name. Attribute name conventions are amed by some
7781 netCDF generic applications, e.g., ‘units’ as the name for a string
7782 attribute that gives the units for a netCDF variable. See
7783 [(netcdf)Attribute Conventions](netcdf.html#Attribute-Conventions)
7784 ‘Attribute Conventions’ in The NetCDF Users Guide.
7787 : One of the set of predefined netCDF external data types. The type of
7788 this parameter, NF\_TYPE, is defined in the netCDF header file. The
7789 valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
7790 NF\_INT, NF\_FLOAT, and NF\_DOUBLE. Although it’s possible to create
7791 attributes of all types, NF\_CHAR and NF\_DOUBLE attributes are
7792 adequate for most purposes.
7795 : Number of values provided for the attribute.
7804 : An array of LEN attribute values. The data should be of a type
7805 appropriate for the function called. You cannot write CHARACTER data
7806 into a numeric attribute or numeric data into a text attribute. For
7807 numeric data, if the type of data differs from the attribute type,
7808 type conversion will occur See [(netcdf)Type
7809 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7810 in The NetCDF Users Guide.
7815 NF\_PUT\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
7816 Otherwise, the returned status indicates an error. Possible causes of
7819 - The variable ID is invalid for the specified netCDF dataset.
7820 - The specified netCDF type is invalid.
7821 - The specified length is negative.
7822 - The specified open netCDF dataset is in data mode and the specified
7823 attribute would expand.
7824 - The specified open netCDF dataset is in data mode and the specified
7825 attribute does not already exist.
7826 - The specified netCDF ID does not refer to an open netCDF dataset.
7827 - The number of attributes for this variable exceeds NF\_MAX\_ATTRS.
7832 Here is an example using NF\_PUT\_ATT\_DOUBLE to add a variable
7833 attribute named valid\_range for a netCDF variable named rh and a global
7834 attribute named title to an existing netCDF dataset named foo.nc:
7839 INCLUDE 'netcdf.inc'
7841 INTEGER STATUS, NCID
7842 INTEGER RHID ! variable ID
7844 DATA RHRNGE /0.0D0, 100.0D0/
7846 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7847 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7849 STATUS = NF_REDEF (NCID) ! enter define mode
7850 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7851 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7852 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7854 STATUS = NF_PUT_ATT_DOUBLE (NCID, RHID, 'valid_range', NF_DOUBLE, &
7856 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7857 STATUS = NF_PUT_ATT_TEXT (NCID, NF_GLOBAL, 'title', 19,
7858 'example netCDF dataset')
7859 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7861 STATUS = NF_ENDDEF (NCID) ! leave define mode
7862 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7865 7.3 NF\_INQ\_ATT Family
7866 -----------------------
7868 This family of functions returns information about a netCDF attribute.
7869 All but one of these functions require the variable ID and attribute
7870 name; the exception is NF\_INQ\_ATTNAME. Information about an attribute
7871 includes its type, length, name, and number. See the NF\_GET\_ATT family
7872 for getting attribute values.
7874 The function NF\_INQ\_ATTNAME gets the name of an attribute, given its
7875 variable ID and number. This function is useful in generic applications
7876 that need to get the names of all the attributes associated with a
7877 variable, since attributes are accessed by name rather than number in
7878 all other attribute functions. The number of an attribute is more
7879 volatile than the name, since it can change when other attributes of the
7880 same variable are deleted. This is why an attribute number is not called
7883 The function NF\_INQ\_ATT returns the attribute’s type and length. The
7884 other functions each return just one item of information about an
7893 INTEGER FUNCTION NF_INQ_ATT (INTEGER NCID, INTEGER VARID,
7894 CHARACTER*(*) NAME, INTEGER xtype,
7896 INTEGER FUNCTION NF_INQ_ATTTYPE(INTEGER NCID, INTEGER VARID,
7897 CHARACTER*(*) NAME, INTEGER xtype)
7898 INTEGER FUNCTION NF_INQ_ATTLEN (INTEGER NCID, INTEGER VARID,
7899 CHARACTER*(*) NAME, INTEGER len)
7900 INTEGER FUNCTION NF_INQ_ATTNAME(INTEGER NCID, INTEGER VARID,
7901 INTEGER ATTNUM, CHARACTER*(*) name)
7902 INTEGER FUNCTION NF_INQ_ATTID (INTEGER NCID, INTEGER VARID,
7903 CHARACTER*(*) NAME, INTEGER attnum)
7907 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7910 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
7914 : Attribute name. For NF\_INQ\_ATTNAME, this is a pointer to the
7915 location for the returned attribute name.
7918 : Returned attribute type, one of the set of predefined netCDF
7919 external data types. The valid netCDF external data types are
7920 NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, and NF\_DOUBLE.
7923 : Returned number of values currently stored in the attribute. For a
7924 string-valued attribute, this is the number of characters in the
7928 : For NF\_INQ\_ATTNAME, the input attribute number; for
7929 NF\_INQ\_ATTID, the returned attribute number. The attributes for
7930 each variable are numbered from 1 (the first attribute) to NATTS,
7931 where NATTS is the number of attributes for the variable, as
7932 returned from a call to NF\_INQ\_VARNATTS.
7934 (If you already know an attribute name, knowing its number is not
7935 very useful, because accessing information about an attribute
7941 Each function returns the value NF\_NOERR if no errors occurred.
7942 Otherwise, the returned status indicates an error. Possible causes of
7945 - The variable ID is invalid for the specified netCDF dataset.
7946 - The specified attribute does not exist.
7947 - The specified netCDF ID does not refer to an open netCDF dataset.
7948 - For NF\_INQ\_ATTNAME, the specified attribute number is negative or
7949 more than the number of attributes defined for the specified
7955 Here is an example using NF\_INQ\_ATT to find out the type and length of
7956 a variable attribute named valid\_range for a netCDF variable named rh
7957 and a global attribute named title in an existing netCDF dataset named
7963 INCLUDE 'netcdf.inc'
7965 INTEGER STATUS, NCID
7966 INTEGER RHID ! variable ID
7967 INTEGER VRLEN, TLEN ! attribute lengths
7969 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7970 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7972 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7973 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7975 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
7976 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7977 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
7978 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7981 7.4 NF\_GET\_ATT\_ type
7982 -----------------------
7984 Members of the NF\_GET\_ATT\_ type family of functions get the value(s)
7985 of a netCDF attribute, given its variable ID and name.
7993 INTEGER FUNCTION NF_GET_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7996 INTEGER FUNCTION NF_GET_ATT_INT1 (INTEGER NCID, INTEGER VARID,
7998 INTEGER*1 i1vals(*))
7999 INTEGER FUNCTION NF_GET_ATT_INT2 (INTEGER NCID, INTEGER VARID,
8001 INTEGER*2 i2vals(*))
8002 INTEGER FUNCTION NF_GET_ATT_INT (INTEGER NCID, INTEGER VARID,
8005 INTEGER FUNCTION NF_GET_ATT_REAL (INTEGER NCID, INTEGER VARID,
8008 INTEGER FUNCTION NF_GET_ATT_DOUBLE (INTEGER NCID, INTEGER VARID,
8011 INTEGER FUNCTION NF_GET_ATT (INTEGER NCID, INTEGER VARID,
8012 CHARACTER*(*) NAME, * vals(*))
8016 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8019 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
8032 : Returned attribute values. All elements of the vector of attribute
8033 values are returned, so you must provide enough space to hold them.
8034 If you don’t know how much space to reserve, call NF\_INQ\_ATTLEN
8035 first to find out the length of the attribute. You cannot read
8036 character data from a numeric variable or numeric data from a text
8037 variable. For numeric data, if the type of data differs from the
8038 netCDF variable type, type conversion will occur. See [(netcdf)Type
8039 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
8040 in The The NetCDF Users Guide.
8045 NF\_GET\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
8046 Otherwise, the returned status indicates an error. Possible causes of
8049 - The variable ID is invalid for the specified netCDF dataset.
8050 - The specified attribute does not exist.
8051 - The specified netCDF ID does not refer to an open netCDF dataset.
8052 - One or more of the attribute values are out of the range of values
8053 representable by the desired type.
8058 Here is an example using NF\_GET\_ATT\_DOUBLE to determine the values of
8059 a variable attribute named valid\_range for a netCDF variable named rh
8060 and a global attribute named title in an existing netCDF dataset named
8061 foo.nc. In this example, it is amed that we don’t know how many
8062 values will be returned, but that we do know the types of the
8063 attributes. Hence, to allocate enough space to store them, we must first
8064 inquire about the length of the attributes.
8069 INCLUDE 'netcdf.inc'
8071 PARAMETER (MVRLEN=3) ! max number of "valid_range" values
8072 PARAMETER (MTLEN=80) ! max length of "title" attribute
8073 INTEGER STATUS, NCID
8074 INTEGER RHID ! variable ID
8075 INTEGER VRLEN, TLEN ! attribute lengths
8076 DOUBLE PRECISION VRVAL(MVRLEN) ! vr attribute values
8077 CHARACTER*80 TITLE ! title attribute values
8079 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8080 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8082 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8083 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8085 ! find out attribute lengths, to makere we have enough space
8086 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
8087 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8088 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
8089 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8090 ! get attribute values, if not too big
8091 IF (VRLEN .GT. MVRLEN) THEN
8092 WRITE (*,*) 'valid_range attribute too big!'
8095 STATUS = NF_GET_ATT_DOUBLE (NCID, RHID, 'valid_range', VRVAL)
8096 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8098 IF (TLEN .GT. MTLEN) THEN
8099 WRITE (*,*) 'title attribute too big!'
8102 STATUS = NF_GET_ATT_TEXT (NCID, NF_GLOBAL, 'title', TITLE)
8103 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8110 The function NF\_COPY\_ATT copies an attribute from one open netCDF
8111 dataset to another. It can also be used to copy an attribute from one
8112 variable to another within the same netCDF.
8114 If used to copy an attribute of user-defined type, then that
8115 user-defined type must already be defined in the target file. In the
8116 case of user-defined attributes, enddef/redef is called for ncid\_in and
8117 ncid\_out if they are in define mode. (This is the ere that all
8118 user-defined types are committed to the file(s) before the copy is
8127 INTEGER FUNCTION NF_COPY_ATT (INTEGER NCID_IN, INTEGER VARID_IN,
8128 CHARACTER*(*) NAME, INTEGER NCID_OUT,
8133 : The netCDF ID of an input netCDF dataset from which the attribute
8134 will be copied, from a previous call to NF\_OPEN or NF\_CREATE.
8137 : ID of the variable in the input netCDF dataset from which the
8138 attribute will be copied, or NF\_GLOBAL for a global attribute.
8141 : Name of the attribute in the input netCDF dataset to be copied.
8144 : The netCDF ID of the output netCDF dataset to which the attribute
8145 will be copied, from a previous call to NF\_OPEN or NF\_CREATE. It
8146 is permissible for the input and output netCDF IDs to be the same.
8147 The output netCDF dataset should be in define mode if the attribute
8148 to be copied does not already exist for the target variable, or if
8149 it would cause an existing target attribute to grow.
8152 : ID of the variable in the output netCDF dataset to which the
8153 attribute will be copied, or NF\_GLOBAL to copy to a global
8159 NF\_COPY\_ATT returns the value NF\_NOERR if no errors occurred.
8160 Otherwise, the returned status indicates an error. Possible causes of
8163 - The input or output variable ID is invalid for the specified netCDF
8165 - The specified attribute does not exist.
8166 - The output netCDF is not in define mode and the attribute is new for
8167 the output dataset is larger than the existing attribute.
8168 - The input or output netCDF ID does not refer to an open netCDF
8174 Here is an example using NF\_COPY\_ATT to copy the variable attribute
8175 units from the variable rh in an existing netCDF dataset named foo.nc to
8176 the variable avgrh in another existing netCDF dataset named bar.nc,
8177 aming that the variable avgrh already exists, but does not yet have a
8183 INCLUDE 'netcdf.inc'
8185 INTEGER STATUS ! error status
8186 INTEGER NCID1, NCID2 ! netCDF IDs
8187 INTEGER RHID, AVRHID ! variable IDs
8189 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID1)
8190 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8191 STATUS = NF_OPEN ('bar.nc', NF_WRITE, NCID2)
8192 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8194 STATUS = NF_INQ_VARID (NCID1, 'rh', RHID)
8195 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8196 STATUS = NF_INQ_VARID (NCID2, 'avgrh', AVRHID)
8197 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8199 STATUS = NF_REDEF (NCID2) ! enter define mode
8200 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8201 ! copy variable attribute from "rh" to "avgrh"
8202 STATUS = NF_COPY_ATT (NCID1, RHID, 'units', NCID2, AVRHID)
8203 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8205 STATUS = NF_ENDDEF (NCID2) ! leave define mode
8206 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8212 The function NF\_RENAME\_ATT changes the name of an attribute. If the
8213 new name is longer than the original name, the netCDF dataset must be in
8214 define mode. You cannot rename an attribute to have the same name as
8215 another attribute of the same variable.
8223 INTEGER FUNCTION NF_RENAME_ATT (INTEGER NCID, INTEGER VARID,
8225 CHARACTER*(*) NEWNAME)
8229 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE
8232 : ID of the attribute’s variable, or NF\_GLOBAL for a global attribute
8235 : The current attribute name.
8238 : The new name to be assigned to the specified attribute. If the new
8239 name is longer than the current name, the netCDF dataset must be in
8245 NF\_RENAME\_ATT returns the value NF\_NOERR if no errors occurred.
8246 Otherwise, the returned status indicates an error. Possible causes of
8249 - The specified variable ID is not valid.
8250 - The new attribute name is already in use for another attribute of
8251 the specified variable.
8252 - The specified netCDF dataset is in data mode and the new name is
8253 longer than the old name.
8254 - The specified attribute does not exist.
8255 - The specified netCDF ID does not refer to an open netCDF dataset.
8260 Here is an example using NF\_RENAME\_ATT to rename the variable
8261 attribute units to Units for a variable rh in an existing netCDF dataset
8267 INCLUDE "netcdf.inc"
8269 INTEGER STATUS ! error status
8270 INTEGER NCID ! netCDF ID
8271 INTEGER RHID ! variable ID
8273 STATUS = NF_OPEN ("foo.nc", NF_NOWRITE, NCID)
8274 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8276 STATUS = NF_INQ_VARID (NCID, "rh", RHID)
8277 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8280 STATUS = NF_RENAME_ATT (NCID, RHID, "units", "Units")
8281 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8287 The function NF\_DEL\_ATT deletes a netCDF attribute from an open netCDF
8288 dataset. The netCDF dataset must be in define mode.
8293 INTEGER FUNCTION NF\_DEL\_ATT (INTEGER NCID, INTEGER VARID,
8294 CHARACTER\*(\*) NAME)
8297 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8300 : ID of the attribute’s variable, or NF\_GLOBAL for a global
8304 : The name of the attribute to be deleted.
8309 NF\_DEL\_ATT returns the value NF\_NOERR if no errors occurred.
8310 Otherwise, the returned status indicates an error. Possible causes of
8313 - The specified variable ID is not valid.
8314 - The specified netCDF dataset is in data mode.
8315 - The specified attribute does not exist.
8316 - The specified netCDF ID does not refer to an open netCDF dataset.
8321 Here is an example using NF\_DEL\_ATT to delete the variable attribute
8322 Units for a variable rh in an existing netCDF dataset named foo.nc:
8327 INCLUDE 'netcdf.inc'
8329 INTEGER STATUS ! error status
8330 INTEGER NCID ! netCDF ID
8331 INTEGER RHID ! variable ID
8333 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8334 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8336 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8337 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8340 STATUS = NF_REDEF (NCID) ! enter define mode
8341 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8342 STATUS = NF_DEL_ATT (NCID, RHID, 'Units')
8343 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8344 STATUS = NF_ENDDEF (NCID) ! leave define mode
8345 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8348 A. NetCDF 2 to NetCDF 3 Fortran 77 Transition Guide {#f77_nc2_to_nc3_transition_guide}
8349 ===================================================
8351 A.1 Overview of FORTRAN interface changes {#f77_overview_of_interface_changes}
8352 -----------------------------------------
8354 NetCDF version 3 includes a complete rewrite of the netCDF library. It
8355 is about twice as fast as the previous version. The netCDF file format
8356 is unchanged, so files written with version 3 can be read with version 2
8357 code and vice versa.
8359 The core library is now written in ANSI C. You must have an ANSI C
8360 compiler to compile this version. The FORTRAN interface is layered on
8361 top of the C interface using a different technique than was used in
8364 Rewriting the library offered an opportunity to implement improved C and
8365 FORTRAN interfaces that provide some significant benefits:
8367 - type safety, by eliminating the need to use type punning in
8369 - automatic type conversions, by eliminating the undesirable coupling
8370 between the language-independent external netCDF types (NF\_BYTE,
8371 ..., NF\_DOUBLE) and language-dependent internal data types (INT\*1,
8372 ..., DOUBLE PRECISION);
8373 - pport for future enhancements, by eliminating obstacles to the
8374 clean addition ofpport for packed data and multithreading;
8375 - more standard error behavior, by uniformly communicating an error
8376 status back to the calling program in the return value of each
8379 It is not necessary to rewrite programs that use the version 2 FORTRAN
8380 interface, because the netCDF-3 library includes a backward
8381 compatibility interface thatpports all the old functions, globals,
8382 and behavior. We are hoping that the benefits of the new interface will
8383 be an incentive to use it in new netCDF applications. It is possible to
8384 convert old applications to the new interface incrementally, replacing
8385 netCDF-2 calls with the corresponding netCDF-3 calls one at a time.
8387 Other changes in the implementation of netCDF rlt in improved
8388 portability, maintainability, and performance on most platforms. A clean
8389 separation between I/O and type layers facilitates platform-specific
8390 optimizations. The new library no longer uses a vendor-provided XDR
8391 library, which simplifies linking programs that use netCDF and speeds up
8392 data access significantly in most cases.
8394 A.2 The New FORTRAN Interface {#f77_new_fortran_interface}
8395 -----------------------------
8397 First, here’s an example of FORTRAN code that uses the netCDF-2
8403 ! Use a buffer big enough for values of any type
8404 DOUBLE PRECISION DBUF(NDATA)
8407 EQUIVALENCE (RBUF, DBUF), ...
8408 INT XTYPE ! to hold the actual type of the data
8409 INT STATUS ! for error status
8410 ! Get the actual data type
8411 CALL NCVINQ(NCID, VARID, ...,XTYPE, ...)
8414 CALL NCVGT(NCID, VARID, START, COUNT, DBUF, STATUS)
8415 IF(STATUS .NE. NCNOERR) THEN
8416 PRINT *, 'Cannot get data, error code =', STATUS
8420 IF (XTYPE .EQ. NCDOUBLE) THEN
8422 ELSEIF (XTYPE .EQ. NCFLOAT) THEN
8428 Here’s how you might handle this with the new netCDF-3 FORTRAN
8434 ! I want to use doubles for my analysis
8435 DOUBLE PRECISION DBUF(NDATA)
8437 ! So I use a function that gets the data as doubles.
8438 STATUS = NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, DBUF)
8439 IF(STATUS .NE. NF_NOERR) THEN
8440 PRINT *, 'Cannot get data, ', NF_STRERROR(STATUS)
8447 The example above illustrates changes in function names, data type
8448 conversion, and error handling, discussed in detail in thes
8451 A.3 Function Naming Conventions {#f77_function_naming_conventions}
8452 -------------------------------
8454 The netCDF-3 Fortran 77 library employs a naming convention intended to
8455 make netCDF programs more readable. For example, the name of the
8456 function to rename a variable is now NF\_RENAME\_VAR instead of the
8459 All netCDF-3 FORTRAN function names begin with the NF\_ prefix. The
8460 second part of the name is a verb, like GET, PUT, INQ (for inquire), or
8461 OPEN. The third part of the name is typically the object of the verb:
8462 for example DIM, VAR, or ATT for functions dealing with dimensions,
8463 variables, or attributes. To distinguish the various I/O operations for
8464 variables, a single character modifier is appended to VAR:
8466 - VAR entire variable access
8467 - VAR1 single value access
8468 - VARA array or array access
8469 - VARS strided access to absample of values
8470 - VARM mapped access to values not contiguous in memory
8472 At the end of the name for variable and attribute functions, there is a
8473 component indicating the type of the final argument: TEXT, INT1, INT2,
8474 INT, REAL, or DOUBLE. This part of the function name indicates the type
8475 of the data container you are using in your program: character string,
8476 1-byte integer, and so on.
8478 Also, all PARAMETER names in the public FORTRAN interface begin with the
8479 prefix NF\_. For example, the PARAMETER which was formerly MAXNCNAM is
8480 now NF\_MAX\_NAME, and the former FILFLOAT is now NF\_FILL\_FLOAT.
8482 As previously mentioned, all the old names are stillpported for
8483 backward compatibility.
8485 A.4 Type Conversion {#f77_type_conversion}
8488 With the new interface, users need not be aware of the external type of
8489 numeric variables, since automatic conversion to or from any desired
8490 numeric type is now available. You can use this feature to simplify
8491 code, by making it independent of external types. The elimination of
8492 type punning prevents some kinds of type errors that could occur with
8493 the previous interface. Programs may be made more robust with the new
8494 interface, because they need not be changed to accommodate a change to
8495 the external type of a variable.
8497 If conversion to or from an external numeric type is necessary, it is
8498 handled by the library. This automatic conversion and separation of
8499 external data representation from internal data types will become even
8500 more important in netCDF version 4, when new external types will be
8501 added for packed data for which there is no natural corresponding
8502 internal type, for example, arrays of 11-bit values.
8504 Converting from one numeric type to another may rlt in an error if
8505 the target type is not capable of representing the converted value. (In
8506 netCDF-2,ch overflows can only happen in the XDR layer.) For example,
8507 a REAL may not be able to hold data stored externally as an NF\_DOUBLE
8508 (an IEEE floating-point number). When accessing an array of values, an
8509 NF\_ERANGE error is returned if one or more values are out of the range
8510 of representable values, but other values are converted properly.
8512 Note that mere loss of precision in type conversion does not return an
8513 error. Thus, if you read double precision values into an INTEGER, for
8514 example, no error rlts unless the magnitude of the double precision
8515 value exceeds the representable range of INTEGERs on your platform.
8516 Similarly, if you read a large integer into a REAL incapable of
8517 representing all the bits of the integer in its mantissa, this loss
8518 There are two new functions in netCDF-3 that don’t correspond to any
8519 netCDF-2 functions: NF\_INQ\_LIBVERS and NF\_STRERROR. The version ation
8520 The previous implementation returned an error when the same dimension
8521 was used more than once in specifying the shape of a variable in
8522 ncvardef. This restriction is relaxed in the netCDF-3 implementation,
8523 because an autocorrelation matrix is a good example where using the same
8524 dimension twice makes sense.
8526 In the new interface, units for the IMAP argument to the NF\_PUT\_VARM
8527 and NF\_GET\_VARM families of functions are now in terms of the number
8528 of data elements of the desired internal type, not in terms of bytes as
8529 in the netCDF version-2 mapped access interfaces.
8531 Following is a table of netCDF-2 function names and names of the
8532 corresponding netCDF-3 functions. For parameter lists of netCDF-2
8533 functions, see the netCDF-2 User’s Guide.
8545 : NF\_GET\_ATT\_DOUBLE, NF\_GET\_ATT\_REAL, NF\_GET\_ATT\_INT,
8546 NF\_GET\_ATT\_INT1, NF\_GET\_ATT\_INT2
8549 : NF\_GET\_ATT\_TEXT
8552 : NF\_INQ\_ATT, NF\_INQ\_ATTID, NF\_INQ\_ATTLEN, NF\_INQ\_ATTTYPE
8558 : NF\_PUT\_ATT\_DOUBLE, NF\_PUT\_ATT\_REAL, NF\_PUT\_ATT\_INT,
8559 NF\_PUT\_ATT\_INT1NF\_PUT
8561 B. Summary of FORTRAN 77 Interface {#f77_interface_summary}
8562 ==================================
8564 Input parameters are in upper case, output parameters are in lower case.
8565 The FORTRAN types of all the parameters are listed alphabetically by
8566 parameter name below the function declarations.
8572 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
8573 CHARACTER*80 FUNCTION NF_STRERROR (NCERR)
8574 INTEGER FUNCTION NF_CREATE (PATH, CMODE, ncid)
8575 INTEGER FUNCTION NF_OPEN (PATH, MODE, ncid)
8576 INTEGER FUNCTION NF_SET_FILL (NCID, FILLMODE, old_mode)
8577 INTEGER FUNCTION NF_REDEF (NCID)
8578 INTEGER FUNCTION NF_ENDDEF (NCID)
8579 INTEGER FUNCTION NF_SYNC (NCID)
8580 INTEGER FUNCTION NF_ABORT (NCID)
8581 INTEGER FUNCTION NF_CLOSE (NCID)
8582 INTEGER FUNCTION NF_INQ (NCID, ndims, nvars, ngatts,
8584 INTEGER FUNCTION NF_INQ_NDIMS (NCID, ndims)
8585 INTEGER FUNCTION NF_INQ_NVARS (NCID, nvars)
8586 INTEGER FUNCTION NF_INQ_NATTS (NCID, ngatts)
8587 INTEGER FUNCTION NF_INQ_UNLIMDIM (NCID, unlimdimid)
8588 INTEGER FUNCTION NF_DEF_DIM (NCID, NAME, LEN, dimid)
8589 INTEGER FUNCTION NF_INQ_DIMID (NCID, NAME, dimid)
8590 INTEGER FUNCTION NF_INQ_DIM (NCID, DIMID, name, len)
8591 INTEGER FUNCTION NF_INQ_DIMNAME (NCID, DIMID, name)
8592 INTEGER FUNCTION NF_INQ_DIMLEN (NCID, DIMID, len)
8593 INTEGER FUNCTION NF_RENAME_DIM (NCID, DIMID, NAME)
8595 INTEGER FUNCTION NF_DEF_VAR (NCID, NAME, XTYPE, NDIMS, DIMIDS,
8597 INTEGER FUNCTION NF_INQ_VAR (NCID, VARID, name, xtype, ndims,
8599 INTEGER FUNCTION NF_INQ_VARID (NCID, NAME, varid)
8600 INTEGER FUNCTION NF_INQ_VARNAME (NCID, VARID, name)
8601 INTEGER FUNCTION NF_INQ_VARTYPE (NCID, VARID, xtype)
8602 INTEGER FUNCTION NF_INQ_VARNDIMS (NCID, VARID, ndims)
8603 INTEGER FUNCTION NF_INQ_VARDIMID (NCID, VARID, DIMIDS)
8604 INTEGER FUNCTION NF_INQ_VARNATTS (NCID, VARID, natts)
8605 INTEGER FUNCTION NF_RENAME_VAR (NCID, VARID, NAME)
8606 INTEGER FUNCTION NF_PUT_VAR_TEXT (NCID, VARID, TEXT)
8607 INTEGER FUNCTION NF_GET_VAR_TEXT (NCID, VARID, text)
8608 INTEGER FUNCTION NF_PUT_VAR_INT1 (NCID, VARID, I1VAL)
8609 INTEGER FUNCTION NF_GET_VAR_INT1 (NCID, VARID, i1val)
8610 INTEGER FUNCTION NF_PUT_VAR_INT2 (NCID, VARID, I2VAL)
8611 INTEGER FUNCTION NF_GET_VAR_INT2 (NCID, VARID, i2val)
8612 INTEGER FUNCTION NF_PUT_VAR_INT (NCID, VARID, IVAL)
8613 INTEGER FUNCTION NF_GET_VAR_INT (NCID, VARID, ival)
8614 INTEGER FUNCTION NF_PUT_VAR_REAL (NCID, VARID, RVAL)
8615 INTEGER FUNCTION NF_GET_VAR_REAL (NCID, VARID, rval)
8616 INTEGER FUNCTION NF_PUT_VAR_DOUBLE (NCID, VARID, DVAL)
8617 INTEGER FUNCTION NF_GET_VAR_DOUBLE (NCID, VARID, dval)
8618 INTEGER FUNCTION NF_PUT_VAR1_TEXT (NCID, VARID, INDEX, TEXT)
8619 INTEGER FUNCTION NF_GET_VAR1_TEXT (NCID, VARID, INDEX, text)
8620 INTEGER FUNCTION NF_PUT_VAR1_INT1 (NCID, VARID, INDEX, I1VAL)
8621 INTEGER FUNCTION NF_GET_VAR1_INT1 (NCID, VARID, INDEX, i1val)
8622 INTEGER FUNCTION NF_PUT_VAR1_INT2 (NCID, VARID, INDEX, I2VAL)
8623 INTEGER FUNCTION NF_GET_VAR1_INT2 (NCID, VARID, INDEX, i2val)
8624 INTEGER FUNCTION NF_PUT_VAR1_INT (NCID, VARID, INDEX, IVAL)
8625 INTEGER FUNCTION NF_GET_VAR1_INT (NCID, VARID, INDEX, ival)
8626 INTEGER FUNCTION NF_PUT_VAR1_REAL (NCID, VARID, INDEX, RVAL)
8627 INTEGER FUNCTION NF_GET_VAR1_REAL (NCID, VARID, INDEX, rval)
8628 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(NCID, VARID, INDEX, DVAL)
8629 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(NCID, VARID, INDEX, dval)
8630 INTEGER FUNCTION NF_PUT_VARA_TEXT (NCID, VARID, START, COUNT, TEXT)
8631 INTEGER FUNCTION NF_GET_VARA_TEXT (NCID, VARID, START, COUNT, text)
8632 INTEGER FUNCTION NF_PUT_VARA_INT1 (NCID, VARID, START, COUNT, I1VALS)
8633 INTEGER FUNCTION NF_GET_VARA_INT1 (NCID, VARID, START, COUNT, i1vals)
8634 INTEGER FUNCTION NF_PUT_VARA_INT2 (NCID, VARID, START, COUNT, I2VALS)
8635 INTEGER FUNCTION NF_GET_VARA_INT2 (NCID, VARID, START, COUNT, i2vals)
8636 INTEGER FUNCTION NF_PUT_VARA_INT (NCID, VARID, START, COUNT, IVALS)
8637 INTEGER FUNCTION NF_GET_VARA_INT (NCID, VARID, START, COUNT, ivals)
8638 INTEGER FUNCTION NF_PUT_VARA_REAL (NCID, VARID, START, COUNT, RVALS)
8639 INTEGER FUNCTION NF_GET_VARA_REAL (NCID, VARID, START, COUNT, rvals)
8640 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(NCID, VARID, START, COUNT, DVALS)
8641 INTEGER FUNCTION NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, dvals)
8642 INTEGER FUNCTION NF_PUT_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8644 INTEGER FUNCTION NF_GET_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8646 INTEGER FUNCTION NF_PUT_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8648 INTEGER FUNCTION NF_GET_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8650 INTEGER FUNCTION NF_PUT_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8652 INTEGER FUNCTION NF_GET_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8654 INTEGER FUNCTION NF_PUT_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8656 INTEGER FUNCTION NF_GET_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8658 INTEGER FUNCTION NF_PUT_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8660 INTEGER FUNCTION NF_GET_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8662 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8664 INTEGER FUNCTION NF_GET_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8666 INTEGER FUNCTION NF_PUT_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8668 INTEGER FUNCTION NF_GET_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8670 INTEGER FUNCTION NF_PUT_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8672 INTEGER FUNCTION NF_GET_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8674 INTEGER FUNCTION NF_PUT_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8676 INTEGER FUNCTION NF_GET_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8678 INTEGER FUNCTION NF_PUT_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8680 INTEGER FUNCTION NF_GET_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8682 INTEGER FUNCTION NF_PUT_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8684 INTEGER FUNCTION NF_GET_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8686 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8688 INTEGER FUNCTION NF_GET_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8691 INTEGER FUNCTION NF_INQ_ATT (NCID, VARID, NAME, xtype, len)
8692 INTEGER FUNCTION NF_INQ_ATTID (NCID, VARID, NAME, attnum)
8693 INTEGER FUNCTION NF_INQ_ATTTYPE (NCID, VARID, NAME, xtype)
8694 INTEGER FUNCTION NF_INQ_ATTLEN (NCID, VARID, NAME, len)
8695 INTEGER FUNCTION NF_INQ_ATTNAME (NCID, VARID, ATTNUM, name)
8696 INTEGER FUNCTION NF_COPY_ATT (NCID_IN, VARID_IN, NAME,
8697 NCID_OUT, VARID_OUT)
8698 INTEGER FUNCTION NF_RENAME_ATT (NCID, VARID, CURNAME, NEWNAME)
8699 INTEGER FUNCTION NF_DEL_ATT (NCID, VARID, NAME)
8700 INTEGER FUNCTION NF_PUT_ATT_TEXT (NCID, VARID, NAME, LEN, TEXT)
8701 INTEGER FUNCTION NF_GET_ATT_TEXT (NCID, VARID, NAME, text)
8702 INTEGER FUNCTION NF_PUT_ATT_INT1 (NCID, VARID, NAME, XTYPE, LEN,
8704 INTEGER FUNCTION NF_GET_ATT_INT1 (NCID, VARID, NAME, i1vals)
8705 INTEGER FUNCTION NF_PUT_ATT_INT2 (NCID, VARID, NAME, XTYPE, LEN,
8707 INTEGER FUNCTION NF_GET_ATT_INT2 (NCID, VARID, NAME, i2vals)
8708 INTEGER FUNCTION NF_PUT_ATT_INT (NCID, VARID, NAME, XTYPE, LEN,
8710 INTEGER FUNCTION NF_GET_ATT_INT (NCID, VARID, NAME, ivals)
8711 INTEGER FUNCTION NF_PUT_ATT_REAL (NCID, VARID, NAME, XTYPE, LEN,
8713 INTEGER FUNCTION NF_GET_ATT_REAL (NCID, VARID, NAME, rvals)
8714 INTEGER FUNCTION NF_PUT_ATT_DOUBLE (NCID, VARID, NAME, XTYPE, LEN,
8716 INTEGER FUNCTION NF_GET_ATT_DOUBLE (NCID, VARID, NAME, dvals)
8718 INTEGER ATTNUM ! attribute number
8719 INTEGER attnum ! returned attribute number
8720 INTEGER CMODE ! NF_NOCLOBBER, NF_SHARE flags expression
8721 INTEGER COUNT ! array of edge lengths of block of values
8722 CHARACTER(*) CURNAME ! current name (before renaming)
8723 INTEGER DIMID ! dimension ID
8724 INTEGER dimid ! returned dimension ID
8725 INTEGER DIMIDS ! list of dimension IDs
8726 INTEGER dimids ! list of returned dimension IDs
8727 DOUBLEPRECISION DVAL ! single data value
8728 DOUBLEPRECISION dval ! returned single data value
8729 DOUBLEPRECISION DVALS ! array of data values
8730 DOUBLEPRECISION dvals ! array of returned data values
8731 INTEGER FILLMODE ! NF_NOFILL or NF_FILL, for setting fill mode
8732 INTEGER*1 I1VAL ! single data value
8733 INTEGER*1 I1val ! returned single data value
8734 INTEGER*1 I1VALS ! array of data values
8735 INTEGER*1 i1vals ! array of returned data values
8736 INTEGER*2 I2VAL ! single data value
8737 INTEGER*2 i2val ! returned single data value
8738 INTEGER*2 I2VALS ! array of data values
8739 INTEGER*2 i2vals ! array of returned data values
8740 INTEGER IMAP ! index mapping vector
8741 INTEGER INDEX ! variable array index vector
8742 INTEGER IVAL ! single data value
8743 INTEGER ival ! returned single data value
8744 INTEGER IVALS ! array of data values
8745 INTEGER ivals ! array of returned data values
8746 INTEGER LEN ! dimension or attribute length
8747 INTEGER len ! returned dimension or attribute length
8748 INTEGER MODE ! open mode, one of NF_WRITE or NF_NOWRITE
8749 CHARACTER(*) NAME ! dimension, variable, or attribute name
8750 CHARACTER(*) name ! returned dim, var, or att name
8751 INTEGER natts ! returned number of attributes
8752 INTEGER NCERR ! error returned from NF_xxx function call
8753 INTEGER NCID ! netCDF ID of an open netCDF dataset
8754 INTEGER ncid ! returned netCDF ID
8755 INTEGER NCID_IN ! netCDF ID of open source netCDF dataset
8756 INTEGER NCID_OUT ! netCDF ID of open destination netCDF dataset
8757 INTEGER NDIMS ! number of dimensions
8758 INTEGER ndims ! returned number of dimensions
8759 CHARACTER(*) NEWNAME ! new name for dim, var, or att
8760 INTEGER ngatts ! returned number of global attributes
8761 INTEGER nvars ! returned number of variables
8762 INTEGER old_mode ! previous fill mode, NF_NOFILL or NF_FILL,
8763 CHARACTER(*) PATH ! name of netCDF dataset
8764 REAL RVAL ! single data value
8765 REAL rval ! returned single data value
8766 REAL RVALS ! array of data values
8767 REAL rvals ! array of returned data values
8768 INTEGER START ! variable array indices of first value
8769 INTEGER STRIDE ! variable array dimensional strides
8770 CHARACTER(*) TEXT ! input text value
8771 CHARACTER(*) text ! returned text value
8772 INTEGER unlimdimid ! returned ID of unlimited dimension
8773 INTEGER VARID ! variable ID
8774 INTEGER varid ! returned variable ID
8775 INTEGER VARID_IN ! variable ID
8776 INTEGER VARID_OUT ! variable ID
8777 INTEGER XTYPE ! external type: NF_BYTE, NF_CHAR, ... ,
8778 INTEGER xtype ! returned external type