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 {#Use_of_the_NetCDF_Library}
9 =============================
11 You can use the netCDF library without knowing about all of the netCDF
12 interface. If you are creating a netCDF dataset, only a handful of
13 routines are required to define the necessary dimensions, variables, and
14 attributes, and to write the data to the netCDF dataset. (Even less are
15 needed if you use the ncgen utility to create the dataset before running
16 a program using netCDF library calls to write data. See
17 section ‘ncgen’ in The NetCDF Users
18 Guide.) Similarly, if you are writing software to access data stored in
19 a particular netCDF object, only a smallbset of the netCDF library is
20 required to open the netCDF dataset and access the data. Authors of
21 generic applications that access arbitrary netCDF datasets need to be
22 familiar with more of the netCDF library.
24 In this we provide templates of common sequences of netCDF calls
25 needed for common uses. For clarity we present only the names of
26 routines; omit declarations and error checking; omit the type-specific
27 suffixes of routine names for variables and attributes; indent
28 statements that are typically invoked multiple times; and use ... to
29 represent arbitrary sequences of other statements. Full parameter lists
30 are described in laters.
34 1.1 Creating a NetCDF Dataset {#Creating_a_NetCDF_Dataset}
35 -----------------------------
37 Here is a typical sequence of netCDF calls used to create a new netCDF
43 NF_CREATE ! create netCDF dataset: enter define mode
45 NF_DEF_DIM ! define dimensions: from name and length
47 NF_DEF_VAR ! define variables: from name, type, dims
49 NF_PUT_ATT ! assign attribute values
51 NF_ENDDEF ! end definitions: leave define mode
53 NF_PUT_VAR ! provide values for variable
55 NF_CLOSE ! close: save new netCDF dataset
58 Only one call is needed to create a netCDF dataset, at which point you
59 will be in the first of two netCDF modes. When accessing an open netCDF
60 dataset, it is either in define mode or data mode. In define mode, you
61 can create dimensions, variables, and new attributes, but you cannot
62 read or write variable data. In data mode, you can access data and
63 change existing attributes, but you are not permitted to create new
64 dimensions, variables, or attributes.
66 One call to NF\_DEF\_DIM is needed for each dimension created.
67 Similarly, one call to NF\_DEF\_VAR is needed for each variable
68 creation, and one call to a member of the NF\_PUT\_ATT family is needed
69 for each attribute defined and assigned a value. To leave define mode
70 and enter data mode, call NF\_ENDDEF.
72 Once in data mode, you can add new data to variables, change old values,
73 and change values of existing attributes (so long as the attribute
74 changes do not require more storage space). Single values may be written
75 to a netCDF variable with one of the members of the NF\_PUT\_VAR1
76 family, depending on what type of data you have to write. All the values
77 of a variable may be written at once with one of the members of the
78 NF\_PUT\_VAR family. Arrays or array crosss of a variable may be
79 written using members of the NF\_PUT\_VARA family. Subsampled array
80 sections may be written using members of the NF\_PUT\_VARS family.
81 Mapped arrays may be written using members of the NF\_PUT\_VARM
82 family. (Subsampled and mapped access are general forms of data access
83 that are explained later.)
85 Finally, you should explicitly close all netCDF datasets that have been
86 opened for writing by calling NF\_CLOSE. By default, access to the file
87 system is buffered by the netCDF library. If a program terminates
88 abnormally with netCDF datasets open for writing, your most recent
89 modifications may be lost. This default buffering of data is disabled by
90 setting the NF\_SHARE flag when opening the dataset. But even if this
91 flag is set, changes to attribute values or changes made in define mode
92 are not written out until NF\_SYNC or NF\_CLOSE is called.
94 1.2 Reading a NetCDF Dataset with Known Names {#Reading_a_NetCDF_Dataset_with_Known_Names}
95 ---------------------------------------------
97 Here we consider the case where you know the names of not only the
98 netCDF datasets, but also the names of their dimensions, variables, and
99 attributes. (Otherwise you would have to do "inquire" calls.) The order
100 of typical C calls to read data from those variables in a netCDF dataset
106 NF_OPEN ! open existing netCDF dataset
108 NF_INQ_DIMID ! get dimension IDs
110 NF_INQ_VARID ! get variable IDs
112 NF_GET_ATT ! get attribute values
114 NF_GET_VAR ! get values of variables
116 NF_CLOSE ! close netCDF dataset
119 First, a single call opens the netCDF dataset, given the dataset name,
120 and returns a netCDF ID that is used to refer to the open netCDF dataset
121 in allbsequent calls.
123 Next, a call to NF\_INQ\_DIMID for each dimension of interest gets the
124 dimension ID from the dimension name. Similarly, each required variable
125 ID is determined from its name by a call to NF\_INQ\_VARID.Once variable
126 IDs are known, variable attribute values can be retrieved using the
127 netCDF ID, the variable ID, and the desired attribute name as input to a
128 member of the NF\_GET\_ATT family (typically NF\_GET\_ATT\_TEXT or
129 NF\_GET\_ATT\_DOUBLE) for each desired attribute. Variable data values
130 can be directly accessed from the netCDF dataset with calls to members
131 of the NF\_GET\_VAR1 family for single values, the NF\_GET\_VAR family
132 for entire variables, or various other members of the NF\_GET\_VARA,
133 NF\_GET\_VARS, or NF\_GET\_VARM families for array,bsampled or mapped
136 Finally, the netCDF dataset is closed with NF\_CLOSE. There is no need
137 to close a dataset open only for reading.
140 1.3 Reading a netCDF Dataset with Unknown Names {#Reading_a_netCDF_Dataset_with_Unknown_Names}
141 -----------------------------------------------
143 It is possible to write programs (e.g., generic software) which doch
144 things as processing every variable, without needing to know in advance
145 the names of these variables. Similarly, the names of dimensions and
146 attributes may be unknown.
148 Names and other information about netCDF objects may be obtained from
149 netCDF datasets by calling inquire functions. These return information
150 about a whole netCDF dataset, a dimension, a variable, or an attribute.
151 The following template illustrates how they are used:
156 NF_OPEN ! open existing netCDF dataset
158 NF_INQ ! find out what is in it
160 NF_INQ_DIM ! get dimension names, lengths
162 NF_INQ_VAR ! get variable names, types, shapes
164 NF_INQ_ATTNAME ! get attribute names
166 NF_INQ_ATT ! get attribute values
168 NF_GET_ATT ! get attribute values
170 NF_GET_VAR ! get values of variables
172 NF_CLOSE ! close netCDF dataset
175 As in the previous example, a single call opens the existing netCDF
176 dataset, returning a netCDF ID. This netCDF ID is given to the NF\_INQ
177 routine, which returns the number of dimensions, the number of
178 variables, the number of global attributes, and the ID of the unlimited
179 dimension, if there is one.
181 All the inquire functions are inexpensive to use and require no I/O,
182 since the information they provide is stored in memory when a netCDF
183 dataset is first opened.
185 Dimension IDs use consecutive integers, beginning at 1. Also dimensions,
186 once created, cannot be deleted. Therefore, knowing the number of
187 dimension IDs in a netCDF dataset means knowing all the dimension IDs:
188 they are the integers 1, 2, 3, ... up to the number of dimensions. For
189 each dimension ID, a call to the inquire function NF\_INQ\_DIM returns
190 the dimension name and length.
192 Variable IDs are also assigned from consecutive integers 1, 2, 3, ... up
193 to the number of variables. These can be used in NF\_INQ\_VAR calls to
194 find out the names, types, shapes, and the number of attributes assigned
197 Once the number of attributes for a variable is known,ccessive calls
198 to NF\_INQ\_ATTNAME return the name for each attribute given the netCDF
199 ID, variable ID, and attribute number. Armed with the attribute name, a
200 call to NF\_INQ\_ATT returns its type and length. Given the type and
201 length, you can allocate enough space to hold the attribute values. Then
202 a call to a member of the NF\_GET\_ATT family returns the attribute
205 Once the IDs and shapes of netCDF variables are known, data values can
206 be accessed by calling a member of the NF\_GET\_VAR1 family for single
207 values, or members of the NF\_GET\_VAR, NF\_GET\_VARA, NF\_GET\_VARS, or
208 NF\_GET\_VARM for various kinds of array access.
210 1.4 Adding New Dimensions, Variables, Attributes {#Adding_New_Dimensions__Variables__Attributes}
211 ------------------------------------------------
213 An existing netCDF dataset can be extensively altered. New dimensions,
214 variables, and attributes can be added or existing ones renamed, and
215 existing attributes can be deleted. Existing dimensions, variables, and
216 attributes can be renamed. The following code template lists a typical
217 sequence of calls to add new netCDF components to an existing dataset:
222 NF_OPEN ! open existing netCDF dataset
224 NF_REDEF ! put it into define mode
226 NF_DEF_DIM ! define additional dimensions (if any)
228 NF_DEF_VAR ! define additional variables (if any)
230 NF_PUT_ATT ! define other attributes (if any)
232 NF_ENDDEF ! check definitions, leave define mode
234 NF_PUT_VAR ! provide new variable values
236 NF_CLOSE ! close netCDF dataset
239 A netCDF dataset is first opened by the NF\_OPEN call. This call puts
240 the open dataset in data mode, which means existing data values can be
241 accessed and changed, existing attributes can be changed (so long as
242 they do not grow), but nothing can be added. To add new netCDF
243 dimensions, variables, or attributes you must enter define mode, by
244 calling NF\_REDEF.In define mode, call NF\_DEF\_DIM to define new
245 dimensions, NF\_DEF\_VAR to define new variables, and a member of the
246 NF\_PUT\_ATT family to assign new attributes to variables or enlarge old
249 You can leave define mode and reenter data mode, checking all the new
250 definitions for consistency and committing the changes to disk, by
251 calling NF\_ENDDEF. If you do not wish to reenter data mode, just call
252 NF\_CLOSE, which will have the effect of first calling NF\_ENDDEF.
254 Until the NF\_ENDDEF call, you may back out of all the redefinitions
255 made in define mode and restore the previous state of the netCDF dataset
256 by calling NF\_ABORT. You may also use the NF\_ABORT call to restore the
257 netCDF dataset to a consistent state if the call to NF\_ENDDEF fails. If
258 you have called NF\_CLOSE from definition mode and the implied call to
259 NF\_ENDDEF fails, NF\_ABORT will automatically be called to close the
260 netCDF dataset and leave it in its previous consistent state (before you
261 entered define mode).
263 At most one process should have a netCDF dataset open for writing at one
264 time. The library is designed to provide limitedpport for multiple
265 concurrent readers with one writer, via disciplined use of the NF\_SYNC
266 function and the NF\_SHARE flag. If a writer makes changes in define
267 mode,ch as the addition of new variables, dimensions, or attributes,
268 some means external to the library is necessary to prevent readers from
269 making concurrent accesses and to inform readers to call NF\_SYNC before
272 1.5 Error Handling {#Error_Handling_1_5}
275 The netCDF library provides the facilities needed to handle errors in a
276 flexible way. Each netCDF function returns an integer status value. If
277 the returned status value indicates an error, you may handle it in any
278 way desired, from printing an associated error message and exiting to
279 ignoring the error indication and proceeding (not recommended!). For
280 simplicity, the examples in this guide check the error status and call a
281 separate function to handle any errors.
283 The NF\_STRERROR function is available to convert a returned integer
284 error status into an error message string.
286 Occasionally, low-level I/O errors may occur in a layer below the netCDF
287 library. For example, if a write operation causes you to exceed disk
288 quotas or to attempt to write to a device that is no longer available,
289 you may get an error from a layer below the netCDF library, but the
290 rlting write error will still be reflected in the returned status
293 1.6 Compiling and Linking with the NetCDF Library {#Compiling_and_Linking_with_the_NetCDF_Library}
294 -------------------------------------------------
296 Details of how to compile and link a program that uses the netCDF C or
297 FORTRAN interfaces differ, depending on the operating system, the
298 available compilers, and where the netCDF library and include files are
299 installed. Nevertheless, we provide here examples of how to compile and
300 link a program that uses the netCDF library on a Unix platform, so that
301 you can adjust these examples to fit your installation.
303 Every FORTRAN file that references netCDF functions or constants must
304 contain an appropriate INCLUDE statement before the first
310 Unless the netcdf.inc file is installed in a standard directory where
311 the FORTRAN compiler always looks, you must use the -I option when
312 invoking the compiler, to specify a directory where netcdf.inc is
313 installed, for example:
315 f77 -c -I/usr/local/include myprogram.f
318 Unless the netCDF library is installed in a standard directory where the
319 linker always looks, you must use the -L and -l options to link an
320 object file that uses the netCDF library. Since version 4.1.3, the
321 netCDF Fortran library (named ‘libnetcdff’) is distinct from the netCDF
322 C library (named ‘libnetcdf’), but depends on it. If it is installed as
323 a shared library, you need only use ‘-lnetcdff’ to specify the Fortran
326 For example, if installed as a shared library, use something like:
329 f77 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff
332 If installed as a static library, you will at least need to mention the
333 netCDF C library and perhaps other libraries,ch as hdf5 or curl,
334 depending on how the C library was built. For example:
339 f77 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff -lnetcdf
342 Use of the nf-config utility program, installed as part of the
343 netcdf-fortran software, provides an easier way to compile and link,
344 without needing to know the details of where the library has been
345 installed, or whether it is installed as a shared or static library.
347 To see all the options for ‘nf-config’, invoke it with the ‘–help’
350 Here’s an example of how you could use ‘nf-config’ to compile and link a
351 Fortran program in one step:
356 f77 myprogram.f -o myprogram `nf-config --fflags --flibs`
359 If it is installed on your system, you could also use the ‘pkg-config’
360 utility to compile and link Fortran programs with the netCDF libraries.
361 This is especially useful in Makefiles, to ilate them from changes to
362 library versions and dependencies. Here is an example of how you could
363 compile and link a Fortran program with netCDF libraries using
369 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
370 f77 myprogram.f -o myprogram `pkg-config --cflags --libs netcdf-fortran`
373 where here ‘–cflags’ means compiler flags and ‘libs’ requests that the
374 approriate libraries be linked in.
378 2. Datasets {#Datasets_}
381 2.1 Datasets Introduction {#Datasets_Introduction}
382 -------------------------
384 This presents the interfaces of the netCDF functions that deal
385 with a netCDF dataset or the whole netCDF library.
387 A netCDF dataset that has not yet been opened can only be referred to by
388 its dataset name. Once a netCDF dataset is opened, it is referred to by
389 a netCDF ID, which is a small nonnegative integer returned when you
390 create or open the dataset. A netCDF ID is much like a file descriptor
391 in C or a logical unit number in FORTRAN. In any single program, the
392 netCDF IDs of distinct open netCDF datasets are distinct. A single
393 netCDF dataset may be opened multiple times and will then have multiple
394 distinct netCDF IDs; however at most one of the open instances of a
395 single netCDF dataset should permit writing. When an open netCDF dataset
396 is closed, the ID is no longer associated with a netCDF dataset.
398 Functions that deal with the netCDF library include:
400 - Get version of library.
401 - Get error message corresponding to a returned error code.
403 The operationspported on a netCDF dataset as a single object are:
405 - Create, given dataset name and whether to overwrite or not.
406 - Open for access, given dataset name and read or write intent.
407 - Put into define mode, to add dimensions, variables, or attributes.
408 - Take out of define mode, checking consistency of additions.
409 - Close, writing to disk if required.
410 - Inquire about the number of dimensions, number of variables, number
411 of global attributes, and ID of the unlimited dimension, if any.
412 - Synchronize to disk to makere it is current.
413 - Set and unset nofill mode for optimized sequential writes.
414 - After ammary of conventions used in describing the netCDF
415 interfaces, the rest of this presents a detailed description
416 of the interfaces for these operations.
418 2.2 NetCDF Library Interface Descriptions {#NetCDF_Library_Interface_Descriptions}
419 -----------------------------------------
421 Each interface description for a particular netCDF function in this and
424 - a description of the purpose of the function;
425 - a FORTRAN function prototype that presents the type and order of the
426 formal parameters to the function;
427 - a description of each formal parameter in the C interface;
428 - a list of possible error conditions; and
429 - an example of a FORTRAN program fragment calling the netCDF function
430 (and perhaps other netCDF functions).
432 The examples follow a simple convention for error handling, always
433 checking the error status returned from each netCDF function call and
434 calling a handle\_error function in case an error was detected. For an
435 example ofch a function, see Section 5.2 "Get error message
436 corresponding to error status: nf\_strerror".
438 2.3 NF_STRERROR {#NF_STRERROR}
441 The function NF\_STRERROR returns a static reference to an error message
442 string corresponding to an integer netCDF error status or to a system
443 error number, prmably returned by a previous call to some other
444 netCDF function. The list of netCDF error status codes is available in
445 the appropriate include file for each language binding.
450 CHARACTER*80 FUNCTION NF_STRERROR(INTEGER NCERR)
454 : An error status that might have been returned from a previous call
455 to some netCDF function.
460 If you provide an invalid integer error status that does not correspond
461 to any netCDF error message or or to any system error message (as
462 understood by the system strerror function), NF\_STRERROR returns a
463 string indicating that there is noch error status.
467 Here is an example of a simple error handling function that uses
468 NF\_STRERROR to print the error message corresponding to the netCDF
469 error status returned from any netCDF function call and then exit:
476 SUBROUTINE HANDLE_ERR(STATUS)
478 IF (STATUS .NE. NF_NOERR) THEN
479 PRINT *, NF_STRERROR(STATUS)
486 2.4 Get netCDF library version: NF_INQ_LIBVERS {#Get_netCDF_library_version_NF_INQ_LIBVERS}
487 ------------------------------------------------
489 The function NF\_INQ\_LIBVERS returns a string identifying the version
490 of the netCDF library, and when it was built.
495 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
500 This function takes no arguments, and thus no errors are possible in its
505 Here is an example using nf\_inq\_libvers to print the version of the
506 netCDF library with which the program is linked:
512 PRINT *, NF_INQ_LIBVERS()
515 2.5 NF_CREATE {#NF_CREATE}
518 This function creates a new netCDF dataset, returning a netCDF ID that
519 can sequently be used to refer to the netCDF dataset in other netCDF
520 function calls. The new netCDF dataset opened for write access and
521 placed in define mode, ready for you to add dimensions, variables, and
524 A creation mode flag specifies whether to overwrite any existing dataset
525 with the same name and whether access to the dataset is shared.
530 INTEGER FUNCTION NF_CREATE (CHARACTER*(*) PATH, INTEGER CMODE,
534 `PATH`: The file name of the new netCDF dataset.
536 `CMODE`: The creation mode flag. The following flags are available:
537 NF\_NOCLOBBER, NF\_SHARE, NF\_64BIT\_OFFSET, NF\_NETCDF4 and
538 NF\_CLASSIC\_MODEL. You can combine the affect of multiple flags in
539 a single argument by using the bitwise OR operator. For example, to
540 specify both NF\_NOCLOBBER and NF\_SHARE, you could provide the
541 argument OR(NF\_NOCLOBBER, NF\_SHARE).
544 A zero value (defined for convenience as NF_CLOBBER) specifies the
545 default behavior: overwrite any existing dataset with the same file
546 name and buffer and cache accesses for efficiency. The dataset will
547 be in netCDF classic format. See 'NetCDF Classic Format Limitations'
548 in The NetCDF Users Guide.
550 Setting NF\_NOCLOBBER means you do not want to clobber (overwrite)
551 an existing dataset; an error (NF_EEXIST) is returned if the
552 specified dataset already exists.
554 The NF\_SHARE flag is appropriate when one process may be writing
555 the dataset and one or more other processes reading the dataset
556 concurrently; it means that dataset accesses are not buffered and
557 caching is limited. Since the buffering scheme is optimized for
558 sequential access, programs that do not access data sequentially may
559 see some performance improvement by setting the NF\_SHARE flag. This
560 only applied to classic and 64-bit offset format files.
562 Setting NF\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
563 format file, instead of a netCDF classic format file. The 64-bit
564 offset format imposes far fewer restrictions on very large (i.e.
565 over 2 GB) data files. See [(netcdf)Large File
566 Support](netcdf.html#Large-File-Support) ‘Large File
567 Support’ in The NetCDF Users Guide.
569 Setting NF\_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format
570 file. Oring NF\_CLASSIC\_MODEL with NF\_NETCDF4 causes the netCDF
571 library to create a netCDF-4/HDF5 data file, with the netCDF classic
572 model enforced - none of the new features of the netCDF-4 data model
573 may be usedinch a file, for example groups and user-defined
577 : Returned netCDF ID.
581 NF\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
582 causes of errors include:
584 - Passing a dataset name that includes a directory that does not
586 - Specifying a dataset name of a file that exists and also specifying
588 - Specifying a meaningless value for the creation mode.
589 - Attempting to create a netCDF dataset in a directory where you don’t
590 have permission to create files.
594 In this example we create a netCDF dataset named foo.nc; we want the
595 dataset to be created in the current directory only if a dataset with
596 that name does not already exist:
605 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
606 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
609 2.6 NF__CREATE {#NF__CREATE}
612 This function is a variant of NF\_CREATE, NF\_\_CREATE (note the double
613 underscore) allows users to specify two tuning parameters for the file
614 that it is creating. These tuning parameters are not written to the data
615 file, they are only used for so long as the file remains open after an
618 This function creates a new netCDF dataset, returning a netCDF ID that
619 canbsequently be used to refer to the netCDF dataset in other netCDF
620 function calls. The new netCDF dataset opened for write access and
621 placed in define mode, ready for you to add dimensions, variables, and
624 A creation mode flag specifies whether to overwrite any existing dataset
625 with the same name and whether access to the dataset is shared.
630 INTEGER FUNCTION NF__CREATE (CHARACTER*(*) PATH, INTEGER CMODE, INTEGER INITIALSZ,
631 INTEGER BUFRSIZEHINT, INTEGER ncid)
635 : The file name of the new netCDF dataset.
638 : The creation mode flag. The following flags are available:
639 NF\_NOCLOBBER, NF\_SHARE, NF\_64BIT\_OFFSET, NF\_NETCDF4, and
642 Setting NF\_NOCLOBBER means you do not want to clobber (overwrite)
643 an existing dataset; an error (NF\_EEXIST) is returned if the
644 specified dataset already exists.
646 The NF\_SHARE flag is appropriate when one process may be writing
647 the dataset and one or more other processes reading the dataset
648 concurrently; it means that dataset accesses are not buffered and
649 caching is limited. Since the buffering scheme is optimized for
650 sequential access, programs that do not access data sequentially may
651 see some performance improvement by setting the NF\_SHARE flag. This
652 flag has no effect with netCDF-4/HDF5 files.
654 Setting NF\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
655 format file, instead of a netCDF classic format file. The 64-bit
656 offset format imposes far fewer restrictions on very large (i.e.
657 over 2 GB) data files. See [(netcdf)Large File
658 Support](netcdf.html#Large-File-Support) ‘Large File
659 Support’ in The NetCDF Users Guide.
661 Setting NF\_CLASSIC\_MODEL causes netCDF to enforce the classic data
662 model in this file. (This only has effect for netCDF-4/HDF5 files,
663 as classic and 64-bit offset files always use the classic model.)
664 When used with NF\_NETCDF4, this flag eres that the rlting
665 netCDF-4/HDF5 file may never contain any new constructs from the
666 enhanced data model. That is, it cannot contain groups, user defined
667 types, multiple unlimited dimensions, or new atomic types. The
668 advantage of this restriction is thatch files are guarenteed to
669 work with existing netCDF software.
671 A zero value (defined for convenience as NF\_CLOBBER) specifies the
672 default behavior: overwrite any existing dataset with the same file
673 name and buffer and cache accesses for efficiency. The dataset will
674 be in netCDF classic format. See [(netcdf)NetCDF Classic Format
675 Limitations](netcdf.html#NetCDF-Classic-Format-Limitations)
676 ‘NetCDF Classic Format Limitations’ in The NetCDF Users Guide.
679 : This parameter sets the initial size of the file at creation time.
682 : The argument referenced by BUFRSIZEHINT controls a space ves time
683 tradeoff, memory allocated in the netcdf library ves number of
686 Because of internal requirements, the value may not be set to
687 exactly the value requested. The actual value chosen is returned by
690 Using the value NF\_SIZEHINT\_DEFAULT causes the library to choose a
691 default. How the system chooses the default depends on the system.
692 On many systems, the "preferred I/O block size" is available from
693 the stat() system call, struct stat member st\_blksize. If this is
694 available it is used. Lacking that, twice the system pagesize is
697 Lacking a call to discover the system pagesize, we just set default
700 The BUFRSIZE is a property of a given open netcdf descriptor ncid,
701 it is not a persistent property of the netcdf dataset.
704 : Returned netCDF ID.
708 NF\_\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
709 causes of errors include:
711 - Passing a dataset name that includes a directory that does not
713 - Specifying a dataset name of a file that exists and also specifying
715 - Specifying a meaningless value for the creation mode.
716 - Attempting to create a netCDF dataset in a directory where you don’t
717 have permission to create files.
721 In this example we create a netCDF dataset named foo.nc; we want the
722 dataset to be created in the current directory only if a dataset with
723 that name does not already exist:
730 INTEGER NCID, STATUS, INITIALSZ, BUFRSIZEHINT
734 STATUS = NF__CREATE('foo.nc', NF_NOCLOBBER, INITIALSZ, BUFRSIZEHINT, NCID)
735 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
738 2.7 NF_CREATE_PAR {#NF_CREATE_PAR}
741 This function is a variant of nf\_create, nf\_create\_par allows users
742 to open a file on a MPI/IO or MPI/Posix parallel file system.
744 The parallel parameters are not written to the data file, they are only
745 used for so long as the file remains open after an nf\_create\_par.
747 This function is only available if the netCDF library was built with
750 This function creates a new netCDF dataset, returning a netCDF ID that
751 canbsequently be used to refer to the netCDF dataset in other netCDF
752 function calls. The new netCDF dataset opened for write access and
753 placed in define mode, ready for you to add dimensions, variables, and
756 When a netCDF-4 file is created for parallel access, independent
757 operations are the default. To use collective access on a variable, See
758 section [Change between Collective and Independent Parallel Access:
759 NF\_VAR\_PAR\_ACCESS](#NF_005fVAR_005fPAR_005fACCESS).
764 INTEGER FUNCTION NF_CREATE_PAR(CHARACTER*(*) PATH, INTEGER CMODE,
765 INTEGER MPI_COMM, INTEGER MPI_INFO,
770 : The file name of the new netCDF dataset.
773 : The creation mode flag. The following flags are available:
774 NF\_NOCLOBBER, NF\_NETCDF4 and NF\_CLASSIC\_MODEL. You can combine
775 the affect of multiple flags in a single argument by using the
776 bitwise OR operator. For example, to specify both NF\_NOCLOBBER and
777 NF\_NETCDF4, you could provide the argument OR(NF\_NOCLOBBER,
780 Setting NF\_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format
781 file. Oring NF\_CLASSIC\_MODEL with NF\_NETCDF4 causes the netCDF
782 library to create a netCDF-4/HDF5 data file, with the netCDF classic
783 model enforced - none of the new features of the netCDF-4 data model
784 may be usedinch a file, for example groups and user-defined
787 Only netCDF-4/HDF5 files may be used with parallel I/O.
790 : The MPI communicator.
796 : Returned netCDF ID.
801 NF\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
802 causes of errors include:
804 - Passing a dataset name that includes a directory that does not
806 - Specifying a dataset name of a file that exists and also specifying
808 - Specifying a meaningless value for the creation mode.
809 - Attempting to create a netCDF dataset in a directory where you don’t
810 have permission to create files.
815 This example is from test program nf\_test/ftst\_parallel.F.
820 ! Create the netCDF file.
821 mode_flag = IOR(nf_netcdf4, nf_classic_model)
822 retval = nf_create_par(FILE_NAME, mode_flag, MPI_COMM_WORLD,
823 $ MPI_INFO_NULL, ncid)
824 if (retval .ne. nf_noerr) stop 2
828 2.8 NF_OPEN {#NF_OPEN_}
831 The function NF\_OPEN opens an existing netCDF dataset for access.
836 INTEGER FUNCTION NF_OPEN(CHARACTER*(*) PATH, INTEGER OMODE, INTEGER ncid)
840 : File name for netCDF dataset to be opened. This may be an OPeNDAP
841 URL if DAPpport is enabled.
844 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
845 read-only access, buffering and caching accesses for efficiency.
847 Otherwise, the creation mode is NF\_WRITE, NF\_SHARE, or
848 OR(NF\_WRITE, NF\_SHARE). Setting the NF\_WRITE flag opens the
849 dataset with read-write access. ("Writing" means any kind of change
850 to the dataset, including appending or changing data, adding or
851 renaming dimensions, variables, and attributes, or deleting
852 attributes.) The NF\_SHARE flag is appropriate when one process may
853 be writing the dataset and one or more other processes reading the
854 dataset concurrently; it means that dataset accesses are not
855 buffered and caching is limited. Since the buffering scheme is
856 optimized for sequential access, programs that do not access data
857 sequentially may see some performance improvement by setting the
861 : Returned netCDF ID.
866 NF\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
867 the returned status indicates an error. Possible causes of errors
870 - The specified netCDF dataset does not exist.
871 - A meaningless mode was specified.
875 Here is an example using NF\_OPEN to open an existing netCDF dataset
876 named foo.nc for read-only, non-shared access:
883 STATUS = NF_OPEN('foo.nc', 0, NCID)
884 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
887 2.9 NF__OPEN {#NF__OPEN_}
890 The function NF\_OPEN opens an existing netCDF dataset for access, with
891 a performance tuning parameter.
896 INTEGER FUNCTION NF_OPEN(CHARACTER*(*) PATH, INTEGER OMODE, INTEGER
897 BUFRSIZEHINT, INTEGER ncid)
901 : File name for netCDF dataset to be opened.
904 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
905 read-only access, buffering and caching accesses for efficiency
907 Otherwise, the creation mode is NF\_WRITE, NF\_SHARE, or
908 OR(NF\_WRITE,NF\_SHARE). Setting the NF\_WRITE flag opens the
909 dataset with read-write access. ("Writing" means any kind of change
910 to the dataset, including appending or changing data, adding or
911 renaming dimensions, variables, and attributes, or deleting
912 attributes.) The NF\_SHARE flag is appropriate when one process may
913 be writing the dataset and one or more other processes reading the
914 dataset concurrently; it means that dataset accesses are not
915 buffered and caching is limited. Since the buffering scheme is
916 optimized for sequential access, programs that do not access data
917 sequentially may see some performance improvement by setting the
921 : This argument controls a space ves time tradeoff, memory
922 allocated in the netcdf library ves number of system calls.
924 Because of internal requirements, the value may not be set to
925 exactly the value requested. The actual value chosen is returned by
928 Using the value NF\_SIZEHINT\_DEFAULT causes the library to choose a
929 default. How the system chooses the default depends on the system.
930 On many systems, the "preferred I/O block size" is available from
931 the stat() system call, struct stat member st\_blksize. If this is
932 available it is used. Lacking that, twice the system pagesize is
935 Lacking a call to discover the system pagesize, we just set default
938 The bufrsize is a property of a given open netcdf descriptor ncid,
939 it is not a persistent property of the netcdf dataset.
942 : Returned netCDF ID.
947 NF\_\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
948 the returned status indicates an error. Possible causes of errors
951 - The specified netCDF dataset does not exist.
952 - A meaningless mode was specified.
956 Here is an example using NF\_\_OPEN to open an existing netCDF dataset
957 named foo.nc for read-only, non-shared access:
963 INTEGER NCID, STATUS, BUFRSIZEHINT
966 STATUS = NF_OPEN('foo.nc', 0, BUFRSIZEHINT, NCID)
967 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
970 2.10 NF\_OPEN\_PAR {#NF_OPEN_PAR}
973 This function opens a netCDF-4 dataset for parallel access.
975 This function is only available if the netCDF library was built with a
976 HDF5 library for which –enable-parallel was used, and which was linked
977 (like HDF5) to MPI libraries.
979 This opens the file using either MPI-IO or MPI-POSIX. The file must be a
980 netCDF-4 file. (That is, it must have been created using NF\_NETCDF4 in
983 This function is only available if netCDF-4 was build with a version of
984 the HDF5 library which was built with –enable-parallel.
986 Before either HDF5 or netCDF-4 can be installed withpport for
987 parallel programming, and MPI layer must also be installed on the
988 machine, and ally a parallel file system.
990 NetCDF-4 exposes the parallel access functionality of HDF5. For more
991 information about what is required to install and use the parallel
992 access functions, see the HDF5 web site.
994 When a netCDF-4 file is opened for parallel access, collective
995 operations are the default. To use independent access on a variable, See
996 section [Change between Collective and Independent Parallel Access:
997 NF\_VAR\_PAR\_ACCESS](#NF_005fVAR_005fPAR_005fACCESS).
1003 INTEGER FUNCTION NF_OPEN_PAR(CHARACTER*(*) PATH, INTEGER OMODE,
1004 INTEGER MPI_COMM, INTEGER MPI_INFO,
1009 : File name for netCDF dataset to be opened.
1012 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
1015 Otherwise, the mode may be NF\_WRITE. Setting the NF\_WRITE flag
1016 opens the dataset with read-write access. ("Writing" means any kind
1017 of change to the dataset, including appending or changing data,
1018 adding or renaming dimensions, variables, and attributes, or
1019 deleting attributes.)
1021 Setting NF\_NETCDF4 is not necessary (or allowed). The file type is
1022 detected automatically.
1025 : The MPI communicator.
1031 : Returned netCDF ID.
1036 NF\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
1037 the returned status indicates an error. Possible causes of errors
1040 - The specified netCDF dataset does not exist.
1041 - A meaningless mode was specified.
1042 - Not a netCDF-4 file.
1047 This example is from the test program nf\_test/ftst\_parallel.F.
1053 retval = nf_open_par(FILE_NAME, nf_nowrite, MPI_COMM_WORLD,
1054 $ MPI_INFO_NULL, ncid)
1055 if (retval .ne. nf_noerr) stop 2
1061 The function NF\_REDEF puts an open netCDF dataset into define mode, so
1062 dimensions, variables, and attributes can be added or renamed and
1063 attributes can be deleted.
1071 INTEGER FUNCTION NF_REDEF(INTEGER NCID)
1075 : netCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1080 NF\_REDEF returns the value NF\_NOERR if no errors occurred. Otherwise,
1081 the returned status indicates an error. Possible causes of errors
1084 - The specified netCDF dataset is already in define mode.
1085 - The specified netCDF dataset was opened for read-only.
1086 - The specified netCDF ID does not refer to an open netCDF dataset.
1091 Here is an example using NF\_REDEF to open an existing netCDF dataset
1092 named foo.nc and put it into define mode:
1097 INCLUDE 'netcdf.inc'
1099 INTEGER NCID, STATUS
1101 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID) ! open dataset
1102 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1104 STATUS = NF_REDEF(NCID) ! put in define mode
1105 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1111 The function NF\_ENDDEF takes an open netCDF dataset out of define mode.
1112 The changes made to the netCDF dataset while it was in define mode are
1113 checked and committed to disk if no problems occurred. Non-record
1114 variables may be initialized to a "fill value" as well (see
1115 [NF\_SET\_FILL](#NF_005fSET_005fFILL)). The netCDF dataset is then
1116 placed in data mode, so variable data can be read or written.
1118 This call may involve copying data under some circumstances. See
1119 [(netcdf)File Structure and
1120 Performance](netcdf.html#File-Structure-and-Performance) ‘File
1121 Structure and Performance’ in NetCDF Users’ Guide.
1129 INTEGER FUNCTION NF_ENDDEF(INTEGER NCID)
1133 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1138 NF\_ENDDEF returns the value NF\_NOERR if no errors occurred. Otherwise,
1139 the returned status indicates an error. Possible causes of errors
1142 - The specified netCDF dataset is not in define mode.
1143 - The specified netCDF ID does not refer to an open netCDF dataset.
1144 The size of one or more variables exceed the size constraints for
1145 whichever variant of the file format is in use). See [(netcdf)Large
1146 File Support](netcdf.html#Large-File-Support) ‘Large File
1147 Support’ in The NetCDF Users Guide.
1152 Here is an example using NF\_ENDDEF to finish the definitions of a new
1153 netCDF dataset named foo.nc and put it into data mode:
1158 INCLUDE 'netcdf.inc'
1160 INTEGER NCID, STATUS
1162 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1163 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1165 ... ! create dimensions, variables, attributes
1167 STATUS = NF_ENDDEF(NCID)
1168 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1174 The function NF\_\_ENDDEF takes an open netCDF dataset out of define
1175 mode. The changes made to the netCDF dataset while it was in define mode
1176 are checked and committed to disk if no problems occurred. Non-record
1177 variables may be initialized to a "fill value" as well (see
1178 [NF\_SET\_FILL](#NF_005fSET_005fFILL)). The netCDF dataset is then
1179 placed in data mode, so variable data can be read or written.
1181 This call may involve copying data under some circumstances. See
1182 [(netcdf)File Structure and
1183 Performance](netcdf.html#File-Structure-and-Performance) ‘File
1184 Structure and Performance’ in NetCDF Users’ Guide.
1186 This function ames specific characteristics of the netcdf version 1
1187 and version 2 file formats. Users should use nf\_enddef in most
1188 circumstances. Although this function will be available in future netCDF
1189 implementations, it may not continue to have any effect on performance.
1191 The current netcdf file format has threes, the "header",
1192 the data for fixed size variables, and the data for
1193 variables which have an unlimited dimension (record variables).
1195 The header begins at the beginning of the file. The index (offset) of
1196 the beginning of the other twos is contained in the header.
1197 Typically, there is no space between thes. This causes copying
1198 overhead to accrue if one wishes to change the size of thes, as
1199 may happen when changing names of things, text attribute values, adding
1200 attributes or adding variables. Also, for buffered i/o, there may be
1201 advantages to alignings in certain ways.
1203 The minfree parameters allow one to control costs of future calls to
1204 nf\_redef, nf\_enddef by requesting that minfree bytes be available at
1207 The align parameters allow one to set the alignment of the beginning of
1208 the correspondings. The beginning of the is rounded up
1209 to an index which is a multiple of the align parameter. The flag value
1210 ALIGN\_CHUNK tells the library to use the bufrsize (see above) as the
1213 The file format requires mod 4 alignment, so the align parameters are
1214 silently rounded up to multiples of 4. The al call,
1225 nf_enddef(ncid, 0, 4, 0, 4);
1228 The file format does not contain a "record size" value, this is
1229 calculated from the sizes of the record variables. This unfortunate fact
1230 prevents us from providing minfree and alignment control of the
1231 "records" in a netcdf file. If you add a variable which has an unlimited
1232 dimension, the third will always be copied with the new variable
1241 INTEGER FUNCTION NF_ENDDEF(INTEGER NCID, INTEGER H_MINFREE, INTEGER V_ALIGN,
1242 INTEGER V_MINFREE, INTEGER R_ALIGN)
1246 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1249 : Sets the pad at the end of the "header".
1252 : Controls the alignment of the beginning of the data for
1253 fixed size variables.
1256 : Sets the pad at the end of the data for fixed size
1260 : Controls the alignment of the beginning of the data for
1261 variables which have an unlimited dimension (record variables).
1266 NF\_\_ENDDEF returns the value NF\_NOERR if no errors occurred.
1267 Otherwise, the returned status indicates an error. Possible causes of
1270 - The specified netCDF dataset is not in define mode.
1271 - The specified netCDF ID does not refer to an open netCDF dataset.
1272 - The size of one or more variables exceed the size constraints for
1273 whichever variant of the file format is in use). See [(netcdf)Large
1274 File Support](netcdf.html#Large-File-Support) ‘Large File
1275 Support’ in The NetCDF Users Guide.
1280 Here is an example using NF\_\_ENDDEF to finish the definitions of a new
1281 netCDF dataset named foo.nc and put it into data mode:
1286 INCLUDE 'netcdf.inc'
1288 INTEGER NCID, STATUS, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN
1290 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1291 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1293 ... ! create dimensions, variables, attributes
1299 STATUS = NF_ENDDEF(NCID, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN)
1300 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1306 The function NF\_CLOSE closes an open netCDF dataset. If the dataset is
1307 in define mode, NF\_ENDDEF will be called before closing. (In this case,
1308 if NF\_ENDDEF returns an error, NF\_ABORT will automatically be called
1309 to restore the dataset to the consistent state before define mode was
1310 last entered.) After an open netCDF dataset is closed, its netCDF ID may
1311 be reassigned to the next netCDF dataset that is opened or created.
1319 INTEGER FUNCTION NF_CLOSE(INTEGER NCID)
1323 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1328 NF\_CLOSE returns the value NF\_NOERR if no errors occurred. Otherwise,
1329 the returned status indicates an error. Possible causes of errors
1332 - Define mode was entered and the automatic call made to NF\_ENDDEF
1334 - The specified netCDF ID does not refer to an open netCDF dataset.
1339 Here is an example using NF\_CLOSE to finish the definitions of a new
1340 netCDF dataset named foo.nc and release its netCDF ID:
1345 INCLUDE 'netcdf.inc'
1347 INTEGER NCID, STATUS
1349 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1350 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1352 ... ! create dimensions, variables, attributes
1354 STATUS = NF_CLOSE(NCID)
1355 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1361 Members of the NF\_INQ family of functions return information about an
1362 open netCDF dataset, given its netCDF ID. Dataset inquire functions may
1363 be called from either define mode or data mode. The first function,
1364 NF\_INQ, returns values for the number of dimensions, the number of
1365 variables, the number of global attributes, and the dimension ID of the
1366 dimension defined with unlimited length, if any. The other functions in
1367 the family each return just one of these items of information.
1369 For FORTRAN, these functions include NF\_INQ, NF\_INQ\_NDIMS,
1370 NF\_INQ\_NVARS, NF\_INQ\_NATTS, and NF\_INQ\_UNLIMDIM. An additional
1371 function, NF\_INQ\_FORMAT, returns the (rarely needed) format version.
1373 No I/O is performed when these functions are called, since the required
1374 information is available in memory for each open netCDF dataset.
1382 INTEGER FUNCTION NF_INQ (INTEGER NCID, INTEGER ndims,
1383 INTEGER nvars,INTEGER ngatts,
1385 INTEGER FUNCTION NF_INQ_NDIMS (INTEGER NCID, INTEGER ndims)
1386 INTEGER FUNCTION NF_INQ_NVARS (INTEGER NCID, INTEGER nvars)
1387 INTEGER FUNCTION NF_INQ_NATTS (INTEGER NCID, INTEGER ngatts)
1388 INTEGER FUNCTION NF_INQ_UNLIMDIM (INTEGER NCID, INTEGER unlimdimid)
1389 INTEGER FUNCTION NF_INQ_FORMAT (INTEGER NCID, INTEGER format)
1393 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1396 : Returned number of dimensions defined for this netCDF dataset.
1399 : Returned number of variables defined for this netCDF dataset.
1402 : Returned number of global attributes defined for this netCDF
1406 : Returned ID of the unlimited dimension, if there is one for this
1407 netCDF dataset. If no unlimited length dimension has been defined,
1411 : Returned format version, one of NF\_FORMAT\_CLASSIC,
1412 NF\_FORMAT\_64BIT, NF\_FORMAT\_NETCDF4,
1413 NF\_FORMAT\_NETCDF4\_CLASSIC.
1418 All members of the NF\_INQ family return the value NF\_NOERR if no
1419 errors occurred. Otherwise, the returned status indicates an error.
1420 Possible causes of errors include:
1422 - The specified netCDF ID does not refer to an open netCDF dataset.
1427 Here is an example using NF\_INQ to find out about a netCDF dataset
1433 INCLUDE 'netcdf.inc'
1435 INTEGER STATUS, NCID, NDIMS, NVARS, NGATTS, UNLIMDIMID
1437 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
1438 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1440 STATUS = NF_INQ(NCID, NDIMS, NVARS, NGATTS, UNLIMDIMID)
1441 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1447 The function NF\_SYNC offers a way to synchronize the disk copy of a
1448 netCDF dataset with in-memory buffers. There are two reasons you might
1449 want to synchronize after writes:
1451 - To minimize data loss in case of abnormal termination, or
1452 - To make data available to other processes for reading immediately
1453 after it is written. But note that a process that already had the
1454 dataset open for reading would not see the number of records
1455 increase when the writing process calls NF\_SYNC; to accomplish
1456 this, the reading process must call NF\_SYNC.
1458 This function is backward-compatible with previous versions of the
1459 netCDF library. The intent was to allow sharing of a netCDF dataset
1460 among multiple readers and one writer, by having the writer call
1461 NF\_SYNC after writing and the readers call NF\_SYNC before each read.
1462 For a writer, this flushes buffers to disk. For a reader, it makesre
1463 that the next read will be from disk rather than from previously cached
1464 buffers, so that the reader will see changes made by the writing process
1465 (e.g., the number of records written) without having to close and reopen
1466 the dataset. If you are only accessing a small amount of data, it can be
1467 expensive in computer resources to always synchronize to disk after
1468 every write, since you are giving up the benefits of buffering.
1470 An easier way to accomplish sharing (and what is now recommended) is to
1471 have the writer and readers open the dataset with the NF\_SHARE flag,
1472 and then it will not be necessary to call NF\_SYNC at all. However, the
1473 NF\_SYNC function still provides finer granularity than the NF\_SHARE
1474 flag, if only a few netCDF accesses need to be synchronized among
1477 It is important to note that changes to the ancillary data,ch as
1478 attribute values, are not propagated automatically by use of the
1479 NF\_SHARE flag. Use of the NF\_SYNC function is still required for this
1482 Sharing datasets when the writer enters define mode to change the data
1483 schema requires extra care. In previous releases, after the writer left
1484 define mode, the readers were left looking at an old copy of the
1485 dataset, since the changes were made to a new copy. The only way readers
1486 could see the changes was by closing and reopening the dataset. Now the
1487 changes are made in place, but readers have no knowledge that their
1488 internal tables are now inconsistent with the new dataset schema. If
1489 netCDF datasets are shared across redefinition, some mechanism external
1490 to the netCDF library must be provided that prevents access by readers
1491 during redefinition and causes the readers to call NF\_SYNC before any
1494 When calling NF\_SYNC, the netCDF dataset must be in data mode. A netCDF
1495 dataset in define mode is synchronized to disk only when NF\_ENDDEF is
1496 called. A process that is reading a netCDF dataset that another process
1497 is writing may call NF\_SYNC to get updated with the changes made to the
1498 data by the writing process (e.g., the number of records written),
1499 without having to close and reopen the dataset.
1501 Data is automatically synchronized to disk when a netCDF dataset is
1502 closed, or whenever you leave define mode.
1510 INTEGER FUNCTION NF_SYNC(INTEGER NCID)
1514 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1519 NF\_SYNC returns the value NF\_NOERR if no errors occurred. Otherwise,
1520 the returned status indicates an error. Possible causes of errors
1523 - The netCDF dataset is in define mode.
1524 - The specified netCDF ID does not refer to an open netCDF dataset.
1529 Here is an example using NF\_SYNC to synchronize the disk writes of a
1530 netCDF dataset named foo.nc:
1535 INCLUDE 'netcdf.inc'
1537 INTEGER STATUS, NCID
1539 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1540 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1542 ! write data or change attributes
1544 STATUS = NF_SYNC(NCID)
1545 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1551 You no longer need to call this function, since it is called
1552 automatically by NF\_CLOSE in case the dataset is in define mode and
1553 something goes wrong with committing the changes. The function NF\_ABORT
1554 just closes the netCDF dataset, if not in define mode. If the dataset is
1555 being created and is still in define mode, the dataset is deleted. If
1556 define mode was entered by a call to NF\_REDEF, the netCDF dataset is
1557 restored to its state before definition mode was entered and the dataset
1566 INTEGER FUNCTION NF_ABORT(INTEGER NCID)
1570 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1575 NF\_ABORT returns the value NF\_NOERR if no errors occurred. Otherwise,
1576 the returned status indicates an error. Possible causes of errors
1579 - When called from define mode while creating a netCDF dataset,
1580 deletion of the dataset failed.
1581 - The specified netCDF ID does not refer to an open netCDF dataset.
1586 Here is an example using NF\_ABORT to back out of redefinitions of a
1587 dataset named foo.nc:
1592 INCLUDE 'netcdf.inc'
1594 INTEGER STATUS, NCID, LATID
1596 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1597 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1599 STATUS = NF_REDEF(NCID)
1600 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1602 STATUS = NF_DEF_DIM(NCID, 'LAT', 18, LATID)
1603 IF (STATUS .NE. NF_NOERR) THEN ! dimension definition failed
1604 CALL HANDLE_ERR(STATUS)
1605 STATUS = NF_ABORT(NCID) ! abort redefinitions
1606 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1614 This function is intended for advanced usage, to optimize writes under
1615 some circumstances described below. The function NF\_SET\_FILL sets the
1616 fill mode for a netCDF dataset open for writing and returns the current
1617 fill mode in a return parameter. The fill mode can be specified as
1618 either NF\_FILL or NF\_NOFILL. The default behavior corresponding to
1619 NF\_FILL is that data is pre-filled with fill values, that is fill
1620 values are written when you create non-record variables or when you
1621 write a value beyond data that has not yet been written. This makes it
1622 possible to detect attempts to read data before it was written. See
1623 section [Fill Values](#Fill-Values), for more information on the use of
1624 fill values. See [(netcdf)Attribute
1625 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
1626 Conventions’ in The NetCDF Users Guide, for information about how to
1627 define your own fill values.
1629 The behavior corresponding to NF\_NOFILL overrides the default behavior
1630 of prefilling data with fill values. This can be used to enhance
1631 performance, because it avoids the duplicate writes that occur when the
1632 netCDF library writes fill values that are later overwritten with data.
1634 A value indicating which mode the netCDF dataset was already in is
1635 returned. You can use this value to temporarily change the fill mode of
1636 an open netCDF dataset and then restore it to the previous mode.
1638 After you turn on NF\_NOFILL mode for an open netCDF dataset, you must
1639 be certain to write valid data in all the positions that will later be
1640 read. Note that nofill mode is only a transient property of a netCDF
1641 dataset open for writing: if you close and reopen the dataset, it will
1642 revert to the default behavior. You can also revert to the default
1643 behavior by calling NF\_SET\_FILL again to explicitly set the fill mode
1646 There are three situations where it is advantageous to set nofill mode:
1648 1. Creating and initializing a netCDF dataset. In this case, you should
1649 set nofill mode before calling NF\_ENDDEF and then write completely
1650 all non-record variables and the initial records of all the record
1651 variables you want to initialize.
1652 2. Extending an existing record-oriented netCDF dataset. Set nofill
1653 mode after opening the dataset for writing, then append the
1654 additional records to the dataset completely, leaving no intervening
1656 3. Adding new variables that you are going to initialize to an existing
1657 netCDF dataset. Set nofill mode before calling NF\_ENDDEF then write
1658 all the new variables completely.
1660 If the netCDF dataset has an unlimited dimension and the last record was
1661 written while in nofill mode, then the dataset may be shorter than if
1662 nofill mode was not set, but this will be completely transparent if you
1663 access the data only through the netCDF interfaces.
1665 The use of this feature may not be available (or even needed) in future
1666 releases. Programmers are cautioned against heavy reliance upon this
1675 INTEGER FUNCTION NF_SET_FILL(INTEGER NCID, INTEGER FILLMODE,
1680 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1683 : Desired fill mode for the dataset, either NF\_NOFILL or NF\_FILL.
1686 : Returned current fill mode of the dataset before this call, either
1687 NF\_NOFILL or NF\_FILL.
1692 NF\_SET\_FILL returns the value NF\_NOERR if no errors occurred.
1693 Otherwise, the returned status indicates an error. Possible causes of
1696 - The specified netCDF ID does not refer to an open netCDF dataset.
1697 - The specified netCDF ID refers to a dataset open for read-only
1699 - The fill mode argument is neither NF\_NOFILL nor NF\_FILL..
1704 Here is an example using NF\_SET\_FILL to set nofill mode forbsequent
1705 writes of a netCDF dataset named foo.nc:
1710 INCLUDE 'netcdf.inc'
1712 INTEGER NCID, STATUS, OMODE
1714 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1715 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1717 ! write data with default prefilling behavior
1719 STATUS = NF_SET_FILL(NCID, NF_NOFILL, OMODE)
1720 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1722 ! write data with no prefilling
1726 2.19 NF\_SET\_DEFAULT\_FORMAT
1727 -----------------------------
1729 This function is intended for advanced users.
1731 In version 3.6, netCDF introduced a new data format, the first change in
1732 the underlying binary data format since the netCDF interface was
1733 released. The new format, 64-bit offset format, was introduced to
1734 greatly relax the limitations on creating very large files.
1736 In version 4.0, another new binary format was introduced: netCDF-4/HDF5.
1738 Users are warned that creating files in the 64-bit offset format makes
1739 them unreadable by the netCDF library prior to version 3.6.0, and
1740 creating files in netcdf-4/HDF5 format makes them unreadable by the
1741 netCDF library prior to version 4.0. For reasons of compatibility, users
1742 should continue to create files in netCDF classic format.
1744 Users who do want to use 64-bit offset or netCDF-4/HDF5 format files can
1745 create them directory from NF\_CREATE, using the proper cmode flag. (see
1746 section [NF\_CREATE](#NF_005fCREATE)).
1748 The function NF\_SET\_DEFAULT\_FORMAT allows the user to change the
1749 format of the netCDF file to be created by future calls to NF\_CREATE
1750 without changing the cmode flag.
1752 This allows the user to convert a program to use the new formats without
1753 changing all calls the NF\_CREATE.
1755 Once the default format is set, all future created files will be in the
1758 Constants are provided in the netcdf.inc file to be used with this
1759 function: nf\_format\_classic, nf\_format\_64bit, nf\_format\_netcdf4
1760 and nf\_format\_netcdf4\_classic.
1768 INTEGER FUNCTION NF_SET_DEFAULT_FORMAT(INTEGER FORMAT, INTEGER OLD_FORMT)
1772 : Either nf\_format\_classic, nf\_format\_64bit, nf\_format\_netcdf4
1773 or nf\_format\_netcdf4\_classic.
1776 : The default format at the time the function is called is returned
1782 The following error codes may be returned by this function:
1784 - An NF\_EINVAL error is returned if an invalid default format is
1793 INCLUDE 'netcdf.inc'
1795 INTEGER STATUS, OLD_FORMAT
1797 STATUS = NF_SET_DEFAULT_FORMAT(nf_format_64bit, OLD_FORMAT)
1798 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1802 2.20 Set HDF5 Chunk Cache for Future File Opens/Creates: NF\_SET\_CHUNK\_CACHE
1803 ------------------------------------------------------------------------------
1805 This function changes the chunk cache settings in the HDF5 library. The
1806 settings apply forbsequent file opens/creates. This function does not
1807 change the chunk cache settings of already open files.
1809 This affects the per-file chunk cache which the HDF5 layer maintains.
1810 The chunk cache size can be tuned for better performance.
1812 For more information, see the documentation for the H5Pset\_cache()
1813 function in the HDF5 library at the HDF5 website:
1814 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
1822 INTEGER NF_SET_CHUNK_CACHE(INTEGER SIZE, INTEGER NELEMS, INTEGER PREEMPTION);
1826 : The total size of the raw data chunk cache in MegaBytes.
1829 : The number slots in the per-variable chunk cache (should be a prime
1830 number larger than the number of chunks in the cache).
1833 : The preemtion value must be between 0 and 100 inclusive and
1834 indicates how much chunks that have been fully read are favored for
1835 preemption. A value of zero means fully read chunks are treated no
1836 differently than other chunks (the preemption is strictly LRU) while
1837 a value of 100 means fully read chunks are always preempted before
1847 : Parameters size and nelems must be non-zero positive integers, and
1848 preemption must be between zero and 100 (inclusive). An NF\_EINVAL
1849 will be returned otherwise.
1853 2.21 Get the HDF5 Chunk Cache Settings for Future File Opens/Creates: NF\_GET\_CHUNK\_CACHE
1854 -------------------------------------------------------------------------------------------
1856 This function gets the chunk cache settings for the HDF5 library. The
1857 settings apply forbsequent file opens/creates.
1859 This affects the per-file chunk cache which the HDF5 layer maintains.
1860 The chunk cache size can be tuned for better performance.
1862 For more information, see the documentation for the H5Pget\_cache()
1863 function in the HDF5 library at the HDF5 website:
1864 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
1872 INTEGER NC_GET_CHUNK_CACHE(INTEGER SIZE, INTEGER NELEMS, INTEGER PREEMPTION);
1876 : The total size of the raw data chunk cache will be put here.
1879 : The number of chunk slots in the raw data chunk cache hash table
1883 : The preemption will be put here. The preemtion value is between 0
1884 and 100 inclusive and indicates how much chunks that have been fully
1885 read are favored for preemption. A value of zero means fully read
1886 chunks are treated no differently than other chunks (the preemption
1887 is strictly LRU) while a value of 100 means fully read chunks are
1888 always preempted before other chunks.
1899 NetCDF-4 addedpport for hierarchical groups within netCDF datasets.
1901 Groups are identified with a ncid, which identifies both the open file,
1902 and the group within that file. When a file is opened with NF\_OPEN or
1903 NF\_CREATE, the ncid for the root group of that file is provided. Using
1904 that as a starting point, users can add new groups, or list and navigate
1907 All netCDF calls take a ncid which determines where the call will take
1908 its action. For example, the NF\_DEF\_VAR function takes a ncid as its
1909 first parameter. It will create a variable in whichever group its ncid
1910 refers to. Use the root ncid provided by NF\_CREATE or NF\_OPEN to
1911 create a variable in the root group. Or use NF\_DEF\_GRP to create a
1912 group and use its ncid to define a variable in the new group.
1914 Variable are only visible in the group in which they are defined. The
1915 same applies to attributes. “Global” attributes are defined in whichever
1916 group is refered to by the ncid.
1918 Dimensions are visible in their groups, and all child groups.
1920 Group operations are only permitted on netCDF-4 files - that is, files
1921 created with the HDF5 flag in nf\_create. (see
1922 [NF\_CREATE](#NF_005fCREATE)). Groups are not compatible with the netCDF
1923 classic data model, so files created with the NF\_CLASSIC\_MODEL file
1924 cannot contain groups (except the root group).
1926 3.1 Find a Group ID: NF\_INQ\_NCID
1927 ----------------------------------
1929 Given an ncid and group name (NULL or "" gets root group), return ncid
1938 INTEGER FUNCTION NF_INQ_NCID(INTEGER NCID, CHARACTER*(*) NAME, INTEGER GRPID)
1942 : The group id for this operation.
1945 : A character array that holds the name of the desired group. Must be
1946 less then NF\_MAX\_NAME.
1949 : The ID of the group will go here.
1961 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
1962 operations can only be performed on files defined with a create mode
1963 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
1966 : This file was created with the strict netcdf-3 flag, therefore
1967 netcdf-4 operations are not allowed. (see
1968 [NF\_OPEN](#NF_005fOPEN)).
1971 : An error was reported by the HDF5 layer.
1976 This example is from nf\_test/ftst\_groups.F.
1981 C Check getting the group by name
1982 retval = nf_inq_ncid(ncid, group_name, grpid_in)
1983 if (retval .ne. nf_noerr) call handle_err(retval)
1986 3.2 Get a List of Groups in a Group: NF\_INQ\_GRPS
1987 --------------------------------------------------
1989 Given a location id, return the number of groups it contains, and an
1990 array of their ncids.
1998 INTEGER FUNCTION NF_INQ_GRPS(INTEGER NCID, INTEGER NUMGRPS, INTEGER NCIDS)
2002 : The group id for this operation.
2005 : An integer which will get number of groups in this group.
2008 : An array of ints which will receive the IDs of all the groups in
2021 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2022 operations can only be performed on files defined with a create mode
2023 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2026 : This file was created with the strict netcdf-3 flag, therefore
2027 netcdf-4 operations are not allowed. (see
2028 [NF\_OPEN](#NF_005fOPEN)).
2031 : An error was reported by the HDF5 layer.
2036 This example is from nf\_test/ftst\_groups.F.
2041 C What groups are there from the root group?
2042 retval = nf_inq_grps(ncid, ngroups_in, grpids)
2043 if (retval .ne. nf_noerr) call handle_err(retval)
2046 3.3 Find all the Variables in a Group: NF\_INQ\_VARIDS
2047 ------------------------------------------------------
2049 Find all varids for a location.
2057 INTEGER FUNCTION NF_INQ_VARIDS(INTEGER NCID, INTEGERS VARIDS)
2061 : The group id for this operation.
2064 : An already allocated array to store the list of varids. Use
2065 nf\_inq\_nvars to find out how many variables there are. (see
2066 [NF\_INQ Family](#NF_005fINQ-Family)).
2078 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2079 operations can only be performed on files defined with a create mode
2080 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2083 : This file was created with the strict netcdf-3 flag, therefore
2084 netcdf-4 operations are not allowed. (see
2085 [NF\_OPEN](#NF_005fOPEN)).
2088 : An error was reported by the HDF5 layer.
2093 This example is from nf\_test/ftst\_groups.F.
2098 C Check varids inbgroup.
2099 retval = nf_inq_varidsbgrp_in, nvars, varids_in)
2100 if (retval .ne. nf_noerr) call handle_err(retval)
2103 3.4 Find all Dimensions Visible in a Group: NF\_INQ\_DIMIDS
2104 -----------------------------------------------------------
2106 Find all dimids for a location. This finds all dimensions in a group, or
2115 INTEGER FUNCTION NF_INQ_DIMIDS(INTEGER NCID, INTEGER NDIMS, INTEGER DIMIDS, INTEGER INCLUDE_PARENTS)
2119 : The group id for this operation.
2122 : Returned number of dimensions for this location. If INCLUDE\_PARENTS
2123 is non-zero, number of dimensions visible from this group, which
2124 includes dimensions in parent groups.
2127 : An array of ints when the dimids of the visible dimensions will be
2128 stashed. Use nf\_inq\_ndims to find out how many dims are visible
2129 from this group. (see [NF\_INQ Family](#NF_005fINQ-Family)).
2132 : If zero, only the group specified by NCID will be searched for
2133 dimensions. Otherwise parent groups will be searched too.
2145 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2146 operations can only be performed on files defined with a create mode
2147 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2150 : This file was created with the strict netcdf-3 flag, therefore
2151 netcdf-4 operations are not allowed. (see
2152 [NF\_OPEN](#NF_005fOPEN)).
2155 : An error was reported by the HDF5 layer.
2160 This example is from nf\_test/ftst\_groups.F.
2165 C Check dimids inbgroup.
2166 retval = nf_inq_dimidsbgrp_in, ndims, dimids_in, 0)
2167 if (retval .ne. nf_noerr) call handle_err(retval)
2168 if (ndims .ne. 2 .or. dimids_in(1) .ne. dimids(1) .or.
2169 & dimids_in(2) .ne. dimids(2)) stop 2
2172 3.5 Find the Length of a Group’s Name: NF\_INQ\_GRPNAME\_LEN
2173 ------------------------------------------------------------
2175 Given ncid, find length of the full name. (Root group is named "/", with
2184 INTEGER FUNCTION NF_INQ_GRPNAME_LEN(INTEGER NCID, INTEGER LEN)
2188 : The group id for this operation.
2191 : An integer where the length will be placed.
2203 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2204 operations can only be performed on files defined with a create mode
2205 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2208 : This file was created with the strict netcdf-3 flag, therefore
2209 netcdf-4 operations are not allowed. (see
2210 [NF\_OPEN](#NF_005fOPEN)).
2213 : An error was reported by the HDF5 layer.
2218 This example is from nf\_test/ftst\_groups.F.
2223 C Check the length of the full name.
2224 retval = nf_inq_grpname_len(grpids(1), full_name_len)
2225 if (retval .ne. nf_noerr) call handle_err(retval)
2228 3.6 Find a Group’s Name: NF\_INQ\_GRPNAME
2229 -----------------------------------------
2231 Given ncid, find relative name of group. (Root group is named "/").
2233 The name provided by this function is relative to the parent group. For
2234 a full path name for the group is, with all parent groups included,
2235 separated with a forward slash (as in Unix directory names) See
2236 [Find a Group’s Full Name:
2237 NF\_INQ\_GRPNAME\_FULL](#NF_005fINQ_005fGRPNAME_005fFULL).
2245 INTEGER FUNCTION NF_INQ_GRPNAME(INTEGER NCID, CHARACTER*(*) NAME)
2250 The group id for this operation.
2254 The name of the group will be copied to this character array. The name
2255 will be less than NF\_MAX\_NAME in length.
2269 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2270 operations can only be performed on files defined with a create mode
2271 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2274 : This file was created with the strict netcdf-3 flag, therefore
2275 netcdf-4 operations are not allowed. (see
2276 [NF\_OPEN](#NF_005fOPEN)).
2279 : An error was reported by the HDF5 layer.
2284 This example is from nf\_test/ftst\_groups.F.
2289 C Check the name of the root group.
2290 retval = nf_inq_grpname(ncid, name_in)
2291 if (retval .ne. nf_noerr) call handle_err(retval)
2292 if (name_in(1:1) .ne. '/') stop 2
2296 3.7 Find a Group’s Full Name: NF\_INQ\_GRPNAME\_FULL
2297 ----------------------------------------------------
2299 Given ncid, find complete name of group. (Root group is named "/").
2301 The name provided by this function is a full path name for the group is,
2302 with all parent groups included, separated with a forward slash (as in
2303 Unix directory names). For a name relative to the parent group See
2304 section [Find a Group’s Name:
2305 NF\_INQ\_GRPNAME](#NF_005fINQ_005fGRPNAME).
2307 To find the length of the full name See [Find the Length of a
2308 Group’s Name: NF\_INQ\_GRPNAME\_LEN](#NF_005fINQ_005fGRPNAME_005fLEN).
2316 INTEGER FUNCTION NF_INQ_GRPNAME_FULL(INTEGER NCID, INTEGER LEN, CHARACTER*(*) NAME)
2320 : The group id for this operation.
2323 : The length of the full group name will go here.
2326 : The name of the group will be copied to this character array.
2338 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2339 operations can only be performed on files defined with a create mode
2340 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2343 : This file was created with the strict netcdf-3 flag, therefore
2344 netcdf-4 operations are not allowed. (see
2345 [NF\_OPEN](#NF_005fOPEN)).
2348 : An error was reported by the HDF5 layer.
2353 This example is from nf\_test/ftst\_groups.F.
2358 C Check the full name.
2359 retval = nf_inq_grpname_full(grpids(1), full_name_len, name_in2)
2360 if (retval .ne. nf_noerr) call handle_err(retval)
2363 3.8 Find a Group’s Parent: NF\_INQ\_GRP\_PARENT
2364 -----------------------------------------------
2366 Given ncid, find the ncid of the parent group.
2368 When used with the root group, this function returns the NF\_ENOGRP
2369 error (since the root group has no parent.)
2377 INTEGER FUNCTION NF_INQ_GRP_PARENT(INTEGER NCID, INTEGER PARENT_NCID)
2384 : The ncid of the parent group will be copied here.
2396 : No parent group found (i.e. this is the root group).
2399 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2400 operations can only be performed on files defined with a create mode
2401 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2404 : This file was created with the strict netcdf-3 flag, therefore
2405 netcdf-4 operations are not allowed. (see
2406 [NF\_OPEN](#NF_005fOPEN)).
2409 : An error was reported by the HDF5 layer.
2414 This example is from nf\_test/ftst\_groups.F.
2419 C Check the parent ncid.
2420 retval = nf_inq_grp_parent(grpids(1), grpid_in)
2421 if (retval .ne. nf_noerr) call handle_err(retval)
2424 3.9 Find a Group by Name: NF\_INQ\_GRP\_NCID
2425 --------------------------------------------
2427 Given a group name an an ncid, find the ncid of the group id.
2435 INTEGER FUNCTION NF_INQ_GRP_NCID(INTEGER NCID, CHARACTER GRP_NAME, INTEGER GRP_NCID)
2439 : The group id to look in.
2442 : The name of the group that should be found.
2445 : This will get the group id, if it is found.
2450 The following return codes may be returned by this function.
2459 : No name provided or name longer than NF\_MAX\_NAME.
2462 : Named group not found.
2465 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2466 operations can only be performed on files defined with a create mode
2467 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2470 : This file was created with the strict netcdf-3 flag, therefore
2471 netcdf-4 operations are not allowed. (see
2472 [NF\_OPEN](#NF_005fOPEN)).
2475 : An error was reported by the HDF5 layer.
2480 This example is from nf\_test/ftst\_types3.F.
2485 C Go to a child group and find the id of our type.
2486 retval = nf_inq_grp_ncid(ncid, group_name,b_grpid)
2487 if (retval .ne. nf_noerr) call handle_err(retval)
2490 3.10 Find a Group by its Fully-qualified Name: NF\_INQ\_GRP\_FULL\_NCID
2491 -----------------------------------------------------------------------
2493 Given a fully qualified group name an an ncid, find the ncid of the
2502 INTEGER FUNCTION NF_INQ_GRP_FULL_NCID(INTEGER NCID, CHARACTER FULL_NAME, INTEGER GRP_NCID)
2506 : The group id to look in.
2509 : The fully-qualified group name.
2512 : This will get the group id, if it is found.
2517 The following return codes may be returned by this function.
2526 : No name provided or name longer than NF\_MAX\_NAME.
2529 : Named group not found.
2532 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2533 operations can only be performed on files defined with a create mode
2534 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2537 : This file was created with the strict netcdf-3 flag, therefore
2538 netcdf-4 operations are not allowed. (see
2539 [NF\_OPEN](#NF_005fOPEN)).
2542 : An error was reported by the HDF5 layer.
2547 This example is from nf\_test/ftst\_groups.F.
2552 C Check the full name of the root group (also "/").
2553 retval = nf_inq_grpname_full(ncid, full_name_len, name_in)
2554 if (retval .ne. nf_noerr) call handle_err(retval)
2557 3.11 Create a New Group: NF\_DEF\_GRP
2558 -------------------------------------
2560 Create a group. Its location id is returned in new\_ncid.
2568 INTEGER FUNCTION NF_DEF_GRP(INTEGER PARENT_NCID, CHARACTER*(*) NAME,
2573 : The group id of the parent group.
2576 : The name of the new group, which must be different from the name of
2577 any variable within the same parent group.
2580 : The ncid of the new group will be placed there.
2592 : That name is in use. Group names must be unique within a group.
2595 : Name exceed max length NF\_MAX\_NAME.
2598 : Name contains illegal characters.
2601 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2602 operations can only be performed on files defined with a create mode
2603 which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2606 : This file was created with the strict netcdf-3 flag, therefore
2607 netcdf-4 operations are not allowed. (see
2608 [NF\_OPEN](#NF_005fOPEN)).
2611 : An error was reported by the HDF5 layer.
2614 : Attempt to write to a read-only file.
2617 : Not in define mode.
2622 In this exampe rom nf\_test/ftst\_groups.F, a groups is reated, and then
2623 ab-group is created in that group.
2628 C Create the netCDF file.
2629 retval = nf_create(file_name, NF_NETCDF4, ncid)
2630 if (retval .ne. nf_noerr) call handle_err(retval)
2632 C Create a group and abgroup.
2633 retval = nf_def_grp(ncid, group_name, grpid)
2634 if (retval .ne. nf_noerr) call handle_err(retval)
2635 retval = nf_def_grp(grpid,b_group_name,b_grpid)
2636 if (retval .ne. nf_noerr) call handle_err(retval)
2642 4.1 Dimensions Introduction
2643 ---------------------------
2645 Dimensions for a netCDF dataset are defined when it is created, while
2646 the netCDF dataset is in define mode. Additional dimensions may be added
2647 later by reentering define mode. A netCDF dimension has a name and a
2648 length. At most one dimension in a netCDF dataset can have the unlimited
2649 length, which means variables using this dimension can grow along this
2652 There is aggested limit (100) to the number of dimensions that can be
2653 defined in a single netCDF dataset. The limit is the value of the
2654 predefined macro NF\_MAX\_DIMS. The purpose of the limit is to make
2655 writing generic applications simpler. They need only provide an array of
2656 NF\_MAX\_DIMS dimensions to handle any netCDF dataset. The
2657 implementation of the netCDF library does not enforce this advisory
2658 maximum, so it is possible to use more dimensions, if necessary, but
2659 netCDF utilities that ame the advisory maximums may not be able to
2660 handle the rlting netCDF datasets.
2662 Ordinarily, the name and length of a dimension are fixed when the
2663 dimension is first defined. The name may be changed later, but the
2664 length of a dimension (other than the unlimited dimension) cannot be
2665 changed without copying all the data to a new netCDF dataset with a
2666 redefined dimension length.
2668 A netCDF dimension in an open netCDF dataset is referred to by a small
2669 integer called a dimension ID. In the FORTRAN interface, dimension IDs
2670 are 1, 2, 3, ..., in the order in which the dimensions were defined.
2672 Operationspported on dimensions are:
2674 - Create a dimension, given its name and length.
2675 - Get a dimension ID from its name.
2676 - Get a dimension’s name and length from its ID.
2677 - Rename a dimension.
2682 The function NF\_DEF\_DIM adds a new dimension to an open netCDF dataset
2683 in define mode. It returns (as an argument) a dimension ID, given the
2684 netCDF ID, the dimension name, and the dimension length. At most one
2685 unlimited length dimension, called the record dimension, may be defined
2686 for each netCDF dataset.
2694 INTEGER FUNCTION NF_DEF_DIM (INTEGER NCID, CHARACTER*(*) NAME,
2695 INTEGER LEN, INTEGER dimid)
2699 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2705 : Length of dimension; that is, number of values for this dimension as
2706 an index to variables that use it. This should be either a positive
2707 integer or the predefined constant NF\_UNLIMITED.
2710 : Returned dimension ID.
2715 NF\_DEF\_DIM returns the value NF\_NOERR if no errors occurred.
2716 Otherwise, the returned status indicates an error. Possible causes of
2719 - The netCDF dataset is not in definition mode.
2720 - The specified dimension name is the name of another existing
2722 - The specified length is not greater than zero.
2723 - The specified length is unlimited, but there is already an unlimited
2724 length dimension defined for this netCDF dataset.
2725 - The specified netCDF ID does not refer to an open netCDF dataset.
2730 Here is an example using NF\_DEF\_DIM to create a dimension named lat of
2731 length 18 and a unlimited dimension named rec in a new netCDF dataset
2737 INCLUDE 'netcdf.inc'
2739 INTEGER STATUS, NCID, LATID, RECID
2741 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
2742 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2744 STATUS = NF_DEF_DIM(NCID, 'lat', 18, LATID)
2745 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2746 STATUS = NF_DEF_DIM(NCID, 'rec', NF_UNLIMITED, RECID)
2747 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2753 The function NF\_INQ\_DIMID returns (as an argument) the ID of a netCDF
2754 dimension, given the name of the dimension. If ndims is the number of
2755 dimensions defined for a netCDF dataset, each dimension has an ID
2756 between 1 and ndims.
2764 INTEGER FUNCTION NF_INQ_DIMID (INTEGER NCID, CHARACTER*(*) NAME,
2769 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2775 : Returned dimension ID.
2780 NF\_INQ\_DIMID returns the value NF\_NOERR if no errors occurred.
2781 Otherwise, the returned status indicates an error. Possible causes of
2784 - The name that was specified is not the name of a dimension in the
2786 - The specified netCDF ID does not refer to an open netCDF dataset.
2791 Here is an example using NF\_INQ\_DIMID to determine the dimension ID of
2792 a dimension named lat, amed to have been defined previously in an
2793 existing netCDF dataset named foo.nc:
2798 INCLUDE 'netcdf.inc'
2800 INTEGER STATUS, NCID, LATID
2802 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
2803 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2805 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2806 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2809 4.4 NF\_INQ\_DIM Family
2810 -----------------------
2812 This family of functions returns information about a netCDF dimension.
2813 Information about a dimension includes its name and its length. The
2814 length for the unlimited dimension, if any, is the number of records
2817 The functions in this family include NF\_INQ\_DIM, NF\_INQ\_DIMNAME, and
2818 NF\_INQ\_DIMLEN. The function NF\_INQ\_DIM returns all the information
2819 about a dimension; the other functions each return just one item of
2828 INTEGER FUNCTION NF_INQ_DIM (INTEGER NCID, INTEGER DIMID,
2829 CHARACTER*(*) name, INTEGER len)
2830 INTEGER FUNCTION NF_INQ_DIMNAME (INTEGER NCID, INTEGER DIMID,
2832 INTEGER FUNCTION NF_INQ_DIMLEN (INTEGER NCID, INTEGER DIMID,
2837 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2840 : Dimension ID, from a previous call to NF\_INQ\_DIMID or
2844 : Returned dimension name. The caller must allocate space for the
2845 returned name. The maximum possible length, in characters, of a
2846 dimension name is given by the predefined constant NF\_MAX\_NAME.
2849 : Returned length of dimension. For the unlimited dimension, this is
2850 the current maximum value used for writing any variables with this
2851 dimension, that is the maximum record number.
2856 These functions return the value NF\_NOERR if no errors occurred.
2857 Otherwise, the returned status indicates an error. Possible causes of
2860 - The dimension ID is invalid for the specified netCDF dataset.
2861 - The specified netCDF ID does not refer to an open netCDF dataset.
2866 Here is an example using NF\_INQ\_DIM to determine the length of a
2867 dimension named lat, and the name and current maximum length of the
2868 unlimited dimension for an existing netCDF dataset named foo.nc:
2873 INCLUDE 'netcdf.inc'
2875 INTEGER STATUS, NCID, LATID, LATLEN, RECID, NRECS
2876 CHARACTER*(NF_MAX_NAME) LATNAM, RECNAM
2878 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
2879 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2880 ! get ID of unlimited dimension
2881 STATUS = NF_INQ_UNLIMDIM(NCID, RECID)
2882 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2884 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2885 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2887 STATUS = NF_INQ_DIMLEN(NCID, LATID, LATLEN)
2888 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2889 ! get unlimited dimension name and current length
2890 STATUS = NF_INQ_DIM(NCID, RECID, RECNAME, NRECS)
2891 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2897 The function NF\_RENAME\_DIM renames an existing dimension in a netCDF
2898 dataset open for writing. If the new name is longer than the old name,
2899 the netCDF dataset must be in define mode. You cannot rename a dimension
2900 to have the same name as another dimension.
2908 INTEGER FUNCTION NF_RENAME_DIM (INTEGER NCID, INTEGER DIMID,
2913 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2916 : Dimension ID, from a previous call to NF\_INQ\_DIMID or
2920 : New dimension name.
2925 NF\_RENAME\_DIM returns the value NF\_NOERR if no errors occurred.
2926 Otherwise, the returned status indicates an error. Possible causes of
2929 - The new name is the name of another dimension.
2930 - The dimension ID is invalid for the specified netCDF dataset.
2931 - The specified netCDF ID does not refer to an open netCDF dataset.
2932 - The new name is longer than the old name and the netCDF dataset is
2938 Here is an example using NF\_RENAME\_DIM to rename the dimension lat to
2939 latitude in an existing netCDF dataset named foo.nc:
2944 INCLUDE 'netcdf.inc'
2946 INTEGER STATUS, NCID, LATID
2948 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
2949 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2951 ! put in define mode to rename dimension
2952 STATUS = NF_REDEF(NCID)
2953 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2954 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2955 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2956 STATUS = NF_RENAME_DIM(NCID, LATID, 'latitude')
2957 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2959 STATUS = NF_ENDDEF(NCID)
2960 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2963 5. User Defined Data Types
2964 ==========================
2966 5.1 User Defined Types Introduction
2967 -----------------------------------
2969 NetCDF-4 has addedpport for four different user defined data types.
2972 : Like a C struct, a compound type is a collection of types, including
2973 other user defined types, in one package.
2975 `variable length array type`
2976 : The variable length array may be used to store ragged arrays.
2979 : This type has only a size per element, and no other type
2983 : Like an enumeration in C, this type lets you assign text values to
2984 integer values, and store the integer values.
2986 Users may construct user defined type with the various NF\_DEF\_\*
2987 functions described in this. They may learn about user defined
2988 types by using the NF\_INQ\_ functions defined in this.
2990 Once types are constructed, define variables of the new type with
2991 NF\_DEF\_VAR (see [Create a Variable:
2992 `NF_DEF_VAR`](#NF_005fDEF_005fVAR)). Write to them with NF\_PUT\_VAR1,
2993 NF\_PUT\_VAR, NF\_PUT\_VARA, or NF\_PUT\_VARS (see
2994 [Variables](#Variables)). Read data of user-defined type with
2995 NF\_GET\_VAR1, NF\_GET\_VAR, NF\_GET\_VARA, or NF\_GET\_VARS (see
2996 section [Variables](#Variables)).
2998 Create attributes of the new type with NF\_PUT\_ATT (see
2999 [NF\_PUT\_ATT\_ type](#NF_005fPUT_005fATT_005f-type)). Read attributes
3000 of the new type with NF\_GET\_ATT (see [NF\_GET\_ATT\_
3001 type](#NF_005fGET_005fATT_005f-type)).
3003 5.2 Learn the IDs of All Types in Group: NF\_INQ\_TYPEIDS
3004 ---------------------------------------------------------
3006 Learn the number of types defined in a group, and their IDs.
3013 INTEGER FUNCTION NF_INQ_TYPEIDS(INTEGER NCID, INTEGER NTYPES,
3021 : A pointer to int which will get the number of types defined in the
3022 group. If NULL, ignored.
3025 : A pointer to an int array which will get the typeids. If NULL,
3040 The following example is from the test program nf\_test/ftst\_vars3.F.
3045 retval = nf_inq_typeids(ncid, num_types, typeids)
3046 if (retval .ne. nf_noerr) call handle_err(retval)
3050 5.3 Find a Typeid from Group and Name: NF\_INQ\_TYPEID
3051 ------------------------------------------------------
3053 Given a group ID and a type name, find the ID of the type. If the type
3054 is not found in the group, then the parents are searched. If still not
3055 found, the entire file is searched.
3063 INTEGER FUNCTION NF_INQ_TYPEID(INTEGER NCID, CHARACTER NAME, NF_TYPE TYPEIDP)
3070 : The name of a type.
3073 : The typeid of the named type (if found).
3090 The following example is from nf\_test/ftst\_types3.F:
3095 C Go to a child group and find the id of our type.
3096 retval = nf_inq_grp_ncid(ncid, group_name,b_grpid)
3097 if (retval .ne. nf_noerr) call handle_err(retval)
3098 retval = nf_inq_typeidb_grpid, type_name, typeid_in)
3099 if (retval .ne. nf_noerr) call handle_err(retval)
3102 5.4 Learn About a User Defined Type: NF\_INQ\_TYPE
3103 --------------------------------------------------
3105 Given an ncid and a typeid, get the information about a type. This
3106 function will work on any type, including atomic and any user defined
3107 type, whether compound, opaque, enumeration, or variable length array.
3109 For even more information about a user defined type [Learn About a User
3110 Defined Type: NF\_INQ\_USER\_TYPE](#NF_005fINQ_005fUSER_005fTYPE).
3118 INTEGER FUNCTION NF_INQ_TYPE(INTEGER NCID, INTEGER XTYPE,
3119 CHARACTER*(*) NAME, INTEGER SIZE)
3123 : The ncid for the group containing the type (ignored for atomic
3127 : The typeid for this type, as returned by NF\_DEF\_COMPOUND,
3128 NF\_DEF\_OPAQUE, NF\_DEF\_ENUM, NF\_DEF\_VLEN, or NF\_INQ\_VAR, or
3129 as found in netcdf.inc in the list of atomic types (NF\_CHAR,
3133 : The name of the user defined type will be copied here. It will be
3134 NF\_MAX\_NAME bytes or less. For atomic types, the type name from
3138 : The (in-memory) size of the type (in bytes) will be copied here.
3139 VLEN type size is the size of one vlen sturture (i.e. the sice of
3140 nc\_vlen\_t). String size is returned as the size of one C character
3153 : Seeking a user-defined type in a netCDF-3 file.
3156 : Seeking a user-defined type in a netCDF-4 file for which classic
3157 model has been turned on.
3160 : Bad group ID in ncid.
3163 : Type ID not found.
3166 : An error was reported by the HDF5 layer.
3171 This example is from the test program nf\_test/ftst\_vars3.F, and it
3172 uses all the possible inquiry functions on an enum type.
3177 C Check the enum type.
3178 retval = NF_INQ_TYPEIDS(ncid, num_types, typeids)
3179 if (retval .ne. nf_noerr) call handle_err(retval)
3180 if (num_types .ne. MAX_TYPES) stop 2
3181 retval = nf_inq_enum(ncid, typeids(1), type_name, base_type,
3182 & base_size, num_members)
3183 if (retval .ne. nf_noerr) call handle_err(retval)
3184 if (base_type .ne. NF_INT .or. num_members .ne. 2) stop 2
3185 retval = nf_inq_enum_member(ncid, typeids(1), 1, member_name,
3187 if (retval .ne. nf_noerr) call handle_err(retval)
3188 if (member_name(1:len(one_name)) .ne. one_name) stop 2
3191 5.5 Learn About a User Defined Type: NF\_INQ\_USER\_TYPE
3192 --------------------------------------------------------
3194 Given an ncid and a typeid, get the information about a user defined
3195 type. This function will work on any user defined type, whether
3196 compound, opaque, enumeration, or variable length array.
3204 INTEGER FUNCTION NF_INQ_USER_TYPE(INTEGER NCID, INTEGER XTYPE,
3205 CHARACTER*(*) NAME, INTEGER SIZE, INTEGER BASE_NF_TYPE,
3206 INTEGER NFIELDS, INTEGER CLASS)
3210 : The ncid for the group containing the user defined type.
3213 : The typeid for this type, as returned by NF\_DEF\_COMPOUND,
3214 NF\_DEF\_OPAQUE, NF\_DEF\_ENUM, NF\_DEF\_VLEN, or NF\_INQ\_VAR.
3217 : The name of the user defined type will be copied here. It will be
3218 NF\_MAX\_NAME bytes or less.
3221 : The (in-memory) size of the user defined type will be copied here.
3224 : The base typeid will be copied here for vlen and enum types.
3227 : The number of fields will be copied here for enum and compound
3231 : The class of the user defined type, NF\_VLEN, NF\_OPAQUE, NF\_ENUM,
3232 or NF\_COMPOUND, will be copied here.
3247 : An error was reported by the HDF5 layer.
3252 This example is from nf\_test/ftst\_types2.F.
3258 retval = nf_inq_user_type(ncid, typeids(1), name_in, size_in,
3259 & base_type_in, nfields_in, class_in)
3260 if (retval .ne. nf_noerr) call handle_err(retval)
3263 5.6 Compound Types Introduction
3264 -------------------------------
3266 NetCDF-4 addedpport for compound types, which allow users to
3267 construct a new type - a combination of other types, like a C struct.
3269 Compound types are notpported in classic or 64-bit offset format
3272 To write data in a compound type, first use nf\_def\_compound to create
3273 the type, multiple calls to nf\_insert\_compound to add to the compound
3274 type, and then write data with the appropriate nf\_put\_var1,
3275 nf\_put\_vara, nf\_put\_vars, or nf\_put\_varm call.
3277 To read data written in a compound type, you must know its structure.
3278 Use the NF\_INQ\_COMPOUND functions to learn about the compound type.
3280 In Fortran a character buffer must be used for the compound data. The
3281 user must read the data from within that buffer in the same way that the
3282 C compiler which compiled netCDF would store the structure.
3284 The use of compound types introduces challenges and portability ies
3287 ### 5.6.1 Creating a Compound Type: NF\_DEF\_COMPOUND
3289 Create a compound type. Provide an ncid, a name, and a total size (in
3290 bytes) of one element of the completed compound type.
3292 After calling this function, fill out the type with repeated calls to
3293 NF\_INSERT\_COMPOUND (see [Inserting a Field into a Compound
3294 Type: NF\_INSERT\_COMPOUND](#NF_005fINSERT_005fCOMPOUND)). Call
3295 NF\_INSERT\_COMPOUND once for each field you wish to insert into the
3298 Note that there does not seem to be a way to readch types into
3299 structures in Fortran 90 (and there are no structures in Fortran 77).
3301 Fortran users may use character buffers to read and write compound
3310 INTEGER FUNCTION NF_DEF_COMPOUND(INTEGER NCID, INTEGER SIZE,
3311 CHARACTER*(*) NAME, INTEGER TYPEIDP)
3315 : The groupid where this compound type will be created.
3318 : The size, in bytes, of the compound type.
3321 : The name of the new compound type.
3324 : The typeid of the new type will be placed here.
3336 : That name is in use. Compound type names must be unique in the data
3340 : Name exceeds max length NF\_MAX\_NAME.
3343 : Name contains illegal characters.
3346 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3347 operations can only be performed on files defined with a create mode
3348 which includes flag NF\_NETCDF4. (see
3349 [NF\_OPEN](#NF_005fOPEN)).
3352 : This file was created with the strict netcdf-3 flag, therefore
3353 netcdf-4 operations are not allowed. (see
3354 [NF\_OPEN](#NF_005fOPEN)).
3357 : An error was reported by the HDF5 layer.
3360 : Attempt to write to a read-only file.
3363 : Not in define mode.
3368 This example is from nf\_test/ftst\_types2.F.
3373 C Define a compound type.
3374 retval = nf_def_compound(ncid, cmp_size, type_name,
3376 if (retval .ne. nf_noerr) call handle_err(retval)
3379 ### 5.6.2 Inserting a Field into a Compound Type: NF\_INSERT\_COMPOUND
3381 Insert a named field into a compound type.
3389 INTEGER FUNTION NF_INSERT_COMPOUND(INTEGER TYPEID, CHARACTER*(*) NAME, INTEGER OFFSET,
3390 INTEGER FIELD_TYPEID)
3394 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3398 : The name of the new field.
3401 : Offset in byte from the beginning of the compound type for this
3405 : The type of the field to be inserted.
3417 : That name is in use. Field names must be unique within a compound
3421 : Name exceed max length NF\_MAX\_NAME.
3424 : Name contains illegal characters.
3427 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3428 operations can only be performed on files defined with a create mode
3429 which includes flag NF\_NETCDF4. (see
3430 [NF\_OPEN](#NF_005fOPEN)).
3433 : This file was created with the strict netcdf-3 flag, therefore
3434 netcdf-4 operations are not allowed. (see
3435 [NF\_OPEN](#NF_005fOPEN)).
3438 : An error was reported by the HDF5 layer.
3441 : Not in define mode.
3446 This example is from nf\_test/ftst\_types.F.
3451 C Define a compound type.
3452 retval = nf_def_compound(ncid, WIND_T_SIZE, type_name,
3454 if (retval .ne. nf_noerr) call handle_err(retval)
3455 retval = nf_insert_compound(ncid, wind_typeid, u_name, 0, NF_INT)
3456 if (retval .ne. nf_noerr) call handle_err(retval)
3457 retval = nf_insert_compound(ncid, wind_typeid, v_name, 4, NF_INT)
3458 if (retval .ne. nf_noerr) call handle_err(retval)
3462 ### 5.6.3 Inserting an Array Field into a Compound Type: NF\_INSERT\_ARRAY\_COMPOUND
3464 Insert a named array field into a compound type.
3472 INTEGER FUNCTION NF_INSERT_ARRAY_COMPOUND(INTEGER NCID, INTEGER XTYPE,
3473 CHARACTER*(*) NAME, INTEGER OFFSET, INTEGER FIELD_TYPEID,
3474 INTEGER NDIMS, INTEGER DIM_SIZES)
3478 : The ID of the file that contains the array type and the compound
3482 : The typeid for this compound type, as returned by nf\_def\_compound,
3486 : The name of the new field.
3489 : Offset in byte from the beginning of the compound type for this
3493 : The base type of the array to be inserted.
3496 : The number of dimensions for the array to be inserted.
3499 : An array containing the sizes of each dimension.
3511 : That name is in use. Field names must be unique within a compound
3515 : Name exceed max length NF\_MAX\_NAME.
3518 : Name contains illegal characters.
3521 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3522 operations can only be performed on files defined with a create mode
3523 which includes flag NF\_NETCDF4. (see
3524 [NF\_OPEN](#NF_005fOPEN)).
3527 : This file was created with the strict netcdf-3 flag, therefore
3528 netcdf-4 operations are not allowed. (see
3529 [NF\_OPEN](#NF_005fOPEN)).
3532 : An error was reported by the HDF5 layer.
3535 : Not in define mode.
3538 : Attempt to change type that has already been committed. The first
3539 time the file leaves define mode, all defined types are committed,
3540 and can’t be changed. If you wish to add an array to a compound
3541 type, you must do so before the compound type is committed.
3546 This example is from nf\_test/ftst\_types2.F.
3551 C Define a compound type.
3552 retval = nf_def_compound(ncid, cmp_size, type_name,
3554 if (retval .ne. nf_noerr) call handle_err(retval)
3559 retval = nf_insert_array_compound(ncid, cmp_typeid, ary_name, 0,
3560 & NF_INT, NDIMS, dim_sizes)
3561 if (retval .ne. nf_noerr) call handle_err(retval)
3564 ### 5.6.4 Learn About a Compound Type: NF\_INQ\_COMPOUND
3566 Get the number of fields, length in bytes, and name of a compound type.
3568 In addtion to the NF\_INQ\_COMPOUND function, three additional functions
3569 are provided which get only the name, size, and number of fields.
3577 INTEGER FUNCTION NF_INQ_COMPOUND(INTEGER NCID, INTEGER XTYPE,
3578 CHARACTER*(*) NAME, INTEGER SIZEP, INTEGER NFIELDSP)
3580 INTEGER FUNCTION NF_INQ_COMPOUND_NAME(INTEGER NCID, INTEGER XTYPE,
3583 INTEGER FUNCTION NF_INQ_COMPOUND_SIZE(INTEGER NCID, INTEGER XTYPE,
3586 INTEGER FUNCTION NF_INQ_COMPOUND_NFIELDS(INTEGER NCID, INTEGER XTYPE,
3591 : The ID of any group in the file that contains the compound type.
3594 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3598 : Character array which will get the name of the compound type. It
3599 will have a maximum length of NF\_MAX\_NAME.
3602 : The size of the compound type in bytes will be put here.
3605 : The number of fields in the compound type will be placed here.
3614 : Couldn’t find this ncid.
3617 : Not a netCDF-4/HDF5 file.
3620 : A netCDF-4/HDF5 file, but with CLASSIC\_MODEL. No user defined types
3621 are allowed in the classic model.
3624 : This type not a compound type.
3630 : An error was reported by the HDF5 layer.
3635 This example is from nf\_test/ftst\_types.F.
3640 C Check it differently.
3641 retval = nf_inq_compound(ncid, typeids(1), name_in, size_in,
3643 if (retval .ne. nf_noerr) call handle_err(retval)
3644 if (name_in(1:len(type_name)) .ne. type_name .or.
3645 & size_in .ne. WIND_T_SIZE .or. nfields_in .ne. 2) stop 2
3647 C Check it one piece at a time.
3648 retval = nf_inq_compound_nfields(ncid, typeids(1), nfields_in)
3649 if (retval .ne. nf_noerr) call handle_err(retval)
3650 if (nfields_in .ne. 2) stop 2
3651 retval = nf_inq_compound_size(ncid, typeids(1), size_in)
3652 if (retval .ne. nf_noerr) call handle_err(retval)
3653 if (size_in .ne. WIND_T_SIZE) stop 2
3654 retval = nf_inq_compound_name(ncid, typeids(1), name_in)
3655 if (retval .ne. nf_noerr) call handle_err(retval)
3656 if (name_in(1:len(type_name)) .ne. type_name) stop 2
3659 ### 5.6.5 Learn About a Field of a Compound Type: NF\_INQ\_COMPOUND\_FIELD
3661 Get information about one of the fields of a compound type.
3669 INTEGER FUNCTION NF_INQ_COMPOUND_FIELD(INTEGER NCID, INTEGER XTYPE,
3670 INTEGER FIELDID, CHARACTER*(*) NAME, INTEGER OFFSETP,
3671 INTEGER FIELD_TYPEIDP, INTEGER NDIMSP, INTEGER DIM_SIZESP)
3673 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDNAME(INTEGER TYPEID,
3674 INTEGER FIELDID, CHARACTER*(*) NAME)
3676 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDINDEX(INTEGER TYPEID,
3677 CHARACTER*(*) NAME, INTEGER FIELDIDP)
3679 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDOFFSET(INTEGER TYPEID,
3680 INTEGER FIELDID, INTEGER OFFSETP)
3682 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDTYPE(INTEGER TYPEID,
3683 INTEGER FIELDID, INTEGER FIELD_TYPEIDP)
3685 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDNDIMS(INTEGER NCID,
3686 INTEGER XTYPE, INTEGER FIELDID, INTEGER NDIMSP)
3688 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDDIM_SIZES(INTEGER NCID,
3689 INTEGER XTYPE, INTEGER FIELDID, INTEGER DIM_SIZES)
3693 : The groupid where this compound type exists.
3696 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3700 : A one-based index number specifying a field in the compound type.
3703 : A character array which will get the name of the field. The name
3704 will be NF\_MAX\_NAME characters, at most.
3707 : An integer which will get the offset of the field.
3710 : An integer which will get the typeid of the field.
3713 : An integer which will get the number of dimensions of the field.
3716 : An integer array which will get the dimension sizes of the field.
3728 : An error was reported by the HDF5 layer.
3733 This example is from nf\_test/fst\_types.F.
3738 C Check the first field of the compound type.
3739 retval = nf_inq_compound_field(ncid, typeids(1), 1, name_in,
3740 & offset_in, field_typeid_in, ndims_in, dim_sizes_in)
3741 if (retval .ne. nf_noerr) call handle_err(retval)
3742 if (name_in(1:len(u_name)) .ne. u_name .or. offset_in .ne. 0 .or.
3743 & field_typeid_in .ne. NF_INT .or. ndims_in .ne. 0) stop 2
3744 retval = nf_inq_compound_fieldname(ncid, typeids(1), 1, name_in)
3745 if (retval .ne. nf_noerr) call handle_err(retval)
3746 if (name_in(1:len(u_name)) .ne. u_name) stop 2
3747 retval = nf_inq_compound_fieldoffset(ncid, typeids(1), 1,
3749 if (retval .ne. nf_noerr) call handle_err(retval)
3750 if (offset_in .ne. 0) stop 2
3751 retval = nf_inq_compound_fieldtype(ncid, typeids(1), 1,
3753 if (retval .ne. nf_noerr) call handle_err(retval)
3754 if (field_typeid_in .ne. NF_INT) stop 2
3755 retval = nf_inq_compound_fieldndims(ncid, typeids(1), 1,
3757 if (retval .ne. nf_noerr) call handle_err(retval)
3758 if (ndims_in .ne. 0) stop 2
3761 5.7 Variable Length Array Introduction
3762 --------------------------------------
3764 NetCDF-4 addedpport for a variable length array type. This is not
3765 supported in classic or 64-bit offset files, or in netCDF-4 files which
3766 were created with the NF\_CLASSIC\_MODEL flag.
3768 A variable length array is represented in C as a structure from HDF5,
3769 the nf\_vlen\_t structure. It contains a len member, which contains the
3770 length of that array, and a pointer to the array.
3772 So an array of VLEN in C is an array of nc\_vlen\_t structures. The only
3773 way to handle this in Fortran is with a character buffer sized correctly
3776 The extra access functions NF\_GET\_VLEN\_ELEMENT and
3777 NF\_PUT\_VLEN\_ELEMENT to get and put one VLEN element. (That is, one
3778 array of variable length.) When calling the put, the data are not copied
3779 from the source. When calling the get the data are copied from VLEN
3780 allocated memory, which must still be freed (see below).
3782 VLEN arrays are handled differently with respect to allocation of
3783 memory. Generally, when reading data, it is up to the user to malloc
3784 (andbsequently free) the memory needed to hold the data. It is up to
3785 the user to ere that enough memory is allocated.
3787 With VLENs, this is impossible. The user cannot know the size of an
3788 array of VLEN until after reading the array. Therefore when reading VLEN
3789 arrays, the netCDF library will allocate the memory for the data within
3792 It is up to the user, however, to eventually free this memory. This is
3793 not just a matter of one call to free, with the pointer to the array of
3794 VLENs; each VLEN contains a pointer which must be freed.
3796 Compression is permitted but may not be effective for VLEN data, because
3797 the compression is applied to the nc\_vlen\_t structures, rather than
3800 ### 5.7.1 Define a Variable Length Array (VLEN): NF\_DEF\_VLEN
3802 Use this function to define a variable length array type.
3810 INTEGER FUNCTION NF_DEF_VLEN(INTEGER NCID, CHARACTER*(*) NAME,
3811 INTEGER BASE_TYPEID, INTEGER XTYPEP)
3815 : The ncid of the file to create the VLEN type in.
3818 : A name for the VLEN type.
3821 : The typeid of the base type of the VLEN. For example, for a VLEN of
3822 shorts, the base type is NF\_SHORT. This can be a user defined type.
3825 : The typeid of the new VLEN type will be set here.
3834 : NF\_MAX\_NAME exceeded.
3837 : Name is already in use.
3840 : Attribute or variable name contains illegal characters.
3846 : Group ID part of ncid was invalid.
3857 This example is from nf\_test/ftst\_vars4.F.
3862 C Create the vlen type.
3863 retval = nf_def_vlen(ncid, vlen_type_name, nf_int, vlen_typeid)
3864 if (retval .ne. nf_noerr) call handle_err(retval)
3867 ### 5.7.2 Learning about a Variable Length Array (VLEN) Type: NF\_INQ\_VLEN
3869 Use this type to learn about a vlen.
3877 INTEGER FUNCTION NF_INQ_VLEN(INTEGER NCID, INTEGER XTYPE,
3878 CHARACTER*(*) NAME, INTEGER DATUM_SIZEP, INTEGER
3883 : The ncid of the file that contains the VLEN type.
3886 : The type of the VLEN to inquire about.
3889 : The name of the VLEN type. The name will be NF\_MAX\_NAME characters
3893 : A pointer to a size\_t, this will get the size of one element of
3897 : An integer that will get the type of the VLEN base type. (In other
3898 words, what type is this a VLEN of?)
3907 : Can’t find the typeid.
3913 : Group ID part of ncid was invalid.
3918 This example is from nf\_test/ftst\_vars4.F.
3923 C Use nf_inq_vlen and makere we get the same answers as we did
3924 C with nf_inq_user_type.
3925 retval = nf_inq_vlen(ncid, typeids(1), type_name, base_size,
3927 if (retval .ne. nf_noerr) call handle_err(retval)
3930 ### 5.7.3 Releasing Memory for a Variable Length Array (VLEN) Type: NF\_FREE\_VLEN
3932 When a VLEN is read into user memory from the file, the HDF5 library
3933 performs memory allocations for each of the variable length arrays
3934 contained within the VLEN structure. This memory must be freed by the
3935 user to avoid memory leaks.
3937 This violates the normal netCDF expectation that the user is responsible
3938 for all memory allocation. But, with VLEN arrays, the underlying HDF5
3939 library allocates the memory for the user, and the user is responsible
3940 for deallocating that memory.
3948 INTEGER FUNCTION NF_FREE_VLEN(CHARACTER VL);
3952 : The variable length array structure which is to be freed.
3961 : Can’t find the typeid.
3966 ### 5.7.4 Set a Variable Length Array with NF\_PUT\_VLEN\_ELEMENT
3968 Use this to set the element of the (potentially) n-dimensional array of
3969 VLEN. That is, this sets the data in one variable length array.
3977 INTEGER FUNCTION NF_PUT_VLEN_ELEMENT(INTEGER NCID, INTEGER XTYPE,
3978 CHARACTER*(*) VLEN_ELEMENT, INTEGER LEN, DATA)
3982 : The ncid of the file that contains the VLEN type.
3985 : The type of the VLEN.
3988 : The VLEN element to be set.
3991 : The number of entries in this array.
3994 : The data to be stored. Must match the base type of this VLEN.
4003 : Can’t find the typeid.
4009 : Group ID part of ncid was invalid.
4014 This example is from nf\_test/ftst\_vars4.F.
4019 C Set up the vlen with this helper function, since F77 can't deal
4021 retval = nf_put_vlen_element(ncid, vlen_typeid, vlen,
4023 if (retval .ne. nf_noerr) call handle_err(retval)
4026 ### 5.7.5 Set a Variable Length Array with NF\_GET\_VLEN\_ELEMENT
4028 Use this to set the element of the (potentially) n-dimensional array of
4029 VLEN. That is, this sets the data in one variable length array.
4037 INTEGER FUNCTION NF_GET_VLEN_ELEMENT(INTEGER NCID, INTEGER XTYPE,
4038 CHARACTER*(*) VLEN_ELEMENT, INTEGER LEN, DATA)
4042 : The ncid of the file that contains the VLEN type.
4045 : The type of the VLEN.
4048 : The VLEN element to be set.
4051 : This will be set to the number of entries in this array.
4054 : The data will be copied here. Sufficient storage must be available
4055 or bad things will happen to you.
4064 : Can’t find the typeid.
4070 : Group ID part of ncid was invalid.
4075 This example is from nf\_test/ftst\_vars4.F.
4080 C Read the vlen attribute.
4081 retval = nf_get_att(ncid, NF_GLOBAL, 'att1', vlen_in)
4082 if (retval .ne. nf_noerr) call handle_err(retval)
4084 C Get the data from the vlen we just read.
4085 retval = nf_get_vlen_element(ncid, vlen_typeid, vlen_in,
4086 & vlen_len_in, data1_in)
4087 if (retval .ne. nf_noerr) call handle_err(retval)
4090 5.8 Opaque Type Introduction
4091 ----------------------------
4093 NetCDF-4 addedpport for the opaque type. This is notpported in
4094 classic or 64-bit offset files.
4096 The opaque type is a type which is a collection of objects of a known
4097 size. (And each object is the same size). Nothing is known to netCDF
4098 about the contents of these blobs of data, except their size in bytes,
4099 and the name of the type.
4101 To use an opaque type, first define it with [Creating Opaque Types:
4102 NF\_DEF\_OPAQUE](#NF_005fDEF_005fOPAQUE). If encountering an enum type
4103 in a new data file, use [Learn About an Opaque Type:
4104 NF\_INQ\_OPAQUE](#NF_005fINQ_005fOPAQUE) to learn its name and size.
4106 ### 5.8.1 Creating Opaque Types: NF\_DEF\_OPAQUE
4108 Create an opaque type. Provide a size and a name.
4116 INTEGER FUNCTION NF_DEF_OPAQUE(INTEGER NCID, INTEGER SIZE,
4117 CHARACTER*(*) NAME, INTEGER TYPEIDP)
4121 : The groupid where the type will be created. The type may be used
4122 anywhere in the file, no matter what group it is in.
4125 : The size of each opaque object.
4128 : The name for this type. Must be shorter than NF\_MAX\_NAME.
4131 : Pointer where the new typeid for this type is returned. Use this
4132 typeid when defining variables of this type with [Create a Variable:
4133 `NF_DEF_VAR`](#NF_005fDEF_005fVAR).
4148 : An error was reported by the HDF5 layer.
4153 This example is from nf\_test/ftst\_vars3.F.
4158 C Create the opaque type.
4159 retval = nf_def_opaque(ncid, opaque_size, opaque_type_name,
4161 if (retval .ne. nf_noerr) call handle_err(retval)
4164 ### 5.8.2 Learn About an Opaque Type: NF\_INQ\_OPAQUE
4166 Given a typeid, get the information about an opaque type.
4174 INTEGER FUNCTION NF_INQ_OPAQUE(INTEGER NCID, INTEGER XTYPE,
4175 CHARACTER*(*) NAME, INTEGER SIZEP)
4179 : The ncid for the group containing the opaque type.
4182 : The typeid for this opaque type, as returned by NF\_DEF\_COMPOUND,
4186 : The name of the opaque type will be copied here. It will be
4187 NF\_MAX\_NAME bytes or less.
4190 : The size of the opaque type will be copied here.
4205 : An error was reported by the HDF5 layer.
4210 This example is from nf\_test/ftst\_vars3.F.
4215 C Use nf_inq_opaque and makere we get the same answers as we did
4216 C with nf_inq_user_type.
4217 retval = nf_inq_opaque(ncid, typeids(2), type_name, base_size)
4218 if (retval .ne. nf_noerr) call handle_err(retval)
4221 5.9 Enum Type Introduction
4222 --------------------------
4224 NetCDF-4 addedpport for the enum type. This is notpported in
4225 classic or 64-bit offset files.
4227 ### 5.9.1 Creating a Enum Type: NF\_DEF\_ENUM
4229 Create an enum type. Provide an ncid, a name, and a base integer type.
4231 After calling this function, fill out the type with repeated calls to
4232 NF\_INSERT\_ENUM (see [Inserting a Field into a Enum Type:
4233 NF\_INSERT\_ENUM](#NF_005fINSERT_005fENUM)). Call NF\_INSERT\_ENUM once
4234 for each value you wish to make part of the enumeration.
4242 INTEGER FUNCTION NF_DEF_ENUM(INTEGER NCID, INTEGER BASE_TYPEID,
4243 CHARACTER*(*) NAME, INTEGER TYPEIDP)
4247 : The groupid where this compound type will be created.
4250 : The base integer type for this enum. Must be one of: NF\_BYTE,
4251 NF\_UBYTE, NF\_SHORT, NF\_USHORT, NF\_INT, NF\_UINT, NF\_INT64,
4255 : The name of the new enum type.
4258 : The typeid of the new type will be placed here.
4270 : That name is in use. Compound type names must be unique in the data
4274 : Name exceeds max length NF\_MAX\_NAME.
4277 : Name contains illegal characters.
4280 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
4281 operations can only be performed on files defined with a create mode
4282 which includes flag NF\_NETCDF4. (see
4283 [NF\_OPEN](#NF_005fOPEN)).
4286 : This file was created with the strict netcdf-3 flag, therefore
4287 netcdf-4 operations are not allowed. (see
4288 [NF\_OPEN](#NF_005fOPEN)).
4291 : An error was reported by the HDF5 layer.
4294 : Attempt to write to a read-only file.
4297 : Not in define mode.
4299 This example is from nf\_test/ftst\_vars3.F.
4304 C Create the enum type.
4305 retval = nf_def_enum(ncid, NF_INT, enum_type_name, enum_typeid)
4306 if (retval .ne. nf_noerr) call handle_err(retval)
4309 ### 5.9.2 Inserting a Field into a Enum Type: NF\_INSERT\_ENUM
4311 Insert a named member into a enum type.
4319 INTEGER FUNCTION NF_INSERT_ENUM(INTEGER NCID, INTEGER XTYPE,
4320 CHARACTER IDENTIFIER, INTEGER VALUE)
4324 : The ncid of the group which contains the type.
4327 : The typeid for this enum type, as returned by nf\_def\_enum, or
4331 : The identifier of the new member.
4334 : The value that is to be associated with this member.
4346 : That name is in use. Field names must be unique within a enum type.
4349 : Name exceed max length NF\_MAX\_NAME.
4352 : Name contains illegal characters.
4355 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
4356 operations can only be performed on files defined with a create mode
4357 which includes flag NF\_NETCDF4. (see
4358 [NF\_OPEN](#NF_005fOPEN)).
4361 : This file was created with the strict netcdf-3 flag, therefore
4362 netcdf-4 operations are not allowed. (see
4363 [NF\_OPEN](#NF_005fOPEN)).
4366 : An error was reported by the HDF5 layer.
4369 : Not in define mode.
4374 This example is from nf\_test/ftst\_vars3.F.
4381 retval = nf_insert_enum(ncid, enum_typeid, zero_name, zero)
4382 if (retval .ne. nf_noerr) call handle_err(retval)
4383 retval = nf_insert_enum(ncid, enum_typeid, one_name, one)
4384 if (retval .ne. nf_noerr) call handle_err(retval)
4387 ### 5.9.3 Learn About a Enum Type: NF\_INQ\_ENUM
4389 Get information about a user-defined enumeration type.
4397 INTEGER FUNCTION NF_INQ_ENUM(INTEGER NCID, INTEGER XTYPE,
4398 CHARACTER*(*) NAME, INTEGER BASE_NF_TYPE, INTEGER BASE_SIZE,
4399 INTEGER NUM_MEMBERS)
4403 : The group ID of the group which holds the enum type.
4406 : The typeid for this enum type, as returned by NF\_DEF\_ENUM, or
4410 : Character array which will get the name. It will have a maximum
4411 length of NF\_MAX\_NAME.
4414 : An integer which will get the base integer type of this enum.
4417 : An integer which will get the size (in bytes) of the base integer
4421 : An integer which will get the number of members defined for this
4434 : An error was reported by the HDF5 layer.
4439 In this example from nf\_test/ftst\_vars3.F, an enum type is created and
4445 retval = nf_inq_enum(ncid, typeids(1), type_name, base_type,
4446 & base_size, num_members)
4447 if (retval .ne. nf_noerr) call handle_err(retval)
4448 if (base_type .ne. NF_INT .or. num_members .ne. 2) stop 2
4451 ### 5.9.4 Learn the Name of a Enum Type: nf\_inq\_enum\_member
4453 Get information about a member of an enum type.
4461 INTEGER FUNCTION NF_INQ_ENUM_MEMBER(INTEGER NCID, INTEGER XTYPE,
4462 INTEGER IDX, CHARACTER*(*) NAME, INTEGER VALUE)
4466 : The groupid where this enum type exists.
4469 : The typeid for this enum type.
4472 : The one-based index number for the member of interest.
4475 : A character array which will get the name of the member. It will
4476 have a maximum length of NF\_MAX\_NAME.
4479 : An integer that will get the value associated with this member.
4491 : An error was reported by the HDF5 layer.
4496 This example is from nf\_test/ftst\_vars3.F:
4501 C Check the members of the enum type.
4502 retval = nf_inq_enum_member(ncid, typeids(1), 1, member_name,
4504 if (retval .ne. nf_noerr) call handle_err(retval)
4505 if (member_name(1:len(zero_name)) .ne. zero_name .or.
4506 & member_value .ne. 0) stop 2
4507 retval = nf_inq_enum_member(ncid, typeids(1), 2, member_name,
4509 if (retval .ne. nf_noerr) call handle_err(retval)
4510 if (member_name(1:len(one_name)) .ne. one_name .or.
4511 & member_value .ne. 1) stop 2
4514 ### 5.9.5 Learn the Name of a Enum Type: NF\_INQ\_ENUM\_IDENT
4516 Get the name which is associated with an enum member value.
4518 This is similar to NF\_INQ\_ENUM\_MEMBER, but instead of using the index
4519 of the member, you use the value of the member.
4527 INTEGER FUNCTION NF_INQ_ENUM_IDENT(INTEGER NCID, INTEGER XTYPE,
4528 INTEGER VALUE, CHARACTER*(*) IDENTIFIER)
4532 : The groupid where this enum type exists.
4535 : The typeid for this enum type.
4538 : The value for which an identifier is sought.
4541 : A character array that will get the identifier. It will have a
4542 maximum length of NF\_MAX\_NAME.
4551 : Bad type id, or not an enum type.
4554 : An error was reported by the HDF5 layer.
4557 : The value was not found in the enum.
4562 In this example from nf\_test/ftst\_vars3.F, the values for 0 and 1 are
4568 retval = nf_inq_enum_ident(ncid, typeids(1), 0, member_name)
4569 if (retval .ne. nf_noerr) call handle_err(retval)
4570 if (member_name(1:len(zero_name)) .ne. zero_name) stop 2
4571 retval = nf_inq_enum_ident(ncid, typeids(1), 1, member_name)
4572 if (retval .ne. nf_noerr) call handle_err(retval)
4573 if (member_name(1:len(one_name)) .ne. one_name) stop 2
4579 6.1 Variables Introduction
4580 --------------------------
4582 Variables for a netCDF dataset are defined when the dataset is created,
4583 while the netCDF dataset is in define mode. Other variables may be added
4584 later by reentering define mode. A netCDF variable has a name, a type,
4585 and a shape, which are specified when it is defined. A variable may also
4586 have values, which are established later in data mode.
4588 Ordinarily, the name, type, and shape are fixed when the variable is
4589 first defined. The name may be changed, but the type and shape of a
4590 variable cannot be changed. However, a variable defined in terms of the
4591 unlimited dimension can grow without bound in that dimension.
4593 A netCDF variable in an open netCDF dataset is referred to by a small
4594 integer called a variable ID.
4596 Variable IDs reflect the order in which variables were defined within a
4597 netCDF dataset. Variable IDs are 1, 2, 3,..., in the order in which the
4598 variables were defined. A function is available for getting the variable
4599 ID from the variable name and vice-versa.
4601 Attributes (see [Attributes](#Attributes)) may be associated with a
4602 variable to specifych properties as units.
4604 Operationspported on variables are:
4606 - Create a variable, given its name, data type, and shape.
4607 - Get a variable ID from its name.
4608 - Get a variable’s name, data type, shape, and number of attributes
4610 - Put a data value into a variable, given variable ID, indices, and
4612 - Put an array of values into a variable, given variable ID, corner
4613 indices, edge lengths, and a block of values.
4614 - Put absampled or mapped array of values into a variable,
4615 given variable ID, corner indices, edge lengths, stride vector,
4616 index mapping vector, and a block of values.
4617 - Get a data value from a variable, given variable ID and indices.
4618 - Get an array of values from a variable, given variable ID, corner
4619 indices, and edge lengths.
4620 - Get absampled or mapped array of values from a variable,
4621 given variable ID, corner indices, edge lengths, stride vector, and
4622 index mapping vector.
4623 - Rename a variable.
4626 6.2 Language Types Corresponding to netCDF external data types
4627 --------------------------------------------------------------
4629 The following table gives the netCDF external data types and the
4630 corresponding type constants for defining variables in the FORTRAN
4633 -------- ---------------------- ------
4634 Type FORTRAN API Mnemonic Bits
4640 double NF\_DOUBLE 64
4641 -------- ---------------------- ------
4643 The first column gives the netCDF external data type, which is the same
4644 as the CDL data type. The next column gives the corresponding FORTRAN
4645 parameter for use in netCDF functions (the parameters are defined in the
4646 netCDF FORTRAN include-file netcdf.inc). The last column gives the
4647 number of bits used in the external representation of values of the
4650 Note that there are no netCDF types corresponding to 64-bit integers or
4651 to characters wider than 8 bits in the current version of the netCDF
4654 6.3 Create a Variable: `NF_DEF_VAR`
4655 -----------------------------------
4657 The function NF\_DEF\_VAR adds a new variable to an open netCDF dataset
4658 in define mode. It returns (as an argument) a variable ID, given the
4659 netCDF ID, the variable name, the variable type, the number of
4660 dimensions, and a list of the dimension IDs.
4668 INTEGER FUNCTION NF_DEF_VAR(INTEGER NCID, CHARACTER*(*) NAME,
4669 INTEGER XTYPE, INTEGER NVDIMS,
4670 INTEGER VDIMS(*), INTEGER varid)
4674 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4680 : One of the set of predefined netCDF external data types. The type of
4681 this parameter, NF\_TYPE, is defined in the netCDF header file. The
4682 valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
4683 NF\_INT, NF\_FLOAT, and NF\_DOUBLE. If the file is a NetCDF-4/HDF5
4684 file, the additional types NF\_UBYTE, NF\_USHORT, NF\_UINT,
4685 NF\_INT64, NF\_UINT64, and NF\_STRING may be used, as well as a user
4689 : Number of dimensions for the variable. For example, 2 specifies a
4690 matrix, 1 specifies a vector, and 0 means the variable is a scalar
4691 with no dimensions. Must not be negative or greater than the
4692 predefined constant NF\_MAX\_VAR\_DIMS.
4695 : Vector of ndims dimension IDs corresponding to the variable
4696 dimensions. If the ID of the unlimited dimension is included, it
4697 must be first. This argument is ignored if ndims is 0. For expanded
4698 model netCDF4/HDF5 files, there may be any number of unlimited
4699 dimensions, and they may be used in any element of the dimids array.
4702 : Returned variable ID.
4707 NF\_DEF\_VAR returns the value NF\_NOERR if no errors occurred.
4708 Otherwise, the returned status indicates an error. Possible causes of
4711 - The netCDF dataset is not in define mode.
4712 - The specified variable name is the name of another existing
4714 - The specified type is not a valid netCDF type.
4715 - The specified number of dimensions is negative or more than the
4716 constant NF\_MAX\_VAR\_DIMS, the maximum number of dimensions
4717 permitted for a netCDF variable.
4718 - One or more of the dimension IDs in the list of dimensions is not a
4719 valid dimension ID for the netCDF dataset.
4720 - The number of variables would exceed the constant NF\_MAX\_VARS, the
4721 maximum number of variables permitted in a netCDF dataset.
4722 - The specified netCDF ID does not refer to an open netCDF dataset.
4727 Here is an example using NF\_DEF\_VAR to create a variable named rh of
4728 type double with three dimensions, time, lat, and lon in a new netCDF
4729 dataset named foo.nc:
4734 INCLUDE 'netcdf.inc'
4736 INTEGER STATUS, NCID
4737 INTEGER LATDIM, LONDIM, TIMDIM ! dimension IDs
4738 INTEGER RHID ! variable ID
4739 INTEGER RHDIMS(3) ! variable shape
4741 STATUS = NF_CREATE ('foo.nc', NF_NOCLOBBER, NCID)
4742 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4745 STATUS = NF_DEF_DIM(NCID, 'lat', 5, LATDIM)
4746 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4747 STATUS = NF_DEF_DIM(NCID, 'lon', 10, LONDIM)
4748 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4749 STATUS = NF_DEF_DIM(NCID, 'time', NF_UNLIMITED, TIMDIM)
4750 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4756 STATUS = NF_DEF_VAR (NCID, 'rh', NF_DOUBLE, 3, RHDIMS, RHID)
4757 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4760 6.4 Define Chunking Parameters for a Variable: `NF_DEF_VAR_CHUNKING`
4761 --------------------------------------------------------------------
4763 The function NF\_DEF\_VAR\_CHUNKING sets the storage parameters for a
4764 variable in a netCDF-4 file. It can set the chunk sizes to get chunked
4765 storage, or it can set the contiguous flag to get contiguous storage.
4767 Variables that make use of one or more unlimited dimensions,
4768 compression, or checms must use chunking. Such variables are created
4769 with default chunk sizes of 1 for each unlimited dimension and the
4770 dimension length for other dimensions, except that if the rlting
4771 chunks are too large, the default chunk sizes for non-record dimensions
4774 The total size of a chunk must be less than 4 GiB. That is, the product
4775 of all chunksizes and the size of the data (or the size of nc\_vlen\_t
4776 for VLEN types) must be less than 4 GiB.
4778 This function may only be called after the variable is defined, but
4779 before nc\_enddef is called. Once the chunking parameters are set for a
4780 variable, they cannot be changed. This function can be used to change
4781 the default chunking for record, compressed, or checmmed variables
4782 before nc\_enddef is called.
4784 Note that you cannot set chunking for scalar variables. Only non-scalar
4785 variables can have chunking.
4793 NF_DEF_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES)
4797 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4803 : If NF\_CONTIGUOUS, then contiguous storage is used for this
4804 variable. Variables with compression, shuffle filter, checms, or
4805 one or more unlimited dimensions cannot use contiguous storage. If
4806 contiguous storage is turned on, the chunksizes parameter is
4809 If NF\_CHUNKED, then chunked storage is used for this variable.
4810 Chunk sizes may be specified with the chunksizes parameter. Default
4811 sizes will be used if chunking is required and this function is not
4814 By default contiguous storage is used for fix-sized variables when
4815 conpression, chunking, checms, or endianness control are not
4819 : An array of chunk sizes. The array must have the one chunksize for
4820 each dimension in the variable. If contiguous storage is used, then
4821 the chunksizes parameter is ignored.
4826 NF\_DEF\_VAR\_CHUNKING returns the value NF\_NOERR if no errors
4827 occurred. Otherwise, the returned status indicates an error.
4829 Possible return codes include:
4838 : Invalid input. This can occur when the user attempts to set
4839 contiguous storage for a variable with compression or checms, or
4840 one or more unlimited dimensions.
4843 : Not a netCDF-4 file.
4846 : Can’t find this variable.
4849 : This variable has already been thebject of a NF\_ENDDEF call. In
4850 netCDF-4 files NF\_ENDDEF will be called automatically for any data
4851 read or write. Once enddef has been called, it is impossible to set
4852 the chunking for a variable.
4855 : Not in define mode. This is returned for netCDF classic or 64-bit
4856 offset files, or for netCDF-4 files, when they were been created
4857 with NF\_STRICT\_NC3 flag. (see
4858 [NF\_CREATE](#NF_005fCREATE)).
4861 : Trying to create a var some place other than the root group in a
4862 netCDF file with NF\_STRICT\_NC3 turned on.
4867 In this example from nf\_test/ftst\_vars.F, a file is created, two
4868 dimensions and a variable are defined, and the chunksizes of the data
4869 are set to the size of the data (that is, data will be written in one
4875 C Create the netCDF file.
4876 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
4877 if (retval .ne. nf_noerr) call handle_err(retval)
4879 C Define the dimensions.
4880 retval = nf_def_dim(ncid, "x", NX, x_dimid)
4881 if (retval .ne. nf_noerr) call handle_err(retval)
4882 retval = nf_def_dim(ncid, "y", NY, y_dimid)
4883 if (retval .ne. nf_noerr) call handle_err(retval)
4885 C Define the variable.
4888 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
4889 if (retval .ne. nf_noerr) call handle_err(retval)
4894 retval = NF_DEF_VAR_chunking(ncid, varid, NF_CHUNKED, chunks)
4895 if (retval .ne. nf_noerr) call handle_err(retval)
4898 6.5 Learn About Chunking Parameters for a Variable: `NF_INQ_VAR_CHUNKING`
4899 -------------------------------------------------------------------------
4901 The function NF\_INQ\_VAR\_CHUNKING returns the chunking settings for a
4902 variable in a netCDF-4 file.
4910 NF_INQ_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES);
4914 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4920 : On return, set to NF\_CONTIGUOUS if this variable uses contiguous
4921 storage, NF\_CHUNKED if it uses chunked storage.
4924 : An array of chunk sizes. The length of CHUNKSIZES must be the same
4925 as the number of dimensions of the variable.
4930 NF\_INQ\_VAR\_CHUNKING returns the value NF\_NOERR if no errors
4931 occurred. Otherwise, the returned status indicates an error.
4933 Possible return codes include:
4942 : Not a netCDF-4 file.
4945 : Can’t find this variable.
4950 In this example from nf\_test/ftst\_vars.F, a variable with chunked
4951 storage is checked to ere that the chunksizes are set to expected
4957 C Is everything set that ispposed to be?
4958 retval = nf_inq_var_chunking(ncid, varid, storage, chunks_in)
4959 if (retval .ne. nf_noerr) call handle_err(retval)
4960 if (storage .ne. NF_CHUNKED) stop 2
4961 if (chunks(1) .ne. chunks_in(1)) stop 2
4962 if (chunks(2) .ne. chunks_in(2)) stop 2
4965 6.6 Set HDF5 Chunk Cache for a Variable: NF\_SET\_VAR\_CHUNK\_CACHE
4966 -------------------------------------------------------------------
4968 This function changes the chunk cache settings for a variable. The
4969 change in cache size happens immediately. This is a property of the open
4970 file - it does not persist the next time you open the file.
4972 For more information, see the documentation for the H5Pset\_cache()
4973 function in the HDF5 library at the HDF5 website:
4974 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
4982 NF_SET_VAR_CHUNK_CACHE(INTEGER NCID, INTEGER VARID, INTEGER SIZE, INTEGER NELEMS,
4983 INTEGER PREEMPTION);
4987 : NetCDF ID, from a previous call to nc\_open or nc\_create.
4993 : The total size of the raw data chunk cache, in megabytes. This
4994 should be big enough to hold multiple chunks of data. (Note that the
4995 C API uses bytes, but the Fortran APIs uses megabytes to avoid
4996 numbers that can’t fit in 4-byte integers.)
4999 : The number of chunk slots in the raw data chunk cache hash table.
5000 This should be a prime number larger than the number of chunks that
5001 will be in the cache.
5004 : The preemption value must be between 0 and 100 inclusive and
5005 indicates the degreee to which chunks that have been fully read are
5006 favored for kicking out of the chunk cache, when needed. A value of
5007 zero means fully read chunks are treated no differently than other
5008 chunks (the preemption is strictly Least Recently Used) while a
5009 value of 100 means fully read chunks are always preempted before
5010 other chunks. (The C API uses a float between 0 and 1 for this
5020 : Preemption must be between zero and 100 (inclusive).
5025 This example is from nf\_test/ftst\_vars2.F:
5030 include 'netcdf.inc'
5032 C These will be used to set the per-variable chunk cache.
5033 integer CACHE_SIZE, CACHE_NELEMS, CACHE_PREEMPTION
5034 parameter (CACHE_SIZE = 8, CACHE_NELEMS = 571)
5035 parameter (CACHE_PREEMPTION = 42)
5037 C Set variable caches.
5038 retval = nf_set_var_chunk_cache(ncid, varid(i), CACHE_SIZE,
5039 & CACHE_NELEMS, CACHE_PREEMPTION)
5040 if (retval .ne. nf_noerr) call handle_err(retval)
5043 6.7 Get the HDF5 Chunk Cache Settings for a variable: NF\_GET\_VAR\_CHUNK\_CACHE
5044 --------------------------------------------------------------------------------
5046 This function gets the current chunk cache settings for a variable in a
5049 For more information, see the documentation for the H5Pget\_cache()
5050 function in the HDF5 library at the HDF5 website:
5051 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
5059 INTEGER NF_GET_VAR_CHUNK_CACHE(INTEGER NCID, INTEGER VARID, INTEGER SIZE, INTEGER NELEMS,
5060 INTEGER PREEMPTION);
5064 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5070 : The total size of the raw data chunk cache, in megabytes, will be
5074 : The number of chunk slots in the raw data chunk cache hash table
5078 : The preemption will be put here. The preemtion value is between 0
5079 and 100 inclusive and indicates how much chunks that have been fully
5080 read are favored for preemption. A value of zero means fully read
5081 chunks are treated no differently than other chunks (the preemption
5082 is strictly LRU) while a value of 100 means fully read chunks are
5083 always preempted before other chunks.
5094 This example is from nf\_test/ftst\_vars2.c:
5099 include 'netcdf.inc'
5101 C These will be used to set the per-variable chunk cache.
5102 integer CACHE_SIZE, CACHE_NELEMS, CACHE_PREEMPTION
5103 parameter (CACHE_SIZE = 8, CACHE_NELEMS = 571)
5104 parameter (CACHE_PREEMPTION = 42)
5106 C These will be used to check the setting of the per-variable chunk
5108 integer cache_size_in, cache_nelems_in, cache_preemption_in
5111 retval = nf_get_var_chunk_cache(ncid, varid(i), cache_size_in,
5112 & cache_nelems_in, cache_preemption_in)
5113 if (retval .ne. nf_noerr) call handle_err(retval)
5114 if (cache_size_in .ne. CACHE_SIZE .or. cache_nelems_in .ne.
5115 & CACHE_NELEMS .or. cache_preemption .ne. CACHE_PREEMPTION)
5119 6.8 Define Fill Parameters for a Variable: `nf_def_var_fill`
5120 ------------------------------------------------------------
5122 The function NF\_DEF\_VAR\_FILL sets the fill parameters for a variable
5125 This function must be called after the variable is defined, but before
5126 NF\_ENDDEF is called.
5134 NF_DEF_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE);
5138 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5144 : Set to non-zero value to set no\_fill mode on a variable. When this
5145 mode is on, fill values will not be written for the variable. This
5146 is helpful in high performance applications. For netCDF-4/HDF5 files
5147 (whether classic model or not), this may only be changed after the
5148 variable is defined, but before it is committed to disk (i.e. before
5149 the first NF\_ENDDEF after the NF\_DEF\_VAR.) For classic and 64-bit
5150 offset file, the no\_fill mode may be turned on and off at any time.
5153 : A value which will be used as the fill value for the variable. Must
5154 be the same type as the variable. This will be written to a
5155 \_FillValue attribute, created for this purpose. If NULL, this
5156 argument will be ignored.
5168 : Not a netCDF-4 file.
5171 : Can’t find this variable.
5174 : This variable has already been thebject of a NF\_ENDDEF call. In
5175 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5176 read or write. Once enddef has been called, it is impossible to set
5177 the fill for a variable.
5180 : Not in define mode. This is returned for netCDF classic or 64-bit
5181 offset files, or for netCDF-4 files, when they were been created
5182 with NF\_STRICT\_NC3 flag. (see
5183 [NF\_CREATE](#NF_005fCREATE)).
5186 : Attempt to create object in read-only file.
5191 6.9 Learn About Fill Parameters for a Variable: `NF_INQ_VAR_FILL`
5192 -----------------------------------------------------------------
5194 The function NF\_INQ\_VAR\_FILL returns the fill settings for a variable
5203 NF_INQ_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE)
5207 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5213 : An integer which will get a 1 if no\_fill mode is set for this
5214 variable, and a zero if it is not set
5217 : This will get the fill value for this variable. This parameter will
5218 be ignored if it is NULL.
5230 : Not a netCDF-4 file.
5233 : Can’t find this variable.
5238 6.10 Define Compression Parameters for a Variable: `NF_DEF_VAR_DEFLATE`
5239 -----------------------------------------------------------------------
5241 The function NF\_DEF\_VAR\_DEFLATE sets the deflate parameters for a
5242 variable in a netCDF-4 file.
5244 When using parallel I/O for writing data, deflate cannot be used. This
5245 is because the compression makes it impossible for the HDF5 library to
5246 exactly map the data to disk location.
5248 (Deflated data can be read with parallel I/O).
5250 NF\_DEF\_VAR\_DEFLATE must be called after the variable is defined, but
5251 before NF\_ENDDEF is called.
5259 NF_DEF_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE, INTEGER DEFLATE,
5260 INTEGER DEFLATE_LEVEL);
5264 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5270 : If non-zero, turn on the shuffle filter.
5273 : If non-zero, turn on the deflate filter at the level specified by
5274 the deflate\_level parameter.
5277 : Must be between 0 (no deflate, the default) and 9 (slowest, but
5280 If set to zero, no deflation takes place and the def\_var\_deflate
5281 call is ignored. This is slightly different from HDF5 handing of 0
5282 deflate, which turns on the filter but makes only trivial changes to
5285 Informal testing at NetCDF World Headquartersggests that there is
5286 little to be gained (with the limited set of test data used here),
5287 in setting the deflate level above 2 or 3.
5292 NF\_DEF\_VAR\_DEFLATE returns the value NF\_NOERR if no errors occurred.
5293 Otherwise, the returned status indicates an error.
5295 Possible return codes include:
5304 : Not a netCDF-4 file.
5307 : Can’t find this variable.
5310 : This variable has already been thebject of a NF\_ENDDEF call. In
5311 netCDF-4 files NF\_ENDDEF will be called automatically for any data
5312 read or write. Once enddef has been called, it is impossible to set
5313 the deflate for a variable.
5316 : Not in define mode. This is returned for netCDF classic or 64-bit
5317 offset files, or for netCDF-4 files, when they were been created
5318 with NF\_STRICT\_NC3 flag. (see
5319 [NF\_CREATE](#NF_005fCREATE)).
5322 : Attempt to create object in read-only file.
5325 : Invalid deflate\_level. The deflate level must be between 0 and 9,
5331 In this example from nf\_test/ftst\_vars.F, a file is created with two
5332 dimensions and one variable. Chunking, deflate, and the fletcher32
5333 filter are turned on. The deflate level is set to 4 below.
5338 C Create the netCDF file.
5339 retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5340 if (retval .ne. nf_noerr) call handle_err(retval)
5342 C Define the dimensions.
5343 retval = nf_def_dim(ncid, "x", NX, x_dimid)
5344 if (retval .ne. nf_noerr) call handle_err(retval)
5345 retval = nf_def_dim(ncid, "y", NY, y_dimid)
5346 if (retval .ne. nf_noerr) call handle_err(retval)
5348 C Define the variable.
5351 retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5352 if (retval .ne. nf_noerr) call handle_err(retval)
5357 retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
5358 if (retval .ne. nf_noerr) call handle_err(retval)
5360 C Turn on deflate compression, fletcher32 checm.
5361 retval = NF_DEF_VAR_deflate(ncid, varid, 0, 1, 4)
5362 if (retval .ne. nf_noerr) call handle_err(retval)
5363 retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
5364 if (retval .ne. nf_noerr) call handle_err(retval)
5367 6.11 Learn About Deflate Parameters for a Variable: `NF_INQ_VAR_DEFLATE`
5368 ------------------------------------------------------------------------
5370 The function NF\_INQ\_VAR\_DEFLATE returns the deflate settings for a
5371 variable in a netCDF-4 file.
5373 It is not necessary to know the deflate settings to read the variable.
5374 (Deflate is completely transparent to readers of the data).
5382 NF_INQ_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE,
5383 INTEGER DEFLATE, INTEGER DEFLATE_LEVEL);
5387 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5393 : NF\_INQ\_VAR\_DEFLATE will set this to a 1 if the shuffle filter is
5394 turned on for this variable, and a 0 otherwise.
5397 : NF\_INQ\_VAR\_DEFLATE will set this to a 1 if the deflate filter is
5398 turned on for this variable, and a 0 otherwise.
5401 : NF\_INQ\_VAR\_DEFLATE function will write the deflate\_level here,
5402 if deflate is in use.
5407 NF\_INQ\_VAR\_DEFLATE returns the value NF\_NOERR if no errors occurred.
5408 Otherwise, the returned status indicates an error.
5410 Possible return codes include:
5419 : Not a netCDF-4 file.
5422 : Can’t find this variable.
5427 In this example code from nf\_test/ftst\_vars.F, a file with a variable
5428 using deflate is opened, and the deflate level checked.
5433 C Is everything set that ispposed to be?
5434 retval = nf_inq_var_deflate(ncid, varid, shuffle, deflate,
5436 if (retval .ne. nf_noerr) call handle_err(retval)
5437 if (shuffle .ne. 0 .or. deflate .ne. 1 .or.
5438 + deflate_level .ne. 4) stop 2
5441 6.12 Learn About Szip Parameters for a Variable: `NF_INQ_VAR_SZIP`
5442 ------------------------------------------------------------------
5444 The function NF\_INQ\_VAR\_SZIP returns the szip settings for a variable
5447 It is not necessary to know the szip settings to read the variable.
5448 (Szip is completely transparent to readers of the data).
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 Get a Variable ID from Its Name: NF\_INQ\_VARID
5827 ----------------------------------------------------
5829 The function NF\_INQ\_VARID returns the ID of a netCDF variable, given
5838 INTEGER FUNCTION NF_INQ_VARID(INTEGER NCID, CHARACTER*(*) NAME,
5843 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5846 : Variable name for which ID is desired.
5849 : Returned variable ID.
5854 NF\_INQ\_VARID returns the value NF\_NOERR if no errors occurred.
5855 Otherwise, the returned status indicates an error. Possible causes of
5858 - The specified variable name is not a valid name for a variable in
5859 the specified netCDF dataset.
5860 - The specified netCDF ID does not refer to an open netCDF dataset.
5865 Here is an example using NF\_INQ\_VARID to find out the ID of a variable
5866 named rh in an existing netCDF dataset named foo.nc:
5871 INCLUDE 'netcdf.inc'
5873 INTEGER STATUS, NCID, RHID
5875 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
5876 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5878 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
5879 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5883 6.18 Get Information about a Variable from Its ID: NF\_INQ\_VAR family
5884 ----------------------------------------------------------------------
5886 A family of functions that returns information about a netCDF variable,
5887 given its ID. Information about a variable includes its name, type,
5888 number of dimensions, a list of dimension IDs describing the shape of
5889 the variable, and the number of variable attributes that have been
5890 assigned to the variable.
5892 The function NF\_INQ\_VAR returns all the information about a netCDF
5893 variable, given its ID. The other functions each return just one item of
5894 information about a variable.
5896 These other functions include NF\_INQ\_VARNAME, NF\_INQ\_VARTYPE,
5897 NF\_INQ\_VARNDIMS, NF\_INQ\_VARDIMID, and NF\_INQ\_VARNATTS.
5905 INTEGER FUNCTION NF_INQ_VAR (INTEGER NCID, INTEGER VARID,
5906 CHARACTER*(*) name, INTEGER xtype,
5907 INTEGER ndims, INTEGER dimids(*),
5909 INTEGER FUNCTION NF_INQ_VARNAME (INTEGER NCID, INTEGER VARID,
5911 INTEGER FUNCTION NF_INQ_VARTYPE (INTEGER NCID, INTEGER VARID,
5913 INTEGER FUNCTION NF_INQ_VARNDIMS (INTEGER NCID, INTEGER VARID,
5915 INTEGER FUNCTION NF_INQ_VARDIMID (INTEGER NCID, INTEGER VARID,
5917 INTEGER FUNCTION NF_INQ_VARNATTS (INTEGER NCID, INTEGER VARID,
5922 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5928 : Returned variable name. The caller must allocate space for the
5929 returned name. The maximum possible length, in characters, of a
5930 variable name is given by the predefined constant NF\_MAX\_NAME.
5933 : Returned variable type, one of the set of predefined netCDF external
5934 data types. The type of this parameter, NF\_TYPE, is defined in the
5935 netCDF header file. The valid netCDF external data types are
5936 NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, AND NF\_DOUBLE.
5939 : Returned number of dimensions the variable was defined as using. For
5940 example, 2 indicates a matrix, 1 indicates a vector, and 0 means the
5941 variable is a scalar with no dimensions.
5944 : Returned vector of \*ndimsp dimension IDs corresponding to the
5945 variable dimensions. The caller must allocate enough space for a
5946 vector of at least \*ndimsp integers to be returned. The maximum
5947 possible number of dimensions for a variable is given by the
5948 predefined constant NF\_MAX\_VAR\_DIMS.
5951 : Returned number of variable attributes assigned to this variable.
5953 These functions return the value NF\_NOERR if no errors occurred.
5954 Otherwise, the returned status indicates an error. Possible causes of
5957 - The variable ID is invalid for the specified netCDF dataset.
5958 - The specified netCDF ID does not refer to an open netCDF dataset.
5963 Here is an example using NF\_INQ\_VAR to find out about a variable named
5964 rh in an existing netCDF dataset named foo.nc:
5969 INCLUDE 'netcdf.inc'
5971 INTEGER STATUS, NCID
5972 INTEGER RHID ! variable ID
5973 CHARACTER*31 RHNAME ! variable name
5974 INTEGER RHTYPE ! variable type
5975 INTEGER RHN ! number of dimensions
5976 INTEGER RHDIMS(NF_MAX_VAR_DIMS) ! variable shape
5977 INTEGER RHNATT ! number of attributes
5979 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
5980 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5982 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
5983 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5984 STATUS = NF_INQ_VAR (NCID, RHID, RHNAME, RHTYPE, RHN, RHDIMS, RHNATT)
5985 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5988 6.19 Write a Single Data Value: NF\_PUT\_VAR1\_ type
5989 ----------------------------------------------------
5991 The functions NF\_PUT\_VAR1\_type (for various types) put a single data
5992 value of the specified type into a variable of an open netCDF dataset
5993 that is in data mode. Inputs are the netCDF ID, the variable ID, an
5994 index that specifies which value to add or alter, and the data value.
5995 The value is converted to the external data type of the variable, if
6004 INTEGER FUNCTION NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6005 INTEGER INDEX(*), CHARACTER CHVAL)
6006 INTEGER FUNCTION NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6007 INTEGER INDEX(*), INTEGER*1 I1VAL)
6008 INTEGER FUNCTION NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6009 INTEGER INDEX(*), INTEGER*2 I2VAL)
6010 INTEGER FUNCTION NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
6011 INTEGER INDEX(*), INTEGER IVAL)
6012 INTEGER FUNCTION NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6013 INTEGER INDEX(*), REAL RVAL)
6014 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6015 INTEGER INDEX(*), DOUBLE DVAL)
6016 INTEGER FUNCTION NF_PUT_VAR1(INTEGER NCID, INTEGER VARID,
6017 INTEGER INDEX(*), *)
6021 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6027 : The index of the data value to be written. The indices are relative
6028 to 1, so for example, the first data value of a two-dimensional
6029 variable would have index (1,1). The elements of index must
6030 correspond to the variable’s dimensions. Hence, if the variable uses
6031 the unlimited dimension, the last index would correspond to the
6040 : Pointer to the data value to be written. If the type of data values
6041 differs from the netCDF variable type, type conversion will occur.
6042 See [(netcdf)Type Conversion](netcdf.html#Type-Conversion)
6043 ‘Type Conversion’ in The NetCDF Users Guide.
6048 NF\_PUT\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6049 Otherwise, the returned status indicates an error. Possible causes of
6052 - The variable ID is invalid for the specified netCDF dataset.
6053 - The specified indices were out of range for the rank of the
6054 specified variable. For example, a negative index or an index that
6055 is larger than the corresponding dimension length will cause an
6057 - The specified value is out of the range of values representable by
6058 the external data type of the variable.
6059 - The specified netCDF is in define mode rather than data mode.
6060 - The specified netCDF ID does not refer to an open netCDF dataset.
6065 Here is an example using NF\_PUT\_VAR1\_DOUBLE to set the (4,3,2)
6066 element of the variable named rh to 0.5 in an existing netCDF dataset
6067 named foo.nc. For simplicity in this example, we ame that we know
6068 that rh is dimensioned with lon, lat, and time, so we want to set the
6069 value of rh that corresponds to the fourth lon value, the third lat
6070 value, and the second time value:
6075 INCLUDE 'netcdf.inc'
6077 INTEGER STATUS ! error status
6079 INTEGER RHID ! variable ID
6080 INTEGER RHINDX(3) ! where to put value
6081 DATA RHINDX /4, 3, 2/
6083 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6084 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6086 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
6087 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6088 STATUS = NF_PUT_VAR1_DOUBLE (NCID, RHID, RHINDX, 0.5)
6089 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6092 6.20 Write an Entire Variable: NF\_PUT\_VAR\_ type
6093 --------------------------------------------------
6095 The NF\_PUT\_VAR\_ type family of functions write all the values of a
6096 variable into a netCDF variable of an open netCDF dataset. This is the
6097 simplest interface to use for writing a value in a scalar variable or
6098 whenever all the values of a multidimensional variable can all be
6099 written at once. The values to be written are associated with the netCDF
6100 variable by aming that the last dimension of the netCDF variable
6101 varies fastest in the C interface. The values are converted to the
6102 external data type of the variable, if necessary.
6104 Take care when using the simplest forms of this interface with record
6105 variables (variables that use the NF\_UNLIMITED dimension) when you
6106 don’t specify how many records are to be written. If you try to write
6107 all the values of a record variable into a netCDF file that has no
6108 record data yet (hence has 0 records), nothing will be written.
6109 Similarly, if you try to write all the values of a record variable from
6110 an array but there are more records in the file than you ame, more
6111 in-memory data will be accessed than you expect, which may cause a
6112 segmentation violation. To avoidch problems, it is better to use the
6113 NF\_PUT\_VARA\_type interfaces for variables that use the NF\_UNLIMITED
6114 dimension. See [Write an Array of Values: NF\_PUT\_VARA\_
6115 type](#NF_005fPUT_005fVARA_005f-type).
6123 INTEGER FUNCTION NF_PUT_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6125 INTEGER FUNCTION NF_PUT_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6126 INTEGER*1 I1VALS(*))
6127 INTEGER FUNCTION NF_PUT_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6128 INTEGER*2 I2VALS(*))
6129 INTEGER FUNCTION NF_PUT_VAR_INT (INTEGER NCID, INTEGER VARID,
6131 INTEGER FUNCTION NF_PUT_VAR_REAL (INTEGER NCID, INTEGER VARID,
6133 INTEGER FUNCTION NF_PUT_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6135 INTEGER FUNCTION NF_PUT_VAR (INTEGER NCID, INTEGER VARID,
6140 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6152 : The block of data values to be written. The data should be of the
6153 type appropriate for the function called. You cannot put CHARACTER
6154 data into a numeric variable or numeric data into a text variable.
6155 For numeric data, if the type of data differs from the netCDF
6156 variable type, type conversion will occur (see [(netcdf)Type
6157 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6158 in The NetCDF Users Guide). The order in which the data will be
6159 written into the specified variable is with the first dimension
6160 varying fastest (like the ordinary FORTRAN convention).
6165 Members of the NF\_PUT\_VAR\_ type family return the value NF\_NOERR if
6166 no errors occurred. Otherwise, the returned status indicates an error.
6167 Possible causes of errors include:
6169 - The variable ID is invalid for the specified netCDF dataset.
6170 - One or more of the specified values are out of the range of values
6171 representable by the external data type of the variable.
6172 - One or more of the specified values are out of the range of values
6173 representable by the external data type of the variable.
6174 - The specified netCDF dataset is in define mode rather than data
6176 - The specified netCDF ID does not refer to an open netCDF dataset.
6181 Here is an example using NF\_PUT\_VAR\_DOUBLE to add or change all the
6182 values of the variable named rh to 0.5 in an existing netCDF dataset
6183 named foo.nc. For simplicity in this example, we ame that we know
6184 that rh is dimensioned with lon and lat, and that there are ten lon
6185 values and five lat values.
6190 INCLUDE 'netcdf.inc'
6192 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6193 INTEGER STATUS, NCID
6194 INTEGER RHID ! variable ID
6195 DOUBLE RHVALS(LONS, LATS)
6197 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6198 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6200 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6201 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6202 DO 10 ILON = 1, LONS
6203 DO 10 ILAT = 1, LATS
6204 RHVALS(ILON, ILAT) = 0.5
6206 STATUS = NF_PUT_var_DOUBLE (NCID, RHID, RHVALS)
6207 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6211 6.21 Write an Array of Values: NF\_PUT\_VARA\_ type
6212 ---------------------------------------------------
6214 The function NF\_PUT\_VARA\_ type writes values into a netCDF variable
6215 of an open netCDF dataset. The part of the netCDF variable to write is
6216 specified by giving a corner and a vector of edge lengths that refer to
6217 an array of the netCDF variable. The values to be written are
6218 associated with the netCDF variable by aming that the first dimension
6219 of the netCDF variable varies fastest in the FORTRAN interface. The
6220 netCDF dataset must be in data mode.
6228 INTEGER FUNCTION NF_PUT_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6229 INTEGER START(*), INTEGER COUNT(*),
6231 INTEGER FUNCTION NF_PUT_VARA_INT1(INTEGER NCID, INTEGER VARID,
6232 INTEGER START(*), INTEGER COUNT(*),
6233 INTEGER*1 I1VALS(*))
6234 INTEGER FUNCTION NF_PUT_VARA_INT2(INTEGER NCID, INTEGER VARID,
6235 INTEGER START(*), INTEGER COUNT(*),
6236 INTEGER*2 I2VALS(*))
6237 INTEGER FUNCTION NF_PUT_VARA_INT (INTEGER NCID, INTEGER VARID,
6238 INTEGER START(*), INTEGER COUNT(*),
6240 INTEGER FUNCTION NF_PUT_VARA_REAL(INTEGER NCID, INTEGER VARID,
6241 INTEGER START(*), INTEGER COUNT(*),
6243 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6244 INTEGER START(*), INTEGER COUNT(*),
6246 INTEGER FUNCTION NF_PUT_VARA (INTEGER NCID, INTEGER VARID,
6247 INTEGER START(*), INTEGER COUNT(*),
6252 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6258 : A vector of integers specifying the index in the variable where the
6259 first of the data values will be written. The indices are relative
6260 to 1, so for example, the first data value of a variable would have
6261 index (1, 1, ..., 1). The length of START must be the same as the
6262 number of dimensions of the specified variable. The elements of
6263 START must correspond to the variable’s dimensions in order. Hence,
6264 if the variable is a record variable, the last index would
6265 correspond to the starting record number for writing the data
6269 : A vector of integers specifying the edge lengths along each
6270 dimension of the block of data values to written. To write a single
6271 value, for example, specify COUNT as (1, 1, ..., 1). The length of
6272 COUNT is the number of dimensions of the specified variable. The
6273 elements of COUNT correspond to the variable’s dimensions. Hence, if
6274 the variable is a record variable, the last element of COUNT
6275 corresponds to a count of the number of records to write.
6277 Note: setting any element of the count array to zero causes the
6278 function to exit without error, and without doing anything.
6287 : The block of data values to be written. The data should be of the
6288 type appropriate for the function called. You cannot put CHARACTER
6289 data into a numeric variable or numeric data into a text variable.
6290 For numeric data, if the type of data differs from the netCDF
6291 variable type, type conversion will occur (see [(netcdf)Type
6292 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6293 in The NetCDF Users Guide).
6298 NF\_PUT\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
6299 Otherwise, the returned status indicates an error. Possible causes of
6302 - The variable ID is invalid for the specified netCDF dataset.
6303 - The specified corner indices were out of range for the rank of the
6304 specified variable. For example, a negative index, or an index that
6305 is larger than the corresponding dimension length will cause an
6307 - The specified edge lengths added to the specified corner would have
6308 referenced data out of range for the rank of the specified variable.
6309 For example, an edge length that is larger than the corresponding
6310 dimension length minus the corner index will cause an error.
6311 - One or more of the specified values are out of the range of values
6312 representable by the external data type of the variable.
6313 - The specified netCDF dataset is in define mode rather than data
6315 - The specified netCDF ID does not refer to an open netCDF dataset.
6320 Here is an example using NF\_PUT\_VARA\_DOUBLE to add or change all the
6321 values of the variable named rh to 0.5 in an existing netCDF dataset
6322 named foo.nc. For simplicity in this example, we ame that we know
6323 that rh is dimensioned with time, lat, and lon, and that there are three
6324 time values, five lat values, and ten lon values.
6329 INCLUDE 'netcdf.inc'
6331 PARAMETER (NDIMS=3) ! number of dimensions
6332 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
6333 INTEGER STATUS, NCID, TIMES
6334 INTEGER RHID ! variable ID
6335 INTEGER START(NDIMS), COUNT(NDIMS)
6336 DOUBLE RHVALS(LONS, LATS, TIMES)
6337 DATA START /1, 1, 1/ ! start at first value
6338 DATA COUNT /LONS, LATS, TIMES/
6340 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6341 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6343 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6344 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6345 DO 10 ILON = 1, LONS
6346 DO 10 ILAT = 1, LATS
6347 DO 10 ITIME = 1, TIMES
6348 RHVALS(ILON, ILAT, ITIME) = 0.5
6350 STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
6351 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6355 6.22 NF\_PUT\_VARS\_ type
6356 -------------------------
6358 Each member of the family of functions NF\_PUT\_VARS\_ type writes a
6359 subsampled (strided) array of values into a netCDF variable of
6360 an open netCDF dataset. Thebsampled array is specified by
6361 giving a corner, a vector of counts, and a stride vector. The netCDF
6362 dataset must be in data mode.
6370 INTEGER FUNCTION NF_PUT_VARS_TEXT (INTEGER NCID, INTEGER VARID,
6371 INTEGER START(*), INTEGER COUNT(*),
6372 INTEGER STRIDE(*),CHARACTER*(*) TEXT)
6373 INTEGER FUNCTION NF_PUT_VARS_INT1 (INTEGER NCID, INTEGER VARID,
6374 INTEGER START(*), INTEGER COUNT(*),
6375 INTEGER STRIDE(*),INTEGER*1 I1VALS(*))
6376 INTEGER FUNCTION NF_PUT_VARS_INT2 (INTEGER NCID, INTEGER VARID,
6377 INTEGER START(*), INTEGER COUNT(*),
6378 INTEGER STRIDE(*),INTEGER*2 I2VALS(*))
6379 INTEGER FUNCTION NF_PUT_VARS_INT (INTEGER NCID, INTEGER VARID,
6380 INTEGER START(*), INTEGER COUNT(*),
6381 INTEGER STRIDE(*), INTEGER IVALS(*))
6382 INTEGER FUNCTION NF_PUT_VARS_REAL (INTEGER NCID, INTEGER VARID,
6383 INTEGER START(*), INTEGER COUNT(*),
6384 INTEGER STRIDE(*), REAL RVALS(*))
6385 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
6386 INTEGER START(*), INTEGER COUNT(*),
6387 INTEGER STRIDE(*), DOUBLE DVALS(*))
6388 INTEGER FUNCTION NF_PUT_VARS (INTEGER NCID, INTEGER VARID,
6389 INTEGER START(*), INTEGER COUNT(*),
6390 INTEGER STRIDE(*), VALS(*))
6394 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6400 : A vector of integers specifying the index in the variable where the
6401 first of the data values will be written. The indices are relative
6402 to 1, so for example, the first data value of a variable would have
6403 index (1, 1, ..., 1). The elements of START correspond, in order, to
6404 the variable’s dimensions. Hence, if the variable is a record
6405 variable, the last index would correspond to the starting record
6406 number for writing the data values.
6409 : A vector of integers specifying the number of indices selected along
6410 each dimension. To write a single value, for example, specify COUNT
6411 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6412 the variable’s dimensions. Hence, if the variable is a record
6413 variable, the last element of COUNT corresponds to a count of the
6414 number of records to write.
6416 Note: setting any element of the count array to zero causes the
6417 function to exit without error, and without doing anything.
6420 : A vector of integers that specifies the sampling interval along each
6421 dimension of the netCDF variable. The elements of the stride vector
6422 correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6423 gives the sampling interval along the most rapidly varying dimension
6424 of the netCDF variable). Sampling intervals are specified in
6425 type-independent units of elements (a value of 1 selects consecutive
6426 elements of the netCDF variable along the corresponding dimension, a
6427 value of 2 selects every other element, etc.).
6436 : The block of data values to be written. The data should be of the
6437 type appropriate for the function called. You cannot put CHARACTER
6438 data into a numeric variable or numeric data into a text variable.
6439 For numeric data, if the type of data differs from the netCDF
6440 variable type, type conversion will occur (see [(netcdf)Type
6441 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6442 in The NetCDF Users Guide).
6447 NF\_PUT\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
6448 Otherwise, the returned status indicates an error. Possible causes of
6451 - The variable ID is invalid for the specified netCDF dataset.
6452 - The specified start, count and stride generate an index which is out
6454 - One or more of the specified values are out of the range of values
6455 representable by the external data type of the variable.
6456 - The specified netCDF is in define mode rather than data mode.
6457 - The specified netCDF ID does not refer to an open netCDF dataset.
6462 Here is an example of using NF\_PUT\_VARS\_REAL to write – from an
6463 internal array – every other point of a netCDF variable named rh which
6464 is described by the FORTRAN declaration REAL RH(6,4) (note the size of
6470 INCLUDE 'netcdf.inc'
6472 PARAMETER (NDIM=2) ! rank of netCDF variable
6473 INTEGER NCID ! netCDF dataset ID
6474 INTEGER STATUS ! return code
6475 INTEGER RHID ! variable ID
6476 INTEGER START(NDIM) ! netCDF variable start point
6477 INTEGER COUNT(NDIM) ! size of internal array
6478 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6479 REAL RH(3,2) ! notebsampled sizes for netCDF variable
6481 DATA START /1, 1/ ! start at first netCDF variable value
6482 DATA COUNT /3, 2/ ! size of internal array: entire bsampled)
6484 DATA STRIDE /2, 2/ ! access every other netCDF element
6486 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6487 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6489 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6490 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6492 STATUS = NF_PUT_VARS_REAL(NCID, RHID, START, COUNT, STRIDE, RH)
6493 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6495 6.23 NF\_PUT\_VARM\_ type
6496 -------------------------
6498 The NF\_PUT\_VARM\_ type family of functions writes a mapped array
6499 section of values into a netCDF variable of an open netCDF dataset. The
6500 mapped array is specified by giving a corner, a vector of
6501 counts, a stride vector, and an index mapping vector. The index mapping
6502 vector is a vector of integers that specifies the mapping between the
6503 dimensions of a netCDF variable and the in-memory structure of the
6504 internal data array. No amptions are made about the ordering or
6505 length of the dimensions of the data array. The netCDF dataset must be
6514 INTEGER FUNCTION NF_PUT_VARM_TEXT (INTEGER NCID, INTEGER VARID,
6515 INTEGER START(*), INTEGER COUNT(*),
6516 INTEGER STRIDE(*), INTEGER IMAP(*),
6518 INTEGER FUNCTION NF_PUT_VARM_INT1 (INTEGER NCID, INTEGER VARID,
6519 INTEGER START(*), INTEGER COUNT(*),
6520 INTEGER STRIDE(*), INTEGER IMAP(*),
6521 INTEGER*1 I1VALS(*))
6522 INTEGER FUNCTION NF_PUT_VARM_INT2 (INTEGER NCID, INTEGER VARID,
6523 INTEGER START(*), INTEGER COUNT(*),
6524 INTEGER STRIDE(*), INTEGER IMAP(*),
6525 INTEGER*2 I2VALS(*))
6526 INTEGER FUNCTION NF_PUT_VARM_INT (INTEGER NCID, INTEGER VARID,
6527 INTEGER START(*), INTEGER COUNT(*),
6528 INTEGER STRIDE(*), INTEGER IMAP(*),
6530 INTEGER FUNCTION NF_PUT_VARM_REAL (INTEGER NCID, INTEGER VARID,
6531 INTEGER START(*), INTEGER COUNT(*),
6532 INTEGER STRIDE(*), INTEGER IMAP(*),
6534 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
6535 INTEGER START(*), INTEGER COUNT(*),
6536 INTEGER STRIDE(*), INTEGER IMAP(*),
6541 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6547 : A vector of integers specifying the index in the variable where the
6548 first of the data values will be written. The indices are relative
6549 to 1, so for example, the first data value of a variable would have
6550 index (1, 1, ..., 1). The elements of START correspond, in order, to
6551 the variable’s dimensions. Hence, if the variable is a record
6552 variable, the last index would correspond to the starting record
6553 number for writing the data values.
6556 : A vector of integers specifying the number of indices selected along
6557 each dimension. To write a single value, for example, specify COUNT
6558 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6559 the variable’s dimensions. Hence, if the variable is a record
6560 variable, the last element of COUNT corresponds to a count of the
6561 number of records to write.
6563 Note: setting any element of the count array to zero causes the
6564 function to exit without error, and without doing anything.
6567 : A vector of integers that specifies the sampling interval along each
6568 dimension of the netCDF variable. The elements of the stride vector
6569 correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6570 gives the sampling interval along the most rapidly varying dimension
6571 of the netCDF variable). Sampling intervals are specified in
6572 type-independent units of elements (a value of 1 selects consecutive
6573 elements of the netCDF variable along the corresponding dimension, a
6574 value of 2 selects every other element, etc.).
6577 : A vector of integers that specifies the mapping between the
6578 dimensions of a netCDF variable and the in-memory structure of the
6579 internal data array. The elements of the index mapping vector
6580 correspond, in order, to the netCDF variable’s dimensions (IMAP(1)
6581 gives the distance between elements of the internal array
6582 corresponding to the most rapidly varying dimension of the netCDF
6583 variable). Distances between elements are specified in units of
6584 elements (the distance between internal elements that occupy
6585 adjacent memory locations is 1 and not the element’s byte-length as
6594 : The data values to be written. The data should be of the type
6595 appropriate for the function called. You cannot put CHARACTER data
6596 into a numeric variable or numeric data into a text variable. For
6597 numeric data, if the type of data differs from the netCDF variable
6598 type, type conversion will occur (see [(netcdf)Type
6599 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6600 in The NetCDF Users Guide).
6605 NF\_PUT\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
6606 Otherwise, the returned status indicates an error. Possible causes of
6609 - The variable ID is invalid for the specified netCDF dataset.
6610 - The specified START, COUNT, and STRIDE generate an index which is
6611 out of range. Note that no error checking is possible on the imap
6613 - One or more of the specified values are out of the range of values
6614 representable by the external data type of the variable.
6615 - The specified netCDF is in define mode rather than data mode.
6616 - The specified netCDF ID does not refer to an open netCDF dataset.
6621 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
6622 variable and an internal array of the same shape:
6627 REAL A(2,3,4) ! same shape as netCDF variable
6629 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
6630 ! ---------------- ----------------------
6631 ! most rapidly varying 1
6632 ! intermediate 2 (=IMAP(1)*2)
6633 ! most slowly varying 6 (=IMAP(2)*3)
6636 Using the IMAP vector above with NF\_PUT\_VARM\_REAL obtains the same
6637 rlt as simply using NF\_PUT\_VAR\_REAL.
6639 Here is an example of using NF\_PUT\_VARM\_REAL to write – from a
6640 transposed, internal array – a netCDF variable named rh which is
6641 described by the FORTRAN declaration REAL RH(4,6) (note the size and
6642 order of the dimensions):
6647 INCLUDE 'netcdf.inc'
6649 PARAMETER (NDIM=2) ! rank of netCDF variable
6650 INTEGER NCID ! netCDF ID
6651 INTEGER STATUS ! return code
6652 INTEGER RHID ! variable ID
6653 INTEGER START(NDIM) ! netCDF variable start point
6654 INTEGER COUNT(NDIM) ! size of internal array
6655 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6656 INTEGER IMAP(NDIM) ! internal array inter-element distances
6657 REAL RH(6,4) ! note transposition of netCDF variable dimensions
6658 DATA START /1, 1/ ! start at first netCDF variable element
6659 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
6660 ! to netCDF variable -- not internal array
6661 DATA STRIDE /1, 1/ ! sample every netCDF element
6662 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
6664 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6665 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6667 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6668 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6670 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6671 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6674 Here is another example of using NF\_PUT\_VARM\_REAL to write – from a
6675 transposed, internal array – absample of the same netCDF variable, by
6676 writing every other point of the netCDF variable:
6681 INCLUDE 'netcdf.inc'
6683 PARAMETER (NDIM=2) ! rank of netCDF variable
6684 INTEGER NCID ! netCDF dataset ID
6685 INTEGER STATUS ! return code
6686 INTEGER RHID ! variable ID
6687 INTEGER START(NDIM) ! netCDF variable start point
6688 INTEGER COUNT(NDIM) ! size of internal array
6689 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6690 INTEGER IMAP(NDIM) ! internal array inter-element distances
6691 REAL RH(3,2) ! note transposition of bsampled) dimensions
6692 DATA START /1, 1/ ! start at first netCDF variable value
6693 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
6694 ! to netCDF variable -- not internal array
6695 DATA STRIDE /2, 2/ ! sample every other netCDF element
6696 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
6698 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6699 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6701 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6702 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6704 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6705 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6708 6.24 NF\_GET\_VAR1\_ type
6709 -------------------------
6711 The functions NF\_GET\_VAR1\_ type get a single data value from a
6712 variable of an open netCDF dataset that is in data mode. Inputs are the
6713 netCDF ID, the variable ID, a multidimensional index that specifies
6714 which value to get, and the address of a location into which the data
6715 value will be read. The value is converted from the external data type
6716 of the variable, if necessary.
6724 INTEGER FUNCTION NF_GET_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6725 INTEGER INDEX(*), CHARACTER CHVAL)
6726 INTEGER FUNCTION NF_GET_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6727 INTEGER INDEX(*), INTEGER*1 I1VAL)
6728 INTEGER FUNCTION NF_GET_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6729 INTEGER INDEX(*), INTEGER*2 I2VAL)
6730 INTEGER FUNCTION NF_GET_VAR1_INT (INTEGER NCID, INTEGER VARID,
6731 INTEGER INDEX(*), INTEGER IVAL)
6732 INTEGER FUNCTION NF_GET_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6733 INTEGER INDEX(*), REAL RVAL)
6734 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6735 INTEGER INDEX(*), DOUBLE DVAL)
6736 INTEGER FUNCTION NF_GET_VAR1(INTEGER NCID, INTEGER VARID,
6737 INTEGER INDEX(*), VAL)
6741 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6747 : The index of the data value to be read. The indices are relative to
6748 1, so for example, the first data value of a two-dimensional
6749 variable has index (1,1). The elements of index correspond to the
6750 variable’s dimensions. Hence, if the variable is a record variable,
6751 the last index is the record number.
6760 : The location into which the data value will be read. You cannot get
6761 CHARACTER data from a numeric variable or numeric data from a
6762 character variable. For numeric data, if the type of data differs
6763 from the netCDF variable type, type conversion will occur. (see
6764 [(netcdf)Type Conversion](netcdf.html#Type-Conversion) ‘Type
6765 Conversion’ in The NetCDF Users Guide).
6770 NF\_GET\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6771 Otherwise, the returned status indicates an error. Possible causes of
6774 - The variable ID is invalid for the specified netCDF dataset.
6775 - The specified indices were out of range for the rank of the
6776 specified variable. For example, a negative index or an index that
6777 is larger than the corresponding dimension length will cause an
6779 - The value is out of the range of values representable by the desired
6781 - The specified netCDF is in define mode rather than data mode.
6782 - The specified netCDF ID does not refer to an open netCDF dataset.
6787 Here is an example using NF\_GET\_VAR1\_DOUBLE to get the (4,3,2)
6788 element of the variable named rh in an existing netCDF dataset named
6789 foo.nc. For simplicity in this example, we ame that we know that rh
6790 is dimensioned with lon, lat, and time, so we want to get the value of
6791 rh that corresponds to the fourth lon value, the third lat value, and
6792 the second time value:
6797 INCLUDE 'netcdf.inc'
6799 INTEGER STATUS, NCID
6800 INTEGER RHID ! variable ID
6801 INTEGER RHINDX(3) ! where to get value
6802 DOUBLE PRECISION RHVAL ! put it here
6803 DATA RHINDX /4, 3, 2/
6805 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6806 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6808 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6809 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6810 STATUS = NF_GET_VAR1_DOUBLE (NCID, RHID, RHINDX, RHVAL)
6811 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6814 6.25 NF\_GET\_VAR\_ type
6815 ------------------------
6817 The members of the NF\_GET\_VAR\_ type family of functions read all the
6818 values from a netCDF variable of an open netCDF dataset. This is the
6819 simplest interface to use for reading the value of a scalar variable or
6820 when all the values of a multidimensional variable can be read at once.
6821 The values are read into consecutive locations with the first dimension
6822 varying fastest. The netCDF dataset must be in data mode.
6824 Take care when using the simplest forms of this interface with record
6825 variables (variables that use the NF\_UNLIMITED dimension) when you
6826 don’t specify how many records are to be read. If you try to read all
6827 the values of a record variable into an array but there are more records
6828 in the file than you ame, more data will be read than you expect,
6829 which may cause a segmentation violation. To avoidch problems, it is
6830 better to use the NF\_GET\_VARA\_type interfaces for variables that use
6831 the NF\_UNLIMITED dimension. See [NF\_GET\_VARA\_
6832 type](#NF_005fGET_005fVARA_005f-type).
6840 INTEGER FUNCTION NF_GET_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6842 INTEGER FUNCTION NF_GET_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6843 INTEGER*1 i1vals(*))
6844 INTEGER FUNCTION NF_GET_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6845 INTEGER*2 i2vals(*))
6846 INTEGER FUNCTION NF_GET_VAR_INT (INTEGER NCID, INTEGER VARID,
6848 INTEGER FUNCTION NF_GET_VAR_REAL (INTEGER NCID, INTEGER VARID,
6850 INTEGER FUNCTION NF_GET_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6852 INTEGER FUNCTION NF_GET_VAR (INTEGER NCID, INTEGER VARID,
6857 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6869 : The block of data values to be read. The data should be of the type
6870 appropriate for the function called. You cannot read CHARACTER data
6871 from a numeric variable or numeric data from a text variable. For
6872 numeric data, if the type of data differs from the netCDF variable
6873 type, type conversion will occur (see [(netcdf)Type
6874 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6875 in The NetCDF Users Guide).
6880 NF\_GET\_VAR\_ type returns the value NF\_NOERR if no errors occurred.
6881 Otherwise, the returned status indicates an error. Possible causes of
6884 - The variable ID is invalid for the specified netCDF dataset.
6885 - One or more of the values are out of the range of values
6886 representable by the desired type.
6887 - The specified netCDF is in define mode rather than data mode.
6888 - The specified netCDF ID does not refer to an open netCDF dataset.
6893 Here is an example using NF\_GET\_VAR\_DOUBLE to read all the values of
6894 the variable named rh from an existing netCDF dataset named foo.nc. For
6895 simplicity in this example, we ame that we know that rh is
6896 dimensioned with lon and lat, and that there are ten lon values and five
6902 INCLUDE 'netcdf.inc'
6904 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6905 INTEGER STATUS, NCID
6906 INTEGER RHID ! variable ID
6907 DOUBLE RHVALS(LONS, LATS)
6909 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6910 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6912 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6913 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6914 STATUS = NF_GET_VAR_DOUBLE (NCID, RHID, RHVALS)
6915 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6918 6.26 NF\_GET\_VARA\_ type
6919 -------------------------
6921 The members of the NF\_GET\_VARA\_ type family of functions read an
6922 array of values from a netCDF variable of an open netCDF dataset. The
6923 array is specified by giving a corner and a vector of edge lengths. The
6924 values are read into consecutive locations with the first dimension
6925 varying fastest. The netCDF dataset must be in data mode.
6933 INTEGER FUNCTION NF_GET_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6934 INTEGER START(*), INTEGER COUNT(*),
6936 INTEGER FUNCTION NF_GET_VARA_INT1(INTEGER NCID, INTEGER VARID,
6937 INTEGER START(*), INTEGER COUNT(*),
6938 INTEGER*1 i1vals(*))
6939 INTEGER FUNCTION NF_GET_VARA_INT2(INTEGER NCID, INTEGER VARID,
6940 INTEGER START(*), INTEGER COUNT(*),
6941 INTEGER*2 i2vals(*))
6942 INTEGER FUNCTION NF_GET_VARA_INT (INTEGER NCID, INTEGER VARID,
6943 INTEGER START(*), INTEGER COUNT(*),
6945 INTEGER FUNCTION NF_GET_VARA_REAL(INTEGER NCID, INTEGER VARID,
6946 INTEGER START(*), INTEGER COUNT(*),
6948 INTEGER FUNCTION NF_GET_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6949 INTEGER START(*), INTEGER COUNT(*),
6954 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6960 : A vector of integers specifying the index in the variable where the
6961 first of the data values will be read. The indices are relative to
6962 1, so for example, the first data value of a variable would have
6963 index (1, 1, ..., 1). The length of START must be the same as the
6964 number of dimensions of the specified variable. The elements of
6965 START correspond, in order, to the variable’s dimensions. Hence, if
6966 the variable is a record variable, the last index would correspond
6967 to the starting record number for reading the data values.
6970 : A vector of integers specifying the edge lengths along each
6971 dimension of the block of data values to be read. To read a single
6972 value, for example, specify COUNT as (1, 1, ..., 1). The length of
6973 COUNT is the number of dimensions of the specified variable. The
6974 elements of COUNT correspond, in order, to the variable’s
6975 dimensions. Hence, if the variable is a record variable, the last
6976 element of COUNT corresponds to a count of the number of records to
6979 Note: setting any element of the count array to zero causes the
6980 function to exit without error, and without doing anything.
6988 : The block of data values to be read. The data should be of the type
6989 appropriate for the function called. You cannot read CHARACTER data
6990 from a numeric variable or numeric data from a text variable. For
6991 numeric data, if the type of data differs from the netCDF variable
6992 type, type conversion will occur (see [(netcdf)Type
6993 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6994 in The NetCDF Users Guide).
6999 NF\_GET\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
7000 Otherwise, the returned status indicates an error. Possible causes of
7003 - The variable ID is invalid for the specified netCDF dataset.
7004 - The specified corner indices were out of range for the rank of the
7005 specified variable. For example, a negative index or an index that
7006 is larger than the corresponding dimension length will cause an
7008 - The specified edge lengths added to the specified corner would have
7009 referenced data out of range for the rank of the specified variable.
7010 For example, an edge length that is larger than the corresponding
7011 dimension length minus the corner index will cause an error.
7012 - One or more of the values are out of the range of values
7013 representable by the desired type.
7014 - The specified netCDF is in define mode rather than data mode.
7015 - The specified netCDF ID does not refer to an open netCDF dataset.
7020 Here is an example using NF\_GET\_VARA\_DOUBLE to read all the values of
7021 the variable named rh from an existing netCDF dataset named foo.nc. For
7022 simplicity in this example, we ame that we know that rh is
7023 dimensioned with lon, lat, and time, and that there are ten lon values,
7024 five lat values, and three time values.
7029 INCLUDE 'netcdf.inc'
7031 PARAMETER (NDIMS=3) ! number of dimensions
7032 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7033 INTEGER STATUS, NCID
7034 INTEGER RHID ! variable ID
7035 INTEGER START(NDIMS), COUNT(NDIMS)
7036 DOUBLE RHVALS(LONS, LATS, TIMES)
7037 DATA START /1, 1, 1/ ! start at first value
7038 DATA COUNT /LONS, LATS, TIMES/ ! get all the values
7040 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7041 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7043 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7044 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7045 STATUS = NF_GET_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
7046 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7049 6.27 NF\_GET\_VARS\_ type
7050 -------------------------
7052 The NF\_GET\_VARS\_ type family of functions read absampled (strided)
7053 array of values from a netCDF variable of an open netCDF
7054 dataset. Thebsampled array is specified by giving a corner, a
7055 vector of edge lengths, and a stride vector. The values are read with
7056 the first dimension of the netCDF variable varying fastest. The netCDF
7057 dataset must be in data mode.
7065 INTEGER FUNCTION NF_GET_VARS_TEXT (INTEGER NCID, INTEGER VARID,
7066 INTEGER START(*), INTEGER COUNT(*),
7067 INTEGER STRIDE(*),CHARACTER*(*) text)
7068 INTEGER FUNCTION NF_GET_VARS_INT1 (INTEGER NCID, INTEGER VARID,
7069 INTEGER START(*), INTEGER COUNT(*),
7070 INTEGER STRIDE(*),INTEGER*1 i1vals(*))
7071 INTEGER FUNCTION NF_GET_VARS_INT2 (INTEGER NCID, INTEGER VARID,
7072 INTEGER START(*), INTEGER COUNT(*),
7073 INTEGER STRIDE(*),INTEGER*2 i2vals(*))
7074 INTEGER FUNCTION NF_GET_VARS_INT (INTEGER NCID, INTEGER VARID,
7075 INTEGER START(*), INTEGER COUNT(*),
7076 INTEGER STRIDE(*), INTEGER ivals(*))
7077 INTEGER FUNCTION NF_GET_VARS_REAL (INTEGER NCID, INTEGER VARID,
7078 INTEGER START(*), INTEGER COUNT(*),
7079 INTEGER STRIDE(*), REAL rvals(*))
7080 INTEGER FUNCTION NF_GET_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
7081 INTEGER START(*), INTEGER COUNT(*),
7082 INTEGER STRIDE(*), DOUBLE dvals(*))
7086 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7092 : A vector of integers specifying the index in the variable from which
7093 the first of the data values will be read. The indices are relative
7094 to 1, so for example, the first data value of a variable would have
7095 index (1, 1, ..., 1). The elements of START correspond, in order, to
7096 the variable’s dimensions. Hence, if the variable is a record
7097 variable, the last index would correspond to the starting record
7098 number for reading the data values.
7101 : A vector of integers specifying the number of indices selected along
7102 each dimension. To read a single value, for example, specify COUNT
7103 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7104 the variable’s dimensions. Hence, if the variable is a record
7105 variable, the last element of COUNT corresponds to a count of the
7106 number of records to read.
7108 Note: setting any element of the count array to zero causes the
7109 function to exit without error, and without doing anything.
7112 : A vector of integers specifying, for each dimension, the interval
7113 between selected indices or the value 0. The elements of the vector
7114 correspond, in order, to the variable’s dimensions. A value of 1
7115 accesses adjacent values of the netCDF variable in the corresponding
7116 dimension; a value of 2 accesses every other value of the netCDF
7117 variable in the corresponding dimension; and so on. A 0 argument is
7118 treated as (1, 1, ..., 1).
7126 : The block of data values to be read. The data should be of the type
7127 appropriate for the function called. You cannot read CHARACTER data
7128 from a numeric variable or numeric data from a text variable. For
7129 numeric data, if the type of data differs from the netCDF variable
7130 type, type conversion will occur (see [(netcdf)Type
7131 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7132 in The NetCDF Users Guide).
7137 NF\_GET\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
7138 Otherwise, the returned status indicates an error. Possible causes of
7141 - The variable ID is invalid for the specified netCDF dataset.
7142 - The specified start, count and stride generate an index which is out
7144 - One or more of the values are out of the range of values
7145 representable by the desired type.
7146 - The specified netCDF is in define mode rather than data mode.
7147 - The specified netCDF ID does not refer to an open netCDF dataset.
7152 Here is an example using NF\_GET\_VARS\_DOUBLE to read every other value
7153 in each dimension of the variable named rh from an existing netCDF
7154 dataset named foo.nc. Values are assigned, using the same dimensional
7155 strides, to a 2-parameter array. For simplicity in this example, we
7156 ame that we know that rh is dimensioned with lon, lat, and time, and
7157 that there are ten lon values, five lat values, and three time values.
7162 INCLUDE 'netcdf.inc'
7164 PARAMETER (NDIMS=3) ! number of dimensions
7165 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7166 INTEGER STATUS, NCID
7167 INTEGER RHID ! variable ID
7168 INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
7169 DOUBLE DATA(LONS, LATS, TIMES)
7170 DATA START /1, 1, 1/ ! start at first value
7171 DATA COUNT /LONS, LATS, TIMES/
7172 DATA STRIDE /2, 2, 2/
7174 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7175 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7177 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7178 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7179 STATUS = NF_GET_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
7180 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7183 6.28 NF\_GET\_VARM\_ type
7184 -------------------------
7186 The NF\_GET\_VARM\_ type family of functions reads a mapped array
7187 section of values from a netCDF variable of an open netCDF dataset. The
7188 mapped array is specified by giving a corner, a vector of edge
7189 lengths, a stride vector, and an index mapping vector. The index mapping
7190 vector is a vector of integers that specifies the mapping between the
7191 dimensions of a netCDF variable and the in-memory structure of the
7192 internal data array. No amptions are made about the ordering or
7193 length of the dimensions of the data array. The netCDF dataset must be
7202 INTEGER FUNCTION NF_GET_VARM_TEXT (INTEGER NCID, INTEGER VARID,
7203 INTEGER START(*), INTEGER COUNT(*),
7204 INTEGER STRIDE(*), INTEGER IMAP(*),
7206 INTEGER FUNCTION NF_GET_VARM_INT1 (INTEGER NCID, INTEGER VARID,
7207 INTEGER START(*), INTEGER COUNT(*),
7208 INTEGER STRIDE(*), INTEGER IMAP(*),
7209 INTEGER*1 i1vals(*))
7210 INTEGER FUNCTION NF_GET_VARM_INT2 (INTEGER NCID, INTEGER VARID,
7211 INTEGER START(*), INTEGER COUNT(*),
7212 INTEGER STRIDE(*), INTEGER IMAP(*),
7213 INTEGER*2 i2vals(*))
7214 INTEGER FUNCTION NF_GET_VARM_INT (INTEGER NCID, INTEGER VARID,
7215 INTEGER START(*), INTEGER COUNT(*),
7216 INTEGER STRIDE(*), INTEGER IMAP(*),
7218 INTEGER FUNCTION NF_GET_VARM_REAL (INTEGER NCID, INTEGER VARID,
7219 INTEGER START(*), INTEGER COUNT(*),
7220 INTEGER STRIDE(*), INTEGER IMAP(*),
7222 INTEGER FUNCTION NF_GET_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
7223 INTEGER START(*), INTEGER COUNT(*),
7224 INTEGER STRIDE(*), INTEGER IMAP(*),
7229 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7235 : A vector of integers specifying the index in the variable from which
7236 the first of the data values will be read. The indices are relative
7237 to 1, so for example, the first data value of a variable would have
7238 index (1, 1, ..., 1). The elements of START correspond, in order, to
7239 the variable’s dimensions. Hence, if the variable is a record
7240 variable, the last index would correspond to the starting record
7241 number for reading the data values.
7244 : A vector of integers specifying the number of indices selected along
7245 each dimension. To read a single value, for example, specify COUNT
7246 as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7247 the variable’s dimensions. Hence, if the variable is a record
7248 variable, the last element of COUNT corresponds to a count of the
7249 number of records to read.
7251 Note: setting any element of the count array to zero causes the
7252 function to exit without error, and without doing anything.
7255 : A vector of integers specifying, for each dimension, the interval
7256 between selected indices or the value 0. The elements of the vector
7257 correspond, in order, to the variable’s dimensions. A value of 1
7258 accesses adjacent values of the netCDF variable in the corresponding
7259 dimension; a value of 2 accesses every other value of the netCDF
7260 variable in the corresponding dimension; and so on. A 0 argument is
7261 treated as (1, 1, ..., 1).
7264 : A vector of integers that specifies the mapping between the
7265 dimensions of a netCDF variable and the in-memory structure of the
7266 internal data array. IMAP(1) gives the distance between elements of
7267 the internal array corresponding to the most rapidly varying
7268 dimension of the netCDF variable. IMAP(N) (where N is the rank of
7269 the netCDF variable) gives the distance between elements of the
7270 internal array corresponding to the most slowly varying dimension of
7271 the netCDF variable. Intervening IMAP elements correspond to other
7272 dimensions of the netCDF variable in the obvious way. Distances
7273 between elements are specified in units of elements (the distance
7274 between internal elements that occupy adjacent memory locations is 1
7275 and not the element’s byte-length as in netCDF 2).
7283 : The block of data values to be read. The data should be of the type
7284 appropriate for the function called. You cannot read CHARACTER data
7285 from a numeric variable or numeric data from a text variable. For
7286 numeric data, if the type of data differs from the netCDF variable
7287 type, type conversion will occur (see [(netcdf)Type
7288 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7289 in The NetCDF Users Guide).
7294 NF\_GET\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
7295 Otherwise, the returned status indicates an error. Possible causes of
7298 - The variable ID is invalid for the specified netCDF dataset.
7299 - The specified START, COUNT, and STRIDE generate an index which is
7300 out of range. Note that no error checking is possible on the imap
7302 - One or more of the values are out of the range of values
7303 representable by the desired type.
7304 - The specified netCDF is in define mode rather than data mode.
7305 - The specified netCDF ID does not refer to an open netCDF dataset.
7310 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
7311 variable and an internal array of the same shape:
7316 REAL A(2,3,4) ! same shape as netCDF variable
7318 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
7319 ! ---------------- ----------------------
7320 ! most rapidly varying 1
7321 ! intermediate 2 (=IMAP(1)*2)
7322 ! most slowly varying 6 (=IMAP(2)*3)
7325 Using the IMAP vector above with NF\_GET\_VARM\_REAL obtains the same
7326 rlt as simply using NF\_GET\_VAR\_REAL.
7328 Here is an example of using NF\_GET\_VARM\_REAL to transpose a netCDF
7329 variable named rh which is described by the FORTRAN declaration REAL
7330 RH(4,6) (note the size and order of the dimensions):
7335 INCLUDE 'netcdf.inc'
7337 PARAMETER (NDIM=2) ! rank of netCDF variable
7338 INTEGER NCID ! netCDF dataset ID
7339 INTEGER STATUS ! return code
7340 INTEGER RHID ! variable ID
7341 INTEGER START(NDIM) ! netCDF variable start point
7342 INTEGER COUNT(NDIM) ! size of internal array
7343 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7344 INTEGER IMAP(NDIM) ! internal array inter-element distances
7345 REAL RH(6,4) ! note transposition of netCDF variable dimensions
7346 DATA START /1, 1/ ! start at first netCDF variable element
7347 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
7348 ! to netCDF variable -- not internal array
7349 DATA STRIDE /1, 1/ ! sample every netCDF element
7350 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
7352 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7353 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7355 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7356 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7358 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7359 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7362 Here is another example of using NF\_GET\_VARM\_REAL to simultaneously
7363 transpose andbsample the same netCDF variable, by accessing every
7364 other point of the netCDF variable:
7369 INCLUDE 'netcdf.inc'
7371 PARAMETER (NDIM=2) ! rank of netCDF variable
7372 INTEGER NCID ! netCDF dataset ID
7373 INTEGER STATUS ! return code
7374 INTEGER RHID ! variable ID
7375 INTEGER START(NDIM) ! netCDF variable start point
7376 INTEGER COUNT(NDIM) ! size of internal array
7377 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7378 INTEGER IMAP(NDIM) ! internal array inter-element distances
7379 REAL RH(3,2) ! note transposition of bsampled) dimensions
7380 DATA START /1, 1/ ! start at first netCDF variable value
7381 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
7382 ! to netCDF variable -- not internal array
7383 DATA STRIDE /2, 2/ ! sample every other netCDF element
7384 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
7386 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7387 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7389 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7390 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7392 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7393 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7396 6.29 Reading and Writing Character String Values
7397 ------------------------------------------------
7399 Character strings are not a primitive netCDF external data type, in part
7400 because FORTRAN does notpport the abstraction of variable-length
7401 character strings (the FORTRAN LEN function returns the static length of
7402 a character string, not its dynamic length). As a rlt, a character
7403 string cannot be written or read as a single object in the netCDF
7404 interface. Instead, a character string must be treated as an array of
7405 characters, and array access must be used to read and write character
7406 strings as variable data in netCDF datasets. Furthermore,
7407 variable-length strings are notpported by the netCDF interface except
7408 by convention; for example, you may treat a zero byte as terminating a
7409 character string, but you must explicitly specify the length of strings
7410 to be read from and written to netCDF variables.
7412 Character strings as attribute values are easier to use, since the
7413 strings are treated as a single unit for access. However, the value of a
7414 character-string attribute is still an array of characters with an
7415 explicit length that must be specified when the attribute is defined.
7417 When you define a variable that will have character-string values, use a
7418 character-position dimension as the most quickly varying dimension for
7419 the variable (the first dimension for the variable in FORTRAN). The
7420 length of the character-position dimension will be the maximum string
7421 length of any value to be stored in the character-string variable. Space
7422 for maximum-length strings will be allocated in the disk representation
7423 of character-string variables whether you use the space or not. If two
7424 or more variables have the same maximum length, the same
7425 character-position dimension may be used in defining the variable
7428 To write a character-string value into a character-string variable, use
7429 either entire variable access or array access. The latter requires that
7430 you specify both a corner and a vector of edge lengths. The
7431 character-position dimension at the corner should be one for FORTRAN. If
7432 the length of the string to be written is n, then the vector of edge
7433 lengths will specify n in the character-position dimension, and one for
7434 all the other dimensions:(n, 1, 1, ..., 1).
7436 In FORTRAN, fixed-length strings may be written to a netCDF dataset
7437 without a terminating character, to save space. Variable-length strings
7438 should follow the C convention of writing strings with a terminating
7439 zero byte so that the intended length of the string can be determined
7440 when it is later read by either C or FORTRAN programs.
7442 The FORTRAN interface for reading and writing strings requires the use
7443 of different functions for accessing string values and numeric values,
7444 because standard FORTRAN does not permit the same formal parameter to be
7445 used for both character values and numeric values. An additional
7446 argument, specifying the declared length of the character string passed
7447 as a value, is required for NF\_PUT\_VARA\_TEXT and NF\_GET\_VARA\_TEXT.
7448 The actual length of the string is specified as the value of the
7449 edge-length vector corresponding to the character-position dimension.
7451 Here is an example that defines a record variable, tx, for character
7452 strings and stores a character-string value into the third record using
7453 NF\_PUT\_VARA\_TEXT. In this example, we ame the string variable and
7454 data are to be added to an existing netCDF dataset named foo.nc that
7455 already has an unlimited record dimension time.
7460 INCLUDE 'netcdf.inc'
7462 INTEGER TDIMS, TXLEN
7463 PARAMETER (TDIMS=2) ! number of TX dimensions
7464 PARAMETER (TXLEN = 15) ! length of example string
7466 INTEGER CHID ! char position dimension id
7467 INTEGER TIMEID ! record dimension id
7468 INTEGER TXID ! variable ID
7469 INTEGER TXDIMS(TDIMS) ! variable shape
7470 INTEGER TSTART(TDIMS), TCOUNT(TDIMS)
7471 CHARACTER*40 TXVAL ! max length 40
7472 DATA TXVAL /'example string'/
7474 TXVAL(TXLEN:TXLEN) = CHAR(0) ! null terminate
7476 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
7477 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7478 STATUS = NF_REDEF(NCID) ! enter define mode
7479 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7481 ! define character-position dimension for strings of max length 40
7482 STATUS = NF_DEF_DIM(NCID, "chid", 40, CHID)
7483 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7485 ! define a character-string variable
7486 TXDIMS(1) = CHID ! character-position dimension first
7488 STATUS = NF_DEF_VAR(NCID, "tx", NF_CHAR, TDIMS, TXDIMS, TXID)
7489 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7491 STATUS = NF_ENDDEF(NCID) ! leave define mode
7492 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7494 ! write txval into tx netCDF variable in record 3
7495 TSTART(1) = 1 ! start at beginning of variable
7496 TSTART(2) = 3 ! record number to write
7497 TCOUNT(1) = TXLEN ! number of chars to write
7498 TCOUNT(2) = 1 ! only write one record
7499 STATUS = NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL)
7500 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7506 What happens when you try to read a value that was never written in an
7507 open netCDF dataset? You might expect that this should always be an
7508 error, and that you should get an error message or an error status
7509 returned. You do get an error if you try to read data from a netCDF
7510 dataset that is not open for reading, if the variable ID is invalid for
7511 the specified netCDF dataset, or if the specified indices are not
7512 properly within the range defined by the dimension lengths of the
7513 specified variable. Otherwise, reading a value that was not written
7514 returns a special fill value used to fill in any undefined values when a
7515 netCDF variable is first written.
7517 You may ignore fill values and use the entire range of a netCDF external
7518 data type, but in this case you should makere you write all data
7519 values before reading them. If you know you will be writing all the data
7520 before reading it, you can specify that no prefilling of variables with
7521 fill values will occur by calling NF\_SET\_FILL before writing. This may
7522 provide a significant performance gain for netCDF writes.
7524 The variable attribute \_FillValue may be used to specify the fill value
7525 for a variable. Their are default fill values for each type, defined in
7526 the include file netcdf.inc: NF\_FILL\_CHAR, NF\_FILL\_INT1 (same as
7527 NF\_FILL\_BYTE), NF\_FILL\_INT2 (same as NF\_FILL\_SHORT),
7528 NF\_FILL\_INT, NF\_FILL\_REAL (same as NF\_FILL\_FLOAT), and
7531 The netCDF byte and character types have different default fill values.
7532 The default fill value for characters is the zero byte, a useful value
7533 for detecting the end of variable-length C character strings. If you
7534 need a fill value for a byte variable, it is recommended that you
7535 explicitly define an appropriate \_FillValue attribute, as generic
7536 utilitiesch as ncdump will not ame a default fill value for byte
7539 Type conversion for fill values is identical to type conversion for
7540 other values: attempting to convert a value from one type to another
7541 type that can’t represent the value rlts in a range error. Such
7542 errors may occur on writing or reading values from a larger type ch
7543 as double) to a smaller type ch as float), if the fill value for the
7544 larger type cannot be represented in the smaller type.
7546 6.31 NF\_RENAME\_VAR
7547 --------------------
7549 The function NF\_RENAME\_VAR changes the name of a netCDF variable in an
7550 open netCDF dataset. If the new name is longer than the old name, the
7551 netCDF dataset must be in define mode. You cannot rename a variable to
7552 have the name of any existing variable.
7560 INTEGER FUNCTION NF_RENAME_VAR (INTEGER NCID, INTEGER VARID,
7561 CHARACTER*(*) NEWNAM)
7565 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7571 : New name for the specified variable.
7576 NF\_RENAME\_VAR returns the value NF\_NOERR if no errors occurred.
7577 Otherwise, the returned status indicates an error. Possible causes of
7580 - The new name is in use as the name of another variable.
7581 - The variable ID is invalid for the specified netCDF dataset.
7582 - The specified netCDF ID does not refer to an open netCDF dataset.
7587 Here is an example using NF\_RENAME\_VAR to rename the variable rh to
7588 rel\_hum in an existing netCDF dataset named foo.nc:
7593 INCLUDE 'netcdf.inc'
7595 INTEGER STATUS, NCID
7596 INTEGER RHID ! variable ID
7598 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7599 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7601 STATUS = NF_REDEF (NCID) ! enter definition mode
7602 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7603 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7604 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7605 STATUS = NF_RENAME_VAR (NCID, RHID, 'rel_hum')
7606 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7607 STATUS = NF_ENDDEF (NCID) ! leave definition mode
7608 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7612 6.32 Change between Collective and Independent Parallel Access: NF\_VAR\_PAR\_ACCESS
7613 ------------------------------------------------------------------------------------
7615 The function NF\_VAR\_PAR\_ACCESS changes whether read/write operations
7616 on a parallel file system are performed collectively or independently
7617 (the default) on the variable. This function can only be called if the
7618 file was created with NF\_CREATE\_PAR (see
7619 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)) or opened with NF\_OPEN\_PAR
7620 (see [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)).
7622 This function is only available if the netCDF library was built with a
7623 HDF5 library for which –enable-parallel was used, and which was linked
7624 (like HDF5) to MPI libraries.
7626 Calling this function affects only the open file - information about
7627 whether a variable is to be accessed collectively or independently is
7628 not written to the data file. Every time you open a file on a parallel
7629 file system, all variables default to independent operations. The change
7630 a variable to collective lasts only as long as that file is open.
7632 The variable can be changed from collective to independent, and back, as
7641 INTEGER NF_VAR_PAR_ACCESS(INTEGER NCID, INTEGER VARID, INTEGER ACCESS);
7645 : NetCDF ID, from a previous call to NF\_OPEN\_PAR (see
7646 [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)) or NF\_CREATE\_PAR (see
7647 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)).
7653 : NF\_INDEPENDENT to set this variable to independent operations.
7654 NF\_COLLECTIVE to set it to collective operations.
7663 : No variable found.
7666 : Not a netCDF-4 file.
7669 : File not opened for parallel access.
7674 This example comes from test program nf\_test/ftst\_parallel.F. For this
7675 test to be run, netCDF must have been built with a parallel-enabled
7676 HDF5, and –enable-parallel-tests must have been used when configuring
7682 retval = nf_var_par_access(ncid, varid, nf_collective)
7683 if (retval .ne. nf_noerr) stop 2
7690 7.1 Attributes Introduction
7691 ---------------------------
7693 Attributes may be associated with each netCDF variable to specifych
7694 properties as units, special values, maximum and minimum valid values,
7695 scaling factors, and offsets. Attributes for a netCDF dataset are
7696 defined when the dataset is first created, while the netCDF dataset is
7697 in define mode. Additional attributes may be added later by reentering
7698 define mode. A netCDF attribute has a netCDF variable to which it is
7699 assigned, a name, a type, a length, and a sequence of one or more
7700 values. An attribute is designated by its variable ID and name. When an
7701 attribute name is not known, it may be designated by its variable ID and
7702 number in order to determine its name, using the function
7705 The attributes associated with a variable are typically defined
7706 immediately after the variable is created, while still in define mode.
7707 The data type, length, and value of an attribute may be changed even
7708 when in data mode, as long as the changed attribute requires no more
7709 space than the attribute as originally defined.
7711 It is also possible to have attributes that are not associated with any
7712 variable. These are called global attributes and are identified by using
7713 NF\_GLOBAL as a variable pseudo-ID. Global attributes are ally
7714 related to the netCDF dataset as a whole and may be used for purposes
7715 such as providing a title or processing history for a netCDF dataset.
7717 Attributes are much more useful when they follow established community
7718 conventions. See [(netcdf)Attribute
7719 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
7720 Conventions’ in The NetCDF Users Guide.
7722 Operationspported on attributes are:
7724 - Create an attribute, given its variable ID, name, data type, length,
7726 - Get attribute’s data type and length from its variable ID and name.
7727 - Get attribute’s value from its variable ID and name.
7728 - Copy attribute from one netCDF variable to another.
7729 - Get name of attribute from its number.
7730 - Rename an attribute.
7731 - Delete an attribute.
7733 7.2 NF\_PUT\_ATT\_ type
7734 -----------------------
7736 The function NF\_PUT\_ATT\_ type adds or changes a variable attribute or
7737 global attribute of an open netCDF dataset. If this attribute is new, or
7738 if the space required to store the attribute is greater than before, the
7739 netCDF dataset must be in define mode.
7744 Although it’s possible to create attributes of all types, text and
7745 double attributes are adequate for most purposes.
7750 INTEGER FUNCTION NF_PUT_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7751 CHARACTER*(*) NAME, INTEGER LEN,
7753 INTEGER FUNCTION NF_PUT_ATT_INT1 (INTEGER NCID, INTEGER VARID,
7754 CHARACTER*(*) NAME, INTEGER XTYPE,
7755 LEN, INTEGER*1 I1VALS(*))
7756 INTEGER FUNCTION NF_PUT_ATT_INT2 (INTEGER NCID, INTEGER VARID,
7757 CHARACTER*(*) NAME, INTEGER XTYPE,
7758 LEN, INTEGER*2 I2VALS(*))
7759 INTEGER FUNCTION NF_PUT_ATT_INT (INTEGER NCID, INTEGER VARID,
7760 CHARACTER*(*) NAME, INTEGER XTYPE,
7761 LEN, INTEGER IVALS(*))
7762 INTEGER FUNCTION NF_PUT_ATT_REAL (INTEGER NCID, INTEGER VARID,
7763 CHARACTER*(*) NAME, INTEGER XTYPE,
7765 INTEGER FUNCTION NF_PUT_ATT_DOUBLE(INTEGER NCID, INTEGER VARID,
7766 CHARACTER*(*) NAME, INTEGER XTYPE,
7767 LEN, DOUBLE DVALS(*))
7768 INTEGER FUNCTION NF_PUT_ATT (INTEGER NCID, INTEGER VARID,
7769 CHARACTER*(*) NAME, INTEGER XTYPE,
7774 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7777 : Variable ID of the variable to which the attribute will be assigned
7778 or NF\_GLOBAL for a global attribute.
7781 : Attribute name. Attribute name conventions are amed by some
7782 netCDF generic applications, e.g., ‘units’ as the name for a string
7783 attribute that gives the units for a netCDF variable. See
7784 [(netcdf)Attribute Conventions](netcdf.html#Attribute-Conventions)
7785 ‘Attribute Conventions’ in The NetCDF Users Guide.
7788 : One of the set of predefined netCDF external data types. The type of
7789 this parameter, NF\_TYPE, is defined in the netCDF header file. The
7790 valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
7791 NF\_INT, NF\_FLOAT, and NF\_DOUBLE. Although it’s possible to create
7792 attributes of all types, NF\_CHAR and NF\_DOUBLE attributes are
7793 adequate for most purposes.
7796 : Number of values provided for the attribute.
7805 : An array of LEN attribute values. The data should be of a type
7806 appropriate for the function called. You cannot write CHARACTER data
7807 into a numeric attribute or numeric data into a text attribute. For
7808 numeric data, if the type of data differs from the attribute type,
7809 type conversion will occur See [(netcdf)Type
7810 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7811 in The NetCDF Users Guide.
7816 NF\_PUT\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
7817 Otherwise, the returned status indicates an error. Possible causes of
7820 - The variable ID is invalid for the specified netCDF dataset.
7821 - The specified netCDF type is invalid.
7822 - The specified length is negative.
7823 - The specified open netCDF dataset is in data mode and the specified
7824 attribute would expand.
7825 - The specified open netCDF dataset is in data mode and the specified
7826 attribute does not already exist.
7827 - The specified netCDF ID does not refer to an open netCDF dataset.
7828 - The number of attributes for this variable exceeds NF\_MAX\_ATTRS.
7833 Here is an example using NF\_PUT\_ATT\_DOUBLE to add a variable
7834 attribute named valid\_range for a netCDF variable named rh and a global
7835 attribute named title to an existing netCDF dataset named foo.nc:
7840 INCLUDE 'netcdf.inc'
7842 INTEGER STATUS, NCID
7843 INTEGER RHID ! variable ID
7845 DATA RHRNGE /0.0D0, 100.0D0/
7847 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7848 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7850 STATUS = NF_REDEF (NCID) ! enter define mode
7851 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7852 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7853 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7855 STATUS = NF_PUT_ATT_DOUBLE (NCID, RHID, 'valid_range', NF_DOUBLE, &
7857 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7858 STATUS = NF_PUT_ATT_TEXT (NCID, NF_GLOBAL, 'title', 19,
7859 'example netCDF dataset')
7860 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7862 STATUS = NF_ENDDEF (NCID) ! leave define mode
7863 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7866 7.3 NF\_INQ\_ATT Family
7867 -----------------------
7869 This family of functions returns information about a netCDF attribute.
7870 All but one of these functions require the variable ID and attribute
7871 name; the exception is NF\_INQ\_ATTNAME. Information about an attribute
7872 includes its type, length, name, and number. See the NF\_GET\_ATT family
7873 for getting attribute values.
7875 The function NF\_INQ\_ATTNAME gets the name of an attribute, given its
7876 variable ID and number. This function is useful in generic applications
7877 that need to get the names of all the attributes associated with a
7878 variable, since attributes are accessed by name rather than number in
7879 all other attribute functions. The number of an attribute is more
7880 volatile than the name, since it can change when other attributes of the
7881 same variable are deleted. This is why an attribute number is not called
7884 The function NF\_INQ\_ATT returns the attribute’s type and length. The
7885 other functions each return just one item of information about an
7894 INTEGER FUNCTION NF_INQ_ATT (INTEGER NCID, INTEGER VARID,
7895 CHARACTER*(*) NAME, INTEGER xtype,
7897 INTEGER FUNCTION NF_INQ_ATTTYPE(INTEGER NCID, INTEGER VARID,
7898 CHARACTER*(*) NAME, INTEGER xtype)
7899 INTEGER FUNCTION NF_INQ_ATTLEN (INTEGER NCID, INTEGER VARID,
7900 CHARACTER*(*) NAME, INTEGER len)
7901 INTEGER FUNCTION NF_INQ_ATTNAME(INTEGER NCID, INTEGER VARID,
7902 INTEGER ATTNUM, CHARACTER*(*) name)
7903 INTEGER FUNCTION NF_INQ_ATTID (INTEGER NCID, INTEGER VARID,
7904 CHARACTER*(*) NAME, INTEGER attnum)
7908 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7911 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
7915 : Attribute name. For NF\_INQ\_ATTNAME, this is a pointer to the
7916 location for the returned attribute name.
7919 : Returned attribute type, one of the set of predefined netCDF
7920 external data types. The valid netCDF external data types are
7921 NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, and NF\_DOUBLE.
7924 : Returned number of values currently stored in the attribute. For a
7925 string-valued attribute, this is the number of characters in the
7929 : For NF\_INQ\_ATTNAME, the input attribute number; for
7930 NF\_INQ\_ATTID, the returned attribute number. The attributes for
7931 each variable are numbered from 1 (the first attribute) to NATTS,
7932 where NATTS is the number of attributes for the variable, as
7933 returned from a call to NF\_INQ\_VARNATTS.
7935 (If you already know an attribute name, knowing its number is not
7936 very useful, because accessing information about an attribute
7942 Each function returns the value NF\_NOERR if no errors occurred.
7943 Otherwise, the returned status indicates an error. Possible causes of
7946 - The variable ID is invalid for the specified netCDF dataset.
7947 - The specified attribute does not exist.
7948 - The specified netCDF ID does not refer to an open netCDF dataset.
7949 - For NF\_INQ\_ATTNAME, the specified attribute number is negative or
7950 more than the number of attributes defined for the specified
7956 Here is an example using NF\_INQ\_ATT to find out the type and length of
7957 a variable attribute named valid\_range for a netCDF variable named rh
7958 and a global attribute named title in an existing netCDF dataset named
7964 INCLUDE 'netcdf.inc'
7966 INTEGER STATUS, NCID
7967 INTEGER RHID ! variable ID
7968 INTEGER VRLEN, TLEN ! attribute lengths
7970 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7971 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7973 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7974 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7976 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
7977 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7978 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
7979 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7982 7.4 NF\_GET\_ATT\_ type
7983 -----------------------
7985 Members of the NF\_GET\_ATT\_ type family of functions get the value(s)
7986 of a netCDF attribute, given its variable ID and name.
7994 INTEGER FUNCTION NF_GET_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7997 INTEGER FUNCTION NF_GET_ATT_INT1 (INTEGER NCID, INTEGER VARID,
7999 INTEGER*1 i1vals(*))
8000 INTEGER FUNCTION NF_GET_ATT_INT2 (INTEGER NCID, INTEGER VARID,
8002 INTEGER*2 i2vals(*))
8003 INTEGER FUNCTION NF_GET_ATT_INT (INTEGER NCID, INTEGER VARID,
8006 INTEGER FUNCTION NF_GET_ATT_REAL (INTEGER NCID, INTEGER VARID,
8009 INTEGER FUNCTION NF_GET_ATT_DOUBLE (INTEGER NCID, INTEGER VARID,
8012 INTEGER FUNCTION NF_GET_ATT (INTEGER NCID, INTEGER VARID,
8013 CHARACTER*(*) NAME, * vals(*))
8017 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8020 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
8033 : Returned attribute values. All elements of the vector of attribute
8034 values are returned, so you must provide enough space to hold them.
8035 If you don’t know how much space to reserve, call NF\_INQ\_ATTLEN
8036 first to find out the length of the attribute. You cannot read
8037 character data from a numeric variable or numeric data from a text
8038 variable. For numeric data, if the type of data differs from the
8039 netCDF variable type, type conversion will occur. See [(netcdf)Type
8040 Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
8041 in The The NetCDF Users Guide.
8046 NF\_GET\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
8047 Otherwise, the returned status indicates an error. Possible causes of
8050 - The variable ID is invalid for the specified netCDF dataset.
8051 - The specified attribute does not exist.
8052 - The specified netCDF ID does not refer to an open netCDF dataset.
8053 - One or more of the attribute values are out of the range of values
8054 representable by the desired type.
8059 Here is an example using NF\_GET\_ATT\_DOUBLE to determine the values of
8060 a variable attribute named valid\_range for a netCDF variable named rh
8061 and a global attribute named title in an existing netCDF dataset named
8062 foo.nc. In this example, it is amed that we don’t know how many
8063 values will be returned, but that we do know the types of the
8064 attributes. Hence, to allocate enough space to store them, we must first
8065 inquire about the length of the attributes.
8070 INCLUDE 'netcdf.inc'
8072 PARAMETER (MVRLEN=3) ! max number of "valid_range" values
8073 PARAMETER (MTLEN=80) ! max length of "title" attribute
8074 INTEGER STATUS, NCID
8075 INTEGER RHID ! variable ID
8076 INTEGER VRLEN, TLEN ! attribute lengths
8077 DOUBLE PRECISION VRVAL(MVRLEN) ! vr attribute values
8078 CHARACTER*80 TITLE ! title attribute values
8080 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8081 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8083 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8084 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8086 ! find out attribute lengths, to makere we have enough space
8087 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
8088 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8089 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
8090 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8091 ! get attribute values, if not too big
8092 IF (VRLEN .GT. MVRLEN) THEN
8093 WRITE (*,*) 'valid_range attribute too big!'
8096 STATUS = NF_GET_ATT_DOUBLE (NCID, RHID, 'valid_range', VRVAL)
8097 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8099 IF (TLEN .GT. MTLEN) THEN
8100 WRITE (*,*) 'title attribute too big!'
8103 STATUS = NF_GET_ATT_TEXT (NCID, NF_GLOBAL, 'title', TITLE)
8104 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8111 The function NF\_COPY\_ATT copies an attribute from one open netCDF
8112 dataset to another. It can also be used to copy an attribute from one
8113 variable to another within the same netCDF.
8115 If used to copy an attribute of user-defined type, then that
8116 user-defined type must already be defined in the target file. In the
8117 case of user-defined attributes, enddef/redef is called for ncid\_in and
8118 ncid\_out if they are in define mode. (This is the ere that all
8119 user-defined types are committed to the file(s) before the copy is
8128 INTEGER FUNCTION NF_COPY_ATT (INTEGER NCID_IN, INTEGER VARID_IN,
8129 CHARACTER*(*) NAME, INTEGER NCID_OUT,
8134 : The netCDF ID of an input netCDF dataset from which the attribute
8135 will be copied, from a previous call to NF\_OPEN or NF\_CREATE.
8138 : ID of the variable in the input netCDF dataset from which the
8139 attribute will be copied, or NF\_GLOBAL for a global attribute.
8142 : Name of the attribute in the input netCDF dataset to be copied.
8145 : The netCDF ID of the output netCDF dataset to which the attribute
8146 will be copied, from a previous call to NF\_OPEN or NF\_CREATE. It
8147 is permissible for the input and output netCDF IDs to be the same.
8148 The output netCDF dataset should be in define mode if the attribute
8149 to be copied does not already exist for the target variable, or if
8150 it would cause an existing target attribute to grow.
8153 : ID of the variable in the output netCDF dataset to which the
8154 attribute will be copied, or NF\_GLOBAL to copy to a global
8160 NF\_COPY\_ATT returns the value NF\_NOERR if no errors occurred.
8161 Otherwise, the returned status indicates an error. Possible causes of
8164 - The input or output variable ID is invalid for the specified netCDF
8166 - The specified attribute does not exist.
8167 - The output netCDF is not in define mode and the attribute is new for
8168 the output dataset is larger than the existing attribute.
8169 - The input or output netCDF ID does not refer to an open netCDF
8175 Here is an example using NF\_COPY\_ATT to copy the variable attribute
8176 units from the variable rh in an existing netCDF dataset named foo.nc to
8177 the variable avgrh in another existing netCDF dataset named bar.nc,
8178 aming that the variable avgrh already exists, but does not yet have a
8184 INCLUDE 'netcdf.inc'
8186 INTEGER STATUS ! error status
8187 INTEGER NCID1, NCID2 ! netCDF IDs
8188 INTEGER RHID, AVRHID ! variable IDs
8190 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID1)
8191 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8192 STATUS = NF_OPEN ('bar.nc', NF_WRITE, NCID2)
8193 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8195 STATUS = NF_INQ_VARID (NCID1, 'rh', RHID)
8196 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8197 STATUS = NF_INQ_VARID (NCID2, 'avgrh', AVRHID)
8198 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8200 STATUS = NF_REDEF (NCID2) ! enter define mode
8201 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8202 ! copy variable attribute from "rh" to "avgrh"
8203 STATUS = NF_COPY_ATT (NCID1, RHID, 'units', NCID2, AVRHID)
8204 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8206 STATUS = NF_ENDDEF (NCID2) ! leave define mode
8207 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8213 The function NF\_RENAME\_ATT changes the name of an attribute. If the
8214 new name is longer than the original name, the netCDF dataset must be in
8215 define mode. You cannot rename an attribute to have the same name as
8216 another attribute of the same variable.
8224 INTEGER FUNCTION NF_RENAME_ATT (INTEGER NCID, INTEGER VARID,
8226 CHARACTER*(*) NEWNAME)
8230 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE
8233 : ID of the attribute’s variable, or NF\_GLOBAL for a global attribute
8236 : The current attribute name.
8239 : The new name to be assigned to the specified attribute. If the new
8240 name is longer than the current name, the netCDF dataset must be in
8246 NF\_RENAME\_ATT returns the value NF\_NOERR if no errors occurred.
8247 Otherwise, the returned status indicates an error. Possible causes of
8250 - The specified variable ID is not valid.
8251 - The new attribute name is already in use for another attribute of
8252 the specified variable.
8253 - The specified netCDF dataset is in data mode and the new name is
8254 longer than the old name.
8255 - The specified attribute does not exist.
8256 - The specified netCDF ID does not refer to an open netCDF dataset.
8261 Here is an example using NF\_RENAME\_ATT to rename the variable
8262 attribute units to Units for a variable rh in an existing netCDF dataset
8268 INCLUDE "netcdf.inc"
8270 INTEGER STATUS ! error status
8271 INTEGER NCID ! netCDF ID
8272 INTEGER RHID ! variable ID
8274 STATUS = NF_OPEN ("foo.nc", NF_NOWRITE, NCID)
8275 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8277 STATUS = NF_INQ_VARID (NCID, "rh", RHID)
8278 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8281 STATUS = NF_RENAME_ATT (NCID, RHID, "units", "Units")
8282 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8288 The function NF\_DEL\_ATT deletes a netCDF attribute from an open netCDF
8289 dataset. The netCDF dataset must be in define mode.
8294 INTEGER FUNCTION NF\_DEL\_ATT (INTEGER NCID, INTEGER VARID,
8295 CHARACTER\*(\*) NAME)
8298 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8301 : ID of the attribute’s variable, or NF\_GLOBAL for a global
8305 : The name of the attribute to be deleted.
8310 NF\_DEL\_ATT returns the value NF\_NOERR if no errors occurred.
8311 Otherwise, the returned status indicates an error. Possible causes of
8314 - The specified variable ID is not valid.
8315 - The specified netCDF dataset is in data mode.
8316 - The specified attribute does not exist.
8317 - The specified netCDF ID does not refer to an open netCDF dataset.
8322 Here is an example using NF\_DEL\_ATT to delete the variable attribute
8323 Units for a variable rh in an existing netCDF dataset named foo.nc:
8328 INCLUDE 'netcdf.inc'
8330 INTEGER STATUS ! error status
8331 INTEGER NCID ! netCDF ID
8332 INTEGER RHID ! variable ID
8334 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8335 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8337 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8338 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8341 STATUS = NF_REDEF (NCID) ! enter define mode
8342 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8343 STATUS = NF_DEL_ATT (NCID, RHID, 'Units')
8344 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8345 STATUS = NF_ENDDEF (NCID) ! leave define mode
8346 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8349 A. NetCDF 2 to NetCDF 3 Fortran 77 Transition Guide {.appendix}
8350 ===================================================
8352 A.1 Overview of FORTRAN interface changes
8353 -----------------------------------------
8355 NetCDF version 3 includes a complete rewrite of the netCDF library. It
8356 is about twice as fast as the previous version. The netCDF file format
8357 is unchanged, so files written with version 3 can be read with version 2
8358 code and vice versa.
8360 The core library is now written in ANSI C. You must have an ANSI C
8361 compiler to compile this version. The FORTRAN interface is layered on
8362 top of the C interface using a different technique than was used in
8365 Rewriting the library offered an opportunity to implement improved C and
8366 FORTRAN interfaces that provide some significant benefits:
8368 - type safety, by eliminating the need to use type punning in
8370 - automatic type conversions, by eliminating the undesirable coupling
8371 between the language-independent external netCDF types (NF\_BYTE,
8372 ..., NF\_DOUBLE) and language-dependent internal data types (INT\*1,
8373 ..., DOUBLE PRECISION);
8374 - pport for future enhancements, by eliminating obstacles to the
8375 clean addition ofpport for packed data and multithreading;
8376 - more standard error behavior, by uniformly communicating an error
8377 status back to the calling program in the return value of each
8380 It is not necessary to rewrite programs that use the version 2 FORTRAN
8381 interface, because the netCDF-3 library includes a backward
8382 compatibility interface thatpports all the old functions, globals,
8383 and behavior. We are hoping that the benefits of the new interface will
8384 be an incentive to use it in new netCDF applications. It is possible to
8385 convert old applications to the new interface incrementally, replacing
8386 netCDF-2 calls with the corresponding netCDF-3 calls one at a time.
8388 Other changes in the implementation of netCDF rlt in improved
8389 portability, maintainability, and performance on most platforms. A clean
8390 separation between I/O and type layers facilitates platform-specific
8391 optimizations. The new library no longer uses a vendor-provided XDR
8392 library, which simplifies linking programs that use netCDF and speeds up
8393 data access significantly in most cases.
8395 A.2 The New FORTRAN Interface
8396 -----------------------------
8398 First, here’s an example of FORTRAN code that uses the netCDF-2
8404 ! Use a buffer big enough for values of any type
8405 DOUBLE PRECISION DBUF(NDATA)
8408 EQUIVALENCE (RBUF, DBUF), ...
8409 INT XTYPE ! to hold the actual type of the data
8410 INT STATUS ! for error status
8411 ! Get the actual data type
8412 CALL NCVINQ(NCID, VARID, ...,XTYPE, ...)
8415 CALL NCVGT(NCID, VARID, START, COUNT, DBUF, STATUS)
8416 IF(STATUS .NE. NCNOERR) THEN
8417 PRINT *, 'Cannot get data, error code =', STATUS
8421 IF (XTYPE .EQ. NCDOUBLE) THEN
8423 ELSEIF (XTYPE .EQ. NCFLOAT) THEN
8429 Here’s how you might handle this with the new netCDF-3 FORTRAN
8435 ! I want to use doubles for my analysis
8436 DOUBLE PRECISION DBUF(NDATA)
8438 ! So I use a function that gets the data as doubles.
8439 STATUS = NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, DBUF)
8440 IF(STATUS .NE. NF_NOERR) THEN
8441 PRINT *, 'Cannot get data, ', NF_STRERROR(STATUS)
8448 The example above illustrates changes in function names, data type
8449 conversion, and error handling, discussed in detail in thes
8452 A.3 Function Naming Conventions
8453 -------------------------------
8455 The netCDF-3 Fortran 77 library employs a naming convention intended to
8456 make netCDF programs more readable. For example, the name of the
8457 function to rename a variable is now NF\_RENAME\_VAR instead of the
8460 All netCDF-3 FORTRAN function names begin with the NF\_ prefix. The
8461 second part of the name is a verb, like GET, PUT, INQ (for inquire), or
8462 OPEN. The third part of the name is typically the object of the verb:
8463 for example DIM, VAR, or ATT for functions dealing with dimensions,
8464 variables, or attributes. To distinguish the various I/O operations for
8465 variables, a single character modifier is appended to VAR:
8467 - VAR entire variable access
8468 - VAR1 single value access
8469 - VARA array or array access
8470 - VARS strided access to absample of values
8471 - VARM mapped access to values not contiguous in memory
8473 At the end of the name for variable and attribute functions, there is a
8474 component indicating the type of the final argument: TEXT, INT1, INT2,
8475 INT, REAL, or DOUBLE. This part of the function name indicates the type
8476 of the data container you are using in your program: character string,
8477 1-byte integer, and so on.
8479 Also, all PARAMETER names in the public FORTRAN interface begin with the
8480 prefix NF\_. For example, the PARAMETER which was formerly MAXNCNAM is
8481 now NF\_MAX\_NAME, and the former FILFLOAT is now NF\_FILL\_FLOAT.
8483 As previously mentioned, all the old names are stillpported for
8484 backward compatibility.
8489 With the new interface, users need not be aware of the external type of
8490 numeric variables, since automatic conversion to or from any desired
8491 numeric type is now available. You can use this feature to simplify
8492 code, by making it independent of external types. The elimination of
8493 type punning prevents some kinds of type errors that could occur with
8494 the previous interface. Programs may be made more robust with the new
8495 interface, because they need not be changed to accommodate a change to
8496 the external type of a variable.
8498 If conversion to or from an external numeric type is necessary, it is
8499 handled by the library. This automatic conversion and separation of
8500 external data representation from internal data types will become even
8501 more important in netCDF version 4, when new external types will be
8502 added for packed data for which there is no natural corresponding
8503 internal type, for example, arrays of 11-bit values.
8505 Converting from one numeric type to another may rlt in an error if
8506 the target type is not capable of representing the converted value. (In
8507 netCDF-2,ch overflows can only happen in the XDR layer.) For example,
8508 a REAL may not be able to hold data stored externally as an NF\_DOUBLE
8509 (an IEEE floating-point number). When accessing an array of values, an
8510 NF\_ERANGE error is returned if one or more values are out of the range
8511 of representable values, but other values are converted properly.
8513 Note that mere loss of precision in type conversion does not return an
8514 error. Thus, if you read double precision values into an INTEGER, for
8515 example, no error rlts unless the magnitude of the double precision
8516 value exceeds the representable range of INTEGERs on your platform.
8517 Similarly, if you read a large integer into a REAL incapable of
8518 representing all the bits of the integer in its mantissa, this loss
8519 There are two new functions in netCDF-3 that don’t correspond to any
8520 netCDF-2 functions: NF\_INQ\_LIBVERS and NF\_STRERROR. The version ation
8521 The previous implementation returned an error when the same dimension
8522 was used more than once in specifying the shape of a variable in
8523 ncvardef. This restriction is relaxed in the netCDF-3 implementation,
8524 because an autocorrelation matrix is a good example where using the same
8525 dimension twice makes sense.
8527 In the new interface, units for the IMAP argument to the NF\_PUT\_VARM
8528 and NF\_GET\_VARM families of functions are now in terms of the number
8529 of data elements of the desired internal type, not in terms of bytes as
8530 in the netCDF version-2 mapped access interfaces.
8532 Following is a table of netCDF-2 function names and names of the
8533 corresponding netCDF-3 functions. For parameter lists of netCDF-2
8534 functions, see the netCDF-2 User’s Guide.
8546 : NF\_GET\_ATT\_DOUBLE, NF\_GET\_ATT\_REAL, NF\_GET\_ATT\_INT,
8547 NF\_GET\_ATT\_INT1, NF\_GET\_ATT\_INT2
8550 : NF\_GET\_ATT\_TEXT
8553 : NF\_INQ\_ATT, NF\_INQ\_ATTID, NF\_INQ\_ATTLEN, NF\_INQ\_ATTTYPE
8559 : NF\_PUT\_ATT\_DOUBLE, NF\_PUT\_ATT\_REAL, NF\_PUT\_ATT\_INT,
8560 NF\_PUT\_ATT\_INT1NF\_PUT
8562 B. Summary of FORTRAN 77 Interface {.appendix}
8563 ==================================
8565 Input parameters are in upper case, output parameters are in lower case.
8566 The FORTRAN types of all the parameters are listed alphabetically by
8567 parameter name below the function declarations.
8572 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
8573 CHARACTER*80 FUNCTION NF_STRERROR (NCERR)
8574 INTEGER FUNCTION NF_CREATE (PATH, CMODE, ncid)
8575 INTEGER FUNCTION NF_OPEN (PATH, MODE, ncid)
8576 INTEGER FUNCTION NF_SET_FILL (NCID, FILLMODE, old_mode)
8577 INTEGER FUNCTION NF_REDEF (NCID)
8578 INTEGER FUNCTION NF_ENDDEF (NCID)
8579 INTEGER FUNCTION NF_SYNC (NCID)
8580 INTEGER FUNCTION NF_ABORT (NCID)
8581 INTEGER FUNCTION NF_CLOSE (NCID)
8582 INTEGER FUNCTION NF_INQ (NCID, ndims, nvars, ngatts,
8584 INTEGER FUNCTION NF_INQ_NDIMS (NCID, ndims)
8585 INTEGER FUNCTION NF_INQ_NVARS (NCID, nvars)
8586 INTEGER FUNCTION NF_INQ_NATTS (NCID, ngatts)
8587 INTEGER FUNCTION NF_INQ_UNLIMDIM (NCID, unlimdimid)
8588 INTEGER FUNCTION NF_DEF_DIM (NCID, NAME, LEN, dimid)
8589 INTEGER FUNCTION NF_INQ_DIMID (NCID, NAME, dimid)
8590 INTEGER FUNCTION NF_INQ_DIM (NCID, DIMID, name, len)
8591 INTEGER FUNCTION NF_INQ_DIMNAME (NCID, DIMID, name)
8592 INTEGER FUNCTION NF_INQ_DIMLEN (NCID, DIMID, len)
8593 INTEGER FUNCTION NF_RENAME_DIM (NCID, DIMID, NAME)
8595 INTEGER FUNCTION NF_DEF_VAR (NCID, NAME, XTYPE, NDIMS, DIMIDS,
8597 INTEGER FUNCTION NF_INQ_VAR (NCID, VARID, name, xtype, ndims,
8599 INTEGER FUNCTION NF_INQ_VARID (NCID, NAME, varid)
8600 INTEGER FUNCTION NF_INQ_VARNAME (NCID, VARID, name)
8601 INTEGER FUNCTION NF_INQ_VARTYPE (NCID, VARID, xtype)
8602 INTEGER FUNCTION NF_INQ_VARNDIMS (NCID, VARID, ndims)
8603 INTEGER FUNCTION NF_INQ_VARDIMID (NCID, VARID, DIMIDS)
8604 INTEGER FUNCTION NF_INQ_VARNATTS (NCID, VARID, natts)
8605 INTEGER FUNCTION NF_RENAME_VAR (NCID, VARID, NAME)
8606 INTEGER FUNCTION NF_PUT_VAR_TEXT (NCID, VARID, TEXT)
8607 INTEGER FUNCTION NF_GET_VAR_TEXT (NCID, VARID, text)
8608 INTEGER FUNCTION NF_PUT_VAR_INT1 (NCID, VARID, I1VAL)
8609 INTEGER FUNCTION NF_GET_VAR_INT1 (NCID, VARID, i1val)
8610 INTEGER FUNCTION NF_PUT_VAR_INT2 (NCID, VARID, I2VAL)
8611 INTEGER FUNCTION NF_GET_VAR_INT2 (NCID, VARID, i2val)
8612 INTEGER FUNCTION NF_PUT_VAR_INT (NCID, VARID, IVAL)
8613 INTEGER FUNCTION NF_GET_VAR_INT (NCID, VARID, ival)
8614 INTEGER FUNCTION NF_PUT_VAR_REAL (NCID, VARID, RVAL)
8615 INTEGER FUNCTION NF_GET_VAR_REAL (NCID, VARID, rval)
8616 INTEGER FUNCTION NF_PUT_VAR_DOUBLE (NCID, VARID, DVAL)
8617 INTEGER FUNCTION NF_GET_VAR_DOUBLE (NCID, VARID, dval)
8618 INTEGER FUNCTION NF_PUT_VAR1_TEXT (NCID, VARID, INDEX, TEXT)
8619 INTEGER FUNCTION NF_GET_VAR1_TEXT (NCID, VARID, INDEX, text)
8620 INTEGER FUNCTION NF_PUT_VAR1_INT1 (NCID, VARID, INDEX, I1VAL)
8621 INTEGER FUNCTION NF_GET_VAR1_INT1 (NCID, VARID, INDEX, i1val)
8622 INTEGER FUNCTION NF_PUT_VAR1_INT2 (NCID, VARID, INDEX, I2VAL)
8623 INTEGER FUNCTION NF_GET_VAR1_INT2 (NCID, VARID, INDEX, i2val)
8624 INTEGER FUNCTION NF_PUT_VAR1_INT (NCID, VARID, INDEX, IVAL)
8625 INTEGER FUNCTION NF_GET_VAR1_INT (NCID, VARID, INDEX, ival)
8626 INTEGER FUNCTION NF_PUT_VAR1_REAL (NCID, VARID, INDEX, RVAL)
8627 INTEGER FUNCTION NF_GET_VAR1_REAL (NCID, VARID, INDEX, rval)
8628 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(NCID, VARID, INDEX, DVAL)
8629 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(NCID, VARID, INDEX, dval)
8630 INTEGER FUNCTION NF_PUT_VARA_TEXT (NCID, VARID, START, COUNT, TEXT)
8631 INTEGER FUNCTION NF_GET_VARA_TEXT (NCID, VARID, START, COUNT, text)
8632 INTEGER FUNCTION NF_PUT_VARA_INT1 (NCID, VARID, START, COUNT, I1VALS)
8633 INTEGER FUNCTION NF_GET_VARA_INT1 (NCID, VARID, START, COUNT, i1vals)
8634 INTEGER FUNCTION NF_PUT_VARA_INT2 (NCID, VARID, START, COUNT, I2VALS)
8635 INTEGER FUNCTION NF_GET_VARA_INT2 (NCID, VARID, START, COUNT, i2vals)
8636 INTEGER FUNCTION NF_PUT_VARA_INT (NCID, VARID, START, COUNT, IVALS)
8637 INTEGER FUNCTION NF_GET_VARA_INT (NCID, VARID, START, COUNT, ivals)
8638 INTEGER FUNCTION NF_PUT_VARA_REAL (NCID, VARID, START, COUNT, RVALS)
8639 INTEGER FUNCTION NF_GET_VARA_REAL (NCID, VARID, START, COUNT, rvals)
8640 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(NCID, VARID, START, COUNT, DVALS)
8641 INTEGER FUNCTION NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, dvals)
8642 INTEGER FUNCTION NF_PUT_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8644 INTEGER FUNCTION NF_GET_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8646 INTEGER FUNCTION NF_PUT_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8648 INTEGER FUNCTION NF_GET_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8650 INTEGER FUNCTION NF_PUT_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8652 INTEGER FUNCTION NF_GET_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8654 INTEGER FUNCTION NF_PUT_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8656 INTEGER FUNCTION NF_GET_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8658 INTEGER FUNCTION NF_PUT_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8660 INTEGER FUNCTION NF_GET_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8662 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8664 INTEGER FUNCTION NF_GET_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8666 INTEGER FUNCTION NF_PUT_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8668 INTEGER FUNCTION NF_GET_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8670 INTEGER FUNCTION NF_PUT_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8672 INTEGER FUNCTION NF_GET_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8674 INTEGER FUNCTION NF_PUT_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8676 INTEGER FUNCTION NF_GET_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8678 INTEGER FUNCTION NF_PUT_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8680 INTEGER FUNCTION NF_GET_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8682 INTEGER FUNCTION NF_PUT_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8684 INTEGER FUNCTION NF_GET_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8686 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8688 INTEGER FUNCTION NF_GET_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8691 INTEGER FUNCTION NF_INQ_ATT (NCID, VARID, NAME, xtype, len)
8692 INTEGER FUNCTION NF_INQ_ATTID (NCID, VARID, NAME, attnum)
8693 INTEGER FUNCTION NF_INQ_ATTTYPE (NCID, VARID, NAME, xtype)
8694 INTEGER FUNCTION NF_INQ_ATTLEN (NCID, VARID, NAME, len)
8695 INTEGER FUNCTION NF_INQ_ATTNAME (NCID, VARID, ATTNUM, name)
8696 INTEGER FUNCTION NF_COPY_ATT (NCID_IN, VARID_IN, NAME,
8697 NCID_OUT, VARID_OUT)
8698 INTEGER FUNCTION NF_RENAME_ATT (NCID, VARID, CURNAME, NEWNAME)
8699 INTEGER FUNCTION NF_DEL_ATT (NCID, VARID, NAME)
8700 INTEGER FUNCTION NF_PUT_ATT_TEXT (NCID, VARID, NAME, LEN, TEXT)
8701 INTEGER FUNCTION NF_GET_ATT_TEXT (NCID, VARID, NAME, text)
8702 INTEGER FUNCTION NF_PUT_ATT_INT1 (NCID, VARID, NAME, XTYPE, LEN,
8704 INTEGER FUNCTION NF_GET_ATT_INT1 (NCID, VARID, NAME, i1vals)
8705 INTEGER FUNCTION NF_PUT_ATT_INT2 (NCID, VARID, NAME, XTYPE, LEN,
8707 INTEGER FUNCTION NF_GET_ATT_INT2 (NCID, VARID, NAME, i2vals)
8708 INTEGER FUNCTION NF_PUT_ATT_INT (NCID, VARID, NAME, XTYPE, LEN,
8710 INTEGER FUNCTION NF_GET_ATT_INT (NCID, VARID, NAME, ivals)
8711 INTEGER FUNCTION NF_PUT_ATT_REAL (NCID, VARID, NAME, XTYPE, LEN,
8713 INTEGER FUNCTION NF_GET_ATT_REAL (NCID, VARID, NAME, rvals)
8714 INTEGER FUNCTION NF_PUT_ATT_DOUBLE (NCID, VARID, NAME, XTYPE, LEN,
8716 INTEGER FUNCTION NF_GET_ATT_DOUBLE (NCID, VARID, NAME, dvals)
8718 INTEGER ATTNUM ! attribute number
8719 INTEGER attnum ! returned attribute number
8720 INTEGER CMODE ! NF_NOCLOBBER, NF_SHARE flags expression
8721 INTEGER COUNT ! array of edge lengths of block of values
8722 CHARACTER(*) CURNAME ! current name (before renaming)
8723 INTEGER DIMID ! dimension ID
8724 INTEGER dimid ! returned dimension ID
8725 INTEGER DIMIDS ! list of dimension IDs
8726 INTEGER dimids ! list of returned dimension IDs
8727 DOUBLEPRECISION DVAL ! single data value
8728 DOUBLEPRECISION dval ! returned single data value
8729 DOUBLEPRECISION DVALS ! array of data values
8730 DOUBLEPRECISION dvals ! array of returned data values
8731 INTEGER FILLMODE ! NF_NOFILL or NF_FILL, for setting fill mode
8732 INTEGER*1 I1VAL ! single data value
8733 INTEGER*1 I1val ! returned single data value
8734 INTEGER*1 I1VALS ! array of data values
8735 INTEGER*1 i1vals ! array of returned data values
8736 INTEGER*2 I2VAL ! single data value
8737 INTEGER*2 i2val ! returned single data value
8738 INTEGER*2 I2VALS ! array of data values
8739 INTEGER*2 i2vals ! array of returned data values
8740 INTEGER IMAP ! index mapping vector
8741 INTEGER INDEX ! variable array index vector
8742 INTEGER IVAL ! single data value
8743 INTEGER ival ! returned single data value
8744 INTEGER IVALS ! array of data values
8745 INTEGER ivals ! array of returned data values
8746 INTEGER LEN ! dimension or attribute length
8747 INTEGER len ! returned dimension or attribute length
8748 INTEGER MODE ! open mode, one of NF_WRITE or NF_NOWRITE
8749 CHARACTER(*) NAME ! dimension, variable, or attribute name
8750 CHARACTER(*) name ! returned dim, var, or att name
8751 INTEGER natts ! returned number of attributes
8752 INTEGER NCERR ! error returned from NF_xxx function call
8753 INTEGER NCID ! netCDF ID of an open netCDF dataset
8754 INTEGER ncid ! returned netCDF ID
8755 INTEGER NCID_IN ! netCDF ID of open source netCDF dataset
8756 INTEGER NCID_OUT ! netCDF ID of open destination netCDF dataset
8757 INTEGER NDIMS ! number of dimensions
8758 INTEGER ndims ! returned number of dimensions
8759 CHARACTER(*) NEWNAME ! new name for dim, var, or att
8760 INTEGER ngatts ! returned number of global attributes
8761 INTEGER nvars ! returned number of variables
8762 INTEGER old_mode ! previous fill mode, NF_NOFILL or NF_FILL,
8763 CHARACTER(*) PATH ! name of netCDF dataset
8764 REAL RVAL ! single data value
8765 REAL rval ! returned single data value
8766 REAL RVALS ! array of data values
8767 REAL rvals ! array of returned data values
8768 INTEGER START ! variable array indices of first value
8769 INTEGER STRIDE ! variable array dimensional strides
8770 CHARACTER(*) TEXT ! input text value
8771 CHARACTER(*) text ! returned text value
8772 INTEGER unlimdimid ! returned ID of unlimited dimension
8773 INTEGER VARID ! variable ID
8774 INTEGER varid ! returned variable ID
8775 INTEGER VARID_IN ! variable ID
8776 INTEGER VARID_OUT ! variable ID
8777 INTEGER XTYPE ! external type: NF_BYTE, NF_CHAR, ... ,
8778 INTEGER xtype ! returned external type