Providing long data for bulk inserts and positioned updates

To provide long data for bulk inserts or positioned updates, use SQLBulkOperations() or SQLSetPos() calls.

Procedure

To perform a bulk insert or positioned update with long data:

  1. Bind the data using SQLBindCol(). When you call SQLBindCol():
    1. Place an application-defined value, such as the column number, in the *rgbValue buffer for a data-at-execution column. The value in the *rgbValue buffer can be used later to identify the column.
    2. Place the SQL_DATA_AT_EXEC value in the *pcbValue buffer.
  2. Call SQLBulkOperations() or SQLSetPos().
    If there are data-at-execution columns, SQLBulkOperations() returns SQL_NEED_DATA and proceeds to step 3. If there are no data-at-execution columns, the process is complete.
  3. Call SQLParamData() to retrieve the address of the *rgbValue buffer for the first data-at-execution column that is to be processed.
    SQLParamData() returns SQL_NEED_DATA.
    1. Retrieve the application-defined value from the *rgbValue buffer.
      Although data-at-execution parameters are similar to data-at-execution columns, the value that is returned by SQLParamData() is different for data-at-execution parameters and data-at-execution columns. Data-at-execution columns are columns in a rowset for which you send data with SQLPutData() after you insert or update a row with SQLBulkOperations() or SQLSetPos(). You bind data-at-execution columns with SQLBindCol(). The value that is returned by SQLParamData() is the address of the row in the *rgbValue buffer that is being processed.
  4. Call SQLPutData() one or more times to send data for the column.
    More than one call is needed if all the data values cannot be returned in the *rgbValue buffer that is specified in SQLPutData(). Multiple calls to SQLPutData() for the same column are allowed only under the following circumstances:
    • When you send character C data to a column with a character, binary, or data-source-specific data type
    • When you send binary C data to a column with a character, binary, or data-source-specific data type
  5. Call SQLParamData() again to signal that all data has been sent for the column.
    • If there are more data-at-execution columns, SQLParamData() returns SQL_NEED_DATA and the address of the *rgbValue buffer for the next data-at-execution column that is to be processed. Repeat steps 3 and 3.
    • If there are no more data-at-execution columns, the process is complete.

      If the statement executes successfully, SQLParamData() returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO. If the execution fails, it returns SQL_ERROR. At this point, SQLParamData() can return any SQLSTATE that can be returned by SQLBulkOperations().

    • If the operation is canceled, or an error occurs in SQLParamData() or SQLPutData(), after SQLBulkOperations() or SQLSetPos() returns SQL_NEED_DATA, and before you retrieve data for all data-at-execution columns, you can call only SQLCancel(), SQLGetDiagRec(), SQLGetFunctions(), SQLParamData(), or SQLPutData() for the statement or the connection that is associated with the statement. If you call any other function for the statement or the connection that is associated with the statement, the function returns SQL_ERROR and SQLSTATE HY010 (function sequence error).
    • If you call SQLCancel() while ODBC needs data for data-at-execution columns, ODBC cancels the operation. You can then call SQLBulkOperations() or SQLSetPos() again. Canceling does not affect the cursor state or the current cursor position.