bcp_bind

發行項
01/10/2024

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

將資料從程式變數系結至資料表資料行，以便大量複製到 SQL Server。

語法

  
RETCODE bcp_bind (  
        HDBC hdbc,
        LPCBYTE pData,  
        INT cbIndicator,  
        DBINT cbData,  
        LPCBYTE pTerm,  
        INT cbTerm,  
        INT eDataType,  
        INT idxServerCol);

引數

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

pData
這是複製資料的指標。如果 eDataType 是 SQLTEXT、SQLNTEXT、SQLXML、SQLUDT、SQLCHARACTER、SQLVARCHAR、SQLVARBINARY、SQLBINARY、SQLNCHAR 或 SQLIMAGE， pData 可以是 Null。 Null pData 表示會使用 bcp_moretext ，以區塊方式將長資料值傳送至 SQL Server。如果使用者對應至使用者系結欄位的資料行是 BLOB 資料行，則使用者應該只將 pData 設定為 Null，否則 bcp_bind 將會失敗。

如果資料中有指標，它們就會直接出現在資料之前的記憶體中。 在此案例中，pData 參數會指向指標變數，而 cbIndicator 參數的寬度 則由大量複製用來正確處理使用者資料。

cbIndicator
這是資料行資料長度或 Null 指標的長度，以位元組為單位。有效的指標長度值為 0（不使用指標時）、1、2、4 或 8。指標會在任何資料之前直接出現在記憶體中。例如，下列結構類型定義可用來使用大量複製將整數值插入 SQL Server 資料表中：

typedef struct tagBCPBOUNDINT  
    {  
    int iIndicator;  
    int Value;  
    } BCPBOUNDINT;

在範例案例中 ，pData 參數會設定為結構的宣告實例位址、BCPBOUNDINT iIndicator 結構成員的位址。 cbIndicator 參數會設定為整數的大小（sizeof（int）， 而 cbData 參數會再次設定為整數的大小（sizeof（int）。若要將資料列大量複製到包含系結資料行 Null 值的伺服器，實例 iIndicator 成員的值應該設定為 SQL_Null_DATA。

cbData
這是程式變數中的資料位元組計數，不包括任何長度或 Null 指標或結束字元的長度。

將 cbData 設定為 SQL_Null_DATA表示複製到伺服器的所有資料列都包含資料行的 Null 值。

將 cbData 設定為 SQL_VARLEN_DATA 表示系統會使用字串結束字元或其他方法來判斷複製的資料長度。

如果是固定長度的資料類型，例如整數，資料類型會指出資料的長度給系統。因此，對於固定長度的資料類型， cbData 可以安全地SQL_VARLEN_DATA或資料的長度。

針對 SQL Server 字元和二進位資料類型， cbData 可以SQL_VARLEN_DATA、SQL_Null_DATA、某些正值或 0。如果 cbData 是SQL_VARLEN_DATA，則系統會使用長度/Null 指標（如果有的話）或結束字元序列來判斷資料的長度。如果兩者都提供，系統會使用會導致複製的資料量最少的。如果 cbData 是SQL_VARLEN_DATA，則資料行的資料類型是 SQL Server 字元或二進位類型，而且不會指定長度指標或結束字元序列，系統就會傳回錯誤訊息。

如果 cbData 為 0 或正值，則系統會使用 cbData 作為資料長度。不過，如果除了正 cbData 值之外，還提供長度指標或結束字元序列，系統會使用會導致複製的資料量最少的方法來判斷資料長度。

cbData 參數值代表資料的位元組計數。如果字元資料是以 Unicode 寬字元表示，則正 cbData 參數值代表字元數乘以每個字元的位元組大小。

pTerm
這是位元組模式的指標，如果有的話，會標記這個程式變數的結尾。例如，ANSI 和 MBCS C 字串通常具有 1 位元組結束字元（\0）。

如果變數沒有結束字元，請將 pTerm 設定為 Null。

您可以使用空字串（「」）將 C Null 結束字元指定為程式變數結束字元。由於 Null 終止的空字串構成單一位元組（結束字元位元組本身），請將 cbTerm 設定為 1。例如，若要指出 szName 中的字串是以 Null 終止，而且應該使用結束字元來指出長度：

bcp_bind(hdbc, szName, 0,  
   SQL_VARLEN_DATA, "", 1,  
   SQLCHARACTER, 2)

這個範例的非決定性形式可能表示 15 個字元會從 szName 變數複製到系結資料表的第二個數據行：

