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