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.
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.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
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.
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. values must be sufficiently allocated to hold the retrieved attribute values. Use VSattrinfo to obtain information about the attribute values for appropriate memory allocation.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
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.FAIL (or -1) otherwise. The parameters for VSfnattrs are described in Table 4L.
TABLE 4L - VSnattrs and VSfnattrs Parameter Lists
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.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.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
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