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

4.6 Reading from Vdatas

Reading from vdatas is more complicated than writing to vdatas, as it usually involves searching for a particular vdata, as well as searching within the vdata, before actually reading data. The process of reading from vdatas can be summarized in three steps:

1. Identify the appropriate vdata in the file.
2. Obtain information about the vdata.
3. Read in the desired data.
The last step will be covered first as the vdata of interest is usually known, therefore the first two steps are not needed.

These three basic steps can be expanded into the following:

1. Open a file.
2. Initialize the VS interface.
3. Access the vdata.
4. Optionally seek to the records to access.
5. Initialize the fields to access.
6. Read the data.
7. Detach from the vdata.
8. Terminate access to the VS interface.
9. Close the file.
The calling program must contain the following sequence of 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);
		record_pos = VSseek(vdata_id, record_index);
		status = VSsetfields(vdata_id, fieldname_list);
		status = VSread(vdata_id, *databuf, n_records, interlace);
		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)
		record_pos = vsfseek(vdata_id, record_index)
		status = vsfsfld(vdata_id, fieldname_list)
		status = vsfread(vdata_id, *databuf, n_records, interlace)
		status = vsfdtch(vdata_id)
		status = vfend(file_id)
		status = hclose(file_id)

4.6.1 Selecting the Record to Begin Reading from: VSseek

VSseek is described in Section 4.5.2.1 on page 114.

4.6.2 Selecting the Fields to be Read: VSsetfields

VSsetfields establishes access to the fields targeted for the next read operation. The argument fieldname_list is a comma-separated string of the target field names with no white space

The order the field names occur in fieldname_list is the order in which the fields will be read. For example, assume that a vdata contains fields named "A, B, C, D, E, F" and they are stored in alphabetical order. The following declarations demonstrate how to use fieldname_list to read a single field, a collection of random fields and a series of fields in reverse order;

4.6.3 Reading from the Current Vdata: VSread

VSread sequentially retrieves data from the records in a vdata. The parameter databuf is the buffer to store the retrieved data, n_records is the number of records to retrieve and interlace specifies the interlace mode (FULL_INTERLACE or NO_INTERLACE) to be used in the contents of databuf. VSread returns the total number of records read if successful and FAIL (or -1) otherwise.

Prior to the first VSread call, VSsetfields must be called.

If a VSread call is successful, the data returned in databuf is formatted according to the interlace mode specified by interlace and the data fields appear in the order specified in the last call to VSsetfields for that vdata. To retrieve an arbitrary record from a vdata, use VSseek to specify the record position before calling VSread.

TABLE 4G VSseek, VSsetfields and VSread Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

VSseek

(vsfseek)

vdata_id

int32

integer

Vdata identifier.

record

int32

integer

Record number to seek to.

VSsetfields

(vsfsfld)

vdata_id

int32

integer

Vdata identifier.

fields

char *

character* (*)

Names of vdata fields to be accessed.

VSread

(vsfread)

vdata_id

int32

integer

Vdata identifier.

databuf

char *

character* (*)

Buffer for the retrieved data.

n_records

int32

integer

Number of records to be retrieved.

interlace

int32

integer

Interlace mode of the buffered data.

VSsetfields and VSread may be called several times to read from the same vdata. However, note that VSread operations are sequential. Thus, in the following code segment, the first call to VSread returns ten "A" data values from the first ten elements in the vdata, while the second call to VSread returns ten "B" data values from the second ten elements (elements 10 to 19) in the vdata.


	VSsetfields(vs, "A");
	VSread(vs, bufA, 10, interlace);

	VSsetfields(vs, "B");
	VSread(vs, bufB, 10, interlace);

To read the first ten "B" data values, the access routine VSseek must be called to explicitly position the read pointer back to the position of the first record. The following code segment reads the first ten "A" and "B" values into two separate float arrays bufA and bufB.


	VSsetfields(vs, "A");
	VSread(vs, bufA, 10, interlace);

	VSseek(vs, 0)	; /* seeks to first element */
	VSsetfields(vs, "B");
	VSread(vs, bufB, 10, interlace);

