Bind data from a program variable to an Adaptive Server Enterprise table.
RETCODE bcp_bind (dbproc, varaddr, prefixlen, varlen,
terminator, termlen, type,
table_column)
DBPROCESS *dbproc;
BYTE *varaddr;
int prefixlen;
DBINT varlen;
BYTE *terminator;
int termlen;
int type;
int table_column;
A pointer to the DBPROCESS structure that provides the connection for a particular front-end/Adaptive Server Enterprise process. It contains all the information that DB-Library uses to manage communications and data between the front end and Adaptive Server Enterprise.
The address of the program variable from which the data will be copied. If type is SYBTEXT or SYBIMAGE, varaddr can be NULL. A NULL varaddr indicates that text and image values will be sent to Adaptive Server Enterprise in chunks by bcp_moretext, rather than all at once by bcp_sendrow.
The length, in bytes, of any length prefix this column may have. For example, strings in some non-C programming languages are made up of a one-byte length prefix, followed by the string data itself. If the data does not have a length prefix, set prefixlen to 0.
The length of the data in the program variable, not including the length of any length prefix and/or terminator. Setting varlen to 0 signifies that the data is null. Setting varlen to -1 indicates that the system should ignore this parameter.
For fixed-length datatypes, such as integer, the datatype itself indicates to the system the length of the data. Therefore, for fixed-length datatypes, varlen must always be -1, except when the data is null, in which case varlen must be 0.
For char, text, binary, and image datatypes, varlen can be -1, 0, or some positive value. If varlen is -1, the system will use either a length prefix or a terminator sequence to determine the length. (If both are supplied, the system will use the one that results in the shortest amount of data being copied.) If varlen is -1 and neither a prefix length nor a terminator sequence is specified, the system will return an error message. If varlen is 0, the system assumes the data is null. If varlen is some positive value, the system uses varlen as the data length. However, if, in addition to a positive varlen, a prefix length and/or terminator sequence is provided, the system determines the data length by using the method that results in the shortest amount of data being copied.
A pointer to the byte pattern, if any, that marks the end of this program variable. For example, C strings usually have a 1-byte terminator whose value is 0. If there is no terminator for the variable, set terminator to NULL.
If you want to designate the C null terminator as the program variable terminator, the simplest way is to use an empty string ("") as terminator and set termlen to 1, since the null terminator constitutes a single byte. For instance, the second bcp_bind call in the “Example” section below uses two tabs as the program variable terminator. It could be rewritten to use a C null terminator instead, as follows:
bcp_bind (dbproc, co_name, 0, -1, "", 1, 0, 2)
The length of this program variable’s terminator, if any. If there is no terminator for the variable, set termlen to 0.
The datatype of your program variable, expressed as an Adaptive Server Enterprise datatype. The data in the program variable will be automatically converted to the type of the database column. If this parameter is 0, no conversion will be performed. See the dbconvert reference page for a list of supported conversions. That reference page also contains a list of Adaptive Server Enterprise datatypes.
The column in the database table to which the data will be copied. Column numbers start at 1.
SUCCEED or FAIL.
The following program fragment illustrates bcp_bind:
LOGINREC *login;
DBPROCESS *dbproc;
char co_name[MAXNAME];
DBINT co_id;
DBINT rows_sent;
DBBOOL more_data;
char *terminator = "\t\t";
/* Initialize DB-Library. */
if (dbinit() == FAIL)
exit(ERREXIT);
/* Install error-handler and message-handler. */
dberrhandle(err_handler);
dbmsghandle(msg_handler);
/* Open a DBPROCESS. */
login = dblogin();
BCP_SETL(login, TRUE);
dbproc = dbopen(login, NULL);
/* Initialize bcp. */
if (bcp_init(dbproc, "comdb..accounts_info",
NULL, NULL, DB_IN) == FAIL)
exit(ERREXIT);
/* Bind program variables to table columns. */
if (bcp_bind(dbproc, &co_id, 0, -1,
(BYTE *)NULL, 0, 0, 1) == FAIL)
{
fprintf(stderr, "bcp_bind, column 1, failed.\n");
exit(ERREXIT);
}
if (bcp_bind
(dbproc, co_name, 0, -1, (BYTE *)terminator,
strlen(terminator), 0, 2)
== FAIL)
{
fprintf(stderr, "bcp_bind, column 2, failed.\n");
exit(ERREXIT);
}
while (TRUE)
{
/* Process/retrieve program data. */
more_data = getdata(&co_id, co_name);
if (more_data == FALSE)
break;
/* Send the data. */
if (bcp_sendrow(dbproc) == FAIL)
exit(ERREXIT);
}
/* Terminate the bulk copy operation. */
if ((rows_sent = bcp_done(dbproc)) == -1)
printf("Bulk-copy unsuccessful.\n");
else
printf("%ld rows copied.\n", rows_sent);
There may be times when you want to copy data directly from a program variable into a table in Adaptive Server Enterprise, without having to first place the data in a host file or use the SQL insert command. The bcp_bind function is a fast and efficient way to do this.
You must call bcp_init before calling this or any other bulk copy functions.
There must be a separate bcp_bind call for every column in the Adaptive Server Enterprise table into which you want to copy. After the necessary bcp_bind calls have been made, you then call bcp_sendrow to send a row of data from your program variables to Adaptive Server Enterprise. The table to be copied into is set by calling bcp_init.
You can override the program variable data length (varlen) for a particular column on the current copy in by calling bcp_collen.
Whenever you want Adaptive Server Enterprise to checkpoint the rows already received, call bcp_batch. For example, you may want to call bcp_batch once for every 1000 rows inserted, or at any other interval.
When there are no more rows to be inserted, call bcp_done. Failure to do so will result in an error.
When using bcp_bind, the host file name parameter used in the call to bcp_init, hfile, must be set to NULL, and the direction parameter, direction, must be set to DB_IN.
Prefix lengths should not be used with fixed-length datatypes, such as integer or float. For fixed-length datatypes, since bulk copy can figure out the length of the data from the datatype, pass prefixlen as 0 and varlen as -1, except when the data is NULL, in which case varlen must be 0.
Control parameter settings, specified with bcp_control, have no effect on bcp_bind row transfers.
It is an error to call bcp_columns when using bcp_bind.
bcp_batch, bcp_colfmt, bcp_collen, bcp_colptr, bcp_columns, bcp_control, bcp_done, bcp_exec, bcp_init, bcp_moretext, bcp_sendrow
