--- title: "bcp_init | Microsoft Docs" ms.custom: "" ms.date: "03/14/2017" ms.prod: sql ms.prod_service: "database-engine, sql-database, sql-data-warehouse, pdw" ms.reviewer: "" ms.technology: native-client ms.topic: "reference" apiname: - "bcp_init" - "bcp_initW" apilocation: - "sqlncli11.dll" apitype: "DLLExport" helpviewer_keywords: - "bcp_init function" ms.assetid: 6a25862c-7f31-4873-ab65-30f3abde89d2 author: markingmyname ms.author: maghan monikerRange: ">=aps-pdw-2016||=azuresqldb-current||=azure-sqldw-latest||>=sql-server-2016||=sqlallproducts-allversions||>=sql-server-linux-2017||=azuresqldb-mi-current" --- # bcp_init [!INCLUDE[appliesto-ss-asdb-asdw-pdw-md](../../includes/appliesto-ss-asdb-asdw-pdw-md.md)] Initializes the bulk copy operation. ## Syntax ``` RETCODE bcp_init ( HDBC hdbc, LPCTSTR szTable, LPCTSTR szDataFile, LPCTSTR szErrorFile, INT eDirection); ``` Unicode and ANSI names: - bcp_initA (ANSI) - bcp_initW (Unicode) ## 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](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/bcp-control.md) before [bcp_exec](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/bcp-exec.md) 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](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/bcp-sendrow.md), 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 [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)]. 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](../../relational-databases/native-client-odbc-api/sqlsetconnectattr.md) 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: - The data type specified is the data type of the column in the database table, view, or SELECT result set. The data type is enumerated by [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] native data types specified in sqlncli.h. Data itself is represented in its computer form. That is, data from a column of **integer** data type is represented by a four-byte sequence that is big-or little-endian based on the computer that created the data file. - If a database data type is fixed in length, the data file data is also fixed in length. Bulk-copy functions that process data (for example, [bcp_exec](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/bcp-exec.md)) parse data rows expecting the length of the data in the data file to be identical to the length of the data specified in the database table, view, or SELECT column list. For example, data for a database column defined as **char(13)** must be represented by 13 characters for each row of data in the file. Fixed-length data can be prefixed with a null indicator if the database column allows null values. - When terminator-byte sequence is defined, the length of the terminator-byte sequence is set to 0. - When copying to [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)], the data file must have data for each column in the database table. When copying from [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)], data from all columns in the database table, view, or SELECT result set are copied to the data file. - When copying to [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)], the ordinal position of a column in the data file must be identical to the ordinal position of the column in the database table. When copying from [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)], **bcp_exec** places data based on the ordinal position of the column in the database table. - If a database data type is variable in length (for example, **varbinary(22)**) or if a database column can contain null values, data in the data file is prefixed by a length/null indicator. The width of the indicator varies based on the data type and version of bulk copy. To change data format values specified for a data file, call [bcp_columns](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/bcp-columns.md) and [bcp_colfmt](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/bcp-colfmt.md). Bulk copies to [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] can be optimized for tables that do not contain indexes by setting the database recovery model to SIMPLE or BULK_LOGGED. For more information, see [Prerequisites for Minimal Logging in Bulk Import](../../relational-databases/import-export/prerequisites-for-minimal-logging-in-bulk-import.md) and [ALTER DATABASE](../../t-sql/statements/alter-database-transact-sql.md). If no data file is used, you must call [bcp_bind](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/bcp-bind.md) to specify the format and location in memory of the data for each column, then copy data rows to the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] using [bcp_sendrow](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/bcp-sendrow.md). ## Example This sample shows how to use the ODBC bcp_init function with a format file. Before you compile and run the C++ code, you need to do the following: - Create an ODBC data source called Test. You can associate this data source with any database. - Run the following [!INCLUDE[tsql](../../includes/tsql-md.md)] on the database: ``` CREATE TABLE BCPDate (cola int, colb datetime); ``` - In the directory where you will run the application, add a file called Bcpfmt.fmt, and add this to the file: ``` 8.0 2 1SQLCHAR04"\t"1colaSQL_Latin1_General_Cp437_Bin 2SQLCHAR08"\r\n"2colbSQL_Latin1_General_Cp437_Bin ``` - In the directory where you will run the application, add a file called Bcpodbc.bcp, and add this to the file: ``` 1 2 ``` Now you are ready to compile and run the C++ code. ``` // compile with: odbc32.lib sqlncli11.lib #include #include #include #include #include SQLHENV henv = SQL_NULL_HENV; HDBC hdbc1 = SQL_NULL_HDBC; void Cleanup() { if (hdbc1 != SQL_NULL_HDBC) { SQLDisconnect(hdbc1); SQLFreeHandle(SQL_HANDLE_DBC, hdbc1); } if (henv != SQL_NULL_HENV) SQLFreeHandle(SQL_HANDLE_ENV, henv); } int main() { RETCODE retcode; SDWORD cRows; // Allocate the ODBC environment and save handle. retcode = SQLAllocHandle (SQL_HANDLE_ENV, NULL, &henv); if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) { printf("SQLAllocHandle(Env) Failed\n\n"); Cleanup(); return(9); } // Notify ODBC that this is an ODBC 3.0 app. retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_INTEGER); if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) { printf("SQLSetEnvAttr(ODBC version) Failed\n\n"); Cleanup(); return(9); } // Allocate ODBC connection handle, set BCP mode, and connect. retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc1); if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) { printf("SQLAllocHandle(hdbc1) Failed\n\n"); Cleanup(); return(9); } retcode = SQLSetConnectAttr(hdbc1, SQL_COPT_SS_BCP, (void *)SQL_BCP_ON, SQL_IS_INTEGER); if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) { printf("SQLSetConnectAttr(hdbc1) Failed\n\n"); Cleanup(); return(9); } // Sample uses Integrated Security. Create SQL Server DSN using Windows NT authentication. retcode = SQLConnect(hdbc1, (UCHAR*)"Test", SQL_NTS, (UCHAR*)"", SQL_NTS, (UCHAR*)"", SQL_NTS); if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) { printf("SQLConnect() Failed\n\n"); Cleanup(); return(9); } // Initialize the bulk copy. retcode = bcp_init(hdbc1, "BCPDate", "BCPODBC.bcp", NULL, DB_IN); if ( (retcode != SUCCEED) ) { printf("bcp_init(hdbc1) Failed\n\n"); Cleanup(); return(9); } // Read the format file. retcode = bcp_readfmt(hdbc1, "BCPFMT.fmt"); if ( (retcode != SUCCEED) ) { printf("bcp_readfmt(hdbc1) Failed\n\n"); Cleanup(); return(9); } // Execute the bulk copy. retcode = bcp_exec(hdbc1, &cRows); if ( (retcode != SUCCEED) ) { printf("bcp_exec(hdbc1) Failed\n\n"); Cleanup(); return(9); } printf("Number of rows bulk copied in = %d.\n", cRows); // Cleanup SQLDisconnect(hdbc1); SQLFreeHandle(SQL_HANDLE_DBC, hdbc1); SQLFreeHandle(SQL_HANDLE_ENV, henv); } ``` ## See Also [Bulk Copy Functions](../../relational-databases/native-client-odbc-extensions-bulk-copy-functions/sql-server-driver-extensions-bulk-copy-functions.md)