EXAMPLE 5. Reading Data from a Vdata

In the following examples, the VS interface is used to read the vdata created in the Example 4. VSgetid is used to demonstrate a method of obtaining the reference id number of the first vdata in the HDF file.

C:

#include "hdf.h"
#define NRECORDS 20

main( )
{

	char vdata_name[MAX_NC_NAME], vdata_class[MAX_NC_NAME], fields[60];
	int32 file_id, vdata_id, status, num_of_elements;
	int32 n_records, interlace, vdata_size, vdata_ref;
	uint8 databuf[((2 * sizeof(float32)) + sizeof(char) \
				+ sizeof(int16)) * NRECORDS];

	/* Open the HDF file. */
	file_id = Hopen("Example4.hdf", DFACC_RDONLY, 0);

	/* Initialize the Vset interface. */
	status = Vstart(file_id);

	/* 
	* Get the reference number for the first vdata in 
	* the file. 
	*/
	vdata_ref = -1;
	vdata_ref = VSgetid(file_id, vdata_ref);

	/* Attach to the first vdata in read mode. */
	vdata_id = VSattach(file_id, vdata_ref, "r");

	/* Get the list of field names. */
	status = VSinquire(vdata_id, &n_records, &interlace, fields, 
                        &vdata_size, vdata_name);

	/* Get the class. */
	status = VSgetclass(vdata_id, vdata_class);

	/* Determine the fields that will be read. */
	status = VSsetfields(vdata_id, fields);
	
	/* Print the vdata information. */
	printf("Current vdata name: %s \nCurrent vdata class: %s\n", \
                     vdata_name, vdata_class);

	/* Read the data. */
	num_of_elements = VSread(vdata_id, databuf, n_records, 
					FULL_INTERLACE);

	/* Detach from the vdata, close the vset interface and the file. */
	status = VSdetach(vdata_id);
	status = Vend(file_id);
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM DATA READ

      character vdata_name*30, vdata_class*30, fields*60
      character databuf*40
      integer file_id, vdata_ref, vdata_id
      integer*4 n_records, interlace, vdata_size
      integer status
      integer hopen, vsfgid, vsfatch, vsfinq, vsfgcls
      integer vsfsfld, vsfread, vsfdtch, hclose, vfstart, vfend

C     DFACC_RDONLY and FULL_INTERLACE are defined in hdf.inc.
      integer*4 DFACC_RDONLY, FULL_INTERLACE
      parameter (DFACC_RDONLY = 1,
     +           FULL_INTERLACE = 0)

C     Open an HDF file with read-only access. 
      file_id = hopen(`Example4.hdf', DFACC_RDONLY, 0)

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

C     Get the reference number for the first Vdata in 
C     the file. 
      vdata_ref = -1
      vdata_ref = vsfgid(file_id, vdata_ref)

C     Attach to the first Vdata in read mode. 
      vdata_id = vsfatch(file_id, vdata_ref, `r')

C     Get the list of field names. 
      status = vsfinq(vdata_id, n_records, interlace, fields, 
     +               vdata_size, vdata_name)

C     Get the class. 
      status = vsfgcls(vdata_id, vdata_class)

C     Determine the fields that will be read. 
      status = vsfsfld(vdata_id, fields)
      
C     Print the Vdata information. 
      print *, `Current Vdata name: `, vdata_name
      print *, `Current Vdata class: `, vdata_class

C     Read the data. 
      status = vsfread(vdata_id, databuf, n_records, FULL_INTERLACE)

C     Detach from the Vdata, close the Vset interface and the file. 
      status = vsfdtch(vdata_id)
      status = vfend(file_id)
      status = hclose(file_id)

      end




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

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.