1 7 Attributes {#f90-attributes}
6 7.1 Attributes Introduction {#f90-attributes-introduction}
9 Attributes may be associated with each netCDF variable to specify such
10 properties as units, special values, maximum and minimum valid values,
11 scaling factors, and offsets. Attributes for a netCDF dataset are
12 defined when the dataset is first created, while the netCDF dataset is
13 in define mode. Additional attributes may be added later by reentering
14 define mode. A netCDF attribute has a netCDF variable to which it is
15 assigned, a name, a type, a length, and a sequence of one or more
16 values. An attribute is designated by its variable ID and name. When an
17 attribute name is not known, it may be designated by its variable ID and
18 number in order to determine its name, using the function
21 The attributes associated with a variable are typically defined
22 immediately after the variable is created, while still in define mode.
23 The data type, length, and value of an attribute may be changed even
24 when in data mode, as long as the changed attribute requires no more
25 space than the attribute as originally defined.
27 It is also possible to have attributes that are not associated with any
28 variable. These are called global attributes and are identified by using
29 NF90\_GLOBAL as a variable pseudo-ID. Global attributes are usually
30 related to the netCDF dataset as a whole and may be used for purposes
31 such as providing a title or processing history for a netCDF dataset.
33 Attributes are much more useful when they follow established community
34 conventions. See [Attribute
35 Conventions](netcdf.html#Attribute-Conventions) in {No value for
38 Operations supported on attributes are:
40 - Create an attribute, given its variable ID, name, data type, length,
42 - Get attribute’s data type and length from its variable ID and name.
43 - Get attribute’s value from its variable ID and name.
44 - Copy attribute from one netCDF variable to another.
45 - Get name of attribute from its number.
46 - Rename an attribute.
47 - Delete an attribute.
51 7.2 Create an Attribute: NF90_PUT_ATT {#f90-create-an-attribute-nf90_put_att}
56 The function NF90\_PUT\_ATTadds or changes a variable attribute or
57 global attribute of an open netCDF dataset. If this attribute is new, or
58 if the space required to store the attribute is greater than before, the
59 netCDF dataset must be in define mode.
65 Although it’s possible to create attributes of all types, text and
66 double attributes are adequate for most purposes.
72 function nf90_put_att(ncid, varid, name, values)
73 integer, intent( in) :: ncid, varid
74 character(len = *), intent( in) :: name
75 scalar character string or any numeric type, scalar, or array of rank 1, &
77 integer :: nf90_put_att
85 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
89 : Variable ID of the variable to which the attribute will be assigned
90 or NF90\_GLOBAL for a global attribute.
94 : Attribute name. Attribute name conventions are assumed by some
95 netCDF generic applications, e.g., ‘units’ as the name for a string
96 attribute that gives the units for a netCDF variable. See [Attribute
97 Conventions](netcdf.html#Attribute-Conventions) in {No value
102 : A numeric rank 1 array of attribute values or a scalar. The external
103 data type of the attribute is set to match the internal
104 representation of the argument, that is if values is a two byte
105 integer array, the attribute will be of type NF90\_INT2. Fortran 90
106 intrinsic functions can be used to convert attributes to the
113 NF90\_PUT\_ATT returns the value NF90\_NOERR if no errors occurred.
114 Otherwise, the returned status indicates an error. Possible causes of
117 - The variable ID is invalid for the specified netCDF dataset.
118 - The specified netCDF type is invalid.
119 - The specified length is negative.
120 - The specified open netCDF dataset is in data mode and the specified
121 attribute would expand.
122 - The specified open netCDF dataset is in data mode and the specified
123 attribute does not already exist.
124 - The specified netCDF ID does not refer to an open netCDF dataset.
125 - The number of attributes for this variable exceeds NF90\_MAX\_ATTRS.
131 Here is an example using NF90\_PUT\_ATT to add a variable attribute
132 named valid\_range for a netCDF variable named rh and a global attribute
133 named title to an existing netCDF dataset named foo.nc:
141 integer :: ncid, status, RHVarID
143 status = nf90_open("foo.nc", nf90_write, ncid)
144 if (status /= nf90_noerr) call handle_err(status)
146 ! Enter define mode so we can add the attribute
147 status = nf90_redef(ncid)
148 if (status /= nf90_noerr) call handle_err(status)
149 ! Get the variable ID for "rh"...
150 status = nf90_inq_varid(ncid, "rh", RHVarID)
151 if (status /= nf90_noerr) call handle_err(status)
152 ! ... put the range attribute, setting it to eight byte reals...
153 status = nf90_put_att(ncid, RHVarID, "valid_range", real((/ 0, 100 /))
154 ! ... and the title attribute.
155 if (status /= nf90_noerr) call handle_err(status)
156 status = nf90_put_att(ncid, RHVarID, "title", "example netCDF dataset") )
157 if (status /= nf90_noerr) call handle_err(status)
159 status = nf90_enddef(ncid)
160 if (status /= nf90_noerr) call handle_err(status)
167 7.3 Get Information about an Attribute: NF90_INQUIRE_ATTRIBUTE and NF90_INQ_ATTNAME {#f90-get-information-about-an-attribute-nf90_inquire_attribute-and-nf90_inq_attname}
172 The function NF90\_INQUIRE\_ATTRIBUTE returns information about a netCDF
173 attribute given the variable ID and attribute name. Information about an
174 attribute includes its type, length, name, and number. See
175 NF90\_GET\_ATT for getting attribute values.
177 The function NF90\_INQ\_ATTNAME gets the name of an attribute, given its
178 variable ID and number. This function is useful in generic applications
179 that need to get the names of all the attributes associated with a
180 variable, since attributes are accessed by name rather than number in
181 all other attribute functions. The number of an attribute is more
182 volatile than the name, since it can change when other attributes of the
183 same variable are deleted. This is why an attribute number is not called
194 function nf90_inquire_attribute(ncid, varid, name, xtype, len, attnum)
195 integer, intent( in) :: ncid, varid
196 character (len = *), intent( in) :: name
197 integer, intent(out), optional :: xtype, len, attnum
198 integer :: nf90_inquire_attribute
199 function nf90_inq_attname(ncid, varid, attnum, name)
200 integer, intent( in) :: ncid, varid, attnum
201 character (len = *), intent(out) :: name
202 integer :: nf90_inq_attname
210 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
214 : Variable ID of the attribute’s variable, or NF90\_GLOBAL for a
219 : Attribute name. For NF90\_INQ\_ATTNAME, this is a pointer to the
220 location for the returned attribute name.
224 : Returned attribute type, one of the set of predefined netCDF
225 external data types. The valid netCDF external data types are
226 NF90\_BYTE, NF90\_CHAR, NF90\_SHORT, NF90\_INT, NF90\_FLOAT,
231 : Returned number of values currently stored in the attribute. For a
232 string-valued attribute, this is the number of characters in
237 : For NF90\_INQ\_ATTNAME, the input attribute number; for
238 NF90\_INQ\_ATTID, the returned attribute number. The attributes for
239 each variable are numbered from 1 (the first attribute) to NATTS,
240 where NATTS is the number of attributes for the variable, as
241 returned from a call to NF90\_INQ\_VARNATTS.
243 (If you already know an attribute name, knowing its number is not
244 very useful, because accessing information about an attribute
251 Each function returns the value NF90\_NOERR if no errors occurred.
252 Otherwise, the returned status indicates an error. Possible causes of
255 - The variable ID is invalid for the specified netCDF dataset.
256 - The specified attribute does not exist.
257 - The specified netCDF ID does not refer to an open netCDF dataset.
258 - For NF90\_INQ\_ATTNAME, the specified attribute number is negative
259 or more than the number of attributes defined for the
266 Here is an example using NF90\_INQUIRE\_ATTRIBUTE to inquire about the
267 lengths of an attribute named valid\_range for a netCDF variable named
268 rh and a global attribute named title in an existing netCDF dataset
277 integer :: ncid, status
278 integer :: RHVarID ! Variable ID
279 integer :: validRangeLength, titleLength ! Attribute lengths
281 status = nf90_open("foo.nc", nf90_nowrite, ncid)
282 if (status /= nf90_noerr) call handle_err(status)
284 ! Get the variable ID for "rh"...
285 status = nf90_inq_varid(ncid, "rh", RHVarID)
286 if (status /= nf90_noerr) call handle_err(status)
287 ! ... get the length of the "valid_range" attribute...
288 status = nf90_inquire_attribute(ncid, RHVarID, "valid_range", &
289 len = validRangeLength)
290 if (status /= nf90_noerr) call handle_err(status)
291 ! ... and the global title attribute.
292 status = nf90_inquire_attribute(ncid, nf90_global, "title", len = titleLength)
293 if (status /= nf90_noerr) call handle_err(status)
299 7.4 Get Attribute’s Values: NF90_GET_ATT {#f90-get-attributes-values-nf90_get_att}
304 Function nf90\_get\_att gets the value(s) of a netCDF attribute, given
305 its variable ID and name.
315 function nf90_get_att(ncid, varid, name, values)
316 integer, intent( in) :: ncid, varid
317 character(len = *), intent( in) :: name
318 any valid type, scalar or array of rank 1, &
319 intent(out) :: values
320 integer :: nf90_get_att
328 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
332 : Variable ID of the attribute’s variable, or NF90\_GLOBAL for a
341 : Returned attribute values. All elements of the vector of attribute
342 values are returned, so you must provide enough space to hold them.
343 If you don’t know how much space to reserve, call
344 NF90\_INQUIRE\_ATTRIBUTE first to find out the length of
345 the attribute. If there is only a single attribute values may be
346 a scalar. If the attribute is of type character values should be a
347 varble of type character with the len Fortran 90 attribute set to
348 an appropriate value (i.e. character (len = 80) :: values). You
349 cannot read character data from a numeric variable or numeric data
350 from a text variable. For numeric data, if the type of data differs
351 from the netCDF variable type, type conversion will occur. See [Type
352 Conversion](netcdf.html#Type-Conversion) in NetCDF Users Guide.
360 NF90\_GET\_ATT\_ type returns the value NF90\_NOERR if no errors
361 occurred. Otherwise, the returned status indicates an error. Possible
362 causes of errors include:
364 - The variable ID is invalid for the specified netCDF dataset.
365 - The specified attribute does not exist.
366 - The specified netCDF ID does not refer to an open netCDF dataset.
367 - One or more of the attribute values are out of the range of values
368 representable by the desired type.
375 Here is an example using NF90\_GET\_ATT to determine the values of an
376 attribute named valid\_range for a netCDF variable named rh and a global
377 attribute named title in an existing netCDF dataset named foo.nc. In
378 this example, it is assumed that we don’t know how many values will be
379 returned, so we first inquire about the length of the attributes to make
380 sure we have enough space to store them:
388 integer :: ncid, status
389 integer :: RHVarID ! Variable ID
390 integer :: validRangeLength, titleLength ! Attribute lengths
391 real, dimension(:), allocatable, &
393 character (len = 80) :: title
395 status = nf90_open("foo.nc", nf90_nowrite, ncid)
396 if (status /= nf90_noerr) call handle_err(status)
398 ! Find the lengths of the attributes
399 status = nf90_inq_varid(ncid, "rh", RHVarID)
400 if (status /= nf90_noerr) call handle_err(status)
401 status = nf90_inquire_attribute(ncid, RHVarID, "valid_range", &
402 len = validRangeLength)
403 if (status /= nf90_noerr) call handle_err(status)
404 status = nf90_inquire_attribute(ncid, nf90_global, "title", len = titleLength)
405 if (status /= nf90_noerr) call handle_err(status)
407 !Allocate space to hold attribute values, check string lengths
408 allocate(validRange(validRangeLength), stat = status)
409 if(status /= 0 .or. len(title) < titleLength)
410 print *, "Not enough space to put attribute values."
413 ! Read the attributes.
414 status = nf90_get_att(ncid, RHVarID, "valid_range", validRange)
415 if (status /= nf90_noerr) call handle_err(status)
416 status = nf90_get_att(ncid, nf90_global, "title", title)
417 if (status /= nf90_noerr) call handle_err(status)
424 7.5 Copy Attribute from One NetCDF to Another: NF90_COPY_ATT {#f90-copy-attribute-from-one-netcdf-to-another-nf90_copy_att}
429 The function NF90\_COPY\_ATT copies an attribute from one open netCDF
430 dataset to another. It can also be used to copy an attribute from one
431 variable to another within the same netCDF dataset.
433 If used to copy an attribute of user-defined type, then that
434 user-defined type must already be defined in the target file. In the
435 case of user-defined attributes, enddef/redef is called for ncid\_in and
436 ncid\_out if they are in define mode. (This is the ensure that all
437 user-defined types are committed to the file(s) before the copy is
446 function nf90_copy_att(ncid_in, varid_in, name, ncid_out, varid_out)
447 integer, intent( in) :: ncid_in, varid_in
448 character (len = *), intent( in) :: name
449 integer, intent( in) :: ncid_out, varid_out
450 integer :: nf90_copy_att
459 : The netCDF ID of an input netCDF dataset from which the attribute
460 will be copied, from a previous call to NF90\_OPEN or NF90\_CREATE.
464 : ID of the variable in the input netCDF dataset from which the
465 attribute will be copied, or NF90\_GLOBAL for a global attribute.
469 : Name of the attribute in the input netCDF dataset to be copied.
473 : The netCDF ID of the output netCDF dataset to which the attribute
474 will be copied, from a previous call to NF90\_OPEN or NF90\_CREATE.
475 It is permissible for the input and output netCDF IDs to be
476 the same. The output netCDF dataset should be in define mode if the
477 attribute to be copied does not already exist for the target
478 variable, or if it would cause an existing target attribute to grow.
482 : ID of the variable in the output netCDF dataset to which the
483 attribute will be copied, or NF90\_GLOBAL to copy to a
490 NF90\_COPY\_ATT returns the value NF90\_NOERR if no errors occurred.
491 Otherwise, the returned status indicates an error. Possible causes of
494 - The input or output variable ID is invalid for the specified
496 - The specified attribute does not exist.
497 - The output netCDF is not in define mode and the attribute is new for
498 the output dataset is larger than the existing attribute.
499 - The input or output netCDF ID does not refer to an open
506 Here is an example using NF90\_COPY\_ATT to copy the variable attribute
507 units from the variable rh in an existing netCDF dataset named foo.nc to
508 the variable avgrh in another existing netCDF dataset named bar.nc,
509 assuming that the variable avgrh already exists, but does not yet have a
518 integer :: ncid1, ncid2, status
519 integer :: RHVarID, avgRHVarID ! Variable ID
521 status = nf90_open("foo.nc", nf90_nowrite, ncid1)
522 if (status /= nf90_noerr) call handle_err(status)
523 status = nf90_open("bar.nc", nf90_write, ncid2)
524 if (status /= nf90_noerr) call handle_err(status)
526 ! Find the IDs of the variables
527 status = nf90_inq_varid(ncid1, "rh", RHVarID)
528 if (status /= nf90_noerr) call handle_err(status)
529 status = nf90_inq_varid(ncid1, "avgrh", avgRHVarID)
530 if (status /= nf90_noerr) call handle_err(status)
532 status = nf90_redef(ncid2) ! Enter define mode
533 if (status /= nf90_noerr) call handle_err(status)
534 ! Copy variable attribute from "rh" in file 1 to "avgrh" in file 1
535 status = nf90_copy_att(ncid1, RHVarID, "units", ncid2, avgRHVarID)
536 if (status /= nf90_noerr) call handle_err(status)
537 status = nf90_enddef(ncid2)
538 if (status /= nf90_noerr) call handle_err(status)
544 7.6 Rename an Attribute: NF90_RENAME_ATT {#f90-rename-an-attribute-nf90_rename_att}
549 The function NF90\_RENAME\_ATT changes the name of an attribute. If the
550 new name is longer than the original name, the netCDF dataset must be in
551 define mode. You cannot rename an attribute to have the same name as
552 another attribute of the same variable.
562 function nf90_rename_att(ncid, varid, curname, newname)
563 integer, intent( in) :: ncid, varid
564 character (len = *), intent( in) :: curname, newname
565 integer :: nf90_rename_att
574 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE
578 : ID of the attribute’s variable, or NF90\_GLOBAL for a global
583 : The current attribute name.
587 : The new name to be assigned to the specified attribute. If the new
588 name is longer than the current name, the netCDF dataset must be in
595 NF90\_RENAME\_ATT returns the value NF90\_NOERR if no errors occurred.
596 Otherwise, the returned status indicates an error. Possible causes of
599 - The specified variable ID is not valid.
600 - The new attribute name is already in use for another attribute of
601 the specified variable.
602 - The specified netCDF dataset is in data mode and the new name is
603 longer than the old name.
604 - The specified attribute does not exist.
605 - The specified netCDF ID does not refer to an open netCDF dataset.
611 Here is an example using NF90\_RENAME\_ATT to rename the variable
612 attribute units to Units for a variable rh in an existing netCDF dataset
619 integer :: ncid1, status
620 integer :: RHVarID ! Variable ID
622 status = nf90_open("foo.nc", nf90_nowrite, ncid)
623 if (status /= nf90_noerr) call handle_err(status)
625 ! Find the IDs of the variables
626 status = nf90_inq_varid(ncid, "rh", RHVarID)
627 if (status /= nf90_noerr) call handle_err(status)
629 status = nf90_rename_att(ncid, RHVarID, "units", "Units")
630 if (status /= nf90_noerr) call handle_err(status)
636 7.7 NF90_DEL_ATT {#f90-nf90_del_att}
641 The function NF90\_DEL\_ATT deletes a netCDF attribute from an open
642 netCDF dataset. The netCDF dataset must be in define mode.
652 function nf90_del_att(ncid, varid, name)
653 integer, intent( in) :: ncid, varid
654 character (len = *), intent( in) :: name
655 integer :: nf90_del_att
663 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
667 : ID of the attribute’s variable, or NF90\_GLOBAL for a
672 : The name of the attribute to be deleted.
678 NF90\_DEL\_ATT returns the value NF90\_NOERR if no errors occurred.
679 Otherwise, the returned status indicates an error. Possible causes of
682 - The specified variable ID is not valid.
683 - The specified netCDF dataset is in data mode.
684 - The specified attribute does not exist.
685 - The specified netCDF ID does not refer to an open netCDF dataset.
691 Here is an example using NF90\_DEL\_ATT to delete the variable attribute
692 Units for a variable rh in an existing netCDF dataset named foo.nc:
700 integer :: ncid1, status
701 integer :: RHVarID ! Variable ID
703 status = nf90_open("foo.nc", nf90_nowrite, ncid)
704 if (status /= nf90_noerr) call handle_err(status)
706 ! Find the IDs of the variables
707 status = nf90_inq_varid(ncid, "rh", RHVarID)
708 if (status /= nf90_noerr) call handle_err(status)
710 status = nf90_redef(ncid) ! Enter define mode
711 if (status /= nf90_noerr) call handle_err(status)
712 status = nf90_del_att(ncid, RHVarID, "Units")
713 if (status /= nf90_noerr) call handle_err(status)
714 status = nf90_enddef(ncid)
715 if (status /= nf90_noerr) call handle_err(status)