Any number of attributes can be assigned to a vgroup, however, each attribute name must be unique among all attributes in the vgroup.
5.8.1 Obtaining the Vgroup Version Number of a Given Vgroup: Vgetversion
The structure of the vgroup has gone through several changes since HDF was first written. Determining the version of any particular vgroup is necessary as some of the older versions of vgroups do not support some of the newer features, such as attributes. Vgetversion returns the version number of the vgroup identified by the parameter vgroup_id. The syntax of Vgetversion is as follows:C: version_num = Vgetversion(vgroup_id);
FORTRAN: version_num = vfgver(vgroup_id)
There are three valid version numbers: VSET_OLD_VERSION (or 2), VSET_VERSION (or 3), and VSET_NEW_VERSION (or 4).VSET_OLD_VERSION is returned when the vgroup is of a version that corresponds to an HDF library version before version 3.2.VSET_VERSION is returned when the vgroup is of a version that corresponds to an HDF library version between versions 3.2 and 4.0 release 2.VSET_NEW_VERSION is returned when the vgroup is of a version that corresponds to an HDF library version of version 4.1 release 1 or higher.FAIL (or -1) otherwise. This routine is further defined in Table 5L on page 205.
5.8.2 Obtaining Information on a Given Vgroup Attribute: Vattrinfo
Vattrinfo retrieves the name, data type, number of values, and the size of the values of an attribute that belongs to the vgroup identified by the parameter vgroup_id. The syntax of Vattrinfo is as follows:C: status = Vattrinfo(vgroup_id, attr_index, attr_name, &data_type, &n_values, &size);
FORTRAN: status = vfainfo(vgroup_id, attr_index, attr_name, data_type, n_values, size)
Vattrinfo stores the name, data type, number of values, and the size of the value of the attribute into the parameters attr_name, data_type, n_values, and size, respectively.attr_index. The valid values of attr_index range from 0 to the total number of attributes attached to the vgroup - 1. The number of vgroup attributes can be obtained using the routine Vnattrs.data_type is an integer number. Refer to Table 2F on page 14 for the definitions of the data types to interpret this value. The parameter size contains the number of bytes taken by an attribute value.
In C, the parameters
attr_name, data_type, n_values, and size can be set to NULL, if the information returned by these parameters is not needed.SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further described in Table 5L.
5.8.3 Obtaining the Total Number of Vgroup Attributes: Vnattrs
Vnattrs returns the number of attributes assigned to the vgroup specified by the parameter vgroup_id. The syntax of Vnattrs is as follows:C: num_of_attrs = Vnattrs(vgroup_id);
FORTRAN: num_of_attrs = vfnatts(vgroup_id)
Vnattrs returns either the number of attributes or FAIL (or -1). This routine is further defined in Table 5L.
TABLE 5L - Vgetversion, Vattrinfo, and Vnattrs Parameter Lists
vgroup_id. The syntax of Vsetattr is as follows:
C: status = Vsetattr(vgroup_id, attr_name, data_type, n_values, attr_values);
FORTRAN: status = vfsnatt(vgroup_id, attr_name, data_type, n_values, attr_values)
OR status = vfscatt(vgroup_id, attr_name, data_type, n_values, attr_values)If the attribute with the name specified in the parameter
attr_name already exists, the new values will replace the current ones, provided the data type and count are not different. If either the data type or the count have been changed, Vsetattr will return FAIL (or -1).The parameter
data_type is an integer number specifying the data type of the attribute values. Refer to Table 2F on page 14 for the definition of the data types to interpret this value. The parameter n_values specifies the number of values to be stored in the attribute. The buffer attr_values contains the values to be stored in the attribute.
Note that the FORTRAN-77 version of Vsetattr has two routines; vfsnatt sets a numeric value attribute and vfscatt sets a character value attribute.
SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 5M on page 206.
5.8.5 Retrieving the Values of a Given Vgroup Attribute: Vgetattr
Vgetattr retrieves the values of an attribute of the vgroup specified by the parameter vgroup_id. The syntax of Vgetattr is as follows:C: status = Vgetattr(vgroup_id, attr_index, attr_values);
FORTRAN: status = vfgnatt(vgroup_id, attr_index, attr_values)
OR status = vfgcatt(vgroup_id, attr_index, attr_values)
The attribute is specified by its index, attr_index. The valid values of attr_index range from 0 to the total number of attributes attached to the vgroup - 1. The number of vgroup attributes can be obtained using the routine Vnattrs.attr_values must be sufficiently allocated to hold the retrieved attribute values. Use Vattrinfo to obtain information about the attribute values for appropriate memory allocation.SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 5M on page 206.
5.8.6 Retrieving the Index of a Vgroup Attribute Given the Attribute Name: Vfindattr
Vfindattr searches the vgroup, identified by the parameter vgroup_id, for the attribute with the name specified by the parameter attr_name, and returns the index of that attribute. The syntax of this routine is as follows:C: attr_index = Vfindattr(vgroup_id, attr_name);
FORTRAN: attr_index = vffdatt(vgroup_id, attr_name)
Vfindattr returns either an attribute index or FAIL (or -1). The parameters of this routine are further defined in Table 5M.
TABLE 5M - Vsetattr, Vgetattr, and Vfindattr Parameter Lists
In the example, the program traverses the HDF file "General_Vgroups.hdf" from the beginning and obtains the reference number of each vgroup so it can be attached. Once a vgroup is attached, the program gets the total number of tag/reference number pairs in the vgroup and displays some information about the vgroup. The information displayed includes the position of the vgroup in the file, the tag/reference number pair of each of its data objects, and the message stating whether the object is a vdata, vgroup, or neither.
C version