Attributes take the form
label=value, where label is a character string containing MAX_NC_NAME (or 256) or fewer characters and value contains one or more entries of the same data type as defined at the time the attribute is created. Attributes can be attached to files, data sets, and dimensions. These are referred to, respectively, as file attributes, data set attributes, and dimension attributes:
For each attribute, an attribute count is maintained that identifies the number of values in the attribute. Each attribute has a unique attribute index, the value of which ranges from 0 to the total number of attributes minus 1. The attribute index is used to locate an attribute in the object which the attribute is attached to. Once the attribute is identified, its values and information can be retrieved.
valid_range specifying the valid range of data values for an array of 16-bit integers might be of type 16-bit integer, whereas the attribute valid_range for an array of 32-bit floats could be of type 32-bit floating-point integer. units" associated with it. Furthermore, if an HDF file is to be used with software that recognizes "units" attributes, the values of the "units" attributes should be expressed in a conventional form as a character string that can be interpreted by that software. 3.9.1 Creating or Writing User-defined Attributes: SDsetattr
SDsetattr creates or modifies an attribute for one of the objects: the file, the data set, or the dimension. If the attribute with the specified name does not exist, SDsetattr creates a new one. If the named attribute already exists, SDsetattr resets all the values that are different from those provided in its argument list. The syntax of this routine is as follows:C: status = SDsetattr(obj_id, attr_name, data_type, n_values, values);
FORTRAN: status = sfsnatt(obj_id, attr_name, data_type, n_values, values)
OR status = sfscatt(obj_id, attr_name, data_type, n_values, values)
The parameter obj_id is the identifier of the HDF data object to which the attribute is assigned and can be a file identifier, SDS identifier, or dimension identifier. If obj_id specifies an SD interface identifier (sd_id), a global attribute will be created which applies to all objects in the file. If obj_id specifies a data set identifier (sds_id), an attribute will be attached only to the specified data set. If obj_id specifies a dimension identifier (dim_id), an attribute will be attached only to the specified dimension.attr_name is an ASCII character string containing the name of the attribute. It represents the label in the label = value equation and can be no more than MAX_NC_NAME (or 256) characters. If this is set to the name of an existing attribute, the value portion of the attribute will be overwritten. Do not use SDsetattr to assign a name to a dimension, use SDsetdimname instead.data_type, n_values, and values describe the right side of the label = value equation. The argument values contains one or more values of the same data type. The argument data_type contains any HDF supported data type (see Table 2E on page 13). The parameter n_values specifies the total number of values in the attribute.
There are two FORTRAN-77 versions of this routine: sfsnatt and sfscatt. The routine sfsnatt writes numeric attribute data and sfscatt writes character attribute data.
SUCCEED (or 0) or FAIL (or -1). The parameters of SDsetattr are further described in Table 3S on page 52.
EXAMPLE 14. Setting Attributes.
This example shows how the routines SDsetattr/sfscatt/sfsnatt are used to set the attributes of the file, data set, and data set dimension created in the Examples 2, 4, and 12.
3.9.2 Querying User-defined Attributes: SDfindattr and SDattrinfo
Given a file, SDS, or dimension identifier and an attribute name, SDfindattr returns a valid attribute index if the corresponding attribute exists. The attribute index can then be used to retrieve information about the attribute or its values. Given a file, SDS, or dimension identifier and a valid attribute index, SDattrinfo retrieves the information about the corresponding attribute if it exists. C: attr_index = SDfindattr(obj_id, attr_name);
status = SDattrinfo(obj_id, attr_index, attr_name, &data_type, &n_values);
FORTRAN: attr_index = sffattr(obj_id, attr_name)
status = sfgainfo(obj_id, attr_index, attr_name, data_type, n_values)
SDfindattr returns the index of the attribute, which belongs to the object identified by the parameter obj_id, and whose name is specified by the parameter attr_name. obj_id can be either an SD interface identifier (sd_id), a data set identifier (sds_id), or a dimension identifier (dim_id). SDfindattr is case-sensitive in searching for the name specified by the parameter attr_name and does not accept wildcards as part of that name.attr_name, data_type, and n_values, respectively.attr_index specifies the relative position of the attribute within the specified object. An attribute index may also be determined by either keeping track of the number and order of attributes as they are written or dumping the contents of the file using the HDF dumping utility, hdp, which is described in Chapter 15, HDF Command-Line Utilities.
SDfindattr returns an attribute index or a value of FAIL (or -1). SDattrinfo returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDfindattr and SDattrinfo are further described in Table 3S on page 52.
3.9.3 Reading User-defined Attributes: SDreadattr
Given a file, SDS, or dimension identifier and an attribute index, SDreadattr reads the values of an attribute that belongs to either a file, an SDS, or a dimension. The syntax of this routine is as follows:C: status = SDreadattr(obj_id, attr_index, values);
FORTRAN: status = sfrattr(obj_id, attr_index, values)
OR status = sfrnatt(obj_id, attr_index, values)
OR status = sfrcatt(obj_id, attr_index, values)
SDreadattr stores the attribute values in the buffer values, which is assumed to be sufficiently allocated. The size of the buffer must be at least n_values*sizeof (data_type) bytes long, where n_values and data_type are the number of attribute values and their type. The values of n_values and data_type can be retrieved using SDattrinfo. Note that the size of the data type must be determined at the local machine where the application is running. SDreadattr will also read attributes and annotations created by the DFSD interface. obj_id can be either an SD interface identifier (sd_id), a data set identifier (sds_id), or a dimension identifier (dim_id).attr_index specifies the relative position of the attribute within the specified object. An attribute index may also be determined by either keeping track of the number and order of attributes as they are written or dumping the contents of the file using the HDF dumping utility, hdp, which is described in Chapter 15, HDF Command-Line Utilities.
There are three FORTRAN-77 versions of this routine: sfrattr, sfrnatt, and sfrcatt. The routine sfrattr reads data of all valid data types, sfrnatt reads numeric attribute data and sfrcatt reads character attribute data.
SUCCEED (or 0) or FAIL (or -1). The parameters of SDreadattr are further described in Table 3S.
TABLE 3S - SDsetattr, SDfindattr, SDattrinfo, and SDreadattr Parameter Lists
C version