[Top] [Prev] [Next]

4.8 Vdata Attributes

HDF version 4.1r1 and later include the ability to assign attributes to a vdata and/or a vdata field. 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 integer cannot be added to an attribute value consisting of ten characters, or a character value cannot be included in an attribute value consisting of 2 32-bit integers.

Any number of attributes can be assigned to either a vdata or any single field in a vdata. However, each attribute name should be unique within its scope. In other words, the name of a field's attribute must be unique among all attributes that belong to that same field, and the name of a vdata's attribute must be unique among all attributes assigned to the same vdata.

The following subsections describe routines that retrieve various information about vdata and vdata field attributes. Those routines that access field attributes require the field index as a parameter (field_index).

4.8.1 Querying the Index of a Vdata Field Given the Field Name: VSfindex

VSfindex retrieves the index of a field given its name, field_name, and stores the value in the parameter field_index. The syntax of VSfindex is as follows:

C:		status = VSfindex(vdata_id, field_name, &field_index);
FORTRAN:	status = vsffidx(vdata_id, field_name, field_index)
The parameter field_index is the index number that uniquely identifies the location of the field within the vdata. Field index numbers are assigned in increasing order and are zero-based: for example, a field_index value of 4 would refer to the fifth field in the vdata.

VSfindex returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The parameters for VSfindex are further defined in Table 4J.

TABLE 4J - VSfindex Parameter List

Routine Name

[Return Type]

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

[intn]

(vsffidx)
vdata_id
int32
integer
Vdata identifier

field_name
char *
character*(*)
Name of the vdata field

field_index
int32 *
integer
Index of the vdata field

4.8.2 Setting the Attribute of a Vdata or Vdata Field: VSsetattr

VSsetattr attaches an attribute to a vdata or a vdata field. The syntax of VSsetattr is as follows:

C:		status = VSsetattr(vdata_id, field_index, attr_name, data_type, n_values, values);
FORTRAN:	status = vsfsnat(vdata_id, field_index, attr_name, data_type, n_values, values)
	OR	status = vsfscat(vdata_id, field_index, attr_name, data_type, n_values, values)
If the attribute has already been attached, the new attribute values will replace the current values, provided the data type and the number of attribute values (n_values) have not been changed. If either of these have been changed, VSsetattr will return FAIL (or -1).

Set the parameter field_index to _HDF_VDATA (or -1) to set an attribute for a vdata or to a valid field index to set attribute for a vdata field. A valid field index is a zero-based integer value representing the ordinal location of a field within the vdata.

The parameter attr_name specifies the name of the attribute to be set and can contain VSNAMELENMAX (or 64) characters. The parameter data_type specifies the data type of the attribute values. Data types supported by HDF are listed in Table 2E on page 13. The parameter values contains attribute values to be written.

The FORTRAN-77 version of VSsetattr has two routines: vsfsnat sets numeric attribute data and vsfscat sets character attribute data.

VSsetattr returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The parameters for VSsetattr are described in Table 4K.

4.8.3 Querying the Values of a Vdata or Vdata Field Attribute: VSgetattr

VSgetattr returns all of the values of the specified attribute of the specified vdata field or vdata. The syntax of VSgetattr is as follows:

C:		status = VSgetattr(vdata_id, field_index, attr_index, values);
FORTRAN:	status = vsfgnat(vdata_id, field_index, attr_index, values)
	OR	status = vsfgcat(vdata_id, field_index, attr_index, values)
Set the parameter field_index to _HDF_VDATA (or -1) to retrieve the values of the attribute attached to the vdata identified by the parameter vdata_id. Set field_index to a zero-based integer value to retrieve the values of an attribute attached to a vdata field; the value of field_index will be used as the index of the vdata field. In both cases, the values returned will be those of the attribute located at the position specified by the parameter attr_index, the zero-based index of the target attribute.

The parameter values must be sufficiently allocated to hold the retrieved attribute values. Use VSattrinfo to obtain information about the attribute values for appropriate memory allocation.

The FORTRAN-77 versions of VSgetattr has two routines: vsfgnat gets numeric attribute data and vsfgcat gets character attribute data.

VSgetattr returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The parameters for VSgetattr are described in Table 4K.

TABLE 4K - VSsetattr and VSgetattr Parameter Lists

Routine Name

[Return Type]

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

[intn]

(vsfsnat/vsfscat)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
_HDF_VDATA or index of the field

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

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

VSgetattr

[intn]

(vsfgnat/vsfgcat)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
_HDF_VDATA or index of the field

attr_index
intn
integer
Index of the attribute

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

4.8.4 Querying the Total Number of Vdata and Vdata Field Attributes: VSnattrs

VSnattrs returns the total number of attributes of the specified vdata and the fields contained in the vdata. This is different from the VSfnattrs routine, which returns the number of attributes of the specified vdata or a specified field contained in the specified vdata. The syntax of VSnattrs is as follows:

C:		num_of_attrs = VSnattrs(vdata_id);
FORTRAN:	num_of_attrs = vsfnats(vdata_id)
VSnattrs returns the total number of attributes assigned to the vdata and its fields when successful, and FAIL (or -1) otherwise. The parameters for VSnattrs are described in Table 4L.

