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:
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".
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.
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.
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.
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
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
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