When retrieving data, you might want
to retrieve more than one row at a time and store the data in an array.
Instead of fetching and copying each row of data into an array, or
binding to new storage areas, you can retrieve multiple rows of data
using row-wise binding. Row-wise binding associates an entire row
of the result set with a structure. The rowset is retrieved into
an array of structures, each of which holds the data in one row and
the associated length fields.
Before you begin
Before using row-wise binding to retrieve data into arrays,
ensure you have initialized your CLI application.
Procedure
To retrieve data using row-wise binding:
- Allocate an array of structures of size equal to the number
of rows to be retrieved, where each element of the structure is composed
of each row's data value and each data value's length.
For
example, if each row of the result set consisted of Column A of type
INTEGER, Column B of type CHAR(3), and Column C of type CHAR(10),
then you can allocate the example structure, where n represents the
number of rows in the result set:
struct { SQLINTEGER La; SQLINTEGER A;
SQLINTEGER Lb; SQLCHAR B[4];
SQLINTEGER Lc; SQLCHAR C[11];
} buffer[n];
- Specify that row-wise array retrieval will be used by setting
the SQL_ATTR_ROW_BIND_TYPE statement attribute, using
SQLSetStmtAttr() to
the size of the structure to which the result columns will be bound.
- Specify the number of rows that will be retrieved by setting
the SQL_ATTR_ROW_ARRAY_SIZE statement attribute using
SQLSetStmtAttr().
- Prepare and execute the SQL statement used to retrieve
the data.
- Bind each structure to the row by calling
SQLBindCol() for
each column of the row. CLI treats
the deferred output data pointer of SQLBindCol() as
the address of the data field for the column in the first element
of the array of structures. The deferred output length pointer is
treated as the address of the associated length field of the column.
- Retrieve the data by calling
SQLFetchScroll().
When returning data, CLI uses
the structure size provided with the SQL_ATTR_ROW_BIND_TYPE statement
attribute to determine where to store successive rows in the array
of structures.