[Top] [Prev] [Next]

4.7 Searching for Vdatas in a File

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

4.7.1 Finding All Vdatas that are Not Members of a Vgroup: VSlone

A lone vdata is one that is not a member of a vgroup. Vgroups are HDF objects that contain sets of HDF objects, including vgroups. Vgroups are described in Chapter 5, Vgroups (V API).

VSlone searches an HDF file and retrieves the reference numbers of lone vdatas in the file. The syntax of VSlone is as follows:

C:		num_of_lone_vdatas = VSlone(file_id, ref_array, maxsize);
FORTRAN:	num_of_lone_vdatas = vsflone(file_id, ref_array, maxsize)
The parameter ref_array is an array allocated to hold the retrieved reference numbers of lone vdatas and the argument maxsize 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 are expected in the file. A size of MAX_FIELD_SIZE (or 65535) 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.

VSlone returns the number of lone vdatas or FAIL (or -1). The parameters for VSlone are listed in Table 4I on page 146.

4.7.2 Sequentially Searching for a Vdata: VSgetid

VSgetid sequentially searches through an HDF file to obtain the vdata immediately following the vdata specified by the reference number in the parameter vdata_ref. The syntax of VSgetid is as follows:

C:		ref_num = VSgetid(file_id, vdata_ref);
FORTRAN:	ref_num = vsfgid(file_id, vdata_ref)
To obtain the reference number of the first vdata in the file, the user must set the parameter vdata_ref to -1. Thus, VSgetid can be repeatedly called, with the initial value of vdata_ref set to -1 so that the routine will sequentially return the reference number of each vdata in the file, starting from the first vdata. After the last vdata is reached, subsequent calls to VSgetid will return FAIL (or -1).

VSgetid returns a vdata reference number or FAIL (or -1). The parameters for VSgetid are listed in Table 4I on page 146.

4.7.3 Determining a Reference Number from a Vdata Name: VSfind

VSfind searches an HDF file for a vdata with the specified name and returns the vdata reference number. The syntax of VSfind is as follows:

C:		ref_num = VSfind(file_id, vdata_name);
FORTRAN:	ref_num = vsffnd(file_id, vdata_name)
The parameter vdata_name is the search key. Although there may be several identically named vdatas in the file, VSfind will only return the reference number of the first vdata in the file with the specified name.

VSfind returns either the vdata reference number if the named vdata is found or 0 otherwise. The parameters for VSfind are listed in Table 4I.

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 vdatas containing particular field names. The syntax of the VSfexist function is as follows:

C:		status = VSfexist(vdata_id, fieldname_list);
FORTRAN:	status = vsfex(vdata_id, fieldname_list)
The parameter fieldname_list is a string of comma-separated field names containing no white space, for example, "PX,PY,PZ".

VSfexist returns SUCCEED (or 0) if all of the fields specified in the parameter fieldname_list are found and FAIL (or -1) otherwise. The parameters for VSfexist are listed in Table 4I.

TABLE 4I - VSlone, VSgetid, VSfind, and VSfexist Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
VSlone

[int32]

(vsflone)
file_id
int32
integer
File identifier

ref_array
int32 []
integer (*)
Buffer for a list of lone vdata reference numbers

maxsize
int32
integer
Maximum number of reference numbers to be buffered

VSgetid

[int32]

(vsfgid)
file_id
int32
integer
File identifier

vdata_ref
int32
integer
Reference number of the vdata preceding the vdata

VSfind

[int32]

(vsffnd)
file_id
int32
integer
File identifier

vdata_name
char *
character*(*)
Name of the vdata to find

VSfexist

[intn]

(vsfex)
vdata_id
int32
integer
Vdata identifier

fieldname_list
char *
character*(*)
Names of the fields to be queried

EXAMPLE 7. Locating a Vdata Containing Specified Field Names

This example illustrates the use of VSgetid/vsfgid to obtain the reference number of each vdata in an HDF file and the use of VSfexist/vsfex to determine whether a vdata contains specific fields.

In this example, the program searches the HDF file "General_Vdatas.hdf" to locate the first vdata containing the fields "Position" and "Temperature". The HDF file is an output of the program in Example 3.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 05/19/99, NCSA HDF Development Group.