1 Version 4.0 -- 5/1/89 bcp_bind
______________________________________________________________________
NAME: bcp_bind
FUNCTION:
Bind data from a program variable to a SQL Server table.
SYNTAX:
RETCODE bcp_bind (dbproc, varaddr, prefixlen, varlen,
terminator, termlen, type, table_column)
DBPROCESS *dbproc;
BYTE *varaddr;
int prefixlen;
bcp_bind Version 4.0 -- 5/1/89 2
______________________________________________________________________
DBINT varlen;
BYTE *terminator;
int termlen;
int type;
int table_column;
COMMENTS:
o There may be times when you want to copy data directly from a
program variable into a table in SQL Server, without having to
first place the data in a host file or use the SQL INSERT com-
mand. The bcp_bind() function is a fast and efficient way to
do this.
o You must call bcp_init() before calling this or any other bulk
copy functions.
o There must be a separate bcp_bind() call for every column in
the SQL Server table into which you want to copy. After the
3 Version 4.0 -- 5/1/89 bcp_bind
______________________________________________________________________
necessary bcp_bind() calls have been made, you then call
bcp_sendrow() to send a row of data from your program variables
to SQL Server. The table to be copied into is set by calling
bcp_init().
o Whenever you want SQL Server 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.
o When there are no more rows to be inserted, call bcp_done().
Failure to do so will result in an error.
o When using bcp_bind(), the host filename parameter used in the
call to bcp_init(), hfile, must be set to NULL, and the direc-
tion parameter, direction, must be set to DB_IN.
o Control parameter settings, specified with bcp_control(), have
no effect on bcp_bind() row transfers.
bcp_bind Version 4.0 -- 5/1/89 4
______________________________________________________________________
o It is an error to call bcp_columns() when using bcp_bind().
o 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. */
5 Version 4.0 -- 5/1/89 bcp_bind
______________________________________________________________________
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);
bcp_bind Version 4.0 -- 5/1/89 6
______________________________________________________________________
}
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;
7 Version 4.0 -- 5/1/89 bcp_bind
______________________________________________________________________
/* 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);
o For information on the bcp utility program, see its manual page
in the Commands Reference.
PARAMETERS:
dbproc - A pointer to the DBPROCESS structure that provides the
bcp_bind Version 4.0 -- 5/1/89 8
______________________________________________________________________
connection for a particular front-end/SQL Server process. It
contains all the information that DB-Library uses to manage
communications and data between the front end and SQL Server.
varaddr - 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 SQL Server in chunks by
bcp_moretext(), rather than all at once by bcp_sendrow().
prefixlen - The length, in bytes, of any length prefix this
column may have. For example, strings in some non-C program-
ming languages are made up of a one-byte length prefix, fol-
lowed by the string data itself. If the data does not have a
length prefix, set prefixlen to 0.
varlen - 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
9 Version 4.0 -- 5/1/89 bcp_bind
______________________________________________________________________
parameter.
For fixed-length datatypes, such as integers, 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 character, text, binary, and image data, 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
bcp_bind Version 4.0 -- 5/1/89 10
______________________________________________________________________
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.
terminator - A pointer to the byte pattern, if any, that marks
the end of this program variable. For example, C strings
usually have a one-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 previous example uses two tabs
as the program variable terminator. It could be rewritten to
use a C null terminator instead, as follows:
11 Version 4.0 -- 5/1/89 bcp_bind
______________________________________________________________________
(bcp_bind (dbproc, co_name, 0, -1, "", 1, 0, 2)
termlen - The length of this program variable's terminator, if
any. If there is no terminator for the variable, set termlen
to 0.
type - The datatype of your program variable, expressed as a
SQL Server 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() manual page for a list of supported conver-
sions. That manual page also contains a list of SQL Server
datatypes.
table_column - The column in the database table to which the
data will be copied. Column numbers start at 1.
RETURNS:
SUCCEED or FAIL.
bcp_bind Version 4.0 -- 5/1/89 12
______________________________________________________________________
SEE ALSO:
bcp_batch, bcp_colfmt, bcp_collen, bcp_colptr, bcp_columns,
bcp_control, bcp_done, bcp_exec, bcp_init, bcp_moretext,
bcp_sendrow