[Top] [Prev] [Next] [Bottom]
Chapter
4
Vdatas (VS API)
4.1 Chapter Overview
This chapter describes the vdata data model, the vdata API (also called the VS interface) and the vdata programming model. The last section of this chapter introduces command-line utilities that operate on vdata objects.
4.2 The Vdata Model
The vdata object is a collection of records whose values are stored in fixed-length fields. The HDF Vdata model provides a framework for storing customized tables, or vdatas, in HDF files. The term "vdata" is an abbreviation of "vertex data" which alludes to the fact that, when the object was first implemented in HDF, it was designed specifically for the purpose of storing the vertex and edge information of polygon sets. The vdata design has since been generalized to apply to a broader variety of applications.
Vdatas are uniquely identified by a name, a class and a series of individual field names . (See Figure 4a.)
FIGURE 4a Vdata Table Structure
A vdata name is a label typically assigned to describe the contents of a vdata. It often serves as a search key for files containing multiple vdatas. A vdata class further distinguishes a particular vdata by identifying the purpose or use of its data. Finally, vdata field names are labels assigned to each field.
4.2.1 Records and Fields
A vdata is a collection of records, which itself is comprised of one or more fixed-length fields. A vdata is like a table in which each row has the same structure and each column contains data of the same data type. (See Figure 4b.) Vdata records and fields are identified by an index. The record and field indexes are zero-based and separately incremented by one for each additional field and record in the vdata object.
Every field in a vdata is assigned a data type when the vdata is created. The data type of a field may be any basic HDF data type: character, 8-bit, 16-bit and 32-bit signed and unsigned integers, and 32-bit and 64-bit floating point numbers. The maximum length of a vdata record is 32,767 bytes.
The Vdata model allows multiple entries per field. The number of entries or components in a field is more commonly called the order of the field.
The organizational structure of a vdata is often determined by the data types of its data set or sets. For example, given a data set describing the location ("X, Y") and temperature ("Temp") of points in a plane, there are several ways to organize the data. (See Figure 4b.) If the "X", "Y" and "Temp" values are of the same data type, they could be stored as three single-component fields, as two-component "X, Y" field and a Temp field or as a three-component "X, Y, Temp" field. Generally, the "X,Y" data is kept in a single field, but HDF places no restrictions on the organization of field data and there are no significant HDF performance issues involved in choosing one organizational regime over another.
FIGURE 4b Three Different Vdata Structures for Data of the Same Number Type
4.2.2 Conventions
To facilitate the sharing of data in an HDF data file among different users and organizations, it is a good idea to establish conventions about vdata attributes such as vdata names, classes, field and record structures and field names. A typical HDF convention describes a configuration of vdata and vgroup objects designed to store polygonal data. These vdatas and vgroups collectively form a structure called a vset. Chapter 5, titled Vgroups (V API), contains additional information on vsets.
4.3 The Vdata API
The VS API consists of routines that are used to store and retrieve information about vdatas and their contents. The V interface, which is described in Chapter 5, titled Vgroups (V API), can also be used to perform certain operations on vdatas.
4.3.1 Vdata Library Routines
Vdata routines begin with the prefixes "VS", "VF", "VSQ" and "VH". Routines in the V interface are prefaced by a capital "V". V 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 designed to write to single-field vdatas.
Vdata routines let you define, organize and manipulate vdatas, and are categorized as follows:
- Access routines attach, or allow access, to vdatas. Data transfer can only occur after a vdata has been accessed. These routines also detach from, or properly terminate access to, vdatas when data transfer is completed.
- Read and write routines read and write the contents of a vdata.
- File inquiry routines provide information about how vdatas are stored in a file. They are useful for locating vdatas in a file.
- Vdata inquiry routines provide specific information about a given vdata, including the vdata's name, class, number of fields, number of records, tag and reference number pairs, interlace mode and size.
- Field inquiry routines provide specific information about the fields in a given vdata, including the field's size, name, order, type and number of fields in the vdata.
TABLE 4A Vdata Interface Routines
4.3.2 Vdata Identifiers in the Vdata API
The VS interface identifies vdatas in several ways. Before a vdata is opened or attached, it is identified by its name, class and reference number. When a vdata is attached it is assigned a vdata identifier, or vdata id, which is used by the vdata interface routines in accessing vdatas.
The name and class are assigned by the calling program and may be changed throughout the scope of the vdata object.
4.3.3 Programming Model for the Vdata Interface
The programming model for accessing vdatas is as follows:
- 1. Open a file.
- 2. Initialize the VS interface.
- 3. Open a vdata by obtaining a vdata id from a vdata reference number.
- 4. Perform the desired operations on the vdata.
- 5. Dispose of the vdata id.
- 6. Terminate access to the VS interface.
- 7. Close the file.
To access a vdata, the calling program must contain the following calls:
C: file_id = Hopen(filename, file_access_mode, n_dds);
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, n_dds)
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.4 Accessing Files and Vdatas: Hopen, Vstart and VSattach
The general routine Hopen opens an HDF file and obtains a file identifier. Details on the use of Hopen are provided in Chapter 2, titled HDF Fundamentals.
To perform operations on a vdata, the calling program must call Vstart for every file to be accessed and VSattach for every vdata to be accessed. Vstart initializes the internal vdata structures used by the VS API. Vstart has as its only argument the file identifier returned by Hopen.
VSattach accesses an individual vdata and must be called before all read and write operations. It has three arguments: file_id, vdata_ref and the file_access_mode. The file_id argument is the file identifier returned by Hopen and vdata_ref is the reference number that identifies to vdata to be accessed. Specifying a nonexistent reference number will return an error, specifying a value of -1 will create a new vdata and specifying an existing reference number will result in the corresponding vdata being accessed.
The access_mode argument specifies the access mode ("r" for read-only access or "w" for write-only) required for subsequent operations on the specified vdata. Although several HDF user programs may simultaneously read from one vdata object, only one write access is allowed at a time. The "r" read-only access mode may only be used with existing vdatas, but the "w" access mode is valid with both new vdatas (vdata_ref = -1) and existing vdatas.
The parameters for Vstart and VSattach are further defined below. (See Table 4B.)
4.3.5 Terminating Access to Vdatas and Files: VSdetach, Vend and Hclose
VSdetach terminates access by updating pertinent information and freeing all memory associated with the vdata. Once access to the vdata is terminated, its identifier is invalid and any attempt to access it will result in an error condition.
Vend releases all internal data structures allocated by Vstart. It takes one argument the file identifier returned by Hopen. Vend must be called once per file and only after access to all vdata objects are terminated. Attempts to call VS interface routines after calling Vend will result in an error condition.
Successfully terminating access to a vdata requires one VSdetach call for each call to VSattach and one Vend call for each call to Vstart. All VSdetach calls must be made prior to making the first call to Vend.
Hclose terminates access to a file only if no vdata ids remain allocated. It is described in Chapter 2, titled HDF Fundamentals.
The parameters for VSdetach and Vend are further defined in the following table.
TABLE 4B Vstart, VSattach, VSdetach and Vend Parameter List
EXAMPLE 1. Accessing a Vdata in an HDF File
These examples show how to write vdata information. It returns information about the specified vdata. The VSinquire routine is described in Section 4.9 on page 135.
Note that the "Dummy_HDF_File.hdf" HDF file represents a previously-created file.
C:
#include "hdf.h"
main( )
{
int32 file_id, vdata_id, status;
int32 n_records, interlace, vdata_size;
char fields[30], vdata_name[30];
/* Open the HDF file. */
file_id = Hopen("Dummy_HDF_File.hdf", DFACC_RDONLY, 0);
/* Initialize the VS interface. */
status = Vstart(file_id);
/* Get information about the vdata. */
status = VSinquire(vdata_id, &n_records, &interlace, fields, \
&vdata_size, vdata_name);
/* Terminate access to the vdata. */
status = VSdetach(vdata_id);
/* Terminate access to the VS interface. */
status = Vend(file_id);
/* Close the HDF file. */
status = Hclose(file_id);
}
FORTRAN:
PROGRAM VDATA ACCESS
integer*4 file_id, vdata_id, n_records, interlace, vdata_size
integer status
character fields*30, vdata_name*30
integer hopen, vfatch, vsfinq, vfdtch, hclose
C DFACC_RDONLY is defined in `hdf.inc'.
integer DFACC_RDONLY
parameter (DFACC_RDONLY = 1)
C Open an HDF file with read-only access.
file_id = hopen(`Dummy_HDF_File.hdf', DFACC_RDONLY, 0)
C Initialize the Vset interface.
status = vfstart(file_id)
C Attach to the first Vdata.
vdata_id = vfatch(file_id, -1, `w')
C Get information about the Vdata.
status = vsfinq(vdata_id, n_records, interlace, fields,
+ vdata_size, vdata_name)
C Terminate access to the Vdata.
status = vfdtch(vdata_id)
C Terminate access to the Vdata interface.
status = vfend(file_id)
C Close the HDF file.
status = hclose(file_id)
end
[Top] [Prev] [Next] [Bottom]
hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF
Development Group.