16 Variables {#f90-variables} 2=========== 3 4[TOC] 5 66.1 Variables Introduction {#f90-variables-introduction} 7=========== 8 9Variables for a netCDF dataset are defined when the dataset is created, 10while the netCDF dataset is in define mode. Other variables may be added 11later by reentering define mode. A netCDF variable has a name, a type, 12and a shape, which are specified when it is defined. A variable may also 13have values, which are established later in data mode. 14 15Ordinarily, the name, type, and shape are fixed when the variable is 16first defined. The name may be changed, but the type and shape of a 17variable cannot be changed. However, a variable defined in terms of the 18unlimited dimension can grow without bound in that dimension. 19 20A netCDF variable in an open netCDF dataset is referred to by a small 21integer called a variable ID. 22 23Variable IDs reflect the order in which variables were defined within a 24netCDF dataset. Variable IDs are 1, 2, 3,..., in the order in which the 25variables were defined. A function is available for getting the variable 26ID from the variable name and vice-versa. 27 28Attributes (see [Attributes](#Attributes)) may be associated with a 29variable to specify such properties as units. 30 31Operations supported on variables are: 32 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 36 from its ID. 37- Put a data value into a variable, given variable ID, indices, 38 and value. 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 49 index mapping vector. 50- Rename a variable. 51 52 536.2 Language Types Corresponding to netCDF external data types {#f90-language-types-corresponding-to-netcdf-external-data-types} 54=========== 55 56The following table gives the netCDF external data types and the 57corresponding type constants for defining variables in the FORTRAN 58interface: 59 60Type | FORTRAN API Mnemonic | Bits 61-------| ----------------------| ------ 62byte | NF90_BYTE | 8 63char | NF90_CHAR | 8 64short | NF90_SHORT | 16 65int | NF90_INT | 32 66float | NF90_FLOAT | 32 67double | NF90_DOUBLE | 64 68 69 70The first column gives the netCDF external data type, which is the same 71as the CDL data type. The next column gives the corresponding Fortran 90 72parameter for use in netCDF functions (the parameters are defined in the 73netCDF Fortran 90 module netcdf.f90). The last column gives the number 74of bits used in the external representation of values of the 75corresponding type. 76 77Note that there are no netCDF types corresponding to 64-bit integers or 78to characters wider than 8 bits in the current version of the netCDF 79library. 80 81 826.3 Create a Variable: `NF90_DEF_VAR` {#f90-create-a-variable-nf90_def_var} 83=========== 84 85 86 87The function NF90\_DEF\_VAR adds a new variable to an open netCDF 88dataset in define mode. It returns (as an argument) a variable ID, given 89the netCDF ID, the variable name, the variable type, the number of 90dimensions, and a list of the dimension IDs. 91 92Optional arguments allow additional settings for variables in 93netCDF-4/HDF5 files. These parameters allow data compression and control 94of the layout of the data on disk for performance tuning. These 95parameters may also be used to set the chunk sizes to get chunked 96storage, or to set the contiguous flag to get contiguous storage. 97 98Variables that make use of one or more unlimited dimensions, 99compression, or checksums must use chunking. Such variables are created 100with default chunk sizes of 1 for each unlimited dimension and the 101dimension length for other dimensions, except that if the resulting 102chunks are too large, the default chunk sizes for non-record dimensions 103are reduced. 104 105All parameters after the varid are optional, and only supported if 106netCDF was built with netCDF-4 features enabled, and if the variable is 107in a netCDF-4/HDF5 file. 108 109 110 111## Usage 112 113 114~~~~.fortran 115 116 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 132 133 134 135~~~~ 136 137`ncid` 138 139: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE. 140 141`name` 142 143: Variable name. 144 145`xtype` 146 147: One of the set of predefined netCDF external data types. The type of 148 this parameter, is defined in the netCDF header file. 149 150 The valid netCDF external data types are NF90\_BYTE, NF90\_CHAR, 151 NF90\_SHORT, NF90\_INT, NF90\_FLOAT, and NF90\_DOUBLE. If the file 152 is a NetCDF-4/HDF5 file, the additional types NF90\_UBYTE, 153 NF90\_USHORT, NF90\_UINT, NF90\_INT64, NF90\_UINT64, and 154 NF90\_STRING may be used, as well as a user defined type ID. 155 156`dimids` 157 158: Scalar or vector of dimension IDs corresponding to the 159 variable dimensions. For example, a vector of 2 dimension IDs 160 specifies a 2-dimensional matrix. 161 162 If an integer is passed for this parameter, a 1-D variable 163 is created. 164 165 If this parameter is not passed (or is a 1D array of size zero) it 166 means the variable is a scalar with no dimensions. 167 168 For classic data model files, if the ID of the unlimited dimension 169 is included, it must be first. In expanded model netCDF4/HDF5 files, 170 there may be any number of unlimited dimensions, and they may be 171 used in any element of the dimids array. 172 173 This argument is optional, and if absent specifies a scalar with 174 no dimensions. 175 176`varid` 177 178: Returned variable ID. 179 180`storage` 181 182: If NF90\_CONTIGUOUS, then contiguous storage is used for 183 this variable. Variables that use deflation, shuffle filter, or 184 checksums, or that have one or more unlimited dimensions cannot use 185 contiguous storage. 186 187 If NF90\_CHUNKED, then chunked storage is used for this variable. 188 Chunk sizes may be specified with the chunksizes parameter. Default 189 sizes will be used if chunking is required and this function is 190 not called. 191 192 If NF90\_COMPACT, then compact storage is used for this variable. 193 Compact storage may only be used on fix-sized variables with a 194 total data size 64 MB or less. Compact datasets are stored with 195 the file metadata, and can be read very quickly on a large number 196 of parallel processors. 197 198 By default contiguous storage is used for fix-sized variables when 199 conpression, chunking, shuffle, and checksums are not used. 200 201`chunksizes` 202 203: An array of chunk number of elements. This array has the number of 204 elements along each dimension of the data chunk. The array must have 205 the one chunksize for each dimension in the variable. 206 207 The total size of a chunk must be less than 4 GiB. That is, the 208 product of all chunksizes and the size of the data (or the size of 209 nc\_vlen\_t for VLEN types) must be less than 4 GiB. (This is a very 210 large chunk size in any case.) 211 212 If not provided, but chunked data are needed, then default 213 chunksizes will be chosen. For more information see [{No value for 214 ‘n-man’}](netcdf.html#Chunking) in {No value for ‘n-man’}. 215 216`shuffle` 217 218: If non-zero, turn on the shuffle filter. 219 220`deflate_level` 221 222: If the deflate parameter is non-zero, set the deflate level to 223 this value. Must be between 1 and 9. 224 225`fletcher32` 226 227: Set to true to turn on fletcher32 checksums for this variable. 228 229`endianness` 230 231: Set to NF90\_ENDIAN\_LITTLE for little-endian format, 232 NF90\_ENDIAN\_BIG for big-endian format, and NF90\_ENDIAN\_NATIVE 233 (the default) for the native endianness of the platform. 234 235`cache_size` 236 237: The size of the per-variable cache in MegaBytes. 238 239`cache_nelems` 240 241: The number slots in the per-variable chunk cache (should be a prime 242 number larger than the number of chunks in the cache). 243 244`cache_preemption` 245 246: The preemtion value must be between 0 and 100 inclusive and 247 indicates how much chunks that have been fully read are favored 248 for preemption. A value of zero means fully read chunks are treated 249 no differently than other chunks (the preemption is strictly LRU) 250 while a value of 100 means fully read chunks are always preempted 251 before other chunks. 252 253 254 255## Return Codes 256 257NF90\_DEF\_VAR returns the value NF90\_NOERR if no errors occurred. 258Otherwise, the returned status indicates an error. 259 260- NF90\_EBADNAME The specified variable name is the name of another 261 existing variable. 262- NF90\_EBADTYPE The specified type is not a valid netCDF type. 263- NF90\_EMAXDIMS The specified number of dimensions is negative or 264 more than the constant NF90\_MAX\_VAR\_DIMS, the maximum number of 265 dimensions permitted for a netCDF variable. (Does not apply to 266 netCDF-4/HDF5 files unless they were created with the 267 CLASSIC\_MODE flag.) 268- NF90\_EBADDIM One or more of the dimension IDs in the list of 269 dimensions is not a valid dimension ID for the netCDF dataset. 270- NF90\_EMAXVARS The number of variables would exceed the constant 271 NF90\_MAX\_VARS, the maximum number of variables permitted in a 272 classic netCDF dataset. (Does not apply to netCDF-4/HDF5 files 273 unless they were created with the CLASSIC\_MODE flag.) 274- NF90\_BADID The specified netCDF ID does not refer to an open 275 netCDF dataset. 276- NF90\_ENOTNC4 NetCDF-4 operation attempted on a files that is not a 277 netCDF-4/HDF5 file. Only variables in NetCDF-4/HDF5 files may use 278 compression, chunking, and endianness control. 279- NF90\_ENOTVAR Can’t find this variable. 280- NF90\_EINVAL Invalid input. This may be because contiguous storage 281 is requested for a variable that has compression, checksums, 282 chunking, or one or more unlimited dimensions. 283- NF90\_ELATEDEF This variable has already been the subject of a 284 NF90\_ENDDEF call. Once enddef has been called, it is impossible to 285 set the chunking for a variable. (In netCDF-4/HDF5 files 286 NF90\_ENDDEF will be called automatically for any data read 287 or write.) 288- NF90\_ENOTINDEFINE Not in define mode. This is returned for netCDF 289 classic or 64-bit offset files, or for netCDF-4 files, when they 290 were been created with NF90\_STRICT\_NC3 flag. (see section 291 [NF90\_CREATE](#NF90_005fCREATE)). 292- NF90\_ESTRICTNC3 Trying to create a var some place other than the 293 root group in a netCDF file with NF90\_STRICT\_NC3 turned on. 294 295 296 297### Example 298 299Here is an example using NF90\_DEF\_VAR to create a variable named rh of 300type double with three dimensions, time, lat, and lon in a new netCDF 301dataset named foo.nc: 302 303 304 305~~~~.fortran 306 307 use netcdf 308 implicit none 309 integer :: status, ncid 310 integer :: LonDimId, LatDimId, TimeDimId 311 integer :: RhVarId 312 ... 313 status = nf90_create("foo.nc", nf90_NoClobber, ncid) 314 if(status /= nf90_NoErr) call handle_error(status) 315 ... 316 ! Define the dimensions 317 status = nf90_def_dim(ncid, "lat", 5, LatDimId) 318 if(status /= nf90_NoErr) call handle_error(status) 319 status = nf90_def_dim(ncid, "lon", 10, LonDimId) 320 if(status /= nf90_NoErr) call handle_error(status) 321 status = nf90_def_dim(ncid, "time", nf90_unlimited, TimeDimId) 322 if(status /= nf90_NoErr) call handle_error(status) 323 ... 324 ! Define the variable 325 status = nf90_def_var(ncid, "rh", nf90_double, & 326 (/ LonDimId, LatDimID, TimeDimID /), RhVarId) 327 if(status /= nf90_NoErr) call handle_error(status) 328 329 330~~~~ 331 332 333In the following example, from nf\_test/f90tst\_vars2.f90, chunking, 334checksums, and endianness control are all used in a netCDF-4/HDF5 file. 335 336 337~~~~.fortran 338 339 340 ! Create the netCDF file. 341 call check(nf90_create(FILE_NAME, nf90_netcdf4, ncid, cache_nelems = CACHE_NELEMS, & 342 cache_size = CACHE_SIZE)) 343 344 ! Define the dimensions. 345 call check(nf90_def_dim(ncid, "x", NX, x_dimid)) 346 call check(nf90_def_dim(ncid, "y", NY, y_dimid)) 347 dimids = (/ y_dimid, x_dimid /) 348 349 ! Define some variables. 350 chunksizes = (/ NY, NX /) 351 call check(nf90_def_var(ncid, VAR1_NAME, NF90_INT, dimids, varid1, chunksizes = chunksizes, & 352 shuffle = .TRUE., fletcher32 = .TRUE., endianness = nf90_endian_big, deflate_level = DEFLATE_LEVEL)) 353 call check(nf90_def_var(ncid, VAR2_NAME, NF90_INT, dimids, varid2, contiguous = .TRUE.)) 354 call check(nf90_def_var(ncid, VAR3_NAME, NF90_INT64, varid3)) 355 call check(nf90_def_var(ncid, VAR4_NAME, NF90_INT, x_dimid, varid4, contiguous = .TRUE.)) 356 357 358~~~~ 359 360 3616.4 Define Fill Parameters for a Variable: `nf90_def_var_fill` {#f90-define-fill-parameters-for-a-variable-nf90_def_var_fill} 362=========== 363 364 365 366The function NF90\_DEF\_VAR\_FILL sets the fill parameters for a 367variable in a netCDF-4 file. 368 369This function must be called after the variable is defined, but before 370NF90\_ENDDEF is called. 371 372 373 374## Usage 375 376 377 378~~~~.fortran 379 380NF90_DEF_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE); 381 382~~~~ 383 384 385 386`NCID` 387 388: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE. 389 390`VARID` 391 392: Variable ID. 393 394`NO_FILL` 395 396: Set to non-zero value to set no\_fill mode on a variable. When this 397 mode is on, fill values will not be written for the variable. This 398 is helpful in high performance applications. For netCDF-4/HDF5 files 399 (whether classic model or not), this may only be changed after the 400 variable is defined, but before it is committed to disk (i.e. before 401 the first NF90\_ENDDEF after the NF90\_DEF\_VAR.) For classic and 402 64-bit offset file, the no\_fill mode may be turned on and off at 403 any time. 404 405`FILL_VALUE` 406 407: A value which will be used as the fill value for the variable. Must 408 be the same type as the variable. This will be written to a 409 \_FillValue attribute, created for this purpose. If NULL, this 410 argument will be ignored. 411 412 413 414## Return Codes 415 416`NF90_NOERR` 417 418: No error. 419 420`NF90_BADID` 421 422: Bad ncid. 423 424`NF90_ENOTNC4` 425 426: Not a netCDF-4 file. 427 428`NF90_ENOTVAR` 429 430: Can’t find this variable. 431 432`NF90_ELATEDEF` 433 434: This variable has already been the subject of a NF90\_ENDDEF call. 435 In netCDF-4 files NF90\_ENDDEF will be called automatically for any 436 data read or write. Once enddef has been called, it is impossible to 437 set the fill for a variable. 438 439`NF90_ENOTINDEFINE` 440 441: Not in define mode. This is returned for netCDF classic or 64-bit 442 offset files, or for netCDF-4 files, when they were been created 443 with NF90\_STRICT\_NC3 flag. (see section 444 [NF90\_CREATE](#NF90_005fCREATE)). 445 446`NF90_EPERM` 447 448: Attempt to create object in read-only file. 449 450 451 452## Example 453 454 4556.5 Learn About Fill Parameters for a Variable: `NF90_INQ_VAR_FILL` {#f90-learn-about-fill-parameters-for-a-variable-nf90_inq_var_fill} 456=========== 457 458 459 460The function NF90\_INQ\_VAR\_FILL returns the fill settings for a 461variable in a netCDF-4 file. 462 463 464 465## Usage 466 467 468 469~~~~.fortran 470 471NF90_INQ_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE) 472 473~~~~ 474 475 476 477`NCID` 478 479: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE. 480 481`VARID` 482 483: Variable ID. 484 485`NO_FILL` 486 487: An integer which will get a 1 if no\_fill mode is set for this 488 variable, and a zero if it is not set 489 490`FILL_VALUE` 491 492: This will get the fill value for this variable. This parameter will 493 be ignored if it is NULL. 494 495 496 497## Return Codes 498 499`NF90_NOERR` 500 501: No error. 502 503`NF90_BADID` 504 505: Bad ncid. 506 507`NF90_ENOTNC4` 508 509: Not a netCDF-4 file. 510 511`NF90_ENOTVAR` 512 513: Can’t find this variable. 514 515 516 517## Example 518 5196.6 Define Filter Parameters for a Variable: `nf90_def_var_filter` {#f90-define-filter-parameters-for-a-variable-nf90_def_var_filter} 520=========== 521 522 523 524The function nf90\_def\_var\_filter sets the filter parameters for a 525variable in a netCDF-4 file. 526 527This function must be called after the variable is defined, but before 528nf90\_enddef is called. 529 530 531 532## Usage 533 534 535~~~~.fortran 536 537function nf90_def_var_filter(ncid, varid, filterid, nparams, params); 538 integer, intent(in) :: ncid, varid, filterid, nparams 539 integer, dimension(:), intent(in) :: params 540 541~~~~ 542 543 544`ncid` 545 546: NetCDF ID, from a previous call to nf90\_open or nf90\_create. 547 548`varid` 549 550: Variable ID. 551 552`filterid` 553 554: The HDFGroup assigned filter id (e.g. 307 for bzip2). 555 556`nparams` 557 558: The number of parameters for the filter 559 560`params` 561 562: A vector of parameters of size nparams. 563 564 565## Return Codes 566 567`NF90_NOERR` 568 569: No error. 570 571`NF90_BADID` 572 573: Bad ncid. 574 575`NF90_ENOTNC4` 576 577: Not a netCDF-4 file. 578 579`NF90_ENOTVAR` 580 581: Can’t find this variable. 582 583`NF90_ELATEDEF` 584 585: This variable has already been the subject of a NF90\_ENDDEF call. 586 In netCDF-4 files NF90\_ENDDEF will be called automatically for any 587 data read or write. Once enddef has been called, it is impossible to 588 set the fill for a variable. 589 590`NF90_ENOTINDEFINE` 591 592: Not in define mode. This is returned for netCDF classic or 64-bit 593 offset files, or for netCDF-4 files, when they were been created 594 with NF90\_STRICT\_NC3 flag. (see section 595 [NF90\_CREATE](#NF90_005fCREATE)). 596 597`NF90_EPERM` 598 599: Attempt to create object in read-only file. 600 601`NF90_EFILTER` 602 603: Invalid filter id or parameters 604 605 606## Example 607 6086.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} 609=========== 610 611 612The function nf90\_inq\_var\_filter gets the filter id and parameters for a 613variable in a netCDF-4 file. 614 615 616## Usage 617 618 619~~~~.fortran 620 621function nf90_inq_var_filter(ncid, varid, filterid, nparams, params); 622 integer, intent(in) :: ncid, varid, filterid, nparams 623 integer, intent(out) :: filterid, nparams 624 integer, dimension(:), intent(out) :: params 625 626~~~~ 627 628 629`ncid` 630 631: NetCDF ID, from a previous call to nf90\_open or nf90\_create. 632 633`varid` 634 635: Variable ID. 636 637`filterid` 638 639: Store the the HDFGroup assigned filter id 640 641`nparams` 642 643: Stor the number of parameters for the filter 644 645`params` 646 647: Store the vector of parameters of size nparams. 648 649## Return Codes 650 651`NF90_NOERR` 652 653: No error. 654 655`NF90_BADID` 656 657: Bad ncid. 658 659`NF90_ENOTNC4` 660 661: Not a netCDF-4 file. 662 663`NF90_ENOTVAR` 664 665: Can’t find this variable. 666 667`NF90_ELATEDEF` 668 669: This variable has already been the subject of a NF90\_ENDDEF call. 670 In netCDF-4 files NF90\_ENDDEF will be called automatically for any 671 data read or write. Once enddef has been called, it is impossible to 672 set the fill for a variable. 673 674`NF90_ENOTINDEFINE` 675 676: Not in define mode. This is returned for netCDF classic or 64-bit 677 offset files, or for netCDF-4 files, when they were been created 678 with NF90\_STRICT\_NC3 flag. (see section 679 [NF90\_CREATE](#NF90_005fCREATE)). 680 681`NF90_EPERM` 682 683: Attempt to create object in read-only file. 684 685`NF90_EFILTER` 686 687: Invalid filter id or parameters 688 689 690## Example 691 692 6936.8 Get Information about a Variable from Its ID: NF90_INQUIRE_VARIABLE {#f90-get-information-about-a-variable-from-its-id-nf90_inquire_variable} 694=========== 695 696NF90\_INQUIRE\_VARIABLE returns information about a netCDF variable 697given its ID. Information about a variable includes its name, type, 698number of dimensions, a list of dimension IDs describing the shape of 699the variable, and the number of variable attributes that have been 700assigned to the variable. 701 702All parameters after nAtts are optional, and only supported if netCDF 703was built with netCDF-4 features enabled, and if the variable is in a 704netCDF-4/HDF5 file. 705 706 707 708## Usage 709 710 711~~~~.fortran 712 713 714 function nf90_inquire_variable(ncid, varid, name, xtype, ndims, dimids, nAtts, & 715 contiguous, chunksizes, deflate_level, shuffle, fletcher32, endianness) 716 integer, intent(in) :: ncid, varid 717 character (len = *), optional, intent(out) :: name 718 integer, optional, intent(out) :: xtype, ndims 719 integer, dimension(:), optional, intent(out) :: dimids 720 integer, optional, intent(out) :: nAtts 721 logical, optional, intent(out) :: contiguous 722 integer, optional, dimension(:), intent(out) :: chunksizes 723 integer, optional, intent(out) :: deflate_level 724 logical, optional, intent(out) :: shuffle, fletcher32 725 integer, optional, intent(out) :: endianness 726 integer :: nf90_inquire_variable 727 728 729 730~~~~ 731 732`ncid` 733 734: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE. 735 736`varid` 737 738: Variable ID. 739 740`name` 741 742: Returned variable name. The caller must allocate space for the 743 returned name. The maximum possible length, in characters, of a 744 variable name is given by the predefined constant NF90\_MAX\_NAME. 745 746`xtype` 747 748: Returned variable type, one of the set of predefined netCDF external 749 data types. The valid netCDF external data types are NF90\_BYTE, 750 NF90\_CHAR, NF90\_SHORT, NF90\_INT, NF90\_FLOAT, AND NF90\_DOUBLE. 751 752`ndims` 753 754: Returned number of dimensions the variable was defined as using. For 755 example, 2 indicates a matrix, 1 indicates a vector, and 0 means the 756 variable is a scalar with no dimensions. 757 758`dimids` 759 760: Returned vector of \*ndimsp dimension IDs corresponding to the 761 variable dimensions. The caller must allocate enough space for a 762 vector of at least \*ndimsp integers to be returned. The maximum 763 possible number of dimensions for a variable is given by the 764 predefined constant NF90\_MAX\_VAR\_DIMS. 765 766`natts` 767 768: Returned number of variable attributes assigned to this variable. 769 770`contiguous` 771 772: On return, set to NF90\_CONTIGUOUS if this variable uses contiguous 773 storage, NF90\_CHUNKED if it uses chunked storage. 774 775`chunksizes` 776 777: An array of chunk sizes. The array must have the one element for 778 each dimension in the variable. 779 780`shuffle` 781 782: True if the shuffle filter is turned on for this variable. 783 784`deflate_level` 785 786: The deflate\_level from 0 to 9. A value of zero indicates no 787 deflation is in use. 788 789`fletcher32` 790 791: Set to true if the fletcher32 checksum filter is turned on for 792 this variable. 793 794`endianness` 795 796: Will be set to NF90\_ENDIAN\_LITTLE if this variable is stored in 797 little-endian format, NF90\_ENDIAN\_BIG if it is stored in 798 big-endian format, and NF90\_ENDIAN\_NATIVE if the endianness is not 799 set, and the variable is not created yet. 800 801These functions return the value NF90\_NOERR if no errors occurred. 802Otherwise, the returned status indicates an error. Possible causes of 803errors include: 804 805- The variable ID is invalid for the specified netCDF dataset. 806- The specified netCDF ID does not refer to an open netCDF dataset. 807 808 809 810## Example 811 812Here is an example using NF90\_INQ\_VAR to find out about a variable 813named rh in an existing netCDF dataset named foo.nc: 814 815 816~~~~.fortran 817 818 819 use netcdf 820 implicit none 821 integer :: status, ncid, & 822 RhVarId & 823 numDims, numAtts 824 integer, dimension(nf90_max_var_dims) :: rhDimIds 825 ... 826 status = nf90_open("foo.nc", nf90_NoWrite, ncid) 827 if(status /= nf90_NoErr) call handle_error(status) 828 ... 829 status = nf90_inq_varid(ncid, "rh", RhVarId) 830 if(status /= nf90_NoErr) call handle_err(status) 831 status = nf90_inquire_variable(ncid, RhVarId, ndims = numDims, natts = numAtts) 832 if(status /= nf90_NoErr) call handle_err(status) 833 status = nf90_inquire_variable(ncid, RhVarId, dimids = rhDimIds(:numDims)) 834 if(status /= nf90_NoErr) call handle_err(status) 835 836 837~~~~ 838 839 8406.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} 841=========== 842 843 844 845Given the name of a varaible, nf90\_inq\_varid finds the variable ID. 846 847 848 849## Usage 850 851 852~~~~.fortran 853 854 855 function nf90_inq_varid(ncid, name, varid) 856 integer, intent(in) :: ncid 857 character (len = *), intent( in) :: name 858 integer, intent(out) :: varid 859 integer :: nf90_inq_varid 860 861 862~~~~ 863 864 865`ncid` 866 867: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE. 868 869`name` 870 871: The variable name. The maximum possible length, in characters, of a 872 variable name is given by the predefined constant NF90\_MAX\_NAME. 873 874`varid` 875 876: Variable ID. 877 878These functions return the value NF90\_NOERR if no errors occurred. 879Otherwise, the returned status indicates an error. Possible causes of 880errors include: 881 882- Variable not found. 883- The specified netCDF ID does not refer to an open netCDF dataset. 884 885 886 887## Example 888 889Here is an example using NF90\_INQ\_VARID to find out about a variable 890named rh in an existing netCDF dataset named foo.nc: 891 892 893 894~~~~.fortran 895 896 use netcdf 897 implicit none 898 integer :: status, ncid, & 899 RhVarId & 900 numDims, numAtts 901 integer, dimension(nf90_max_var_dims) :: rhDimIds 902 ... 903 status = nf90_open("foo.nc", nf90_NoWrite, ncid) 904 if(status /= nf90_NoErr) call handle_error(status) 905 ... 906 status = nf90_inq_varid(ncid, "rh", RhVarId) 907 if(status /= nf90_NoErr) call handle_err(status) 908 status = nf90_inquire_variable(ncid, RhVarId, ndims = numDims, natts = numAtts) 909 if(status /= nf90_NoErr) call handle_err(status) 910 status = nf90_inquire_variable(ncid, RhVarId, dimids = rhDimIds(:numDims)) 911 if(status /= nf90_NoErr) call handle_err(status) 912 913 914 915~~~~ 916 917 9186.10 Writing Data Values: NF90_PUT_VAR {#f90-writing-data-values-nf90_put_var} 919=========== 920 921 922 923The function NF90\_PUT\_VAR puts one or more data values into the 924variable of an open netCDF dataset that is in data mode. Required inputs 925are the netCDF ID, the variable ID, and one or more data values. 926Optional inputs may indicate the starting position of the data values in 927the netCDF variable (argument start), the sampling frequency with which 928data values are written into the netCDF variable (argument stride), and 929a mapping between the dimensions of the data array and the netCDF 930variable (argument map). The values to be written are associated with 931the netCDF variable by assuming that the first dimension of the netCDF 932variable varies fastest in the Fortran 90 interface. Data values are 933converted to the external type of the variable, if necessary. 934 935Take care when using the simplest forms of this interface with record 936variables (variables that use the NF90\_UNLIMITED dimension) when you 937don’t specify how many records are to be written. If you try to write 938all the values of a record variable into a netCDF file that has no 939record data yet (hence has 0 records), nothing will be written. 940Similarly, if you try to write all the values of a record variable from 941an array but there are more records in the file than you assume, more 942in-memory data will be accessed than you expect, which may cause a 943segmentation violation. To avoid such problems, it is better to specify 944start and count arguments for variables that use the NF90\_UNLIMITED 945dimension. 946 947 948 949### Usage 950 951 952 953~~~~.fortran 954 955 function nf90_put_var(ncid, varid, values, start, count, stride, map) 956 integer, intent( in) :: ncid, varid 957 any valid type, scalar or array of any rank, & 958 intent( in) :: values 959 integer, dimension(:), optional, intent( in) :: start, count, stride, map 960 integer :: nf90_put_var 961 962 963~~~~ 964 965 966`ncid` 967 968: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE. 969 970`varid` 971 972: Variable ID. 973 974`values` 975 976: The data value(s) to be written. The data may be of any type, and 977 may be a scalar or an array of any rank. You cannot put CHARACTER 978 data into a numeric variable or numeric data into a text variable. 979 For numeric data, if the type of data differs from the netCDF 980 variable type, type conversion will occur. See [Type 981 Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide. 982 983`start` 984 985: A vector of integers specifying the index in the variable where the 986 first (or only) of the data values will be written. The indices are 987 relative to 1, so for example, the first data value of a variable 988 would have index (1, 1, ..., 1). The elements of start correspond, 989 in order, to the variable’s dimensions. Hence, if the variable is a 990 record variable, the last index would correspond to the starting 991 record number for writing the data values. 992 993 By default, start(:) = 1. 994 995`count` 996 997: A vector of integers specifying the number of indices selected along 998 each dimension. To write a single value, for example, specify count 999 as (1, 1, ..., 1). The elements of count correspond, in order, to 1000 the variable’s dimensions. Hence, if the variable is a record 1001 variable, the last element of count corresponds to a count of the 1002 number of records to write. 1003 1004 By default, count(:numDims) = shape(values) and count(numDims + 1:) 1005 = 1, where numDims = size(shape(values)). 1006 1007`stride` 1008 1009: A vector of integers that specifies the sampling interval along each 1010 dimension of the netCDF variable. The elements of the stride vector 1011 correspond, in order, to the netCDF variable’s dimensions (stride(1) 1012 gives the sampling interval along the most rapidly varying dimension 1013 of the netCDF variable). Sampling intervals are specified in 1014 type-independent units of elements (a value of 1 selects consecutive 1015 elements of the netCDF variable along the corresponding dimension, a 1016 value of 2 selects every other element, etc.). 1017 1018 By default, stride(:) = 1. 1019 1020`imap` 1021 1022: A vector of integers that specifies the mapping between the 1023 dimensions of a netCDF variable and the in-memory structure of the 1024 internal data array. The elements of the index mapping vector 1025 correspond, in order, to the netCDF variable’s dimensions (map(1) 1026 gives the distance between elements of the internal array 1027 corresponding to the most rapidly varying dimension of the 1028 netCDF variable). Distances between elements are specified in units 1029 of elements. 1030 1031 By default, edgeLengths = shape(values), and map = (/ 1, 1032 (product(edgeLengths(:i)), i = 1, size(edgeLengths) - 1) /), that 1033 is, there is no mapping. 1034 1035 Use of Fortran 90 intrinsic functions (including reshape, transpose, 1036 and spread) may let you avoid using this argument. 1037 1038 1039 1040## Errors 1041 1042NF90\_PUT\_VAR1\_ type returns the value NF90\_NOERR if no errors 1043occurred. Otherwise, the returned status indicates an error. Possible 1044causes of errors include: 1045 1046- The variable ID is invalid for the specified netCDF dataset. 1047- The specified indices were out of range for the rank of the 1048 specified variable. For example, a negative index or an index that 1049 is larger than the corresponding dimension length will cause 1050 an error. 1051- The specified value is out of the range of values representable by 1052 the external data type of the variable. 1053- The specified netCDF is in define mode rather than data mode. 1054- The specified netCDF ID does not refer to an open netCDF dataset. 1055 1056 1057 1058## Example 1059 1060Here is an example using NF90\_PUT\_VAR to set the (4,3,2) element of 1061the variable named rh to 0.5 in an existing netCDF dataset named foo.nc. 1062For simplicity in this example, we assume that we know that rh is 1063dimensioned with lon, lat, and time, so we want to set the value of rh 1064that corresponds to the fourth lon value, the third lat value, and the 1065second time value: 1066 1067 1068 1069~~~~.fortran 1070 1071 use netcdf 1072 implicit none 1073 integer :: ncId, rhVarId, status 1074 ... 1075 status = nf90_open("foo.nc", nf90_Write, ncid) 1076 if(status /= nf90_NoErr) call handle_err(status) 1077 ... 1078 status = nf90_inq_varid(ncid, "rh", rhVarId) 1079 if(status /= nf90_NoErr) call handle_err(status) 1080 status = nf90_put_var(ncid, rhVarId, 0.5, start = (/ 4, 3, 2 /) ) 1081 if(status /= nf90_NoErr) call handle_err(status) 1082 1083 1084~~~~ 1085 1086 1087In this example we use NF90\_PUT\_VAR to add or change all the values of 1088the variable named rh to 0.5 in an existing netCDF dataset named foo.nc. 1089We assume that we know that rh is dimensioned with lon, lat, and time. 1090In this example we query the netCDF file to discover the lengths of the 1091dimensions, then use the Fortran 90 intrinsic function reshape to create 1092a temporary array of data values which is the same shape as the netCDF 1093variable. 1094 1095 1096~~~~.fortran 1097 1098 1099 use netcdf 1100 implicit none 1101 integer :: ncId, rhVarId,status, & 1102 lonDimID, latDimId, timeDimId, & 1103 numLons, numLats, numTimes, & 1104 i 1105 integer, dimension(nf90_max_var_dims) :: dimIDs 1106 ... 1107 status = nf90_open("foo.nc", nf90_Write, ncid) 1108 if(status /= nf90_NoErr) call handle_err(status) 1109 ... 1110 status = nf90_inq_varid(ncid, "rh", rhVarId) 1111 if(status /= nf90_NoErr) call handle_err(status) 1112 ! How big is the netCDF variable, that is, what are the lengths of 1113 ! its constituent dimensions? 1114 status = nf90_inquire_variable(ncid, rhVarId, dimids = dimIDs) 1115 if(status /= nf90_NoErr) call handle_err(status) 1116 status = nf90_inquire_dimension(ncid, dimIDs(1), len = numLons) 1117 if(status /= nf90_NoErr) call handle_err(status) 1118 status = nf90_inquire_dimension(ncid, dimIDs(2), len = numLats) 1119 if(status /= nf90_NoErr) call handle_err(status) 1120 status = nf90_inquire_dimension(ncid, dimIDs(3), len = numTimes) 1121 if(status /= nf90_NoErr) call handle_err(status) 1122 ... 1123 ! Make a temporary array the same shape as the netCDF variable. 1124 status = nf90_put_var(ncid, rhVarId, & 1125 reshape( & 1126 (/ (0.5, i = 1, numLons * numLats * numTimes) /) , & 1127 shape = (/ numLons, numLats, numTimes /) ) 1128 if(status /= nf90_NoErr) call handle_err(status) 1129 1130 1131~~~~ 1132 1133 1134Here is an example using NF90\_PUT\_VAR to add or change a section of 1135the variable named rh to 0.5 in an existing netCDF dataset named foo.nc. 1136For simplicity in this example, we assume that we know that rh is 1137dimensioned with lon, lat, and time, that there are ten lon values, five 1138lat values, and three time values, and that we want to replace all the 1139values at the last time. 1140 1141 1142 1143~~~~.fortran 1144 1145 use netcdf 1146 implicit none 1147 integer :: ncId, rhVarId, status 1148 integer, parameter :: numLons = 10, numLats = 5, numTimes = 3 1149 real, dimension(numLons, numLats) & 1150 :: rhValues 1151 ... 1152 status = nf90_open("foo.nc", nf90_Write, ncid) 1153 if(status /= nf90_NoErr) call handle_err(status) 1154 ... 1155 status = nf90_inq_varid(ncid, "rh", rhVarId) 1156 if(status /= nf90_NoErr) call handle_err(status) 1157 ! Fill in all values at the last time 1158 rhValues(:, :) = 0.5 1159 status = nf90_put_var(ncid, rhVarId,rhvalues, & 1160 start = (/ 1, 1, numTimes /), & 1161 count = (/ numLats, numLons, 1 /)) 1162 if(status /= nf90_NoErr) call handle_err(status) 1163 1164 1165~~~~ 1166 1167 1168Here is an example of using NF90\_PUT\_VAR to write every other point of 1169a netCDF variable named rh having dimensions (6, 4). 1170 1171 1172 1173~~~~.fortran 1174 1175 use netcdf 1176 implicit none 1177 integer :: ncId, rhVarId, status 1178 integer, parameter :: numLons = 6, numLats = 4 1179 real, dimension(numLons, numLats) & 1180 :: rhValues = 0.5 1181 ... 1182 status = nf90_open("foo.nc", nf90_Write, ncid) 1183 if(status /= nf90_NoErr) call handle_err(status) 1184 ... 1185 status = nf90_inq_varid(ncid, "rh", rhVarId) 1186 if(status /= nf90_NoErr) call handle_err(status) 1187 ... 1188 ! Fill in every other value using an array section 1189 status = nf90_put_var(ncid, rhVarId, rhValues(::2, ::2), & 1190 stride = (/ 2, 2 /)) 1191 if(status /= nf90_NoErr) call handle_err(status) 1192 1193 1194~~~~ 1195 1196 1197The following map vector shows the default mapping between a 2x3x4 1198netCDF variable and an internal array of the same shape: 1199 1200 1201~~~~.fortran 1202 1203 1204 real, dimension(2, 3, 4):: a ! same shape as netCDF variable 1205 integer, dimension(3) :: map = (/ 1, 2, 6 /) 1206 ! netCDF dimension inter-element distance 1207 ! ---------------- ---------------------- 1208 ! most rapidly varying 1 1209 ! intermediate 2 (= map(1)*2) 1210 ! most slowly varying 6 (= map(2)*3) 1211 1212 1213~~~~ 1214 1215 1216Using the map vector above obtains the same result as simply not passing 1217a map vector at all. 1218 1219Here is an example of using nf90\_put\_var to write a netCDF variable 1220named rh whose dimensions are the transpose of the Fortran 90 array: 1221 1222 1223~~~~.fortran 1224 1225 1226 use netcdf 1227 implicit none 1228 integer :: ncId, rhVarId, status 1229 integer, parameter :: numLons = 6, numLats = 4 1230 real, dimension(numLons, numLats) :: rhValues 1231 ! netCDF variable has dimensions (numLats, numLons) 1232 ... 1233 status = nf90_open("foo.nc", nf90_Write, ncid) 1234 if(status /= nf90_NoErr) call handle_err(status) 1235 ... 1236 status = nf90_inq_varid(ncid, "rh", rhVarId) 1237 if(status /= nf90_NoErr) call handle_err(status) 1238 ... 1239 !Write transposed values: map vector would be (/ 1, numLats /) for 1240 ! no transposition 1241 status = nf90_put_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /)) 1242 if(status /= nf90_NoErr) call handle_err(status) 1243 1244 1245~~~~ 1246 1247 1248The same effect can be obtained more simply using Fortran 90 intrinsic 1249functions: 1250 1251 1252 1253~~~~.fortran 1254 1255 use netcdf 1256 implicit none 1257 integer :: ncId, rhVarId, status 1258 integer, parameter :: numLons = 6, numLats = 4 1259 real, dimension(numLons, numLats) :: rhValues 1260 ! netCDF variable has dimensions (numLats, numLons) 1261 ... 1262 status = nf90_open("foo.nc", nf90_Write, ncid) 1263 if(status /= nf90_NoErr) call handle_err(status) 1264 ... 1265 status = nf90_inq_varid(ncid, "rh", rhVarId) 1266 if(status /= nf90_NoErr) call handle_err(status) 1267 ... 1268 status = nf90_put_var(ncid, rhVarId, transpose(rhValues)) 1269 if(status /= nf90_NoErr) call handle_err(status) 1270 1271 1272~~~~ 1273 1274 1275 12766.11 Reading Data Values: NF90_GET_VAR {#f90-reading-data-values-nf90_get_var} 1277=========== 1278 1279 1280 1281The function NF90\_GET\_VAR gets one or more data values from a netCDF 1282variable of an open netCDF dataset that is in data mode. Required inputs 1283are the netCDF ID, the variable ID, and a specification for the data 1284values into which the data will be read. Optional inputs may indicate 1285the starting position of the data values in the netCDF variable 1286(argument start), the sampling frequency with which data values are read 1287from the netCDF variable (argument stride), and a mapping between the 1288dimensions of the data array and the netCDF variable (argument map). The 1289values to be read are associated with the netCDF variable by assuming 1290that the first dimension of the netCDF variable varies fastest in the 1291Fortran 90 interface. Data values are converted from the external type 1292of the variable, if necessary. 1293 1294Take care when using the simplest forms of this interface with record 1295variables (variables that use the NF90\_UNLIMITED dimension) when you 1296don’t specify how many records are to be read. If you try to read all 1297the values of a record variable into an array but there are more records 1298in the file than you assume, more data will be read than you expect, 1299which may cause a segmentation violation. To avoid such problems, it is 1300better to specify the optional start and count arguments for variables 1301that use the NF90\_UNLIMITED dimension. 1302 1303In netCDF classic model the maximum integer size is NF90\_INT, the 13044-byte signed integer. Reading variables into an eight-byte integer 1305array from a classic model file will read from an NF90\_INT. Reading 1306variables into an eight-byte integer in a netCDF-4/HDF5 (without classic 1307model flag) will read from an NF90\_INT64 1308 1309 1310 1311## Usage 1312 1313 1314 1315~~~~.fortran 1316 1317 function nf90_get_var(ncid, varid, values, start, count, stride, map) 1318 integer, intent( in) :: ncid, varid 1319 any valid type, scalar or array of any rank, & 1320 intent(out) :: values 1321 integer, dimension(:), optional, intent( in) :: start, count, stride, map 1322 integer :: nf90_get_var 1323 1324 1325~~~~ 1326 1327 1328`ncid` 1329 1330: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE. 1331 1332`varid` 1333 1334: Variable ID. 1335 1336`values` 1337 1338: The data value(s) to be read. The data may be of any type, and may 1339 be a scalar or an array of any rank. You cannot read CHARACTER data 1340 from a numeric variable or numeric data from a text variable. For 1341 numeric data, if the type of data differs from the netCDF variable 1342 type, type conversion will occur. See [Type 1343 Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide. 1344 1345`start` 1346 1347: A vector of integers specifying the index in the variable from which 1348 the first (or only) of the data values will be read. The indices are 1349 relative to 1, so for example, the first data value of a variable 1350 would have index (1, 1, ..., 1). The elements of start correspond, 1351 in order, to the variable’s dimensions. Hence, if the variable is a 1352 record variable, the last index would correspond to the starting 1353 record number for writing the data values. 1354 1355 By default, start(:) = 1. 1356 1357`count` 1358 1359: A vector of integers specifying the number of indices selected along 1360 each dimension. To read a single value, for example, specify count 1361 as (1, 1, ..., 1). The elements of count correspond, in order, to 1362 the variable’s dimensions. Hence, if the variable is a record 1363 variable, the last element of count corresponds to a count of the 1364 number of records to read. 1365 1366 By default, count(:numDims) = shape(values) and count(numDims + 1:) 1367 = 1, where numDims = size(shape(values)). 1368 1369`stride` 1370 1371: A vector of integers that specifies the sampling interval along each 1372 dimension of the netCDF variable. The elements of the stride vector 1373 correspond, in order, to the netCDF variable’s dimensions (stride(1) 1374 gives the sampling interval along the most rapidly varying dimension 1375 of the netCDF variable). Sampling intervals are specified in 1376 type-independent units of elements (a value of 1 selects consecutive 1377 elements of the netCDF variable along the corresponding dimension, a 1378 value of 2 selects every other element, etc.). 1379 1380 By default, stride(:) = 1. 1381 1382`map` 1383 1384: A vector of integers that specifies the mapping between the 1385 dimensions of a netCDF variable and the in-memory structure of the 1386 internal data array. The elements of the index mapping vector 1387 correspond, in order, to the netCDF variable’s dimensions (map(1) 1388 gives the distance between elements of the internal array 1389 corresponding to the most rapidly varying dimension of the 1390 netCDF variable). Distances between elements are specified in units 1391 of elements. 1392 1393 By default, edgeLengths = shape(values), and map = (/ 1, 1394 (product(edgeLengths(:i)), i = 1, size(edgeLengths) - 1) /), that 1395 is, there is no mapping. 1396 1397 Use of Fortran 90 intrinsic functions (including reshape, transpose, 1398 and spread) may let you avoid using this argument. 1399 1400 1401 1402## Errors 1403 1404NF90\_GET\_VAR returns the value NF90\_NOERR if no errors occurred. 1405Otherwise, the returned status indicates an error. Possible causes of 1406errors include: 1407 1408- The variable ID is invalid for the specified netCDF dataset. 1409- The assumed or specified start, count, and stride generate an index 1410 which is out of range. Note that no error checking is possible on 1411 the map vector. 1412- One or more of the specified values are out of the range of values 1413 representable by the desired type. 1414- The specified netCDF is in define mode rather than data mode. 1415- The specified netCDF ID does not refer to an open netCDF dataset. 1416 1417(As noted above, another possible source of error is using this 1418interface to read all the values of a record variable without specifying 1419the number of records. If there are more records in the file than you 1420assume, more data will be read than you expect!) 1421 1422 1423 1424## Example 1425 1426Here is an example using NF90\_GET\_VAR to read the (4,3,2) element of 1427the variable named rh from an existing netCDF dataset named foo.nc. For 1428simplicity in this example, we assume that we know that rh is 1429dimensioned with lon, lat, and time, so we want to read the value of rh 1430that corresponds to the fourth lon value, the third lat value, and the 1431second time value: 1432 1433 1434 1435~~~~.fortran 1436 1437 use netcdf 1438 implicit none 1439 integer :: ncId, rhVarId, status 1440 real :: rhValue 1441 ... 1442 status = nf90_open("foo.nc", nf90_NoWrite, ncid) 1443 if(status /= nf90_NoErr) call handle_err(status) 1444 - 1445 status = nf90_inq_varid(ncid, "rh", rhVarId) 1446 if(status /= nf90_NoErr) call handle_err(status) 1447 status = nf90_get_var(ncid, rhVarId, rhValue, start = (/ 4, 3, 2 /) ) 1448 if(status /= nf90_NoErr) call handle_err(status) 1449 1450 1451~~~~ 1452 1453 1454In this example we use NF90\_GET\_VAR to read all the values of the 1455variable named rh from an existing netCDF dataset named foo.nc. We 1456assume that we know that rh is dimensioned with lon, lat, and time. In 1457this example we query the netCDF file to discover the lengths of the 1458dimensions, then allocate a Fortran 90 array the same shape as the 1459netCDF variable. 1460 1461 1462 1463 1464 use netcdf 1465 implicit none 1466 integer :: ncId, rhVarId, & 1467 lonDimID, latDimId, timeDimId, & 1468 numLons, numLats, numTimes, & 1469 status 1470 integer, dimension(nf90_max_var_dims) :: dimIDs 1471 real, dimension(:, :, :), allocatable :: rhValues 1472 ... 1473 status = nf90_open("foo.nc", nf90_NoWrite, ncid) 1474 if(status /= nf90_NoErr) call handle_err(status) 1475 ... 1476 status = nf90_inq_varid(ncid, "rh", rhVarId) 1477 if(status /= nf90_NoErr) call handle_err(status) 1478 ! How big is the netCDF variable, that is, what are the lengths of 1479 ! its constituent dimensions? 1480 status = nf90_inquire_variable(ncid, rhVarId, dimids = dimIDs) 1481 if(status /= nf90_NoErr) call handle_err(status) 1482 status = nf90_inquire_dimension(ncid, dimIDs(1), len = numLons) 1483 if(status /= nf90_NoErr) call handle_err(status) 1484 status = nf90_inquire_dimension(ncid, dimIDs(2), len = numLats) 1485 if(status /= nf90_NoErr) call handle_err(status) 1486 status = nf90_inquire_dimension(ncid, dimIDs(3), len = numTimes) 1487 if(status /= nf90_NoErr) call handle_err(status) 1488 allocate(rhValues(numLons, numLats, numTimes)) 1489 ... 1490 status = nf90_get_var(ncid, rhVarId, rhValues) 1491 if(status /= nf90_NoErr) call handle_err(status) 1492 1493 1494 1495 1496Here is an example using NF90\_GET\_VAR to read a section of the 1497variable named rh from an existing netCDF dataset named foo.nc. For 1498simplicity in this example, we assume that we know that rh is 1499dimensioned with lon, lat, and time, that there are ten lon values, five 1500lat values, and three time values, and that we want to replace all the 1501values at the last time. 1502 1503 1504~~~~.fortran 1505 1506 1507 use netcdf 1508 implicit none 1509 integer :: ncId, rhVarId, status 1510 integer, parameter :: numLons = 10, numLats = 5, numTimes = 3 1511 real, dimension(numLons, numLats, numTimes) & 1512 :: rhValues 1513 ... 1514 status = nf90_open("foo.nc", nf90_NoWrite, ncid) 1515 if(status /= nf90_NoErr) call handle_err(status) 1516 ... 1517 status = nf90_inq_varid(ncid, "rh", rhVarId) 1518 if(status /= nf90_NoErr) call handle_err(status) 1519 !Read the values at the last time by passing an array section 1520 status = nf90_get_var(ncid, rhVarId, rhValues(:, :, 3), & 1521 start = (/ 1, 1, numTimes /), & 1522 count = (/ numLons, numLats, 1 /)) 1523 if(status /= nf90_NoErr) call handle_err(status) 1524 1525 1526~~~~ 1527 1528 1529Here is an example of using NF90\_GET\_VAR to read every other point of 1530a netCDF variable named rh having dimensions (6, 4). 1531 1532 1533~~~~.fortran 1534 1535 1536 use netcdf 1537 implicit none 1538 integer :: ncId, rhVarId, status 1539 integer, parameter :: numLons = 6, numLats = 4 1540 real, dimension(numLons, numLats) & 1541 :: rhValues 1542 ... 1543 status = nf90_open("foo.nc", nf90_NoWrite, ncid) 1544 if(status /= nf90_NoErr) call handle_err(status) 1545 ... 1546 status = nf90_inq_varid(ncid, "rh", rhVarId) 1547 if(status /= nf90_NoErr) call handle_err(status) 1548 ... 1549 ! Read every other value into an array section 1550 status = nf90_get_var(ncid, rhVarId, rhValues(::2, ::2) & 1551 stride = (/ 2, 2 /)) 1552 if(status /= nf90_NoErr) call handle_err(status) 1553 1554 1555 1556~~~~ 1557 1558The following map vector shows the default mapping between a 2x3x4 1559netCDF variable and an internal array of the same shape: 1560 1561 1562~~~~.fortran 1563 1564 1565 real, dimension(2, 3, 4):: a ! same shape as netCDF variable 1566 integer, dimension(3) :: map = (/ 1, 2, 6 /) 1567 ! netCDF dimension inter-element distance 1568 ! ---------------- ---------------------- 1569 ! most rapidly varying 1 1570 ! intermediate 2 (= map(1)*2) 1571 ! most slowly varying 6 (= map(2)*3) 1572 1573 1574 1575 1576~~~~ 1577 1578Using the map vector above obtains the same result as simply not passing 1579a map vector at all. 1580 1581Here is an example of using nf90\_get\_var to read a netCDF variable 1582named rh whose dimensions are the transpose of the Fortran 90 array: 1583 1584 1585 1586~~~~.fortran 1587 1588 use netcdf 1589 implicit none 1590 integer :: ncId, rhVarId, status 1591 integer, parameter :: numLons = 6, numLats = 4 1592 real, dimension(numLons, numLats) :: rhValues 1593 ! netCDF variable has dimensions (numLats, numLons) 1594 ... 1595 status = nf90_open("foo.nc", nf90_NoWrite, ncid) 1596 if(status /= nf90_NoErr) call handle_err(status) 1597 ... 1598 status = nf90_inq_varid(ncid, "rh", rhVarId) 1599 if(status /= nf90_NoErr) call handle_err(status) 1600 ... 1601 ! Read transposed values: map vector would be (/ 1, numLats /) for 1602 ! no transposition 1603 status = nf90_get_var(ncid, rhVarId,rhValues, map = (/ numLons, 1 /)) 1604 if(status /= nf90_NoErr) call handle_err(status) 1605 1606 1607~~~~ 1608 1609 1610The same effect can be obtained more simply, though using more memory, 1611using Fortran 90 intrinsic functions: 1612 1613 1614~~~~.fortran 1615 1616 1617 use netcdf 1618 implicit none 1619 integer :: ncId, rhVarId, status 1620 integer, parameter :: numLons = 6, numLats = 4 1621 real, dimension(numLons, numLats) :: rhValues 1622 ! netCDF variable has dimensions (numLats, numLons) 1623 real, dimension(numLons, numLats) :: tempValues 1624 ... 1625 status = nf90_open("foo.nc", nf90_NoWrite, ncid) 1626 if(status /= nf90_NoErr) call handle_err(status) 1627 ... 1628 status = nf90_inq_varid(ncid, "rh", rhVarId) 1629 if(status /= nf90_NoErr) call handle_err(status) 1630 ... 1631 status = nf90_get_var(ncid, rhVarId, tempValues)) 1632 if(status /= nf90_NoErr) call handle_err(status) 1633 rhValues(:, :) = transpose(tempValues) 1634 1635 1636~~~~ 1637 1638 1639 1640 16416.12 Reading and Writing Character String Values {#f90-reading-and-writing-character-string-values} 1642=========== 1643 1644Character strings are not a primitive netCDF external data type under 1645the classic netCDF data model, in part because FORTRAN does not support 1646the abstraction of variable-length character strings (the FORTRAN LEN 1647function returns the static length of a character string, not its 1648dynamic length). As a result, a character string cannot be written or 1649read as a single object in the netCDF interface. Instead, a character 1650string must be treated as an array of characters, and array access must 1651be used to read and write character strings as variable data in netCDF 1652datasets. Furthermore, variable-length strings are not supported by the 1653netCDF classic interface except by convention; for example, you may 1654treat a zero byte as terminating a character string, but you must 1655explicitly specify the length of strings to be read from and written to 1656netCDF variables. 1657 1658Character strings as attribute values are easier to use, since the 1659strings are treated as a single unit for access. However, the value of a 1660character-string attribute in the classic netCDF interface is still an 1661array of characters with an explicit length that must be specified when 1662the attribute is defined. 1663 1664When you define a variable that will have character-string values, use a 1665character-position dimension as the most quickly varying dimension for 1666the variable (the first dimension for the variable in Fortran 90). The 1667length of the character-position dimension will be the maximum string 1668length of any value to be stored in the character-string variable. Space 1669for maximum-length strings will be allocated in the disk representation 1670of character-string variables whether you use the space or not. If two 1671or more variables have the same maximum length, the same 1672character-position dimension may be used in defining the variable 1673shapes. 1674 1675To write a character-string value into a character-string variable, use 1676either entire variable access or array access. The latter requires that 1677you specify both a corner and a vector of edge lengths. The 1678character-position dimension at the corner should be one for Fortran 90. 1679If the length of the string to be written is n, then the vector of edge 1680lengths will specify n in the character-position dimension, and one for 1681all the other dimensions: (n, 1, 1, ..., 1). 1682 1683In Fortran 90, fixed-length strings may be written to a netCDF dataset 1684without a terminating character, to save space. Variable-length strings 1685should follow the C convention of writing strings with a terminating 1686zero byte so that the intended length of the string can be determined 1687when it is later read by either C or Fortran 90 programs. It is the 1688users responsibility to provide such null termination. 1689 1690If you are writing data in the default prefill mode (see next section), 1691you can ensure that simple strings represented as 1-dimensional 1692character arrays are null terminated in the netCDF file by writing fewer 1693characters than the length declared when the variable was defined. That 1694way, the extra unwritten characters will be filled with the default 1695character fill value, which is a null byte. The Fortran intrinsic TRIM 1696function can be used to trim trailing blanks from the character string 1697argument to NF90\_PUT\_VAR to make the argument shorter than the 1698declared length. If prefill is not on, the data writer must explicitly 1699provide a null terminating byte. 1700 1701Here is an example illustrating this way of writing strings to character 1702array variables: 1703 1704 1705 1706~~~~.fortran 1707 1708 use netcdf 1709 implicit none 1710 integer status 1711 integer :: ncid, oceanStrLenID, oceanId 1712 integer, parameter :: MaxOceanNameLen = 20 1713 character, (len = MaxOceanNameLen):: ocean 1714 ... 1715 status = nf90_create("foo.nc", nf90_NoClobber, ncid) 1716 if(status /= nf90_NoErr) call handle_err(status) 1717 ... 1718 status = nf90_def_dim(ncid, "oceanStrLen", MaxOceanNameLen, oceanStrLenId) 1719 if(status /= nf90_NoErr) call handle_err(status) 1720 ... 1721 status = nf90_def_var(ncid, "ocean", nf90_char, (/ oceanStrLenId /), oceanId) 1722 if(status /= nf90_NoErr) call handle_err(status) 1723 ... 1724 ! Leave define mode, which prefills netCDF variables with fill values 1725 status = nf90_enddef(ncid) 1726 if (status /= nf90_noerr) call handle_err(status) 1727 ... 1728 ! Note that this assignment adds blank fill 1729 ocean = "Pacific" 1730 ! Using trim removes trailing blanks, prefill provides null 1731 ! termination, so C programs can later get intended string. 1732 status = nf90_put_var(ncid, oceanId, trim(ocean)) 1733 if(status /= nf90_NoErr) call handle_err(status) 1734 1735 1736~~~~ 1737 1738 17396.13 Fill Values {#f90-fill-values} 1740=========== 1741 1742What happens when you try to read a value that was never written in an 1743open netCDF dataset? You might expect that this should always be an 1744error, and that you should get an error message or an error status 1745returned. You do get an error if you try to read data from a netCDF 1746dataset that is not open for reading, if the variable ID is invalid for 1747the specified netCDF dataset, or if the specified indices are not 1748properly within the range defined by the dimension lengths of the 1749specified variable. Otherwise, reading a value that was not written 1750returns a special fill value used to fill in any undefined values when a 1751netCDF variable is first written. 1752 1753You may ignore fill values and use the entire range of a netCDF external 1754data type, but in this case you should make sure you write all data 1755values before reading them. If you know you will be writing all the data 1756before reading it, you can specify that no prefilling of variables with 1757fill values will occur by calling writing. This may provide a 1758significant performance gain for netCDF writes. 1759 1760The variable attribute \_FillValue may be used to specify the fill value 1761for a variable. There are default fill values for each type, defined in 1762module netcdf: NF90\_FILL\_CHAR, NF90\_FILL\_INT1 (same as 1763NF90\_FILL\_BYTE), NF90\_FILL\_INT2 (same as NF90\_FILL\_SHORT), 1764NF90\_FILL\_INT, NF90\_FILL\_REAL (same as NF90\_FILL\_FLOAT), and 1765NF90\_FILL\_DOUBLE 1766 1767The netCDF byte and character types have different default fill values. 1768The default fill value for characters is the zero byte, a useful value 1769for detecting the end of variable-length C character strings. If you 1770need a fill value for a byte variable, it is recommended that you 1771explicitly define an appropriate \_FillValue attribute, as generic 1772utilities such as ncdump will not assume a default fill value for byte 1773variables. 1774 1775Type conversion for fill values is identical to type conversion for 1776other values: attempting to convert a value from one type to another 1777type that can’t represent the value results in a range error. Such 1778errors may occur on writing or reading values from a larger type (such 1779as double) to a smaller type (such as float), if the fill value for the 1780larger type cannot be represented in the smaller type. 1781 1782 17836.14 NF90_RENAME_VAR {#f90-nf90_rename_var} 1784=========== 1785 1786 1787 1788The function NF90\_RENAME\_VAR changes the name of a netCDF variable in 1789an open netCDF dataset. If the new name is longer than the old name, the 1790netCDF dataset must be in define mode. You cannot rename a variable to 1791have the name of any existing variable. 1792 1793 1794 1795## Usage 1796 1797 1798 1799~~~~.fortran 1800 1801 function nf90_rename_var(ncid, varid, newname) 1802 integer, intent( in) :: ncid, varid 1803 character (len = *), intent( in) :: newname 1804 integer :: nf90_rename_var 1805 1806~~~~ 1807 1808 1809 1810`ncid` 1811 1812: NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE. 1813 1814`varid` 1815 1816: Variable ID. 1817 1818`newname` 1819 1820: New name for the specified variable. 1821 1822 1823 1824## Errors 1825 1826NF90\_RENAME\_VAR returns the value NF90\_NOERR if no errors occurred. 1827Otherwise, the returned status indicates an error. Possible causes of 1828errors include: 1829 1830- The new name is in use as the name of another variable. 1831- The variable ID is invalid for the specified netCDF dataset. 1832- The specified netCDF ID does not refer to an open netCDF dataset. 1833 1834 1835 1836## Example 1837 1838Here is an example using NF90\_RENAME\_VAR to rename the variable rh to 1839rel\_hum in an existing netCDF dataset named foo.nc: 1840 1841 1842~~~~.fortran 1843 1844 1845 use netcdf 1846 implicit none 1847 integer :: ncId, rhVarId, status 1848 ... 1849 status = nf90_open("foo.nc", nf90_Write, ncid) 1850 if(status /= nf90_NoErr) call handle_err(status) 1851 ... 1852 status = nf90_inq_varid(ncid, "rh", rhVarId) 1853 if(status /= nf90_NoErr) call handle_err(status) 1854 status = nf90_redef(ncid) ! Enter define mode to change variable name 1855 if(status /= nf90_NoErr) call handle_err(status) 1856 status = nf90_rename_var(ncid, rhVarId, "rel_hum") 1857 if(status /= nf90_NoErr) call handle_err(status) 1858 status = nf90_enddef(ncid) ! Leave define mode 1859 if(status /= nf90_NoErr) call handle_err(status) 1860 1861 1862 1863~~~~ 1864 1865 18666.15 Change between Collective and Independent Parallel Access: NF90_VAR_PAR_ACCESS {#f90-change-between-collective-and-independent-parallel-access-nf90_var_par_access} 1867=========== 1868 1869 1870 1871The function NF90\_VAR\_PAR\_ACCESS changes whether read/write 1872operations on a parallel file system are performed collectively or 1873independently (the default) on the variable. This function can only be 1874called if the file was created (see [NF90\_CREATE](#NF90_005fCREATE)) or 1875opened (see [NF90\_OPEN](#NF90_005fOPEN)) for parallel I/O. 1876 1877This function is only available if the netCDF library was built with 1878parallel I/O enabled. 1879 1880Calling this function affects only the open file - information about 1881whether a variable is to be accessed collectively or independently is 1882not written to the data file. Every time you open a file on a parallel 1883file system, all variables default to independent operations. The change 1884of a variable to collective access lasts only as long as that file is 1885open. 1886 1887The variable can be changed from collective to independent, and back, as 1888often as desired. 1889 1890Classic and 64-bit offset files, when opened for parallel access, use 1891the parallel-netcdf (a.k.a. pnetcdf) library, which does not allow 1892per-variable changes of access mode - the entire file must be access 1893independently or collectively. For classic and 64-bit offset files, the 1894nf90\_var\_par\_access function changes the access for all variables in 1895the file. 1896 1897 1898 1899## Usage 1900 1901 1902 1903~~~~.fortran 1904 1905 function nf90_var_par_access(ncid, varid, access) 1906 integer, intent(in) :: ncid 1907 integer, intent(in) :: varid 1908 integer, intent(in) :: access 1909 integer :: nf90_var_par_access 1910 end function nf90_var_par_access 1911 1912~~~~ 1913 1914 1915 1916`ncid` 1917 1918: NetCDF ID, from a previous call to NF90\_OPEN (see 1919 [NF90\_OPEN](#NF90_005fOPEN)) or NF90\_CREATE (see 1920 [NF90\_CREATE](#NF90_005fCREATE)). 1921 1922`varid` 1923 1924: Variable ID. 1925 1926`access` 1927 1928: NF90\_INDEPENDENT to set this variable to independent operations. 1929 NF90\_COLLECTIVE to set it to collective operations. 1930 1931 1932 1933## Return Values 1934 1935`NF90_NOERR` 1936 1937: No error. 1938 1939`NF90_ENOTVAR` 1940 1941: No variable found. 1942 1943`NF90_NOPAR` 1944 1945: File not opened for parallel access. 1946 1947 1948 1949## Example 1950 1951This example comes from test program nf\_test/f90tst\_parallel.f90. For 1952this test to be run, netCDF must have been built with a parallel-enabled 1953HDF5, and –enable-parallel-tests must have been used when configuring 1954netcdf. 1955 1956 1957 1958~~~~.fortran 1959 1960 ! Reopen the file. 1961 call handle_err(nf90_open(FILE_NAME, nf90_nowrite, ncid, comm = MPI_COMM_WORLD, & 1962 info = MPI_INFO_NULL)) 1963 1964 ! Set collective access on this variable. This will cause all 1965 ! reads/writes to happen together on every processor. 1966 call handle_err(nf90_var_par_access(ncid, varid, nf90_collective)) 1967 1968 ! Read this processor's data. 1969 call handle_err(nf90_get_var(ncid, varid, data_in, start = start, count = count)) 1970 1971~~~~ 1972