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 144 and Step 2 is covered in Section 4.9 on page 151.
Step 3 can be expanded into the following:
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:
fieldname_list
= "B
"
fieldname_list
= "A,E
"
fieldname_list
= "F,E,D,C,B,A
"
VSsetfields returns either SUCCEED
(or 0
) or FAIL
(or -1
). The parameters for VSsetfields are further defined in Table 4E on page 135.
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
.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.
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.
FAIL
(or -1
) otherwise. The parameters for VSread are further defined in Table 4H.
TABLE 4H - VSread Parameter List
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);
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:
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. 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