Vgroups (V API)

[Top] [Prev] [Next]

5.5 Creating and Writing to a Vgroup

There are two steps involved in the creation of a vgroup: creating the vgroup and inserting data objects into it. Any HDF data object can be inserted into a vgroup. Creation and insertion operations are usually performed at the same time, but that is not required.

HDF provides two routines that insert an HDF data object into a vgroup, Vaddtagref and Vinsert. Vaddtagref can insert any HDF data object into a vgroup, but requires that the tag and reference number of the object be available. Refer to Section 2.2.2.1 on page 8 for the description of tags and reference numbers for HDF data objects. Vinsert only inserts a vdata or a vgroup to a vgroup, but only requires the identifier of the vdata or the vgroup.

Creating a vgroup with a member involves the following steps:

Open the HDF file.
Initialize the Vgroup interface.
Create the new vgroup.
Optionally assign a vgroup name.
Optionally assign a vgroup class.
Insert a data object.
Terminate access to the vgroup.
Terminate access to the Vgroup interface.
Close the HDF file.

These steps correspond to the following sequence of function calls:

C:		file_id = Hopen(filename, file_access_mode, num_dds_block);

		status = Vstart(file_id);

		vgroup_id = Vattach(file_id, vgroup_ref, vg_access_mode);

		status = Vsetname(vgroup_id, vgroup_name);

		status = Vsetclass(vgroup_id, vgroup_class);

		/* Use either Vinsert to add a vdata or a vgroup, or

		   Vaddtagref to add any data object */

		num_of_tag_refs = Vaddtagref(vgroup_id, obj_tag, obj_ref);

	OR	obj_pos = Vinsert(vgroup_id, v_id);

		status = Vdetach(vgroup_id);

		status = Vend(file_id);

		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, file_access_mode, num_dds_block)

		status = vfstart(file_id)

		vgroup_id = vfatch(file_id, vgroup_ref, vg_access_mode)

		status = vfsnam(vgroup_id, vdata_name)

		status = vfscls(vgroup_id, vdata_class)

C		Use either Vinsert to add a vdata or a vgroup, or Vaddtagref to

C		add any data object

		num_of_tag_refs = vfadtr(vgroup_id, obj_tag, obj_ref)

	OR	obj_pos = vfinsrt(vgroup_id, v_id)

		status = vfdtch(vgroup_id)

		status = vfend(file_id)

		status = hclose(file_id)

The parameter v_id in the calling sequence is either a vdata or vgroup identifier. The parameter vgroup_id is the vgroup identifier returned by Vattach.

When a new vgroup is created, the value of vgroup_ref must be set to -1 and the value of vg_access_mode must be "w".

5.5.1 Assigning a Vgroup Name and Class: Vsetname and Vsetclass

Vsetname assigns a name to a vgroup. The parameter vgroup_name is a character string with the name to be assigned to the vgroup. If Vsetname is not called, the vgroup name is set to a zero-length character string. A name may be assigned and reset any time after the vgroup is created.

Vsetclass assigns a class to a vgroup. The parameter vgroup_class is a character string with the class name to be assigned to the vgroup. If Vsetclass is not called, the vgroup class is set to a zero-length string. As with the vgroup names, the class may be set and reset at any time after the vgroup is created.

Vsetname and Vsetclass return either SUCCEED (or 0) or FAIL (or -1). The parameters of these routines are further described in Table 5C on page 196.

5.5.2 Inserting Any HDF Data Object into a Vgroup: Vaddtagref

Vaddtagref inserts HDF data objects into the vgroup identified by vgroup_id. HDF data objects may be added to a vgroup when the vgroup is created or at any point thereafter.

The parameters obj_tag and obj_ref in Vaddtagref are the tag and reference number, respectively, of the data object to be inserted into the vgroup. Note that duplicated tag and reference number pairs are allowed.

Vaddtagref returns the total number of tag and reference number pairs, i.e., the total number of data objects, in the vgroup if the operation is successful, and FAIL (or -1) otherwise. The parameters of Vaddtagref are further described in Table 5C.

