[Top] [Prev] [Next] [Bottom]

4.8 Vdata Attributes

Version 4.1r1 of HDF includes the capability of assigning attributes to a vdata and/or a vdata field. The concept of attributes is fully explained in Chapter 3, titled 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, a field attribute name must be unique among all attributes of that field, and a vdata attribute name must be unique among all attributes of the vdata it's contained in.

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

VSfindex returns the index of specified field given the field name. It returns SUCCEED if successful, and FAIL otherwise.

TABLE 4I VSfindex Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSfindex

(vsffidx)

vdata_id

int32

integer

Vdata identifier.

field_name

char *

character* (*)

Name of the target vdata field.

field_index

int32 *

integer

Index of the target vdata field.

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

VSsetattr attaches an attribute to a vdata field or a vdata. If the attribute already exists, the new values will replace the current ones, provided the data type and order have not been changed. If either the data type or the order have been changed, VSsetattr will exit on an error condition.

The field_index parameter is zero-based, and represents the ordinal location of the field within the vdata - for example, a field_index value of 4 would refer to the fifth field in the vdata. If field_index is set to _HDF_VDATA, the attribute of the specified vdata will be set to the value pointed to by values. When using either Fortran-77 version of this routine, specify a field_index value of -1 to attach an attribute to the specified vdata.

VSsetattr returns SUCCEED if successful, FAIL otherwise.

TABLE 4J VSsetattr Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSsetattr

(vsfsnat/vsfscat)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Vdata field index.

attr_name

char *

character* (*)

Name of the attribute.

data_type

int32

integer

Data type of the attribute.

count

int32

integer

Number of values the attribute contains.

values

VOIDP

integer (*)/character* (*)

Buffer containing the attribute values.

4.8.3 Querying the Total Number of Vdata Attributes: VSnattrs

VSnattrs returns the number of attributes of the specified vdata and the vdata fields contained in it. This is different from the VSfnattrs routine, which returns the number of attributes of a field contained in the specified vdata or the specified vdata.

VSnattrs returns total number of attributes assigned to this vdata and its fields when successful, and FAIL otherwise

TABLE 4K VSnattrs Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSnattrs

(vsfnats)

vdata_id

int32

integer

Vdata identifier.

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

VSfnattrs returns the number of attributes attached to the specified vdata field or the number of attributes attached to the vdata identified by vdata_id. This is different from the VSnattrs routine, which returns the number of attributes of the specified vdata and the fields contained in it.

If field_index is set to _HDF_VDATA, the number of attributes attached to the vdata referred to by the value of vdata_id is returned. When using the Fortran-77 version of this routine, specify a field_index value of -1 to return the number of vdata attributes.

As with VSsetattr, if field_index is set to a zero-based integer value, it will be used as the index of the target vdata field, and the attributes attached to that field will be returned.

VSfnattrs returns number of attributes assigned to this vdata or its fields when successful, and FAIL otherwise.

TABLE 4L VSfnattrs Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSfnattrs

(vsffnas)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Index of the target field.

4.8.5 Retrieving the Index of a Vdata Attribute Given the Attribute Name: VSfindattr

VSfindattr returns the index of an attribute with the specified name. The attribute must to attached to the vdata identified by the the specified vdata identifier.

If field_index is set to _HDF_VDATA, the index of the attribute attached to the vdata referred to by the value of vdata_id is returned. When using the Fortran-77 version of this routine, specify a field_index value of -1 to return the vdata attribute indices.

As with VSsetattr, if field_index is set to a zero-based integer value, the value will be used as the index of the target vdata field, and the index of the attribute with the name specifiedby the attr_name parameter will be returned.

VSfindattr returns the index of the target attribute if successful, and FAIL otherwise.

TABLE 4M VSfindattr Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSfindattr

(vsffdat)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Index of the target field.

attr_name

char *

character* (*)

Name of the target attribute.

4.8.6 Querying Information on a Given Vdata 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 values of the attr_name, data_type, count and size parameters can be set to NULL, if the information returned by these parameters are not needed.

The field_index in VSattrinfo is the same as with the field_index parameter in VSsetattr. It can be set to either a integer field index, or _HDF_VDATA to specify the vdata referred to by vdata_id.

VSattrinfo returns SUCCEED if successful, and FAIL otherwise.

TABLE 4N VSattrinfo Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSattrinfo

(vsfainf)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Index of the target field

attr_index

intn

integer

Index of the target attribute.

attr_name

char *

character* (*)

Returned name of the target attribute.

data_type

int32 *

integer

Returned data type of the target attribute.

count

int32 *

integer

Number of values of the target attribute.

size

int32 *

integer

Size, in bytes, of the values of the target attribute.

4.8.7 Querying the Values of a Given Vdata Attribute: VSgetattr

VSgetattr returns all of the values of the specified attribute of the specified vdata field or vdata.

The attr_index parameter is the ordinal, zero-based (as with field_index in VSsetattr and this routine) index of the target attribute.

If field_index is set to _HDF_VDATA, the value of the attribute attached to the vdata referred to by the value of vdata_id is returned. If field_index is set to a zero-based integer value, the value will be used as the index of the target vdata field, and the attribute located at the ordinal position specified by attr_index will be returned.

VSgetattr returns SUCCEED if successful, FAIL otherwise.

TABLE 4O VSgetattr Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSgetattr

(vsfgnat/vsfgcat)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Index of the target field.

attr_index

intn

integer

Index of the target attribute.

values

VOIDP

<valid numeric data type>

Buffer containing attribute values.

4.8.8 Determining if the Given Vdata is an Attribute: VSisattr

As attributes are stored by the HDF library as vdatas, a means of testing whether or not a particular vdata is attribute data is provided by the VSisattr routine.

