1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386
|
4 Dimensions {#f90_dimensions}
============
[TOC]
4.1 Dimensions Introduction {#f90-dimensions-introduction}
============
Dimensions for a netCDF dataset are defined when it is created, while
the netCDF dataset is in define mode. Additional dimensions may be added
later by reentering define mode. A netCDF dimension has a name and a
length. At most one dimension in a netCDF dataset can have the unlimited
length, which means variables using this dimension can grow along this
dimension.
There is a suggested limit (512) to the number of dimensions that can be
defined in a single netCDF dataset. The limit is the value of the
constant NF90\_MAX\_DIMS. The purpose of the limit is to make writing
generic applications simpler. They need only provide an array of
NF90\_MAX\_DIMS dimensions to handle any netCDF dataset. The
implementation of the netCDF library does not enforce this advisory
maximum, so it is possible to use more dimensions, if necessary, but
netCDF utilities that assume the advisory maximums may not be able to
handle the resulting netCDF datasets.
Ordinarily, the name and length of a dimension are fixed when the
dimension is first defined. The name may be changed later, but the
length of a dimension (other than the unlimited dimension) cannot be
changed without copying all the data to a new netCDF dataset with a
redefined dimension length.
A netCDF dimension in an open netCDF dataset is referred to by a small
integer called a dimension ID. In the Fortran 90 interface, dimension
IDs are 1, 2, 3, ..., in the order in which the dimensions were defined.
Operations supported on dimensions are:
- Create a dimension, given its name and length.
- Get a dimension ID from its name.
- Get a dimension’s name and length from its ID.
- Rename a dimension.
4.2 NF90_DEF_DIM {#f90-nf90_def_dim}
============
The function NF90\_DEF\_DIM adds a new dimension to an open netCDF
dataset in define mode. It returns (as an argument) a dimension ID,
given the netCDF ID, the dimension name, and the dimension length. At
most one unlimited length dimension, called the record dimension, may be
defined for each netCDF dataset.
## Usage
~~~~.fortran
function nf90_def_dim(ncid, name, len, dimid)
integer, intent( in) :: ncid
character (len = *), intent( in) :: name
integer, intent( in) :: len
integer, intent(out) :: dimid
integer :: nf90_def_dim
~~~~
`ncid`
: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
`name`
: Dimension name.
`len`
: Length of dimension; that is, number of values for this dimension as
an index to variables that use it. This should be either a positive
integer or the predefined constant NF90\_UNLIMITED.
`dimid`
: Returned dimension ID.
## Errors
NF90\_DEF\_DIM returns the value NF90\_NOERR if no errors occurred.
Otherwise, the returned status indicates an error. Possible causes of
errors include:
- The netCDF dataset is not in definition mode.
- The specified dimension name is the name of another
existing dimension.
- The specified length is not greater than zero.
- The specified length is unlimited, but there is already an unlimited
length dimension defined for this netCDF dataset.
- The specified netCDF ID does not refer to an open netCDF dataset.
## Example
Here is an example using NF90\_DEF\_DIM to create a dimension named lat
of length 18 and a unlimited dimension named rec in a new netCDF dataset
named foo.nc:
~~~~.fortran
use netcdf
implicit none
integer :: ncid, status, LatDimID, RecordDimID
...
status = nf90_create("foo.nc", nf90_noclobber, ncid)
if (status /= nf90_noerr) call handle_err(status)
...
status = nf90_def_dim(ncid, "Lat", 18, LatDimID)
if (status /= nf90_noerr) call handle_err(status)
status = nf90_def_dim(ncid, "Record", nf90_unlimited, RecordDimID)
if (status /= nf90_noerr) call handle_err(status)
~~~~
4.3 NF90_INQ_DIMID {#f90-nf90_inq_dimid}
============
The function NF90\_INQ\_DIMID returns (as an argument) the ID of a
netCDF dimension, given the name of the dimension. If ndims is the
number of dimensions defined for a netCDF dataset, each dimension has an
ID between 1 and ndims.
## Usage
~~~~.fortran
function nf90_inq_dimid(ncid, name, dimid)
integer, intent( in) :: ncid
character (len = *), intent( in) :: name
integer, intent(out) :: dimid
integer :: nf90_inq_dimid
~~~~
`ncid`
: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
`name`
: Dimension name.
`dimid`
: Returned dimension ID.
## Errors
NF90\_INQ\_DIMID returns the value NF90\_NOERR if no errors occurred.
Otherwise, the returned status indicates an error. Possible causes of
errors include:
- The name that was specified is not the name of a dimension in the
netCDF dataset.
- The specified netCDF ID does not refer to an open netCDF dataset.
## Example
Here is an example using NF90\_INQ\_DIMID to determine the dimension ID
of a dimension named lat, assumed to have been defined previously in an
existing netCDF dataset named foo.nc:
~~~~.fortran
use netcdf
implicit none
integer :: ncid, status, LatDimID
...
status = nf90_open("foo.nc", nf90_nowrite, ncid)
if (status /= nf90_noerr) call handle_err(status)
...
status = nf90_inq_dimid(ncid, "Lat", LatDimID)
if (status /= nf90_noerr) call handle_err(status)
~~~~
4.4 NF90_INQUIRE_DIMENSION {#f90-nf90_inquire_dimension}
============
This function information about a netCDF dimension. Information about a
dimension includes its name and its length. The length for the unlimited
dimension, if any, is the number of records written so far.
## Usage
~~~~.fortran
function nf90_inquire_dimension(ncid, dimid, name, len)
integer, intent( in) :: ncid, dimid
character (len = *), optional, intent(out) :: name
integer, optional, intent(out) :: len
integer :: nf90_inquire_dimension
~~~~
`ncid`
: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
`dimid`
: Dimension ID, from a previous call to NF90\_INQ\_DIMID
or NF90\_DEF\_DIM.
`name`
: Returned dimension name. The caller must allocate space for the
returned name. The maximum possible length, in characters, of a
dimension name is given by the predefined constant NF90\_MAX\_NAME.
`len`
: Returned length of dimension. For the unlimited dimension, this is
the current maximum value used for writing any variables with this
dimension, that is the maximum record number.
## Errors
These functions return the value NF90\_NOERR if no errors occurred.
Otherwise, the returned status indicates an error. Possible causes of
errors include:
- The dimension ID is invalid for the specified netCDF dataset.
- The specified netCDF ID does not refer to an open netCDF dataset.
## Example
Here is an example using NF90\_INQ\_DIM to determine the length of a
dimension named lat, and the name and current maximum length of the
unlimited dimension for an existing netCDF dataset named foo.nc:
~~~~.fortran
use netcdf
implicit none
integer :: ncid, status, LatDimID, RecordDimID
integer :: nLats, nRecords
character(len = nf90_max_name) :: RecordDimName
...
status = nf90_open("foo.nc", nf90_nowrite, ncid)
if (status /= nf90_noerr) call handle_err(status)
! Get ID of unlimited dimension
status = nf90_inquire(ncid, unlimitedDimId = RecordDimID)
if (status /= nf90_noerr) call handle_err(status)
...
status = nf90_inq_dimid(ncid, "Lat", LatDimID)
if (status /= nf90_noerr) call handle_err(status)
! How many values of "lat" are there?
status = nf90_inquire_dimension(ncid, LatDimID, len = nLats)
if (status /= nf90_noerr) call handle_err(status)
! What is the name of the unlimited dimension, how many records are there?
status = nf90_inquire_dimension(ncid, RecordDimID, &
name = RecordDimName, len = Records)
if (status /= nf90_noerr) call handle_err(status)
~~~~
4.5 NF90_RENAME_DIM {#f90-nf90_rename_dim}
============
The function NF90\_RENAME\_DIM renames an existing dimension in a netCDF
dataset open for writing. If the new name is longer than the old name,
the netCDF dataset must be in define mode. You cannot rename a dimension
to have the same name as another dimension.
## Usage
~~~~.fortran
function nf90_rename_dim(ncid, dimid, name)
integer, intent( in) :: ncid
character (len = *), intent( in) :: name
integer, intent( in) :: dimid
integer :: nf90_rename_dim
~~~~
`ncid`
: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
`dimid`
: Dimension ID, from a previous call to NF90\_INQ\_DIMID
or NF90\_DEF\_DIM.
`name`
: New dimension name.
## Errors
NF90\_RENAME\_DIM returns the value NF90\_NOERR if no errors occurred.
Otherwise, the returned status indicates an error. Possible causes of
errors include:
- The new name is the name of another dimension.
- The dimension ID is invalid for the specified netCDF dataset.
- The specified netCDF ID does not refer to an open netCDF dataset.
- The new name is longer than the old name and the netCDF dataset is
not in define mode.
## Example
Here is an example using NF90\_RENAME\_DIM to rename the dimension lat
to latitude in an existing netCDF dataset named foo.nc:
~~~~~~.fortran
use netcdf
implicit none
integer :: ncid, status, LatDimID
...
status = nf90_open("foo.nc", nf90_write, ncid)
if (status /= nf90_noerr) call handle_err(status)
...
! Put in define mode so we can rename the dimension
status = nf90_redef(ncid)
if (status /= nf90_noerr) call handle_err(status)
! Get the dimension ID for "Lat"...
status = nf90_inq_dimid(ncid, "Lat", LatDimID)
if (status /= nf90_noerr) call handle_err(status)
! ... and change the name to "Latitude".
status = nf90_rename_dim(ncid, LatDimID, "Latitude")
if (status /= nf90_noerr) call handle_err(status)
! Leave define mode
status = nf90_enddef(ncid)
if (status /= nf90_noerr) call handle_err(status)
~~~~~~
|