[Top] [Prev] [Next]

5.4 Programming Model for the Vgroup Interface

The programming model for accessing vgroups is as follows:

  1. Open an HDF file.
  2. Initialize the Vgroup interface.
  3. Create a new vgroup or open an existing one.
  4. Perform the desired operations on the vgroup.
  5. Terminate access to the vgroup.
  6. Terminate access to the Vgroup interface.
  7. Close the 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);
		<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.

The calling program must also call one Vattach for every vgroup to be accessed. Vattach provides access to an individual vgroup for all read and write operations. Vattach takes three arguments: file_id, vgroup_ref, and vg_access_mode, and returns either a vgroup identifier or FAIL (or -1).

The argument 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.

When a new vgroup is created, it does not have any members. Additional operations must be performed to add other HDF data objects to the vgroup. Refer to Section 5.5 on page 192 for information.

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 198 and Section 5.6.1.2 on page 196.

The parameter vg_access_mode in Vattach specifies the type of access ("r" or "w") required for operations on the selected vgroup.

Multiple attaches may be made to a vgroup, which will result in several vgroup identifiers being assigned to the same vgroup. Termination must be properly handled as described in the next section.

The parameters of Vstart and Vattach are defined in Table 5B on page 192.

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.

Vdetach terminates access to a vgroup by updating internal library structures and freeing all memory associated with the vgroup and allocated by Vattach. Once a vgroup is detached, its identifier is invalid and any attempts to access this vgroup identifier will result in an error condition. Vdetach takes one argument, vgroup_id, the vgroup identifier returned by Vattach, and returns either SUCCEED (or 0) or FAIL (or -1).

Vend releases all internal data structures allocated by Vstart. Attempts to use the Vgroup interface identifier after calling Vend will produce errors. Vend takes one argument, 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.

Hclose must be used to terminate access to the HDF file and only after all proper Vend calls are made. Hclose is described in Chapter 2, HDF Fundamentals.

The parameters of Vdetach and Vend are also defined in Table 5B.

TABLE 5B - Vstart, Vattach, Vdetach, and Vend Parameter Lists

Routine Name

[Return Type]

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

[intn]

(vfstart)
file_id
int32
integer
File identifier

Vattach

[int32]

(vfatch)
file_id
int32
integer
File identifier

vgroup_ref
int32
integer
Reference number for an existing vgroup or -1 to create a new one

vg_access_mode
char *
character*(*)
Access mode of the vgroup operation

Vdetach

[int32]

(vfdtch)
vgroup_id
int32
integer
Vgroup identifier

Vend

[intn]

(vfend)
file_id
int32
integer
File identifier



[Top] [Prev] [Next]

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