[Top] [Prev] [Next]

3.9 User-defined Attributes

User-defined attributes are defined by the calling program and contain auxiliary information about a file, SDS array, or dimension. This auxiliary information is sometimes called metadata because it is data about data. There are two ways to store metadata: as user-defined attributes or as predefined attributes.

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.

The data types permitted for attributes are the same as those allowed for SDS arrays. SDS arrays with general attributes of the same name can have different data types. For example, the attribute 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.

Attribute names follow the same rules as dimension names. Providing meaningful names for attributes is important, however using standardized names may be necessary if generic applications and utility programs are to be used. For example, every variable assigned a unit should have an attribute named "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.

The SD interface uses the same functions to access all attributes regardless of the objects they are assigned to. The difference between accessing a file, array, or dimension attribute lies in the use of identifiers. File identifiers, SDS identifiers, and dimension identifiers are used to respectively access file attributes, SDS attributes, and dimension attributes.

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.

The parameter 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.

The arguments 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 2F on page 14). 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.

SDsetattr returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDsetattr are further described in Table 3S on page 53.

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.

C version

FORTRAN-77 version

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.

The syntax for SDfindattr and SDattrinfo are as follows:

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.

The parameter 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.

SDattrinfo retrieves the attribute's name, data type, and number of values into the parameters attr_name, data_type, and n_values, respectively.

The parameter 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 53.

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.

The parameter obj_id can be either an SD interface identifier (sd_id), a data set identifier (sds_id), or a dimension identifier (dim_id).

The parameter 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.

SDreadattr returns a value of 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

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
SDsetattr

[intn]

(sfsnatt/
sfscatt)
sd_id, sds_id or dim_id
int32
integer
SD interface, data set, or

dimension identifier

attr_name
char *
character*(*)
Name of the attribute

data_type
int32
integer
Data type of the attribute

n_values
int32
integer
Number of values in the attribute

values
VOIDP
<valid numeric data type>(*)/
character*(*)
Buffer containing the data to be written

SDfindattr

[int32]

(sffattr)
sd_id, sds_id or dim_id
int32
integer
SD interface, data set, or

dimension identifier

attr_name
char *
character*(*)
Attribute name

SDattrinfo

[intn]

(sfgainfo)
sd_id, sds_id or dim_id
int32
integer
SD interface, data set, or

dimension identifier

attr_index
int32
integer
Index of the attribute to be read

attr_name
char *
character*(*)
Buffer for the name of the attribute

data_type
int32 *
integer
Buffer for the data type of the values in the attribute

n_values
int32 *
integer
Buffer for the total number of values in the attribute

SDreadattr

[intn]

(sfrattr/
sfrnatt/
sfrcatt)
sd_id, sds_id or dim_id
int32
integer
SD interface, data set, or dimension identifier

attr_index
int32
integer
Index of the attribute to be read

values
VOIDP
<valid data type>(*)/
<valid numeric data type>(*)/
character*(*)
Buffer for the attribute values

EXAMPLE 15. Reading Attributes.

This example uses the routines SDfindattr/sffattr, SDattrinfo/sfgainfo, and SDreadattr/sfrattr to find and read attributes of the file, data set, and data set dimension created in the Example 14.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 05/19/99, NCSA HDF Development Group.