5.5.3 Inserting a Vdata or Vgroup Into a Vgroup: Vinsert

Vinsert is a routine designed specifically for inserting vdatas or vgroups into a parent vgroup. To use Vinsert, you must provide the identifier of the parent vgroup, vgroup_id, as well as the identifier of the vdata or vgroup to be inserted, v_id.

The parameter v_id of Vinsert is either a vdata identifier or a vgroup identifier, depending on whether a vdata or vgroup is to be inserted.

Vinsert returns the index of the inserted vdata or vgroup if the operation is successful, and FAIL (or -1) otherwise. The parameters of Vinsert are further defined in Table 5C.

TABLE 5C - Vsetname, Vsetclass, Vaddtagref, and Vinsert Parameter Lists

Routine Name

[Return Type]
(FORTRAN-77) Parameter Parameter Type Description

C FORTRAN-77

Vsetname

[int32]

(vfsnam)
`vgroup_id` `int32` `integer` Vgroup identifier

`vgroup_name` `char ` `character()` Vgroup name

Vsetclass

[int32]

(vfscls)
`vgroup_id` `int32` `integer` Vgroup identifier

`vgroup_class` `char ` `character()` Vgroup class

Vaddtagref

[int32]

(vfadtr)
`vgroup_id` `int32` `integer` Vgroup identifier

`obj_tag` `int32` `integer` Tag of the data object to be inserted

`obj_ref` `int32` `integer` Reference number of the data object to be inserted

Vinsert

[int32]

(vfinsrt)
`vgroup_id` `int32` `integer` Vgroup identifier

`v_id` `int32` `integer` Identifier of the vgroup or vdata to be inserted

EXAMPLE 1. Creating HDF Files and Vgroups

This example illustrates the use of Hopen/hopen, Vstart/vfstart, Vattach/vfatch, Vdetach/vfdtch, Vend/vfend, and Hclose/hclose to create and to access two vgroups in an HDF file.

The program creates the HDF file, named "Two_Vgroups.hdf", and two vgroups stored in the file. Note that, in this example, the program only create two empty vgroups.

FORTRAN-77 version

EXAMPLE 2. Adding an SDS to a New Vgroup

This example illustrates the use of Vaddtagref/vfadtr to add an HDF data object, an SDS specifically, to a vgroup.

In this example, the program first creates the HDF file "General_Vgroups.hdf", then an SDS in the SD interface, and a vgroup in the Vgroup interface. The SDS is named "Test SD" and is a one-dimensional array of type int32 of 10 elements. The vgroup is named "SD Vgroup" and is of class "Common Vgroups". The program then adds the SDS to the vgroup using Vaddtagref/vfadtr. Notice that, when the operations are complete, the program explicitly terminates access to the SDS, the vgroup, the SD interface, and the Vgroup interface before closing the HDF file. Refer to Chapter 3, Scientific Data Sets (SD API) for the discussion of the SD routines used in this example.

FORTRAN-77 version

EXAMPLE 3. Adding Three Vdatas into a Vgroup

This example illustrates the use of Vinsert/vfinsrt to add a vdata to a vgroup. Note that Vaddtagref/vfadtrf, used in the previous example, performs the same task and only differs in the argument list.

In this example, the program creates three vdatas and a vgroup in the existing HDF file "General_Vgroups.hdf" then adds the three vdatas to the vgroup. Notice that the vdatas and the vgroup are created in the same interface that is initialized by the call Vstart/vfstart. The first vdata is named "X,Y Coordinates" and has two order-1 fields of type float32. The second vdata is named "Temperature" and has one order-1 field of type float32. The third vdata is named "Node List" and has one order-3 field of type int16. The vgroup is named "Vertices" and is of class "Vertex Set". The program uses Vinsert/vfinsrt to add the vdatas to the vgroup using the vdata identifiers. Refer to Chapter 4, Vdatas (VS API), for the discussion of the VS routines used in this example.

FORTRAN-77 version

[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu

HDF User's Guide - 07/21/98, NCSA HDF Development Group.