bcp_init

發行項
07/04/2024

適用於：SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse 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

語法

引數

傳回

備註

範例

另請參閱

意見反應

意見反應

其他資源