bcp_init

發行項
01/10/2024

適用於：SQL Server Azure SQL Database Azure SQL 受控執行個體 Azure Synapse Analytics Analytics Platform System (PDW)

初始化大量複製作業。

語法

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

Unicode 和 ANSI 名稱：

bcp_initA（ANSI）
bcp_initW （Unicode）

引數

hdbc
這是啟用大量複製的 ODBC 連接控制碼。

szTable
這是要複製到或移出的資料庫資料表名稱。此名稱也可以包含資料庫名稱或擁有者名稱。例如 pubs.gracie.titles 、 pubs.。titles 、 gracie.titles 和 titles 都是合法的資料表名稱。

如果 eDirection 是DB_OUT， szTable 也可以是資料庫檢視的名稱。

如果 eDirection 是DB_OUT，而且會在呼叫 bcp_exec 之前使用 bcp_control 指定 SELECT 語句， bcp_init szTable 必須設定為 Null。

szDataFile
這是要複製到或移出的使用者檔案名稱。如果使用 bcp_sendrow 直接從變數複製資料，請將 szDataFile 設定為 Null。

szErrorFile
這是要填入進度訊息、錯誤訊息和任何資料列複本的錯誤檔名稱，因為任何原因都無法從使用者檔案複製到資料表。如果 Null 傳遞為 szErrorFile ，則不會使用任何錯誤檔案。

eDirection
這是複本的方向，DB_IN或DB_OUT。 DB_IN表示從程式變數或使用者檔案複製到資料表的複本。 DB_OUT表示從資料庫資料表複製到使用者檔案的複本。您必須使用 DB_OUT 指定使用者檔案名。

傳回

SUCCEED 或 FAIL。

備註

呼叫任何其他大量複製函式 之前，請先呼叫 bcp_init。 bcp_init 針對工作站與 SQL Server 之間的大量資料複本執行必要的初始化。

bcp_init 函式必須提供已啟用 ODBC 連接控制碼，才能與大量複製函式搭配使用。若要啟用控制碼，請使用 SQLSetConnectAttr ，並將 SQL_COPT_SS_BCP 設定為在已配置但未連線的連接控制碼上SQL_BCP_ON。嘗試在連接的控制碼上指派屬性會導致錯誤。

指定資料檔案時， bcp_init 檢查資料庫來源或目標資料表的結構，而不是資料檔案。 bcp_init會根據資料庫資料表、檢視或 SELECT 結果集中的每個資料行，指定資料檔案的資料格式值。這個指定包括每個資料行的資料類型、資料中是否有長度或 null 指標和結束字元位元組字串，以及固定長度資料類型的寬度。 bcp_init 設定這些值，如下所示：

指定的資料類型為資料行在資料庫資料表、檢視或 SELECT 結果集中的資料類型。資料類型是由 sqlncli.h 中指定的 SQL Server 原生資料類型所列舉。資料本身會以電腦形式表示。也就是說，來自整數 資料類型資料行 的資料是由以建立資料檔之電腦為基礎的四位元組序列來表示。
如果資料庫資料類型的長度是固定的，資料檔案資料的長度也是固定的。處理資料的大量複製函式（例如， bcp_exec ）會剖析資料列，預期資料檔案中的資料長度與資料庫資料表、檢視或 SELECT 資料行清單中指定的資料長度相同。例如，定義為 char（13） 的資料庫資料行資料必須以 13 個字元表示檔案中每個資料列的資料。如果資料庫資料行允許使用 Null 值，固定長度的資料前置詞可以是 Null 指標。
定義結束字元位元組序列時，結束字元位元組序列的長度會設定為 0。
複製到 SQL Server 時，資料檔案必須有資料庫資料表中每個資料行的資料。從 SQL Server 複製時，資料庫資料表、檢視或 SELECT 結果集中所有資料行的資料都會複製到資料檔案。
複製到 SQL Server 時，資料檔中資料行的序數位置必須與資料庫資料表中資料行的序數位置相同。從 SQL Server 複製時， bcp_exec 根據資料庫資料表中資料行的序數位置放置資料。
如果資料庫資料類型長度可變（例如 Varbinary（22） 或資料庫資料行可以包含 Null 值，則資料檔案中的資料前面會加上長度/Null 指標。指標的寬度會根據資料類型和大量複製的版本而改變。

若要變更為資料檔案指定的資料格式值，請呼叫 bcp_columns 和 bcp_colfmt 。

將資料庫復原模式設定為 SIMPLE 或 BULK_LOGGED，即可針對不包含索引的資料表優化大量複製到 SQL Server。如需詳細資訊，請參閱大量匯入和 ALTER DATABASE 中最低限度記錄的必要條件。

如果沒有使用資料檔案，您必須呼叫 bcp_bind 來指定每個資料行資料記憶體中的格式和位置，然後使用 bcp_sendrow 將資料列複製到 SQL Server 。

範例

此範例示範如何搭配格式檔案使用 ODBC bcp_init 函式。

編譯並執行 C++ 程式碼之前，您需要執行下列動作：

建立名為 Test 的 ODBC 資料來源。您可以將此資料來源與任何資料庫產生關聯。

在資料庫上執行下列 Transact-SQL：

CREATE TABLE BCPDate (cola int, colb datetime);

在您將執行應用程式的目錄中，新增名為 Bcpfmt.fmt 的檔案，並將此新增至檔案：

8.0  
2  
1SQLCHAR04"\t"1colaSQL_Latin1_General_Cp437_Bin  
2SQLCHAR08"\r\n"2colbSQL_Latin1_General_Cp437_Bin

在您將執行應用程式的目錄中，新增名為 Bcpodbc.bcp 的檔案，並將此新增至檔案：
```
1  
2  
```

現在您已準備好編譯並執行 C++ 程式碼。

// compile with: odbc32.lib sqlncli11.lib  
#include <stdio.h>  
#include <windows.h>  
#include <sql.h>  
#include <sqlext.h>  
#include <odbcss.h>  
  
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);  
}

另請參閱

大量複製函式

bcp_init

語法

引數

傳回

備註

範例

另請參閱

意見反應

意見反應

其他資源