NetCDF-Fortran  4.4.4
 All Classes Files Functions Variables Typedefs Macros Pages
netcdf-f90-sec2-datasets.md
Go to the documentation of this file.
1 2 Datasets {#f90_datasets}
2 ===========================
3 
4 [TOC]
5 
6 2.1 Datasets Introduction {#f90-datasets-introduction}
7 =========================
8 
9 This chapter presents the interfaces of the netCDF functions that deal
10 with a netCDF dataset or the whole netCDF library.
11 
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.
22 
23 Functions that deal with the netCDF library include:
24 
25 - Get version of library.
26 - Get error message corresponding to a returned error code.
27 
28 The operations supported on a netCDF dataset as a single object are:
29 
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.
42 
43 2.2 NetCDF Library Interface Descriptions {#f90-netcdf-library-interface-descriptions}
44 =========================
45 
46 Each interface description for a particular netCDF function in this and
47 later chapters contains:
48 
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).
56 
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".
62 
63 2.3 NF90_STRERROR {#f90-nf90_strerror}
64 =========================
65 
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.
71 
72 
73 
74 ## Usage
75 
76 
77 ~~~~.fortran
78 
79 
80  function nf90_strerror(ncerr)
81  integer, intent( in) :: ncerr
82  character(len = 80) :: nf90_strerror
83 
84 ~~~~
85 
86 
87 
88 `NCERR`
89 
90 : An error status that might have been returned from a previous call
91  to some netCDF function.
92 
93 ## Errors
94 
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.
99 
100 ## Example
101 
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:
105 
106 
107 ~~~~.fortran
108 
109 
110  subroutine handle_err(status)
111  integer, intent ( in) :: status
112 
113  if(status /= nf90_noerr) then
114  print *, trim(nf90_strerror(status))
115  stop "Stopped"
116  end if
117  end subroutine handle_err
118 
119 
120 
121 ~~~~
122 
123 2.4 Get netCDF library version: NF90_INQ_LIBVERS {#f90-get-netcdf-library-version-nf90_inq_libvers}
124 =========================
125 
126 The function NF90\_INQ\_LIBVERS returns a string identifying the version
127 of the netCDF library, and when it was built.
128 
129 
130 
131 ## Usage
132 
133 
134 
135 
136 ~~~~.fortran
137 
138  function nf90_inq_libvers()
139  character(len = 80) :: nf90_inq_libvers
140 
141 
142 
143 ~~~~
144 
145 
146 
147 ## Errors
148 
149 This function takes no arguments, and returns no error status.
150 
151 
152 
153 ## Example
154 
155 Here is an example using nf90\_inq\_libvers to print the version of the
156 netCDF library with which the program is linked:
157 
158 
159 
160 ~~~~.fortran
161 print *, trim(nf90_inq_libvers())
162 
163 ~~~~
164 
165 
166 
167 
168 2.5 NF90_CREATE {#f90-nf90_create}
169 =========================
170 
171 
172 
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
177 attributes.
178 
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.
181 
182 
183 
184 ## Usage
185 
186 
187 
188 ~~~~.fortran
189 
190  function nf90_create(path, cmode, ncid, initialsize, bufrsize, cache_size, &
191  cache_nelems, cache_preemption, comm, info)
192  implicit none
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
202 
203 
204 ~~~~
205 
206 
207 `path`
208 
209 : The file name of the new netCDF dataset.
210 
211 `cmode`
212 
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).
217 
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
223  NetCDF Users’ Guide.
224 
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.
228 
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.)
236 
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.
242 
243  Setting the NF90\_NETCDF4 flag causes netCDF to create a
244  netCDF-4/HDF5 format output file.
245 
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.
250 
251 `ncid`
252 
253 : Returned netCDF ID.
254 
255 The following optional arguments allow additional performance tuning.
256 
257 `initialsize`
258 
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.
262 
263 `bufrsize`
264 
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.
269 
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.
276 
277  The bufrsize is a property of a given open netcdf descriptor ncid,
278  it is not a persistent property of the netcdf dataset.
279 
280  This is ignored for NetCDF-4/HDF5 files.
281 
282 `cache_size`
283 
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.
287 
288 `cache_nelems`
289 
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.
293 
294 `cache_premtion`
295 
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.
299 
300 `comm`
301 
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.
306 
307 `info`
308 
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.
313 
314 
315 
316 ## Errors
317 
318 NF90\_CREATE returns the value NF90\_NOERR if no errors occurred.
319 Possible causes of errors include:
320 
321 - Passing a dataset name that includes a directory that does
322  not exist.
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.
328 
329 
330 
331 ## Example
332 
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:
336 
337 
338 
339 ~~~~.fortran
340 
341  use netcdf
342  implicit none
343  integer :: ncid, status
344  ...
345  status = nf90_create(path = "foo.nc", cmode = nf90_noclobber, ncid = ncid)
346  if (status /= nf90_noerr) call handle_err(status)
347 
348 
349 ~~~~
350 
351 
352 
353 2.6 NF90_OPEN {#f90-nf90_open}
354 =========================
355 
356 The function NF90\_OPEN opens an existing netCDF dataset for access.
357 
358 ## Usage
359 
360 
361 ~~~~.fortran
362 
363 
364  function nf90_open(path, mode, ncid, bufrsize, cache_size, cache_nelems, &
365  cache_preemption, comm, info)
366  implicit none
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
374  integer :: nf90_open
375 
376 
377 ~~~~
378 
379 
380 `path`
381 
382 : File name for netCDF dataset to be opened. This may be an OPeNDAP
383  URL if DAP support is enabled.
384 
385 `mode`
386 
387 : A zero value (or NF90\_NOWRITE) specifies: open the dataset with
388  read-only access, buffering and caching accesses for efficiency
389 
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.
402 
403 `ncid`
404 
405 : Returned netCDF ID.
406 
407 The following optional argument allows additional performance tuning.
408 
409 `bufrsize`
410 
411 : This parameter applies only when opening classic format or 64-bit
412  offset files. It is ignored for netCDF-4/HDF5 files.
413 
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.
418 
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.
425 
426  The bufrsize is a property of a given open netcdf descriptor ncid,
427  it is not a persistent property of the netcdf dataset.
428 
429 `cache_size`
430 
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.
434 
435 `cache_nelems`
436 
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.
440 
441 `cache_premtion`
442 
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.
446 
447 `comm`
448 
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.
453 
454 `info`
455 
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.
460 
461 
462 
463 ## Errors
464 
465 NF90\_OPEN returns the value NF90\_NOERR if no errors occurred.
466 Otherwise, the returned status indicates an error. Possible causes of
467 errors include:
468 
469 - The specified netCDF dataset does not exist.
470 - A meaningless mode was specified.
471 
472 ## Example
473 
474 Here is an example using NF90\_OPEN to open an existing netCDF dataset
475 named foo.nc for read-only, non-shared access:
476 
477 
478 ~~~~.fortran
479 
480 
481  use netcdf
482  implicit none
483  integer :: ncid, status
484  ...
485  status = nf90_open(path = "foo.nc", mode = nf90_nowrite, ncid = ncid)
486  if (status /= nf90_noerr) call handle_err(status)
487 
488 
489 ~~~~
490 
491 
492 ## Example
493 
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.
497 
498 
499 ~~~~.fortran
500 
501 
502  use netcdf
503  implicit none
504  integer :: ncid, status
505  ...
506  ! Reopen the file.
507  call handle_err(nf90_open(FILE_NAME, nf90_nowrite, ncid, comm = MPI_COMM_WORLD, &
508  info = MPI_INFO_NULL))
509 
510 
511 
512 ~~~~
513 
514 2.7 NF90_REDEF {#f90-nf90_redef}
515 =========================
516 
517 
518 
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.
522 
523 
524 
525 ## Usage
526 
527 
528 ~~~~.fortran
529 
530 
531  function nf90_redef(ncid)
532  integer, intent( in) :: ncid
533  integer :: nf90_redef
534 
535 
536 
537 ~~~~
538 
539 `ncid`
540 
541 : netCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
542 
543 
544 
545 ## Errors
546 
547 NF90\_REDEF returns the value NF90\_NOERR if no errors occurred.
548 Otherwise, the returned status indicates an error. Possible causes of
549 errors include:
550 
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.
554 
555 
556 
557 ## Example
558 
559 Here is an example using NF90\_REDEF to open an existing netCDF dataset
560 named foo.nc and put it into define mode:
561 
562 
563 
564 ~~~~.fortran
565 
566  use netcdf
567  implicit none
568  integer :: ncid, status
569  ...
570  status = nf90_open("foo.nc", nf90_write, ncid) ! Open dataset
571  if (status /= nf90_noerr) call handle_err(status)
572  ...
573  status = nf90_redef(ncid) ! Put the file in define mode
574  if (status /= nf90_noerr) call handle_err(status)
575 
576 
577 
578 ~~~~
579 
580 2.8 NF90_ENDDEF {#f90-nf90_enddef}
581 =========================
582 
583 
584 
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.
591 
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
595 Guide.
596 
597 ## Usage
598 
599 
600 ~~~~.fortran
601 
602 
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
607 
608 ~~~~
609 
610 
611 
612 `ncid`
613 
614 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
615 
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.
619 
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.
630 
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
634 v\_minfree is 0.
635 
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
641 4 bytes.
642 
643 `h_minfree`
644 
645 : Size of the pad (in bytes) at the end of the "header" section.
646 
647 `v_minfree`
648 
649 : Size of the pad (in bytes) at the end of the data section for fixed
650  size variables.
651 
652 `v_align`
653 
654 : The alignment of the beginning of the data section for fixed
655  size variables.
656 
657 `r_align`
658 
659 : The alignment of the beginning of the data section for variables
660  which have an unlimited dimension (record variables).
661 
662 ## Errors
663 
664 NF90\_ENDDEF returns the value NF90\_NOERR if no errors occurred.
665 Otherwise, the returned status indicates an error. Possible causes of
666 errors include:
667 
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).
672 
673 ## Example
674 
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:
677 
678 
679 
680 ~~~~.fortran
681 
682  use netcdf
683  implicit none
684  integer :: ncid, status
685  ...
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)
691 
692 
693 ~~~~
694 
695 
696 
697 
698 2.9 NF90_CLOSE {#f90-nf90_close}
699 =========================
700 
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
707 created.
708 
709 
710 
711 ## Usage
712 
713 
714 
715 ~~~~.fortran
716 
717  function nf90_close(ncid)
718  integer, intent( in) :: ncid
719  integer :: nf90_close
720 
721 
722 ~~~~
723 
724 
725 `ncid`
726 
727 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
728 
729 
730 
731 ## Errors
732 
733 NF90\_CLOSE returns the value NF90\_NOERR if no errors occurred.
734 Otherwise, the returned status indicates an error. Possible causes of
735 errors include:
736 
737 - Define mode was entered and the automatic call made to
738  NF90\_ENDDEF failed.
739 - The specified netCDF ID does not refer to an open netCDF dataset.
740 
741 
742 
743 ## Example
744 
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:
747 
748 
749 ~~~~.fortran
750 
751 
752  use netcdf
753  implicit none
754  integer :: ncid, status
755  ...
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)
761 
762 ~~~~
763 
764 
765 
766 2.10 NF90_INQUIRE Family {#f90-nf90_inquire-family}
767 =========================
768 
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.
776 
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.
779 
780 ## Usage
781 
782 
783 ~~~~.fortran
784 
785 
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, &
791  formatNum
792  integer :: nf90_inquire
793 
794 
795 
796 ~~~~
797 
798 `ncid`
799 
800 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
801 
802 `nDimensions`
803 
804 : Returned number of dimensions defined for this netCDF dataset.
805 
806 `nVariables`
807 
808 : Returned number of variables defined for this netCDF dataset.
809 
810 `nAttributes`
811 
812 : Returned number of global attributes defined for this
813  netCDF dataset.
814 
815 `unlimitedDimID`
816 
817 : Returned ID of the unlimited dimension, if there is one for this
818  netCDF dataset. If no unlimited length dimension has been defined,
819  -1 is returned.
820 
821 `format`
822 
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.
828 
829 
830 
831 ## Errors
832 
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:
836 
837 - The specified netCDF ID does not refer to an open netCDF dataset.
838 
839 ## Example
840 
841 Here is an example using NF90\_INQUIRE to find out about a netCDF
842 dataset named foo.nc:
843 
844 
845 ~~~~.fortran
846 
847 
848  use netcdf
849  implicit none
850  integer :: ncid, status, nDims, nVars, nGlobalAtts, unlimDimID
851  ...
852  status = nf90_open("foo.nc", nf90_nowrite, ncid)
853  if (status /= nf90_noerr) call handle_err(status)
854  ...
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)
860 
861 
862 ~~~~
863 
864 
865 2.11 NF90_SYNC {#f90-nf90_sync}
866 =========================
867 
868 
869 
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:
873 
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.
880 
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
892 buffering.
893 
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
899 among processes.
900 
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
904 this purpose.
905 
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
916 subsequent access.
917 
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.
924 
925 Data is automatically synchronized to disk when a netCDF dataset is
926 closed, or whenever you leave define mode.
927 
928 
929 ## Usage
930 
931 
932 ~~~~.fortran
933 
934 
935  function nf90_sync(ncid)
936  integer, intent( in) :: ncid
937  integer :: nf90_sync
938 
939 
940 
941 ~~~~
942 
943 `ncid`
944 
945 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
946 
947 
948 
949 ## Errors
950 
951 NF90\_SYNC returns the value NF90\_NOERR if no errors occurred.
952 Otherwise, the returned status indicates an error. Possible causes of
953 errors include:
954 
955 - The netCDF dataset is in define mode.
956 - The specified netCDF ID does not refer to an open netCDF dataset.
957 
958 
959 
960 ## Example
961 
962 Here is an example using NF90\_SYNC to synchronize the disk writes of a
963 netCDF dataset named foo.nc:
964 
965 
966 
967 ~~~~.fortran
968 
969  use netcdf
970  implicit none
971  integer :: ncid, status
972  ...
973  status = nf90_open("foo.nc", nf90_write, ncid)
974  if (status /= nf90_noerr) call handle_err(status)
975  ...
976  ! write data or change attributes
977  ...
978  status = NF90_SYNC(ncid)
979  if (status /= nf90_noerr) call handle_err(status)
980 
981 
982 ~~~~
983 
984 
985 2.12 NF90_ABORT {#f90-nf90_abort}
986 =========================
987 
988 
989 
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.
998 
999 
1000 
1001 ## Usage
1002 
1003 
1004 ~~~~.fortran
1005 
1006 
1007  function nf90_abort(ncid)
1008  integer, intent( in) :: ncid
1009  integer :: nf90_abort
1010 
1011 
1012 ~~~~
1013 
1014 
1015 `ncid`
1016 
1017 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1018 
1019 
1020 
1021 ## Errors
1022 
1023 NF90\_ABORT returns the value NF90\_NOERR if no errors occurred.
1024 Otherwise, the returned status indicates an error. Possible causes of
1025 errors include:
1026 
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.
1030 
1031 
1032 
1033 ## Example
1034 
1035 Here is an example using NF90\_ABORT to back out of redefinitions of a
1036 dataset named foo.nc:
1037 
1038 
1039 ~~~~.fortran
1040 
1041 
1042  use netcdf
1043  implicit none
1044  integer :: ncid, status, LatDimID
1045  ...
1046  status = nf90_open("foo.nc", nf90_write, ncid)
1047  if (status /= nf90_noerr) call handle_err(status)
1048  ...
1049  status = nf90_redef(ncid)
1050  if (status /= nf90_noerr) call handle_err(status)
1051  ...
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)
1057  end if
1058 ...
1059 
1060 
1061 ~~~~
1062 
1063 
1064 
1065 2.13 NF90_SET_FILL {#f90-nf90_set_fill}
1066 =========================
1067 
1068 
1069 
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.
1083 
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
1088 with data.
1089 
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.
1093 
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
1100 mode to NF90\_FILL.
1101 
1102 There are three situations where it is advantageous to set nofill mode:
1103 
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
1111  unwritten records.
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.
1115 
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.
1120 
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
1123 feature.
1124 
1125 
1126 
1127 ## Usage
1128 
1129 
1130 ~~~~.fortran
1131 
1132 
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
1137 
1138 
1139 
1140 ~~~~
1141 
1142 `ncid`
1143 
1144 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1145 
1146 `fillmode`
1147 
1148 : Desired fill mode for the dataset, either NF90\_NOFILL
1149  or NF90\_FILL.
1150 
1151 `old_mode`
1152 
1153 : Returned current fill mode of the dataset before this call, either
1154  NF90\_NOFILL or NF90\_FILL.
1155 
1156 
1157 
1158 ## Errors
1159 
1160 NF90\_SET\_FILL returns the value NF90\_NOERR if no errors occurred.
1161 Otherwise, the returned status indicates an error. Possible causes of
1162 errors include:
1163 
1164 - The specified netCDF ID does not refer to an open netCDF dataset.
1165 - The specified netCDF ID refers to a dataset open for
1166  read-only access.
1167 - The fill mode argument is neither NF90\_NOFILL nor NF90\_FILL..
1168 
1169 ## Example
1170 
1171 Here is an example using NF90\_SET\_FILL to set nofill mode for
1172 subsequent writes of a netCDF dataset named foo.nc:
1173 
1174 
1175 ~~~~.fortran
1176 
1177 
1178  use netcdf
1179  implicit none
1180  integer :: ncid, status, oldMode
1181  ...
1182  status = nf90_open("foo.nc", nf90_write, ncid)
1183  if (status /= nf90_noerr) call handle_err(status)
1184  ...
1185  ! Write data with prefilling behavior
1186  ...
1187  status = nf90_set_fill(ncid, nf90_nofill, oldMode)
1188  if (status /= nf90_noerr) call handle_err(status)
1189  ...
1190  ! Write data with no prefilling
1191  ...
1192 
1193 ~~~~
integer function nf90_set_fill(ncid, fillmode, old_mode)
Definition: netcdf_file.f90:58
integer function nf90_abort(ncid)
integer function nf90_inquire(ncid, nDimensions, nVariables, nAttributes, unlimitedDimId, formatNum)
integer function nf90_enddef(ncid, h_minfree, v_align, v_minfree, r_align)
Definition: netcdf_file.f90:73
integer function nf90_create(path, cmode, ncid, initialsize, chunksize)
character(len=80) function nf90_inq_libvers()
Definition: netcdf_file.f90:9
integer function nf90_def_dim(ncid, name, len, dimid)
Definition: netcdf_dims.f90:5
integer function nf90_open(path, mode, ncid, chunksize)
Definition: netcdf3_file.f90:8
integer function nf90_redef(ncid)
Definition: netcdf_file.f90:66
character(len=80) function nf90_strerror(ncerr)
Definition: netcdf_file.f90:15
integer function nf90_sync(ncid)
Definition: netcdf_file.f90:95
integer function nf90_close(ncid)

Return to the Main Unidata NetCDF page.
Generated on Mon Dec 19 2016 16:43:42 for NetCDF-Fortran. NetCDF is a Unidata library.