bcp_bind(hdbc, szName, 0, 15,
   NULL, 0, SQLCHARACTER, 2)

大量複製 API 會視需要執行 Unicode 到 MBCS 的字元轉換。請確定已正確設定結束字元位元組字串和位元組字串的長度。例如，若要指出 szName 中的字串是 Unicode 寬字元字串，由 Unicode Null 結束字元值終止：

bcp_bind(hdbc, szName, 0,
   SQL_VARLEN_DATA, L"",  
   sizeof(WCHAR), SQLNCHAR, 2)

如果系結的 SQL Server 資料行是寬字元，則不會在bcp_sendrow 上執行任何轉換。如果 SQL Server 資料行是 MBCS 字元類型，則會執行寬字元到多位元組字元轉換，因為資料會傳送至 SQL Server。

cbTerm
這是程式變數結束字元中存在的位元組計數，如果有的話。如果變數沒有結束字元，請將 cbTerm 設定為 0。

eDataType 是程式變數的 C 資料類型。程式變數中的資料會轉換成資料庫資料行的類型。如果此參數為 0，則不會執行任何轉換。

eDataType 參數是由 sqlncli.h 中的 SQL Server 資料類型標記所列舉，而不是 ODBC C 資料類型列舉值。例如，您可以使用 SQL Server 特定類型 SQLINT2 來指定雙位元組整數 ODBC 類型SQL_C_SHORT。

SQL Server 2005 （9.x）引進了 eDataType 參數中 SQLXML 和 SQLUDT 資料類型權杖的支援。

下表列出有效的列舉資料類型和對應的 ODBC C 資料類型。

eDataType	C 類型
SQLTEXT	char *
SQLNTEXT	wchar_t *
SQLCHARACTER	char *
SQLBIGCHAR	char *
SQLVARCHAR	char *
SQLBIGVARCHAR	char *
SQLNCHAR	wchar_t *
SQLNVARCHAR	wchar_t *
SQLBINARY	unsigned char *
SQLBIGBINARY	unsigned char *
SQLVARBINARY	unsigned char *
SQLBIGVARBINARY	unsigned char *
SQLBIT	char
SQLBITN	char
SQLINT1	char
SQLINT2	short int
SQLINT4	int
SQLINT8	_int64
SQLINTN	cbIndicator 1：SQLINT1 2：SQLINT2 4：SQLINT4 8：SQLINT8
SQLFLT4	float
SQLFLT8	float
SQLFLTN	cbIndicator 4：SQLFLT4 8：SQLFLT8
SQLDECIMALN	SQL_NUMERIC_STRUCT
SQLNUMERICN	SQL_NUMERIC_STRUCT
SQLMONEY	DBMONEY
SQLMONEY4	DBMONEY4
SQLMONEYN	cbIndicator 4：SQLMONEY4 8：SQLMONEY
SQLTIMEN	SQL_SS_TIME2_STRUCT
SQLDATEN	SQL_DATE_STRUCT
SQLDATETIM4	DBDATETIM4
SQLDATETIME	DBDATETIME
SQLDATETIMN	cbIndicator 4：SQLDATETIM4 8：SQLDATETIME
SQLDATETIME2N	SQL_TIMESTAMP_STRUCT
SQLDATETIMEOFFSETN	SQL_SS_TIMESTAMPOFFSET_STRUCT
SQLIMAGE	unsigned char *
SQLUDT	unsigned char *
SQLUNIQUEID	SQLGUID
SQLVARIANT	除了下列任何資料類型： - 文字 - ntext - 影像 - Varchar（max） - Varbinary（max） - Nvarchar（max） -Xml -時間戳
SQLXML	支援的 C 資料類型： -字元* - wchar_t * - 不帶正負號的字元 *

idxServerCol 是資料複製到資料庫資料表中資料行的序數位置。資料表中的第一個資料行是資料行 1。 SQLColumns 會報告資料行的序數位置。

傳回

SUCCEED 或 FAIL。

備註

使用 bcp_bind ，以快速且有效率的方式將資料從程式變數複製到 SQL Server 中的資料表。

呼叫此函式或任何其他大量複製函式之前，請先呼叫 bcp_init 。呼叫 bcp_init 設定大量複製的 SQL Server 目標資料表。呼叫 bcp_init 以搭配 bcp_bind 和 bcp_sendrow 使用時， bcp_init szDataFile 參數會設定為 Null; bcp_init eDirection 參數會設定為 DB_IN。