VSisattr returns TRUE if the vdata is an attribute, and FALSE otherwise.

TABLE 4P VSisattr Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSisattr

(vsfisat)

vdata_id

int32

integer

Vdata identifier.

EXAMPLE 7. Attaching and Querying Vdata Attributes

These examples attach an attribute to the vdata created in Example 3 (in the file named "Example3.hdf") and to the first field of that vdata. Then it checks the number of attributes in the file and reads the attribute data.

C:

#include "hdf.h"
#include "vg.h"

#define FILE_NAME "Example3.hdf"
#define VATTR_NAME "Vdata Attribute 1"
#define FATTR_NAME "Field Attribute 1"

main( )
{

	int32 file_id, vdata_ref, vdata_id, status;
	int32 n_vdattrs, n_fldattrs;
	int32 v_type, v_count, v_size, f_type, f_count, f_size;
	char vd_attr[6] = {`m','N','p', `S', `t', `\0'};
	char vattr_buf[6];
	char vattrname[30], fattrname[30];
	float32 fld_attr[2] = {30.452, 5.467};
	float32 fattr_buf[2];
	
	/* Open the HDF file. */
	file_id = Hopen(FILE_NAME, DFACC_RDWR, 0);

	/* Initialize the vdata interface. */
	status = Vstart(file_id);

	/* Get the reference number of the target vdata. */
	vdata_ref = VSfind(file_id, "Example Vdata");

	/* Attach to the target vdata. */
	vdata_id = VSattach(file_id, vdata_ref, "w");

	/* Attach an attribute to the vdata. */
	status = VSsetattr(vdata_id, _HDF_VDATA, VATTR_NAME, DFNT_CHAR,\
						6, vd_attr);

	/* Attach an attribute to the first field in the vdata. */
	status = VSsetattr(vdata_id, 0, FATTR_NAME, DFNT_FLOAT32, 2, 
				fld_attr);

	/* Get the number of attributes attached to the first field - 
	should be 1. */
	n_fldattrs = VSfnattrs(vdata_id, 0);

	/* Get the total number of field and vdata attributes. 
	This should be 2. */
	n_vdattrs = VSnattrs(vdata_id);

	/* Get information about the vdata attribute. */
	status = VSattrinfo(vdata_id, _HDF_VDATA, 0, vattrname, \
    			&v_type, &v_count, &v_size);

	/* Get information about the field attribute. */
	status = VSattrinfo(vdata_id, 0, 0, fattrname, &f_type, 
				&f_count, &f_size);

	/* Get the vdata attribute. */
	status = VSgetattr(vdata_id, _HDF_VDATA, 0, vattr_buf);

	/* Get the field attribute. */
	status = VSgetattr(vdata_id, 0, 0, fattr_buf);

	/* Detach from the vdata, close the VS interface and the file. */
	status = VSdetach(vdata_id);
	status = Vend(file_id);
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM CREATE QUERY ATTRS

      integer file_id, vdata_ref, vdata_id, status
      integer n_fldattrs, n_vdattrs
      integer hopen, vfstart, vsffnd, vsfatch, vsfdtch, hclose
      integer vfend, vsfscat, vsfsnat, vsffnas, vsfnats
      integer vsfainf, vsfgnat, vsfgcat
      integer v_type, v_count, v_size, f_type, f_count, f_size
      double precision fld_attr(2), fattr_buf(2)
      character*20 vattrname, vattr_buf
      character*50 filename, vd_attr, fattr_name
      parameter (filename = `Example3.hdf',
     +      vattr_name = `Vdata Attribute 1',
     +      vd_attr = `mnpst',
     +      fattr_name = `Field Attribute 1'
     +     	) 

C     The following parameters are defined in hdf.inc.
      integer DFACC_RDWR, DFNT_CHAR, DFNT_FLOAT32, _HDF_VDATA
      parameter (DFACC_RDWR = 3, DFNT_CHAR = 4, DFNT_FLOAT32 = 5,
     +           _HDF_VDATA = -1)

      fld_attr(1) = 30.452
      fld_attr(2) = 5.467

C     Open an HDF file with full access. 
      file_id = hopen(filename, DFACC_RDWR, 0)

C     Initialize the VS interface. 
      status = vfstart(file_id)

C     Get the reference number of the target vdata. 
      vdata_ref = vsffnd(file_id, `Example Vdata')

C     Attach to the target vdata. 
      vdata_id = vsfatch(file_id, vdata_ref, `w')

C     Attach an attribute to the vdata. 
      status = vsfscat(vdata_id, _HDF_VDATA, vattr_name, 
     +                 DFNT_CHAR, 5, vd_attr)

C     Attach an attribute to the first field of the vdata. 
      status = vsfsnat(vdata_id, _HDF_VDATA, fattr_name, 
     +                 DFNT_FLOAT32, 2, fld_attr)

C     Get the number of attributes attached to the first field. 
      n_fldattrs = vsffnas(vdata_id, 0)

C     Get the total number of field and vdata attributes. 
      n_vdattrs = vsfnats(vdata_id)

C     Get information about the vdata attribute. 
      status = vsfainf(vdata_id, _HDF_VDATA, 0, vattrname, 
     +               v_type, v_count, v_size)

C     Get information about the field attribute. 
      status = vsfainf(vdata_id, 0, 0, vattrname, f_type, 
     +               f_count, f_size)

C     Get the vdata attribute. 
      status = vsfgnat(vdata_id, _HDF_VDATA, 0, vattr_buf)

C     Get the field attribute. 
      status = vsfgcat(vdata_id, 0, 0, fattr_buf)

C     Detach from the vdata, close the VS interface and the file.
      status = vsfdtch(vdata_id)
      status = vfend(file_id)
      status = hclose(file_id)

      end




[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.