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

1.7 Vgroup Attributes

Version 4.1r1 of HDF includes the capability of assigning attributes to a vgroup. 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 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.

1.7.1 Querying Information on a Given Vgroup Attribute: Vattrinfo

Vattrinfo returns the name, data type, number of values, and the size of the values of the specified attribute of the specified vgroup.

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 value of attr_index parameter is used as the index of the target vgroup attribute, and is zero-based. For example, a attr_index value of 4 would refer to the fifth attribute of the vgroup.

Vattrinfo returns SUCCEED if successful, and FAIL otherwise.

TABLE 5E Vattrinfo Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vattrinfo

(vfainfo)

vgroup_id

int32

integer

Vgroup identifier.

attr_index

intn

integer

Index of the target attribute..

name

char *

character* (*)

Returned name of the target attribute.

data_type

int32 *

integer

Returned data type of the target attribute.

count

int32 *

integer

Returned number of values of the target attribute.

size

int32 *

integer

Returned size, in bytes, of the values of the target attribute.

1.7.2 Querying the Vgroup Version of a Given Vgroup: Vgetversion

Vgetversion returns the vgroup version number of the specified vgroup. 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 don't support attributes.

The newest version is version 4, which is the only version that supports vgroup attributes. Vgetversion returns a value of VSET_NEW_VERSION when encountering a vgroup of this vgroup version. Version 3 is the vgroup version corresponding to all versions of the HDF library between 3.2 and 4.0 release 2. Vgetversion returns a value of VSET_VERSION when encountering a vgroup of this vgroup version. The third version is version 2. This vgroup version corresponds to all HDF library versions before version 3.2, and Vgetversion returns a value of VSET_OLD_VERSION when encountering a vgroup of this vgroup version.

Vgetversion returns the vset version number if successful, and FAIL otherwise.

TABLE 5F Vgetversion Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vgetversion

(vfgver)

vgroup_id

int32

integer

Vgroup identifier.

1.7.3 Querying the Total Number of Vgroup Attributes: Vnattrs

Vnattrs returns number of attributes assigned to this vgroup and its fields when successful, and FAIL otherwise.

TABLE 5G Vnattrs Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vnattrs

(vfnatts)

vgroup_id

int32

integer

Vgroup identifier.

1.7.4 Querying the Values of a Given Vgroup Attribute: Vgetattr

Vgetattr returns all of the values of the specified attribute of the specified vgroup.

The attr_index parameter is the ordinal, zero-based index of the target attribute.

Vgetattr returns SUCCEED if successful, FAIL otherwise.

TABLE 5H Vgetattr Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vgetattr

(vsgnatt/vsgcatt)

vgroup_id

int32

integer

Vgroup identifier.

attr_index

intn

integer

Index of the target attribute.

values

VOIDP

<valid numeric data type>

Buffer containing attribute values.

1.7.5 Setting the Attribute of a Vgroup: Vsetattr

Vsetattr attaches an attribute to a vgroup. 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, Vsetattr will exit on an error condition.

Vsetattr returns SUCCEED if successful, FAIL otherwise.

TABLE 5I Vsetattr Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vsetattr

(vfsatt/vfscatt)

vgroup_id

int32

integer

Vgroup identifier.

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

<valid numeric data type>

Buffer containing the attribute values.

1.7.6 Retrieving the Index of a Vgroup Attribute Given the Attribute Name: Vfindattr

Vfindattr returns the index of an attribute with the given name, specified by the value of the attr_name parameter, of a vgroup.

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

TABLE 5J Vfindattr Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vfindattr

(vffdatt)

vgroup_id

int32

integer

Vgroup identifier.

attr_name

char *

character* (*)

Name of the target attribute.

EXAMPLE 5. Attaching and Querying Vgroup Attributes

These examples attach an attribute to the vgroup created in Example 1 (in the file named "Example1.hdf"). Then it checks the number of attributes in the file, the version of the vgroup and then reads the attribute data.

C:

#include "hdf.h"

#define FILE_NAME "Example1.hdf"
#define VGATTR_NAME "Vgroup Attribute 1"

main( )
{

	int32 file_id, vgroup_ref, vgroup_id, status;
	int32 vg_version;
	int32 v_type, v_count, v_size;
	char vg_attr[6] = {'m','N','p', 'S', 't', '\0'};
	char vgattr_buf[6], vattrname[30];

	/* Open the HDF file. */
	file_id = Hopen(FILE_NAME, DFACC_RDWR, 0);

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

	/* Get the reference number of the target vgroup. */
	vgroup_ref = Vfind(file_id, "VG_Name_1");

	/* Attach to the target vgroup. */
	vgroup_id = Vattach(file_id, vgroup_ref, "w");

	/* Get the version of the vgroup just created. */
	vg_version = Vgetversion(vgroup_id);

	/* Attach an attribute to the vgroup. */
	status = Vsetattr(vgroup_id, VGATTR_NAME, DFNT_CHAR, 
				6, vg_attr);

	/* Get information about the vgroup attribute. */
	status = Vattrinfo(vgroup_id, 0, vattrname, &v_type, 
				&v_count, &v_size);

	/* Get the vgroup attribute. */
	status = Vgetattr(vgroup_id, 0, vgattr_buf);

	/* Detach from the vgroup, close the V interface and the file. */
	status = Vdetach(vgroup_id);
	status = Vend(file_id);
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM CREATE QUERY ATTRS

      integer file_id, vgroup_ref, vgroup_id, status
      integer vg_version
      integer hopen, vfstart, vfind, vfatch, vfdtch, hclose
      integer vfend, vsgver, vfgcatt, vfainfo, vfscatt
      integer v_type, v_count, v_size
      character*20 vgattrname, vgattr_buf
      character* (*) filename, vgattr_name, vg_attr
      parameter (filename = 'Example1.hdf',
     +   vgattr_name = 'Vgroup Attribute 1',
     +   vg_attr = 'mnpst'
     +    ) 

C     The following parameters are defined in hdf.inc.
      integer DFACC_RDWR, DFNT_CHAR
      parameter (DFACC_RDWR = 3, DFNT_CHAR = 4)

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

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

C     Get the reference number of the target vgroup. 
      vgroup_ref = vfind(file_id, 'VG_Name_1')

C     Attach to the target vdata. 
      vgroup_id = vfatch(file_id, vgroup_ref, 'w')

C     Get the version of the vgroup just created. 
      vg_version = vsgver(vgroup_id)

C     Attach an attribute to the vgroup. 
      status = vfscatt(vgroup_id, vgattr_name, DFNT_CHAR, 5, vg_attr)

C     Get information about the vgroup attribute. 
      status = vfainfo(vgroup_id, 0, vgattrname, v_type, v_count,
     +                 v_size)

C     Get the vgroup attribute. 
      status = vfgcatt(vgroup_id, 0, vgattr_buf)

C     Detach from the vgroup, close the V interface and the file.
      status = vfdtch(vgroup_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.