Reading from vgroups is more complicated than writing to vgroups. This section describes routines that locate the appropriate vgroup and obtain information about the member or members of a vgroup.
file_id and retrieves the reference numbers of lone vgroups in the file. This routine is useful for locating unattached vgroups in a file or the vgroups at the top of a grouping hierarchy. The syntax of Vlone is as follows:
C: num_of_lones = Vlone(file_id, ref_array, maxsize);
FORTRAN: num_of_lones = vflone(file_id, ref_array, maxsize)The parameter
ref_array is an array allocated to hold the reference numbers of the found vgroups. The argument maxsize specifies the maximum size of ref_array. At most maxsize reference numbers will be retrieved in ref_array. The value of max_size, the space allocated for ref_array, depends on how many lone vgroups are expected to be found. To use dynamic memory instead of allocating an unnecessarily large array (i.e., one that will hold the maximum possible number of reference numbers), call Vlone twice. In the first call to Vlone, set
maxsize to a small value, for example, 0 or 1, then use the returned value (the total number of lone vgroups in the file) to allocate memory for ref_array. This array is then passed into the second call to Vlone.Vlone returns the total number of lone vgroups or
FAIL (or -1). The parameters of this routine are further defined in Table 5D on page 199.
5.6.1.2 Sequentially Searching for a Vgroup: Vgetid
Vgetid sequentially searches through an HDF file to obtain the reference number of the vgroup immediately following the vgroup specified by the reference number, vgroup_ref. The syntax of Vgetid is as follows:C: ref_num = Vgetid(file_id, vgroup_ref);
FORTRAN: ref_num = vfgid(file_id, vgroup_ref)
To initiate a search, Vgetid may be called with vgroup_ref set to -1. Doing so returns the reference number of the first vgroup in the file. Any attempt to search past the last vgroup in a file will cause Vgetid to return a value of FAIL (or -1).FAIL (or -1). The parameters of Vgetid are further defined in Table 5D.
TABLE 5D - Vlone and Vgetid Parameter Lists
5.6.1.3 Obtaining the Name of a Vgroup: Vgetname
Vgetname retrieves the name of the vgroup identified by the parameter vgroup_id into the parameter vgroup_name. The syntax of Vgetname is as follows:C: status = Vgetname(vgroup_id, vgroup_name);
FORTRAN: status = vfgnam(vgroup_id, vgroup_name)
The maximum length of the vgroup name is defined by VGNAMELENMAX (or 64).SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 5E on page 199.
5.6.1.4 Obtaining the Class Name of a Vgroup: Vgetclass
Vgetclass retrieves the class name of the vgroup specified by the parameter vgroup_id into the parameter vgroup_class. The syntax of Vgetclass is as follows:C: status = Vgetclass(vgroup_id, vgroup_class);
FORTRAN: status = vfgcls(vgroup_id, vgroup_class)
The maximum length of the class name is defined by VGNAMELENMAX (or 64).SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 5E.
TABLE 5E - Vgetname and Vgetclass Parameter Lists
5.6.1.5 Locating a Vgroup Given Its Name: Vfind
Vfind searches the file identified by file_id for a vgroup with the name specified by the parameter vgroup_name. The syntax for Vfind is as follows:C: vgroup_ref = Vfind(file_id, vgroup_name);
FORTRAN: vgroup_ref = vfind(file_id, vgroup_name)
Vfind returns the reference number of the vgroup if one is found, or 0 otherwise. If more than one vgroup has the same name, Vfind will return the reference number of the first one.
5.6.1.6 Locating a Vgroup Given Its Class Name: Vfindclass
Vfindclass searches the file identified by file_id for a vgroup with the class name specified by the parameter vgroup_class. The syntax of Vfindclass is as follows:C: vgroup_ref = Vfindclass(file_id, vgroup_class);
FORTRAN: vgroup_ref = vfndcls(file_id, vgroup_class)
Vfindclass returns the reference number of the vgroup if one is found, or 0 otherwise. If more than one vgroup has the same class name, Vfindclass will return the reference number of the first one.
TABLE 5F - Vfind and Vfindclass Parameter Lists
EXAMPLE 4. Obtaining Information about Lone Vgroups
This example illustrates the use of Vlone/vflone to obtain the list of reference numbers of all lone vgroups in the file and the use of Vgetname/vfgnam and Vgetclass/vfgcls to obtain the name and the class of a vgroup.
5.6.2 Obtaining Information about the Contents of a Vgroup
This section describes the Vgroup interface routines that allow the user to obtain various information about the contents of vgroups. 5.6.2.1 Obtaining the Number of Objects in a Vgroup: Vntagrefs
Vntagrefs returns the number of tag/reference number pairs (i.e., the number of vgroup members) stored in the specified vgroup. The syntax of Vntagrefs is as follows:C: num_of_tagrefs = Vntagrefs(vgroup_id);
FORTRAN: num_of_tagrefs = vfntr(vgroup_id)
Vntagrefs can be used together with Vgettagrefs or Vgettagref to identify the data objects linked to a given vgroup.FAIL (or -1) otherwise. The parameter of Vntagrefs is further defined in Table 5G on page 202.
5.6.2.2 Obtaining the Tag/Reference Number Pair of a Data Object within a Vgroup : Vgettagref
Vgettagref retrieves the tag/reference number pair of a specified data object stored within the vgroup identified by the parameter vgroup_id. The syntax of Vgettagref is as follows:C: status = Vgettagref(vgroup_id, index, &obj_tag, &obj_ref);
FORTRAN: status = vfgttr(vgroup_id, index, obj_tag, obj_ref)
Vgettagref stores the tag and reference number in the parameters obj_tag and obj_ref, respectively. The parameter index specifies the location of the data object within the vgroup and is zero-based. SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 5G on page 202.
5.6.2.3 Obtaining the Tag/Reference Number Pairs of Data Objects in a Vgroup: Vgettagrefs
Vgettagrefs retrieves the tag/reference number pairs of the members of a vgroup and returns the number of pairs retrieved. The syntax of Vgettagrefs is as follows:C: num_of_pairs = Vgettagrefs(vgroup_id, tag_array, ref_array, maxsize);
FORTRAN: num_of_pairs = vfgttrs(vgroup_id, tag_array, ref_array, maxsize)
Vgettagrefs stores the tags into the array tag_array and the reference numbers into the array ref_array. The parameter maxsize specifies the maximum number of tag/reference number pairs to return, therefore each array must be at least maxsize in size.maxsize if the tag/reference number pairs for all members of the vgroup are desired. To do this, set maxsize to 1 in the first call to Vgettagrefs.FAIL (or -1). The parameters of this routine are further defined in Table 5G.
TABLE 5G - Vntagrefs, Vgettagref, and Vgettagrefs Parameter Lists
5.6.2.4 Testing Whether a Data Object Belongs to a Vgroup: Vinqtagref
Vinqtagref determines whether a data object is a member of the vgroup specified by the parameter vgroup_id. The syntax of Vinqtagref is as follows:C: true_false = Vinqtagref(vgroup_id, obj_tag, obj_ref);
FORTRAN: true_false = vfinqtr(vgroup_id, obj_tag, obj_ref)
The data object is specified by its tag/reference number pair in the parameters obj_tag and obj_ref. Vinqtagref returns TRUE (or 1) if the object belongs to the vgroup, and FALSE (or 0) otherwise. The parameters of this routine are further defined in Table 5H on page 203.
5.6.2.5 Testing Whether a Data Object within a Vgroup is a Vgroup: Visvg
Visvg determines whether the data object specified by its reference number, obj_ref, is a vgroup and is a member of the vgroup identified by the parameter vgroup_id. The syntax of Visvg is as follows:C: true_false = Visvg(vgroup_id, obj_ref);
FORTRAN: true_false = vfisvg(vgroup_id, obj_ref)
Visvg returns either TRUE (or 1) or FALSE (or 0). The parameters of this routine are further defined in Table 5H on page 203.
5.6.2.6 Testing Whether an HDF Object within a Vgroup is a Vdata: Visvs
Visvs determines whether the data object specified by its reference number, obj_ref, is a vdata and is a member of the vgroup identified by the parameter vgroup_id. The syntax of Visvs is as follows:C: true_false = Visvs(vgroup_id, obj_ref);
FORTRAN: true_false = vfisvs(vgroup_id, obj_ref)
Visvs returns either TRUE (or 1) or FALSE (or 0). The parameters of this routine are further defined in Table 5H.
TABLE 5H - Vinqtagref, Visvg, and Visvs Parameter Lists
5.6.2.7 Locating a Vdata in a Vgroup Given Vdata Fields: Vflocate
Vflocate locates a vdata that belongs to the vgroup identified by the parameter vgroup_id and contains the fields specified in the parameter fieldname_list. The syntax of Vflocate is as follows:C: vdata_ref = Vflocate(vgroup_id, fieldname_list);
FORTRAN: vdata_ref = vffloc(vgroup_id, fieldname_list)
The parameter fieldname_list is a string of comma-separated field names containing no white space, for example, "PX,PY,PZ". Note that a vdata must contain all of the fields specified in fieldname_list to be qualified.FAIL (or -1) otherwise. The parameters of this routine are further defined in Table 5I.
5.6.2.8 Retrieving the Number of Tags of a Given Type in a Vgroup: Vnrefs
Vnrefs returns the number of tags of the type specified by the parameter tag_type in the vgroup identified by the parameter vgroup_id. The syntax of Vnrefs is as follows:C: num_of_tags = Vnrefs(vgroup_id, tag_type);
FORTRAN: num_of_tags = vnrefs(vgroup_id, tag_type)
Possible values of the parameter tag_type are defined in Appendix A of this manual. Vnrefs returns 0 or the number of tags if successful, and FAIL (or -1) otherwise. The parameters of this routine are further defined in Table 5I.
TABLE 5I - Vflocate and Vnrefs Parameter Lists
5.6.2.9 Retrieving the Reference Number of a Vgroup: VQueryref
VQueryref returns the reference number of the vgroup identified by the parameter vgroup_id, or FAIL (or -1) if unsuccessful. The syntax of VQueryref is as follows:C: vgroup_ref = VQueryref(vgroup_id);
FORTRAN: vgroup_ref = vqref(vgroup_id)
VQueryref is further defined in Table 5J.
5.6.2.10 Retrieving the Tag of a Vgroup: VQuerytag
VQuerytag returns DFTAG_VG (or 1965), which would be the tag of the vgroup identified by the parameter vgroup_id, or FAIL (or -1) if unsuccessful. The syntax of VQuerytag is as follows:C: vgroup_tag = VQuerytag(vgroup_id);
FORTRAN: vgroup_tag = vqtag(vgroup_id)
VQuerytag is further defined in Table 5J.
TABLE 5J - VQueryref and VQuerytag Parameter Lists
Vgroup identifier
Vgroup identifier
EXAMPLE 5. Operations on Vgroup Attributes
This example illustrates the use of Vfind/vfind to locate a vgroup by its name, Vsetattr/vfscatt to attach an attribute to the vgroup, Vattrinfo/vfainfo to obtain information about the vgroup attribute, and Vgetattr/vfgcatt to obtain the attribute values.