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