針對您要複製之 SQL Server 資料表中的每個資料行，進行個別 bcp_bind 呼叫。在進行必要的 bcp_bind 呼叫之後，請呼叫 bcp_sendrow ，將程式變數的資料列傳送至 SQL Server。不支援重新系結資料行。

每當您想要 SQL Server 認可已收到的資料列時，請呼叫 bcp_batch 。例如， 針對每個插入的 1000 個數據列或任何其他間隔呼叫bcp_batch 一次。

當沒有其他資料列要插入時，請呼叫 bcp_done 。無法執行這項操作時，會發生錯誤。

使用 bcp_control 指定的控制參數設定，對bcp_bind 資料列傳輸沒有任何影響 。

如果 資料行的 pData 設定為 Null，因為其值會透過呼叫 bcp_moretext 提供，則任何將 eDataType 設為 SQLTEXT、SQLNTEXT、SQLXML、SQLUDT、SQLCHARACTER、SQLVARCHAR、SQLVARBINARY、SQLBINARY、SQLNCHAR 或 SQLIMAGE 的後續資料行也必須系結 為 Null，而且其值也必須由呼叫 bcp_moretext 提供。

針對新的大型實數值型別，例如 Varchar（max） 、 Varbinary（max） 或 Nvarchar（max） ，您可以使用 SQLCHARACTER、SQLVARCHAR、SQLVARBINARY、SQLBINARY 和 SQLNCHAR 作為 eDataType 參數中的 類型指標。

如果 cbTerm 不是 0，任何值（1、2、4 或 8）都適用于前置詞（ cbIndicator ）。在此情況下，SQL Server Native Client 會搜尋結束字元、計算結束字元的資料長度（ i ），並將 cbData 設定為較小的 i 值和前置詞的值。

如果 cbTerm 為 0 且 cbIndicator （前置詞）不是 0， cbIndicator 必須是 8。 8 位元組前置詞可以採用下列值：

0xFFFFFFFFFFFFFFFF表示欄位的 Null 值
0xFFFFFFFFFFFFFFFE會被視為特殊的前置詞值，用來有效率地將資料分區塊轉送至伺服器。具有此特殊前置詞的資料格式為：
<>< SPECIAL_PREFIX 0 個以上的資料區塊 >< ZERO_CHUNK > 其中：
SPECIAL_PREFIX為0xFFFFFFFFFFFFFFFE
DATA_CHUNK是包含區塊長度的 4 位元組前置詞，後面接著在 4 位元組前置詞中指定其長度的實際資料。
ZERO_CHUNK是一個 4 位元組值，其中包含表示資料結束的所有零（00000000000）。
任何其他有效的 8 位元組長度都會被視為一般資料長度。

使用 bcp_bind時呼叫 bcp_columns 會導致錯誤。

bcp_bind增強日期和時間功能的支援

如需與日期/時間類型 eDataType 參數搭配 使用的類型相關資訊，請參閱增強型日期和時間類型的大量複製變更（OLE DB 和 ODBC）。

如需詳細資訊，請參閱日期和時間改善（ODBC）。

範例

#include sql.h  
#include sqlext.h  
#include odbcss.h  
// Variables like henv not specified.  
HDBC      hdbc;  
char         szCompanyName[MAXNAME];  
DBINT      idCompany;  
DBINT      nRowsProcessed;  
DBBOOL      bMoreData;  
char*      pTerm = "\t\t";  
  
// 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;  
   }  
  
// Initialize bcp.
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL  
   DB_IN) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Bind program variables to table columns.
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,  
   SQLINT4, 1)    == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,  
   (LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
while (TRUE)  
   {  
   // Retrieve and process program data.
   if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)  
      {  
      // Send the data.
      if (bcp_sendrow(hdbc) == FAIL)  
         {  
         // Raise error and return.  
         return;  
         }  
      }  
   else  
      {  
      // Break out of loop.  
      break;  
      }  
   }  
  
// Terminate the bulk copy operation.  
if ((nRowsProcessed = bcp_done(hdbc)) == -1)  
   {  
   printf_s("Bulk-copy unsuccessful.\n");  
   return;  
   }  
  
printf_s("%ld rows copied.\n", nRowsProcessed);

另請參閱

大量複製函式

Share via

bcp_bind

語法

引數

傳回

備註

bcp_bind增強日期和時間功能的支援

範例

另請參閱

意見反應

意見反應

其他資源