[Top] [Prev] [Next] [Bottom]

1.4 Programming Model for the Vgroup Interface

The programming model for accessing vgroups is as follows:

1. Open a file.
2. Initialize the V interface
3. Open a vgroup.
4. Perform the desired operations on the vgroup.
5. Dispose of the vgroup id.
6. Terminate access to the V interface.
7. Close the file.
To access a single vgroup in an HDF file, the calling program must contain the following calls:

C:		file_id = Hopen(filename, file_access_mode, n_dds);
		status = Vstart(file_id);
		vgroup_id = Vattach(file_id, vgroup_ref, vgroup_access_mode);
		<Optional operations>
		status = Vdetach(vgroup_id);
		status = Vend(file_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, file_access_mode, n_dds)
		status = vfstart(file_id)
		vgroup_id = vsfatch(file_id, vdata_ref, vgroup_access_mode)
		<Optional operations>
		status = vfdtch(vgroup_id)
		status = vfend(file_id)
		status = hclose(file_id)

The calling program must obtain a separate vgroup id for each vgroup to be accessed.

1.4.1 Accessing Files and Vgroups: Hopen, Vstart and Vattach

An HDF file must be opened by Hopen before it can be accessed using the V interface. Hopen is described in Chapter 2, titled HDF Fundamentals.

The Vgroup interface routines are used in a similar manner to the V interface routines. Before performing operations on a vgroup, a calling program must call Vstart for every file it intends to access and Vattach for every vgroup it intends to access. Vstart initializes the internal vgroup structures in a file. Consequently, any HDF file involved in a vgroup operation must be initialized by Vstart before the operation begins. Vstart takes one argument, the file id returned by Hopen.

Vattach provides access to an individual vgroup for all read and write operations. It takes three arguments: file_id, vgroup_ref and the access_mode. The argument file_id is a file identifier returned by Hopen and vgroup_ref is the reference number that identifies the vgroup to be accessed. Specifying a nonexistent reference number will return an error, specifying a value of -1 for the reference number will create a new vgroup and specifying an existing reference number will provide access to the corresponding vgroup. To find the reference number of a vgroup, consider using either Vgetnext or Vgetid.

The access_mode parameter in Vattach specifies the type of access ("r" or "w") required for operations on the selected vgroup. This argument is not currently used; all vgroups are automatically opened with read and write access. Multiple attaches may be made to the same vgroup, which will result in several vgroup identifiers being assigned to the same vgroup.

The parameters of Vstart and Vattach are defined in Table 5B below.

1.4.2 Terminating Access to Vgroups and Files: Vdetach, Vend and Hclose

Successfully terminating access to a vgroup requires one Vdetach call for every Vattach call made. The calling program must also call Vend once for every Vstart call made. All Vdetach calls must occur prior to the first Vend call for the same file. Vdetach terminates access by updating internal library structures and frees all memory associated with the vgroup. Once a vgroup is detached, its vgroup id is invalid and any attempts to access it will result in an error condition.

Vend releases all internal data structures allocated by calling Vstart. Its one argument is file_id, the file identifier returned by Hopen. Vend must be called once per file and only after all vgroups are detached. Attempts to use the Vgroup interface after calling Vend will produce errors.

Hclose terminates access to a file only if there are no vgroup ids attached to the file. To successfully close a file, individually release all vgroup idsby making one Vdetach call for each Vattach call.

The parameters of Vdetach and Vend are also defined in the following table.

TABLE 5B Vstart, Vattach, Vdetach and Vend Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vstart

(vstart)

file_id

int32

integer

File identifier.

Vattach

(vfatch)

file_id

int32

integer

File identifier.

vgroup_ref

int32

integer

Reference number for existing vgroup or -1 for new.

access_mode

char *

character* (*)

Access mode of the vgroup operation.

Vdetach

(vfdtch)

vgroup_id

int32

integer

Vgroup identifier.

Vend

(vend)

file_id

int32

integer

IFile identifier.



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.