Column-wise binding for array data

When you retrieve a result set into an array, you can call SQLBindCol() to bind application variables to columns in the result set. Before calling this function, you need to call SQLSetStmtAttr() to set the number of rows that you want to retrieve.

The following figure is a logical view of column-wise binding.

Figure 1. Column-wise binding
Begin figure summary. This figure shows an example result set with three columns and the six arrays that are used to retrieve this data. Detailed description available.
To perform column-wise array retrieval, include the following procedure in your application:
  1. Call SQLSetStmtAttr() to set the rowset size.

    If you plan to fetch rows with SQLExtendedFetch(), set the SQL_ATTR_ROWSET_SIZE attribute set to the number of rows that you want to retrieve with each fetch.

    If you plan to fetch rows with SQLFetchScroll(), set the SQL_ATTR_ROW_ARRAY_SIZE attribute set to the number of rows that you want to retrieve with each fetch.

    When the value of the SQL_ATTR_ROWSET_SIZE or SQL_ATTR_ROW_ARRAY_SIZE attribute is greater than 1 on a statement handle, Db2 ODBC treats deferred output data pointers and length pointers of that handle as pointers to arrays.

  2. Call SQLBindCol() for each column in the result set. In this call, include the following argument values:
    • Point the rgbValue argument to an array that is to receive data from the column that you specify with the icol argument.
    • For character and binary input data, specify the maximum size of the elements in the array with the input argument cbValueMax. (For other input data types, this argument is ignored.)
    • Optionally, you can retrieve the number of bytes that each complete value requires in the array that is to receive the column data. To retrieve length data, point the pcbValue argument to an array that is to hold the number of bytes that Db2 ODBC will return for each retrieved value. Otherwise, you must set this value to NULL.
  3. Call SQLExtendedFetch() or SQLFetchScroll() to retrieve the result data into the array.

    For an SQLExtendedFetch() call, if the number of rows in the result set is greater than the SQL_ATTR_ROWSET_SIZE attribute value, you must call SQLExtendedFetch() multiple times to retrieve all the rows.

    For an SQLExtendedScroll() call, if the number of rows in the result set is greater than the SQL_ATTR_ROW_ARRAY_SIZE attribute value, you must call SQLFetchScroll() multiple times to retrieve all the rows.

Db2 ODBC uses the value of the maximum buffer size argument to determine where to store each successive result value in the array. You specify this value in the cbValueMax argument in SQLBindCol(). Db2 ODBC optionally stores the number of bytes that each element contains in a deferred length array. You specify this deferred array in the pcbValue argument in SQLBindCol().