[Top] [Prev] [Next]

4.4 Creating and Writing to Single-Field Vdatas: VHstoredata and VHstoredatam

There are two methods of writing vdatas that contain one field per record. One requires the use of several VS routines and the other involves the use of VHstoredata or VHstoredatam, two high-level routines that encapsulate several VS routines into one.

The high-level VH routines are useful when writing one-field vdatas and complete information about each vdata is available. If you cannot provide full information about a vdata, you must use the VS routines described in the next section.

Figure 4c shows two examples of single-field vdatas. The fields can be single-component or multi-component fields. With a multi-component field, they may contain one or more values of the same data type.

FIGURE 4c - Single- and Multi-component Vdatas

VHstoredata creates then writes a vdata with one single-component field. VHstoredatam creates and writes a vdata with one multi-component field. In both cases the following steps are involved:

  1. Open the file.
  2. Initialize the Vdata interface.
  3. Store (create then write to) the vdata.
  4. Terminate access to the Vdata interface.
  5. Close the file.

These steps correspond to the following sequence of function calls:

C:		file_id = Hopen(filename, file_access_mode, num_dds_block);
		status = Vstart(file_id);
		/* Either VHstoredata or VHstoredatam can be called here. */
		vdata_ref = VHstoredata(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class);
	OR	vdata_ref = VHstoredatam(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class, order);
		status = Vend(file_id);
		status = Hclose(file_id);
FORTRAN:	file_id = hopen(filename, file_access_mode, num_dds_block)
		status = vfstart(file_id)
C		Either vhfsd/vhfscd or vhfsdm/vhfscdm can be called here.
		vdata_ref = vhfsd(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class)
	OR	vdata_ref = vhfscd(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class)
			OR
		vdata_ref = vhfsdm(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class, order)
	OR	vdata_ref = vhfscdm(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class, order)
		status = vfend(file_id)
		status = hclose(file_id)
The first seven parameters of VHstoredata and VHstoredatam are the same. The parameter file_id is the file identifier returned by Hopen. The parameter fieldname specifies the name of the vdata field. The parameter buf contains the data to be stored into the vdata. In C, the data type of the parameter buf is uint8; in FORTRAN-77, it is the data type of the data to be stored. The parameters n_records and data_type contain the number of records in the vdata and the data type of the vdata data. The parameters vdata_name and vdata_class specify the name and class of the vdata. The parameter order of VHstoredatam specifies the order of the field. The maximum length of the vdata name is given by the VSNAMELENMAX (or 64) as defined in the header file "hlimits.h".

Note that these two routines do not overwrite existing vdatas but only create new ones before storing the data.

The FORTRAN-77 version of VHstoredata has two routines: vhfsd for numeric data and vhfscd for character data; the FORTRAN-77 version of VHstoredatam has two routines: vhfsdm for numeric data and vhfscdm for character data.

Both routines return the reference number of the newly-created vdata or FAIL (or -1) if the operation is unsuccessful. The parameters for VHstoredata and VHstoredatam are further described in Table 4C.

TABLE 4C - VHstoredata and VHstoredatam Parameter Lists

Routine Name

[Return Type]

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

[int32]

(vhfsd/vhfscd)
file_id
int32
integer
File identifier

fieldname
char *
character*(*)
String containing the name of the field

buf
uint8 *
<valid numeric data type>(*)/character*(*)
Buffer containing the data to be stored

n_records
int32
integer
Number of records to create in the vdata

data_type
int32
integer
Data type of the stored data

vdata_name
char *
character*(*)
Name of the vdata

vdata_class
char *
character*(*)
Class name of the vdata

VHstoredatam

[int32]

(vhfsdm/
vhfscdm)
file_id
int32
integer
File identifier

fieldname
char *
character*(*)
String containing the name of the field

buf
uint8 *
<valid numeric data type>(*)/character*(*)
Buffer containing the data to be stored

n_records
int32
integer
Number of records to create in the vdata

data_type
int32
integer
Data type of the stored data

vdata_name
char *
character*(*)
Name of the vdata

vdata_class
char *
character*(*)
Class name of the vdata

order
int32
integer
Number of field components

EXAMPLE 2. Creating and Storing One-field Vdatas Using VHstoredata and VHstoredatam

This example illustrates the use of VHstoredata/vhfscd and VHstoredatam/vhfsdm to create single-field vdatas.

This example creates and writes two vdatas to the file "General_Vdatas.hdf". The first vdata is named "First Vdata", contains 5 records, and belongs to a class named "5x1 Array". The second vdata is named "Second Vdata", contains 6 records, and belongs to a class named "6x4 Array". The field of the first vdata is a single-component field, i.e., order of 1, and named "Single-component Field". The field of the second vdata has an order of 4 and is named "Multi-component Field".

In these examples two vdatas are created. The first vdata has five records with one field of order 1 and is created from a 5 x 1 array in memory. The second vdata has six records with one field of order 4 and is created from a 6 x 4 array in memory.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

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