[Top] [Prev] [Next]

5.8 Vgroup Attributes

HDF version 4.1r1 and later include the ability to assign attributes to a vgroup. The concept of attributes is fully explained in Chapter 3, Scientific Data Sets (SD API). To review briefly, an attribute has a name, a data type, a number of attribute values, and the attribute values themselves. All attribute values must be of the same data type. For example, an attribute value cannot consist of ten characters and one integer, or a character value cannot be included in an attribute value consisting of two 32-bit integers.

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.

Vgetversion returns the vgroup version number if successful, and 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.

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.

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

Vattrinfo returns either 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

Routine Name

[Return Type]

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

[int32]

(vfgver)
vgroup_id
int32
integer
Vgroup identifier

Vattrinfo

[intn]

(vfainfo)
vgroup_id
int32
integer
Vgroup identifier

attr_index
intn
integer
Index of the attribute

attr_name
char *
character*(*)
Returned name of the attribute

data_type
int32 *
integer
Returned data type of the attribute

n_values
int32 *
integer
Returned number of values of the attribute

size
int32 *
integer
Returned size, in bytes, of the value of the attribute

Vnattrs

[intn]

(vfnatts)
vgroup_id
int32
integer
Vgroup identifier

5.8.4 Setting the Attribute of a Vgroup: Vsetattr

Vsetattr attaches an attribute to the vgroup specified by the parameter 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.

Vsetattr returns either 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.

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

This routine is often used with Vinquire in a loop to retrieve the total number of attributes.

Note that the FORTRAN-77 version of Vgetattr has two routines; vfgnatt gets a numeric value attribute and vfgcatt gets a character value attribute.

Vgetattr returns either 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

Routine Name

[Return Type]

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

[intn]

(vfsnatt/vfscatt)
vgroup_id
int32
integer
Vgroup 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 the attribute contains

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

Vgetattr

[intn]

(vfgnatt/vfgcatt)
vgroup_id
int32
integer
Vgroup identifier

attr_index
intn
integer
Index of the attribute

attr_values
VOIDP
<valid numeric data type> (*)/
character*(*)
Buffer containing attribute values

Vfindattr

[intn]

(vffdatt)
vgroup_id
int32
integer
Vgroup identifier

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

EXAMPLE 6. Obtaining Information about the Contents of a Vgroup

This example illustrates the use of Vgetid/vfgid to get the reference number of a vgroup, Vntagrefs/vfntr to get the number of HDF data objects in the vgroup, Vgettagref/vfgttr to get the tag/reference number pair of a data object within the vgroup, and Visvg/vfisvg and Visvs/vfisvs to determine whether a data object is a vgroup and a vdata, respectively.

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

FORTRAN-77 version



[Top] [Prev] [Next]

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