[Top] [Prev] [Next]

4.6 Reading from Vdatas

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

  1. Identify the appropriate vdata in the file.
  2. Obtain information about the vdata.
  3. Read in the desired data.

Only Step 3 will be covered in this section assuming that the vdata of interest and its data information is known. Step 1 is covered in Section 4.7 on page 146 and Step 2 is covered in Section 4.9 on page 153.

Step 3 can be expanded into the following:

  1. Open the file.
  2. Initialize the Vdata interface.
  3. Initiate access to the vdata.
  4. Optionally seek to the appropriate record.
  5. Initialize the fields to be read.
  6. Read the data.
  7. If the fields have different data types, unpack the field data.
  8. Terminate access to the vdata.
  9. Terminate access to the Vdata interface.
  10. Close the file.

The following sequence of function calls corresponds to the above steps:

C:		file_id = Hopen(filename, file_access_mode, num_dds_block);
		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);
 
		records_read = VSread(vdata_id, databuf, n_records, interlace_mode);
 
		status = VSfpack(vdata_id, action, fields_in_buf, buf, buf_size, n_records, fieldname_list, bufptrs);
 
		status = VSdetach(vdata_id);
 
		status = Vend(file_id);
 
		status = Hclose(file_id);
 
FORTRAN:	file_id = hopen(filename, file_access_mode, num_dds_block)
 
		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)
 
		records_read = vsfrd(vdata_id, databuf, n_records, interlace_mode)
 
	OR	records_read = vsfrdc(vdata_id, databuf, n_records, interlace_mode)
 
		status = vsfcpak(vdata_id, action, fields_in_buf, buf, buf_size, n_records, fieldname_list, bufptrs)
 
	OR	status = vsfnpak(vdata_id, action, fields_in_buf, buf, buf_size, n_records, fieldname_list, bufptrs)
 
		status = vsfdtch(vdata_id)
 
		status = vfend(file_id)
 
		status = hclose(file_id)

4.6.1 Initializing the Fields for Read Access: VSsetfields

 VSsetfields establishes access to the fields to be read by the next read operation. The argument fieldname_list is a comma-separated string of the 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 in that order. The following declarations demonstrate how to use fieldname_list to read a single field, a collection of random fields, and all the fields in reverse order:

VSsetfields returns either SUCCEED (or 0) or FAIL (or -1). The parameters for VSsetfields are further defined in Table 4E on page 137.

4.6.2 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 specifies the number of records to retrieve, and interlace_mode specifies the interlace mode, FULL_INTERLACE (or 0) or NO_INTERLACE (or 1), to be used in the contents of databuf.

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 the parameter interlace_mode and the data fields appear in the order specified in the last call to VSsetfields for that vdata.

By default, VSread reads from the first vdata record. To retrieve an arbitrary record from a vdata, use VSseek to specify the record position before calling VSread. VSseek is described in Section 4.5.2.1 on page 138.

The FORTRAN-77 version of VSread has three routines: vsfrd reads buffered numeric data, vsfrdc reads buffered character data and vsfread reads generic packed data.

VSread returns the total number of records read if successful and FAIL (or -1) otherwise. The parameters for VSread are further defined in Table 4H.

TABLE 4H - VSread Parameter List

Routine Name

[Return Type]

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

[int32]

(vsfrd/vsfrdc/vsfread)
vdata_id
int32
integer
Vdata identifier

databuf
uint8*
<valid numeric data type>(*) /
character*(*) / integer
Buffer for the retrieved data

n_records
int32
integer
Number of records to be retrieved

interlace_mode
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.

	status = VSsetfields(vdata_id, "A");
		records_read = VSread(vdata_id, bufferA, 10, interlace_mode);
 
	status = VSsetfields(vdata_id, "B");
 
		records_read = VSread(vdata_id, bufferB, 10, interlace_mode);
 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 bufferA and bufferB.

	status = VSsetfields(vdata_id, "A");
		records_read = VSread(vdata_id, bufferA, 10, interlace_mode);
 
	record_pos = VSseek(vdata_id, 0)	; /* seeks to first record */
 
		status = VSsetfields(vdata_id, "B");
 
		records_read = VSread(vdata_id, bufferB, 10, interlace_mode);

EXAMPLE 5. Reading a Vdata of Homogeneous Type

This example illustrates the use of VSfind/vsffnd to locate a vdata given its name, VSseek/vsfseek to move the current position to a desired record, and VSread/vsfrd to read the data of several records. The function VSfind will be discussed in Section 4.7.3. The approach used in this example can only read data written by a program such as that in Example 3, i.e., without packing. Reading mixed data vdatas must use the approach illustrated in Example 6.

The program reads 5 records starting from the fourth record of the two fields "Position" and "Temperature" in the vdata "Solid Particle" from the file "General_Vdatas.hdf". After the program uses VSfind/vsffnd to obtain the reference number of the vdata, it uses VSseek/vsfseek to place the current position at the fourth record, then starts reading 5 records, and displays the data.

C version

FORTRAN-77 version

FORTRAN: 




EXAMPLE 6.	 Reading a Multi-field and Mixed-type Vdata with Packing 


This example illustrates the use of VSread/vsfread to read part of a mixed data vdata and VSfpack/vsfnpak/vsfcpak to unpack the data read. 


The program reads the vdata "Mixed Data Vdata" that was written to the file "Packed_Vdata.hdf" by the program in Example 4.  In Example 6, all values of the fields "Temp" and "Ident" are read.  The program unpacks and displays all the values after reading is complete.  Again, note that in C only one call to VSread and one call to VSfpack are made to read and unpack all N_RECORDS records. In Fortran, data is read with one call to vsfread, but each field is unpacked using separate calls to vsfnpak and vsfcpak


C version





FORTRAN-77 version








 
[Top] [Prev] [Next]








hdfhelp@ncsa.uiuc.edu



HDF User's Guide - 07/21/98, NCSA HDF  
Development Group.