1 6 Variables {#f90-variables}
6 6.1 Variables Introduction {#f90-variables-introduction}
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.
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.
20 A netCDF variable in an open netCDF dataset is referred to by a small
21 integer called a variable ID.
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.
28 Attributes (see [Attributes](#Attributes)) may be associated with a
29 variable to specify such properties as units.
31 Operations supported on variables are:
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
37 - Put a data value into a variable, given variable ID, indices,
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
53 6.2 Language Types Corresponding to netCDF external data types {#f90-language-types-corresponding-to-netcdf-external-data-types}
56 The following table gives the netCDF external data types and the
57 corresponding type constants for defining variables in the FORTRAN
60 Type | FORTRAN API Mnemonic | Bits
61 -------| ----------------------| ------
64 short | NF90_SHORT | 16
66 float | NF90_FLOAT | 32
67 double | NF90_DOUBLE | 64
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
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
82 6.3 Create a Variable: `NF90_DEF_VAR` {#f90-create-a-variable-nf90_def_var}
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.
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.
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
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.
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
139 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
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.
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.
161 If an integer is passed for this parameter, a 1-D variable
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.
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.
172 This argument is optional, and if absent specifies a scalar with
177 : Returned variable ID.
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
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
191 By default contiguous storage is used for fix-sized variables when
192 conpression, chunking, shuffle, and checksums are not used.
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.
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.)
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’}.
211 : If non-zero, turn on the shuffle filter.
215 : If the deflate parameter is non-zero, set the deflate level to
216 this value. Must be between 1 and 9.
220 : Set to true to turn on fletcher32 checksums for this variable.
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.
230 : The size of the per-variable cache in MegaBytes.
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).
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
250 NF90\_DEF\_VAR returns the value NF90\_NOERR if no errors occurred.
251 Otherwise, the returned status indicates an error.
253 - NF90\_EBADNAME The specified variable name is the name of another
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
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
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
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.
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:
302 integer :: status, ncid
303 integer :: LonDimId, LatDimId, TimeDimId
306 status = nf90_create("foo.nc", nf90_NoClobber, ncid)
307 if(status /= nf90_NoErr) call handle_error(status)
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)
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)
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.
333 ! Create the netCDF file.
334 call check(nf90_create(FILE_NAME, nf90_netcdf4, ncid, cache_nelems = CACHE_NELEMS, &
335 cache_size = CACHE_SIZE))
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 /)
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.))
354 6.4 Define Fill Parameters for a Variable: `nf90_def_var_fill` {#f90-define-fill-parameters-for-a-variable-nf90_def_var_fill}
359 The function NF90\_DEF\_VAR\_FILL sets the fill parameters for a
360 variable in a netCDF-4 file.
362 This function must be called after the variable is defined, but before
363 NF90\_ENDDEF is called.
373 NF90_DEF_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE);
381 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
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
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.
419 : Not a netCDF-4 file.
423 : Can’t find this variable.
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.
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)).
441 : Attempt to create object in read-only file.
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}
453 The function NF90\_INQ\_VAR\_FILL returns the fill settings for a
454 variable in a netCDF-4 file.
464 NF90_INQ_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE)
472 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
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
485 : This will get the fill value for this variable. This parameter will
486 be ignored if it is NULL.
502 : Not a netCDF-4 file.
506 : Can’t find this variable.
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}
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.
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
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
553 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
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.
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.
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.
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.
587 : Returned number of variable attributes assigned to this variable.
591 : On return, set to NF90\_CONTIGUOUS if this variable uses contiguous
592 storage, NF90\_CHUNKED if it uses chunked storage.
596 : An array of chunk sizes. The array must have the one element for
597 each dimension in the variable.
601 : True if the shuffle filter is turned on for this variable.
605 : The deflate\_level from 0 to 9. A value of zero indicates no
610 : Set to true if the fletcher32 checksum filter is turned on for
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.
620 These functions return the value NF90\_NOERR if no errors occurred.
621 Otherwise, the returned status indicates an error. Possible causes of
624 - The variable ID is invalid for the specified netCDF dataset.
625 - The specified netCDF ID does not refer to an open netCDF dataset.
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:
640 integer :: status, ncid, &
643 integer, dimension(nf90_max_var_dims) :: rhDimIds
645 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
646 if(status /= nf90_NoErr) call handle_error(status)
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)
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}
664 Given the name of a varaible, nf90\_inq\_varid finds the variable ID.
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
686 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
690 : The variable name. The maximum possible length, in characters, of a
691 variable name is given by the predefined constant NF90\_MAX\_NAME.
697 These functions return the value NF90\_NOERR if no errors occurred.
698 Otherwise, the returned status indicates an error. Possible causes of
701 - Variable not found.
702 - The specified netCDF ID does not refer to an open netCDF dataset.
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:
717 integer :: status, ncid, &
720 integer, dimension(nf90_max_var_dims) :: rhDimIds
722 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
723 if(status /= nf90_NoErr) call handle_error(status)
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)
737 6.8 Writing Data Values: NF90_PUT_VAR {#f90-writing-data-values-nf90_put_var}
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.
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
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
787 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
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.
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.
812 By default, start(:) = 1.
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.
823 By default, count(:numDims) = shape(values) and count(numDims + 1:)
824 = 1, where numDims = size(shape(values)).
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.).
837 By default, stride(:) = 1.
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
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.
854 Use of Fortran 90 intrinsic functions (including reshape, transpose,
855 and spread) may let you avoid using this argument.
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:
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
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.
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
892 integer :: ncId, rhVarId, status
894 status = nf90_open("foo.nc", nf90_Write, ncid)
895 if(status /= nf90_NoErr) call handle_err(status)
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)
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
920 integer :: ncId, rhVarId,status, &
921 lonDimID, latDimId, timeDimId, &
922 numLons, numLats, numTimes, &
924 integer, dimension(nf90_max_var_dims) :: dimIDs
926 status = nf90_open("foo.nc", nf90_Write, ncid)
927 if(status /= nf90_NoErr) call handle_err(status)
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)
942 ! Make a temporary array the same shape as the netCDF variable.
943 status = nf90_put_var(ncid, rhVarId, &
945 (/ (0.5, i = 1, numLons * numLats * numTimes) /) , &
946 shape = (/ numLons, numLats, numTimes /) )
947 if(status /= nf90_NoErr) call handle_err(status)
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.
966 integer :: ncId, rhVarId, status
967 integer, parameter :: numLons = 10, numLats = 5, numTimes = 3
968 real, dimension(numLons, numLats) &
971 status = nf90_open("foo.nc", nf90_Write, ncid)
972 if(status /= nf90_NoErr) call handle_err(status)
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
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)
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).
996 integer :: ncId, rhVarId, status
997 integer, parameter :: numLons = 6, numLats = 4
998 real, dimension(numLons, numLats) &
1001 status = nf90_open("foo.nc", nf90_Write, ncid)
1002 if(status /= nf90_NoErr) call handle_err(status)
1004 status = nf90_inq_varid(ncid, "rh", rhVarId)
1005 if(status /= nf90_NoErr) call handle_err(status)
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)
1016 The following map vector shows the default mapping between a 2x3x4
1017 netCDF variable and an internal array of the same shape:
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)
1035 Using the map vector above obtains the same result as simply not passing
1036 a map vector at all.
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:
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)
1052 status = nf90_open("foo.nc", nf90_Write, ncid)
1053 if(status /= nf90_NoErr) call handle_err(status)
1055 status = nf90_inq_varid(ncid, "rh", rhVarId)
1056 if(status /= nf90_NoErr) call handle_err(status)
1058 !Write transposed values: map vector would be (/ 1, numLats /) for
1060 status = nf90_put_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /))
1061 if(status /= nf90_NoErr) call handle_err(status)
1067 The same effect can be obtained more simply using Fortran 90 intrinsic
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)
1081 status = nf90_open("foo.nc", nf90_Write, ncid)
1082 if(status /= nf90_NoErr) call handle_err(status)
1084 status = nf90_inq_varid(ncid, "rh", rhVarId)
1085 if(status /= nf90_NoErr) call handle_err(status)
1087 status = nf90_put_var(ncid, rhVarId, transpose(rhValues))
1088 if(status /= nf90_NoErr) call handle_err(status)
1095 6.9 Reading Data Values: NF90_GET_VAR {#f90-reading-data-values-nf90_get_var}
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.
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.
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
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
1149 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
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.
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.
1174 By default, start(:) = 1.
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.
1185 By default, count(:numDims) = shape(values) and count(numDims + 1:)
1186 = 1, where numDims = size(shape(values)).
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.).
1199 By default, stride(:) = 1.
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
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.
1216 Use of Fortran 90 intrinsic functions (including reshape, transpose,
1217 and spread) may let you avoid using this argument.
1223 NF90\_GET\_VAR returns the value NF90\_NOERR if no errors occurred.
1224 Otherwise, the returned status indicates an error. Possible causes of
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
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.
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!)
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
1258 integer :: ncId, rhVarId, status
1261 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1262 if(status /= nf90_NoErr) call handle_err(status)
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)
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
1285 integer :: ncId, rhVarId, &
1286 lonDimID, latDimId, timeDimId, &
1287 numLons, numLats, numTimes, &
1289 integer, dimension(nf90_max_var_dims) :: dimIDs
1290 real, dimension(:, :, :), allocatable :: rhValues
1292 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1293 if(status /= nf90_NoErr) call handle_err(status)
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))
1309 status = nf90_get_var(ncid, rhVarId, rhValues)
1310 if(status /= nf90_NoErr) call handle_err(status)
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.
1328 integer :: ncId, rhVarId, status
1329 integer, parameter :: numLons = 10, numLats = 5, numTimes = 3
1330 real, dimension(numLons, numLats, numTimes) &
1333 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1334 if(status /= nf90_NoErr) call handle_err(status)
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)
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).
1357 integer :: ncId, rhVarId, status
1358 integer, parameter :: numLons = 6, numLats = 4
1359 real, dimension(numLons, numLats) &
1362 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1363 if(status /= nf90_NoErr) call handle_err(status)
1365 status = nf90_inq_varid(ncid, "rh", rhVarId)
1366 if(status /= nf90_NoErr) call handle_err(status)
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)
1377 The following map vector shows the default mapping between a 2x3x4
1378 netCDF variable and an internal array of the same shape:
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)
1397 Using the map vector above obtains the same result as simply not passing
1398 a map vector at all.
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:
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)
1414 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1415 if(status /= nf90_NoErr) call handle_err(status)
1417 status = nf90_inq_varid(ncid, "rh", rhVarId)
1418 if(status /= nf90_NoErr) call handle_err(status)
1420 ! Read transposed values: map vector would be (/ 1, numLats /) for
1422 status = nf90_get_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /))
1423 if(status /= nf90_NoErr) call handle_err(status)
1429 The same effect can be obtained more simply, though using more memory,
1430 using Fortran 90 intrinsic functions:
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
1444 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1445 if(status /= nf90_NoErr) call handle_err(status)
1447 status = nf90_inq_varid(ncid, "rh", rhVarId)
1448 if(status /= nf90_NoErr) call handle_err(status)
1450 status = nf90_get_var(ncid, rhVarId, tempValues))
1451 if(status /= nf90_NoErr) call handle_err(status)
1452 rhValues(:, :) = transpose(tempValues)
1460 6.10 Reading and Writing Character String Values {#f90-reading-and-writing-character-string-values}
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
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.
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
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).
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.
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.
1520 Here is an example illustrating this way of writing strings to character
1530 integer :: ncid, oceanStrLenID, oceanId
1531 integer, parameter :: MaxOceanNameLen = 20
1532 character, (len = MaxOceanNameLen):: ocean
1534 status = nf90_create("foo.nc", nf90_NoClobber, ncid)
1535 if(status /= nf90_NoErr) call handle_err(status)
1537 status = nf90_def_dim(ncid, "oceanStrLen", MaxOceanNameLen, oceanStrLenId)
1538 if(status /= nf90_NoErr) call handle_err(status)
1540 status = nf90_def_var(ncid, "ocean", nf90_char, (/ oceanStrLenId /), oceanId)
1541 if(status /= nf90_NoErr) call handle_err(status)
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)
1547 ! Note that this assignment adds blank fill
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)
1558 6.11 Fill Values {#f90-fill-values}
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.
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.
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
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
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.
1602 6.12 NF90_RENAME_VAR {#f90-nf90_rename_var}
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.
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
1631 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1639 : New name for the specified variable.
1645 NF90\_RENAME\_VAR returns the value NF90\_NOERR if no errors occurred.
1646 Otherwise, the returned status indicates an error. Possible causes of
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.
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:
1666 integer :: ncId, rhVarId, status
1668 status = nf90_open("foo.nc", nf90_Write, ncid)
1669 if(status /= nf90_NoErr) call handle_err(status)
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)
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}
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.
1696 This function is only available if the netCDF library was built with
1697 parallel I/O enabled.
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
1706 The variable can be changed from collective to independent, and back, as
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
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
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)).
1747 : NF90\_INDEPENDENT to set this variable to independent operations.
1748 NF90\_COLLECTIVE to set it to collective operations.
1760 : No variable found.
1764 : File not opened for parallel access.
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
1780 call handle_err(nf90_open(FILE_NAME, nf90_nowrite, ncid, comm = MPI_COMM_WORLD, &
1781 info = MPI_INFO_NULL))
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))
1787 ! Read this processor's data.
1788 call handle_err(nf90_get_var(ncid, varid, data_in, start = start, count = count))