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.NULL in C, the corresponding data will not be returned.SUCCEED (or 0) or FAIL (or -1). The parameters for VSinquire are further defined in Table 4N.
TABLE 4N - VSinquire Parameter List
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
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
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.
FAIL (or -1).
FAIL (or -1).
FAIL (or -1).
FAIL (or -1).
SUCCEED (or 0) or FAIL (or -1).
SUCCEED (or 0) or FAIL (or -1).
The parameters for these routines are described in Table 4P.
TABLE 4P - VSelts, VSgetfields, VSgetinterlace, VSsizeof, VSgetname, and VSgetclass Parameter Lists
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