A typical application follows these steps to perform a bulk-copy-in operation:
Initializes the application in the same way as for a Client-Library application and sets up Client-Library error handling. Bulk-Library reports errors generated by calls to client-side routines as Client-Library messages.
Allocates the connection structure to be used.
Calls ct_con_props to set the necessary properties to connect to the target server. In addition, the application must set the CS_BULK_LOGIN property to CS_TRUE to enable the connection to perform bulk copies.
Programmers can often tune the Tabular Data Stream™ (TDS) packet
size to increase throughput. A packet size larger than the default usually
increases performance. First, make sure that the Adaptive Server is
configured to accept a larger TDS packet size, then set the CS_PACKET_SIZE
connection property in your application. See the Adaptive
Server Enterprise System Administration Guide for details
on increasing the allowable network packet size and the Open
Client Client-Library/C Reference Manual for
details on connection properties.
Calls ct_connect to open the connection.
Calls blk_alloc to allocate a bulk-descriptor structure.
Calls blk_init to initialize the bulk-copy operation.
For each column in the target table, the application:
(Optional) Calls blk_describe, which returns a target column’s description, allowing the application determine the column’s datatype or size.
(Optional) Calls blk_default, which returns a column’s default value, if a default is defined by the table schema. An application can call blk_bind with *datalen as 0 to indicate that the bulk-copy-in operation should use a column’s default value.
Calls blk_bind to bind the variable to the target column. If data for the column will be transferred using blk_textxfer, the application must call blk_bind with buffer as NULL.
Columns can be bound either to scalar variables or to arrays. When columns are bound to scalar variables, each call to blk_rowxfer_mult transfers column values for a single row from the bound variables into the database. For array binding, an array is bound to each column, and multiple rows are transferred by each call to blk_rowxfer_mult. In either case, the application also binds indicator and datalen variables to the column as well. These are used to indicate the condition of the data to be transferred.
The discussion in this chapter assumes that array binding is not in effect. For more information about array binding, see blk_bind in Chapter 4, “Bulk-Library Routines.”
Transfers the data.
While data remains to be transferred, the application places data into the program variables that are bound to the table columns, then calls blk_rowxfer_mult to transfer the row.
Before each call to blk_rowxfer_mult, for each bound column, the application sets datalen and indicator values to specify what value should be inserted:
datalen value |
indicator value |
Result |
|---|---|---|
> 0 |
Any (is ignored). |
blk_rowxfer_mult reads datalen bytes from buffer as the column value. |
0 |
0 |
The column’s default value, if available, is inserted. If no default is available, NULL is inserted. |
0 |
-1 |
NULL is inserted. |
If the row contains columns whose data is being transferred in chunks, the application calls blk_textxfer in a loop for each column. Data being transferred via blk_textxfer must reside at the end of the row, following any bound columns.
The application can call blk_done(CS_BLK_BATCH), if needed, to send a batch of rows. This call instructs the Adaptive Server to permanently save all rows transferred since the application’s last blk_done call.
Calls blk_done(CS_BLK_ALL) to send the last batch of rows and indicate that the bulk-copy operation is complete.
Calls blk_drop to deallocate the bulk-descriptor structure.
An application can call blk_bind between calls to blk_rowxfer_mult to specify
a different program variable address or length.
