Vdata routines let you define, organize and manipulate vdatas. They are categorized as follows and are listed in Table 4A by their categories:
TABLE 4A - Vdata Interface Routines
When a vdata is attached, it is assigned with an identifier, called vdata id, which is used by the Vdata interface routines in accessing the vdata.
4.3.4 Programming Model for the Vdata Interface
The programming model for accessing vdatas is as follows:
To access a vdata, the calling program must contain the following calls, which are individually explained in the following subsections:
C: file_id = Hopen(filename, file_access_mode, num_dds_block);
status = Vstart(file_id);
vdata_id = VSattach(file_id, vdata_ref, vdata_access_mode);
<Optional operations>
status = VSdetach(vdata_id);
status = Vend(file_id);
status = Hclose(file_id);
FORTRAN: file_id = hopen(filename, file_access_mode, num_dds_block)
status = vfstart(file_id)
vdata_id = vsfatch(file_id, vdata_ref, vdata_access_mode)
<Optional operations>
status = vsfdtch(vdata_id)
status = vfend(file_id)
status = hclose(file_id)
4.3.5 Accessing Files and Vdatas: Vstart and VSattach
An HDF file must be opened by Hopen before it can be accessed using the Vdata interface. Hopen is described in Chapter 2, HDF Fundamentals.
Vstart must be called for every file to be accessed. This routine initializes the internal vdata structures used by the Vdata interface. Vstart has only one argument, the file identifier (
file_id
) 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
, vdata_ref
, and vdata_access_mode
, and returns either a vdata identifier or FAIL
(or -1
).file_id
is the file identifier returned by Hopen and vdata_ref
is the reference number that identifies the vdata to be accessed. Specifying vdata_ref
with a value of -1
will create a new vdata; specifying vdata_ref
with a nonexistent reference number will return an error code of FAIL
(or -1
); and specifying vdata_ref
with a valid reference number will initiate access to the corresponding vdata.
The argument
vdata_access_mode
specifies the access mode ("r
" for read-only access or "w
" for read and write access) for subsequent operations on the specified vdata. Although several HDF user programs may simultaneously read from one vdata, only one write access is allowed at a time. The "r
" access mode may only be used with existing vdatas; the "w
" access mode is valid with both new vdatas (vdata_ref = -1
) and existing vdatas.
4.3.6 Terminating Access to Vdatas and Files: VSdetach and Vend
VSdetach terminates access to a vdata by updating pertinent information and freeing all memory associated with the vdata and initialized by VSattach. Once access to the vdata is terminated, its identifier becomes invalid and any attempt to access it will result in an error condition. VSdetach takes only one argument, the vdata identifier that is returned by VSattach, and returns either SUCCEED
(or 0
) or FAIL
(or -1
). SUCCEED
(or 0
) or FAIL
(or -1
). Note that the Vend routine is used by both the Vdata and Vgroup interfaces.
Hclose terminates access to a file and should only be called after all Vend calls have been made to close the Vdata interface. Refer to Chapter 2, HDF Fundamentals, for a description of Hclose.
TABLE 4B - Vstart, VSattach, VSdetach, and Vend Parameter Lists
The program creates an HDF file, named "General_Vdatas.hdf", containing a vdata. The program also creates a second HDF file, named "Two_Vdatas.hdf", containing two vdatas. Note that, in this example, the program does not write data to these vdatas. Also note that before closing the file, the access to its vdatas and its corresponding Vdata interface must be terminated. These examples request information about a specific vdata.
C version