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 Define Filter Parameters for a Variable: `nf90_def_var_filter` {#f90-define-filter-parameters-for-a-variable-nf90_def_var_filter}
517 The function nf90\_def\_var\_filter sets the filter parameters for a
518 variable in a netCDF-4 file.
520 This function must be called after the variable is defined, but before
521 nf90\_enddef is called.
530 function nf90_def_var_filter(ncid, varid, filterid, nparams, params);
531 integer, intent(in) :: ncid, varid, filterid, nparams
532 integer, dimension(:), intent(in) :: params
539 : NetCDF ID, from a previous call to nf90\_open or nf90\_create.
547 : The HDFGroup assigned filter id (e.g. 307 for bzip2).
551 : The number of parameters for the filter
555 : A vector of parameters of size nparams.
570 : Not a netCDF-4 file.
574 : Can’t find this variable.
578 : This variable has already been the subject of a NF90\_ENDDEF call.
579 In netCDF-4 files NF90\_ENDDEF will be called automatically for any
580 data read or write. Once enddef has been called, it is impossible to
581 set the fill for a variable.
585 : Not in define mode. This is returned for netCDF classic or 64-bit
586 offset files, or for netCDF-4 files, when they were been created
587 with NF90\_STRICT\_NC3 flag. (see section
588 [NF90\_CREATE](#NF90_005fCREATE)).
592 : Attempt to create object in read-only file.
596 : Invalid filter id or parameters
601 6.7 Get information about any Filter associated with a variable: `nf90_inq_var_filter` {#f90-get-information-about-a-variable-from-its-id-nf90_inq_var_filter}
605 The function nf90\_inq\_var\_filter gets the filter id and parameters for a
606 variable in a netCDF-4 file.
614 function nf90_inq_var_filter(ncid, varid, filterid, nparams, params);
615 integer, intent(in) :: ncid, varid, filterid, nparams
616 integer, intent(out) :: filterid, nparams
617 integer, dimension(:), intent(out) :: params
624 : NetCDF ID, from a previous call to nf90\_open or nf90\_create.
632 : Store the the HDFGroup assigned filter id
636 : Stor the number of parameters for the filter
640 : Store the vector of parameters of size nparams.
654 : Not a netCDF-4 file.
658 : Can’t find this variable.
662 : This variable has already been the subject of a NF90\_ENDDEF call.
663 In netCDF-4 files NF90\_ENDDEF will be called automatically for any
664 data read or write. Once enddef has been called, it is impossible to
665 set the fill for a variable.
669 : Not in define mode. This is returned for netCDF classic or 64-bit
670 offset files, or for netCDF-4 files, when they were been created
671 with NF90\_STRICT\_NC3 flag. (see section
672 [NF90\_CREATE](#NF90_005fCREATE)).
676 : Attempt to create object in read-only file.
680 : Invalid filter id or parameters
686 6.8 Get Information about a Variable from Its ID: NF90_INQUIRE_VARIABLE {#f90-get-information-about-a-variable-from-its-id-nf90_inquire_variable}
689 NF90\_INQUIRE\_VARIABLE returns information about a netCDF variable
690 given its ID. Information about a variable includes its name, type,
691 number of dimensions, a list of dimension IDs describing the shape of
692 the variable, and the number of variable attributes that have been
693 assigned to the variable.
695 All parameters after nAtts are optional, and only supported if netCDF
696 was built with netCDF-4 features enabled, and if the variable is in a
707 function nf90_inquire_variable(ncid, varid, name, xtype, ndims, dimids, nAtts, &
708 contiguous, chunksizes, deflate_level, shuffle, fletcher32, endianness)
709 integer, intent(in) :: ncid, varid
710 character (len = *), optional, intent(out) :: name
711 integer, optional, intent(out) :: xtype, ndims
712 integer, dimension(:), optional, intent(out) :: dimids
713 integer, optional, intent(out) :: nAtts
714 logical, optional, intent(out) :: contiguous
715 integer, optional, dimension(:), intent(out) :: chunksizes
716 integer, optional, intent(out) :: deflate_level
717 logical, optional, intent(out) :: shuffle, fletcher32
718 integer, optional, intent(out) :: endianness
719 integer :: nf90_inquire_variable
727 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
735 : Returned variable name. The caller must allocate space for the
736 returned name. The maximum possible length, in characters, of a
737 variable name is given by the predefined constant NF90\_MAX\_NAME.
741 : Returned variable type, one of the set of predefined netCDF external
742 data types. The valid netCDF external data types are NF90\_BYTE,
743 NF90\_CHAR, NF90\_SHORT, NF90\_INT, NF90\_FLOAT, AND NF90\_DOUBLE.
747 : Returned number of dimensions the variable was defined as using. For
748 example, 2 indicates a matrix, 1 indicates a vector, and 0 means the
749 variable is a scalar with no dimensions.
753 : Returned vector of \*ndimsp dimension IDs corresponding to the
754 variable dimensions. The caller must allocate enough space for a
755 vector of at least \*ndimsp integers to be returned. The maximum
756 possible number of dimensions for a variable is given by the
757 predefined constant NF90\_MAX\_VAR\_DIMS.
761 : Returned number of variable attributes assigned to this variable.
765 : On return, set to NF90\_CONTIGUOUS if this variable uses contiguous
766 storage, NF90\_CHUNKED if it uses chunked storage.
770 : An array of chunk sizes. The array must have the one element for
771 each dimension in the variable.
775 : True if the shuffle filter is turned on for this variable.
779 : The deflate\_level from 0 to 9. A value of zero indicates no
784 : Set to true if the fletcher32 checksum filter is turned on for
789 : Will be set to NF90\_ENDIAN\_LITTLE if this variable is stored in
790 little-endian format, NF90\_ENDIAN\_BIG if it is stored in
791 big-endian format, and NF90\_ENDIAN\_NATIVE if the endianness is not
792 set, and the variable is not created yet.
794 These functions return the value NF90\_NOERR if no errors occurred.
795 Otherwise, the returned status indicates an error. Possible causes of
798 - The variable ID is invalid for the specified netCDF dataset.
799 - The specified netCDF ID does not refer to an open netCDF dataset.
805 Here is an example using NF90\_INQ\_VAR to find out about a variable
806 named rh in an existing netCDF dataset named foo.nc:
814 integer :: status, ncid, &
817 integer, dimension(nf90_max_var_dims) :: rhDimIds
819 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
820 if(status /= nf90_NoErr) call handle_error(status)
822 status = nf90_inq_varid(ncid, "rh", RhVarId)
823 if(status /= nf90_NoErr) call handle_err(status)
824 status = nf90_inquire_variable(ncid, RhVarId, ndims = numDims, natts = numAtts)
825 if(status /= nf90_NoErr) call handle_err(status)
826 status = nf90_inquire_variable(ncid, RhVarId, dimids = rhDimIds(:numDims))
827 if(status /= nf90_NoErr) call handle_err(status)
833 6.9 Get the ID of a variable from the name: NF90_INQ_VARID {#f90-get-the-id-of-a-variable-from-the-name-nf90_inq_varid}
838 Given the name of a variable, nf90\_inq\_varid finds the variable ID.
848 function nf90_inq_varid(ncid, name, varid)
849 integer, intent(in) :: ncid
850 character (len = *), intent( in) :: name
851 integer, intent(out) :: varid
852 integer :: nf90_inq_varid
860 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
864 : The variable name. The maximum possible length, in characters, of a
865 variable name is given by the predefined constant NF90\_MAX\_NAME.
871 These functions return the value NF90\_NOERR if no errors occurred.
872 Otherwise, the returned status indicates an error. Possible causes of
875 - Variable not found.
876 - The specified netCDF ID does not refer to an open netCDF dataset.
882 Here is an example using NF90\_INQ\_VARID to find out about a variable
883 named rh in an existing netCDF dataset named foo.nc:
891 integer :: status, ncid, &
894 integer, dimension(nf90_max_var_dims) :: rhDimIds
896 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
897 if(status /= nf90_NoErr) call handle_error(status)
899 status = nf90_inq_varid(ncid, "rh", RhVarId)
900 if(status /= nf90_NoErr) call handle_err(status)
901 status = nf90_inquire_variable(ncid, RhVarId, ndims = numDims, natts = numAtts)
902 if(status /= nf90_NoErr) call handle_err(status)
903 status = nf90_inquire_variable(ncid, RhVarId, dimids = rhDimIds(:numDims))
904 if(status /= nf90_NoErr) call handle_err(status)
911 6.10 Writing Data Values: NF90_PUT_VAR {#f90-writing-data-values-nf90_put_var}
916 The function NF90\_PUT\_VAR puts one or more data values into the
917 variable of an open netCDF dataset that is in data mode. Required inputs
918 are the netCDF ID, the variable ID, and one or more data values.
919 Optional inputs may indicate the starting position of the data values in
920 the netCDF variable (argument start), the sampling frequency with which
921 data values are written into the netCDF variable (argument stride), and
922 a mapping between the dimensions of the data array and the netCDF
923 variable (argument map). The values to be written are associated with
924 the netCDF variable by assuming that the first dimension of the netCDF
925 variable varies fastest in the Fortran 90 interface. Data values are
926 converted to the external type of the variable, if necessary.
928 Take care when using the simplest forms of this interface with record
929 variables (variables that use the NF90\_UNLIMITED dimension) when you
930 don’t specify how many records are to be written. If you try to write
931 all the values of a record variable into a netCDF file that has no
932 record data yet (hence has 0 records), nothing will be written.
933 Similarly, if you try to write all the values of a record variable from
934 an array but there are more records in the file than you assume, more
935 in-memory data will be accessed than you expect, which may cause a
936 segmentation violation. To avoid such problems, it is better to specify
937 start and count arguments for variables that use the NF90\_UNLIMITED
948 function nf90_put_var(ncid, varid, values, start, count, stride, map)
949 integer, intent( in) :: ncid, varid
950 any valid type, scalar or array of any rank, &
951 intent( in) :: values
952 integer, dimension(:), optional, intent( in) :: start, count, stride, map
953 integer :: nf90_put_var
961 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
969 : The data value(s) to be written. The data may be of any type, and
970 may be a scalar or an array of any rank. You cannot put CHARACTER
971 data into a numeric variable or numeric data into a text variable.
972 For numeric data, if the type of data differs from the netCDF
973 variable type, type conversion will occur. See [Type
974 Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide.
978 : A vector of integers specifying the index in the variable where the
979 first (or only) of the data values will be written. The indices are
980 relative to 1, so for example, the first data value of a variable
981 would have index (1, 1, ..., 1). The elements of start correspond,
982 in order, to the variable’s dimensions. Hence, if the variable is a
983 record variable, the last index would correspond to the starting
984 record number for writing the data values.
986 By default, start(:) = 1.
990 : A vector of integers specifying the number of indices selected along
991 each dimension. To write a single value, for example, specify count
992 as (1, 1, ..., 1). The elements of count correspond, in order, to
993 the variable’s dimensions. Hence, if the variable is a record
994 variable, the last element of count corresponds to a count of the
995 number of records to write.
997 By default, count(:numDims) = shape(values) and count(numDims + 1:)
998 = 1, where numDims = size(shape(values)).
1002 : A vector of integers that specifies the sampling interval along each
1003 dimension of the netCDF variable. The elements of the stride vector
1004 correspond, in order, to the netCDF variable’s dimensions (stride(1)
1005 gives the sampling interval along the most rapidly varying dimension
1006 of the netCDF variable). Sampling intervals are specified in
1007 type-independent units of elements (a value of 1 selects consecutive
1008 elements of the netCDF variable along the corresponding dimension, a
1009 value of 2 selects every other element, etc.).
1011 By default, stride(:) = 1.
1015 : A vector of integers that specifies the mapping between the
1016 dimensions of a netCDF variable and the in-memory structure of the
1017 internal data array. The elements of the index mapping vector
1018 correspond, in order, to the netCDF variable’s dimensions (map(1)
1019 gives the distance between elements of the internal array
1020 corresponding to the most rapidly varying dimension of the
1021 netCDF variable). Distances between elements are specified in units
1024 By default, edgeLengths = shape(values), and map = (/ 1,
1025 (product(edgeLengths(:i)), i = 1, size(edgeLengths) - 1) /), that
1026 is, there is no mapping.
1028 Use of Fortran 90 intrinsic functions (including reshape, transpose,
1029 and spread) may let you avoid using this argument.
1035 NF90\_PUT\_VAR1\_ type returns the value NF90\_NOERR if no errors
1036 occurred. Otherwise, the returned status indicates an error. Possible
1037 causes of errors include:
1039 - The variable ID is invalid for the specified netCDF dataset.
1040 - The specified indices were out of range for the rank of the
1041 specified variable. For example, a negative index or an index that
1042 is larger than the corresponding dimension length will cause
1044 - The specified value is out of the range of values representable by
1045 the external data type of the variable.
1046 - The specified netCDF is in define mode rather than data mode.
1047 - The specified netCDF ID does not refer to an open netCDF dataset.
1053 Here is an example using NF90\_PUT\_VAR to set the (4,3,2) element of
1054 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
1055 For simplicity in this example, we assume that we know that rh is
1056 dimensioned with lon, lat, and time, so we want to set the value of rh
1057 that corresponds to the fourth lon value, the third lat value, and the
1066 integer :: ncId, rhVarId, status
1068 status = nf90_open("foo.nc", nf90_Write, ncid)
1069 if(status /= nf90_NoErr) call handle_err(status)
1071 status = nf90_inq_varid(ncid, "rh", rhVarId)
1072 if(status /= nf90_NoErr) call handle_err(status)
1073 status = nf90_put_var(ncid, rhVarId, 0.5, start = (/ 4, 3, 2 /) )
1074 if(status /= nf90_NoErr) call handle_err(status)
1080 In this example we use NF90\_PUT\_VAR to add or change all the values of
1081 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
1082 We assume that we know that rh is dimensioned with lon, lat, and time.
1083 In this example we query the netCDF file to discover the lengths of the
1084 dimensions, then use the Fortran 90 intrinsic function reshape to create
1085 a temporary array of data values which is the same shape as the netCDF
1094 integer :: ncId, rhVarId,status, &
1095 lonDimID, latDimId, timeDimId, &
1096 numLons, numLats, numTimes, &
1098 integer, dimension(nf90_max_var_dims) :: dimIDs
1100 status = nf90_open("foo.nc", nf90_Write, ncid)
1101 if(status /= nf90_NoErr) call handle_err(status)
1103 status = nf90_inq_varid(ncid, "rh", rhVarId)
1104 if(status /= nf90_NoErr) call handle_err(status)
1105 ! How big is the netCDF variable, that is, what are the lengths of
1106 ! its constituent dimensions?
1107 status = nf90_inquire_variable(ncid, rhVarId, dimids = dimIDs)
1108 if(status /= nf90_NoErr) call handle_err(status)
1109 status = nf90_inquire_dimension(ncid, dimIDs(1), len = numLons)
1110 if(status /= nf90_NoErr) call handle_err(status)
1111 status = nf90_inquire_dimension(ncid, dimIDs(2), len = numLats)
1112 if(status /= nf90_NoErr) call handle_err(status)
1113 status = nf90_inquire_dimension(ncid, dimIDs(3), len = numTimes)
1114 if(status /= nf90_NoErr) call handle_err(status)
1116 ! Make a temporary array the same shape as the netCDF variable.
1117 status = nf90_put_var(ncid, rhVarId, &
1119 (/ (0.5, i = 1, numLons * numLats * numTimes) /) , &
1120 shape = (/ numLons, numLats, numTimes /) )
1121 if(status /= nf90_NoErr) call handle_err(status)
1127 Here is an example using NF90\_PUT\_VAR to add or change a section of
1128 the variable named rh to 0.5 in an existing netCDF dataset named foo.nc.
1129 For simplicity in this example, we assume that we know that rh is
1130 dimensioned with lon, lat, and time, that there are ten lon values, five
1131 lat values, and three time values, and that we want to replace all the
1132 values at the last time.
1140 integer :: ncId, rhVarId, status
1141 integer, parameter :: numLons = 10, numLats = 5, numTimes = 3
1142 real, dimension(numLons, numLats) &
1145 status = nf90_open("foo.nc", nf90_Write, ncid)
1146 if(status /= nf90_NoErr) call handle_err(status)
1148 status = nf90_inq_varid(ncid, "rh", rhVarId)
1149 if(status /= nf90_NoErr) call handle_err(status)
1150 ! Fill in all values at the last time
1151 rhValues(:, :) = 0.5
1152 status = nf90_put_var(ncid, rhVarId,rhvalues, &
1153 start = (/ 1, 1, numTimes /), &
1154 count = (/ numLats, numLons, 1 /))
1155 if(status /= nf90_NoErr) call handle_err(status)
1161 Here is an example of using NF90\_PUT\_VAR to write every other point of
1162 a netCDF variable named rh having dimensions (6, 4).
1170 integer :: ncId, rhVarId, status
1171 integer, parameter :: numLons = 6, numLats = 4
1172 real, dimension(numLons, numLats) &
1175 status = nf90_open("foo.nc", nf90_Write, ncid)
1176 if(status /= nf90_NoErr) call handle_err(status)
1178 status = nf90_inq_varid(ncid, "rh", rhVarId)
1179 if(status /= nf90_NoErr) call handle_err(status)
1181 ! Fill in every other value using an array section
1182 status = nf90_put_var(ncid, rhVarId, rhValues(::2, ::2), &
1183 stride = (/ 2, 2 /))
1184 if(status /= nf90_NoErr) call handle_err(status)
1190 The following map vector shows the default mapping between a 2x3x4
1191 netCDF variable and an internal array of the same shape:
1197 real, dimension(2, 3, 4):: a ! same shape as netCDF variable
1198 integer, dimension(3) :: map = (/ 1, 2, 6 /)
1199 ! netCDF dimension inter-element distance
1200 ! ---------------- ----------------------
1201 ! most rapidly varying 1
1202 ! intermediate 2 (= map(1)*2)
1203 ! most slowly varying 6 (= map(2)*3)
1209 Using the map vector above obtains the same result as simply not passing
1210 a map vector at all.
1212 Here is an example of using nf90\_put\_var to write a netCDF variable
1213 named rh whose dimensions are the transpose of the Fortran 90 array:
1221 integer :: ncId, rhVarId, status
1222 integer, parameter :: numLons = 6, numLats = 4
1223 real, dimension(numLons, numLats) :: rhValues
1224 ! netCDF variable has dimensions (numLats, numLons)
1226 status = nf90_open("foo.nc", nf90_Write, ncid)
1227 if(status /= nf90_NoErr) call handle_err(status)
1229 status = nf90_inq_varid(ncid, "rh", rhVarId)
1230 if(status /= nf90_NoErr) call handle_err(status)
1232 !Write transposed values: map vector would be (/ 1, numLats /) for
1234 status = nf90_put_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /))
1235 if(status /= nf90_NoErr) call handle_err(status)
1241 The same effect can be obtained more simply using Fortran 90 intrinsic
1250 integer :: ncId, rhVarId, status
1251 integer, parameter :: numLons = 6, numLats = 4
1252 real, dimension(numLons, numLats) :: rhValues
1253 ! netCDF variable has dimensions (numLats, numLons)
1255 status = nf90_open("foo.nc", nf90_Write, ncid)
1256 if(status /= nf90_NoErr) call handle_err(status)
1258 status = nf90_inq_varid(ncid, "rh", rhVarId)
1259 if(status /= nf90_NoErr) call handle_err(status)
1261 status = nf90_put_var(ncid, rhVarId, transpose(rhValues))
1262 if(status /= nf90_NoErr) call handle_err(status)
1269 6.11 Reading Data Values: NF90_GET_VAR {#f90-reading-data-values-nf90_get_var}
1274 The function NF90\_GET\_VAR gets one or more data values from a netCDF
1275 variable of an open netCDF dataset that is in data mode. Required inputs
1276 are the netCDF ID, the variable ID, and a specification for the data
1277 values into which the data will be read. Optional inputs may indicate
1278 the starting position of the data values in the netCDF variable
1279 (argument start), the sampling frequency with which data values are read
1280 from the netCDF variable (argument stride), and a mapping between the
1281 dimensions of the data array and the netCDF variable (argument map). The
1282 values to be read are associated with the netCDF variable by assuming
1283 that the first dimension of the netCDF variable varies fastest in the
1284 Fortran 90 interface. Data values are converted from the external type
1285 of the variable, if necessary.
1287 Take care when using the simplest forms of this interface with record
1288 variables (variables that use the NF90\_UNLIMITED dimension) when you
1289 don’t specify how many records are to be read. If you try to read all
1290 the values of a record variable into an array but there are more records
1291 in the file than you assume, more data will be read than you expect,
1292 which may cause a segmentation violation. To avoid such problems, it is
1293 better to specify the optional start and count arguments for variables
1294 that use the NF90\_UNLIMITED dimension.
1296 In netCDF classic model the maximum integer size is NF90\_INT, the
1297 4-byte signed integer. Reading variables into an eight-byte integer
1298 array from a classic model file will read from an NF90\_INT. Reading
1299 variables into an eight-byte integer in a netCDF-4/HDF5 (without classic
1300 model flag) will read from an NF90\_INT64
1310 function nf90_get_var(ncid, varid, values, start, count, stride, map)
1311 integer, intent( in) :: ncid, varid
1312 any valid type, scalar or array of any rank, &
1313 intent(out) :: values
1314 integer, dimension(:), optional, intent( in) :: start, count, stride, map
1315 integer :: nf90_get_var
1323 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1331 : The data value(s) to be read. The data may be of any type, and may
1332 be a scalar or an array of any rank. You cannot read CHARACTER data
1333 from a numeric variable or numeric data from a text variable. For
1334 numeric data, if the type of data differs from the netCDF variable
1335 type, type conversion will occur. See [Type
1336 Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide.
1340 : A vector of integers specifying the index in the variable from which
1341 the first (or only) of the data values will be read. The indices are
1342 relative to 1, so for example, the first data value of a variable
1343 would have index (1, 1, ..., 1). The elements of start correspond,
1344 in order, to the variable’s dimensions. Hence, if the variable is a
1345 record variable, the last index would correspond to the starting
1346 record number for writing the data values.
1348 By default, start(:) = 1.
1352 : A vector of integers specifying the number of indices selected along
1353 each dimension. To read a single value, for example, specify count
1354 as (1, 1, ..., 1). The elements of count correspond, in order, to
1355 the variable’s dimensions. Hence, if the variable is a record
1356 variable, the last element of count corresponds to a count of the
1357 number of records to read.
1359 By default, count(:numDims) = shape(values) and count(numDims + 1:)
1360 = 1, where numDims = size(shape(values)).
1364 : A vector of integers that specifies the sampling interval along each
1365 dimension of the netCDF variable. The elements of the stride vector
1366 correspond, in order, to the netCDF variable’s dimensions (stride(1)
1367 gives the sampling interval along the most rapidly varying dimension
1368 of the netCDF variable). Sampling intervals are specified in
1369 type-independent units of elements (a value of 1 selects consecutive
1370 elements of the netCDF variable along the corresponding dimension, a
1371 value of 2 selects every other element, etc.).
1373 By default, stride(:) = 1.
1377 : A vector of integers that specifies the mapping between the
1378 dimensions of a netCDF variable and the in-memory structure of the
1379 internal data array. The elements of the index mapping vector
1380 correspond, in order, to the netCDF variable’s dimensions (map(1)
1381 gives the distance between elements of the internal array
1382 corresponding to the most rapidly varying dimension of the
1383 netCDF variable). Distances between elements are specified in units
1386 By default, edgeLengths = shape(values), and map = (/ 1,
1387 (product(edgeLengths(:i)), i = 1, size(edgeLengths) - 1) /), that
1388 is, there is no mapping.
1390 Use of Fortran 90 intrinsic functions (including reshape, transpose,
1391 and spread) may let you avoid using this argument.
1397 NF90\_GET\_VAR returns the value NF90\_NOERR if no errors occurred.
1398 Otherwise, the returned status indicates an error. Possible causes of
1401 - The variable ID is invalid for the specified netCDF dataset.
1402 - The assumed or specified start, count, and stride generate an index
1403 which is out of range. Note that no error checking is possible on
1405 - One or more of the specified values are out of the range of values
1406 representable by the desired type.
1407 - The specified netCDF is in define mode rather than data mode.
1408 - The specified netCDF ID does not refer to an open netCDF dataset.
1410 (As noted above, another possible source of error is using this
1411 interface to read all the values of a record variable without specifying
1412 the number of records. If there are more records in the file than you
1413 assume, more data will be read than you expect!)
1419 Here is an example using NF90\_GET\_VAR to read the (4,3,2) element of
1420 the variable named rh from an existing netCDF dataset named foo.nc. For
1421 simplicity in this example, we assume that we know that rh is
1422 dimensioned with lon, lat, and time, so we want to read the value of rh
1423 that corresponds to the fourth lon value, the third lat value, and the
1432 integer :: ncId, rhVarId, status
1435 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1436 if(status /= nf90_NoErr) call handle_err(status)
1438 status = nf90_inq_varid(ncid, "rh", rhVarId)
1439 if(status /= nf90_NoErr) call handle_err(status)
1440 status = nf90_get_var(ncid, rhVarId, rhValue, start = (/ 4, 3, 2 /) )
1441 if(status /= nf90_NoErr) call handle_err(status)
1447 In this example we use NF90\_GET\_VAR to read all the values of the
1448 variable named rh from an existing netCDF dataset named foo.nc. We
1449 assume that we know that rh is dimensioned with lon, lat, and time. In
1450 this example we query the netCDF file to discover the lengths of the
1451 dimensions, then allocate a Fortran 90 array the same shape as the
1459 integer :: ncId, rhVarId, &
1460 lonDimID, latDimId, timeDimId, &
1461 numLons, numLats, numTimes, &
1463 integer, dimension(nf90_max_var_dims) :: dimIDs
1464 real, dimension(:, :, :), allocatable :: rhValues
1466 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1467 if(status /= nf90_NoErr) call handle_err(status)
1469 status = nf90_inq_varid(ncid, "rh", rhVarId)
1470 if(status /= nf90_NoErr) call handle_err(status)
1471 ! How big is the netCDF variable, that is, what are the lengths of
1472 ! its constituent dimensions?
1473 status = nf90_inquire_variable(ncid, rhVarId, dimids = dimIDs)
1474 if(status /= nf90_NoErr) call handle_err(status)
1475 status = nf90_inquire_dimension(ncid, dimIDs(1), len = numLons)
1476 if(status /= nf90_NoErr) call handle_err(status)
1477 status = nf90_inquire_dimension(ncid, dimIDs(2), len = numLats)
1478 if(status /= nf90_NoErr) call handle_err(status)
1479 status = nf90_inquire_dimension(ncid, dimIDs(3), len = numTimes)
1480 if(status /= nf90_NoErr) call handle_err(status)
1481 allocate(rhValues(numLons, numLats, numTimes))
1483 status = nf90_get_var(ncid, rhVarId, rhValues)
1484 if(status /= nf90_NoErr) call handle_err(status)
1489 Here is an example using NF90\_GET\_VAR to read a section of the
1490 variable named rh from an existing netCDF dataset named foo.nc. For
1491 simplicity in this example, we assume that we know that rh is
1492 dimensioned with lon, lat, and time, that there are ten lon values, five
1493 lat values, and three time values, and that we want to replace all the
1494 values at the last time.
1502 integer :: ncId, rhVarId, status
1503 integer, parameter :: numLons = 10, numLats = 5, numTimes = 3
1504 real, dimension(numLons, numLats, numTimes) &
1507 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1508 if(status /= nf90_NoErr) call handle_err(status)
1510 status = nf90_inq_varid(ncid, "rh", rhVarId)
1511 if(status /= nf90_NoErr) call handle_err(status)
1512 !Read the values at the last time by passing an array section
1513 status = nf90_get_var(ncid, rhVarId, rhValues(:, :, 3), &
1514 start = (/ 1, 1, numTimes /), &
1515 count = (/ numLons, numLats, 1 /))
1516 if(status /= nf90_NoErr) call handle_err(status)
1522 Here is an example of using NF90\_GET\_VAR to read every other point of
1523 a netCDF variable named rh having dimensions (6, 4).
1531 integer :: ncId, rhVarId, status
1532 integer, parameter :: numLons = 6, numLats = 4
1533 real, dimension(numLons, numLats) &
1536 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1537 if(status /= nf90_NoErr) call handle_err(status)
1539 status = nf90_inq_varid(ncid, "rh", rhVarId)
1540 if(status /= nf90_NoErr) call handle_err(status)
1542 ! Read every other value into an array section
1543 status = nf90_get_var(ncid, rhVarId, rhValues(::2, ::2) &
1544 stride = (/ 2, 2 /))
1545 if(status /= nf90_NoErr) call handle_err(status)
1551 The following map vector shows the default mapping between a 2x3x4
1552 netCDF variable and an internal array of the same shape:
1558 real, dimension(2, 3, 4):: a ! same shape as netCDF variable
1559 integer, dimension(3) :: map = (/ 1, 2, 6 /)
1560 ! netCDF dimension inter-element distance
1561 ! ---------------- ----------------------
1562 ! most rapidly varying 1
1563 ! intermediate 2 (= map(1)*2)
1564 ! most slowly varying 6 (= map(2)*3)
1571 Using the map vector above obtains the same result as simply not passing
1572 a map vector at all.
1574 Here is an example of using nf90\_get\_var to read a netCDF variable
1575 named rh whose dimensions are the transpose of the Fortran 90 array:
1583 integer :: ncId, rhVarId, status
1584 integer, parameter :: numLons = 6, numLats = 4
1585 real, dimension(numLons, numLats) :: rhValues
1586 ! netCDF variable has dimensions (numLats, numLons)
1588 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1589 if(status /= nf90_NoErr) call handle_err(status)
1591 status = nf90_inq_varid(ncid, "rh", rhVarId)
1592 if(status /= nf90_NoErr) call handle_err(status)
1594 ! Read transposed values: map vector would be (/ 1, numLats /) for
1596 status = nf90_get_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /))
1597 if(status /= nf90_NoErr) call handle_err(status)
1603 The same effect can be obtained more simply, though using more memory,
1604 using Fortran 90 intrinsic functions:
1612 integer :: ncId, rhVarId, status
1613 integer, parameter :: numLons = 6, numLats = 4
1614 real, dimension(numLons, numLats) :: rhValues
1615 ! netCDF variable has dimensions (numLats, numLons)
1616 real, dimension(numLons, numLats) :: tempValues
1618 status = nf90_open("foo.nc", nf90_NoWrite, ncid)
1619 if(status /= nf90_NoErr) call handle_err(status)
1621 status = nf90_inq_varid(ncid, "rh", rhVarId)
1622 if(status /= nf90_NoErr) call handle_err(status)
1624 status = nf90_get_var(ncid, rhVarId, tempValues))
1625 if(status /= nf90_NoErr) call handle_err(status)
1626 rhValues(:, :) = transpose(tempValues)
1634 6.12 Reading and Writing Character String Values {#f90-reading-and-writing-character-string-values}
1637 Character strings are not a primitive netCDF external data type under
1638 the classic netCDF data model, in part because FORTRAN does not support
1639 the abstraction of variable-length character strings (the FORTRAN LEN
1640 function returns the static length of a character string, not its
1641 dynamic length). As a result, a character string cannot be written or
1642 read as a single object in the netCDF interface. Instead, a character
1643 string must be treated as an array of characters, and array access must
1644 be used to read and write character strings as variable data in netCDF
1645 datasets. Furthermore, variable-length strings are not supported by the
1646 netCDF classic interface except by convention; for example, you may
1647 treat a zero byte as terminating a character string, but you must
1648 explicitly specify the length of strings to be read from and written to
1651 Character strings as attribute values are easier to use, since the
1652 strings are treated as a single unit for access. However, the value of a
1653 character-string attribute in the classic netCDF interface is still an
1654 array of characters with an explicit length that must be specified when
1655 the attribute is defined.
1657 When you define a variable that will have character-string values, use a
1658 character-position dimension as the most quickly varying dimension for
1659 the variable (the first dimension for the variable in Fortran 90). The
1660 length of the character-position dimension will be the maximum string
1661 length of any value to be stored in the character-string variable. Space
1662 for maximum-length strings will be allocated in the disk representation
1663 of character-string variables whether you use the space or not. If two
1664 or more variables have the same maximum length, the same
1665 character-position dimension may be used in defining the variable
1668 To write a character-string value into a character-string variable, use
1669 either entire variable access or array access. The latter requires that
1670 you specify both a corner and a vector of edge lengths. The
1671 character-position dimension at the corner should be one for Fortran 90.
1672 If the length of the string to be written is n, then the vector of edge
1673 lengths will specify n in the character-position dimension, and one for
1674 all the other dimensions: (n, 1, 1, ..., 1).
1676 In Fortran 90, fixed-length strings may be written to a netCDF dataset
1677 without a terminating character, to save space. Variable-length strings
1678 should follow the C convention of writing strings with a terminating
1679 zero byte so that the intended length of the string can be determined
1680 when it is later read by either C or Fortran 90 programs. It is the
1681 users responsibility to provide such null termination.
1683 If you are writing data in the default prefill mode (see next section),
1684 you can ensure that simple strings represented as 1-dimensional
1685 character arrays are null terminated in the netCDF file by writing fewer
1686 characters than the length declared when the variable was defined. That
1687 way, the extra unwritten characters will be filled with the default
1688 character fill value, which is a null byte. The Fortran intrinsic TRIM
1689 function can be used to trim trailing blanks from the character string
1690 argument to NF90\_PUT\_VAR to make the argument shorter than the
1691 declared length. If prefill is not on, the data writer must explicitly
1692 provide a null terminating byte.
1694 Here is an example illustrating this way of writing strings to character
1704 integer :: ncid, oceanStrLenID, oceanId
1705 integer, parameter :: MaxOceanNameLen = 20
1706 character, (len = MaxOceanNameLen):: ocean
1708 status = nf90_create("foo.nc", nf90_NoClobber, ncid)
1709 if(status /= nf90_NoErr) call handle_err(status)
1711 status = nf90_def_dim(ncid, "oceanStrLen", MaxOceanNameLen, oceanStrLenId)
1712 if(status /= nf90_NoErr) call handle_err(status)
1714 status = nf90_def_var(ncid, "ocean", nf90_char, (/ oceanStrLenId /), oceanId)
1715 if(status /= nf90_NoErr) call handle_err(status)
1717 ! Leave define mode, which prefills netCDF variables with fill values
1718 status = nf90_enddef(ncid)
1719 if (status /= nf90_noerr) call handle_err(status)
1721 ! Note that this assignment adds blank fill
1723 ! Using trim removes trailing blanks, prefill provides null
1724 ! termination, so C programs can later get intended string.
1725 status = nf90_put_var(ncid, oceanId, trim(ocean))
1726 if(status /= nf90_NoErr) call handle_err(status)
1732 6.13 Fill Values {#f90-fill-values}
1735 What happens when you try to read a value that was never written in an
1736 open netCDF dataset? You might expect that this should always be an
1737 error, and that you should get an error message or an error status
1738 returned. You do get an error if you try to read data from a netCDF
1739 dataset that is not open for reading, if the variable ID is invalid for
1740 the specified netCDF dataset, or if the specified indices are not
1741 properly within the range defined by the dimension lengths of the
1742 specified variable. Otherwise, reading a value that was not written
1743 returns a special fill value used to fill in any undefined values when a
1744 netCDF variable is first written.
1746 You may ignore fill values and use the entire range of a netCDF external
1747 data type, but in this case you should make sure you write all data
1748 values before reading them. If you know you will be writing all the data
1749 before reading it, you can specify that no prefilling of variables with
1750 fill values will occur by calling writing. This may provide a
1751 significant performance gain for netCDF writes.
1753 The variable attribute \_FillValue may be used to specify the fill value
1754 for a variable. There are default fill values for each type, defined in
1755 module netcdf: NF90\_FILL\_CHAR, NF90\_FILL\_INT1 (same as
1756 NF90\_FILL\_BYTE), NF90\_FILL\_INT2 (same as NF90\_FILL\_SHORT),
1757 NF90\_FILL\_INT, NF90\_FILL\_REAL (same as NF90\_FILL\_FLOAT), and
1760 The netCDF byte and character types have different default fill values.
1761 The default fill value for characters is the zero byte, a useful value
1762 for detecting the end of variable-length C character strings. If you
1763 need a fill value for a byte variable, it is recommended that you
1764 explicitly define an appropriate \_FillValue attribute, as generic
1765 utilities such as ncdump will not assume a default fill value for byte
1768 Type conversion for fill values is identical to type conversion for
1769 other values: attempting to convert a value from one type to another
1770 type that can’t represent the value results in a range error. Such
1771 errors may occur on writing or reading values from a larger type (such
1772 as double) to a smaller type (such as float), if the fill value for the
1773 larger type cannot be represented in the smaller type.
1776 6.14 NF90_RENAME_VAR {#f90-nf90_rename_var}
1781 The function NF90\_RENAME\_VAR changes the name of a netCDF variable in
1782 an open netCDF dataset. If the new name is longer than the old name, the
1783 netCDF dataset must be in define mode. You cannot rename a variable to
1784 have the name of any existing variable.
1794 function nf90_rename_var(ncid, varid, newname)
1795 integer, intent( in) :: ncid, varid
1796 character (len = *), intent( in) :: newname
1797 integer :: nf90_rename_var
1805 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
1813 : New name for the specified variable.
1819 NF90\_RENAME\_VAR returns the value NF90\_NOERR if no errors occurred.
1820 Otherwise, the returned status indicates an error. Possible causes of
1823 - The new name is in use as the name of another variable.
1824 - The variable ID is invalid for the specified netCDF dataset.
1825 - The specified netCDF ID does not refer to an open netCDF dataset.
1831 Here is an example using NF90\_RENAME\_VAR to rename the variable rh to
1832 rel\_hum in an existing netCDF dataset named foo.nc:
1840 integer :: ncId, rhVarId, status
1842 status = nf90_open("foo.nc", nf90_Write, ncid)
1843 if(status /= nf90_NoErr) call handle_err(status)
1845 status = nf90_inq_varid(ncid, "rh", rhVarId)
1846 if(status /= nf90_NoErr) call handle_err(status)
1847 status = nf90_redef(ncid) ! Enter define mode to change variable name
1848 if(status /= nf90_NoErr) call handle_err(status)
1849 status = nf90_rename_var(ncid, rhVarId, "rel_hum")
1850 if(status /= nf90_NoErr) call handle_err(status)
1851 status = nf90_enddef(ncid) ! Leave define mode
1852 if(status /= nf90_NoErr) call handle_err(status)
1859 6.15 Change between Collective and Independent Parallel Access: NF90_VAR_PAR_ACCESS {#f90-change-between-collective-and-independent-parallel-access-nf90_var_par_access}
1864 The function NF90\_VAR\_PAR\_ACCESS changes whether read/write
1865 operations on a parallel file system are performed collectively or
1866 independently (the default) on the variable. This function can only be
1867 called if the file was created (see [NF90\_CREATE](#NF90_005fCREATE)) or
1868 opened (see [NF90\_OPEN](#NF90_005fOPEN)) for parallel I/O.
1870 This function is only available if the netCDF library was built with
1871 parallel I/O enabled.
1873 Calling this function affects only the open file - information about
1874 whether a variable is to be accessed collectively or independently is
1875 not written to the data file. Every time you open a file on a parallel
1876 file system, all variables default to independent operations. The change
1877 of a variable to collective access lasts only as long as that file is
1880 The variable can be changed from collective to independent, and back, as
1883 Classic and 64-bit offset files, when opened for parallel access, use
1884 the parallel-netcdf (a.k.a. pnetcdf) library, which does not allow
1885 per-variable changes of access mode - the entire file must be access
1886 independently or collectively. For classic and 64-bit offset files, the
1887 nf90\_var\_par\_access function changes the access for all variables in
1898 function nf90_var_par_access(ncid, varid, access)
1899 integer, intent(in) :: ncid
1900 integer, intent(in) :: varid
1901 integer, intent(in) :: access
1902 integer :: nf90_var_par_access
1903 end function nf90_var_par_access
1911 : NetCDF ID, from a previous call to NF90\_OPEN (see
1912 [NF90\_OPEN](#NF90_005fOPEN)) or NF90\_CREATE (see
1913 [NF90\_CREATE](#NF90_005fCREATE)).
1921 : NF90\_INDEPENDENT to set this variable to independent operations.
1922 NF90\_COLLECTIVE to set it to collective operations.
1934 : No variable found.
1938 : File not opened for parallel access.
1944 This example comes from test program nf\_test/f90tst\_parallel.f90. For
1945 this test to be run, netCDF must have been built with a parallel-enabled
1946 HDF5, and –enable-parallel-tests must have been used when configuring
1954 call handle_err(nf90_open(FILE_NAME, nf90_nowrite, ncid, comm = MPI_COMM_WORLD, &
1955 info = MPI_INFO_NULL))
1957 ! Set collective access on this variable. This will cause all
1958 ! reads/writes to happen together on every processor.
1959 call handle_err(nf90_var_par_access(ncid, varid, nf90_collective))
1961 ! Read this processor's data.
1962 call handle_err(nf90_get_var(ncid, varid, data_in, start = start, count = count))