bcp_moretext

適用於：SQL ServerAzure SQL DatabaseAzure SQL 受控執行個體Azure Synapse AnalyticsAnalytics Platform System (PDW)

將長、可變長度資料類型值的一部分傳送至 SQL Server。

語法

  
RETCODE bcp_moretext (  
        HDBC hdbc,  
        DBINT cbData,  
        LPCBYTE pData);  

引數

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

cbData
這是從 pData 所參考 的資料複製到 SQL Server 的資料位元組數。 SQL_Null_DATA的值表示 Null。

pData
這是要傳送至 SQL Server 的支援、長、可變長度資料區塊的指標。

傳回

SUCCEED 或 FAIL。

備註

此函式可以與bcp_bind 和 bcp_sendrow 搭配 使用，以數個較小的區塊將長、可變長度的資料值複製到 SQL Server。 bcp_moretext 可以搭配具有下列 SQL Server 資料類型的資料行使用： text 、 Ntext 、 image 、 Varchar（max）、Nvarchar（max） 、 Varbinary（max） 、 使用者定義類型 （UDT） 和 XML。 bcp_moretext不支援資料轉換，提供的資料必須符合目標資料行的資料類型。

如果 針對bcp_moretext 支援的 資料類型，使用非 Null pData 參數呼叫bcp_bind ，則不論長度為何， bcp_sendrow 傳送整個資料值。 不過， 如果bcp_bind 具有支援的資料類型的 Null pData 參數，bcp_moretext就可以在成功從 bcp_sendrow 傳回資料之後立即複製資料， 指出已處理任何具有資料之系結資料行的資料行。

如果您使用 bcp_moretext 將資料列中一個支援的資料類型資料行傳送，您也必須使用它來傳送資料列中所有其他支援的資料類型資料行。 無法略過任何資料行。 支援的資料類型包括 SQLTEXT、SQLNTEXT、SQLIMAGE、SQLUDT 和 SQLXML。 如果資料行分別是 Varchar（max）、Nvarchar（max）或 Varbinary（max），SQLCHARCHAR、SQNCHAR、SQLBINARY 和 SQLVARBINARY 也屬於此類別。

呼叫 bcp_bind 或 bcp_collen 會設定要複製到 SQL Server 資料行的所有資料元件總長度。 嘗試在呼叫 bcp_bind 或 bcp_collen 時傳送 SQL Server 的位元組數超過指定的位元組，則會產生錯誤。 例如，在使用 bcp_collen 將 SQL Server 文字 資料行的可用資料長度設定為 4500 的應用程式中，然後呼叫 bcp_moretext 5 次，同時指出每次呼叫資料緩衝區長度為 1000 個位元組。

如果複製的資料列包含一個以上的長、可變長度的資料行， bcp_moretext 先將其資料傳送至最低序數資料行，後面接著下一個最低序數資料行等等。 正確設定預期的資料總長度很重要。 在長度設定之外，無法發出信號，表示資料行的所有資料都已透過大量複製來接收。

使用 bcp_sendrow 和 bcp_moretext 將 var（max） 值傳送至伺服器時 ，不需要呼叫 bcp_collen 來設定資料行長度。 相反地，只有這些類型，值會藉由呼叫長度為零的bcp_sendrow來終止。

應用程式通常會在迴圈內呼叫 bcp_sendrow 和 bcp_moretext ，以傳送一些資料列。 以下概述如何針對包含兩 個文字 資料行的資料表執行這項操作：

while (there are still rows to send)  
{  
bcp_sendrow(...);  
  
for (all the data in the first varbinary(max) column)  
bcp_moretext(...);  
bcp_moretext(hdbc, 0, NULL);  
  
for (all the data in the second varbinary(max) column)  
bcp_moretext(...);  
bcp_moretext(hdbc, 0, NULL);  
  
}  
  

範例

此範例示範如何使用 bcp_moretext 搭配 bcp_bind 和 bcp_sendrow ：

// Variables like henv not specified.  
HDBC      hdbc;  
DBINT      idRow = 5;  
char*      pPart1 = "This text value isn't very long,";  
char*      pPart2 = " but it's broken into three parts";  
char*      pPart3 = " anyhow.";  
DBINT      cbAllParts;  
DBINT      nRowsProcessed;  
  
// 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 bulk copy.   
if (bcp_init(hdbc, "comdb..articles", NULL, NULL, DB_IN) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Bind program variables to table columns.   
if (bcp_bind(hdbc, (LPCBYTE) &idRow, 0, SQL_VARLEN_DATA, NULL, 0,  
   SQLINT4, 1)    == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
cbAllParts = (DBINT) (strnlen(pPart1, sizeof(pPart1) + 1) + strnlen(pPart2, sizeof(pPart2) + 1) + strnlen(pPart3, sizeof(pPart3) + 1));  
if (bcp_bind(hdbc, NULL, 0, cbAllParts, NULL, 0, SQLTEXT, 2) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Send this row, with the text value broken into three chunks.   
if (bcp_sendrow(hdbc) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart1, sizeof(pPart1) + 1), pPart1) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart2, sizeof(pPart2) + 1), pPart2) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart3, sizeof(pPart3) + 1), pPart3) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// All done. Get the number of rows processed (should be one).  
nRowsProcessed = bcp_done(hdbc);  
  
// Carry on.  

另請參閱

大量複製函式