Initialize bulk copy.
RETCODE bcp_init(dbproc, tblname, hfile, errfile,
direction)
DBPROCESS *dbproc;
char *tblname;
char *hfile;
char *errfile;
int direction;
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 name of the database table to be copied in or out. This name may also include the database name or the owner name. For example, pubs2.gracie.titles, pubs2.titles, gracie.titles, and titles are all legal table names.
The name of the host file to be copied in or out. If no host file is involved (the situation when data is being copied directly from variables), hfile should be NULL.
The name of the error file to be used. This error file will be filled with progress messages, error messages, and copies of any rows that, for any reason, could not be copied from a host file to an Adaptive Server Enterprise table.
If errfile is NULL, no error file is used.
If hfile is NULL, errfile is ignored. This is because an error file is not necessary when bulk-copying from program variables.
The direction of the copy. It must be one of two values—DB_IN or DB_OUT. DB_IN indicates a copy from the host into the database table, while DB_OUT indicates a copy from the database table into the host file.
It is illegal to request a bulk copy from the database table (DB_OUT) without supplying a host file name.
SUCCEED or FAIL.
bcp_init performs the necessary initialization for a bulk copy of data between the front-end and an Adaptive Server Enterprise. It sets the default host file data formats and examines the structure of the database table.
bcp_init must be called before any other bulk copy functions. Failure to do so will result in an error.
If a host file is being used (see the description of hfile in the “Parameters” section above), the default data formats are as follows:
The order, type, length, and number of the columns in the host file are assumed to be identical to the order, type, and number of the columns in the database table.
If a given database column’s data is fixed-length, then the host file’s data column will also be fixed-length. If a given database column’s data is variable-length or may contain null values, the host file’s data column will be prefixed by a 4-byte length value for SYBTEXT and SYBIMAGE data types, and a 1-byte length value for all other types.
There are no terminators of any kind between host file columns.
Any of these defaults can be overridden by calling bcp_columns and bcp_colfmt.
Using the bulk copy routines to copy data to a database table requires the following:
The DBPROCESS structure must be usable for bulk copy purposes. This is accomplished by calling BCP_SETL:
login = dblogin();
BCP_SETL(login, TRUE);
If the table has no indexes, the database option select into/bulkcopy must be set to “true.” The following SQL command will do this:
sp_dboption ’mydb’, ’select into/bulkcopy’, ’true’
See the Adaptive Server Enterprise Reference Manual for further details on sp_dboption.
If no host file is being used, it is necessary to call bcp_bind to specify the format and location in memory of each column’s data value.
If no host file is being used, errfile is ignored. An error file is not necessary when bulk-copying from program variables because bcp_sendrow returns FAIL if an error occurs. In this case, the application can examine the bulk copy program variables to determine which row values caused the error.
bcp_batch, bcp_bind, bcp_colfmt, bcp_collen, bcp_colptr, bcp_columns, bcp_control, bcp_done, bcp_exec, bcp_sendrow
