Transfers one or more rows during a bulk-copy operation.
CS_RETCODE blk_rowxfer_mult(blkdesc, row_count) CS_BLKDESC *blkdesc; CS_INT *row_count;
A pointer to the CS_BLKDESC that is serving as a control block for the bulk-copy operation. blk_alloc allocates a CS_BLKDESC structure.
A pointer to a CS_INT variable or NULL.
For bulk-copy-out operations, blk_rowxfer_mult returns with *row_count set to the number of rows read by the call. If row_count is NULL, this information is not available to the application. (The application can call blk_done to determine how many rows have been transferred by the cumulative number of blk_rowxfer_mult calls since the last blk_done call—but it is simpler to use a row count variable.
For bulk-copy-in operations, blk_rowxfer_mult sends the number of rows specified by *row_count to the server. If row_count is NULL or *row_count is 0, then the number of rows specified by datafmt−>count in previous calls to blk_bind are sent to the server.
row_count is used by applications that perform array binding. For more information on this feature, see “Array binding”.
blk_rowxfer_mult returns:
Returns |
Indicates |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
CS_PENDING |
Asynchronous network I/O is in effect. For more information, see the “Asynchronous Programming” topics page in the Open Client Client-Library/C Reference Manual. |
CS_BLK_HAS_TEXT |
The row contains one or more columns which have been marked for transfer using blk_textxfer. The application must call blk_textxfer to transfer data for these columns row before calling blk_rowxfer_mult to transfer the next row. |
CS_END_DATA |
When copying data out from a database, blk_rowxfer_mult returns CS_END_DATA to indicate that all rows have been transferred. When copying data into a database, blk_rowxfer_mult does not return CS_END_DATA. |
CS_ROW_FAIL |
A recoverable error occurred while fetching a row. Applies to bulk-copy-out operations only. blk_rowxfer_mult sets *row_count to indicate the number of rows transferred (including the row containing the error) and transfers no rows after that row. The next call to blk_rowxfer_mult will read rows starting with the row after the one where the error occurred. Recoverable errors include memory allocation failures and conversion errors (such as overflowing the destination buffer) that occur while copying row values to program variables. In the case of buffer-overflow errors, blk_rowxfer_mult sets the corresponding *indicator variable(s) to a value greater than 0. Indicator variables must have been specified in the application’s calls to blk_bind. When blk_rowxfer_mult returns CS_ROW_FAIL, the application must continue calling blk_rowxfer_mult to keep retrieving rows, or it can call ct_cancel to cancel the remaining results. |
A common reason for a blk_rowxfer_mult failure is conversion error.
blk_rowxfer_mult is a client-side routine.
An application calls blk_rowxfer_mult to transfer rows between program variables (bound with blk_bind) and the database table:
During a bulk-copy-in operation, blk_rowxfer_mult copies data from program variables to the database.
During a bulk-copy-out operation, blk_rowxfer_mult copies data from the database and places it in program variables.
Application variables must first be bound to table columns with blk_bind for blk_rowxfer_mult to read or write their contents.
To transfer rows into a database, an application calls blk_rowxfer_mult repeatedly to transfer values from program variables to the database table. See “Program structure for bulk-copy-in operations” for the sequence of Bulk-Library calls used to transfer data into a database table.
During bulk-copy-in operations, the value of blk_rowxfer_mult’s *row_count parameter overrides the array lengths that were passed to blk_bind (as datafmt−>count). The number of rows transferred per call is determined as follows:
If the application passes the address of a row count variable as the row_count parameter, then blk_rowxfer_mult transfers either datafmt−>count or *row_count rows, whichever is smaller.
If the application passes row_count as NULL, blk_rowxfer_mult always transfers datafmt−>count rows.
For example, if an application was uploading 103 rows and it used array binding to transfer 10 rows at a time, the application would:
Pass datafmt−>count as 10 in all calls to blk_bind
Set *row_count to 10 for the first 10 calls to blk_rowxfer_mult
Set *row_count to 3 for the final call to blk_rowxfer_mult
To upload row data that contains large text or image column values, you can forgo array binding and use blk_textxfer together with blk_rowxfer_mult to send large values one piece at a time. See “Transferring large text or image values in chunks” for details.
A bulk-copy-in operation is not automatically terminated if blk_rowxfer_mult returns CS_FAIL. An application can continue to call blk_rowxfer_mult after correcting or discarding the problem row.
To transfer rows out of a database, an application calls blk_rowxfer_mult repeatedly to read column values from the server and place them in program variables. See “Program structure for bulk-copy-out operations” for the sequence of Bulk-Library calls used to read data from a database table.
For bulk copies out of a database, the use of blk_rowxfer_mult is similar to the use of the Client-Library ct_fetch routine.
The number of rows to be read by blk_rowxfer_mult is determined by the value passed as datafmt−>count in the application’s calls to blk_bind. blk_rowxfer_mult attempts to read this number of rows and write the data to program variables.
Fewer rows may be read by the final call to blk_rowxfer_mult (that is, the call that retrieves the last row in the table) or if a conversion error occurs while data is being retrieved. The former condition is indicated by a return code of CS_END_DATA; the latter, by CS_ROW_FAIL. In either case, blk_rowxfer_mult returns with *row_count set to the actual number of rows read.
To download row data that contains large text or image column values, you can forgo array binding and use blk_textxfer together with blk_rowxfer_mult to read large values one piece at a time. See the following section for details.
If array binding is not in effect, an application can use blk_textxfer in conjunction with blk_rowxfer_mult to transfer rows containing large text or image values. For information on how to do this, see “Bulk-Library client programming”.
For tables that contain large text or image columns, it is often convenient for an application to transfer the text or image data in fixed-size chunks rather than all at once. If a column is transferred all at once, the application must have sufficient buffer space to hold the value in its entirety.
To transfer large column values in chunks:
The application passes buffer as NULL in its blk_bind call for the column. This setting specifies that data for this column will be transferred using blk_textxfer. For a bulk-copy-in operation, the application must also specify the length of the column value as blk_bind’s *datalen parameter.
The application calls blk_rowxfer_mult to transfer the row. blk_rowxfer_mult returns CS_BLK_HAS_TEXT, indicating that Bulk-Library expects further data for this row to be transferred with blk_textxfer.
For each column requiring transfer, the application calls blk_textxfer in a loop until blk_textxfer returns CS_END_DATA, indicating that all of the data for this column has been transferred.
