Transfers a column’s data in chunks during a bulk-copy operation.
CS_RETCODE blk_textxfer(blkdesc, buffer, buflen,
outlen)
CS_BLKDESC *blkdesc;
CS_BYTE *buffer;
CS_INT buflen;
CS_INT *outlen;
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 the space from which blk_textxfer picks up the chunk of text, image, sensitivity, or boundary data.
The length, in bytes, of the *buffer data space.
A pointer to an integer variable. outlen is not used for a bulk-copy-in operation and should be passed as NULL.
For a bulk-copy-out operation, *outlen represents the length, in bytes, of the data copied to *buffer.
blk_textxfer returns:
Returns |
Indicates |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
CS_END_DATA |
When copying data out from a database, blk_textxfer returns CS_END_DATA to indicate that a complete column value has been sent. When copying data into a database, blk_textxfer returns CS_END_DATA when an amount of data equal to blk_bind’s *datalen has been sent. |
CS_PENDING |
Asynchronous network I/O is in effect. See the “Asynchronous Programming” topics page in the Open Client Client-Library/C Reference Manual. |
/*
** BulkCopyIn()
**
** BLKDATA and DATA_END are defined in the bulk copy
** example program.
*/
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.....
/* Bind columns and transfer rows */
dptr = BLKDATA;
while (dptr->pub_id != DATA_END)
{
datafmt.datatype = CS_INT_TYPE;
datafmt.count = 1;
datafmt.maxlength = sizeof(CS_INT);
datalen[0] = CS_UNUSED;
if (blk_bind(blkdesc, 1, &datafmt, &dptr->pub_id,
&datalen[0], NULL) != CS_SUCCEED)
{
ex_error("BulkCopyIn: blk_bind(1) failed");
return CS_FAIL;
}
datafmt.datatype = CS_CHAR_TYPE;
datafmt.maxlength = MAX_PUBNAME - 1;
datalen[1] = strlen(dptr->pub_name);
if (blk_bind(blkdesc, 2, &datafmt, dptr->pub_name,
&datalen[1], NULL) != CS_SUCCEED)
{
ex_error("BulkCopyIn: blk_bind(2) failed");
return CS_FAIL;
}
datafmt.maxlength = MAX_PUBCITY - 1;
datalen[2] = strlen(dptr->pub_city);
if (blk_bind(blkdesc, 3, &datafmt, dptr->pub_city,
&datalen[2], NULL) != CS_SUCCEED)
{
ex_error("BulkCopyIn: blk_bind(3) failed");
return CS_FAIL;
}
datafmt.maxlength = MAX_PUBST - 1;
datalen[3] = strlen(dptr->pub_st);
if (blk_bind(blkdesc, 4, &datafmt, dptr->pub_st,
&datalen[3], NULL) != CS_SUCCEED)
{
ex_error("BulkCopyIn: blk_bind(4) failed");
return CS_FAIL;
}
datafmt.datatype = CS_TEXT_TYPE;
datafmt.maxlength = MAX_BIO - 1;
datalen[4] = strlen((char *)dptr->pub_bio);
if (blk_bind(blkdesc, 5, &datafmt, NULL,
&datalen[4], NULL) != CS_SUCCEED)
{
ex_error("BulkCopyIn: blk_bind(5) failed");
return CS_FAIL;
}
if (blk_rowxfer (blkdesc) == CS_FAIL)
{
ex_error("BulkCopyIn: EX_BLK - Failed on \
blk_rowxfer.");
return CS_FAIL;
}
if (blk_textxfer(blkdesc, dptr->pub_bio,
datalen[4], &len) == CS_FAIL)
{
ex_error("BulkCopyIn: blk_rowxfer() failed");
return CS_FAIL;
}
dptr++;
}
/* ALL the rows sent so clear up */
...CODE DELETED.....
return CS_SUCCEED;
}
blk_textxfer is a client-side routine.
blk_textxfer transfers large text or image values. blk_textxfer does not perform any data conversion; it simply transfers data.
There are two ways for an application to transfer text and image values during a bulk-copy operation:
The application can treat text or image data like ordinary data: that is, it can bind columns to program variables and transfer rows using blk_rowxfer_mult. Generally, this method is convenient for small text and image values but not for larger ones. If the entire value is to be transferred by blk_rowxfer_mult, the application must allocate program variables that are large enough to hold entire column values.
Using blk_textxfer, the application can transfer text or image data in chunks. This method allows the application to use a transfer buffer that is smaller than the values to be transferred.
An application marks a column for transfer through blk_textxfer by calling blk_bind for the column with a NULL buffer parameter. If the transfer is going into the database, pass the total length of the value as blk_bind’s *datalen parameter.
An application’s blk_bind calls do not have to be in column order, but data for blk_textxfer columns must be transferred in column order.
For example, an application can bind columns 3 and 4, and then mark columns 2 and 1 for transfer using blk_textxfer. After calling blk_rowxfer_mult to copy data for columns 3 and 4, the application needs to call blk_textxfer to transfer data for column 1 before calling it for column 2.
When copying data into a database, if a text, image, boundary, or sensitivity datatype column is marked for transfer using blk_textxfer, all subsequent columns of these types must also be marked for transfer using blk_textxfer.
For example, an application cannot mark the first text column in a row for transfer using blk_textxfer and then bind a subsequent text column to a program variable.
When copying data into a database, an application is responsible for calling blk_textxfer the correct number of times to transfer the complete text or image value.
When using blk_textxfer to copy data out of a database, only columns that follow bound columns are available for transfer using blk_textxfer. In other words, columns being transferred using blk_textxfer must reside at the end of row.
For example, an application cannot bind the first two columns in a row to program variables, mark the third for transfer using blk_textxfer, and bind the fourth.
When copying data out from a database, blk_textxfer returns CS_END_DATA to indicate that a complete column value has been copied.
