[Top] [Prev] [Next]

4.3 The Vdata Interface

The Vdata interface consists of routines that are used to store and retrieve information about vdatas and their contents.

4.3.1 Header Files Used by the Vdata Interface

The header file "hdf.h" must be included in programs that invoke Vdata interface routines.

4.3.2 Vdata Library Routines

Vdata routines begin with the prefixes "VS", "VF", "VSQ", and "VH" in C, and "vsf", "vf", "vsq", and "vh" in FORTRAN-77. Vdata routines perform most general vdata operations, VF routines query information about vdata fields, and VSQ routines query information about specific vdatas. VH routines are high-level procedures that write to single-field vdatas.

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

Category
Routine Names
Description
C
FORTRAN-77
Access/Create
Vstart vfstart Initializes the Vdata and the Vgroup interfaces (Section 4.3.5 on page 128)

VSattach vsfatch Establishes access to a specified vdata (Section 4.3.5 on page 128)

VSdetach vsfdtch Terminates access to a specified vdata (Section 4.3.6 on page 128)

Vend vfend Terminates access to the Vdata and the Vgroup interfaces (Section 4.3.6 on page 128)

Read and Write
VSfdefine vsffdef Defines a new vdata field (Section 4.5.1.2 on page 133)

VSread vsfrd/vsfrdc/vsfread Reads one record from a vdata (Section 4.6.2 on page 143)

VSseek vsfseek Seeks to a specified record in a vdata (Section 4.5.2.1 on page 136)

VSsetattr vsfsnat/vsfscat Sets the attribute of a vdata field or vdata (Section 4.8.2 on page 147)

VSsetclass vsfscls Assigns a class to a vdata (Section 4.5.1.1 on page 133)

VSsetfields vsfsfld Specifies the vdata fields to be read or written (Section 4.5.1.3 on page 134 and Section 4.6.1 on page 142)

VSsetinterlace vsfsint Sets the interlace mode for a vdata (Section 4.5.1.4 on page 134)

VSsetname vsfsnam Assigns a name to a vdata (Section 4.5.1.1 on page 133)

VHstoredata vhfsd/vhfscd Writes data to a vdata with a single-component field (Section 4.4 on page 129)

VHstoredatam vhfsdm/vhfscdm Writes data to a vdata with a multi-component field (Section 4.4 on page 129)

VSwrite vsfwrt/vsfwrtc/ vsfwrit Writes records to a vdata (Section 4.5.2.2 on page 137)

Vdata
Inquiry

VSattrinfo vsfainf Retrieves information on a given attribute (Section 4.8.7 on page 150)

VSelts vsfelts Returns the number of records in the specified vdata (Section 4.9.3 on page 153)

VSfexist vsfex Locates a vdata given a list of field names (Section 4.7.4 on page 145)

VSfindex vsffidx Returns the index of a vdata field given the field name (Section 4.8.1 on page 147)

VSfnattrs vsffnas Returns the number of attributes of a vdata or vdata field (Section 4.8.5 on page 149)

VSfindattr vsffdat Retrieves the index of an attribute given the attribute name (Section 4.8.6 on page 149)

VSgetattr vsfgnat/vsfgcat Retrieves the values of a given attribute (Section 4.8.3 on page 148)

VSgetclass vsfgcls Returns the class name of the specified vdata (Section 4.9.3 on page 153)

VSgetfields vsfgfld Retrieves all field names within the specified vdata (Section 4.9.3 on page 153)

VSgetinterlace vsfgint Retrieves the interlace mode of the specified vdata (Section 4.9.3 on page 153)

VSgetname vsfgnam Retrieves the name of the specified vdata (Section 4.9.3 on page 153)

VSinquire vsfinq Returns information about the specified vdata (Section 4.9.1 on page 151)

VSisattr vsfisat Determines whether the given vdata is an attribute (Section 4.8.8 on page 150)

VSnattrs vsfnats Returns the total number of vdata attributes (Section 4.8.4 on page 148)

VSQuerycount vsqfnelt Returns the number of records in the specified vdata (Section 4.9.2 on page 152)

VSQueryfields vsqfflds Returns the field names of the specified vdata (Section 4.9.2 on page 152)

VSQueryinterlace vsqfintr Returns the interlace mode of the specified vdata (Section 4.9.2 on page 152)

VSQueryname vsqfname Returns the name of the specified vdata (Section 4.9.2 on page 152)

VSQueryref vsqref Retrieves the reference number of the specified vdata (Section 4.9.2 on page 152)

