bcp_init

Initializes bulk copy operation.

Syntax

RETCODE bcp_init (
PDBPROCESS dbproc,
LPCSTR tblname,
LPCSTR hfile,
LPCSTR errfile,
INT direction );

Arguments

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation/ Microsoft® SQL Server™ process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.

tblname

Is the name of the database table to be copied in or out. This name can also include the database name or the database owner name. For example, pubs.gracie.titles, pubs..titles, gracie.titles, and titles are all legal table names.

If direction is DB_OUT, tblname can also be the name of a database view.

hfile

Is the name of the user file to be copied into or out of SQL Server. If data is being copied directly from variables using bcp_sendrow, set hfile to NULL.

errfile

Is the name of the error file to be used. This error file is filled with progress messages, error messages, and copies of any rows that, for any reason, could not be copied from a user file to a SQL Server table. If NULL is passed as errfile, no error file is used.

direction

Is the direction of the copy. It must be one of two values: DB_IN or DB_OUT. DB_IN indicates a copy from program variables or a user file to the database table, while DB_OUT indicates a copy from the database table to the user file. It is illegal to request a bulk copy from the database table (DB_OUT) without supplying a user file name.

Returns

SUCCEED or FAIL.

Remarks

bcp_init performs the necessary initializations for a bulk copy of data between the workstation and SQL Server. It sets the default user-file data formats and examines the structure of the database table.

If a user file is being used (see the description of the hfile parameter), the default data native formats are as follows:

• The order, type, length, and number of the columns in the user 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 user file’s data column is also fixed length.

  When a given database column’s data is variable length or when it can contain null values, the user file’s data column is prefixed by a 4-byte length value for SQLTEXT and SQLIMAGE data types and a 1-byte length value for all other types.

• There are no terminators of any kind between user file columns.

Any of these defaults can be overridden by calling bcp_columns and bcp_colfmt.

To use the bulk copy functions to copy data to a database table, follow these examples:

• Call BCP_SETL to make the DBPROCESS structure usable for bulk copy purposes:

  login = dblogin();
BCP_SETL(login, TRUE);

    

• If the table has no indexes, set the database option select into/bulkcopy to TRUE, use the database, and send the SQL Server CHECKPOINT statement:

  sp_dboption 'mydb', 'select into/bulkcopy', 'true'

  GO

  USE mydb

  GO

  CHECKPOINT

    

If no user file is being used, it is necessary to call bcp_bind to specify the format and location in memory for each column’s data value, and send the rows using bcp_sendrow

The bcp_init function must be called before any other bulk-copy functions. Failure to do so results in an error.

See Also