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

1.6 Reading from Vgroups

Reading from vgroups is more complicated than writing to vgroups. The process of reading from vgroups involves three steps:

1. Locate the appropriate vgroup.
2. Identify the members of the vgroup of interest.
3. Perform the read operation on the vgroup members.

1.6.1 Locating Vgroups in Files

There are several routines provided for the purpose of searching for a particular vgroup. The syntax for these routines are as follows.

C:		num_of_lones = Vlone(file_id, ref_array, maxsize);
		ref_num = Vgetid(file_id, vgroup_ref);
		status = Vgetname(vgroup_id, vgroup_name);
		status = Vgetclass(vgroup_id, vgroup_class);

FORTRAN:	num_of_lones = vflone(file_id, ref_array, maxsize)
		ref_num = vfgetid(file_id, vgroup_ref)
		status = vfgfnam(vgroup_id, vgroup_name)
		status = vfgcls(vgroup_id, vgroup_class)

1.6.1.1 Locating a Lone Vgroup: Vlone

A lone vgroup is one that is not a member of another vgroup. Vlone returns an array of reference numbers for all lone vgroups in a file. Vlone is useful for locating unattached vgroups in a file or the vgroups at the top of a grouping hierarchy. The parameter ref_array is an array allocated to hold the reference numbers. The maxsize argument specifies the maximum size of ref_array. At most maxsize reference numbers will be returned in ref_array. The value returned from Vlone is the total number of vgroups that are not linked to any other vgroup in the file.

The space allocated for ref_array depends on how many lone vgroups are expected to be found. A size of 32,767 integers is adequate to handle any case. To use dynamic memory instead of allocating such a large array, first call Vlone with maxsize set to a small value, for example, 0 or 1, then use the returned value to allocate memory for ref_array. This array is then to be passed to an argument of Vlone.

1.6.1.2 Determining the Next Vgroup Identifier: Vgetid

Vgetid sequentially searches through an HDF file to check vgroup reference numbers. It returns the reference number for the vgroup immediately following the vgroup with the reference number in the vgroup_ref parameter. To initiate a search, Vgetid may be called with vgroup_ref set to -1. Doing so returns the reference number of the first vgroup in the file. Any attempt to search past the last vgroup in a file will cause Vgetid to return a value of -1.

1.6.1.3 Determining a Vgroup's Name and Class: Vgetname and Vgetclass

Vgetname returns the name of the vgroup through the parameter vgroup_name. The maximum length of the name is defined by the macro VGNAMELENMAX.

Vgetclass returns the class of the vgroup through the parameter vgroup_class. The maximum length of the class name is defined by the macro VGNAMELENMAX.

TABLE 5D Vlone, Vgetid, Vgetname and Vgetclass Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vlone

(vflone)

file_id

int32

integer

File identifier.

ref_array

int32

integer

Buffer for the reference numbers of lone vgroups.

maxsize

int32

integer

Maximum number of vgroups to store in ref_array.

Vgetid

(vfgid)

file_id

int32

integer

File identifier.

vgroup_ref

int32

integer

Reference number of the previous vgroup.

Vgetname

(vfgnam)

vgroup_id

int32

integer

Vgroup identifier.

vgroup_name

char *

character* (*)

Buffer for the name of the vgroup.

Vgetclass

(vfgcls)

vgroup_id

int32

integer

Vgroup identifier.

vgroup_class

char *

character* (*)

Buffer for the vgroup class. (if any)

EXAMPLE 4. Printing Vgroup Reference Numbers

These examples obtain and print the reference numbers for all of the lone vgroups and the vdata objects in an HDF file.

C:

#include "hdf.h"

main( )
{

	int32 file_id, status;
	int32 vgroup_ref, vgroup_id;
	int32 maxsize, i, num_of_lones;
	int32 n_entries, *ref_array; 
	char vgroup_name[VGNAMELENMAX];

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

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

	/* Get and print the reference numbers of all the lone 
	vgroups.  First, call Vlone with maxsize set to 0 to 
	get the length of the storage array, then call Vlone 
	again to put the reference id numbers into the array. 	*/
	maxsize = Vlone(file_id, ref_array, 0);
	ref_array = (int32 *) HDmalloc(sizeof(int32) * maxsize);
	num_of_lones = Vlone(file_id, ref_array, maxsize);

	for (i = 0; i < maxsize; i++)
	   printf("Lone vgroup reference id  %d\n", ref_array[i]); 

	printf("*******\n");
	HDfree(ref_array);

	/* Set the reference number variable to start the search
	at the first vgroup in the file. */ 
	vgroup_ref = -1;

	/* Print every reference id in the file. */ 
	while (TRUE) {
	   vgroup_ref = Vgetid(file_id, vgroup_ref);
	   if (vgroup_ref == -1) break; 
	   vgroup_id = Vattach(file_id, vgroup_ref, "r");
	   status = Vinquire(vgroup_id, &n_entries, vgroup_name);
       printf("Found vgroup with ref %d, number of entries %d, name 
%s\n", 
              vgroup_ref, n_entries, vgroup_name); 
       Vdetach(vgroup_id);
	} 

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

}

FORTRAN:

PROGRAM PRINT REFS


      integer*4 file_id, ref_array(31)
      integer vgroup_ref, vgroup_id, status
      integer n_entries, i
      character vgroup_name(64)
      logical loop_flag
      integer hopen, vflone, vfgid, vfatch, vfdtch
      integer vfinq, hclose, vfstart, vfend
      integer*4 DFACC_READ
      parameter (DFACC_READ = 1)

C     Open an HDF file with read 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     Get and print the reference numbers of all the lone 
C     vgroups. 
      status = vflone(file_id, ref_array, 30)
      do 10 i = 1, status
         print *, 'Lone vgroup reference id ', ref_array(i)
10    continue   

      print *, '*******'

C     Set the reference number variable to start the search
C     at the first vgroup in the file.
      vgroup_ref = -1

C     Print every reference id in the file.  
      loop_flag = .TRUE.
      if (loop_flag) then
20       vgroup_ref = vfgid(file_id, vgroup_ref)
        if (vgroup_ref .eq. -1) then 
          go to 30
        end if
        vgroup_id = vfatch(file_id, vgroup_ref, 'r')
        status = vfinq(vgroup_id, n_entries, vgroup_name)
        print *, 'Found vgroup with ref ', vgroup_ref, 
     +           ' number of entries ', n_entries, 
     +           ' name ', vgroup_name
        status = vfdtch(vgroup_id)
        goto 20
      end if 

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