4.8.5 Querying the Number of Attributes of a Vdata or a Vdata Field: VSfnattrs

VSfnattrs returns the number of attributes attached to the vdata field specified by the parameter field_index or the number of attributes attached to the vdata identified by vdata_id. This is different from the routine VSnattrs, which returns the total number of attributes of the specified vdata and the fields contained in it. The syntax of VSfnattrs is as follows:

C:		num_of_attrs = VSfnattrs(vdata_id, field_index);
FORTRAN:	num_of_attrs = vsffnas(vdata_id, field_index)
If field_index is set to a zero-based integer value, it will be used as the index of the vdata field, and the number of attributes attached to that field will be returned. If field_index is set to _HDF_VDATA (or -1), the number of attributes attached to the vdata specified by vdata_id will be returned.

VSfnattrs returns the number of attributes assigned to the specified vdata or to the specified vdata field when successful, and FAIL (or -1) otherwise. The parameters for VSfnattrs are described in Table 4L.

TABLE 4L - VSnattrs and VSfnattrs Parameter Lists

Routine Name

[Return Type]

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

[intn]

(vsfnats)
vdata_id
int32
integer
Vdata identifier

VSfnattrs

[int32]

(vsffnas)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
_HDF_VDATA or index of the field

4.8.6 Retrieving the Index of a Vdata or Vdata Field Attribute Given the Attribute Name: VSfindattr

VSfindattr returns the index of an attribute with the specified name. The attribute must be attached to either a vdata or one of its fields. The syntax of VSfindattrs is as follows:

C:		attr_index = VSfindattr(vdata_id, field_index, attr_name);
FORTRAN:	attr_index = vsffdat(vdata_id, field_index, attr_name)
If field_index is set to _HDF_VDATA (or -1), the index of the attribute identified by the parameter attr_name and attached to the vdata specified by vdata_id will be returned.

If the parameter field_index is set to a zero-based integer value, the value will be used as the index of the vdata field. Then, the index of the attribute named by the parameter attr_name and attached to the field specified by the parameter field_index will be returned.

VSfindattr returns an attribute index if successful, and FAIL (or -1) otherwise. The parameters for VSfindattr are described in Table 4M on page 152.

4.8.7 Querying Information on a Vdata or Vdata Field Attribute: VSattrinfo

VSattrinfo returns the name, data type, number of values, and the size of the values of the specified attribute of the specified vdata field or vdata. The syntax of VSattrinfo is as follows:

C:		status = VSattrinfo(vdata_id, field_index, attr_index, attr_name, &data_type, &n_values, &size);
FORTRAN:	status = vsfainf(vdata_id, field_index, attr_index, attr_name, data_type, n_values, size)
In C, the parameters attr_name, data_type, n_values, and size can be set to NULL, if the information returned by these parameters are not needed.

The parameter field_index is the same as the parameter field_index in VSsetattr; it can be set either to a nonnegative integer to specify the field or to _HDF_VDATA (or -1) to specify the vdata referred to by vdata_id.

VSattrinfo returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The parameters for VSattrinfo are described in Table 4M.

4.8.8 Determining whether a Vdata Is an Attribute: VSisattr

The HDF library stores vdata attributes and vdata field attributes as vdatas. HDF therefore provides the routine VSisattr to determine whether a particular vdata contains attribute data. The syntax of VSisattr is as follows:

C:			status = VSisattr(vdata_id);
FORTRAN:	status = vsfisat(vdata_id)
VSisattr returns TRUE (or 1) if the vdata contains an attribute data and FALSE (or 0) otherwise. The parameters for VSisattr are described in Table 4M.

TABLE 4M - VSfindattr, VSattrinfo, and VSisattr Parameter Lists

Routine Name

[Return Type]

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

[intn]

(vsffdat)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
_HDF_VDATA or index of the field

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

VSattrinfo

[intn]

(vsfainf)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
Index of the field

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
Number of values of the attribute

size
int32 *
integer
Size, in bytes, of the values of the attribute

VSisattr

[intn]

(vsfisat)
vdata_id
int32
integer
Vdata identifier

EXAMPLE 8. Operations on Field and Vdata Attributes

This example illustrates the use of VSsetattr/vsfscat/vsfsnat to attach an attribute to a vdata and to a field in a vdata, the use of VSattrinfo/vsfainf to get information about a field attribute and a vdata attribute, and the use of VSgetattr/vsfgcat/vsfgnat to get the values of an attribute of a vdata and the values of an attribute of a field in a vdata. The example also shows the use of VSfnattrs/vsffnas to obtain the number of attributes attached to a field of a vdata and the use of VSnattrs/vsfnats to obtain the total number of attributes attached to both a vdata and its fields.

In this example, the program finds the vdata, named "Solid Particle", in the HDF file "General_Vdatas.hdf" produced by Example 3. It then obtains the index of the field, named "Mass", in the vdata. An attribute named "Site Ident" is attached to the vdata to contain the identification of the experiment sites. Another attribute named "Scales" is attached to the field for its scale values. The vdata attribute has 3 character values and the field attribute has 4 integer values.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.