4.3.1 Header Files Used by the Vdata Interface

4.3.2 Vdata Library Routines

Vdata routines let you define, organize and manipulate vdatas. They are categorized as follows and are listed in Table 4A by their categories:

• Access routines control access to files and vdatas. Data transfer to and from a vdata can only occur after the access to the vdata has been initiated and before it is terminated. Some Vgroup interface routines are included since they are used interchangeably between the Vdata and Vgroup interfaces. Refer to Chapter 5, Vgroups (V API), for a description of the Vgroup interface.
• Read and write routines store and retrieve the contents of and the information about a vdata.
• File inquiry routines provide information about how vdatas are stored in a file. They are useful for locating vdatas in the file.
• Vdata inquiry routines provide specific information about a given vdata, including the vdata's name, class, number of records, tag and reference number pairs, size, and interlace mode.
• Field inquiry routines provide specific information about the fields in a given vdata, including the field's size, name, order, and type, and the number of fields in the vdata.

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)

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

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)

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

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

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