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).
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.
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.
VSsetattr returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The parameters for VSsetattr are described in Table 4K.
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.
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.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.
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.
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.
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.
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.
FORTRAN-77 version