NetCDF-Fortran  4.5.2
netcdf-f90-sec4-dimensions.md
Go to the documentation of this file.
1 4 Dimensions {#f90_dimensions}
2 ============
3 
4 [TOC]
5 
6 4.1 Dimensions Introduction {#f90-dimensions-introduction}
7 ============
8 
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
14 dimension.
15 
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.
25 
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.
31 
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.
35 
36 Operations supported on dimensions are:
37 
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.
41 - Rename a dimension.
42 
43 4.2 NF90_DEF_DIM {#f90-nf90_def_dim}
44 ============
45 
46 
47 
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.
53 
54 
55 
56 ## Usage
57 
58 
59 ~~~~.fortran
60 
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
67 
68 ~~~~
69 
70 
71 `ncid`
72 
73 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
74 
75 `name`
76 
77 : Dimension name.
78 
79 `len`
80 
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.
84 
85 `dimid`
86 
87 : Returned dimension ID.
88 
89 
90 
91 ## Errors
92 
93 NF90\_DEF\_DIM returns the value NF90\_NOERR if no errors occurred.
94 Otherwise, the returned status indicates an error. Possible causes of
95 errors include:
96 
97 - The netCDF dataset is not in definition mode.
98 - The specified dimension name is the name of another
99  existing dimension.
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.
104 
105 
106 
107 ## Example
108 
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
111 named foo.nc:
112 
113 
114 ~~~~.fortran
115 
116  use netcdf
117  implicit none
118  integer :: ncid, status, LatDimID, RecordDimID
119  ...
120  status = nf90_create("foo.nc", nf90_noclobber, ncid)
121  if (status /= nf90_noerr) call handle_err(status)
122  ...
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)
127 
128 ~~~~
129 
130 
131 
132 4.3 NF90_INQ_DIMID {#f90-nf90_inq_dimid}
133 ============
134 
135 
136 
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.
141 
142 
143 
144 ## Usage
145 
146 
147 ~~~~.fortran
148 
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
154 
155 ~~~~
156 
157 
158 
159 `ncid`
160 
161 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
162 
163 `name`
164 
165 : Dimension name.
166 
167 `dimid`
168 
169 : Returned dimension ID.
170 
171 
172 
173 ## Errors
174 
175 NF90\_INQ\_DIMID returns the value NF90\_NOERR if no errors occurred.
176 Otherwise, the returned status indicates an error. Possible causes of
177 errors include:
178 
179 - The name that was specified is not the name of a dimension in the
180  netCDF dataset.
181 - The specified netCDF ID does not refer to an open netCDF dataset.
182 
183 
184 
185 ## Example
186 
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:
190 
191 
192 ~~~~.fortran
193 
194  use netcdf
195  implicit none
196  integer :: ncid, status, LatDimID
197  ...
198  status = nf90_open("foo.nc", nf90_nowrite, ncid)
199  if (status /= nf90_noerr) call handle_err(status)
200  ...
201  status = nf90_inq_dimid(ncid, "Lat", LatDimID)
202  if (status /= nf90_noerr) call handle_err(status)
203 
204 ~~~~
205 
206 
207 4.4 NF90_INQUIRE_DIMENSION {#f90-nf90_inquire_dimension}
208 ============
209 
210 
211 
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.
215 
216 
217 
218 ## Usage
219 
220 
221 ~~~~.fortran
222 
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
228 
229 ~~~~
230 
231 
232 
233 `ncid`
234 
235 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
236 
237 `dimid`
238 
239 : Dimension ID, from a previous call to NF90\_INQ\_DIMID
240  or NF90\_DEF\_DIM.
241 
242 `name`
243 
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.
247 
248 `len`
249 
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.
253 
254 
255 
256 ## Errors
257 
258 These functions return the value NF90\_NOERR if no errors occurred.
259 Otherwise, the returned status indicates an error. Possible causes of
260 errors include:
261 
262 - The dimension ID is invalid for the specified netCDF dataset.
263 - The specified netCDF ID does not refer to an open netCDF dataset.
264 
265 
266 
267 ## Example
268 
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:
272 
273 
274 ~~~~.fortran
275 
276  use netcdf
277  implicit none
278  integer :: ncid, status, LatDimID, RecordDimID
279  integer :: nLats, nRecords
280  character(len = nf90_max_name) :: RecordDimName
281  ...
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)
287  ...
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)
297 
298 ~~~~
299 
300 
301 
302 4.5 NF90_RENAME_DIM {#f90-nf90_rename_dim}
303 ============
304 
305 
306 
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.
311 
312 
313 
314 ## Usage
315 
316 
317 ~~~~.fortran
318 
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
324 
325 ~~~~
326 
327 
328 
329 `ncid`
330 
331 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
332 
333 `dimid`
334 
335 : Dimension ID, from a previous call to NF90\_INQ\_DIMID
336  or NF90\_DEF\_DIM.
337 
338 `name`
339 
340 : New dimension name.
341 
342 
343 
344 ## Errors
345 
346 NF90\_RENAME\_DIM returns the value NF90\_NOERR if no errors occurred.
347 Otherwise, the returned status indicates an error. Possible causes of
348 errors include:
349 
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
354  not in define mode.
355 
356 
357 
358 ## Example
359 
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:
362 
363 
364 ~~~~~~.fortran
365 
366 use netcdf
367 implicit none
368 integer :: ncid, status, LatDimID
369 ...
370 status = nf90_open("foo.nc", nf90_write, ncid)
371 if (status /= nf90_noerr) call handle_err(status)
372 ...
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)
382 ! Leave define mode
383 status = nf90_enddef(ncid)
384 if (status /= nf90_noerr) call handle_err(status)
385 
386 ~~~~~~

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