NeXTSTEP 3.3 (Developer)/NeXT_Developer-3.3.iso/NextLibrary/Documentation/Sybase/DBLIB/Section3/bcp_bind.nr

Text File | 1993-04-22 | 6.9 KB | 215 lines

.Na "bcp_bind"
.mc |
.Aa
.Fu
Bind data from a program variable to a \*S table.
.Ih "bcp, bind data"
.Sy
.Sf "RETCODE bcp_bind (dbproc, varaddr, prefixlen, varlen,"
.sp -1v
.Sf "                  terminator, termlen, type, table_column)"
.Sp "DBPROCESS" "*dbproc"
.Sp "BYTE" "*varaddr"
.Sp "int" "prefixlen"
.Sp "DBINT" "varlen"
.Sp "BYTE" "*terminator"
.Sp "int" "termlen"
.Sp "int" "type"
.Sp "int" "table_column"
.Co
.Bl
There may be times when you want to copy data directly from a
program variable into a table in \*S, without having to
first place the data in a host file or use the SQL INSERT command.
The \f2bcp_bind()\f1 function is a fast and efficient way to do this.
.Bl
You must call \f2bcp_init()\f1 before calling this or any other bulk copy functions.
.Bl
There must be a separate \f2bcp_bind()\f1 call for every column in the
\*S table into which you want to copy. After the necessary
\f2bcp_bind()\f1 calls have been made, you then call \f2bcp_sendrow()\f1
to send a row of data from your program variables to \*S.
The table to be copied into is set by calling \f2bcp_init()\f1.
.Bl
Whenever you want \*S to checkpoint the rows already
received, call \f2bcp_batch()\f1. For example, you may want to call \f2bcp_batch()\f1 once
for every 1000 rows inserted, or at any other interval.
.Bl
When there are no more rows to be inserted, call \f2bcp_done()\f1. Failure
to do so will result in an error.
.Bl
When using \f2bcp_bind()\f1, the host filename parameter
used in the call to \f2bcp_init()\f1, \f2hfile\f1, must be set to NULL, and  the direction
parameter, \f2direction\f1, must be set to DB_IN.
.Bl
Control parameter settings, specified with \f2bcp_control()\f1, have no effect on
\f2bcp_bind()\f1 row transfers.
.Bl
It is an error to call \f2bcp_columns()\f1 when using \f2bcp_bind()\f1.
.Bl
The following program fragment illustrates \f2bcp_bind()\f1:
.SD
.ta +4n +4n +4n +4n +4n +4n +4n
.ne 5
LOGINREC        *login;
DBPROCESS       *dbproc;
char            co_name[MAXNAME];
DBINT           co_id;
DBINT           rows_sent;
DBBOOL            more_data;
char            *terminator = "\et\et";

/* 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.\en");
    exit(ERREXIT);
}

if (bcp_bind
    (dbproc, co_name, 0, -1, (BYTE *)terminator, strlen(terminator), 0, 2)
        == FAIL)
{
    fprintf(stderr, "bcp_bind, column 2, failed.\en");
    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.\en");
else
    printf("%ld rows copied.\en", rows_sent);
.ED
.Bl
For information on the \f2bcp\f1 utility program, see its manual page
in the \f2Commands Reference\f1.
.Bz
.Pa
.Pi dbproc
A pointer to the DBPROCESS structure that provides the connection
for a particular front-end/\*S process.  It contains all the
information that \*L uses to manage communications and data between the
front end and \*S.
.Pi varaddr
The address of the program variable from which the data
will be copied.
If \f2type\f1 is SYBTEXT or SYBIMAGE, \f2varaddr\f1 can be NULL.
A NULL \f2varaddr\f1 indicates
that text and image values will be
sent to \*S in chunks by \f2bcp_moretext()\f1, rather than all
at once by \f2bcp_sendrow()\f1.
.Pi prefixlen
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 \f2prefixlen\f1 to 0.
.Pi varlen
The length of the data in the program variable, \f2not\f1 including
the length of any length prefix and/or terminator.
Setting \f2varlen\f1 to 0 signifies that the data is null.
Setting \f2varlen\f1 to -1 indicates that the system should ignore
this parameter.
.sp 0.5v
For fixed-length datatypes, such as integers, the datatype itself
indicates to the system the length of the data.
Therefore, for fixed-length datatypes, \f2varlen\f1 must always
be -1, except when the data is null, in which case \f2varlen\f1
must be 0.
.sp 0.5v
For character, text, binary, and image data, \f2varlen\f1 can be
-1, 0, or some positive value.
If \f2varlen\f1 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 \f2varlen\f1 is -1 and neither a prefix length nor a
terminator sequence is specified, the system will return an error message.
If \f2varlen\f1 is 0, the system assumes the data is null.
If \f2varlen\f1 is some positive value, the system uses \f2varlen\f1 as
the data length.
However, if, in addition to a positive \f2varlen\f1,
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.
.Pi 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 \f2terminator\f1 to NULL.
.sp 0.5v
If you want to designate the C null terminator as the program variable terminator,
the simplest way is to
use an empty string ("") as \f2terminator\f1 and set \f2termlen\f1 to 1, since
the null terminator constitutes a single byte.
For instance,
the second \f2bcp_bind()\f1 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:
.SD
.in +3n
(bcp_bind (dbproc, co_name, 0, -1, "", 1, 0, 2)
.in -3n
.ED
.Pi termlen
The length of this program variable's terminator, if any.
If there is no terminator for the variable, set \f2termlen\f1 to 0.
.Pi type
The datatype of your program variable, expressed as a \*S 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 \f2dbconvert()\f1 manual page for a list of
supported conversions.
That manual page also contains a list of \*S datatypes.
.Pi table_column
The column in the database table to which the data will
be copied. Column numbers start at 1.
.in -.375i
.Re
.br
SUCCEED or FAIL.
.Sa
bcp_batch,
bcp_colfmt,
bcp_collen,
bcp_colptr,
bcp_columns,
bcp_control,
bcp_done,
bcp_exec,
bcp_init,
bcp_moretext,
bcp_sendrow
.mc