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.
TABLE 4Q VSinquire Parameter List
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);
}
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);
The parameters of these routines are listed in the following table.
TABLE 4R VSQuery Routine Parameter List
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);
The parameters of these routines are described in the following table.
TABLE 4S VSelts, VSgetclass, VSgetfields, VSgetinterlace, VSgetname and VSsizeof Parameter List
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.
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