NetCDF-Fortran  4.4.4
netcdf-f90-sec7-attributes.md
Go to the documentation of this file.
1 7 Attributes {#f90-attributes}
2 ============
3 
4 [TOC]
5 
6 7.1 Attributes Introduction {#f90-attributes-introduction}
7 ============
8 
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
19 NF90\_INQ\_ATTNAME.
20 
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.
26 
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.
32 
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
36 ‘n-man’}.
37 
38 Operations supported on attributes are:
39 
40 - Create an attribute, given its variable ID, name, data type, length,
41  and value.
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.
48 
49 
50 
51 7.2 Create an Attribute: NF90_PUT_ATT {#f90-create-an-attribute-nf90_put_att}
52 ============
53 
54 
55 
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.
60 
61 
62 
63 ## Usage
64 
65 Although it’s possible to create attributes of all types, text and
66 double attributes are adequate for most purposes.
67 
68 
69 ~~~~.fortran
70 
71 
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, &
76  intent( in) :: values
77  integer :: nf90_put_att
78 
79 
80 ~~~~
81 
82 
83 `ncid`
84 
85 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
86 
87 `varid`
88 
89 : Variable ID of the variable to which the attribute will be assigned
90  or NF90\_GLOBAL for a global attribute.
91 
92 `name`
93 
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
98  for ‘n-man’}.
99 
100 `values`
101 
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
107  desired type.
108 
109 
110 
111 ## Errors
112 
113 NF90\_PUT\_ATT returns the value NF90\_NOERR if no errors occurred.
114 Otherwise, the returned status indicates an error. Possible causes of
115 errors include:
116 
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.
126 
127 
128 
129 ## Example
130 
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:
134 
135 
136 ~~~~.fortran
137 
138 
139  use netcdf
140  implicit none
141  integer :: ncid, status, RHVarID
142  ...
143  status = nf90_open("foo.nc", nf90_write, ncid)
144  if (status /= nf90_noerr) call handle_err(status)
145  ...
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)
158  ! Leave define mode
159  status = nf90_enddef(ncid)
160  if (status /= nf90_noerr) call handle_err(status)
161 
162 
163 
164 ~~~~
165 
166 
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}
168 ============
169 
170 
171 
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.
176 
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
184 an attribute ID.
185 
186 
187 
188 ## Usage
189 
190 
191 
192 ~~~~.fortran
193 
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
203 
204 
205 ~~~~
206 
207 
208 `ncid`
209 
210 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
211 
212 `varid`
213 
214 : Variable ID of the attribute’s variable, or NF90\_GLOBAL for a
215  global attribute.
216 
217 `name`
218 
219 : Attribute name. For NF90\_INQ\_ATTNAME, this is a pointer to the
220  location for the returned attribute name.
221 
222 `xtype`
223 
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,
227  and NF90\_DOUBLE.
228 
229 `len`
230 
231 : Returned number of values currently stored in the attribute. For a
232  string-valued attribute, this is the number of characters in
233  the string.
234 
235 `attnum`
236 
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.
242 
243  (If you already know an attribute name, knowing its number is not
244  very useful, because accessing information about an attribute
245  requires its name.)
246 
247 
248 
249 ## Errors
250 
251 Each function returns the value NF90\_NOERR if no errors occurred.
252 Otherwise, the returned status indicates an error. Possible causes of
253 errors include:
254 
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
260  specified variable.
261 
262 
263 
264 ## Example
265 
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
269 named foo.nc:
270 
271 
272 
273 ~~~~.fortran
274 
275  use netcdf
276  implicit none
277  integer :: ncid, status
278  integer :: RHVarID ! Variable ID
279  integer :: validRangeLength, titleLength ! Attribute lengths
280  ...
281  status = nf90_open("foo.nc", nf90_nowrite, ncid)
282  if (status /= nf90_noerr) call handle_err(status)
283  ...
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)
294 
295 
296 
297 ~~~~
298 
299 7.4 Get Attribute’s Values: NF90_GET_ATT {#f90-get-attributes-values-nf90_get_att}
300 ============
301 
302 
303 
304 Function nf90\_get\_att gets the value(s) of a netCDF attribute, given
305 its variable ID and name.
306 
307 
308 
309 ## Usage
310 
311 
312 
313 ~~~~.fortran
314 
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
321 
322 
323 
324 ~~~~
325 
326 `ncid`
327 
328 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
329 
330 `varid`
331 
332 : Variable ID of the attribute’s variable, or NF90\_GLOBAL for a
333  global attribute.
334 
335 `name`
336 
337 : Attribute name.
338 
339 `values`
340 
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.
353 
354 
355 
356 ## Errors
357 
358 ~~~~.fortran
359 
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:
363 
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.
369 
370 ~~~~
371 
372 
373 ## Example
374 
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:
381 
382 
383 ~~~~.fortran
384 
385 
386  use netcdf
387  implicit none
388  integer :: ncid, status
389  integer :: RHVarID ! Variable ID
390  integer :: validRangeLength, titleLength ! Attribute lengths
391  real, dimension(:), allocatable, &
392  :: validRange
393  character (len = 80) :: title
394  ...
395  status = nf90_open("foo.nc", nf90_nowrite, ncid)
396  if (status /= nf90_noerr) call handle_err(status)
397  ...
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)
406  ...
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."
411  exit
412  end if
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)
418 
419 
420 ~~~~
421 
422 
423 
424 7.5 Copy Attribute from One NetCDF to Another: NF90_COPY_ATT {#f90-copy-attribute-from-one-netcdf-to-another-nf90_copy_att}
425 ============
426 
427 
428 
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.
432 
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
438 attempted.)
439 
440 
441 
442 ## Usage
443 
444 ~~~~.fortran
445 
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
451 
452 
453 
454 
455 ~~~~
456 
457 `ncid_in`
458 
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.
461 
462 `varid_in`
463 
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.
466 
467 `name`
468 
469 : Name of the attribute in the input netCDF dataset to be copied.
470 
471 `ncid_out`
472 
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.
479 
480 `varid_out`
481 
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
484  global attribute.
485 
486 
487 
488 ## Errors
489 
490 NF90\_COPY\_ATT returns the value NF90\_NOERR if no errors occurred.
491 Otherwise, the returned status indicates an error. Possible causes of
492 errors include:
493 
494 - The input or output variable ID is invalid for the specified
495  netCDF dataset.
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
500  netCDF dataset.
501 
502 
503 
504 ## Example
505 
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
510 units attribute:
511 
512 
513 ~~~~.fortran
514 
515 
516  use netcdf
517  implicit none
518  integer :: ncid1, ncid2, status
519  integer :: RHVarID, avgRHVarID ! Variable ID
520  ...
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)
525  ...
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)
531  ...
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)
539 
540 
541 
542 ~~~~
543 
544 7.6 Rename an Attribute: NF90_RENAME_ATT {#f90-rename-an-attribute-nf90_rename_att}
545 ============
546 
547 
548 
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.
553 
554 
555 
556 ## Usage
557 
558 
559 ~~~~.fortran
560 
561 
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
566 
567 
568 
569 
570 ~~~~
571 
572 `ncid`
573 
574 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE
575 
576 `varid`
577 
578 : ID of the attribute’s variable, or NF90\_GLOBAL for a global
579  attribute
580 
581 `curname`
582 
583 : The current attribute name.
584 
585 `newname`
586 
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
589  define mode.
590 
591 
592 
593 ## Errors
594 
595 NF90\_RENAME\_ATT returns the value NF90\_NOERR if no errors occurred.
596 Otherwise, the returned status indicates an error. Possible causes of
597 errors include:
598 
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.
606 
607 
608 
609 ## Example
610 
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
613 named foo.nc:
614 
615 ~~~~.fortran
616 
617  use netcdf
618  implicit none
619  integer :: ncid1, status
620  integer :: RHVarID ! Variable ID
621  ...
622  status = nf90_open("foo.nc", nf90_nowrite, ncid)
623  if (status /= nf90_noerr) call handle_err(status)
624  ...
625  ! Find the IDs of the variables
626  status = nf90_inq_varid(ncid, "rh", RHVarID)
627  if (status /= nf90_noerr) call handle_err(status)
628  ...
629  status = nf90_rename_att(ncid, RHVarID, "units", "Units")
630  if (status /= nf90_noerr) call handle_err(status)
631 
632 
633 ~~~~
634 
635 
636 7.7 NF90_DEL_ATT {#f90-nf90_del_att}
637 ============
638 
639 
640 
641 The function NF90\_DEL\_ATT deletes a netCDF attribute from an open
642 netCDF dataset. The netCDF dataset must be in define mode.
643 
644 
645 
646 ## Usage
647 
648 
649 ~~~~.fortran
650 
651 
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
656 
657 ~~~~
658 
659 
660 
661 `ncid`
662 
663 : NetCDF ID, from a previous call to NF90\_OPEN or NF90\_CREATE.
664 
665 `varid`
666 
667 : ID of the attribute’s variable, or NF90\_GLOBAL for a
668  global attribute.
669 
670 `name`
671 
672 : The name of the attribute to be deleted.
673 
674 
675 
676 ## Errors
677 
678 NF90\_DEL\_ATT returns the value NF90\_NOERR if no errors occurred.
679 Otherwise, the returned status indicates an error. Possible causes of
680 errors include:
681 
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.
686 
687 
688 
689 ## Example
690 
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:
693 
694 
695 
696 ~~~~.fortran
697 
698  use netcdf
699  implicit none
700  integer :: ncid1, status
701  integer :: RHVarID ! Variable ID
702  ...
703  status = nf90_open("foo.nc", nf90_nowrite, ncid)
704  if (status /= nf90_noerr) call handle_err(status)
705  ...
706  ! Find the IDs of the variables
707  status = nf90_inq_varid(ncid, "rh", RHVarID)
708  if (status /= nf90_noerr) call handle_err(status)
709  ...
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)
716 
717 ~~~~

Return to the Main Unidata NetCDF page.
Generated on Fri Aug 4 2017 17:20:58 for NetCDF-Fortran. NetCDF is a Unidata library.