When using row-wise binding, an application defines a structure containing one, two, or in some cases three, elements for each column in which data is to be returned. The first element holds the data value and the second element holds the length/indicator buffer. Indicators and length values can be stored in separate buffers by setting the SQL_DESC_INDICATOR_PTR and SQL_DESC_OCTET_LENGTH_PTR descriptor fields to different values. If this is done, the structure contains a third element. The application then allocates an array of these structures, which contains as many elements as there are rows in the rowset.
The application declares the size of the structure to the driver with the SQL_ATTR_ROW_BIND_TYPE statement attribute. It then binds the address of each member in the first element of the array. Thus, the driver can calculate the address of the data for a particular row and column as:
Address = Bound Address + ((Row Number) * Structure Size)
where rows are numbered from 1 to the size of the rowset. Figure 5.4 shows how row-wise binding works. Generally, only columns that will be bound are included in the structure. The structure can contain fields that are unrelated to result set columns. The columns can be placed in the structure in any order, but are shown in sequential order for clarity.
Figure 5.4. Row-wise binding. Each row of the vector contains a structure. The structure has fields for the data (in blue) and fields for the length/indicator buffer (in green).
Example 5.6 is a modified version of Example 5.5. This example uses row-wise binding instead of column-wise binding. Both examples are very similar. The main differences are readily marked in the program. Note that to indicate row-wise binding, we set the attribute SQL_ATTR_ROW_BIND_TYPE to the size of the row structure (in this case to the size of the structure defined as TitlesStruct). The Fortran standard does not include a function to compute the size in bytes of a structure. However, most implementations offer a non-standard function to do so. In many compilers, the non-standard function, sizeof() returns the number of bytes used by a structure. The name of this function may be different in your compiler. Another important point to keep in mind when using row-wise binding from Fortran is that Fortran compilers do not necessarily store the fields in a structure in the same sequence they have been declared. Although having the variables in sequence is not a requirement for row-wise binding, in the example we use the time-stamp structure (TIMESTAMP_STRUCT) which is declared in sequence (this is necessary to ensure that time-stamp data are put in the right places by the driver). This forces us to declare TitlesStruct as a sequence structure (the standard in Fortran indicates that structures containing sequence sub-structures must also be declared with the sequence attribute).
|