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

4.9 Obtaining Information About a Specific Vdata

Once a vdata has been located, its contents must be determined. In this section three categories of routines that obtain vdata information are described:

4.9.1 Obtaining Vdata Information: VSinquire

VSinquire is a general inquiry routine used to request information about the contents of a vdata. It has the following syntax:

	status = VSinquire(vdata_id, n_records, interlace, fields, vdata_size,
		vdata_name);

The n_records parameter contains the returned number of records in the target vdata, the interlace parameter contains the returned interlace mode of the vdata contents, the fields parameter is a comma-separated list of the returned names of all fields in the vdata, the vdata_size parameter is the returned size, in bytes, of the vdata and the vdata_name parameter contains the returned name of the vdata.

If any of the parameters are set to NULL, the corresponding data is not returned.

The parameters of VSinquire are further defined in Table 4Q below.

TABLE 4Q VSinquire Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSinquire

(vsfinq)

vdata_id

int32

integer

Vdata identifier.

n_records

int32 *

integer

Number of records in the vdata.

interlace

int32 *

integer

Interlace mode.

fieldname_list

char *

character* (*)

Buffer for the returned list of field names.

vdata_size

int32 *

integer

Size in bytes of a vdata record.

vdata_name

char *

character* (*)

Name of the vdata.

EXAMPLE 8. Obtaining Vdata Information

The following examples search for the vdata named "Example Vdata".

C:

#include "hdf.h"

#define FILE_NAME "Example3.hdf"

