bcp_moretext
適用於： 
SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse Analytics Analytics 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五次，同時指出數據緩衝區長度長度為 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.