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);
<Optional operations>
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)
<Optional operations>
status = vfdtch(vgroup_id)
status = vfend(file_id)
status = hclose(file_id)
The calling program must obtain a separate vgroup identifier for each vgroup to be accessed. 5.4.1 Accessing Files and Vgroups: Vstart and Vattach
An HDF file must be opened by Hopen before it can be accessed using the Vgroup interface. Hopen is described in Chapter 2, HDF Fundamentals.
The Vgroup interface routines are used in a similar manner to the Vdata interface routines. Before performing operations on a vgroup, a calling program must call Vstart for every file to be accessed. Vstart initializes the internal vgroup structures in a file. Vstart takes one argument, the file identifier returned by Hopen, and returns either
SUCCEED (or 0) or FAIL (or -1). Note that the Vstart routine is used by both the Vdata and Vgroup interfaces.file_id, vgroup_ref, and vg_access_mode, and returns either a vgroup identifier or FAIL (or -1).file_id is the file identifier returned by Hopen. The parameter vgroup_ref is the reference number that identifies the vgroup to be accessed. Specifying vgroup_ref with a value of -1 will create a new vgroup; specifying vgroup_ref with a nonexistent reference number will return an error code of FAIL (or -1); and specifying vgroup_ref with a valid reference number will initiate access to the corresponding vgroup.
To access an existing vdata, its reference number must be obtained. The Vgroup interface includes two routines for this purpose, Vfind and Vgetid. Vfind can be used to obtain the reference number of a vgroup when the vgroup's name is known. Vgetid can be used to obtain the reference number by sequentially traversing the file. These routines are discussed in Section 5.6.1.5 on page 200 and Section 5.6.1.2 on page 198.
The parameter
vg_access_mode in Vattach specifies the type of access ("r" or "w") required for operations on the selected vgroup.
5.4.2 Terminating Access to Vgroups and Files: Vdetach and Vend
Successfully terminating access to a vgroup requires one Vdetach call for every Vattach call made. Similarly, successfully terminating access to the Vgroup interface requires one Vend call for every Vstart call made.vgroup_id, the vgroup identifier returned by Vattach, and returns either SUCCEED (or 0) or FAIL (or -1). file_id, the file identifier returned by Hopen, and returns either SUCCEED (or 0) or FAIL (or -1). Note that the first Vend call to a file must occur after all Vdetach calls for the vgroups in the same file have been made. Note also that the Vend routine is used by both the Vdata and Vgroup interfaces.
The parameters of Vdetach and Vend are also defined in Table 5B.
TABLE 5B - Vstart, Vattach, Vdetach, and Vend Parameter Lists