1 2 Datasets {#f90_datasets}
2 ===========================
6 2.1 Datasets Introduction {#f90-datasets-introduction}
7 =========================
9 This chapter presents the interfaces of the netCDF functions that deal
10 with a netCDF dataset or the whole netCDF library.
12 A netCDF dataset that has not yet been opened can only be referred to by
13 its dataset name. Once a netCDF dataset is opened, it is referred to by
14 a netCDF ID, which is a small nonnegative integer returned when you
15 create or open the dataset. A netCDF ID is much like a file descriptor
16 in C or a logical unit number in FORTRAN. In any single program, the
17 netCDF IDs of distinct open netCDF datasets are distinct. A single
18 netCDF dataset may be opened multiple times and will then have multiple
19 distinct netCDF IDs; however at most one of the open instances of a
20 single netCDF dataset should permit writing. When an open netCDF dataset
21 is closed, the ID is no longer associated with a netCDF dataset.
23 Functions that deal with the netCDF library include:
25 - Get version of library.
26 - Get error message corresponding to a returned error code.
28 The operations supported on a netCDF dataset as a single object are:
30 - Create, given dataset name and whether to overwrite or not.
31 - Open for access, given dataset name and read or write intent.
32 - Put into define mode, to add dimensions, variables, or attributes.
33 - Take out of define mode, checking consistency of additions.
34 - Close, writing to disk if required.
35 - Inquire about the number of dimensions, number of variables, number
36 of global attributes, and ID of the unlimited dimension, if any.
37 - Synchronize to disk to make sure it is current.
38 - Set and unset nofill mode for optimized sequential writes.
39 - After a summary of conventions used in describing the netCDF
40 interfaces, the rest of this chapter presents a detailed description
41 of the interfaces for these operations.
43 2.2 NetCDF Library Interface Descriptions {#f90-netcdf-library-interface-descriptions}
44 =========================
46 Each interface description for a particular netCDF function in this and
47 later chapters contains:
49 - a description of the purpose of the function;
50 - a Fortran 90 interface block that presents the type and order of the
51 formal parameters to the function;
52 - a description of each formal parameter in the C interface;
53 - a list of possible error conditions; and
54 - an example of a Fortran 90 program fragment calling the netCDF
55 function (and perhaps other netCDF functions).
57 The examples follow a simple convention for error handling, always
58 checking the error status returned from each netCDF function call and
59 calling a handle\_error function in case an error was detected. For an
60 example of such a function, see Section 5.2 "Get error message
61 corresponding to error status: nf90\_strerror".
63 2.3 NF90_STRERROR {#f90-nf90_strerror}
64 =========================
66 The function NF90\_STRERROR returns a static reference to an error
67 message string corresponding to an integer netCDF error status or to a
68 system error number, presumably returned by a previous call to some
69 other netCDF function. The list of netCDF error status codes is
70 available in the appropriate include file for each language binding.
80 function nf90_strerror(ncerr)
81 integer, intent( in) :: ncerr
82 character(len = 80) :: nf90_strerror
90 : An error status that might have been returned from a previous call
91 to some netCDF function.
95 If you provide an invalid integer error status that does not correspond
96 to any netCDF error message or or to any system error message (as
97 understood by the system strerror function), NF90\_STRERROR returns a
98 string indicating that there is no such error status.
102 Here is an example of a simple error handling function that uses
103 NF90\_STRERROR to print the error message corresponding to the netCDF
104 error status returned from any netCDF function call and then exit:
110 subroutine handle_err(status)
111 integer, intent ( in) :: status
113 if(status /= nf90_noerr) then
114 print *, trim(nf90_strerror(status))
117 end subroutine handle_err
123 2.4 Get netCDF library version: NF90_INQ_LIBVERS {#f90-get-netcdf-library-version-nf90_inq_libvers}
124 =========================
126 The function NF90\_INQ\_LIBVERS returns a string identifying the version
127 of the netCDF library, and when it was built.
138 function nf90_inq_libvers()
139 character(len = 80) :: nf90_inq_libvers
149 This function takes no arguments, and returns no error status.
155 Here is an example using nf90\_inq\_libvers to print the version of the
156 netCDF library with which the program is linked:
161 print *, trim(nf90_inq_libvers())
168 2.5 NF90_CREATE {#f90-nf90_create}
169 =========================
173 This function creates a new netCDF dataset, returning a netCDF ID that
174 can subsequently be used to refer to the netCDF dataset in other netCDF
175 function calls. The new netCDF dataset opened for write access and
176 placed in define mode, ready for you to add dimensions, variables, and
179 A creation mode flag specifies whether to overwrite any existing dataset
180 with the same name and whether access to the dataset is shared.
190 function nf90_create(path, cmode, ncid, initialsize, bufrsize, cache_size, &
191 cache_nelems, cache_preemption, comm, info)
193 character (len = *), intent(in) :: path
194 integer, intent(in) :: cmode
195 integer, intent(out) :: ncid
196 integer, optional, intent(in) :: initialsize
197 integer, optional, intent(inout) :: bufrsize
198 integer, optional, intent(in) :: cache_size, cache_nelems
199 real, optional, intent(in) :: cache_preemption
200 integer, optional, intent(in) :: comm, info
201 integer :: nf90_create
209 : The file name of the new netCDF dataset.
213 : The creation mode flag. The following flags are available:
214 NF90\_CLOBBER, NF90\_NOCLOBBER, NF90\_SHARE, NF90\_64BIT\_OFFSET,
215 NF90\_NETCDF4, and NF90\_CLASSIC\_MODEL. (NF90\_HDF5 is deprecated,
216 use NF90\_NETCDF4 instead).
218 A zero value (defined for convenience as NF90\_CLOBBER) specifies:
219 overwrite any existing dataset with the same file name, and buffer
220 and cache accesses for efficiency. The dataset will be in netCDF
221 classic format. See [NetCDF Classic Format
222 Limitations](netcdf.html#NetCDF-Classic-Format-Limitations) in
225 Setting NF90\_NOCLOBBER means you do not want to clobber (overwrite)
226 an existing dataset; an error (NF90\_EEXIST) is returned if the
227 specified dataset already exists.
229 The NF90\_SHARE flag is appropriate when one process may be writing
230 the dataset and one or more other processes reading the dataset
231 concurrently; it means that dataset accesses are not buffered and
232 caching is limited. Since the buffering scheme is optimized for
233 sequential access, programs that do not access data sequentially may
234 see some performance improvement by setting the NF90\_SHARE flag.
235 (This only applies to netCDF-3 classic or 64-bit offset files.)
237 Setting NF90\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
238 format file, instead of a netCDF classic format file. The 64-bit
239 offset format imposes far fewer restrictions on very large (i.e.
240 over 2 GB) data files. See [Large File
241 Support](netcdf.html#Large-File-Support) in NetCDF Users’ Guide.
243 Setting the NF90\_NETCDF4 flag causes netCDF to create a
244 netCDF-4/HDF5 format output file.
246 Oring the NF90\_CLASSIC\_MODEL flag with the NF90\_NETCDF4 flag
247 causes the resulting netCDF-4/HDF5 file to restrict itself to the
248 classic model - none of the new netCDF-4 data model features, such
249 as groups or user-defined types, are allowed in such a file.
253 : Returned netCDF ID.
255 The following optional arguments allow additional performance tuning.
259 : The initial size of the file (in bytes) at creation time. A value of
260 0 causes the file size to be computed when nf90\_enddef is called.
261 This is ignored for NetCDF-4/HDF5 files.
265 : Controls a space versus time trade-off, memory allocated in the
266 netcdf library versus number of system calls. Because of internal
267 requirements, the value may not be set to exactly the
268 value requested. The actual value chosen is returned.
270 The library chooses a system-dependent default value if
271 NF90\_SIZEHINT\_DEFAULT is supplied as input. If the "preferred I/O
272 block size" is available from the stat() system call as member
273 st\_blksize this value is used. Lacking that, twice the system
274 pagesize is used. Lacking a call to discover the system pagesize,
275 the default bufrsize is set to 8192 bytes.
277 The bufrsize is a property of a given open netcdf descriptor ncid,
278 it is not a persistent property of the netcdf dataset.
280 This is ignored for NetCDF-4/HDF5 files.
284 : If the cache\_size is provided when creating a netCDF-4/HDF5 file,
285 it will be used instead of the default (32000000) as the size, in
286 bytes, of the HDF5 chunk cache.
290 : If cache\_nelems is provided when creating a netCDF-4/HDF5 file, it
291 will be used instead of the default (1000) as the maximum number of
292 elements in the HDF5 chunk cache.
296 : If cache\_preemption is provided when creating a netCDF-4/HDF5 file,
297 it will be used instead of the default (0.75) as the preemption
298 value for the HDF5 chunk cache.
302 : If the comm and info parameters are provided the file is created and
303 opened for parallel I/O. Set the comm parameter to the MPI
304 communicator (of type MPI\_Comm). If this parameter is provided the
305 info parameter must also be provided.
309 : If the comm and info parameters are provided the file is created and
310 opened for parallel I/O. Set the comm parameter to the MPI
311 information value (of type MPI\_Info). If this parameter is provided
312 the comm parameter must also be provided.
318 NF90\_CREATE returns the value NF90\_NOERR if no errors occurred.
319 Possible causes of errors include:
321 - Passing a dataset name that includes a directory that does
323 - Specifying a dataset name of a file that exists and also
324 specifying NF90\_NOCLOBBER.
325 - Specifying a meaningless value for the creation mode.
326 - Attempting to create a netCDF dataset in a directory where you don’t
327 have permission to create files.
333 In this example we create a netCDF dataset named foo.nc; we want the
334 dataset to be created in the current directory only if a dataset with
335 that name does not already exist:
343 integer :: ncid, status
345 status = nf90_create(path = "foo.nc", cmode = nf90_noclobber, ncid = ncid)
346 if (status /= nf90_noerr) call handle_err(status)
353 2.6 NF90_OPEN {#f90-nf90_open}
354 =========================
356 The function NF90\_OPEN opens an existing netCDF dataset for access.
364 function nf90_open(path, mode, ncid, bufrsize, cache_size, cache_nelems, &
365 cache_preemption, comm, info)
367 character (len = *), intent(in) :: path
368 integer, intent(in) :: mode
369 integer, intent(out) :: ncid
370 integer, optional, intent(inout) :: bufrsize
371 integer, optional, intent(in) :: cache_size, cache_nelems
372 real, optional, intent(in) :: cache_preemption
373 integer, optional, intent(in) :: comm, info
382 : File name for netCDF dataset to be opened. This may be an OPeNDAP
383 URL if DAP support is enabled.
387 : A zero value (or NF90\_NOWRITE) specifies: open the dataset with
388 read-only access, buffering and caching accesses for efficiency
390 Otherwise, the open mode is NF90\_WRITE, NF90\_SHARE,
391 or NF90\_WRITE|NF90\_SHARE. Setting the NF90\_WRITE flag opens the
392 dataset with read-write access. ("Writing" means any kind of change
393 to the dataset, including appending or changing data, adding or
394 renaming dimensions, variables, and attributes, or
395 deleting attributes.) The NF90\_SHARE flag is appropriate when one
396 process may be writing the dataset and one or more other processes
397 reading the dataset concurrently (note that this is not the same as
398 parallel I/O); it means that dataset accesses are not buffered and
399 caching is limited. Since the buffering scheme is optimized for
400 sequential access, programs that do not access data sequentially may
401 see some performance improvement by setting the NF90\_SHARE flag.
405 : Returned netCDF ID.
407 The following optional argument allows additional performance tuning.
411 : This parameter applies only when opening classic format or 64-bit
412 offset files. It is ignored for netCDF-4/HDF5 files.
414 It Controls a space versus time trade-off, memory allocated in the
415 netcdf library versus number of system calls. Because of internal
416 requirements, the value may not be set to exactly the
417 value requested. The actual value chosen is returned.
419 The library chooses a system-dependent default value if
420 NF90\_SIZEHINT\_DEFAULT is supplied as input. If the "preferred I/O
421 block size" is available from the stat() system call as member
422 st\_blksize this value is used. Lacking that, twice the system
423 pagesize is used. Lacking a call to discover the system pagesize,
424 the default bufrsize is set to 8192 bytes.
426 The bufrsize is a property of a given open netcdf descriptor ncid,
427 it is not a persistent property of the netcdf dataset.
431 : If the cache\_size is provided when opening a netCDF-4/HDF5 file, it
432 will be used instead of the default (32000000) as the size, in
433 bytes, of the HDF5 chunk cache.
437 : If cache\_nelems is provided when opening a netCDF-4/HDF5 file, it
438 will be used instead of the default (1000) as the maximum number of
439 elements in the HDF5 chunk cache.
443 : If cache\_preemption is provided when opening a netCDF-4/HDF5 file,
444 it will be used instead of the default (0.75) as the preemption
445 value for the HDF5 chunk cache.
449 : If the comm and info parameters are provided the file is opened for
450 parallel I/O. Set the comm parameter to the MPI communicator (of
451 type MPI\_Comm). If this parameter is provided the info parameter
452 must also be provided.
456 : If the comm and info parameters are provided the file is opened for
457 parallel I/O. Set the comm parameter to the MPI information value
458 (of type MPI\_Info). If this parameter is provided the comm
459 parameter must also be provided.
465 NF90\_OPEN returns the value NF90\_NOERR if no errors occurred.
466 Otherwise, the returned status indicates an error. Possible causes of
469 - The specified netCDF dataset does not exist.
470 - A meaningless mode was specified.
474 Here is an example using NF90\_OPEN to open an existing netCDF dataset
475 named foo.nc for read-only, non-shared access:
483 integer :: ncid, status
485 status = nf90_open(path = "foo.nc", mode = nf90_nowrite, ncid = ncid)
486 if (status /= nf90_noerr) call handle_err(status)
494 Here is an example using NF90\_OPEN to open an existing netCDF dataset
495 for parallel I/O access. (Note the use of the comm and info parameters).
496 This example is from test program nf\_test/f90tst\_parallel.f90.
504 integer :: ncid, status
507 call handle_err(nf90_open(FILE_NAME, nf90_nowrite, ncid, comm = MPI_COMM_WORLD, &
508 info = MPI_INFO_NULL))
514 2.7 NF90_REDEF {#f90-nf90_redef}
515 =========================
519 The function NF90\_REDEF puts an open netCDF dataset into define mode,
520 so dimensions, variables, and attributes can be added or renamed and
521 attributes can be deleted.
531 function nf90_redef(ncid)
532 integer, intent( in) :: ncid
533 integer :: nf90_redef
541 : netCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
547 NF90\_REDEF returns the value NF90\_NOERR if no errors occurred.
548 Otherwise, the returned status indicates an error. Possible causes of
551 - The specified netCDF dataset is already in define mode.
552 - The specified netCDF dataset was opened for read-only.
553 - The specified netCDF ID does not refer to an open netCDF dataset.
559 Here is an example using NF90\_REDEF to open an existing netCDF dataset
560 named foo.nc and put it into define mode:
568 integer :: ncid, status
570 status = nf90_open("foo.nc", nf90_write, ncid) ! Open dataset
571 if (status /= nf90_noerr) call handle_err(status)
573 status = nf90_redef(ncid) ! Put the file in define mode
574 if (status /= nf90_noerr) call handle_err(status)
580 2.8 NF90_ENDDEF {#f90-nf90_enddef}
581 =========================
585 The function NF90\_ENDDEF takes an open netCDF dataset out of define
586 mode. The changes made to the netCDF dataset while it was in define mode
587 are checked and committed to disk if no problems occurred. Non-record
588 variables may be initialized to a "fill value" as well (see section
589 [NF90_SET_FILL](#NF90_005fSET_005fFILL)). The netCDF dataset is then
590 placed in data mode, so variable data can be read or written.
592 This call may involve copying data under some circumstances. For a more
593 extensive discussion See [File Structure and
594 Performance](netcdf.html#File-Structure-and-Performance) in NetCDF Users
603 function nf90_enddef(ncid, h_minfree, v_align, v_minfree, r_align)
604 integer, intent( in) :: ncid
605 integer, optional, intent( in) :: h_minfree, v_align, v_minfree, r_align
606 integer :: nf90_enddef
614 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
616 The following arguments allow additional performance tuning. Note: these
617 arguments expose internals of the netcdf version 1 file format, and may
618 not be available in future netcdf implementations.
620 The current netcdf file format has three sections: the "header" section,
621 the data section for fixed size variables, and the data section for
622 variables which have an unlimited dimension (record variables). The
623 header begins at the beginning of the file. The index (offset) of the
624 beginning of the other two sections is contained in the header.
625 Typically, there is no space between the sections. This causes copying
626 overhead to accrue if one wishes to change the size of the sections, as
627 may happen when changing the names of things, text attribute values,
628 adding attributes or adding variables. Also, for buffered i/o, there may
629 be advantages to aligning sections in certain ways.
631 The minfree parameters allow one to control costs of future calls to
632 nf90\_redef or nf90\_enddef by requesting that some space be available
633 at the end of the section. The default value for both h\_minfree and
636 The align parameters allow one to set the alignment of the beginning of
637 the corresponding sections. The beginning of the section is rounded up
638 to an index which is a multiple of the align parameter. The flag value
639 NF90\_ALIGN\_CHUNK tells the library to use the bufrsize (see above) as
640 the align parameter. The default value for both v\_align and r\_align is
645 : Size of the pad (in bytes) at the end of the "header" section.
649 : Size of the pad (in bytes) at the end of the data section for fixed
654 : The alignment of the beginning of the data section for fixed
659 : The alignment of the beginning of the data section for variables
660 which have an unlimited dimension (record variables).
664 NF90\_ENDDEF returns the value NF90\_NOERR if no errors occurred.
665 Otherwise, the returned status indicates an error. Possible causes of
668 - The specified netCDF dataset is not in define mode.
669 - The specified netCDF ID does not refer to an open netCDF dataset.
670 - The size of one or more variables exceed the size constraints for
671 whichever variant of the file format is in use).
675 Here is an example using NF90\_ENDDEF to finish the definitions of a new
676 netCDF dataset named foo.nc and put it into data mode:
684 integer :: ncid, status
686 status = nf90_create("foo.nc", nf90_noclobber, ncid)
687 if (status /= nf90_noerr) call handle_err(status)
688 ... ! create dimensions, variables, attributes
689 status = nf90_enddef(ncid)
690 if (status /= nf90_noerr) call handle_err(status)
698 2.9 NF90_CLOSE {#f90-nf90_close}
699 =========================
701 The function NF90\_CLOSE closes an open netCDF dataset. If the dataset
702 is in define mode, NF90\_ENDDEF will be called before closing. (In this
703 case, if NF90\_ENDDEF returns an error, NF90\_ABORT will automatically
704 be called to restore the dataset to the consistent state before define
705 mode was last entered.) After an open netCDF dataset is closed, its
706 netCDF ID may be reassigned to the next netCDF dataset that is opened or
717 function nf90_close(ncid)
718 integer, intent( in) :: ncid
719 integer :: nf90_close
727 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
733 NF90\_CLOSE returns the value NF90\_NOERR if no errors occurred.
734 Otherwise, the returned status indicates an error. Possible causes of
737 - Define mode was entered and the automatic call made to
739 - The specified netCDF ID does not refer to an open netCDF dataset.
745 Here is an example using NF90\_CLOSE to finish the definitions of a new
746 netCDF dataset named foo.nc and release its netCDF ID:
754 integer :: ncid, status
756 status = nf90_create("foo.nc", nf90_noclobber, ncid)
757 if (status /= nf90_noerr) call handle_err(status)
758 ... ! create dimensions, variables, attributes
759 status = nf90_close(ncid)
760 if (status /= nf90_noerr) call handle_err(status)
766 2.10 NF90_INQUIRE Family {#f90-nf90_inquire-family}
767 =========================
769 The NF90\_INQUIRE subroutine returns information about an open netCDF
770 dataset, given its netCDF ID. The subroutine can be called from either
771 define mode or data mode, and returns values for any or all of the
772 following: the number of dimensions, the number of variables, the number
773 of global attributes, and the dimension ID of the dimension defined with
774 unlimited length, if any. An additional function, NF90\_INQ\_FORMAT,
775 returns the (rarely needed) format version.
777 No I/O is performed when NF90\_INQUIRE is called, since the required
778 information is available in memory for each open netCDF dataset.
786 function nf90_inquire(ncid, nDimensions, nVariables, nAttributes, &
787 unlimitedDimId, formatNum)
788 integer, intent( in) :: ncid
789 integer, optional, intent(out) :: nDimensions, nVariables, &
790 nAttributes, unlimitedDimId, &
792 integer :: nf90_inquire
800 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
804 : Returned number of dimensions defined for this netCDF dataset.
808 : Returned number of variables defined for this netCDF dataset.
812 : Returned number of global attributes defined for this
817 : Returned ID of the unlimited dimension, if there is one for this
818 netCDF dataset. If no unlimited length dimension has been defined,
823 : Returned integer indicating format version for this dataset, one of
824 nf90\_format\_classic, nf90\_format\_64bit, nf90\_format\_netcdf4,
825 or nf90\_format\_netcdf4\_classic. These are rarely needed by users
826 or applications, since thhe library recognizes the format of a file
827 it is accessing and handles it accordingly.
833 Function NF90\_INQUIRE returns the value NF90\_NOERR if no errors
834 occurred. Otherwise, the returned status indicates an error. Possible
835 causes of errors include:
837 - The specified netCDF ID does not refer to an open netCDF dataset.
841 Here is an example using NF90\_INQUIRE to find out about a netCDF
842 dataset named foo.nc:
850 integer :: ncid, status, nDims, nVars, nGlobalAtts, unlimDimID
852 status = nf90_open("foo.nc", nf90_nowrite, ncid)
853 if (status /= nf90_noerr) call handle_err(status)
855 status = nf90_inquire(ncid, nDims, nVars, nGlobalAtts, unlimdimid)
856 if (status /= nf90_noerr) call handle_err(status)
857 status = nf90_inquire(ncid, nDimensions = nDims, &
858 unlimitedDimID = unlimdimid)
859 if (status /= nf90_noerr) call handle_err(status)
865 2.11 NF90_SYNC {#f90-nf90_sync}
866 =========================
870 The function NF90\_SYNC offers a way to synchronize the disk copy of a
871 netCDF dataset with in-memory buffers. There are two reasons you might
872 want to synchronize after writes:
874 - To minimize data loss in case of abnormal termination, or
875 - To make data available to other processes for reading immediately
876 after it is written. But note that a process that already had the
877 dataset open for reading would not see the number of records
878 increase when the writing process calls NF90\_SYNC; to accomplish
879 this, the reading process must call NF90\_SYNC.
881 This function is backward-compatible with previous versions of the
882 netCDF library. The intent was to allow sharing of a netCDF dataset
883 among multiple readers and one writer, by having the writer call
884 NF90\_SYNC after writing and the readers call NF90\_SYNC before each
885 read. For a writer, this flushes buffers to disk. For a reader, it makes
886 sure that the next read will be from disk rather than from previously
887 cached buffers, so that the reader will see changes made by the writing
888 process (e.g., the number of records written) without having to close
889 and reopen the dataset. If you are only accessing a small amount of
890 data, it can be expensive in computer resources to always synchronize to
891 disk after every write, since you are giving up the benefits of
894 An easier way to accomplish sharing (and what is now recommended) is to
895 have the writer and readers open the dataset with the NF90\_SHARE flag,
896 and then it will not be necessary to call NF90\_SYNC at all. However,
897 the NF90\_SYNC function still provides finer granularity than the
898 NF90\_SHARE flag, if only a few netCDF accesses need to be synchronized
901 It is important to note that changes to the ancillary data, such as
902 attribute values, are not propagated automatically by use of the
903 NF90\_SHARE flag. Use of the NF90\_SYNC function is still required for
906 Sharing datasets when the writer enters define mode to change the data
907 schema requires extra care. In previous releases, after the writer left
908 define mode, the readers were left looking at an old copy of the
909 dataset, since the changes were made to a new copy. The only way readers
910 could see the changes was by closing and reopening the dataset. Now the
911 changes are made in place, but readers have no knowledge that their
912 internal tables are now inconsistent with the new dataset schema. If
913 netCDF datasets are shared across redefinition, some mechanism external
914 to the netCDF library must be provided that prevents access by readers
915 during redefinition and causes the readers to call NF90\_SYNC before any
918 When calling NF90\_SYNC, the netCDF dataset must be in data mode. A
919 netCDF dataset in define mode is synchronized to disk only when
920 NF90\_ENDDEF is called. A process that is reading a netCDF dataset that
921 another process is writing may call NF90\_SYNC to get updated with the
922 changes made to the data by the writing process (e.g., the number of
923 records written), without having to close and reopen the dataset.
925 Data is automatically synchronized to disk when a netCDF dataset is
926 closed, or whenever you leave define mode.
935 function nf90_sync(ncid)
936 integer, intent( in) :: ncid
945 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
951 NF90\_SYNC returns the value NF90\_NOERR if no errors occurred.
952 Otherwise, the returned status indicates an error. Possible causes of
955 - The netCDF dataset is in define mode.
956 - The specified netCDF ID does not refer to an open netCDF dataset.
962 Here is an example using NF90\_SYNC to synchronize the disk writes of a
963 netCDF dataset named foo.nc:
971 integer :: ncid, status
973 status = nf90_open("foo.nc", nf90_write, ncid)
974 if (status /= nf90_noerr) call handle_err(status)
976 ! write data or change attributes
978 status = NF90_SYNC(ncid)
979 if (status /= nf90_noerr) call handle_err(status)
985 2.12 NF90_ABORT {#f90-nf90_abort}
986 =========================
990 You no longer need to call this function, since it is called
991 automatically by NF90\_CLOSE in case the dataset is in define mode and
992 something goes wrong with committing the changes. The function
993 NF90\_ABORT just closes the netCDF dataset, if not in define mode. If
994 the dataset is being created and is still in define mode, the dataset is
995 deleted. If define mode was entered by a call to NF90\_REDEF, the netCDF
996 dataset is restored to its state before definition mode was entered and
997 the dataset is closed.
1007 function nf90_abort(ncid)
1008 integer, intent( in) :: ncid
1009 integer :: nf90_abort
1017 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1023 NF90\_ABORT returns the value NF90\_NOERR if no errors occurred.
1024 Otherwise, the returned status indicates an error. Possible causes of
1027 - When called from define mode while creating a netCDF dataset,
1028 deletion of the dataset failed.
1029 - The specified netCDF ID does not refer to an open netCDF dataset.
1035 Here is an example using NF90\_ABORT to back out of redefinitions of a
1036 dataset named foo.nc:
1044 integer :: ncid, status, LatDimID
1046 status = nf90_open("foo.nc", nf90_write, ncid)
1047 if (status /= nf90_noerr) call handle_err(status)
1049 status = nf90_redef(ncid)
1050 if (status /= nf90_noerr) call handle_err(status)
1052 status = nf90_def_dim(ncid, "Lat", 18, LatDimID)
1053 if (status /= nf90_noerr) then ! Dimension definition failed
1054 call handle_err(status)
1055 status = nf90_abort(ncid) ! Abort redefinitions
1056 if (status /= nf90_noerr) call handle_err(status)
1065 2.13 NF90_SET_FILL {#f90-nf90_set_fill}
1066 =========================
1070 This function is intended for advanced usage, to optimize writes under
1071 some circumstances described below. The function NF90\_SET\_FILL sets
1072 the fill mode for a netCDF dataset open for writing and returns the
1073 current fill mode in a return parameter. The fill mode can be specified
1074 as either NF90\_FILL or NF90\_NOFILL. The default behavior corresponding
1075 to NF90\_FILL is that data is pre-filled with fill values, that is fill
1076 values are written when you create non-record variables or when you
1077 write a value beyond data that has not yet been written. This makes it
1078 possible to detect attempts to read data before it was written. See
1079 section [Fill Values](#Fill-Values), for more information on the use of
1080 fill values. See [Attribute
1081 Conventions](netcdf.html#Attribute-Conventions) in {No value for
1082 ‘n-man’}, for information about how to define your own fill values.
1084 The behavior corresponding to NF90\_NOFILL overrides the default
1085 behavior of prefilling data with fill values. This can be used to
1086 enhance performance, because it avoids the duplicate writes that occur
1087 when the netCDF library writes fill values that are later overwritten
1090 A value indicating which mode the netCDF dataset was already in is
1091 returned. You can use this value to temporarily change the fill mode of
1092 an open netCDF dataset and then restore it to the previous mode.
1094 After you turn on NF90\_NOFILL mode for an open netCDF dataset, you must
1095 be certain to write valid data in all the positions that will later be
1096 read. Note that nofill mode is only a transient property of a netCDF
1097 dataset open for writing: if you close and reopen the dataset, it will
1098 revert to the default behavior. You can also revert to the default
1099 behavior by calling NF90\_SET\_FILL again to explicitly set the fill
1102 There are three situations where it is advantageous to set nofill mode:
1104 1. Creating and initializing a netCDF dataset. In this case, you should
1105 set nofill mode before calling NF90\_ENDDEF and then write
1106 completely all non-record variables and the initial records of all
1107 the record variables you want to initialize.
1108 2. Extending an existing record-oriented netCDF dataset. Set nofill
1109 mode after opening the dataset for writing, then append the
1110 additional records to the dataset completely, leaving no intervening
1112 3. Adding new variables that you are going to initialize to an existing
1113 netCDF dataset. Set nofill mode before calling NF90\_ENDDEF then
1114 write all the new variables completely.
1116 If the netCDF dataset has an unlimited dimension and the last record was
1117 written while in nofill mode, then the dataset may be shorter than if
1118 nofill mode was not set, but this will be completely transparent if you
1119 access the data only through the netCDF interfaces.
1121 The use of this feature may not be available (or even needed) in future
1122 releases. Programmers are cautioned against heavy reliance upon this
1133 function nf90_set_fill(ncid, fillmode, old_mode)
1134 integer, intent( in) :: ncid, fillmode
1135 integer, intent(out) :: old_mode
1136 integer :: nf90_set_fill
1144 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1148 : Desired fill mode for the dataset, either NF90\_NOFILL
1153 : Returned current fill mode of the dataset before this call, either
1154 NF90\_NOFILL or NF90\_FILL.
1160 NF90\_SET\_FILL returns the value NF90\_NOERR if no errors occurred.
1161 Otherwise, the returned status indicates an error. Possible causes of
1164 - The specified netCDF ID does not refer to an open netCDF dataset.
1165 - The specified netCDF ID refers to a dataset open for
1167 - The fill mode argument is neither NF90\_NOFILL nor NF90\_FILL..
1171 Here is an example using NF90\_SET\_FILL to set nofill mode for
1172 subsequent writes of a netCDF dataset named foo.nc:
1180 integer :: ncid, status, oldMode
1182 status = nf90_open("foo.nc", nf90_write, ncid)
1183 if (status /= nf90_noerr) call handle_err(status)
1185 ! Write data with prefilling behavior
1187 status = nf90_set_fill(ncid, nf90_nofill, oldMode)
1188 if (status /= nf90_noerr) call handle_err(status)
1190 ! Write data with no prefilling