VSQuerytag vsqtag Retrieves the tag of the specified vdata (Section 4.9.2 on page 152)

VSQueryvsize vsqfsiz Retrieves the local size in bytes of the specified vdata record (Section 4.9.2 on page 152)

VSsetattr vsfsnat/vsfscat Sets the attribute of a vdata field or vdata (Section 4.8.2 on page 147)

VSsizeof vsfsiz Returns the size of the specified fields in a vdata (Section 4.9.3 on page 153)

Field
Inquiry
VFfieldesize vffesiz Returns the field size, as stored in a file, of a specified field (Section 4.9.4 on page 154)

VFfieldisize vffisiz Returns the field size, as stored in memory, of a specified field (Section 4.9.4 on page 154)

VFfieldname vffname Returns the name of the specified field in the given vdata (Section 4.9.4 on page 154)

VFfieldorder vffordr Returns the order of the specified field in the given vdata (Section 4.9.4 on page 154)

VFfieldtype vfftype Returns the data type for the specified field in the given vdata (Section 4.9.4 on page 154)

VFnfields vfnflds Returns the total number of fields in the specified vdata (Section 4.9.4 on page 154)

File
Inquiry
VSfind vsffnd Searches for a vdata in a file given the vdata's name (Section 4.7.3 on page 145)

VSgetid vsfgid Returns the reference number of the next vdata in the file (Section 4.7.2 on page 145)

VSlone vsflone Returns the reference number of vdatas that are not linked with any vgroups (Section 4.7.1 on page 144)

4.3.3 Identifying Vdatas in the Vdata Interface

The Vdata interface identifies vdatas in several ways. Before an existing vdata is accessible, it is uniquely identified by its reference number. The reference number of a vdata can be obtained from the name or the class of the vdata, or by sequentially traversing the file. The concept of reference number is discussed in Section 2.2.2.1 on page 8.

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:

  1. Open the file.
  2. Initialize the Vdata interface.
  3. Create a new vdata or open an existing one using its reference number.
  4. Perform the desired operations on the vdata.
  5. Terminate access to the vdata.
  6. Terminate access to the Vdata interface.
  7. Close the file.

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.

VSattach initiates access to a vdata and must be called before any operations on the vdata may occur. VSattach takes three arguments: file_id, vdata_ref, and vdata_access_mode, and returns either a vdata identifier or FAIL (or -1).

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

If an existing vdata's reference number is unknown, it must be obtained prior to the VSattach call. (Refer to Chapter 2, HDF Fundamentals, for a description of reference numbers.) The HDF library provides two routines for this purpose, VSfind and VSgetid. VSfind can be used to obtain the reference number of a vdata when the vdata's name is known. VSgetid can be used to obtain the reference number when only the location of the vdata within the file is known; this is often discovered by sequentially traversing the file. These routines are discussed in Section 4.7.2 on page 145 and Section 4.7.3 on page 145.

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.

Note that, although a vdata can be created without being written with data, either the routine VSsetname or VSsetfields must be called in order for the vdata to exist in the file.

The parameters for Vstart and VSattach are further defined in Table 4B on page 129.

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).

Vend releases all internal data structures allocated by Vstart. Vend must be called once for each call to Vstart and only after access to all vdatas have been terminated (i.e., all calls to VSdetach have been made). Attempts to call Vdata interface routines after calling Vend will result in an error condition. Vend takes one argument, the file identifier that is returned by Hopen, and returns either SUCCEED (or 0) or FAIL (or -1). Note that the Vend routine is used by both the Vdata and Vgroup interfaces.

In summary, successfully terminating access to a vdata requires one VSdetach call for each call to VSattach and one Vend call for each call to Vstart.

The parameters for VSdetach and Vend are further defined in Table 4B.

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

Routine Name

[Return Type]

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

[intn]

(vfstart)
file_id
int32
integer
File identifier

VSattach

[int32]

(vsfatch)
file_id
int32
integer
File identifier

vdata_ref
int32
integer
Reference number of the vdata

vdata_access_mode
char *
character*1
Vdata access mode

VSdetach

[int32]

(vsfdtch)
vdata_id
int32
integer
Vdata identifier

Vend

[intn]

(vfend)
file_id
int32
integer
File identifier

EXAMPLE 1. Accessing a Vdata in an HDF File

This example illustrates the use of Hopen/hopen, Vstart/vfstart, VSattach/vsfatch, VSdetach/vsfdtch, Vend/vfend, and Hclose/hclose to create and to access different vdatas from different HDF files.

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

FORTRAN-77 version



[Top] [Prev] [Next]

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