Marks a complete bulk-copy operation or a complete bulk-copy batch.
CS_RETCODE blk_done(blkdesc, type, outrow) CS_BLKDESC *blkdesc; CS_INT type; CS_INT *outrow;
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.
One of the following symbolic values:
Value of type |
blk_done |
|---|---|
CS_BLK_ALL |
Marks a complete bulk-copy-in or bulk-copy-out operation. |
CS_BLK_BATCH |
Marks the end of a batch of rows in a batched bulk-copy-in operation. |
CS_BLK_CANCEL |
Cancels a bulk-copy batch or bulk-copy operation. |
A pointer to an integer variable. If type is CS_BLK_BATCH or CS_BLK_ALL, blk_done sets *outrow to the number of rows bulk copied to Adaptive Server since the application’s last blk_done call. When type is CS_BLK_CANCEL, *outrow is set to 0.
blk_done 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. |
Common reasons for blk_done failure include:
An invalid blkdesc pointer
An invalid value for type
/*
** BulkCopyIn()
*/
CS_STATIC CS_RETCODE
BulkCopyIn(connection)
CS_CONNECTION *connection;
{
CS_BLKDESC *blkdesc;
CS_DATAFMT datafmt; /* variable descriptions */
Blk_Data *dptr; /* data for transfer */
CS_INT datalen[5]; /* variable data length */
CS_INT len;
CS_INT numrows;
/*
** Ready to start the bulk copy in now that all the
** connections have been made and have a table name.
** Start by getting the bulk descriptor initializing.
*/
...CODE DELETED.....
/*
** Now to bind the variables to the columns and
** transfer the data
*/
...CODE DELETED.....
/* ALL the rows sent so clear up */
if (blk_done(blkdesc, CS_BLK_ALL, &numrows) == CS_FAIL)
{
ex_error("BulkCopyIn: blk_done() failed");
return CS_FAIL;
}
if (blk_drop(blkdesc) == CS_FAIL)
{
ex_error("BulkCopyIn: blk_drop() failed");
return CS_FAIL;
}
return CS_SUCCEED;
}
A client-side routine called blk_done is necessary in both client-only and gateway applications.
Setting CS_OPT_NOCOUNT before
doing a bulk copy operation on a connection, causes blk_done to erroneously
report errors.
Calling blk_done with type as CS_BLK_ALL marks the end of a bulk-copy operation. Once an application marks the end of a bulk-copy operation, it cannot call any Bulk-Library routines (except for blk_drop and blk_alloc) until it begins a new bulk-copy operation by calling blk_init.
Calling blk_done with type as CS_BLK_BATCH marks the end of a batch of rows in a bulk-copy-in operation. CS_BLK_BATCH is legal only during bulk-copy-in operations.
Calling blk_done with type as CS_BLK_CANCEL cancels the current bulk-copy operation. Rows transferred since an application’s last blk_done(CS_BLK_BATCH) call are not saved in the database. Once an application cancels a bulk-copy operation, it cannot call any bulk-copy routines (except for blk_drop and blk_alloc) until it initializes a new bulk-copy operation by calling blk_init.
When an application bulk copies data into a database, the rows are permanently saved only when the application calls blk_done. During a large data transfer, blk_done(CS_BLK_BATCH) can be called periodically to “batch” the transmitted rows into smaller units of recoverability.
An application can batch rows by calling blk_done with type as CS_BLK_BATCH once every n rows or when there is a lull between periods of data, as in a telemetry application. This causes all rows transferred since the application’s last blk_done call to be permanently saved.
After saving a batch of rows, an application’s first call to blk_rowxfer or blk_rowxfer_mult implicitly starts the next batch.
An application must call blk_done with type as CS_BLK_ALL to send its final batch of rows. This call permanently saves the rows, marks the end of the bulk-copy operation, and cleans up internal bulk-copy data structures.
After transferring the last row in a bulk-copy-out operation, an application must call blk_done with type as CS_BLK_ALL to mark the end of the bulk-copy operation and clean up internal bulk-copy data structures.
