NetCDF-Fortran 4.6.1
|
Attributes may be associated with each netCDF variable to specify such properties as units, special values, maximum and minimum valid values, scaling factors, and offsets. Attributes for a netCDF dataset are defined when the dataset is first created, while the netCDF dataset is in define mode. Additional attributes may be added later by reentering define mode. A netCDF attribute has a netCDF variable to which it is assigned, a name, a type, a length, and a sequence of one or more values. An attribute is designated by its variable ID and name. When an attribute name is not known, it may be designated by its variable ID and number in order to determine its name, using the function NF90_INQ_ATTNAME.
The attributes associated with a variable are typically defined immediately after the variable is created, while still in define mode. The data type, length, and value of an attribute may be changed even when in data mode, as long as the changed attribute requires no more space than the attribute as originally defined.
It is also possible to have attributes that are not associated with any variable. These are called global attributes and are identified by using NF90_GLOBAL as a variable pseudo-ID. Global attributes are usually related to the netCDF dataset as a whole and may be used for purposes such as providing a title or processing history for a netCDF dataset.
Attributes are much more useful when they follow established community conventions. See Attribute Conventions in {No value for ‘n-man’}.
Operations supported on attributes are:
The function NF90_PUT_ATTadds or changes a variable attribute or global attribute of an open netCDF dataset. If this attribute is new, or if the space required to store the attribute is greater than before, the netCDF dataset must be in define mode.
Although it’s possible to create attributes of all types, text and double attributes are adequate for most purposes.
ncid
: NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
varid
: Variable ID of the variable to which the attribute will be assigned or NF90_GLOBAL for a global attribute.
name
: Attribute name. Attribute name conventions are assumed by some netCDF generic applications, e.g., ‘units’ as the name for a string attribute that gives the units for a netCDF variable. See Attribute Conventions in {No value for ‘n-man’}.
values
: A numeric rank 1 array of attribute values or a scalar. The external data type of the attribute is set to match the internal representation of the argument, that is if values is a two byte integer array, the attribute will be of type NF90_INT2. Fortran 90 intrinsic functions can be used to convert attributes to the desired type.
NF90_PUT_ATT returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF90_PUT_ATT to add a variable attribute named valid_range for a netCDF variable named rh and a global attribute named title to an existing netCDF dataset named foo.nc:
The function NF90_INQUIRE_ATTRIBUTE returns information about a netCDF attribute given the variable ID and attribute name. Information about an attribute includes its type, length, name, and number. See NF90_GET_ATT for getting attribute values.
The function NF90_INQ_ATTNAME gets the name of an attribute, given its variable ID and number. This function is useful in generic applications that need to get the names of all the attributes associated with a variable, since attributes are accessed by name rather than number in all other attribute functions. The number of an attribute is more volatile than the name, since it can change when other attributes of the same variable are deleted. This is why an attribute number is not called an attribute ID.
ncid
: NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
varid
: Variable ID of the attribute’s variable, or NF90_GLOBAL for a global attribute.
name
: Attribute name. For NF90_INQ_ATTNAME, this is a pointer to the location for the returned attribute name.
xtype
: Returned attribute type, one of the set of predefined netCDF external data types. The valid netCDF external data types are NF90_BYTE, NF90_CHAR, NF90_SHORT, NF90_INT, NF90_FLOAT, and NF90_DOUBLE.
len
: Returned number of values currently stored in the attribute. For a string-valued attribute, this is the number of characters in the string.
attnum
: For NF90_INQ_ATTNAME, the input attribute number; for NF90_INQ_ATTID, the returned attribute number. The attributes for each variable are numbered from 1 (the first attribute) to NATTS, where NATTS is the number of attributes for the variable, as returned from a call to NF90_INQ_VARNATTS.
(If you already know an attribute name, knowing its number is not very useful, because accessing information about an attribute requires its name.)
Each function returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF90_INQUIRE_ATTRIBUTE to inquire about the lengths of an attribute named valid_range for a netCDF variable named rh and a global attribute named title in an existing netCDF dataset named foo.nc:
Function nf90_get_att gets the value(s) of a netCDF attribute, given its variable ID and name.
ncid
: NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
varid
: Variable ID of the attribute’s variable, or NF90_GLOBAL for a global attribute.
name
: Attribute name.
values
: Returned attribute values. All elements of the vector of attribute values are returned, so you must provide enough space to hold them. If you don’t know how much space to reserve, call NF90_INQUIRE_ATTRIBUTE first to find out the length of the attribute. If there is only a single attribute values may be a scalar. If the attribute is of type character values should be a varble of type character with the len Fortran 90 attribute set to an appropriate value (i.e. character (len = 80) :: values). You cannot read character data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur. See Type Conversion in NetCDF Users Guide.
Here is an example using NF90_GET_ATT to determine the values of an attribute named valid_range for a netCDF variable named rh and a global attribute named title in an existing netCDF dataset named foo.nc. In this example, it is assumed that we don’t know how many values will be returned, so we first inquire about the length of the attributes to make sure we have enough space to store them:
The function NF90_COPY_ATT copies an attribute from one open netCDF dataset to another. It can also be used to copy an attribute from one variable to another within the same netCDF dataset.
If used to copy an attribute of user-defined type, then that user-defined type must already be defined in the target file. In the case of user-defined attributes, enddef/redef is called for ncid_in and ncid_out if they are in define mode. (This is the ensure that all user-defined types are committed to the file(s) before the copy is attempted.)
ncid_in
: The netCDF ID of an input netCDF dataset from which the attribute will be copied, from a previous call to NF90_OPEN or NF90_CREATE.
varid_in
: ID of the variable in the input netCDF dataset from which the attribute will be copied, or NF90_GLOBAL for a global attribute.
name
: Name of the attribute in the input netCDF dataset to be copied.
ncid_out
: The netCDF ID of the output netCDF dataset to which the attribute will be copied, from a previous call to NF90_OPEN or NF90_CREATE. It is permissible for the input and output netCDF IDs to be the same. The output netCDF dataset should be in define mode if the attribute to be copied does not already exist for the target variable, or if it would cause an existing target attribute to grow.
varid_out
: ID of the variable in the output netCDF dataset to which the attribute will be copied, or NF90_GLOBAL to copy to a global attribute.
NF90_COPY_ATT returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF90_COPY_ATT to copy the variable attribute units from the variable rh in an existing netCDF dataset named foo.nc to the variable avgrh in another existing netCDF dataset named bar.nc, assuming that the variable avgrh already exists, but does not yet have a units attribute:
The function NF90_RENAME_ATT changes the name of an attribute. If the new name is longer than the original name, the netCDF dataset must be in define mode. You cannot rename an attribute to have the same name as another attribute of the same variable.
ncid
: NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE
varid
: ID of the attribute’s variable, or NF90_GLOBAL for a global attribute
curname
: The current attribute name.
newname
: The new name to be assigned to the specified attribute. If the new name is longer than the current name, the netCDF dataset must be in define mode.
NF90_RENAME_ATT returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF90_RENAME_ATT to rename the variable attribute units to Units for a variable rh in an existing netCDF dataset named foo.nc:
The function NF90_DEL_ATT deletes a netCDF attribute from an open netCDF dataset. The netCDF dataset must be in define mode.
ncid
: NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
varid
: ID of the attribute’s variable, or NF90_GLOBAL for a global attribute.
name
: The name of the attribute to be deleted.
NF90_DEL_ATT returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using NF90_DEL_ATT to delete the variable attribute Units for a variable rh in an existing netCDF dataset named foo.nc: