[Top] [Prev]

4.9 Obtaining Information about a Specific Vdata

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

4.9.1 Obtaining Vdata Information: VSinquire

VSinquire retrieves information about the vdata identified by the parameter vdata_id. The routine has the following syntax:

C:			status = VSinquire(vdata_id, &n_records, &interlace_mode, fieldname_list, &vdata_size, vdata_name);
FORTRAN:	status = vsfinq(vdata_id, n_records, interlace_mode, fieldname_list, vdata_size, vdata_name)
The parameter n_records contains the returned number of records in the vdata, the parameter interlace_mode contains the returned interlace mode of the vdata contents, the parameter fieldname_list is a comma-separated list of the returned names of all the fields in the vdata, the parameter vdata_size is the returned size, in bytes, of the vdata record, and the parameter vdata_name contains the returned name of the vdata.

If any of the parameters are set to NULL in C, the corresponding data will not be returned.

VSinquire returns either SUCCEED (or 0) or FAIL (or -1). The parameters for VSinquire are further defined in Table 4N.

TABLE 4N - VSinquire Parameter List

Routine Name

[Return Type]

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

[intn]

(vsfinq)
vdata_id
int32
integer
Vdata identifier

n_records
int32 *
integer
Number of records in the vdata

interlace_mode
int32 *
integer
Interlace mode

fieldname_list
char *
character*(*)
Buffer for the list of field names

vdata_size
int32 *
integer
Size in bytes of the vdata record

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

EXAMPLE 9. Obtaining Vdata Information

This example illustrates the use of VSgetid/vsfgid and VSinquire/vsfinq to obtain information about all vdatas in an HDF file.

In this example, the program uses VSgetid to locate all vdatas in the HDF file "General_Vdatas.hdf", which is the output of Example 3. For each vdata found, if it is not the storage of an attribute, the program uses VSinquire/vsfinq to obtain information about the vdata and displays its information. Recall that an attribute is also stored as a vdata; the function VSisattr/vsfisat checks whether a vdata is a storage of an attribute.

C version

FORTRAN-77 version

4.9.2 VSQuery Vdata Information Retrieval Routines

The syntax of the VSQuery routines are as follows:

C:		status = VSQueryname(vdata_id, vdata_name);
		status = VSQueryfields(vdata_id, fields);
		status = VSQueryinterlace(vdata_id, &interlace_mode);
		status = VSQuerycount(vdata_id, &n_records);
		vdata_tag = VSQuerytag(vdata_id);
		vdata_ref = VSQueryref(vdata_id);
		status = VSQueryvsize(vdata_id, &vdata_vsize);
FORTRAN:	status = vsqfname(vdata_id, vdata_name)
		status = vsqfflds(vdata_id, fields)
		status = vsqfintr(vdata_id, interlace_mode)
		status = vsqfnelt(vdata_id, n_records)
		vdata_tag = vsqtag(vdata_id)
		vdata_ref = vsqref(vdata_id)
		status = vsqfvsiz(vdata_id, vdata_vsize)
All VSQuery routines except VSQuerytag and VSQueryref have two arguments. The first argument identifies the vdata to be queried. The second argument is the type of vdata information being requested.

VSQuerytag and VSQueryref return the tag and reference number, respectively, or FAIL (or -1). All other routines return SUCCEED (or 0) or FAIL (or -1). The parameters for these routines are listed in Table 4O.

TABLE 4O - VSQuery Routines Parameter Lists

Routine Name

[Return Type]

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

[intn]

(vsqfname)
vdata_id
int32
integer
Vdata identifier

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

VSQueryfields

[intn]

(vsqfflds)
vdata_id
int32
integer
Vdata identifier

fields
char *
character*(*)
Comma-separated list of the field names in the vdata

VSQueryinterlace

[intn]

(vsqfintr)
vdata_id
int32
integer
Vdata identifier

interlace_mode
int32 *
integer
Interlace mode

VSQuerycount

[intn]

(vsqfnelt)
vdata_id
int32
integer
Vdata identifier

n_records
int32 *
integer
Number of records in the vdata

VSQueryvsize

[intn]

(vsqfvsiz)
vdata_id
int32
integer
Vdata identifier

vdata_size
int32 *
integer
Size in bytes of the vdata record

VSQuerytag

[int32]

(vsqtag)
vdata_id
int32
integer
Vdata identifier

VSQueryref

[int32]

(vsqref)
vdata_id
int32
integer
Vdata identifier

4.9.3 Other Vdata Information Retrieval Routines

The routines described in this section, with names prefaced by "VS", are used to obtain specific types of vdata information. The syntax of these routines are as follows:

C:		num_of_records = VSelts(vdata_id);
		num_of_fields = VSgetfields(vdata_id, fieldname_list);
		interlace_mode = VSgetinterlace(vdata_id);
		size_of_fields = VSsizeof(vdata_id, fieldname_list);
		status = VSgetname(vdata_id, vdata_name);
		status = VSgetclass(vdata_id, vdata_class);
FORTRAN:	num_of_records = vsfelts(vdata_id)
		num_of_fields = vsfgfld(vdata_id, fieldname_list)
		interlace_mode = vsfgint(vdata_id)
		size_of_fields = vsfsiz(vdata_id, fieldname_list)
		status = vsfgnam(vdata_id, vdata_name)
		status = vsfcls(vdata_id, vdata_class)
With the exception of VSgetclass, the information obtained through these routines can also be obtained through VSinquire. VSinquire provides a way to query commonly used vdata information with one routine call. The VS routines in this section are useful in situations where the HDF programmer wishes to obtain only specific information.

The parameters for these routines are described in Table 4P.

TABLE 4P - VSelts, VSgetfields, VSgetinterlace, VSsizeof, VSgetname, and VSgetclass Parameter Lists

Routine Name

[Return Type]

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

[int32]

(vsfelts)
vdata_id
int32
integer
Vdata identifier

VSgetfields

[int32]

(vsfgfld)
vdata_id
int32
integer
Vdata identifier

fieldname_list
char *
character*(*)
List of field names to be queried

VSgetinterlace

[int32]

(vsfgint)
vdata_id
int32
integer
Vdata identifier

VSsizeof

[int32]

(vsfsiz)
vdata_id
int32
integer
Vdata identifier

fieldname_list
char *
character*(*)
List of field names to be queried

VSgetname

[int32]

(vsfgnam)
vdata_id
int32
integer
Vdata identifier

vdata_name
char *
character*(*)
Vdata name

VSgetclass

[int32]

(vsfcls)
vdata_id
int32
integer
Vdata identifier

vdata_class
char *
character*(*)
Class name of the vdata to be queried

4.9.4 VF Field Information Retrieval Routines

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

C:		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);
FORTRAN:	field_name = vffname(vdata_id, field_index)
		field_file_size = vffesiz(vdata_id, field_index)
		field_mem_size = vffisiz(vdata_id, field_index)
		num_of_fields = vfnflds(vdata_id)
		field_order = vffordr(vdata_id, field_index)
		field_type = vfftype(vdata_id, field_index)
The functionality of each of the VF routines is as follows:

If the operations are unsuccessful, these routines return FAIL (or -1). The parameters for all of these routines are described in Table 4Q.

TABLE 4Q - VF Routines Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
VFfieldname
[char *]
(vffname)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
Field index

VFfieldesize

[int32]

(vffesiz)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
Field index

VFfieldisize

[int32]

(vffisiz)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
Field index

VFnfields

[int32]

(vfnflds)
vdata_id
int32
integer
Vdata identifier

VFfieldorder

[int32]

(vffordr)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
Field index

VFfieldtype

[int32]

(vfftype)
vdata_id
int32
integer
Vdata identifier

field_index
int32
integer
Field index



[Top] [Prev]

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