[Top] [Prev] [Next] [Bottom]

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 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 for writing vdatas when it is only necessary to write one field per vdata and complete information about each vdata to be written is available. If you cannot provide full information about the vdata the VS routines described in the next section must be called.

Figure 4c on page 108 shows two examples of single-field vdatas. The fields can be single-component or multi-component fields, that is, they may contain one or more components of the same data type.

FIGURE 4c Single- and Multi-Component Vdatas

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

1. Open the file.
2. Initialize the VS interface.
3. Create the vdata.
4. Terminate access to the VS interface.
5. Close the file.
These steps correspond to the following sequence of function calls:

C:		file_id = Hopen(filename, file_access_mode, n_dds);
		status = Vstart(file_id);
		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, n_dds)
		status = vfstart(file_id)
		vdata_ref = vhfsd (file_id, fieldname, buf, n_records,
			data_type, vdata_name, vdata_class)
		status = vfend(file_id)
		status = hclose(file_id)

			OR

		vdata_ref = vhfsdm (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 file_id parameter is the file identifier returned by Hopen. The fieldname parameter is the name of the single field. The buf, n_records and data_type parameters contain the contents, number of records and data type of the vdata and the vdata_name and vdata_class parameters specify the name and class of the vdata. The order parameter of VHstoredatam specifies the order of the multi-component field. The maximum length of the vdata name is given by the VSNAMELENMAX definition in the "hlimits.h" header file. Both routines return the reference number of the newly-created vdata or FAIL (or -1) if the create operation was unsuccessful.

The parameters of VHstoredata and VHstoredatam are further described in the following table.

TABLE 4C VHstoredataand VHstoredatam Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VHstoredata

(vhfsd/vhfscd)

file_id

int32

integer

File identifier.

fieldname

char *

character* (*)

String containing the name of the field.

buf

uint8

integer (*)

Buffer containing the data to be stored.

n_records

int32

integer

Number of records to create in the vdata.

data_type

int32

integer

Number type of the stored data.

vdata_name

char *

character* (*)

Name of the vdata.

vdata_class

char *

character* (*)

Vdata class.

VHstoredatam

(vhfsdm/

vhfscdm)

file_id

int32

integer

File identifier.

fieldname

char *

character* (*)

String containing the name of the single field.

buf

uint8 *

integer (*)

Buffer containing the data to be stored.

n_records

int32

integer

Number of records to create in the vdata.

data_type

int32

integer

Number type of the stored data.

vdata_name

char *

character* (*)

Name of the vdata.

vdata_class

char *

character* (*)

Class describing the type of vdata.

order

int32

character* (*)

Number of components to store in the field.

EXAMPLE 2. Creating Single-Field Vsets

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 fields of order 4 and is created from a 6 x 4 array in memory.

C:

#include "hdf.h" 

main( )
{

	int32	 file_id, vdata_id, vdata_ref1, vdata_ref2, status;
	uint8	 vset1_data[5] = {1, 2, 3, 4, 5};
	uint8 vset2_data[6][4] = {{1, 2, 3, 4}, {2, 4, 6, 8},
                        {3, 6, 9, 12}, {4, 8, 12, 16},
                        {5, 10, 15, 20}, {6, 12, 18, 24}};

	/* Create the HDF file. */
	file_id = Hopen("Example2.hdf", DFACC_CREATE, 0);

	/* Initialize the VS interface. */
	status = Vstart(file_id);
	 
	/* Create the first vdata and populate it with data
	* from the vset1_data array. 	*/

	vdata_ref1 = VHstoredata(file_id, "Vset1 data", (uint8 *)vset1_data, \
						5, DFNT_UINT8, "Second Vset", "5x1 array"); 

	/* 
	* Create the second vdata and populate it with data
	* from the vset2_data array. 
	*/

	vdata_ref2 = VHstoredatam(file_id, "Vset2 data", (uint8 *)vset2_data, \
					6, DFNT_UINT8, "Third Vset", "6x4 array", 4); 

	/* Terminate access to the VS interface. */
	status = Vend(file_id);

	/* Close the HDF file. */
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM VSET CREATE

      integer*4 file_id, vdata_ref1, vdata_ref2
      integer vset_data1(5), vset_data2(6, 4), i
      integer hopen, vhfsd, vhfsdm, hclose

C     DFACC_CREATE is defined in `hdf.inc'. DFNT_INT32 is
C     defined in `hntdefs.h'.
      integer DFACC_CREATE, DFNT_INT32
      parameter (DFACC_CREATE = 4, DFNT_INT32 = 24)

C     Generate the vset_data1 data. 
      do 10 i = 1, 5
        vset_data1(i) = i
10    continue

C     Generate the vset_data2 data. 
      do 20 i = 1, 6
        do 30 j = 1, 4
          vset_data2(i, j) = i + j
30      continue
20    continue

C     Create the HDF file. 
      file_id = hopen(`Example2.hdf', DFACC_CREATE, 0)

C     Initialize the VS interface. 
      status = vfstart(file_id)

C     Create the first vdata and populate it with data
C     from the vset1_data array. 
      vdata_ref1 = vhfsd(file_id, `Vset1 data', vset_data1,
     +               5, DFNT_INT32, `First Vset', `5x1 array')

C     Create the second vdata and populate it with data
C     from the vset2_data array. 
      vdata_ref2 = vhfsdm(file_id, `Vset2 data', vset_data2,
     +               6, DFNT_INT32, `Second Vset', `6x4 array', 4)

C     Terminate access to the VS 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.