[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:

TABLE 4A Vdata Interface Routines
Category

Routine Name

Description

C

Fortran-77

Access

Vend

vfend

Closes the vdata interface.

Vstart

vfstart

Initializes the vdata interface.

VSattach

vsfatch

Establishes access to a specified vdata.

VSdetach

vsfdtch

Terminates access to a specified vdata.

Read and Write

VHstoredata

vhfsd/vhfscd

Writes data to a simple, single-component vdata.

VHstoredatam

vhfsdm/vhfscdm

Writes a vdata with one multi-component field.

VSfdefine

vsffdef

Defines a new vdata field.

VSsetclass

vsfscls

Assigns a class to a vdata.

VSsetfields

vsfsfld

Specifies the vdata fields to be written to.

VSsetinterlace

vsfsint

Sets the interlace mode for a vdata.

VSsetname

vsfsnam

Assigns a name to a vdata.

VSwrite

vsfwrit

Writes records to a vdata.

VSread

vsfread

Reads from a vdata.

VSseek

vsfseek

Seeks to a specified record in a vdata.

VSsetattr

vsfsnat/vsfscat

Sets the attribute of a vdata field or vdata.

File

Inquiry

VSfind

vsffnd

Searches for a given vdata name the opened HDF file.

VSgetid

vsfgid

Returns the identifier of the next vdata in the file.

VSlone

vsflone

Returns the vdatas that are not linked into vgroups.

Vdata

Inquiry

VSfexist

vsfex

Tests for the existence of fields in the specified vdata.

VSinquire

vsfinq

Returns information about the specified vdata.

VSelts

vsfelts

Returns the number of records in the specified vdata.

VSgetclass

vsfcls

Returns the class name of the specified vdata.

VSgetfields

vsfgfld

Returns all field names within the specified vdata.

VSgetinterlace

vsfgint

Retrieves the interlace mode of the specified vdata.

VSgetname

vsfgnam

Retrieves the name of the specified vdata.

VSsizeof

vsfsiz

Returns the field sizes of the specified vdata.

VSQueryclass

None

Returns the class of the specified vdata.

VSQueryfields

vsgfld

Returns the field names of the specified vdata.

VSQueryname

vsfgname

Returns the name of the specified vdata.

VSQueryref

None

Retrieves the reference number of the specified vdata.

VSQuerytag

None

Retrieves the tag of the specified vdata.

VSQuerycount

vsfelts

Returns the number of records in the specified vdata.

VSQueryinterlace

vsfgint

Returns the interlace mode of the specified vdata.

VSQueryvsize

vsfsiz

Retrieves the local size in bytes of the specified vdata record.

VSfindex

vsffidx

Queries the index of a vdata field given the field name.

VSsetattr

vsfsnat/vsfscat

Sets the attribute of a vdata field or vdata.

VSnattrs

vsfnats

Queries the total number of vdata attributes.

VSfnattrs

vsffnas

Queries the number of attributes of a vdata or vdata field.

VSfindattr

vsffdat

Retrieves the index of an attribute given the attribute name.

VSattrinfo

vsfainf

Queries information on a given attribute.

VSgetattr

vsfgnat/vsfgcat

Queries the values of a given attribute.

VSisattr

vsfisat

Determines if the given vdata is an attribute.

Field

Inquiry

VFfieldesize

None

Retrieve the field size (as stored in a file) of a specified field.

VFfieldisize

None

Retrieve the field size (as stored in memory) of a specified field.

VFfieldname

None

Retrieves the name of the specified field in the given vdata.

VFfieldorder

None

Retrieves the order of the specified field in the given vdata.

VFfieldtype

None

Retrieves the data type for the specified field in the given vdata.

VFnfields

None

Retrieves the total number of fields in the specified vdata.

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
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vstart

(vfstart)

file_id

int32

integer

File identifier.

VSattach

(vsfatch)

vdata_id

int32

integer

Vdata identifier.

vdata_ref

int32

integer

Reference number of the vdata.

file_access_mode

char *

character*1

Vdata access mode.

VSdetach

(vsfdtch)

vdata_id

int32

integer

Vdata identifier.

Vend

(vfend)

file_id

int32

integer

File identifier.

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.