[Top] [Prev] [Next]

5.6 Reading from Vgroups

Reading from vgroups is more complicated than writing to vgroups. The process of reading from vgroups involves two steps: locating the appropriate vgroup and obtaining information about the member or members of a vgroup.

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.

5.6.1 Locating Vgroups and Obtaining Vgroup Information

There are several routines provided for the purpose of locating a particular vgroup, each corresponding to an identifying aspect of a vgroup. These aspects include whether the vgroup has vgroups included in it, the identification of the vgroup in the file based on its reference number, and the name and class name of the vgroup. The routines are described in the following subsections.

5.6.1.1 Locating Lone Vgroups: Vlone

A lone vgroup is one that is not a member of any other vgroups, i.e., not linked with any other vgroups. Vlone searches the file specified by the parameter 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 197.

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).

Vgetid returns a vgroup reference number or FAIL (or -1). The parameters of Vgetid are further defined in Table 5D.

TABLE 5D - Vlone and Vgetid Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Vlone

[int32]

(vflone)
file_id
int32
integer
File identifier

ref_array
int32 *
integer (*)
Buffer for the reference numbers of lone vgroups

maxsize
int32
integer
Maximum number of vgroups to store in ref_array

Vgetid

[int32]

(vfgid)
file_id
int32
integer
File identifier

vgroup_ref
int32
integer
Reference number of the current vgroup

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).

Vgetname returns either SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 5E on page 197.

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).

Vgetclass returns either 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

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Vgetname

[int32]

(vfgnam)
vgroup_id
int32
integer
Vgroup identifier

vgroup_name
char *
character*(*)
Buffer for the name of the vgroup

Vgetclass

[int32]

(vfgcls)
vgroup_id
int32
integer
Vgroup identifier

vgroup_class
char *
character*(*)
Buffer for the vgroup class

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.

The parameters of Vfind are further defined in Table 5F.

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.

The parameters of Vfindclass are further defined in Table 5F.

TABLE 5F - Vfind and Vfindclass Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Vfind

[int32]

(vfind)
file_id
int32
integer
File identifier

vgroup_name
char *
character*(*)
Buffer for the name of the vgroup

Vfindclass

[int32]

(vfndcls)
file_id
int32
integer
File identifier

vgroup_class
char *
character*(*)
Buffer for the vgroup class

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.

In this example, the program calls Vlone/vflone twice. The first call is to obtain the number of lone vgroups in the file so that sufficient space can be allocated; the later call is to obtain the actual reference numbers of the lone vgroups. The program then goes through the list of lone vgroup reference numbers to get and display the name and class of each lone vgroup. The file used in this example is "General_Vgroups.hdf".

C version

FORTRAN-77 version

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.

Vntagrefs returns 0 or a positive number representing the number of HDF data objects linked to the vgroup if successful, or FAIL (or -1) otherwise. The parameter of Vntagrefs is further defined in Table 5G on page 200.

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.

Often, this routine is called in a loop to identify the tag/reference number pair of each data object belong to a vgroup. In this case, Vntagrefs is used to obtain the loop boundary.

Vgettagref returns either SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 5G on page 200.

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.

Vgettagrefs can be used to obtain the value of 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.

Vgettagrefs returns the number of tag/reference number pairs or FAIL (or -1). The parameters of this routine are further defined in Table 5G.

TABLE 5G - Vntagrefs, Vgettagref, and Vgettagrefs Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Vntagrefs

[int32]

(vfntr)
vgroup_id
int32
integer
Vgroup identifier

Vgettagref

[intn]

(vfgttr)
vgroup_id
int32
integer
Vgroup identifier

index
int32
integer
Index of the tag/reference number pair to be retrieved

obj_tag
int32 *
integer
Tag of the data object

obj_ref
int32 *
integer
Reference number of the data object

Vgettagrefs

[int32]

(vfgttrs)
vgroup_id
int32
integer
Vgroup identifier

tag_array
int32 []
integer (*)
Buffer for the returned tags

ref_array
int32 []
integer (*)
Buffer for the returned reference numbers

maxsize
int32
integer
Maximum number of tag/reference number pairs to be returned

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 201.

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 201.

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

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Vinqtagref

[intn]

(vfinqtr)
vgroup_id
int32
integer
Vgroup identifier

obj_tag
int32
integer
Tag of the data object to be queried

obj_ref
int32
integer
Reference number of the data object to be queried

Visvg

[intn]

(vfisvg)
vgroup_id
int32
integer
Vgroup identifier

obj_ref
int32
integer
Data object reference number to be queried

Visvs

[intn]

(vfisvs)
vgroup_id
int32
integer
Vgroup identifier

obj_ref
int32
integer
Data object reference number to be queried

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.

Vflocate returns the reference number of the vdata, if one is found, and 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

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Vflocate

[int32]

(vffloc)
vgroup_id
int32
integer
Vgroup identifier

fieldname_list
char *
character*(*)
Buffer containing the names of the fields

Vnrefs

[int32]

(vnrefs)
vgroup_id
int32
integer
Vgroup identifier

tag_type
int32
integer
Tag type

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

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
VQueryref

[int32]

(vqref)
vgroup_id
int32
integer
Vgroup identifier

VQuerytag

[int32]

(vqtag)
vgroup_id
int32
integer
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.

The program obtains the version of the group then sets an attribute named "First Attribute" for the vgroup named "SD Vgroup". Next, the program gets the number of attributes that the vgroup has, and obtains and displays the name, the number of values, and the values of each attribute.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 05/19/99, NCSA HDF Development Group.