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

4.7 Searching for Vdatas in a File

There are several HDF routines that perform searches for a specific vdata in a file. In this section we introduce these four routines and in the following section methods for obtaining information about the members of a given vdata is described.

4.7.1 Finding All Vdatas that are Not Members of Vgroups: VSlone

A lone vdata is one that is not a member of a vgroup. The function VSlone returns the total number of lone vdatas. The parameter ref_array is an array allocated to hold the reference numbers of all lone vdatas in a file and the maxsize argument specifies the maximum size of ref_array. At most maxsize reference numbers will be returned in ref_array.

The space that should be allocated for ref_array is dependent upon on how many lone vdatas you expect to find. 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 VSlone with maxsize set to a small value like 0 or 1, then use the returned value to allocate memory for ref_array to be passed to a subsequent call to VSlone.

The syntax of the VSlone function is as follows:

	num_of_lone_vdatas = VSlone(file_id, ref_array, maxsize);

4.7.2 Searching for the Reference Number of a Vdata: VSgetid

VSgetid sequentially searches for vdata reference numbers in an HDF file. It returns the reference number for the vdata immediately following the vdata with the reference number vdata_ref. To initiate a search, VSgetid may be called using vdata_ref = -1. Doing so returns the reference number of the first vdata in the file. Searching past the last vdata in a file will return FAIL (or -1).

The syntax of the VSgetid function is as follows:

	ref_num = VSgetid(file_id, vdata_ref);

4.7.3 Determining a Reference Number from a Vdata Name: VSfind

VSfind checks an HDF file for a vdata with the specified name and returns its reference number if it is found or FAIL (or -1) if not. The parameter vdata_name is the search key. Although there may be several identically named vdatas in a file, VSfind will only return the reference number of the first vdata in the file with the specified name.

The syntax of the VSfind function is as follows:

	ref_num = VSfind(file_id, vdata_name);

4.7.4 Searching for a Vdata by Field Name: VSfexist

VSfexist queries a vdata for a set of specified field names and is often useful for locating vdata objects containing particular field names. Its return value is 1 if successful. The fields parameter is a string of comma-separated field names containing no white space - for example, "PX,PY,PZ".

The syntax of the VSfexist function is as follows:

	status = VSfexist(vdata_id, fields);

To review, VSfind searches for a vdata with a specified name and returns its reference number if found. Given the reference number of the target vdata, VSfexist determines whether certain field names exist in it.

TABLE 4H VSlone, VSgetid, VSfind and VSfexist Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSlone

(vsflone)

file_id

int32

integer

File identifier.

ref_array

int32 []

integer (*)

Buffer for a list of vdata reference numbers.

maxsize

int32

integer

Maximum number of reference numbers to be buffered.

VSgetid

(vsfgid)

file_id

int32

integer

File identifier.

vdata_ref

int32

integer

Reference number of the vdata preceding the target vdata.

VSfind

(vsffnd)

file_id

int32

integer

File identifier.

vdata_name

char *

character* (*)

Name of the vdata to find.

VSfexist

(vsfex)

vdata_id

int32

integer

Vdata identifier.

fields

char *

character* (*)

Names of the fields to be queried.

EXAMPLE 6. Locating a Vdata from a Specified Field Name

The following examples search all vdatas in an HDF file for the first vdata containing the field names "Temp" and "Ident".

C:

#include "hdf.h"

#define FILE_NAME "Example4.hdf"

main( )
{

	int32 file_id, vdata_ref, vdata_id, status;
	int8 found_fields;

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

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

	vdata_ref = -1;
	found_fields = 0;

	/* Attach to each vdata and search for the fields. */ 
	while ((vdata_ref = VSgetid(file_id, vdata_ref)) != -1) {
	   vdata_id = VSattach(file_id, vdata_ref, "r");
	   if ((status = VSfexist(vdata_id, "Temp,Speed,Height,Ident")) 
				!= FAIL) {
	      found_fields = 1;
	      break;
	   } else status = VSdetach(vdata_id);
	}

	if (!found_fields) 
		printf("Fields TEMP and IDENT were not found.\n");
	else printf("Fields TEMP and IDENT found in vdata id %d\n", 
			vdata_ref);

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

}

FORTRAN:

	 PROGRAM SCAN VDATAS

      integer file_id, vdata_ref
      logical found_fields
      integer vdata_id, status
      integer hopen, vsfgid, vsfatch, vsfex, vsfdtch, hclose
      integer vfstart, vfend

C     DFACC_RDONLY is defined in hdf.inc.
      integer DFACC_RDONLY
      parameter (DFACC_RDONLY = 1)

C     Open an HDF file with full access. 
      file_id = hopen(`Example4.hdf', DFACC_RDONLY, 0)

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

      vdata_ref = -1
      found_fields = .FALSE.

C     Attach to each vdata and search for the fields. 
30    vdata_ref = vsfgid(file_id, vdata_ref)
      if (vdata_ref .ne. -1) then
        vdata_id = vsfatch(file_id, vdata_ref, `r')
        status = vsfex(vdata_id, `Temp,Ident')
        if (status .eq. 1) then
          found_fields = .TRUE.
          go to 20
        else
          status = vsfdtch(vdata_id)
          go to 30
        end if 
      end if

20    if (found_fields .eq. .FALSE.) then
        print *, `Fields TEMP and IDENT were not found.'
      else 
        print *, `Fields TEMP and IDENT found in vdata id `, 
     +           vdata_id
      end if

C     Detach from the vdata, close the Vset 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.