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

1.8 Obtaining Information About the Contents of a Vgroup

When the target vgroup has been located, a way to determine its internal structure is needed. The HDF routines necessary to perform this operation are listed here, along with their syntax:

C:		num_of_elems = Vntagrefs(vgroup_id);
		status = Vgettagref(vgroup_id, index, tag, ref);
		num_of_pairs = Vgettagrefs(vgroup_id, tag_array, ref_array, 
			maxsize);
		true_false = Vinqtagref(vgroup_id, tag, ref);
		true_false = Visvg(vgroup_id, vgroup_ref);
		true_false = Visvs(vgroup_id, vdata_ref);

FORTRAN:	num_of_elems = vfntr(vgroup_id)
		status = vfgttr(vgroup_id, index, tag, ref)
		num_of_pairs = vfgttrs(vgroup_id, tag_array, ref_array, maxsize)
		true_false = vfinqtr(vgroup_id, tag, ref)
		true_false = vfisvg(vgroup_id, vgroup_ref)
		true_false = vfisvs(vgroup_id, vdata_ref)

Each routine queries a specific item of vgroup information. The parameters of these routines are described below. (See Table 5K on page 164.)

1.8.1 Returning the Tag/Reference Number Pairs of Vgroup Members: Vntagrefs, Vgettagref and Vgettagrefs

Vntagrefs returns the number of members stored in the specified vgroup. This routine is used together with Vgettagrefs or in a loop with Vgettagref to identify the HDF objects linked to a given vgroup.

Vgettagref returns the tag/reference number pair of a specified HDF object stored within the vgroup in the tag and ref parameters respectively. The parameter index specifies the location of the member within the vgroup and is zero-based.

Vgettagrefs returns the tags/reference number pairs of the vgroup members in arrays. The tag/reference number pairs are returned in the parameters tag_array and ref_array. The parameter maxsize specifies the maximum number of tag/reference number pairs to return, therefore each array must be at least maxsize in size.

1.8.2 Returning Vgroup Member Information: Vinqtagref, Visvg and Visvs

Vinqtagref returns TRUE (or 1) if the data object with tag/reference number pair specified by the tag and ref parameters are a member of the vgroup and FALSE (or 0) otherwise.

Visvg returns TRUE (or 1) if the vgroup reference number specified by the vgroup_ref parameter is that of a vgroup stored in the vgroup, and FALSE (or 0) otherwise.

Visvs returns TRUE (or 1) if the vdata reference number specified by the vdata_ref parameter is that of a vdata stored in the vgroup, and FALSE(or 0) otherwise.

TABLE 5K Vgetname, Vgetclass, Visvg and Visvs Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vntagrefs

(vfntr)

vgroup_id

int32

integer

Vgroup identifier.

Vgettagref

(vfgttr)

vgroup_id

int32

integer

Vgroup identifier.

index

int32

integer

Index of the tag/reference number pair tobe retrieved.

tag

int32

integer

Pointer to the tag.

ref

int32

integer

Pointer to the reference number.

Vgettagrefs

(vfgttrs)

vgroup_id

int32

integer

Vgroup identifier.

tag_array

int32 *

integer

Buffer for the returned tags.

ref_array

int32 *

integer

Buffer for the returned reference numbers.

maxsize

int32

integer

Maximum number of tag/reference numbrr pairs to be returned.

Vinqtagref

(vfinqtr)

vgroup_id

int32

integer

Vgroup identifier.

tag

int32

interger

Tag of item to be queried.

ref

int32

integer

Reference number of items to be queried.

Visvg

(vfisvg)

vgroup_id

int32

integer

Vgroup identifier.

vgroup_ref

int32

integer

Vgroup reference number to be queried.

Visvs

(vfisvs)

vgroup_id

int32

integer

Vgroup identifier.

vdata_ref

int32

integer

Vdata reference number to be queried.

EXAMPLE 6. Extracting the Tag/Reference Number Pairs of Vgroup Members

The following examples make use of Vntagrefs to determine the number of tag/reference number pairs assigned to the members of a vgroup. It then uses Vgettagref to extract each tag/reference number pair.

C:

#include "hdf.h"

main( )
{
	int32 file_id;
	int32 vgroup_id, vgroup_ref;
	int32 vdata_tag, vdata_ref;
	int32 status, i, npairs;

	/* Open the "Example2.hdf" file. */
	file_id = Hopen("Example2.hdf", DFACC_READ, 0);

	/* Initialize HDF for subsequent vgroup/vdata access. */
	status = Vstart(file_id);

	/* Attach to every vgroup in the file. */
	vgroup_ref = -1;

	while (TRUE) {
	   vgroup_ref = Vgetid(file_id, vgroup_ref);
	   if (vgroup_ref == -1) break;
	   vgroup_id = Vattach(file_id, vgroup_ref, "r"); 

	   /* Get the total number of tag/reference id pairs. */
	   npairs = Vntagrefs(vgroup_id);

	   /* Print every tag and reference id with their 
	   corresponding file position. */
	   for (i = 0; i < npairs; i++) {
	      status = Vgettagref(vgroup_id, i, &vdata_tag, &vdata_ref);
	      printf("Found tag = %d, ref = %d at position %d.\n", \
	              vdata_tag, vdata_ref, i+1);
	   }

	   /* Terminate access to the vgroup. */
	   status = Vdetach(vgroup_id);
	}

	/* Terminate access to the V interface and close the file. */
	status = Vend(file_id);
	status = Hclose(file_id);

}

FORTRAN:

PROGRAM EXTRACT TAG


      integer*4 file_id, vgroup_id, vgroup_ref, vdata_tag
      integer*4 vdata_ref, npairs
      integer i, status
      integer hopen, vfatch, vfntr, vfgttr
      integer vfgid, vfdtch, hclose, vfstart, vfend
      integer*4 DFACC_READ
      parameter (DFACC_READ = 1)

C     Open an HDF file with read-only access. 
C     DFACC_READ is defined in hdf.inc.
      file_id = hopen('Example2.hdf', DFACC_READ, 0)

C     Initialize HDF for subsequent vgroup/vdata access. 
      status = vfstart(file_id)

C     Attach to every vgroup in the file. 
      vgroup_ref = -1
30    vgroup_ref = vfgid(file_id, vgroup_ref)

      if (vgroup_ref .eq. -1) then
        go to 20
      else
        vgroup_id = vfatch(file_id, vgroup_ref, 'r') 
C       Get the total number of tag/reference id pairs. 
        npairs = vfntr(vgroup_id)
C       Print every tag and reference id with their 
C       corresponding file position.
        do 10 i = 1, npairs
          status = vfgttr(vgroup_id, i-1, vdata_tag, vdata_ref)
          if (status .eq. -1) then
            go to 40
          end if
          print *, 'Found tag = ', vdata_tag, ' ref = ', vdata_ref,  
     +             ' at position ', i

10      continue   

C       Terminate access to the vgroup. 
40      status = vfdtch(vgroup_id)
      end if
      go to 30

C     Terminate access to the V interface and close the file. 
20    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.