NetCDF-Fortran  4.4.4
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 Get Information about a Variable from Its ID: NF90_INQUIRE_VARIABLE {#f90-get-information-about-a-variable-from-its-id-nf90_inquire_variable}
513 ===========
514 
515 NF90\_INQUIRE\_VARIABLE returns information about a netCDF variable
516 given its ID. Information about a variable includes its name, type,
517 number of dimensions, a list of dimension IDs describing the shape of
518 the variable, and the number of variable attributes that have been
519 assigned to the variable.
520 
521 All parameters after nAtts are optional, and only supported if netCDF
522 was built with netCDF-4 features enabled, and if the variable is in a
523 netCDF-4/HDF5 file.
524 
525 
526 
527 ## Usage
528 
529 
530 ~~~~.fortran
531 
532 
533  function nf90_inquire_variable(ncid, varid, name, xtype, ndims, dimids, nAtts, &
534  contiguous, chunksizes, deflate_level, shuffle, fletcher32, endianness)
535  integer, intent(in) :: ncid, varid
536  character (len = *), optional, intent(out) :: name
537  integer, optional, intent(out) :: xtype, ndims
538  integer, dimension(:), optional, intent(out) :: dimids
539  integer, optional, intent(out) :: nAtts
540  logical, optional, intent(out) :: contiguous
541  integer, optional, dimension(:), intent(out) :: chunksizes
542  integer, optional, intent(out) :: deflate_level
543  logical, optional, intent(out) :: shuffle, fletcher32
544  integer, optional, intent(out) :: endianness
545  integer :: nf90_inquire_variable
546 
547 
548 
549 ~~~~
550 
551 `ncid`
552 
553 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
554 
555 `varid`
556 
557 : Variable ID.
558 
559 `name`
560 
561 : Returned variable name. The caller must allocate space for the
562  returned name. The maximum possible length, in characters, of a
563  variable name is given by the predefined constant NF90\_MAX\_NAME.
564 
565 `xtype`
566 
567 : Returned variable type, one of the set of predefined netCDF external
568  data types. The valid netCDF external data types are NF90\_BYTE,
569  NF90\_CHAR, NF90\_SHORT, NF90\_INT, NF90\_FLOAT, AND NF90\_DOUBLE.
570 
571 `ndims`
572 
573 : Returned number of dimensions the variable was defined as using. For
574  example, 2 indicates a matrix, 1 indicates a vector, and 0 means the
575  variable is a scalar with no dimensions.
576 
577 `dimids`
578 
579 : Returned vector of \*ndimsp dimension IDs corresponding to the
580  variable dimensions. The caller must allocate enough space for a
581  vector of at least \*ndimsp integers to be returned. The maximum
582  possible number of dimensions for a variable is given by the
583  predefined constant NF90\_MAX\_VAR\_DIMS.
584 
585 `natts`
586 
587 : Returned number of variable attributes assigned to this variable.
588 
589 `contiguous`
590 
591 : On return, set to NF90\_CONTIGUOUS if this variable uses contiguous
592  storage, NF90\_CHUNKED if it uses chunked storage.
593 
594 `chunksizes`
595 
596 : An array of chunk sizes. The array must have the one element for
597  each dimension in the variable.
598 
599 `shuffle`
600 
601 : True if the shuffle filter is turned on for this variable.
602 
603 `deflate_level`
604 
605 : The deflate\_level from 0 to 9. A value of zero indicates no
606  deflation is in use.
607 
608 `fletcher32`
609 
610 : Set to true if the fletcher32 checksum filter is turned on for
611  this variable.
612 
613 `endianness`
614 
615 : Will be set to NF90\_ENDIAN\_LITTLE if this variable is stored in
616  little-endian format, NF90\_ENDIAN\_BIG if it is stored in
617  big-endian format, and NF90\_ENDIAN\_NATIVE if the endianness is not
618  set, and the variable is not created yet.
619 
620 These functions return the value NF90\_NOERR if no errors occurred.
621 Otherwise, the returned status indicates an error. Possible causes of
622 errors include:
623 
624 - The variable ID is invalid for the specified netCDF dataset.
625 - The specified netCDF ID does not refer to an open netCDF dataset.
626 
627 
628 
629 ## Example
630 
631 Here is an example using NF90\_INQ\_VAR to find out about a variable
632 named rh in an existing netCDF dataset named foo.nc:
633 
634 
635 ~~~~.fortran
636 
637 
638  use netcdf
639  implicit none
640  integer :: status, ncid, &
641  RhVarId &
642  numDims, numAtts
643  integer, dimension(nf90_max_var_dims) :: rhDimIds
644  ...
645  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
646  if(status /= nf90_NoErr) call handle_error(status)
647  ...
648  status = nf90_inq_varid(ncid, "rh", RhVarId)
649  if(status /= nf90_NoErr) call handle_err(status)
650  status = nf90_inquire_variable(ncid, RhVarId, ndims = numDims, natts = numAtts)
651  if(status /= nf90_NoErr) call handle_err(status)
652  status = nf90_inquire_variable(ncid, RhVarId, dimids = rhDimIds(:numDims))
653  if(status /= nf90_NoErr) call handle_err(status)
654 
655 
656 ~~~~
657 
658 
659 6.7 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}
660 ===========
661 
662 
663 
664 Given the name of a variable, nf90\_inq\_varid finds the variable ID.
665 
666 
667 
668 ## Usage
669 
670 
671 ~~~~.fortran
672 
673 
674  function nf90_inq_varid(ncid, name, varid)
675  integer, intent(in) :: ncid
676  character (len = *), intent( in) :: name
677  integer, intent(out) :: varid
678  integer :: nf90_inq_varid
679 
680 
681 ~~~~
682 
683 
684 `ncid`
685 
686 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
687 
688 `name`
689 
690 : The variable name. The maximum possible length, in characters, of a
691  variable name is given by the predefined constant NF90\_MAX\_NAME.
692 
693 `varid`
694 
695 : Variable ID.
696 
697 These functions return the value NF90\_NOERR if no errors occurred.
698 Otherwise, the returned status indicates an error. Possible causes of
699 errors include:
700 
701 - Variable not found.
702 - The specified netCDF ID does not refer to an open netCDF dataset.
703 
704 
705 
706 ## Example
707 
708 Here is an example using NF90\_INQ\_VARID to find out about a variable
709 named rh in an existing netCDF dataset named foo.nc:
710 
711 
712 
713 ~~~~.fortran
714 
715  use netcdf
716  implicit none
717  integer :: status, ncid, &
718  RhVarId &
719  numDims, numAtts
720  integer, dimension(nf90_max_var_dims) :: rhDimIds
721  ...
722  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
723  if(status /= nf90_NoErr) call handle_error(status)
724  ...
725  status = nf90_inq_varid(ncid, "rh", RhVarId)
726  if(status /= nf90_NoErr) call handle_err(status)
727  status = nf90_inquire_variable(ncid, RhVarId, ndims = numDims, natts = numAtts)
728  if(status /= nf90_NoErr) call handle_err(status)
729  status = nf90_inquire_variable(ncid, RhVarId, dimids = rhDimIds(:numDims))
730  if(status /= nf90_NoErr) call handle_err(status)
731 
732 
733 
734 ~~~~
735 
736 
737 6.8 Writing Data Values: NF90_PUT_VAR {#f90-writing-data-values-nf90_put_var}
738 ===========
739 
740 
741 
742 The function NF90\_PUT\_VAR puts one or more data values into the
743 variable of an open netCDF dataset that is in data mode. Required inputs
744 are the netCDF ID, the variable ID, and one or more data values.
745 Optional inputs may indicate the starting position of the data values in
746 the netCDF variable (argument start), the sampling frequency with which
747 data values are written into the netCDF variable (argument stride), and
748 a mapping between the dimensions of the data array and the netCDF
749 variable (argument map). The values to be written are associated with
750 the netCDF variable by assuming that the first dimension of the netCDF
751 variable varies fastest in the Fortran 90 interface. Data values are
752 converted to the external type of the variable, if necessary.
753 
754 Take care when using the simplest forms of this interface with record
755 variables (variables that use the NF90\_UNLIMITED dimension) when you
756 don’t specify how many records are to be written. If you try to write
757 all the values of a record variable into a netCDF file that has no
758 record data yet (hence has 0 records), nothing will be written.
759 Similarly, if you try to write all the values of a record variable from
760 an array but there are more records in the file than you assume, more
761 in-memory data will be accessed than you expect, which may cause a
762 segmentation violation. To avoid such problems, it is better to specify
763 start and count arguments for variables that use the NF90\_UNLIMITED
764 dimension.
765 
766 
767 
768 ### Usage
769 
770 
771 
772 ~~~~.fortran
773 
774  function nf90_put_var(ncid, varid, values, start, count, stride, map)
775  integer, intent( in) :: ncid, varid
776  any valid type, scalar or array of any rank, &
777  intent( in) :: values
778  integer, dimension(:), optional, intent( in) :: start, count, stride, map
779  integer :: nf90_put_var
780 
781 
782 ~~~~
783 
784 
785 `ncid`
786 
787 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
788 
789 `varid`
790 
791 : Variable ID.
792 
793 `values`
794 
795 : The data value(s) to be written. The data may be of any type, and
796  may be a scalar or an array of any rank. You cannot put CHARACTER
797  data into a numeric variable or numeric data into a text variable.
798  For numeric data, if the type of data differs from the netCDF
799  variable type, type conversion will occur. See [Type
800  Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide.
801 
802 `start`
803 
804 : A vector of integers specifying the index in the variable where the
805  first (or only) of the data values will be written. The indices are
806  relative to 1, so for example, the first data value of a variable
807  would have index (1, 1, ..., 1). The elements of start correspond,
808  in order, to the variable’s dimensions. Hence, if the variable is a
809  record variable, the last index would correspond to the starting
810  record number for writing the data values.
811 
812  By default, start(:) = 1.
813 
814 `count`
815 
816 : A vector of integers specifying the number of indices selected along
817  each dimension. To write a single value, for example, specify count
818  as (1, 1, ..., 1). The elements of count correspond, in order, to
819  the variable’s dimensions. Hence, if the variable is a record
820  variable, the last element of count corresponds to a count of the
821  number of records to write.
822 
823  By default, count(:numDims) = shape(values) and count(numDims + 1:)
824  = 1, where numDims = size(shape(values)).
825 
826 `stride`
827 
828 : A vector of integers that specifies the sampling interval along each
829  dimension of the netCDF variable. The elements of the stride vector
830  correspond, in order, to the netCDF variable’s dimensions (stride(1)
831  gives the sampling interval along the most rapidly varying dimension
832  of the netCDF variable). Sampling intervals are specified in
833  type-independent units of elements (a value of 1 selects consecutive
834  elements of the netCDF variable along the corresponding dimension, a
835  value of 2 selects every other element, etc.).
836 
837  By default, stride(:) = 1.
838 
839 `imap`
840 
841 : A vector of integers that specifies the mapping between the
842  dimensions of a netCDF variable and the in-memory structure of the
843  internal data array. The elements of the index mapping vector
844  correspond, in order, to the netCDF variable’s dimensions (map(1)
845  gives the distance between elements of the internal array
846  corresponding to the most rapidly varying dimension of the
847  netCDF variable). Distances between elements are specified in units
848  of elements.
849 
850  By default, edgeLengths = shape(values), and map = (/ 1,
851  (product(edgeLengths(:i)), i = 1, size(edgeLengths) - 1) /), that
852  is, there is no mapping.
853 
854  Use of Fortran 90 intrinsic functions (including reshape, transpose,
855  and spread) may let you avoid using this argument.
856 
857 
858 
859 ## Errors
860 
861 NF90\_PUT\_VAR1\_ type returns the value NF90\_NOERR if no errors
862 occurred. Otherwise, the returned status indicates an error. Possible
863 causes of errors include:
864 
865 - The variable ID is invalid for the specified netCDF dataset.
866 - The specified indices were out of range for the rank of the
867  specified variable. For example, a negative index or an index that
868  is larger than the corresponding dimension length will cause
869  an error.
870 - The specified value is out of the range of values representable by
871  the external data type of the variable.
872 - The specified netCDF is in define mode rather than data mode.
873 - The specified netCDF ID does not refer to an open netCDF dataset.
874 
875 
876 
877 ## Example
878 
879 Here is an example using NF90\_PUT\_VAR to set the (4,3,2) element of
880 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
881 For simplicity in this example, we assume that we know that rh is
882 dimensioned with lon, lat, and time, so we want to set the value of rh
883 that corresponds to the fourth lon value, the third lat value, and the
884 second time value:
885 
886 
887 
888 ~~~~.fortran
889 
890  use netcdf
891  implicit none
892  integer :: ncId, rhVarId, status
893  ...
894  status = nf90_open("foo.nc", nf90_Write, ncid)
895  if(status /= nf90_NoErr) call handle_err(status)
896  ...
897  status = nf90_inq_varid(ncid, "rh", rhVarId)
898  if(status /= nf90_NoErr) call handle_err(status)
899  status = nf90_put_var(ncid, rhVarId, 0.5, start = (/ 4, 3, 2 /) )
900  if(status /= nf90_NoErr) call handle_err(status)
901 
902 
903 ~~~~
904 
905 
906 In this example we use NF90\_PUT\_VAR to add or change all the values of
907 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
908 We assume that we know that rh is dimensioned with lon, lat, and time.
909 In this example we query the netCDF file to discover the lengths of the
910 dimensions, then use the Fortran 90 intrinsic function reshape to create
911 a temporary array of data values which is the same shape as the netCDF
912 variable.
913 
914 
915 ~~~~.fortran
916 
917 
918  use netcdf
919  implicit none
920  integer :: ncId, rhVarId,status, &
921  lonDimID, latDimId, timeDimId, &
922  numLons, numLats, numTimes, &
923  i
924  integer, dimension(nf90_max_var_dims) :: dimIDs
925  ...
926  status = nf90_open("foo.nc", nf90_Write, ncid)
927  if(status /= nf90_NoErr) call handle_err(status)
928  ...
929  status = nf90_inq_varid(ncid, "rh", rhVarId)
930  if(status /= nf90_NoErr) call handle_err(status)
931  ! How big is the netCDF variable, that is, what are the lengths of
932  ! its constituent dimensions?
933  status = nf90_inquire_variable(ncid, rhVarId, dimids = dimIDs)
934  if(status /= nf90_NoErr) call handle_err(status)
935  status = nf90_inquire_dimension(ncid, dimIDs(1), len = numLons)
936  if(status /= nf90_NoErr) call handle_err(status)
937  status = nf90_inquire_dimension(ncid, dimIDs(2), len = numLats)
938  if(status /= nf90_NoErr) call handle_err(status)
939  status = nf90_inquire_dimension(ncid, dimIDs(3), len = numTimes)
940  if(status /= nf90_NoErr) call handle_err(status)
941  ...
942  ! Make a temporary array the same shape as the netCDF variable.
943  status = nf90_put_var(ncid, rhVarId, &
944  reshape( &
945  (/ (0.5, i = 1, numLons * numLats * numTimes) /) , &
946  shape = (/ numLons, numLats, numTimes /) )
947  if(status /= nf90_NoErr) call handle_err(status)
948 
949 
950 ~~~~
951 
952 
953 Here is an example using NF90\_PUT\_VAR to add or change a section of
954 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
955 For simplicity in this example, we assume that we know that rh is
956 dimensioned with lon, lat, and time, that there are ten lon values, five
957 lat values, and three time values, and that we want to replace all the
958 values at the last time.
959 
960 
961 
962 ~~~~.fortran
963 
964  use netcdf
965  implicit none
966  integer :: ncId, rhVarId, status
967  integer, parameter :: numLons = 10, numLats = 5, numTimes = 3
968  real, dimension(numLons, numLats) &
969  :: rhValues
970  ...
971  status = nf90_open("foo.nc", nf90_Write, ncid)
972  if(status /= nf90_NoErr) call handle_err(status)
973  ...
974  status = nf90_inq_varid(ncid, "rh", rhVarId)
975  if(status /= nf90_NoErr) call handle_err(status)
976  ! Fill in all values at the last time
977  rhValues(:, :) = 0.5
978  status = nf90_put_var(ncid, rhVarId,rhvalues, &
979  start = (/ 1, 1, numTimes /), &
980  count = (/ numLats, numLons, 1 /))
981  if(status /= nf90_NoErr) call handle_err(status)
982 
983 
984 ~~~~
985 
986 
987 Here is an example of using NF90\_PUT\_VAR to write every other point of
988 a netCDF variable named rh having dimensions (6, 4).
989 
990 
991 
992 ~~~~.fortran
993 
994  use netcdf
995  implicit none
996  integer :: ncId, rhVarId, status
997  integer, parameter :: numLons = 6, numLats = 4
998  real, dimension(numLons, numLats) &
999  :: rhValues = 0.5
1000  ...
1001  status = nf90_open("foo.nc", nf90_Write, ncid)
1002  if(status /= nf90_NoErr) call handle_err(status)
1003  ...
1004  status = nf90_inq_varid(ncid, "rh", rhVarId)
1005  if(status /= nf90_NoErr) call handle_err(status)
1006  ...
1007  ! Fill in every other value using an array section
1008  status = nf90_put_var(ncid, rhVarId, rhValues(::2, ::2), &
1009  stride = (/ 2, 2 /))
1010  if(status /= nf90_NoErr) call handle_err(status)
1011 
1012 
1013 ~~~~
1014 
1015 
1016 The following map vector shows the default mapping between a 2x3x4
1017 netCDF variable and an internal array of the same shape:
1018 
1019 
1020 ~~~~.fortran
1021 
1022 
1023  real, dimension(2, 3, 4):: a ! same shape as netCDF variable
1024  integer, dimension(3) :: map = (/ 1, 2, 6 /)
1025  ! netCDF dimension inter-element distance
1026  ! ---------------- ----------------------
1027  ! most rapidly varying 1
1028  ! intermediate 2 (= map(1)*2)
1029  ! most slowly varying 6 (= map(2)*3)
1030 
1031 
1032 ~~~~
1033 
1034 
1035 Using the map vector above obtains the same result as simply not passing
1036 a map vector at all.
1037 
1038 Here is an example of using nf90\_put\_var to write a netCDF variable
1039 named rh whose dimensions are the transpose of the Fortran 90 array:
1040 
1041 
1042 ~~~~.fortran
1043 
1044 
1045  use netcdf
1046  implicit none
1047  integer :: ncId, rhVarId, status
1048  integer, parameter :: numLons = 6, numLats = 4
1049  real, dimension(numLons, numLats) :: rhValues
1050  ! netCDF variable has dimensions (numLats, numLons)
1051  ...
1052  status = nf90_open("foo.nc", nf90_Write, ncid)
1053  if(status /= nf90_NoErr) call handle_err(status)
1054  ...
1055  status = nf90_inq_varid(ncid, "rh", rhVarId)
1056  if(status /= nf90_NoErr) call handle_err(status)
1057  ...
1058  !Write transposed values: map vector would be (/ 1, numLats /) for
1059  ! no transposition
1060  status = nf90_put_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /))
1061  if(status /= nf90_NoErr) call handle_err(status)
1062 
1063 
1064 ~~~~
1065 
1066 
1067 The same effect can be obtained more simply using Fortran 90 intrinsic
1068 functions:
1069 
1070 
1071 
1072 ~~~~.fortran
1073 
1074  use netcdf
1075  implicit none
1076  integer :: ncId, rhVarId, status
1077  integer, parameter :: numLons = 6, numLats = 4
1078  real, dimension(numLons, numLats) :: rhValues
1079  ! netCDF variable has dimensions (numLats, numLons)
1080  ...
1081  status = nf90_open("foo.nc", nf90_Write, ncid)
1082  if(status /= nf90_NoErr) call handle_err(status)
1083  ...
1084  status = nf90_inq_varid(ncid, "rh", rhVarId)
1085  if(status /= nf90_NoErr) call handle_err(status)
1086  ...
1087  status = nf90_put_var(ncid, rhVarId, transpose(rhValues))
1088  if(status /= nf90_NoErr) call handle_err(status)
1089 
1090 
1091 ~~~~
1092 
1093 
1094 
1095 6.9 Reading Data Values: NF90_GET_VAR {#f90-reading-data-values-nf90_get_var}
1096 ===========
1097 
1098 
1099 
1100 The function NF90\_GET\_VAR gets one or more data values from a netCDF
1101 variable of an open netCDF dataset that is in data mode. Required inputs
1102 are the netCDF ID, the variable ID, and a specification for the data
1103 values into which the data will be read. Optional inputs may indicate
1104 the starting position of the data values in the netCDF variable
1105 (argument start), the sampling frequency with which data values are read
1106 from the netCDF variable (argument stride), and a mapping between the
1107 dimensions of the data array and the netCDF variable (argument map). The
1108 values to be read are associated with the netCDF variable by assuming
1109 that the first dimension of the netCDF variable varies fastest in the
1110 Fortran 90 interface. Data values are converted from the external type
1111 of the variable, if necessary.
1112 
1113 Take care when using the simplest forms of this interface with record
1114 variables (variables that use the NF90\_UNLIMITED dimension) when you
1115 don’t specify how many records are to be read. If you try to read all
1116 the values of a record variable into an array but there are more records
1117 in the file than you assume, more data will be read than you expect,
1118 which may cause a segmentation violation. To avoid such problems, it is
1119 better to specify the optional start and count arguments for variables
1120 that use the NF90\_UNLIMITED dimension.
1121 
1122 In netCDF classic model the maximum integer size is NF90\_INT, the
1123 4-byte signed integer. Reading variables into an eight-byte integer
1124 array from a classic model file will read from an NF90\_INT. Reading
1125 variables into an eight-byte integer in a netCDF-4/HDF5 (without classic
1126 model flag) will read from an NF90\_INT64
1127 
1128 
1129 
1130 ## Usage
1131 
1132 
1133 
1134 ~~~~.fortran
1135 
1136  function nf90_get_var(ncid, varid, values, start, count, stride, map)
1137  integer, intent( in) :: ncid, varid
1138  any valid type, scalar or array of any rank, &
1139  intent(out) :: values
1140  integer, dimension(:), optional, intent( in) :: start, count, stride, map
1141  integer :: nf90_get_var
1142 
1143 
1144 ~~~~
1145 
1146 
1147 `ncid`
1148 
1149 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1150 
1151 `varid`
1152 
1153 : Variable ID.
1154 
1155 `values`
1156 
1157 : The data value(s) to be read. The data may be of any type, and may
1158  be a scalar or an array of any rank. You cannot read CHARACTER data
1159  from a numeric variable or numeric data from a text variable. For
1160  numeric data, if the type of data differs from the netCDF variable
1161  type, type conversion will occur. See [Type
1162  Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide.
1163 
1164 `start`
1165 
1166 : A vector of integers specifying the index in the variable from which
1167  the first (or only) of the data values will be read. The indices are
1168  relative to 1, so for example, the first data value of a variable
1169  would have index (1, 1, ..., 1). The elements of start correspond,
1170  in order, to the variable’s dimensions. Hence, if the variable is a
1171  record variable, the last index would correspond to the starting
1172  record number for writing the data values.
1173 
1174  By default, start(:) = 1.
1175 
1176 `count`
1177 
1178 : A vector of integers specifying the number of indices selected along
1179  each dimension. To read a single value, for example, specify count
1180  as (1, 1, ..., 1). The elements of count correspond, in order, to
1181  the variable’s dimensions. Hence, if the variable is a record
1182  variable, the last element of count corresponds to a count of the
1183  number of records to read.
1184 
1185  By default, count(:numDims) = shape(values) and count(numDims + 1:)
1186  = 1, where numDims = size(shape(values)).
1187 
1188 `stride`
1189 
1190 : A vector of integers that specifies the sampling interval along each
1191  dimension of the netCDF variable. The elements of the stride vector
1192  correspond, in order, to the netCDF variable’s dimensions (stride(1)
1193  gives the sampling interval along the most rapidly varying dimension
1194  of the netCDF variable). Sampling intervals are specified in
1195  type-independent units of elements (a value of 1 selects consecutive
1196  elements of the netCDF variable along the corresponding dimension, a
1197  value of 2 selects every other element, etc.).
1198 
1199  By default, stride(:) = 1.
1200 
1201 `map`
1202 
1203 : A vector of integers that specifies the mapping between the
1204  dimensions of a netCDF variable and the in-memory structure of the
1205  internal data array. The elements of the index mapping vector
1206  correspond, in order, to the netCDF variable’s dimensions (map(1)
1207  gives the distance between elements of the internal array
1208  corresponding to the most rapidly varying dimension of the
1209  netCDF variable). Distances between elements are specified in units
1210  of elements.
1211 
1212  By default, edgeLengths = shape(values), and map = (/ 1,
1213  (product(edgeLengths(:i)), i = 1, size(edgeLengths) - 1) /), that
1214  is, there is no mapping.
1215 
1216  Use of Fortran 90 intrinsic functions (including reshape, transpose,
1217  and spread) may let you avoid using this argument.
1218 
1219 
1220 
1221 ## Errors
1222 
1223 NF90\_GET\_VAR returns the value NF90\_NOERR if no errors occurred.
1224 Otherwise, the returned status indicates an error. Possible causes of
1225 errors include:
1226 
1227 - The variable ID is invalid for the specified netCDF dataset.
1228 - The assumed or specified start, count, and stride generate an index
1229  which is out of range. Note that no error checking is possible on
1230  the map vector.
1231 - One or more of the specified values are out of the range of values
1232  representable by the desired type.
1233 - The specified netCDF is in define mode rather than data mode.
1234 - The specified netCDF ID does not refer to an open netCDF dataset.
1235 
1236 (As noted above, another possible source of error is using this
1237 interface to read all the values of a record variable without specifying
1238 the number of records. If there are more records in the file than you
1239 assume, more data will be read than you expect!)
1240 
1241 
1242 
1243 ## Example
1244 
1245 Here is an example using NF90\_GET\_VAR to read the (4,3,2) element of
1246 the variable named rh from an existing netCDF dataset named foo.nc. For
1247 simplicity in this example, we assume that we know that rh is
1248 dimensioned with lon, lat, and time, so we want to read the value of rh
1249 that corresponds to the fourth lon value, the third lat value, and the
1250 second time value:
1251 
1252 
1253 
1254 ~~~~.fortran
1255 
1256  use netcdf
1257  implicit none
1258  integer :: ncId, rhVarId, status
1259  real :: rhValue
1260  ...
1261  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1262  if(status /= nf90_NoErr) call handle_err(status)
1263  -
1264  status = nf90_inq_varid(ncid, "rh", rhVarId)
1265  if(status /= nf90_NoErr) call handle_err(status)
1266  status = nf90_get_var(ncid, rhVarId, rhValue, start = (/ 4, 3, 2 /) )
1267  if(status /= nf90_NoErr) call handle_err(status)
1268 
1269 
1270 ~~~~
1271 
1272 
1273 In this example we use NF90\_GET\_VAR to read all the values of the
1274 variable named rh from an existing netCDF dataset named foo.nc. We
1275 assume that we know that rh is dimensioned with lon, lat, and time. In
1276 this example we query the netCDF file to discover the lengths of the
1277 dimensions, then allocate a Fortran 90 array the same shape as the
1278 netCDF variable.
1279 
1280 
1281 
1282 
1283  use netcdf
1284  implicit none
1285  integer :: ncId, rhVarId, &
1286  lonDimID, latDimId, timeDimId, &
1287  numLons, numLats, numTimes, &
1288  status
1289  integer, dimension(nf90_max_var_dims) :: dimIDs
1290  real, dimension(:, :, :), allocatable :: rhValues
1291  ...
1292  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1293  if(status /= nf90_NoErr) call handle_err(status)
1294  ...
1295  status = nf90_inq_varid(ncid, "rh", rhVarId)
1296  if(status /= nf90_NoErr) call handle_err(status)
1297  ! How big is the netCDF variable, that is, what are the lengths of
1298  ! its constituent dimensions?
1299  status = nf90_inquire_variable(ncid, rhVarId, dimids = dimIDs)
1300  if(status /= nf90_NoErr) call handle_err(status)
1301  status = nf90_inquire_dimension(ncid, dimIDs(1), len = numLons)
1302  if(status /= nf90_NoErr) call handle_err(status)
1303  status = nf90_inquire_dimension(ncid, dimIDs(2), len = numLats)
1304  if(status /= nf90_NoErr) call handle_err(status)
1305  status = nf90_inquire_dimension(ncid, dimIDs(3), len = numTimes)
1306  if(status /= nf90_NoErr) call handle_err(status)
1307  allocate(rhValues(numLons, numLats, numTimes))
1308  ...
1309  status = nf90_get_var(ncid, rhVarId, rhValues)
1310  if(status /= nf90_NoErr) call handle_err(status)
1311 
1312 
1313 
1314 
1315 Here is an example using NF90\_GET\_VAR to read a section of the
1316 variable named rh from an existing netCDF dataset named foo.nc. For
1317 simplicity in this example, we assume that we know that rh is
1318 dimensioned with lon, lat, and time, that there are ten lon values, five
1319 lat values, and three time values, and that we want to replace all the
1320 values at the last time.
1321 
1322 
1323 ~~~~.fortran
1324 
1325 
1326  use netcdf
1327  implicit none
1328  integer :: ncId, rhVarId, status
1329  integer, parameter :: numLons = 10, numLats = 5, numTimes = 3
1330  real, dimension(numLons, numLats, numTimes) &
1331  :: rhValues
1332  ...
1333  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1334  if(status /= nf90_NoErr) call handle_err(status)
1335  ...
1336  status = nf90_inq_varid(ncid, "rh", rhVarId)
1337  if(status /= nf90_NoErr) call handle_err(status)
1338  !Read the values at the last time by passing an array section
1339  status = nf90_get_var(ncid, rhVarId, rhValues(:, :, 3), &
1340  start = (/ 1, 1, numTimes /), &
1341  count = (/ numLons, numLats, 1 /))
1342  if(status /= nf90_NoErr) call handle_err(status)
1343 
1344 
1345 ~~~~
1346 
1347 
1348 Here is an example of using NF90\_GET\_VAR to read every other point of
1349 a netCDF variable named rh having dimensions (6, 4).
1350 
1351 
1352 ~~~~.fortran
1353 
1354 
1355  use netcdf
1356  implicit none
1357  integer :: ncId, rhVarId, status
1358  integer, parameter :: numLons = 6, numLats = 4
1359  real, dimension(numLons, numLats) &
1360  :: rhValues
1361  ...
1362  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1363  if(status /= nf90_NoErr) call handle_err(status)
1364  ...
1365  status = nf90_inq_varid(ncid, "rh", rhVarId)
1366  if(status /= nf90_NoErr) call handle_err(status)
1367  ...
1368  ! Read every other value into an array section
1369  status = nf90_get_var(ncid, rhVarId, rhValues(::2, ::2) &
1370  stride = (/ 2, 2 /))
1371  if(status /= nf90_NoErr) call handle_err(status)
1372 
1373 
1374 
1375 ~~~~
1376 
1377 The following map vector shows the default mapping between a 2x3x4
1378 netCDF variable and an internal array of the same shape:
1379 
1380 
1381 ~~~~.fortran
1382 
1383 
1384  real, dimension(2, 3, 4):: a ! same shape as netCDF variable
1385  integer, dimension(3) :: map = (/ 1, 2, 6 /)
1386  ! netCDF dimension inter-element distance
1387  ! ---------------- ----------------------
1388  ! most rapidly varying 1
1389  ! intermediate 2 (= map(1)*2)
1390  ! most slowly varying 6 (= map(2)*3)
1391 
1392 
1393 
1394 
1395 ~~~~
1396 
1397 Using the map vector above obtains the same result as simply not passing
1398 a map vector at all.
1399 
1400 Here is an example of using nf90\_get\_var to read a netCDF variable
1401 named rh whose dimensions are the transpose of the Fortran 90 array:
1402 
1403 
1404 
1405 ~~~~.fortran
1406 
1407  use netcdf
1408  implicit none
1409  integer :: ncId, rhVarId, status
1410  integer, parameter :: numLons = 6, numLats = 4
1411  real, dimension(numLons, numLats) :: rhValues
1412  ! netCDF variable has dimensions (numLats, numLons)
1413  ...
1414  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1415  if(status /= nf90_NoErr) call handle_err(status)
1416  ...
1417  status = nf90_inq_varid(ncid, "rh", rhVarId)
1418  if(status /= nf90_NoErr) call handle_err(status)
1419  ...
1420  ! Read transposed values: map vector would be (/ 1, numLats /) for
1421  ! no transposition
1422  status = nf90_get_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /))
1423  if(status /= nf90_NoErr) call handle_err(status)
1424 
1425 
1426 ~~~~
1427 
1428 
1429 The same effect can be obtained more simply, though using more memory,
1430 using Fortran 90 intrinsic functions:
1431 
1432 
1433 ~~~~.fortran
1434 
1435 
1436  use netcdf
1437  implicit none
1438  integer :: ncId, rhVarId, status
1439  integer, parameter :: numLons = 6, numLats = 4
1440  real, dimension(numLons, numLats) :: rhValues
1441  ! netCDF variable has dimensions (numLats, numLons)
1442  real, dimension(numLons, numLats) :: tempValues
1443  ...
1444  status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1445  if(status /= nf90_NoErr) call handle_err(status)
1446  ...
1447  status = nf90_inq_varid(ncid, "rh", rhVarId)
1448  if(status /= nf90_NoErr) call handle_err(status)
1449  ...
1450  status = nf90_get_var(ncid, rhVarId, tempValues))
1451  if(status /= nf90_NoErr) call handle_err(status)
1452  rhValues(:, :) = transpose(tempValues)
1453 
1454 
1455 ~~~~
1456 
1457 
1458 
1459 
1460 6.10 Reading and Writing Character String Values {#f90-reading-and-writing-character-string-values}
1461 ===========
1462 
1463 Character strings are not a primitive netCDF external data type under
1464 the classic netCDF data model, in part because FORTRAN does not support
1465 the abstraction of variable-length character strings (the FORTRAN LEN
1466 function returns the static length of a character string, not its
1467 dynamic length). As a result, a character string cannot be written or
1468 read as a single object in the netCDF interface. Instead, a character
1469 string must be treated as an array of characters, and array access must
1470 be used to read and write character strings as variable data in netCDF
1471 datasets. Furthermore, variable-length strings are not supported by the
1472 netCDF classic interface except by convention; for example, you may
1473 treat a zero byte as terminating a character string, but you must
1474 explicitly specify the length of strings to be read from and written to
1475 netCDF variables.
1476 
1477 Character strings as attribute values are easier to use, since the
1478 strings are treated as a single unit for access. However, the value of a
1479 character-string attribute in the classic netCDF interface is still an
1480 array of characters with an explicit length that must be specified when
1481 the attribute is defined.
1482 
1483 When you define a variable that will have character-string values, use a
1484 character-position dimension as the most quickly varying dimension for
1485 the variable (the first dimension for the variable in Fortran 90). The
1486 length of the character-position dimension will be the maximum string
1487 length of any value to be stored in the character-string variable. Space
1488 for maximum-length strings will be allocated in the disk representation
1489 of character-string variables whether you use the space or not. If two
1490 or more variables have the same maximum length, the same
1491 character-position dimension may be used in defining the variable
1492 shapes.
1493 
1494 To write a character-string value into a character-string variable, use
1495 either entire variable access or array access. The latter requires that
1496 you specify both a corner and a vector of edge lengths. The
1497 character-position dimension at the corner should be one for Fortran 90.
1498 If the length of the string to be written is n, then the vector of edge
1499 lengths will specify n in the character-position dimension, and one for
1500 all the other dimensions: (n, 1, 1, ..., 1).
1501 
1502 In Fortran 90, fixed-length strings may be written to a netCDF dataset
1503 without a terminating character, to save space. Variable-length strings
1504 should follow the C convention of writing strings with a terminating
1505 zero byte so that the intended length of the string can be determined
1506 when it is later read by either C or Fortran 90 programs. It is the
1507 users responsibility to provide such null termination.
1508 
1509 If you are writing data in the default prefill mode (see next section),
1510 you can ensure that simple strings represented as 1-dimensional
1511 character arrays are null terminated in the netCDF file by writing fewer
1512 characters than the length declared when the variable was defined. That
1513 way, the extra unwritten characters will be filled with the default
1514 character fill value, which is a null byte. The Fortran intrinsic TRIM
1515 function can be used to trim trailing blanks from the character string
1516 argument to NF90\_PUT\_VAR to make the argument shorter than the
1517 declared length. If prefill is not on, the data writer must explicitly
1518 provide a null terminating byte.
1519 
1520 Here is an example illustrating this way of writing strings to character
1521 array variables:
1522 
1523 
1524 
1525 ~~~~.fortran
1526 
1527  use netcdf
1528  implicit none
1529  integer status
1530  integer :: ncid, oceanStrLenID, oceanId
1531  integer, parameter :: MaxOceanNameLen = 20
1532  character, (len = MaxOceanNameLen):: ocean
1533  ...
1534  status = nf90_create("foo.nc", nf90_NoClobber, ncid)
1535  if(status /= nf90_NoErr) call handle_err(status)
1536  ...
1537  status = nf90_def_dim(ncid, "oceanStrLen", MaxOceanNameLen, oceanStrLenId)
1538  if(status /= nf90_NoErr) call handle_err(status)
1539  ...
1540  status = nf90_def_var(ncid, "ocean", nf90_char, (/ oceanStrLenId /), oceanId)
1541  if(status /= nf90_NoErr) call handle_err(status)
1542  ...
1543  ! Leave define mode, which prefills netCDF variables with fill values
1544  status = nf90_enddef(ncid)
1545  if (status /= nf90_noerr) call handle_err(status)
1546  ...
1547  ! Note that this assignment adds blank fill
1548  ocean = "Pacific"
1549  ! Using trim removes trailing blanks, prefill provides null
1550  ! termination, so C programs can later get intended string.
1551  status = nf90_put_var(ncid, oceanId, trim(ocean))
1552  if(status /= nf90_NoErr) call handle_err(status)
1553 
1554 
1555 ~~~~
1556 
1557 
1558 6.11 Fill Values {#f90-fill-values}
1559 ===========
1560 
1561 What happens when you try to read a value that was never written in an
1562 open netCDF dataset? You might expect that this should always be an
1563 error, and that you should get an error message or an error status
1564 returned. You do get an error if you try to read data from a netCDF
1565 dataset that is not open for reading, if the variable ID is invalid for
1566 the specified netCDF dataset, or if the specified indices are not
1567 properly within the range defined by the dimension lengths of the
1568 specified variable. Otherwise, reading a value that was not written
1569 returns a special fill value used to fill in any undefined values when a
1570 netCDF variable is first written.
1571 
1572 You may ignore fill values and use the entire range of a netCDF external
1573 data type, but in this case you should make sure you write all data
1574 values before reading them. If you know you will be writing all the data
1575 before reading it, you can specify that no prefilling of variables with
1576 fill values will occur by calling writing. This may provide a
1577 significant performance gain for netCDF writes.
1578 
1579 The variable attribute \_FillValue may be used to specify the fill value
1580 for a variable. There are default fill values for each type, defined in
1581 module netcdf: NF90\_FILL\_CHAR, NF90\_FILL\_INT1 (same as
1582 NF90\_FILL\_BYTE), NF90\_FILL\_INT2 (same as NF90\_FILL\_SHORT),
1583 NF90\_FILL\_INT, NF90\_FILL\_REAL (same as NF90\_FILL\_FLOAT), and
1584 NF90\_FILL\_DOUBLE
1585 
1586 The netCDF byte and character types have different default fill values.
1587 The default fill value for characters is the zero byte, a useful value
1588 for detecting the end of variable-length C character strings. If you
1589 need a fill value for a byte variable, it is recommended that you
1590 explicitly define an appropriate \_FillValue attribute, as generic
1591 utilities such as ncdump will not assume a default fill value for byte
1592 variables.
1593 
1594 Type conversion for fill values is identical to type conversion for
1595 other values: attempting to convert a value from one type to another
1596 type that can’t represent the value results in a range error. Such
1597 errors may occur on writing or reading values from a larger type (such
1598 as double) to a smaller type (such as float), if the fill value for the
1599 larger type cannot be represented in the smaller type.
1600 
1601 
1602 6.12 NF90_RENAME_VAR {#f90-nf90_rename_var}
1603 ===========
1604 
1605 
1606 
1607 The function NF90\_RENAME\_VAR changes the name of a netCDF variable in
1608 an open netCDF dataset. If the new name is longer than the old name, the
1609 netCDF dataset must be in define mode. You cannot rename a variable to
1610 have the name of any existing variable.
1611 
1612 
1613 
1614 ## Usage
1615 
1616 
1617 
1618 ~~~~.fortran
1619 
1620  function nf90_rename_var(ncid, varid, newname)
1621  integer, intent( in) :: ncid, varid
1622  character (len = *), intent( in) :: newname
1623  integer :: nf90_rename_var
1624 
1625 ~~~~
1626 
1627 
1628 
1629 `ncid`
1630 
1631 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1632 
1633 `varid`
1634 
1635 : Variable ID.
1636 
1637 `newname`
1638 
1639 : New name for the specified variable.
1640 
1641 
1642 
1643 ## Errors
1644 
1645 NF90\_RENAME\_VAR returns the value NF90\_NOERR if no errors occurred.
1646 Otherwise, the returned status indicates an error. Possible causes of
1647 errors include:
1648 
1649 - The new name is in use as the name of another variable.
1650 - The variable ID is invalid for the specified netCDF dataset.
1651 - The specified netCDF ID does not refer to an open netCDF dataset.
1652 
1653 
1654 
1655 ## Example
1656 
1657 Here is an example using NF90\_RENAME\_VAR to rename the variable rh to
1658 rel\_hum in an existing netCDF dataset named foo.nc:
1659 
1660 
1661 ~~~~.fortran
1662 
1663 
1664  use netcdf
1665  implicit none
1666  integer :: ncId, rhVarId, status
1667  ...
1668  status = nf90_open("foo.nc", nf90_Write, ncid)
1669  if(status /= nf90_NoErr) call handle_err(status)
1670  ...
1671  status = nf90_inq_varid(ncid, "rh", rhVarId)
1672  if(status /= nf90_NoErr) call handle_err(status)
1673  status = nf90_redef(ncid) ! Enter define mode to change variable name
1674  if(status /= nf90_NoErr) call handle_err(status)
1675  status = nf90_rename_var(ncid, rhVarId, "rel_hum")
1676  if(status /= nf90_NoErr) call handle_err(status)
1677  status = nf90_enddef(ncid) ! Leave define mode
1678  if(status /= nf90_NoErr) call handle_err(status)
1679 
1680 
1681 
1682 ~~~~
1683 
1684 
1685 6.13 Change between Collective and Independent Parallel Access: NF90_VAR_PAR_ACCESS {#f90-change-between-collective-and-independent-parallel-access-nf90_var_par_access}
1686 ===========
1687 
1688 
1689 
1690 The function NF90\_VAR\_PAR\_ACCESS changes whether read/write
1691 operations on a parallel file system are performed collectively or
1692 independently (the default) on the variable. This function can only be
1693 called if the file was created (see [NF90\_CREATE](#NF90_005fCREATE)) or
1694 opened (see [NF90\_OPEN](#NF90_005fOPEN)) for parallel I/O.
1695 
1696 This function is only available if the netCDF library was built with
1697 parallel I/O enabled.
1698 
1699 Calling this function affects only the open file - information about
1700 whether a variable is to be accessed collectively or independently is
1701 not written to the data file. Every time you open a file on a parallel
1702 file system, all variables default to independent operations. The change
1703 of a variable to collective access lasts only as long as that file is
1704 open.
1705 
1706 The variable can be changed from collective to independent, and back, as
1707 often as desired.
1708 
1709 Classic and 64-bit offset files, when opened for parallel access, use
1710 the parallel-netcdf (a.k.a. pnetcdf) library, which does not allow
1711 per-variable changes of access mode - the entire file must be access
1712 independently or collectively. For classic and 64-bit offset files, the
1713 nf90\_var\_par\_access function changes the access for all variables in
1714 the file.
1715 
1716 
1717 
1718 ## Usage
1719 
1720 
1721 
1722 ~~~~.fortran
1723 
1724  function nf90_var_par_access(ncid, varid, access)
1725  integer, intent(in) :: ncid
1726  integer, intent(in) :: varid
1727  integer, intent(in) :: access
1728  integer :: nf90_var_par_access
1729  end function nf90_var_par_access
1730 
1731 ~~~~
1732 
1733 
1734 
1735 `ncid`
1736 
1737 : NetCDF ID, from a previous call to NF90\_OPEN (see
1738  [NF90\_OPEN](#NF90_005fOPEN)) or NF90\_CREATE (see
1739  [NF90\_CREATE](#NF90_005fCREATE)).
1740 
1741 `varid`
1742 
1743 : Variable ID.
1744 
1745 `access`
1746 
1747 : NF90\_INDEPENDENT to set this variable to independent operations.
1748  NF90\_COLLECTIVE to set it to collective operations.
1749 
1750 
1751 
1752 ## Return Values
1753 
1754 `NF90_NOERR`
1755 
1756 : No error.
1757 
1758 `NF90_ENOTVAR`
1759 
1760 : No variable found.
1761 
1762 `NF90_NOPAR`
1763 
1764 : File not opened for parallel access.
1765 
1766 
1767 
1768 ## Example
1769 
1770 This example comes from test program nf\_test/f90tst\_parallel.f90. For
1771 this test to be run, netCDF must have been built with a parallel-enabled
1772 HDF5, and –enable-parallel-tests must have been used when configuring
1773 netcdf.
1774 
1775 
1776 
1777 ~~~~.fortran
1778 
1779  ! Reopen the file.
1780  call handle_err(nf90_open(FILE_NAME, nf90_nowrite, ncid, comm = MPI_COMM_WORLD, &
1781  info = MPI_INFO_NULL))
1782 
1783  ! Set collective access on this variable. This will cause all
1784  ! reads/writes to happen together on every processor.
1785  call handle_err(nf90_var_par_access(ncid, varid, nf90_collective))
1786 
1787  ! Read this processor's data.
1788  call handle_err(nf90_get_var(ncid, varid, data_in, start = start, count = count))
1789 
1790 ~~~~

Return to the Main Unidata NetCDF page.
Generated on Wed Aug 1 2018 06:17:02 for NetCDF-Fortran. NetCDF is a Unidata library.