1 4 Dimensions {#f90_dimensions}
6 4.1 Dimensions Introduction {#f90-dimensions-introduction}
9 Dimensions for a netCDF dataset are defined when it is created, while
10 the netCDF dataset is in define mode. Additional dimensions may be added
11 later by reentering define mode. A netCDF dimension has a name and a
12 length. At most one dimension in a netCDF dataset can have the unlimited
13 length, which means variables using this dimension can grow along this
16 There is a suggested limit (512) to the number of dimensions that can be
17 defined in a single netCDF dataset. The limit is the value of the
18 constant NF90\_MAX\_DIMS. The purpose of the limit is to make writing
19 generic applications simpler. They need only provide an array of
20 NF90\_MAX\_DIMS dimensions to handle any netCDF dataset. The
21 implementation of the netCDF library does not enforce this advisory
22 maximum, so it is possible to use more dimensions, if necessary, but
23 netCDF utilities that assume the advisory maximums may not be able to
24 handle the resulting netCDF datasets.
26 Ordinarily, the name and length of a dimension are fixed when the
27 dimension is first defined. The name may be changed later, but the
28 length of a dimension (other than the unlimited dimension) cannot be
29 changed without copying all the data to a new netCDF dataset with a
30 redefined dimension length.
32 A netCDF dimension in an open netCDF dataset is referred to by a small
33 integer called a dimension ID. In the Fortran 90 interface, dimension
34 IDs are 1, 2, 3, ..., in the order in which the dimensions were defined.
36 Operations supported on dimensions are:
38 - Create a dimension, given its name and length.
39 - Get a dimension ID from its name.
40 - Get a dimension’s name and length from its ID.
43 4.2 NF90_DEF_DIM {#f90-nf90_def_dim}
48 The function NF90\_DEF\_DIM adds a new dimension to an open netCDF
49 dataset in define mode. It returns (as an argument) a dimension ID,
50 given the netCDF ID, the dimension name, and the dimension length. At
51 most one unlimited length dimension, called the record dimension, may be
52 defined for each netCDF dataset.
61 function nf90_def_dim(ncid, name, len, dimid)
62 integer, intent( in) :: ncid
63 character (len = *), intent( in) :: name
64 integer, intent( in) :: len
65 integer, intent(out) :: dimid
66 integer :: nf90_def_dim
73 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
81 : Length of dimension; that is, number of values for this dimension as
82 an index to variables that use it. This should be either a positive
83 integer or the predefined constant NF90\_UNLIMITED.
87 : Returned dimension ID.
93 NF90\_DEF\_DIM returns the value NF90\_NOERR if no errors occurred.
94 Otherwise, the returned status indicates an error. Possible causes of
97 - The netCDF dataset is not in definition mode.
98 - The specified dimension name is the name of another
100 - The specified length is not greater than zero.
101 - The specified length is unlimited, but there is already an unlimited
102 length dimension defined for this netCDF dataset.
103 - The specified netCDF ID does not refer to an open netCDF dataset.
109 Here is an example using NF90\_DEF\_DIM to create a dimension named lat
110 of length 18 and a unlimited dimension named rec in a new netCDF dataset
118 integer :: ncid, status, LatDimID, RecordDimID
120 status = nf90_create("foo.nc", nf90_noclobber, ncid)
121 if (status /= nf90_noerr) call handle_err(status)
123 status = nf90_def_dim(ncid, "Lat", 18, LatDimID)
124 if (status /= nf90_noerr) call handle_err(status)
125 status = nf90_def_dim(ncid, "Record", nf90_unlimited, RecordDimID)
126 if (status /= nf90_noerr) call handle_err(status)
132 4.3 NF90_INQ_DIMID {#f90-nf90_inq_dimid}
137 The function NF90\_INQ\_DIMID returns (as an argument) the ID of a
138 netCDF dimension, given the name of the dimension. If ndims is the
139 number of dimensions defined for a netCDF dataset, each dimension has an
140 ID between 1 and ndims.
149 function nf90_inq_dimid(ncid, name, dimid)
150 integer, intent( in) :: ncid
151 character (len = *), intent( in) :: name
152 integer, intent(out) :: dimid
153 integer :: nf90_inq_dimid
161 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
169 : Returned dimension ID.
175 NF90\_INQ\_DIMID returns the value NF90\_NOERR if no errors occurred.
176 Otherwise, the returned status indicates an error. Possible causes of
179 - The name that was specified is not the name of a dimension in the
181 - The specified netCDF ID does not refer to an open netCDF dataset.
187 Here is an example using NF90\_INQ\_DIMID to determine the dimension ID
188 of a dimension named lat, assumed to have been defined previously in an
189 existing netCDF dataset named foo.nc:
196 integer :: ncid, status, LatDimID
198 status = nf90_open("foo.nc", nf90_nowrite, ncid)
199 if (status /= nf90_noerr) call handle_err(status)
201 status = nf90_inq_dimid(ncid, "Lat", LatDimID)
202 if (status /= nf90_noerr) call handle_err(status)
207 4.4 NF90_INQUIRE_DIMENSION {#f90-nf90_inquire_dimension}
212 This function information about a netCDF dimension. Information about a
213 dimension includes its name and its length. The length for the unlimited
214 dimension, if any, is the number of records written so far.
223 function nf90_inquire_dimension(ncid, dimid, name, len)
224 integer, intent( in) :: ncid, dimid
225 character (len = *), optional, intent(out) :: name
226 integer, optional, intent(out) :: len
227 integer :: nf90_inquire_dimension
235 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
239 : Dimension ID, from a previous call to NF90\_INQ\_DIMID
244 : Returned dimension name. The caller must allocate space for the
245 returned name. The maximum possible length, in characters, of a
246 dimension name is given by the predefined constant NF90\_MAX\_NAME.
250 : Returned length of dimension. For the unlimited dimension, this is
251 the current maximum value used for writing any variables with this
252 dimension, that is the maximum record number.
258 These functions return the value NF90\_NOERR if no errors occurred.
259 Otherwise, the returned status indicates an error. Possible causes of
262 - The dimension ID is invalid for the specified netCDF dataset.
263 - The specified netCDF ID does not refer to an open netCDF dataset.
269 Here is an example using NF90\_INQ\_DIM to determine the length of a
270 dimension named lat, and the name and current maximum length of the
271 unlimited dimension for an existing netCDF dataset named foo.nc:
278 integer :: ncid, status, LatDimID, RecordDimID
279 integer :: nLats, nRecords
280 character(len = nf90_max_name) :: RecordDimName
282 status = nf90_open("foo.nc", nf90_nowrite, ncid)
283 if (status /= nf90_noerr) call handle_err(status)
284 ! Get ID of unlimited dimension
285 status = nf90_inquire(ncid, unlimitedDimId = RecordDimID)
286 if (status /= nf90_noerr) call handle_err(status)
288 status = nf90_inq_dimid(ncid, "Lat", LatDimID)
289 if (status /= nf90_noerr) call handle_err(status)
290 ! How many values of "lat" are there?
291 status = nf90_inquire_dimension(ncid, LatDimID, len = nLats)
292 if (status /= nf90_noerr) call handle_err(status)
293 ! What is the name of the unlimited dimension, how many records are there?
294 status = nf90_inquire_dimension(ncid, RecordDimID, &
295 name = RecordDimName, len = Records)
296 if (status /= nf90_noerr) call handle_err(status)
302 4.5 NF90_RENAME_DIM {#f90-nf90_rename_dim}
307 The function NF90\_RENAME\_DIM renames an existing dimension in a netCDF
308 dataset open for writing. If the new name is longer than the old name,
309 the netCDF dataset must be in define mode. You cannot rename a dimension
310 to have the same name as another dimension.
319 function nf90_rename_dim(ncid, dimid, name)
320 integer, intent( in) :: ncid
321 character (len = *), intent( in) :: name
322 integer, intent( in) :: dimid
323 integer :: nf90_rename_dim
331 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
335 : Dimension ID, from a previous call to NF90\_INQ\_DIMID
340 : New dimension name.
346 NF90\_RENAME\_DIM returns the value NF90\_NOERR if no errors occurred.
347 Otherwise, the returned status indicates an error. Possible causes of
350 - The new name is the name of another dimension.
351 - The dimension ID is invalid for the specified netCDF dataset.
352 - The specified netCDF ID does not refer to an open netCDF dataset.
353 - The new name is longer than the old name and the netCDF dataset is
360 Here is an example using NF90\_RENAME\_DIM to rename the dimension lat
361 to latitude in an existing netCDF dataset named foo.nc:
368 integer :: ncid, status, LatDimID
370 status = nf90_open("foo.nc", nf90_write, ncid)
371 if (status /= nf90_noerr) call handle_err(status)
373 ! Put in define mode so we can rename the dimension
374 status = nf90_redef(ncid)
375 if (status /= nf90_noerr) call handle_err(status)
376 ! Get the dimension ID for "Lat"...
377 status = nf90_inq_dimid(ncid, "Lat", LatDimID)
378 if (status /= nf90_noerr) call handle_err(status)
379 ! ... and change the name to "Latitude".
380 status = nf90_rename_dim(ncid, LatDimID, "Latitude")
381 if (status /= nf90_noerr) call handle_err(status)
383 status = nf90_enddef(ncid)
384 if (status /= nf90_noerr) call handle_err(status)