VSlone searches an HDF file and retrieves the reference numbers of lone vdatas in the file. The syntax of VSlone is as follows:
C: num_of_lone_vdatas = VSlone(file_id, ref_array, maxsize);
FORTRAN: num_of_lone_vdatas = vsflone(file_id, ref_array, maxsize)
The parameter ref_array
is an array allocated to hold the retrieved reference numbers of lone vdatas and the argument maxsize
specifies the maximum size of ref_array
. At most, maxsize
reference numbers will be returned in ref_array
.ref_array
is dependent upon on how many lone vdatas are expected in the file. A size of MAX_FIELD_SIZE
(or 65535
) integers is adequate to handle any case. To use dynamic memory instead of allocating such a large array, first call VSlone with maxsize
set to a small value like 0 or 1, then use the returned value to allocate memory for ref_array
to be passed to a subsequent call to VSlone.FAIL
(or -1
). The parameters for VSlone are listed in Table 4I on page 146.
4.7.2 Sequentially Searching for a Vdata: VSgetid
VSgetid sequentially searches through an HDF file to obtain the vdata immediately following the vdata specified by the reference number in the parameter vdata_ref
. The syntax of VSgetid is as follows:C: ref_num = VSgetid(file_id, vdata_ref);
FORTRAN: ref_num = vsfgid(file_id, vdata_ref)
To obtain the reference number of the first vdata in the file, the user must set the parameter vdata_ref
to -1. Thus, VSgetid can be repeatedly called, with the initial value of vdata_ref
set to -1 so that the routine will sequentially return the reference number of each vdata in the file, starting from the first vdata. After the last vdata is reached, subsequent calls to VSgetid will return FAIL
(or -1
). FAIL
(or -1
). The parameters for VSgetid are listed in Table 4I on page 146.
4.7.3 Determining a Reference Number from a Vdata Name: VSfind
VSfind searches an HDF file for a vdata with the specified name and returns the vdata reference number. The syntax of VSfind is as follows:C: ref_num = VSfind(file_id, vdata_name);
FORTRAN: ref_num = vsffnd(file_id, vdata_name)
The parameter vdata_name
is the search key. Although there may be several identically named vdatas in the file, VSfind will only return the reference number of the first vdata in the file with the specified name.0
otherwise. The parameters for VSfind are listed in Table 4I.
4.7.4 Searching for a Vdata by Field Name: VSfexist
VSfexist queries a vdata for a set of specified field names and is often useful for locating vdatas containing particular field names. The syntax of the VSfexist function is as follows:C: status = VSfexist(vdata_id, fieldname_list);
FORTRAN: status = vsfex(vdata_id, fieldname_list)
The parameter fieldname_list
is a string of comma-separated field names containing no white space, for example, "PX,PY,PZ
".SUCCEED
(or 0
) if all of the fields specified in the parameter fieldname_list
are found and FAIL
(or -1
) otherwise. The parameters for VSfexist are listed in Table 4I.
TABLE 4I - VSlone, VSgetid, VSfind, and VSfexist Parameter Lists
In this example, the program searches the HDF file "General_Vdatas.hdf" to locate the first vdata containing the fields "Position" and "Temperature". The HDF file is an output of the program in Example 3.
C version