bcp_init (ODBC)

Initializes bulk copy operation.

Syntax

RETCODE bcp_init (
HDBC
hdbc,
LPCTSTR
szTable,
LPCTSTR
szDataFile,
LPCTSTR
szErrorFile,
INT
eDirection );

Arguments
hdbc
Is the bulk copy-enabled ODBC connection handle.
szTable
Is the name of the database table to be copied into or out of. This name can also include the database name or the owner name. For example, pubs.gracie.titles, pubs..titles, gracie.titles, and titles are all legal table names.

If eDirection is DB_OUT, szTable can also be the name of a database view.

If eDirection is DB_OUT and a SELECT statement is specified using bcp_control before bcp_exec is called, bcp_init szTable must be set to NULL.

szDataFile
Is the name of the user file to be copied into or out of. If data is being copied directly from variables by using bcp_sendrow, set szDataFile to NULL.
szErrorFile
Is the name of the error file to be 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 table. If NULL is passed as szErrorFile, no error file is used.
eDirection
Is the direction of the copy, either DB_IN or DB_OUT. DB_IN indicates a copy from program variables or a user file to a table. DB_OUT indicates a copy from a database table to a user file. You must specify a user file name with DB_OUT.
Returns

SUCCEED or FAIL.

Remarks

Call bcp_init before calling any other bulk-copy function. bcp_init performs the necessary initializations for a bulk copy of data between the workstation and Microsoft® SQL Server™.

The bcp_init function must be provided with an ODBC connection handle enabled for use with bulk copy functions. To enable the handle, use SQLSetConnectAttr with SQL_COPT_SS_BCP set to SQL_BCP_ON on an allocated, but not connected, connection handle. Attempting to assign the attribute on a connected handle results in an error.

When a data file is specified, bcp_init examines the structure of the database source or target table, not the data file. bcp_init specifies data format values for the data file based on each column in the database table, view, or SELECT result set. This specification includes the data type of each column, the presence or absence of a length or null indicator and terminator byte strings in the data, and the width of fixed-length data types. bcp_init sets these values as follows:

To change data format values specified for a data file, call bcp_columns and bcp_colfmt.

Bulk copies to SQL Server can be optimized for tables that do not contain indexes by setting the database option select into/bulkcopy (see the example). For more information, see Optimizing Bulk Copy Performance.

If no data file is used, you must call bcp_bind to specify the format and location in memory of the data for each column, then copy data rows to the SQL Server using bcp_sendrow.

Example

Setting the select into/bulkcopy option allows faster bulk copies for tables that do not contain indexes.

...

// Variables like henv not specified.
HDBC        hdbc;
SQLHSTMT        hstmt;

// Application initiation, get an ODBC environment handle, allocate the
// hdbc, and so on.
...

// Enable bulk copy prior to connecting on allocated hdbc.

SQLSetConnectAttr(hdbc, SQL_COPT_SS_BCP, (SQLPOINTER) SQL_BCP_ON,
    SQL_IS_INTEGER);

// Connect to the data source, return on error.

if (!SQL_SUCCEEDED(SQLConnect(hdbc, _T("myDSN"), SQL_NTS,
    _T("myUser"), SQL_NTS, _T("myPwd"), SQL_NTS)))
    {
    // Raise error and return.
    return;
    }

// Get a statement handle and set the select into/bulkcopy database
// option to TRUE.
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
if (!SQL_SUCCEEDED(SQLExecDirect(hstmt,
    _T("sp_dboption 'mydb', 'select into/bulkcopy', 'true'"),
    SQL_NTS)))
    {
    // Raise error and return.
    return;
    }

// Flush the statement handle.
while (SQL_SUCCEEDED(SQLMoreResults(hstmt)))
    ;

// Initialize bulk copy, perform copies, and so on.
...

// Turn off the select into/bulkcopy database option.
if (!SQL_SUCCEEDED(SQLExecDirect(hstmt,
    _T("sp_dboption 'mydb', 'select into/bulkcopy', 'false'"),
    SQL_NTS)))
    {
    // Raise error and return.
    return;
    }

// Carry on.
...

See Also
bcp_bind bcp_control
bcp_colfmt bcp_sendrow
bcp_columns SQLSetConnectAttr
Logged and Nonlogged Bulk Copy Operations  

  


(c) 1988-98 Microsoft Corporation. All Rights Reserved.