FIGURE 4d - Interlaced and Non-Interlaced Vdata Contents
VSsetinterlace returns either
SUCCEED (or 0) or FAIL (or -1). The parameters for VSsetinterlace are further described in Table 4E.
Like the high-level VH interface, the Vdata interface does not retain default settings from one operation to the next or from one file to the next. Each time a vdata is created, its definitions must be explicitly reset.
C: file_id = Hopen(filename, file_access_mode, num_dds_block);
status = Vstart(file_id);
vdata_id = VSattach(file_id, -1, vdata_access_mode);
status = VSsetname(vdata_id, vdata_name);
status = VSsetclass(vdata_id, vdata_class);
status = VSfdefine(vdata_id, fieldname1, data_type1, order1);
. . . . . . . . . .
status = VSfdefine(vdata_id, fieldnameN, data_typeN, orderN);
status = VSsetfields(vdata_id, fieldname_list);
status = VSsetinterlace(vdata_id, interlace_mode);
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, -1, vdata_access_mode)
status = vsfsnam(vdata_id, vdata_name)
status = vsfscls(vdata_id, vdata_class)
status = vsffdef(vdata_id, fieldname1, data_type1, order1)
. . . . . . . . . .
status = vsffdef(vdata_id, fieldnameN, data_typeN, orderN)
status = vsfsfld(vdata_id, fieldname_list)
status = vsfsint(vdata_id, interlace_mode)
status = vsfdtch(vdata_id)
status = vfend(file_id)
status = hclose(file_id)
In the routines that follow, vdata_id is the vdata identifier returned by VSattach. 4.5.1.1 Assigning a Vdata Name and Class: VSsetname and VSsetclass
VSsetname assigns a name to a vdata. If not explicitly named by a call to VSsetname, the name of the vdata is set by default to NULL. A name may be assigned and reassigned at any time after the vdata is created. The parameter vdata_name contains the name to be assigned to the vdata.NULL. As with the vdata name, the class may be assigned and reassigned any time after the vdata is created. The parameter vdata_class contains the class name to be assigned to the vdata.SUCCEED (or 0) or FAIL (or -1). The parameters for these routines are further defined in Table 4E on page 137.
4.5.1.2 Defining a Field within a Vdata: VSfdefine
VSfdefine defines a field within a newly-created vdata. Each VSfdefine call assigns the name contained in the argument fieldname, the data type contained in the argument data_type, and the order contained in the argument order to one new field. Once data is written to a vdata, the name, data type and order of the field may not be modified or deleted.
Note that VSfdefine does not allocate memory for the field, but simply introduces the field. The field definition must be completed by VSsetfields, which is discussed in Section 4.5.1.3 on page 136.
VSfdefine returns either SUCCEED (or 0) or FAIL (or -1). The parameters for VSfdefine are further described in Table 4E on page 137.
TABLE 4D - Predefined Data Types and Field Names for Vdata Fields
|
|
|
| ||||
|
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
The parameter
fieldname_list is a comma-separated list of the field names, with no white space included. The fields can be either the predefined fields or the fields that have been previously introduced by VSfdefine. VSfdefine allows a user to declare a field, along with its data type and order, but VSsetfields finalizes the definition by allowing the user to select the fields that are to be included in the vdata. Thus, any fields created by VSfdefine that are not in the parameter fieldname_list of VSsetfields will be ignored. This feature was originally intended for interactive-mode users. The combined width of the fields in the parameter fieldname_list is also the length of the record and must be less than MAX_FIELD_SIZE (or 65535). An attempt to create a larger record will cause VSsetfields to return FAIL (or -1).SUCCEED (or 0) or FAIL (or -1). The parameters for VSsetfields are further defined in Table 4E on page 137.
4.5.1.4 Specifying the Interlace Mode: VSsetinterlace
The Vdata interface supports two types of interlacing: file interlacing and buffer interlacing. File interlacing determines how data is stored in a file and buffer interlacing determines how data is stored in memory. The Vdata interface can write data from a buffer to a file in an interlaced or non-interlaced manner. It can also read data from a file in an interlaced or non-interlaced manner.
VSsetinterlace sets the file interlacing mode for a vdata. Setting the parameter interlace_mode to FULL_INTERLACE (or 0) fills the vdata by record, whereas specifying NO_INTERLACE (or 1) fills the vdata by field. (See Figure 4d.) For multi-component fields, all components are treated as a single field.
As with file interlacing, the default buffer interlace mode is
FULL_INTERLACE because it is more efficient to write complete records than it is to write fields if the file and buffer interlace modes are the same, although both require the same amount of disk space.
FIGURE 4d - Interlaced and Non-Interlaced Vdata Contents
SUCCEED (or 0) or FAIL (or -1). The parameters for VSsetinterlace are further described in Table 4E.
TABLE 4E - VSsetname, VSsetclass, VSfdefine, VSsetfields, and VSsetinterlace Parameter Lists
Writing to a vdata requires the following steps:
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);
vdata_id = VSattach(file_id, vdata_ref, vdata_access_mode);
status = VSsetfields(vdata_id, fieldname_list);
record_pos = VSseek(vdata_id, record_index);
num_of_recs = VSwrite(vdata_id, databuf, n_records, interlace_mode);
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)
status = vsfsfld(vdata_id, fieldname_list);
record_pos = vsfseek(vdata_id, record_index);
num_of_recs = vsfwrt(vdata_id, databuf, n_records, interlace_mode)
OR num_of_recs = vsfwrtc(vdata_id, databuf, n_records, interlace_mode)
OR num_of_recs = vsfwrit(vdata_id, databuf, n_records, interlace_mode)
status = vsfdtch(vdata_id)
status = vfend(file_id)
status = hclose(file_id)
4.5.2.1 Resetting the Current Position within Vdatas: VSseek
VSseek provides a mechanism for random access to fully-interlaced vdatas. Random-access for non-interlaced vdatas is not available. The parameter record_index is the position of the record to be written. The position of the first record in a vdata is specified by record_index = 0. Any vdata operation will be performed on this record by default; vdata operations on other records require that VSseek be called first to specify the target record.
Note that, because the record location numbering starts at 0, the record location and the value of the parameter
record_index are off by 1. For example, reading the fourth record in the buffer requires record_index to be set to 3. FIGURE 4e - Setting the Record Pointer to the End of a Vdata
record_index to 4 results in an error condition. Setting the parameter record_index to 3 places the current record pointer at the beginning of the fourth record. We then use VSread to read the contents of the fourth record into a buffer; this moves the current record pointer to the end of the fourth record. The contents of the buffer can then be discarded and a write operation can be called to append data to the end of the vdata.FAIL (or -1). Its parameters are further defined in Table 4F.
4.5.2.2 Writing to a Vdata: VSwrite
VSwrite writes buffered data to a specified vdata. The parameter databuf is a buffer containing the records to be stored in the vdata. The parameter n_records specifies the number of records to be stored.interlace_mode in the call to VSwrite when data is written to the file. The array databuf is assumed to be organized in memory as specified by interlace_mode. Setting interlace_mode to FULL_INTERLACE (or 0) indicates that the array in memory is organized by record, whereas to NO_INTERLACE (or 1) indicates that the array is organized by field. (See Figure 4f.) VSwrite will write interlaced or non-interlaced data to a vdata in a file: interlaced data in the buffer can be written to the vdata in the file as non-interlaced data and vice versa. If the data is to be stored with an interlace mode different from that of the buffer, VSsetinterlace (described in Section 4.5.1.4 on page 136) must be called prior to VSwrite. Multiple write operations can only be used on fully-interlaced vdatas in the file.
FIGURE 4f - Writing Interlaced or Non-interlaced Buffers into Interlaced or Non-interlaced Vdatas
databuf is assumed to contain the exact amount of data in the order needed to fill the fields defined in the last call to VSsetfields. Because VSwrite writes the contents of databuf contiguously to the vdata, any "padding" due to record alignment must be removed before attempting to write from databuf to the vdata. For more information on alignment padding see Section 4.5.2.3 on page 141.
It should be remembered that VSwrite writes whole records, not individual fields. If a modification to one field within a previously-written record is needed, the contents of the record must first be preserved by reading it to a buffer with VSread, which will be described in Section 4.6.2 on page 145; the record must then be updated in the buffer and written back to the file with VSwrite.
To store a vdata to the file after being created, either VSsetname, VSsetfields, or VSwrite must be called before VSdetach for the vdata. If VSwrite is not called, the vdata created will be empty.
FAIL (or -1). Its parameters are further defined in Table 4F.
TABLE 4F - VSseek and VSwrite Parameter Lists
To clarify the illustration, let us assume that the vdata is used to contain the data of some particles collected from an experiment. Each record of the data includes the position of a particle, its weight, and the minimum and maximum temperature the particle can endure. The vdata is named "Solid Particle", contains 10 records, and belongs to a class, named "Particle Data". The fields of the vdata include "Position", "Mass", and "Temperature". The field "Position" has an order of 3 for the x, y, and z values representing the position of a particle. The field "Mass" has an order of 1. The field "Temperature" has an order of 2 for the minimum and maximum temperature. The program creates the vdata, sets its name and class name, defines its fields, and then writes the data to it.
C version
4.5.2.3 Packing or Unpacking Field Data: VSfpack
Storing fields of mixed data types is an efficient use of disk space and is useful in applications that use structures. However, while data structures in memory containing fields of variable lengths can contain alignment bytes, field data stored in a vdata cannot include them. This is true for both fully-interlaced and non-interlaced data. Because of this storing limitation, when variable-length field types are used, it is generally not possible to write data directly from a structure in memory into a vdata in a file with a VSwrite call or to read data directly into a buffer from the vdata with a call to VSread. Thus, when writing, VSfpack is used to pack field data into a temporary buffer by removing the padding, or alignment bytes, and when reading, to unpack field data into vdata fields by adding necessary alignment bytes. The syntax for VSfpack is as follows:C: status = VSfpack(vdata_id, action, fields_in_buf, buf, buf_size, n_records, fieldname_list, bufptrs);
FORTRAN: 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)
The process of removing the alignment bytes is called "packing the array." An illustration of this process is provided in Figure 4g. The data provided by the user is stored in the structure in memory. The field values are aligned with padded bytes. VSfpack packs the data into the array in memory after removing the padded bytes. The packed data is then written to the vdata in the file by VSwrite.
FIGURE 4g - Removing Alignment Bytes When Writing Data From a C Structure to a Vdata
VSfpack performs both tasks, packing and unpacking, and the parameter
action specifies the appropriate action for the routine. Valid values for the parameter action are _HDF_VSPACK (or 0) for packing and _HDF_VSUNPACK (or 1) for unpacking.buf to hold all packed or unpacked fields. The parameter buf_size specifies the size of the buffer buf and should be at least n_records *( the total size of all fields specified in fields_in_buf). buf, the parameter fields_in_buf must specify all fields of the vdata. This can be accomplished either by listing all of the field names in fields_in_buf or by setting fields_in_buf to NULL in C or to one blank character in FORTRAN-77.fields_in_buf may specify a subset of the vdata fields. The parameter fields_in_buf can be set to NULL in C or to one space character in FORTRAN-77 to specify all fields in the vdata.fieldname_list specifies the field(s) to be packed or unpacked. The parameter bufptrs provides pointers to the buffers for each field to be packed or unpacked. The calling program is responsible for allocating sufficient space for each field buffer. Significant differences between the C and FORTRAN-77 functionality are described in the following paragraphs.fieldname_list can list either all of the fields specified by fields_in_buf or a subset of those fields. Only if fields_in_buf specifies all of the vdata fields, then fields_in_buf can be set to NULL to specify all vdata fields. The parameter bufptrs contains an array of pointers to the buffers where field data will be packed or unpacked.fieldname_list contains only the name of that field. The parameter bufptrs is the buffer for that field.
VSfpack returns either SUCCEED (or 0) or FAIL (or -1). The parameters for VSfpack are described in Table 4G.
TABLE 4G - VSfpack Parameter List
In this example, the program creates an HDF file, named "Packed_Vdata.hdf", then defines a vdata which is named "Mixed Data Vdata" and belongs to class "General Data Class". The vdata contains four order-1 fields, "Temp", "Height", "Speed", and "Ident" of type float32, int16, float32, and char8, respectively. The program then packs the data in fully interlaced mode into a databuf and writes the packed data to the vdata. Note that, in the C example, a VSfpack call packs all N_RECORDS and a VSwrite call writes out all N_RECORDS records. In the Fortran example, N_RECORDS of each field are packed using separate calls to vsfnpak and vsfcpak; vsfwrit writes packed data to the vdata.
C version