NetCDF-Fortran  4.5.2
netcdf-f90-sec6-variables.md
Go to the documentation of this file.
1 6 Variables {#f90-variables}
2 ===========
3 
4 [TOC]
5 
6 6.1 Variables Introduction {#f90-variables-introduction}
7 ===========
8 
9 Variables for a netCDF dataset are defined when the dataset is created,
10 while the netCDF dataset is in define mode. Other variables may be added
11 later by reentering define mode. A netCDF variable has a name, a type,
12 and a shape, which are specified when it is defined. A variable may also
13 have values, which are established later in data mode.
14 
15 Ordinarily, the name, type, and shape are fixed when the variable is
16 first defined. The name may be changed, but the type and shape of a
17 variable cannot be changed. However, a variable defined in terms of the
18 unlimited dimension can grow without bound in that dimension.
19 
20 A netCDF variable in an open netCDF dataset is referred to by a small
21 integer called a variable ID.
22 
23 Variable IDs reflect the order in which variables were defined within a
24 netCDF dataset. Variable IDs are 1, 2, 3,..., in the order in which the
25 variables were defined. A function is available for getting the variable
26 ID from the variable name and vice-versa.
27 
28 Attributes (see [Attributes](#Attributes)) may be associated with a
29 variable to specify such properties as units.
30 
31 Operations supported on variables are:
32 
33 - Create a variable, given its name, data type, and shape.
34 - Get a variable ID from its name.
35 - Get a variable’s name, data type, shape, and number of attributes
36  from its ID.
37 - Put a data value into a variable, given variable ID, indices,
38  and value.
39 - Put an array of values into a variable, given variable ID, corner
40  indices, edge lengths, and a block of values.
41 - Put a subsampled or mapped array-section of values into a variable,
42  given variable ID, corner indices, edge lengths, stride vector,
43  index mapping vector, and a block of values.
44 - Get a data value from a variable, given variable ID and indices.
45 - Get an array of values from a variable, given variable ID, corner
46  indices, and edge lengths.
47 - Get a subsampled or mapped array-section of values from a variable,
48  given variable ID, corner indices, edge lengths, stride vector, and
49  index mapping vector.
50 - Rename a variable.
51 
52 
53 6.2 Language Types Corresponding to netCDF external data types {#f90-language-types-corresponding-to-netcdf-external-data-types}
54 ===========
55 
56 The following table gives the netCDF external data types and the
57 corresponding type constants for defining variables in the FORTRAN
58 interface:
59 
60 Type | FORTRAN API Mnemonic | Bits
61 -------| ----------------------| ------
62 byte | NF90_BYTE | 8
63 char | NF90_CHAR | 8
64 short | NF90_SHORT | 16
65 int | NF90_INT | 32
66 float | NF90_FLOAT | 32
67 double | NF90_DOUBLE | 64
68 
69 
70 The first column gives the netCDF external data type, which is the same
71 as the CDL data type. The next column gives the corresponding Fortran 90
72 parameter for use in netCDF functions (the parameters are defined in the
73 netCDF Fortran 90 module netcdf.f90). The last column gives the number
74 of bits used in the external representation of values of the
75 corresponding type.
76 
77 Note that there are no netCDF types corresponding to 64-bit integers or
78 to characters wider than 8 bits in the current version of the netCDF
79 library.
80 
81 
82 6.3 Create a Variable: `NF90_DEF_VAR` {#f90-create-a-variable-nf90_def_var}
83 ===========
84 
85 
86 
87 The function NF90\_DEF\_VAR adds a new variable to an open netCDF
88 dataset in define mode. It returns (as an argument) a variable ID, given
89 the netCDF ID, the variable name, the variable type, the number of
90 dimensions, and a list of the dimension IDs.
91 
92 Optional arguments allow additional settings for variables in
93 netCDF-4/HDF5 files. These parameters allow data compression and control
94 of the layout of the data on disk for performance tuning. These
95 parameters may also be used to set the chunk sizes to get chunked
96 storage, or to set the contiguous flag to get contiguous storage.
97 
98 Variables that make use of one or more unlimited dimensions,
99 compression, or checksums must use chunking. Such variables are created
100 with default chunk sizes of 1 for each unlimited dimension and the
101 dimension length for other dimensions, except that if the resulting
102 chunks are too large, the default chunk sizes for non-record dimensions
103 are reduced.
104 
105 All parameters after the varid are optional, and only supported if
106 netCDF was built with netCDF-4 features enabled, and if the variable is
107 in a netCDF-4/HDF5 file.
108 
109 
110 
111 ## Usage
112 
113 
114 ~~~~.fortran
115 
116 
117  function nf90_def_var(ncid, name, xtype, dimids, varid, contiguous, &
118  chunksizes, deflate_level, shuffle, fletcher32, endianness, &
119  cache_size, cache_nelems, cache_preemption)
120  integer, intent(in) :: ncid
121  character (len = *), intent(in) :: name
122  integer, intent( in) :: xtype
123  integer, scalar or dimension(:), intent(in), optional :: dimids
124  integer, intent(out) :: varid
125  logical, optional, intent(in) :: contiguous
126  integer, optional, dimension(:), intent(in) :: chunksizes
127  integer, optional, intent(in) :: deflate_level
128  logical, optional, intent(in) :: shuffle, fletcher32
129  integer, optional, intent(in) :: endianness
130  integer, optional, intent(in) :: cache_size, cache_nelems, cache_preemption
131  integer :: nf90_def_var
132 
133 
134 
135 ~~~~
136 
137 `ncid`
138 
139 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
140 
141 `name`
142 
143 : Variable name.
144 
145 `xtype`
146 
147 : One of the set of predefined netCDF external data types. The type of
148  this parameter, NF90\_TYPE, is defined in the netCDF header file.
149  The valid netCDF external data types are NF90\_BYTE, NF90\_CHAR,
150  NF90\_SHORT, NF90\_INT, NF90\_FLOAT, and NF90\_DOUBLE. If the file
151  is a NetCDF-4/HDF5 file, the additional types NF90\_UBYTE,
152  NF90\_USHORT, NF90\_UINT, NF90\_INT64, NF90\_UINT64, and
153  NF90\_STRING may be used, as well as a user defined type ID.
154 
155 `dimids`
156 
157 : Scalar or vector of dimension IDs corresponding to the
158  variable dimensions. For example, a vector of 2 dimension IDs
159  specifies a 2-dimensional matrix.
160 
161  If an integer is passed for this parameter, a 1-D variable
162  is created.
163 
164  If this parameter is not passed (or is a 1D array of size zero) it
165  means the variable is a scalar with no dimensions.
166 
167  For classic data model files, if the ID of the unlimited dimension
168  is included, it must be first. In expanded model netCDF4/HDF5 files,
169  there may be any number of unlimited dimensions, and they may be
170  used in any element of the dimids array.
171 
172  This argument is optional, and if absent specifies a scalar with
173  no dimensions.
174 
175 `varid`
176 
177 : Returned variable ID.
178 
179 `storage`
180 
181 : If NF90\_CONTIGUOUS, then contiguous storage is used for
182  this variable. Variables that use deflation, shuffle filter, or
183  checksums, or that have one or more unlimited dimensions cannot use
184  contiguous storage.
185 
186  If NF90\_CHUNKED, then chunked storage is used for this variable.
187  Chunk sizes may be specified with the chunksizes parameter. Default
188  sizes will be used if chunking is required and this function is
189  not called.
190 
191  By default contiguous storage is used for fix-sized variables when
192  conpression, chunking, shuffle, and checksums are not used.
193 
194 `chunksizes`
195 
196 : An array of chunk number of elements. This array has the number of
197  elements along each dimension of the data chunk. The array must have
198  the one chunksize for each dimension in the variable.
199 
200  The total size of a chunk must be less than 4 GiB. That is, the
201  product of all chunksizes and the size of the data (or the size of
202  nc\_vlen\_t for VLEN types) must be less than 4 GiB. (This is a very
203  large chunk size in any case.)
204 
205  If not provided, but chunked data are needed, then default
206  chunksizes will be chosen. For more information see [{No value for
207  ‘n-man’}](netcdf.html#Chunking) in {No value for ‘n-man’}.
208 
209 `shuffle`
210 
211 : If non-zero, turn on the shuffle filter.
212 
213 `deflate_level`
214 
215 : If the deflate parameter is non-zero, set the deflate level to
216  this value. Must be between 1 and 9.
217 
218 `fletcher32`
219 
220 : Set to true to turn on fletcher32 checksums for this variable.
221 
222 `endianness`
223 
224 : Set to NF90\_ENDIAN\_LITTLE for little-endian format,
225  NF90\_ENDIAN\_BIG for big-endian format, and NF90\_ENDIAN\_NATIVE
226  (the default) for the native endianness of the platform.
227 
228 `cache_size`
229 
230 : The size of the per-variable cache in MegaBytes.
231 
232 `cache_nelems`
233 
234 : The number slots in the per-variable chunk cache (should be a prime
235  number larger than the number of chunks in the cache).
236 
237 `cache_preemption`
238 
239 : The preemtion value must be between 0 and 100 inclusive and
240  indicates how much chunks that have been fully read are favored
241  for preemption. A value of zero means fully read chunks are treated
242  no differently than other chunks (the preemption is strictly LRU)
243  while a value of 100 means fully read chunks are always preempted
244  before other chunks.
245 
246 
247 
248 ## Return Codes
249 
250 NF90\_DEF\_VAR returns the value NF90\_NOERR if no errors occurred.
251 Otherwise, the returned status indicates an error.
252 
253 - NF90\_EBADNAME The specified variable name is the name of another
254  existing variable.
255 - NF90\_EBADTYPE The specified type is not a valid netCDF type.
256 - NF90\_EMAXDIMS The specified number of dimensions is negative or
257  more than the constant NF90\_MAX\_VAR\_DIMS, the maximum number of
258  dimensions permitted for a netCDF variable. (Does not apply to
259  netCDF-4/HDF5 files unless they were created with the
260  CLASSIC\_MODE flag.)
261 - NF90\_EBADDIM One or more of the dimension IDs in the list of
262  dimensions is not a valid dimension ID for the netCDF dataset.
263 - NF90\_EMAXVARS The number of variables would exceed the constant
264  NF90\_MAX\_VARS, the maximum number of variables permitted in a
265  classic netCDF dataset. (Does not apply to netCDF-4/HDF5 files
266  unless they were created with the CLASSIC\_MODE flag.)
267 - NF90\_BADID The specified netCDF ID does not refer to an open
268  netCDF dataset.
269 - NF90\_ENOTNC4 NetCDF-4 operation attempted on a files that is not a
270  netCDF-4/HDF5 file. Only variables in NetCDF-4/HDF5 files may use
271  compression, chunking, and endianness control.
272 - NF90\_ENOTVAR Can’t find this variable.
273 - NF90\_EINVAL Invalid input. This may be because contiguous storage
274  is requested for a variable that has compression, checksums,
275  chunking, or one or more unlimited dimensions.
276 - NF90\_ELATEDEF This variable has already been the subject of a
277  NF90\_ENDDEF call. Once enddef has been called, it is impossible to
278  set the chunking for a variable. (In netCDF-4/HDF5 files
279  NF90\_ENDDEF will be called automatically for any data read
280  or write.)
281 - NF90\_ENOTINDEFINE Not in define mode. This is returned for netCDF
282  classic or 64-bit offset files, or for netCDF-4 files, when they
283  were been created with NF90\_STRICT\_NC3 flag. (see section
284  [NF90\_CREATE](#NF90_005fCREATE)).
285 - NF90\_ESTRICTNC3 Trying to create a var some place other than the
286  root group in a netCDF file with NF90\_STRICT\_NC3 turned on.
287 
288 
289 
290 ### Example
291 
292 Here is an example using NF90\_DEF\_VAR to create a variable named rh of
293 type double with three dimensions, time, lat, and lon in a new netCDF
294 dataset named foo.nc:
295 
296 
297 
298 ~~~~.fortran
299 
300  use netcdf
301  implicit none
302  integer :: status, ncid
303  integer :: LonDimId, LatDimId, TimeDimId
304  integer :: RhVarId
305  ...
306  status = nf90_create("foo.nc", nf90_NoClobber, ncid)
307  if(status /= nf90_NoErr) call handle_error(status)
308  ...
309  ! Define the dimensions
310  status = nf90_def_dim(ncid, "lat", 5, LatDimId)
311  if(status /= nf90_NoErr) call handle_error(status)
312  status = nf90_def_dim(ncid, "lon", 10, LonDimId)
313  if(status /= nf90_NoErr) call handle_error(status)
314  status = nf90_def_dim(ncid, "time", nf90_unlimited, TimeDimId)
315  if(status /= nf90_NoErr) call handle_error(status)
316  ...
317  ! Define the variable
318  status = nf90_def_var(ncid, "rh", nf90_double, &
319  (/ LonDimId, LatDimID, TimeDimID /), RhVarId)
320  if(status /= nf90_NoErr) call handle_error(status)
321 
322 
323 ~~~~
324 
325 
326 In the following example, from nf\_test/f90tst\_vars2.f90, chunking,
327 checksums, and endianness control are all used in a netCDF-4/HDF5 file.
328 
329 
330 ~~~~.fortran
331 
332 
333  ! Create the netCDF file.
334  call check(nf90_create(FILE_NAME, nf90_netcdf4, ncid, cache_nelems = CACHE_NELEMS, &
335  cache_size = CACHE_SIZE))
336 
337  ! Define the dimensions.
338  call check(nf90_def_dim(ncid, "x", NX, x_dimid))
339  call check(nf90_def_dim(ncid, "y", NY, y_dimid))
340  dimids = (/ y_dimid, x_dimid /)
341 
342  ! Define some variables.
343  chunksizes = (/ NY, NX /)
344  call check(nf90_def_var(ncid, VAR1_NAME, NF90_INT, dimids, varid1, chunksizes = chunksizes, &
345  shuffle = .TRUE., fletcher32 = .TRUE., endianness = nf90_endian_big, deflate_level = DEFLATE_LEVEL))
346  call check(nf90_def_var(ncid, VAR2_NAME, NF90_INT, dimids, varid2, contiguous = .TRUE.))
347  call check(nf90_def_var(ncid, VAR3_NAME, NF90_INT64, varid3))
348  call check(nf90_def_var(ncid, VAR4_NAME, NF90_INT, x_dimid, varid4, contiguous = .TRUE.))
349 
350 
351 ~~~~
352 
353 
354 6.4 Define Fill Parameters for a Variable: `nf90_def_var_fill` {#f90-define-fill-parameters-for-a-variable-nf90_def_var_fill}
355 ===========
356 
357 
358 
359 The function NF90\_DEF\_VAR\_FILL sets the fill parameters for a
360 variable in a netCDF-4 file.
361 
362 This function must be called after the variable is defined, but before
363 NF90\_ENDDEF is called.
364 
365 
366 
367 ## Usage
368 
369 
370 
371 ~~~~.fortran
372 
373 NF90_DEF_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE);
374 
375 ~~~~
376 
377 
378 
379 `NCID`
380 
381 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
382 
383 `VARID`
384 
385 : Variable ID.
386 
387 `NO_FILL`
388 
389 : Set to non-zero value to set no\_fill mode on a variable. When this
390  mode is on, fill values will not be written for the variable. This
391  is helpful in high performance applications. For netCDF-4/HDF5 files
392  (whether classic model or not), this may only be changed after the
393  variable is defined, but before it is committed to disk (i.e. before
394  the first NF90\_ENDDEF after the NF90\_DEF\_VAR.) For classic and
395  64-bit offset file, the no\_fill mode may be turned on and off at
396  any time.
397 
398 `FILL_VALUE`
399 
400 : A value which will be used as the fill value for the variable. Must
401  be the same type as the variable. This will be written to a
402  \_FillValue attribute, created for this purpose. If NULL, this
403  argument will be ignored.
404 
405 
406 
407 ## Return Codes
408 
409 `NF90_NOERR`
410 
411 : No error.
412 
413 `NF90_BADID`
414 
415 : Bad ncid.
416 
417 `NF90_ENOTNC4`
418 
419 : Not a netCDF-4 file.
420 
421 `NF90_ENOTVAR`
422 
423 : Can’t find this variable.
424 
425 `NF90_ELATEDEF`
426 
427 : This variable has already been the subject of a NF90\_ENDDEF call.
428  In netCDF-4 files NF90\_ENDDEF will be called automatically for any
429  data read or write. Once enddef has been called, it is impossible to
430  set the fill for a variable.
431 
432 `NF90_ENOTINDEFINE`
433 
434 : Not in define mode. This is returned for netCDF classic or 64-bit
435  offset files, or for netCDF-4 files, when they were been created
436  with NF90\_STRICT\_NC3 flag. (see section
437  [NF90\_CREATE](#NF90_005fCREATE)).
438 
439 `NF90_EPERM`
440 
441 : Attempt to create object in read-only file.
442 
443 
444 
445 ## Example
446 
447 
448 6.5 Learn About Fill Parameters for a Variable: `NF90_INQ_VAR_FILL` {#f90-learn-about-fill-parameters-for-a-variable-nf90_inq_var_fill}
449 ===========
450 
451 
452 
453 The function NF90\_INQ\_VAR\_FILL returns the fill settings for a
454 variable in a netCDF-4 file.
455 
456 
457 
458 ## Usage
459 
460 
461 
462 ~~~~.fortran
463 
464 NF90_INQ_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE)
465 
466 ~~~~
467 
468 
469 
470 `NCID`
471 
472 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
473 
474 `VARID`
475 
476 : Variable ID.
477 
478 `NO_FILL`
479 
480 : An integer which will get a 1 if no\_fill mode is set for this
481  variable, and a zero if it is not set
482 
483 `FILL_VALUE`
484 
485 : This will get the fill value for this variable. This parameter will
486  be ignored if it is NULL.
487 
488 
489 
490 ## Return Codes
491 
492 `NF90_NOERR`
493 
494 : No error.
495 
496 `NF90_BADID`
497 
498 : Bad ncid.
499 
500 `NF90_ENOTNC4`
501 
502 : Not a netCDF-4 file.
503 
504 `NF90_ENOTVAR`
505 
506 : Can’t find this variable.
507 
508 
509 
510 ## Example
511 
512 6.6 Define Filter Parameters for a Variable: `nf90_def_var_filter` {#f90-define-filter-parameters-for-a-variable-nf90_def_var_filter}
513 ===========
514 
515 
516 
517 The function nf90\_def\_var\_filter sets the filter parameters for a
518 variable in a netCDF-4 file.
519 
520 This function must be called after the variable is defined, but before
521 nf90\_enddef is called.
522 
523 
524 
525 ## Usage
526 
527 
528 ~~~~.fortran
529 
530 function nf90_def_var_filter(ncid, varid, filterid, nparams, params);
531  integer, intent(in) :: ncid, varid, filterid, nparams
532  integer, dimension(:), intent(in) :: params
533 
534 ~~~~
535 
536 
537 `ncid`
538 
539 : NetCDF ID, from a previous call to nf90\_open or nf90\_create.
540 
541 `varid`
542 
543 : Variable ID.
544 
545 `filterid`
546 
547 : The HDFGroup assigned filter id (e.g. 307 for bzip2).
548 
549 `nparams`
550 
551 : The number of parameters for the filter
552 
553 `params`
554 
555 : A vector of parameters of size nparams.
556 
557 
558 ## Return Codes
559 
560 `NF90_NOERR`
561 
562 : No error.
563 
564 `NF90_BADID`
565 
566 : Bad ncid.
567 
568 `NF90_ENOTNC4`
569 
570 : Not a netCDF-4 file.
571 
572 `NF90_ENOTVAR`
573 
574 : Can’t find this variable.
575 
576 `NF90_ELATEDEF`
577 
578 : This variable has already been the subject of a NF90\_ENDDEF call.
579  In netCDF-4 files NF90\_ENDDEF will be called automatically for any
580  data read or write. Once enddef has been called, it is impossible to
581  set the fill for a variable.
582 
583 `NF90_ENOTINDEFINE`
584 
585 : Not in define mode. This is returned for netCDF classic or 64-bit
586  offset files, or for netCDF-4 files, when they were been created
587  with NF90\_STRICT\_NC3 flag. (see section
588  [NF90\_CREATE](#NF90_005fCREATE)).
589 
590 `NF90_EPERM`
591 
592 : Attempt to create object in read-only file.
593 
594 `NF90_EFILTER`
595 
596 : Invalid filter id or parameters
597 
598 
599 ## Example
600 
601 6.7 Get information about any Filter associated with a variable: `nf90_inq_var_filter` {#f90-get-information-about-a-variable-from-its-id-nf90_inq_var_filter}
602 ===========
603 
604 
605 The function nf90\_inq\_var\_filter gets the filter id and parameters for a
606 variable in a netCDF-4 file.
607 
608 
609 ## Usage
610 
611 
612 ~~~~.fortran
613 
614 function nf90_inq_var_filter(ncid, varid, filterid, nparams, params);
615  integer, intent(in) :: ncid, varid, filterid, nparams
616  integer, intent(out) :: filterid, nparams
617  integer, dimension(:), intent(out) :: params
618 
619 ~~~~
620 
621 
622 `ncid`
623 
624 : NetCDF ID, from a previous call to nf90\_open or nf90\_create.
625 
626 `varid`
627 
628 : Variable ID.
629 
630 `filterid`
631 
632 : Store the the HDFGroup assigned filter id
633 
634 `nparams`
635 
636 : Stor the number of parameters for the filter
637 
638 `params`
639 
640 : Store the vector of parameters of size nparams.
641 
642 ## Return Codes
643 
644 `NF90_NOERR`
645 
646 : No error.
647 
648 `NF90_BADID`
649 
650 : Bad ncid.
651 
652 `NF90_ENOTNC4`
653 
654 : Not a netCDF-4 file.
655 
656 `NF90_ENOTVAR`
657 
658 : Can’t find this variable.
659 
660 `NF90_ELATEDEF`
661 
662 : This variable has already been the subject of a NF90\_ENDDEF call.
663  In netCDF-4 files NF90\_ENDDEF will be called automatically for any
664  data read or write. Once enddef has been called, it is impossible to
665  set the fill for a variable.
666 
667 `NF90_ENOTINDEFINE`
668 
669 : Not in define mode. This is returned for netCDF classic or 64-bit
670  offset files, or for netCDF-4 files, when they were been created
671  with NF90\_STRICT\_NC3 flag. (see section
672  [NF90\_CREATE](#NF90_005fCREATE)).
673 
674 `NF90_EPERM`
675 
676 : Attempt to create object in read-only file.
677 
678 `NF90_EFILTER`
679 
680 : Invalid filter id or parameters
681 
682 
683 ## Example
684 
685 
686 6.8 Get Information about a Variable from Its ID: NF90_INQUIRE_VARIABLE {#f90-get-information-about-a-variable-from-its-id-nf90_inquire_variable}
687 ===========
688 
689 NF90\_INQUIRE\_VARIABLE returns information about a netCDF variable
690 given its ID. Information about a variable includes its name, type,
691 number of dimensions, a list of dimension IDs describing the shape of
692 the variable, and the number of variable attributes that have been
693 assigned to the variable.
694 
695 All parameters after nAtts are optional, and only supported if netCDF
696 was built with netCDF-4 features enabled, and if the variable is in a
697 netCDF-4/HDF5 file.
698 
699 
700 
701 ## Usage
702 
703 
704 ~~~~.fortran
705 
706 
707  function nf90_inquire_variable(ncid, varid, name, xtype, ndims, dimids, nAtts, &
708  contiguous, chunksizes, deflate_level, shuffle, fletcher32, endianness)
709  integer, intent(in) :: ncid, varid
710  character (len = *), optional, intent(out) :: name
711  integer, optional, intent(out) :: xtype, ndims
712  integer, dimension(:), optional, intent(out) :: dimids
713  integer, optional, intent(out) :: nAtts
714  logical, optional, intent(out) :: contiguous
715  integer, optional, dimension(:), intent(out) :: chunksizes
716  integer, optional, intent(out) :: deflate_level
717  logical, optional, intent(out) :: shuffle, fletcher32
718  integer, optional, intent(out) :: endianness
719  integer :: nf90_inquire_variable
720 
721 
722 
723 ~~~~
724 
725 `ncid`
726 
727 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
728 
729 `varid`
730 
731 : Variable ID.
732 
733 `name`
734 
735 : Returned variable name. The caller must allocate space for the
736  returned name. The maximum possible length, in characters, of a
737  variable name is given by the predefined constant NF90\_MAX\_NAME.
738 
739 `xtype`
740 
741 : Returned variable type, one of the set of predefined netCDF external
742  data types. The valid netCDF external data types are NF90\_BYTE,
743  NF90\_CHAR, NF90\_SHORT, NF90\_INT, NF90\_FLOAT, AND NF90\_DOUBLE.
744 
745 `ndims`
746 
747 : Returned number of dimensions the variable was defined as using. For
748  example, 2 indicates a matrix, 1 indicates a vector, and 0 means the
749  variable is a scalar with no dimensions.
750 
751 `dimids`
752 
753 : Returned vector of \*ndimsp dimension IDs corresponding to the
754  variable dimensions. The caller must allocate enough space for a
755  vector of at least \*ndimsp integers to be returned. The maximum
756  possible number of dimensions for a variable is given by the
757  predefined constant NF90\_MAX\_VAR\_DIMS.
758 
759 `natts`
760 
761 : Returned number of variable attributes assigned to this variable.
762 
763 `contiguous`
764 
765 : On return, set to NF90\_CONTIGUOUS if this variable uses contiguous
766  storage, NF90\_CHUNKED if it uses chunked storage.
767 
768 `chunksizes`
769 
770 : An array of chunk sizes. The array must have the one element for
771  each dimension in the variable.
772 
773 `shuffle`
774 
775 : True if the shuffle filter is turned on for this variable.
776 
777 `deflate_level`
778 
779 : The deflate\_level from 0 to 9. A value of zero indicates no
780  deflation is in use.
781 
782 `fletcher32`
783 
784 : Set to true if the fletcher32 checksum filter is turned on for
785  this variable.
786 
787 `endianness`
788 
789 : Will be set to NF90\_ENDIAN\_LITTLE if this variable is stored in
790  little-endian format, NF90\_ENDIAN\_BIG if it is stored in
791  big-endian format, and NF90\_ENDIAN\_NATIVE if the endianness is not
792  set, and the variable is not created yet.
793 
794 These functions return the value NF90\_NOERR if no errors occurred.
795 Otherwise, the returned status indicates an error. Possible causes of
796 errors include:
797 
798 - The variable ID is invalid for the specified netCDF dataset.
799 - The specified netCDF ID does not refer to an open netCDF dataset.
800 
801 
802 
803 ## Example
804 
805 Here is an example using NF90\_INQ\_VAR to find out about a variable
806 named rh in an existing netCDF dataset named foo.nc:
807 
808 
809 ~~~~.fortran
810 
811 
812  use netcdf
813  implicit none
814  integer :: status, ncid, &
815  RhVarId &
816  numDims, numAtts
817  integer, dimension(nf90_max_var_dims) :: rhDimIds
818  ...
819  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
820  if(status /= nf90_NoErr) call handle_error(status)
821  ...
822  status = nf90_inq_varid(ncid, "rh", RhVarId)
823  if(status /= nf90_NoErr) call handle_err(status)
824  status = nf90_inquire_variable(ncid, RhVarId, ndims = numDims, natts = numAtts)
825  if(status /= nf90_NoErr) call handle_err(status)
826  status = nf90_inquire_variable(ncid, RhVarId, dimids = rhDimIds(:numDims))
827  if(status /= nf90_NoErr) call handle_err(status)
828 
829 
830 ~~~~
831 
832 
833 6.9 Get the ID of a variable from the name: NF90_INQ_VARID {#f90-get-the-id-of-a-variable-from-the-name-nf90_inq_varid}
834 ===========
835 
836 
837 
838 Given the name of a variable, nf90\_inq\_varid finds the variable ID.
839 
840 
841 
842 ## Usage
843 
844 
845 ~~~~.fortran
846 
847 
848  function nf90_inq_varid(ncid, name, varid)
849  integer, intent(in) :: ncid
850  character (len = *), intent( in) :: name
851  integer, intent(out) :: varid
852  integer :: nf90_inq_varid
853 
854 
855 ~~~~
856 
857 
858 `ncid`
859 
860 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
861 
862 `name`
863 
864 : The variable name. The maximum possible length, in characters, of a
865  variable name is given by the predefined constant NF90\_MAX\_NAME.
866 
867 `varid`
868 
869 : Variable ID.
870 
871 These functions return the value NF90\_NOERR if no errors occurred.
872 Otherwise, the returned status indicates an error. Possible causes of
873 errors include:
874 
875 - Variable not found.
876 - The specified netCDF ID does not refer to an open netCDF dataset.
877 
878 
879 
880 ## Example
881 
882 Here is an example using NF90\_INQ\_VARID to find out about a variable
883 named rh in an existing netCDF dataset named foo.nc:
884 
885 
886 
887 ~~~~.fortran
888 
889  use netcdf
890  implicit none
891  integer :: status, ncid, &
892  RhVarId &
893  numDims, numAtts
894  integer, dimension(nf90_max_var_dims) :: rhDimIds
895  ...
896  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
897  if(status /= nf90_NoErr) call handle_error(status)
898  ...
899  status = nf90_inq_varid(ncid, "rh", RhVarId)
900  if(status /= nf90_NoErr) call handle_err(status)
901  status = nf90_inquire_variable(ncid, RhVarId, ndims = numDims, natts = numAtts)
902  if(status /= nf90_NoErr) call handle_err(status)
903  status = nf90_inquire_variable(ncid, RhVarId, dimids = rhDimIds(:numDims))
904  if(status /= nf90_NoErr) call handle_err(status)
905 
906 
907 
908 ~~~~
909 
910 
911 6.10 Writing Data Values: NF90_PUT_VAR {#f90-writing-data-values-nf90_put_var}
912 ===========
913 
914 
915 
916 The function NF90\_PUT\_VAR puts one or more data values into the
917 variable of an open netCDF dataset that is in data mode. Required inputs
918 are the netCDF ID, the variable ID, and one or more data values.
919 Optional inputs may indicate the starting position of the data values in
920 the netCDF variable (argument start), the sampling frequency with which
921 data values are written into the netCDF variable (argument stride), and
922 a mapping between the dimensions of the data array and the netCDF
923 variable (argument map). The values to be written are associated with
924 the netCDF variable by assuming that the first dimension of the netCDF
925 variable varies fastest in the Fortran 90 interface. Data values are
926 converted to the external type of the variable, if necessary.
927 
928 Take care when using the simplest forms of this interface with record
929 variables (variables that use the NF90\_UNLIMITED dimension) when you
930 don’t specify how many records are to be written. If you try to write
931 all the values of a record variable into a netCDF file that has no
932 record data yet (hence has 0 records), nothing will be written.
933 Similarly, if you try to write all the values of a record variable from
934 an array but there are more records in the file than you assume, more
935 in-memory data will be accessed than you expect, which may cause a
936 segmentation violation. To avoid such problems, it is better to specify
937 start and count arguments for variables that use the NF90\_UNLIMITED
938 dimension.
939 
940 
941 
942 ### Usage
943 
944 
945 
946 ~~~~.fortran
947 
948  function nf90_put_var(ncid, varid, values, start, count, stride, map)
949  integer, intent( in) :: ncid, varid
950  any valid type, scalar or array of any rank, &
951  intent( in) :: values
952  integer, dimension(:), optional, intent( in) :: start, count, stride, map
953  integer :: nf90_put_var
954 
955 
956 ~~~~
957 
958 
959 `ncid`
960 
961 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
962 
963 `varid`
964 
965 : Variable ID.
966 
967 `values`
968 
969 : The data value(s) to be written. The data may be of any type, and
970  may be a scalar or an array of any rank. You cannot put CHARACTER
971  data into a numeric variable or numeric data into a text variable.
972  For numeric data, if the type of data differs from the netCDF
973  variable type, type conversion will occur. See [Type
974  Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide.
975 
976 `start`
977 
978 : A vector of integers specifying the index in the variable where the
979  first (or only) of the data values will be written. The indices are
980  relative to 1, so for example, the first data value of a variable
981  would have index (1, 1, ..., 1). The elements of start correspond,
982  in order, to the variable’s dimensions. Hence, if the variable is a
983  record variable, the last index would correspond to the starting
984  record number for writing the data values.
985 
986  By default, start(:) = 1.
987 
988 `count`
989 
990 : A vector of integers specifying the number of indices selected along
991  each dimension. To write a single value, for example, specify count
992  as (1, 1, ..., 1). The elements of count correspond, in order, to
993  the variable’s dimensions. Hence, if the variable is a record
994  variable, the last element of count corresponds to a count of the
995  number of records to write.
996 
997  By default, count(:numDims) = shape(values) and count(numDims + 1:)
998  = 1, where numDims = size(shape(values)).
999 
1000 `stride`
1001 
1002 : A vector of integers that specifies the sampling interval along each
1003  dimension of the netCDF variable. The elements of the stride vector
1004  correspond, in order, to the netCDF variable’s dimensions (stride(1)
1005  gives the sampling interval along the most rapidly varying dimension
1006  of the netCDF variable). Sampling intervals are specified in
1007  type-independent units of elements (a value of 1 selects consecutive
1008  elements of the netCDF variable along the corresponding dimension, a
1009  value of 2 selects every other element, etc.).
1010 
1011  By default, stride(:) = 1.
1012 
1013 `imap`
1014 
1015 : A vector of integers that specifies the mapping between the
1016  dimensions of a netCDF variable and the in-memory structure of the
1017  internal data array. The elements of the index mapping vector
1018  correspond, in order, to the netCDF variable’s dimensions (map(1)
1019  gives the distance between elements of the internal array
1020  corresponding to the most rapidly varying dimension of the
1021  netCDF variable). Distances between elements are specified in units
1022  of elements.
1023 
1024  By default, edgeLengths = shape(values), and map = (/ 1,
1025  (product(edgeLengths(:i)), i = 1, size(edgeLengths) - 1) /), that
1026  is, there is no mapping.
1027 
1028  Use of Fortran 90 intrinsic functions (including reshape, transpose,
1029  and spread) may let you avoid using this argument.
1030 
1031 
1032 
1033 ## Errors
1034 
1035 NF90\_PUT\_VAR1\_ type returns the value NF90\_NOERR if no errors
1036 occurred. Otherwise, the returned status indicates an error. Possible
1037 causes of errors include:
1038 
1039 - The variable ID is invalid for the specified netCDF dataset.
1040 - The specified indices were out of range for the rank of the
1041  specified variable. For example, a negative index or an index that
1042  is larger than the corresponding dimension length will cause
1043  an error.
1044 - The specified value is out of the range of values representable by
1045  the external data type of the variable.
1046 - The specified netCDF is in define mode rather than data mode.
1047 - The specified netCDF ID does not refer to an open netCDF dataset.
1048 
1049 
1050 
1051 ## Example
1052 
1053 Here is an example using NF90\_PUT\_VAR to set the (4,3,2) element of
1054 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
1055 For simplicity in this example, we assume that we know that rh is
1056 dimensioned with lon, lat, and time, so we want to set the value of rh
1057 that corresponds to the fourth lon value, the third lat value, and the
1058 second time value:
1059 
1060 
1061 
1062 ~~~~.fortran
1063 
1064  use netcdf
1065  implicit none
1066  integer :: ncId, rhVarId, status
1067  ...
1068  status = nf90_open("foo.nc", nf90_Write, ncid)
1069  if(status /= nf90_NoErr) call handle_err(status)
1070  ...
1071  status = nf90_inq_varid(ncid, "rh", rhVarId)
1072  if(status /= nf90_NoErr) call handle_err(status)
1073  status = nf90_put_var(ncid, rhVarId, 0.5, start = (/ 4, 3, 2 /) )
1074  if(status /= nf90_NoErr) call handle_err(status)
1075 
1076 
1077 ~~~~
1078 
1079 
1080 In this example we use NF90\_PUT\_VAR to add or change all the values of
1081 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
1082 We assume that we know that rh is dimensioned with lon, lat, and time.
1083 In this example we query the netCDF file to discover the lengths of the
1084 dimensions, then use the Fortran 90 intrinsic function reshape to create
1085 a temporary array of data values which is the same shape as the netCDF
1086 variable.
1087 
1088 
1089 ~~~~.fortran
1090 
1091 
1092  use netcdf
1093  implicit none
1094  integer :: ncId, rhVarId,status, &
1095  lonDimID, latDimId, timeDimId, &
1096  numLons, numLats, numTimes, &
1097  i
1098  integer, dimension(nf90_max_var_dims) :: dimIDs
1099  ...
1100  status = nf90_open("foo.nc", nf90_Write, ncid)
1101  if(status /= nf90_NoErr) call handle_err(status)
1102  ...
1103  status = nf90_inq_varid(ncid, "rh", rhVarId)
1104  if(status /= nf90_NoErr) call handle_err(status)
1105  ! How big is the netCDF variable, that is, what are the lengths of
1106  ! its constituent dimensions?
1107  status = nf90_inquire_variable(ncid, rhVarId, dimids = dimIDs)
1108  if(status /= nf90_NoErr) call handle_err(status)
1109  status = nf90_inquire_dimension(ncid, dimIDs(1), len = numLons)
1110  if(status /= nf90_NoErr) call handle_err(status)
1111  status = nf90_inquire_dimension(ncid, dimIDs(2), len = numLats)
1112  if(status /= nf90_NoErr) call handle_err(status)
1113  status = nf90_inquire_dimension(ncid, dimIDs(3), len = numTimes)
1114  if(status /= nf90_NoErr) call handle_err(status)
1115  ...
1116  ! Make a temporary array the same shape as the netCDF variable.
1117  status = nf90_put_var(ncid, rhVarId, &
1118  reshape( &
1119  (/ (0.5, i = 1, numLons * numLats * numTimes) /) , &
1120  shape = (/ numLons, numLats, numTimes /) )
1121  if(status /= nf90_NoErr) call handle_err(status)
1122 
1123 
1124 ~~~~
1125 
1126 
1127 Here is an example using NF90\_PUT\_VAR to add or change a section of
1128 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
1129 For simplicity in this example, we assume that we know that rh is
1130 dimensioned with lon, lat, and time, that there are ten lon values, five
1131 lat values, and three time values, and that we want to replace all the
1132 values at the last time.
1133 
1134 
1135 
1136 ~~~~.fortran
1137 
1138  use netcdf
1139  implicit none
1140  integer :: ncId, rhVarId, status
1141  integer, parameter :: numLons = 10, numLats = 5, numTimes = 3
1142  real, dimension(numLons, numLats) &
1143  :: rhValues
1144  ...
1145  status = nf90_open("foo.nc", nf90_Write, ncid)
1146  if(status /= nf90_NoErr) call handle_err(status)
1147  ...
1148  status = nf90_inq_varid(ncid, "rh", rhVarId)
1149  if(status /= nf90_NoErr) call handle_err(status)
1150  ! Fill in all values at the last time
1151  rhValues(:, :) = 0.5
1152  status = nf90_put_var(ncid, rhVarId,rhvalues, &
1153  start = (/ 1, 1, numTimes /), &
1154  count = (/ numLats, numLons, 1 /))
1155  if(status /= nf90_NoErr) call handle_err(status)
1156 
1157 
1158 ~~~~
1159 
1160 
1161 Here is an example of using NF90\_PUT\_VAR to write every other point of
1162 a netCDF variable named rh having dimensions (6, 4).
1163 
1164 
1165 
1166 ~~~~.fortran
1167 
1168  use netcdf
1169  implicit none
1170  integer :: ncId, rhVarId, status
1171  integer, parameter :: numLons = 6, numLats = 4
1172  real, dimension(numLons, numLats) &
1173  :: rhValues = 0.5
1174  ...
1175  status = nf90_open("foo.nc", nf90_Write, ncid)
1176  if(status /= nf90_NoErr) call handle_err(status)
1177  ...
1178  status = nf90_inq_varid(ncid, "rh", rhVarId)
1179  if(status /= nf90_NoErr) call handle_err(status)
1180  ...
1181  ! Fill in every other value using an array section
1182  status = nf90_put_var(ncid, rhVarId, rhValues(::2, ::2), &
1183  stride = (/ 2, 2 /))
1184  if(status /= nf90_NoErr) call handle_err(status)
1185 
1186 
1187 ~~~~
1188 
1189 
1190 The following map vector shows the default mapping between a 2x3x4
1191 netCDF variable and an internal array of the same shape:
1192 
1193 
1194 ~~~~.fortran
1195 
1196 
1197  real, dimension(2, 3, 4):: a ! same shape as netCDF variable
1198  integer, dimension(3) :: map = (/ 1, 2, 6 /)
1199  ! netCDF dimension inter-element distance
1200  ! ---------------- ----------------------
1201  ! most rapidly varying 1
1202  ! intermediate 2 (= map(1)*2)
1203  ! most slowly varying 6 (= map(2)*3)
1204 
1205 
1206 ~~~~
1207 
1208 
1209 Using the map vector above obtains the same result as simply not passing
1210 a map vector at all.
1211 
1212 Here is an example of using nf90\_put\_var to write a netCDF variable
1213 named rh whose dimensions are the transpose of the Fortran 90 array:
1214 
1215 
1216 ~~~~.fortran
1217 
1218 
1219  use netcdf
1220  implicit none
1221  integer :: ncId, rhVarId, status
1222  integer, parameter :: numLons = 6, numLats = 4
1223  real, dimension(numLons, numLats) :: rhValues
1224  ! netCDF variable has dimensions (numLats, numLons)
1225  ...
1226  status = nf90_open("foo.nc", nf90_Write, ncid)
1227  if(status /= nf90_NoErr) call handle_err(status)
1228  ...
1229  status = nf90_inq_varid(ncid, "rh", rhVarId)
1230  if(status /= nf90_NoErr) call handle_err(status)
1231  ...
1232  !Write transposed values: map vector would be (/ 1, numLats /) for
1233  ! no transposition
1234  status = nf90_put_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /))
1235  if(status /= nf90_NoErr) call handle_err(status)
1236 
1237 
1238 ~~~~
1239 
1240 
1241 The same effect can be obtained more simply using Fortran 90 intrinsic
1242 functions:
1243 
1244 
1245 
1246 ~~~~.fortran
1247 
1248  use netcdf
1249  implicit none
1250  integer :: ncId, rhVarId, status
1251  integer, parameter :: numLons = 6, numLats = 4
1252  real, dimension(numLons, numLats) :: rhValues
1253  ! netCDF variable has dimensions (numLats, numLons)
1254  ...
1255  status = nf90_open("foo.nc", nf90_Write, ncid)
1256  if(status /= nf90_NoErr) call handle_err(status)
1257  ...
1258  status = nf90_inq_varid(ncid, "rh", rhVarId)
1259  if(status /= nf90_NoErr) call handle_err(status)
1260  ...
1261  status = nf90_put_var(ncid, rhVarId, transpose(rhValues))
1262  if(status /= nf90_NoErr) call handle_err(status)
1263 
1264 
1265 ~~~~
1266 
1267 
1268 
1269 6.11 Reading Data Values: NF90_GET_VAR {#f90-reading-data-values-nf90_get_var}
1270 ===========
1271 
1272 
1273 
1274 The function NF90\_GET\_VAR gets one or more data values from a netCDF
1275 variable of an open netCDF dataset that is in data mode. Required inputs
1276 are the netCDF ID, the variable ID, and a specification for the data
1277 values into which the data will be read. Optional inputs may indicate
1278 the starting position of the data values in the netCDF variable
1279 (argument start), the sampling frequency with which data values are read
1280 from the netCDF variable (argument stride), and a mapping between the
1281 dimensions of the data array and the netCDF variable (argument map). The
1282 values to be read are associated with the netCDF variable by assuming
1283 that the first dimension of the netCDF variable varies fastest in the
1284 Fortran 90 interface. Data values are converted from the external type
1285 of the variable, if necessary.
1286 
1287 Take care when using the simplest forms of this interface with record
1288 variables (variables that use the NF90\_UNLIMITED dimension) when you
1289 don’t specify how many records are to be read. If you try to read all
1290 the values of a record variable into an array but there are more records
1291 in the file than you assume, more data will be read than you expect,
1292 which may cause a segmentation violation. To avoid such problems, it is
1293 better to specify the optional start and count arguments for variables
1294 that use the NF90\_UNLIMITED dimension.
1295 
1296 In netCDF classic model the maximum integer size is NF90\_INT, the
1297 4-byte signed integer. Reading variables into an eight-byte integer
1298 array from a classic model file will read from an NF90\_INT. Reading
1299 variables into an eight-byte integer in a netCDF-4/HDF5 (without classic
1300 model flag) will read from an NF90\_INT64
1301 
1302 
1303 
1304 ## Usage
1305 
1306 
1307 
1308 ~~~~.fortran
1309 
1310  function nf90_get_var(ncid, varid, values, start, count, stride, map)
1311  integer, intent( in) :: ncid, varid
1312  any valid type, scalar or array of any rank, &
1313  intent(out) :: values
1314  integer, dimension(:), optional, intent( in) :: start, count, stride, map
1315  integer :: nf90_get_var
1316 
1317 
1318 ~~~~
1319 
1320 
1321 `ncid`
1322 
1323 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1324 
1325 `varid`
1326 
1327 : Variable ID.
1328 
1329 `values`
1330 
1331 : The data value(s) to be read. The data may be of any type, and may
1332  be a scalar or an array of any rank. You cannot read CHARACTER data
1333  from a numeric variable or numeric data from a text variable. For
1334  numeric data, if the type of data differs from the netCDF variable
1335  type, type conversion will occur. See [Type
1336  Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide.
1337 
1338 `start`
1339 
1340 : A vector of integers specifying the index in the variable from which
1341  the first (or only) of the data values will be read. The indices are
1342  relative to 1, so for example, the first data value of a variable
1343  would have index (1, 1, ..., 1). The elements of start correspond,
1344  in order, to the variable’s dimensions. Hence, if the variable is a
1345  record variable, the last index would correspond to the starting
1346  record number for writing the data values.
1347 
1348  By default, start(:) = 1.
1349 
1350 `count`
1351 
1352 : A vector of integers specifying the number of indices selected along
1353  each dimension. To read a single value, for example, specify count
1354  as (1, 1, ..., 1). The elements of count correspond, in order, to
1355  the variable’s dimensions. Hence, if the variable is a record
1356  variable, the last element of count corresponds to a count of the
1357  number of records to read.
1358 
1359  By default, count(:numDims) = shape(values) and count(numDims + 1:)
1360  = 1, where numDims = size(shape(values)).
1361 
1362 `stride`
1363 
1364 : A vector of integers that specifies the sampling interval along each
1365  dimension of the netCDF variable. The elements of the stride vector
1366  correspond, in order, to the netCDF variable’s dimensions (stride(1)
1367  gives the sampling interval along the most rapidly varying dimension
1368  of the netCDF variable). Sampling intervals are specified in
1369  type-independent units of elements (a value of 1 selects consecutive
1370  elements of the netCDF variable along the corresponding dimension, a
1371  value of 2 selects every other element, etc.).
1372 
1373  By default, stride(:) = 1.
1374 
1375 `map`
1376 
1377 : A vector of integers that specifies the mapping between the
1378  dimensions of a netCDF variable and the in-memory structure of the
1379  internal data array. The elements of the index mapping vector
1380  correspond, in order, to the netCDF variable’s dimensions (map(1)
1381  gives the distance between elements of the internal array
1382  corresponding to the most rapidly varying dimension of the
1383  netCDF variable). Distances between elements are specified in units
1384  of elements.
1385 
1386  By default, edgeLengths = shape(values), and map = (/ 1,
1387  (product(edgeLengths(:i)), i = 1, size(edgeLengths) - 1) /), that
1388  is, there is no mapping.
1389 
1390  Use of Fortran 90 intrinsic functions (including reshape, transpose,
1391  and spread) may let you avoid using this argument.
1392 
1393 
1394 
1395 ## Errors
1396 
1397 NF90\_GET\_VAR returns the value NF90\_NOERR if no errors occurred.
1398 Otherwise, the returned status indicates an error. Possible causes of
1399 errors include:
1400 
1401 - The variable ID is invalid for the specified netCDF dataset.
1402 - The assumed or specified start, count, and stride generate an index
1403  which is out of range. Note that no error checking is possible on
1404  the map vector.
1405 - One or more of the specified values are out of the range of values
1406  representable by the desired type.
1407 - The specified netCDF is in define mode rather than data mode.
1408 - The specified netCDF ID does not refer to an open netCDF dataset.
1409 
1410 (As noted above, another possible source of error is using this
1411 interface to read all the values of a record variable without specifying
1412 the number of records. If there are more records in the file than you
1413 assume, more data will be read than you expect!)
1414 
1415 
1416 
1417 ## Example
1418 
1419 Here is an example using NF90\_GET\_VAR to read the (4,3,2) element of
1420 the variable named rh from an existing netCDF dataset named foo.nc. For
1421 simplicity in this example, we assume that we know that rh is
1422 dimensioned with lon, lat, and time, so we want to read the value of rh
1423 that corresponds to the fourth lon value, the third lat value, and the
1424 second time value:
1425 
1426 
1427 
1428 ~~~~.fortran
1429 
1430  use netcdf
1431  implicit none
1432  integer :: ncId, rhVarId, status
1433  real :: rhValue
1434  ...
1435  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1436  if(status /= nf90_NoErr) call handle_err(status)
1437  -
1438  status = nf90_inq_varid(ncid, "rh", rhVarId)
1439  if(status /= nf90_NoErr) call handle_err(status)
1440  status = nf90_get_var(ncid, rhVarId, rhValue, start = (/ 4, 3, 2 /) )
1441  if(status /= nf90_NoErr) call handle_err(status)
1442 
1443 
1444 ~~~~
1445 
1446 
1447 In this example we use NF90\_GET\_VAR to read all the values of the
1448 variable named rh from an existing netCDF dataset named foo.nc. We
1449 assume that we know that rh is dimensioned with lon, lat, and time. In
1450 this example we query the netCDF file to discover the lengths of the
1451 dimensions, then allocate a Fortran 90 array the same shape as the
1452 netCDF variable.
1453 
1454 
1455 
1456 
1457  use netcdf
1458  implicit none
1459  integer :: ncId, rhVarId, &
1460  lonDimID, latDimId, timeDimId, &
1461  numLons, numLats, numTimes, &
1462  status
1463  integer, dimension(nf90_max_var_dims) :: dimIDs
1464  real, dimension(:, :, :), allocatable :: rhValues
1465  ...
1466  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1467  if(status /= nf90_NoErr) call handle_err(status)
1468  ...
1469  status = nf90_inq_varid(ncid, "rh", rhVarId)
1470  if(status /= nf90_NoErr) call handle_err(status)
1471  ! How big is the netCDF variable, that is, what are the lengths of
1472  ! its constituent dimensions?
1473  status = nf90_inquire_variable(ncid, rhVarId, dimids = dimIDs)
1474  if(status /= nf90_NoErr) call handle_err(status)
1475  status = nf90_inquire_dimension(ncid, dimIDs(1), len = numLons)
1476  if(status /= nf90_NoErr) call handle_err(status)
1477  status = nf90_inquire_dimension(ncid, dimIDs(2), len = numLats)
1478  if(status /= nf90_NoErr) call handle_err(status)
1479  status = nf90_inquire_dimension(ncid, dimIDs(3), len = numTimes)
1480  if(status /= nf90_NoErr) call handle_err(status)
1481  allocate(rhValues(numLons, numLats, numTimes))
1482  ...
1483  status = nf90_get_var(ncid, rhVarId, rhValues)
1484  if(status /= nf90_NoErr) call handle_err(status)
1485 
1486 
1487 
1488 
1489 Here is an example using NF90\_GET\_VAR to read a section of the
1490 variable named rh from an existing netCDF dataset named foo.nc. For
1491 simplicity in this example, we assume that we know that rh is
1492 dimensioned with lon, lat, and time, that there are ten lon values, five
1493 lat values, and three time values, and that we want to replace all the
1494 values at the last time.
1495 
1496 
1497 ~~~~.fortran
1498 
1499 
1500  use netcdf
1501  implicit none
1502  integer :: ncId, rhVarId, status
1503  integer, parameter :: numLons = 10, numLats = 5, numTimes = 3
1504  real, dimension(numLons, numLats, numTimes) &
1505  :: rhValues
1506  ...
1507  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1508  if(status /= nf90_NoErr) call handle_err(status)
1509  ...
1510  status = nf90_inq_varid(ncid, "rh", rhVarId)
1511  if(status /= nf90_NoErr) call handle_err(status)
1512  !Read the values at the last time by passing an array section
1513  status = nf90_get_var(ncid, rhVarId, rhValues(:, :, 3), &
1514  start = (/ 1, 1, numTimes /), &
1515  count = (/ numLons, numLats, 1 /))
1516  if(status /= nf90_NoErr) call handle_err(status)
1517 
1518 
1519 ~~~~
1520 
1521 
1522 Here is an example of using NF90\_GET\_VAR to read every other point of
1523 a netCDF variable named rh having dimensions (6, 4).
1524 
1525 
1526 ~~~~.fortran
1527 
1528 
1529  use netcdf
1530  implicit none
1531  integer :: ncId, rhVarId, status
1532  integer, parameter :: numLons = 6, numLats = 4
1533  real, dimension(numLons, numLats) &
1534  :: rhValues
1535  ...
1536  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1537  if(status /= nf90_NoErr) call handle_err(status)
1538  ...
1539  status = nf90_inq_varid(ncid, "rh", rhVarId)
1540  if(status /= nf90_NoErr) call handle_err(status)
1541  ...
1542  ! Read every other value into an array section
1543  status = nf90_get_var(ncid, rhVarId, rhValues(::2, ::2) &
1544  stride = (/ 2, 2 /))
1545  if(status /= nf90_NoErr) call handle_err(status)
1546 
1547 
1548 
1549 ~~~~
1550 
1551 The following map vector shows the default mapping between a 2x3x4
1552 netCDF variable and an internal array of the same shape:
1553 
1554 
1555 ~~~~.fortran
1556 
1557 
1558  real, dimension(2, 3, 4):: a ! same shape as netCDF variable
1559  integer, dimension(3) :: map = (/ 1, 2, 6 /)
1560  ! netCDF dimension inter-element distance
1561  ! ---------------- ----------------------
1562  ! most rapidly varying 1
1563  ! intermediate 2 (= map(1)*2)
1564  ! most slowly varying 6 (= map(2)*3)
1565 
1566 
1567 
1568 
1569 ~~~~
1570 
1571 Using the map vector above obtains the same result as simply not passing
1572 a map vector at all.
1573 
1574 Here is an example of using nf90\_get\_var to read a netCDF variable
1575 named rh whose dimensions are the transpose of the Fortran 90 array:
1576 
1577 
1578 
1579 ~~~~.fortran
1580 
1581  use netcdf
1582  implicit none
1583  integer :: ncId, rhVarId, status
1584  integer, parameter :: numLons = 6, numLats = 4
1585  real, dimension(numLons, numLats) :: rhValues
1586  ! netCDF variable has dimensions (numLats, numLons)
1587  ...
1588  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1589  if(status /= nf90_NoErr) call handle_err(status)
1590  ...
1591  status = nf90_inq_varid(ncid, "rh", rhVarId)
1592  if(status /= nf90_NoErr) call handle_err(status)
1593  ...
1594  ! Read transposed values: map vector would be (/ 1, numLats /) for
1595  ! no transposition
1596  status = nf90_get_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /))
1597  if(status /= nf90_NoErr) call handle_err(status)
1598 
1599 
1600 ~~~~
1601 
1602 
1603 The same effect can be obtained more simply, though using more memory,
1604 using Fortran 90 intrinsic functions:
1605 
1606 
1607 ~~~~.fortran
1608 
1609 
1610  use netcdf
1611  implicit none
1612  integer :: ncId, rhVarId, status
1613  integer, parameter :: numLons = 6, numLats = 4
1614  real, dimension(numLons, numLats) :: rhValues
1615  ! netCDF variable has dimensions (numLats, numLons)
1616  real, dimension(numLons, numLats) :: tempValues
1617  ...
1618  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1619  if(status /= nf90_NoErr) call handle_err(status)
1620  ...
1621  status = nf90_inq_varid(ncid, "rh", rhVarId)
1622  if(status /= nf90_NoErr) call handle_err(status)
1623  ...
1624  status = nf90_get_var(ncid, rhVarId, tempValues))
1625  if(status /= nf90_NoErr) call handle_err(status)
1626  rhValues(:, :) = transpose(tempValues)
1627 
1628 
1629 ~~~~
1630 
1631 
1632 
1633 
1634 6.12 Reading and Writing Character String Values {#f90-reading-and-writing-character-string-values}
1635 ===========
1636 
1637 Character strings are not a primitive netCDF external data type under
1638 the classic netCDF data model, in part because FORTRAN does not support
1639 the abstraction of variable-length character strings (the FORTRAN LEN
1640 function returns the static length of a character string, not its
1641 dynamic length). As a result, a character string cannot be written or
1642 read as a single object in the netCDF interface. Instead, a character
1643 string must be treated as an array of characters, and array access must
1644 be used to read and write character strings as variable data in netCDF
1645 datasets. Furthermore, variable-length strings are not supported by the
1646 netCDF classic interface except by convention; for example, you may
1647 treat a zero byte as terminating a character string, but you must
1648 explicitly specify the length of strings to be read from and written to
1649 netCDF variables.
1650 
1651 Character strings as attribute values are easier to use, since the
1652 strings are treated as a single unit for access. However, the value of a
1653 character-string attribute in the classic netCDF interface is still an
1654 array of characters with an explicit length that must be specified when
1655 the attribute is defined.
1656 
1657 When you define a variable that will have character-string values, use a
1658 character-position dimension as the most quickly varying dimension for
1659 the variable (the first dimension for the variable in Fortran 90). The
1660 length of the character-position dimension will be the maximum string
1661 length of any value to be stored in the character-string variable. Space
1662 for maximum-length strings will be allocated in the disk representation
1663 of character-string variables whether you use the space or not. If two
1664 or more variables have the same maximum length, the same
1665 character-position dimension may be used in defining the variable
1666 shapes.
1667 
1668 To write a character-string value into a character-string variable, use
1669 either entire variable access or array access. The latter requires that
1670 you specify both a corner and a vector of edge lengths. The
1671 character-position dimension at the corner should be one for Fortran 90.
1672 If the length of the string to be written is n, then the vector of edge
1673 lengths will specify n in the character-position dimension, and one for
1674 all the other dimensions: (n, 1, 1, ..., 1).
1675 
1676 In Fortran 90, fixed-length strings may be written to a netCDF dataset
1677 without a terminating character, to save space. Variable-length strings
1678 should follow the C convention of writing strings with a terminating
1679 zero byte so that the intended length of the string can be determined
1680 when it is later read by either C or Fortran 90 programs. It is the
1681 users responsibility to provide such null termination.
1682 
1683 If you are writing data in the default prefill mode (see next section),
1684 you can ensure that simple strings represented as 1-dimensional
1685 character arrays are null terminated in the netCDF file by writing fewer
1686 characters than the length declared when the variable was defined. That
1687 way, the extra unwritten characters will be filled with the default
1688 character fill value, which is a null byte. The Fortran intrinsic TRIM
1689 function can be used to trim trailing blanks from the character string
1690 argument to NF90\_PUT\_VAR to make the argument shorter than the
1691 declared length. If prefill is not on, the data writer must explicitly
1692 provide a null terminating byte.
1693 
1694 Here is an example illustrating this way of writing strings to character
1695 array variables:
1696 
1697 
1698 
1699 ~~~~.fortran
1700 
1701  use netcdf
1702  implicit none
1703  integer status
1704  integer :: ncid, oceanStrLenID, oceanId
1705  integer, parameter :: MaxOceanNameLen = 20
1706  character, (len = MaxOceanNameLen):: ocean
1707  ...
1708  status = nf90_create("foo.nc", nf90_NoClobber, ncid)
1709  if(status /= nf90_NoErr) call handle_err(status)
1710  ...
1711  status = nf90_def_dim(ncid, "oceanStrLen", MaxOceanNameLen, oceanStrLenId)
1712  if(status /= nf90_NoErr) call handle_err(status)
1713  ...
1714  status = nf90_def_var(ncid, "ocean", nf90_char, (/ oceanStrLenId /), oceanId)
1715  if(status /= nf90_NoErr) call handle_err(status)
1716  ...
1717  ! Leave define mode, which prefills netCDF variables with fill values
1718  status = nf90_enddef(ncid)
1719  if (status /= nf90_noerr) call handle_err(status)
1720  ...
1721  ! Note that this assignment adds blank fill
1722  ocean = "Pacific"
1723  ! Using trim removes trailing blanks, prefill provides null
1724  ! termination, so C programs can later get intended string.
1725  status = nf90_put_var(ncid, oceanId, trim(ocean))
1726  if(status /= nf90_NoErr) call handle_err(status)
1727 
1728 
1729 ~~~~
1730 
1731 
1732 6.13 Fill Values {#f90-fill-values}
1733 ===========
1734 
1735 What happens when you try to read a value that was never written in an
1736 open netCDF dataset? You might expect that this should always be an
1737 error, and that you should get an error message or an error status
1738 returned. You do get an error if you try to read data from a netCDF
1739 dataset that is not open for reading, if the variable ID is invalid for
1740 the specified netCDF dataset, or if the specified indices are not
1741 properly within the range defined by the dimension lengths of the
1742 specified variable. Otherwise, reading a value that was not written
1743 returns a special fill value used to fill in any undefined values when a
1744 netCDF variable is first written.
1745 
1746 You may ignore fill values and use the entire range of a netCDF external
1747 data type, but in this case you should make sure you write all data
1748 values before reading them. If you know you will be writing all the data
1749 before reading it, you can specify that no prefilling of variables with
1750 fill values will occur by calling writing. This may provide a
1751 significant performance gain for netCDF writes.
1752 
1753 The variable attribute \_FillValue may be used to specify the fill value
1754 for a variable. There are default fill values for each type, defined in
1755 module netcdf: NF90\_FILL\_CHAR, NF90\_FILL\_INT1 (same as
1756 NF90\_FILL\_BYTE), NF90\_FILL\_INT2 (same as NF90\_FILL\_SHORT),
1757 NF90\_FILL\_INT, NF90\_FILL\_REAL (same as NF90\_FILL\_FLOAT), and
1758 NF90\_FILL\_DOUBLE
1759 
1760 The netCDF byte and character types have different default fill values.
1761 The default fill value for characters is the zero byte, a useful value
1762 for detecting the end of variable-length C character strings. If you
1763 need a fill value for a byte variable, it is recommended that you
1764 explicitly define an appropriate \_FillValue attribute, as generic
1765 utilities such as ncdump will not assume a default fill value for byte
1766 variables.
1767 
1768 Type conversion for fill values is identical to type conversion for
1769 other values: attempting to convert a value from one type to another
1770 type that can’t represent the value results in a range error. Such
1771 errors may occur on writing or reading values from a larger type (such
1772 as double) to a smaller type (such as float), if the fill value for the
1773 larger type cannot be represented in the smaller type.
1774 
1775 
1776 6.14 NF90_RENAME_VAR {#f90-nf90_rename_var}
1777 ===========
1778 
1779 
1780 
1781 The function NF90\_RENAME\_VAR changes the name of a netCDF variable in
1782 an open netCDF dataset. If the new name is longer than the old name, the
1783 netCDF dataset must be in define mode. You cannot rename a variable to
1784 have the name of any existing variable.
1785 
1786 
1787 
1788 ## Usage
1789 
1790 
1791 
1792 ~~~~.fortran
1793 
1794  function nf90_rename_var(ncid, varid, newname)
1795  integer, intent( in) :: ncid, varid
1796  character (len = *), intent( in) :: newname
1797  integer :: nf90_rename_var
1798 
1799 ~~~~
1800 
1801 
1802 
1803 `ncid`
1804 
1805 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1806 
1807 `varid`
1808 
1809 : Variable ID.
1810 
1811 `newname`
1812 
1813 : New name for the specified variable.
1814 
1815 
1816 
1817 ## Errors
1818 
1819 NF90\_RENAME\_VAR returns the value NF90\_NOERR if no errors occurred.
1820 Otherwise, the returned status indicates an error. Possible causes of
1821 errors include:
1822 
1823 - The new name is in use as the name of another variable.
1824 - The variable ID is invalid for the specified netCDF dataset.
1825 - The specified netCDF ID does not refer to an open netCDF dataset.
1826 
1827 
1828 
1829 ## Example
1830 
1831 Here is an example using NF90\_RENAME\_VAR to rename the variable rh to
1832 rel\_hum in an existing netCDF dataset named foo.nc:
1833 
1834 
1835 ~~~~.fortran
1836 
1837 
1838  use netcdf
1839  implicit none
1840  integer :: ncId, rhVarId, status
1841  ...
1842  status = nf90_open("foo.nc", nf90_Write, ncid)
1843  if(status /= nf90_NoErr) call handle_err(status)
1844  ...
1845  status = nf90_inq_varid(ncid, "rh", rhVarId)
1846  if(status /= nf90_NoErr) call handle_err(status)
1847  status = nf90_redef(ncid) ! Enter define mode to change variable name
1848  if(status /= nf90_NoErr) call handle_err(status)
1849  status = nf90_rename_var(ncid, rhVarId, "rel_hum")
1850  if(status /= nf90_NoErr) call handle_err(status)
1851  status = nf90_enddef(ncid) ! Leave define mode
1852  if(status /= nf90_NoErr) call handle_err(status)
1853 
1854 
1855 
1856 ~~~~
1857 
1858 
1859 6.15 Change between Collective and Independent Parallel Access: NF90_VAR_PAR_ACCESS {#f90-change-between-collective-and-independent-parallel-access-nf90_var_par_access}
1860 ===========
1861 
1862 
1863 
1864 The function NF90\_VAR\_PAR\_ACCESS changes whether read/write
1865 operations on a parallel file system are performed collectively or
1866 independently (the default) on the variable. This function can only be
1867 called if the file was created (see [NF90\_CREATE](#NF90_005fCREATE)) or
1868 opened (see [NF90\_OPEN](#NF90_005fOPEN)) for parallel I/O.
1869 
1870 This function is only available if the netCDF library was built with
1871 parallel I/O enabled.
1872 
1873 Calling this function affects only the open file - information about
1874 whether a variable is to be accessed collectively or independently is
1875 not written to the data file. Every time you open a file on a parallel
1876 file system, all variables default to independent operations. The change
1877 of a variable to collective access lasts only as long as that file is
1878 open.
1879 
1880 The variable can be changed from collective to independent, and back, as
1881 often as desired.
1882 
1883 Classic and 64-bit offset files, when opened for parallel access, use
1884 the parallel-netcdf (a.k.a. pnetcdf) library, which does not allow
1885 per-variable changes of access mode - the entire file must be access
1886 independently or collectively. For classic and 64-bit offset files, the
1887 nf90\_var\_par\_access function changes the access for all variables in
1888 the file.
1889 
1890 
1891 
1892 ## Usage
1893 
1894 
1895 
1896 ~~~~.fortran
1897 
1898  function nf90_var_par_access(ncid, varid, access)
1899  integer, intent(in) :: ncid
1900  integer, intent(in) :: varid
1901  integer, intent(in) :: access
1902  integer :: nf90_var_par_access
1903  end function nf90_var_par_access
1904 
1905 ~~~~
1906 
1907 
1908 
1909 `ncid`
1910 
1911 : NetCDF ID, from a previous call to NF90\_OPEN (see
1912  [NF90\_OPEN](#NF90_005fOPEN)) or NF90\_CREATE (see
1913  [NF90\_CREATE](#NF90_005fCREATE)).
1914 
1915 `varid`
1916 
1917 : Variable ID.
1918 
1919 `access`
1920 
1921 : NF90\_INDEPENDENT to set this variable to independent operations.
1922  NF90\_COLLECTIVE to set it to collective operations.
1923 
1924 
1925 
1926 ## Return Values
1927 
1928 `NF90_NOERR`
1929 
1930 : No error.
1931 
1932 `NF90_ENOTVAR`
1933 
1934 : No variable found.
1935 
1936 `NF90_NOPAR`
1937 
1938 : File not opened for parallel access.
1939 
1940 
1941 
1942 ## Example
1943 
1944 This example comes from test program nf\_test/f90tst\_parallel.f90. For
1945 this test to be run, netCDF must have been built with a parallel-enabled
1946 HDF5, and –enable-parallel-tests must have been used when configuring
1947 netcdf.
1948 
1949 
1950 
1951 ~~~~.fortran
1952 
1953  ! Reopen the file.
1954  call handle_err(nf90_open(FILE_NAME, nf90_nowrite, ncid, comm = MPI_COMM_WORLD, &
1955  info = MPI_INFO_NULL))
1956 
1957  ! Set collective access on this variable. This will cause all
1958  ! reads/writes to happen together on every processor.
1959  call handle_err(nf90_var_par_access(ncid, varid, nf90_collective))
1960 
1961  ! Read this processor's data.
1962  call handle_err(nf90_get_var(ncid, varid, data_in, start = start, count = count))
1963 
1964 ~~~~

Return to the Main Unidata NetCDF page.
Generated on Thu Sep 19 2019 05:09:46 for NetCDF-Fortran. NetCDF is a Unidata library.