main( )
{

	int32	 file_id, vdata_ref, vdata_id, status;
	int32	 n_records, interlace, vdata_size;
	char	 fields[30], vdata_name[VSNAMELENMAX];
	int8 	found_fields;

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

	/* Initialize the vdata 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");
	   	status = VSinquire(vdata_id, &n_records, &interlace, fields, 
                           &vdata_size, vdata_name);
		status = VSdetach(vdata_id);
	   if (!strncmp(vdata_name, "Example Vdata", 20)) {
	      found_fields = 1;
	      break;
	   } else VSdetach(vdata_id);
	}

	if (!found_fields) 
	   printf("Vdata name - Example Vdata - was not found.\n");
	else 
	   printf("Vdata name - Example Vdata - found, vdata id %d.\n", 
                         vdata_ref);

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

}

FORTRAN:

	 PROGRAM SEARCH VDATANAME

      integer*4 file_id, vdata_ref
      integer*4 n_records, interlace, vdata_size, vdata_id
      character fields *30, vdata_name *20
      logical found_fields
      integer hopen, vsfgid, vsfatch, vsfinq, vsfdtch, hclose

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

      character target_vdata_name *20
      parameter (target_vdata_name = `Example Vdata')

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

C     Initialize the VS interface. 
      call vfstart(file_id)

      vdata_ref = -1
      found_fields = .FALSE.

C     Attach to each vdata and search for the fields. 
10    vdata_ref = vsfgid(file_id, vdata_ref)
      if (vdata_ref .ne. -1) then
        vdata_id = vsfatch(file_id, vdata_ref, `r')
        status = vsfinq(vdata_id, n_records, interlace, fields, 
     +                 vdata_size, vdata_name)
			status = vsfdtch(vdata_id)

        if (vdata_name .eq. target_vdata_name) then
           found_fields = .TRUE.
           go to 20
        else 
				go to 10
        end if
      end if

20    if (found_fields .eq. .FALSE.) then
        print *, `Vdata name - Example Vdata - was not found'
      else 
        print *, `Vdata name - Example Vdata - found, vdata id `, 
     +            vdata_ref
      end if

C     Detach from the vdata, close the Vset interface and the file. 
      status = vfend(file_id)
      status = hclose(file_id)

      end


4.9.2 VSQuery Vdata Information Retrieval Routines

The syntax of the VSQuery routines are as follows:


	status = VSQueryname(vdata_id, *vdata_name);
	status = VSQueryclass(vdata_id, *vdata_class);
	status = VSQueryfields(vdata_id, fields);
	status = VSQueryinterlace(vdata_id, *interlace);
	status = VSQuerycount(vdata_id, *n_records);
	vdata_tag = VSQuerytag(vdata_id);
	vdata_ref = VSQueryref(vdata_id);
	status = VSQueryvsize(vdata_id, *vdata_vsize);

All VSQuery routines except VSQuerytag and VSQueryref have two arguments. The second argument is the type of vdata information being requested. VSQuerytag and VSQueryref are functions that retrieve the vdata information through their return value.

The parameters of these routines are listed in the following table.

TABLE 4R VSQuery Routine Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSQueryname

(vsqfname)

vdata_id

int32

integer

Vdata identifier.

vdata_name

char *

character* (*)

Name of the vdata.

VSQueryfields

(vsqfflds)

vdata_id

int32

integer

Vdata identifier.

fields

char *

character* (*)

Comma-separated list of the field names in the vdata.

VSQueryinterlace

(vsqfintr)

vdata_id

int32

integer

Vdata identifier.

interlace

int32 *

integer

Interlace mode.

VSQuerycount

(vsqnfelt)

vdata_id

int32

integer

Vdata identifier.

n_records

int32 *

integer

Number of records in the vdata.

VSQueryvsize

(vsqfvsiz)

vdata_id

int32

integer

Vdata identifier.

vdata_size

int32 *

integer

Size in bytes of the vdata record.

VSQuerytag

(vsqtag)

vdata_id

int32

integer

Vdata identifier.

VSQueryref

(vsqref)

vdata_id

int32

integer

Vdata identifier.

4.9.3 VS Vdata Information Retrieval Routines

Some routines with names prefaced by "VS" are used to obtain specific types of vdata information. Here is the syntax of these routines:

num_of_elements = VSelts(vdata_id);
status = VSgetclass(vdata_id, vdata_class);
num_of_fields = VSgetfields(vdata_id, field_names);
interlace_mode = VSgetinterlace(vdata_id);
status = VSgetname(vdata_id, vdata_name);
size_of_fields = VSsizeof(vdata_id, field_name_list);

With the exception of VSgetclass, the information obtainable through these routines can also be obtained through VSinquire. VSinquire provides a way to query commonly used vdata information with one standardized routine call. However, as there are situations where the HDF programmer may not want all of the information VSinquire provides, the VS routines have also been provided.

The parameters of these routines are described in the following table.

TABLE 4S VSelts, VSgetclass, VSgetfields, VSgetinterlace, VSgetname and VSsizeof Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran -77

VSelts

(vsfelts)

vdata_id

int32

integer

Vdata identifier.

VSgetclass

(vsfcls)

vdata_id

int32

integer

Vdata identifier.

vdata_class

char *

character* (*)

Pointer to the class name.

VSgetfields

(vsfgfld)

vdata_id

int32

integer

Vdata identifier.

fields

char *

character* (*)

Pointer to the field names.

VSgetinterlace

(vsfgint)

vdata_id

int32

integer

Vdata identifier.

VSgetname

(vsfgnam)

vdata_id

int32

integer

Vdata identifier

vdata_name

char *

character* (*)

Pointer to the vdata name.

VSsizeof

(vsfsiz)

vdata_id

int32

integer

Vdata identifier.

fields

char *

character* (*)

List of field names to be queried.

4.9.4 VF Field Information Retrieval Routines

Routines whose names of prefaced by "VF" are used for obtaining information about specific fields in a vdata. Here is the syntax of these routines:

	field_name = VFfieldname(vdata_id, field_index);
	field_file_size = VFfieldesize(vdata_id, field_index);
	field_mem_size = VFfieldisize(vdata_id, field_index);
	num_of_fields = VFnfields(vdata_id);
	field_order = VFfieldorder(vdata_id, field_index);
	field_type = VFfieldtype(vdata_id, field_index);

The second, field_index is the index number that uniquely identifies the location of the field within the vdata. Field index numbers are assigned in increasing order and are zero-based.

The values returned by each of the VF routines are as follows:

If unsuccessful, these routines return FAIL (or -1). The parameters of these routines are described in the following table.

TABLE 4T VFfieldname, VFfieldesize, VFfieldisize, VFnfields, VFfieldorder and VFfieldtype Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VFfieldname

(vffname)

vdata_id

int32

integer*4

Vdata identifier.

field_index

int32

integer

Field index.

VFfieldesize

(vffesiz)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Field index.

VFfieldisize

(vffisiz)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Field index.

VFnfields

(vfnflds)

vdata_id

int32

integer

Vdata identifier.

VFfieldorder

(vffordr)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Field index.

VFfieldtype

(vfftype)

vdata_id

int32

integer

Vdata identifier.

field_index

int32

integer

Field index.



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

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.