共用方式為


bcp_moretext

將長的變動長度資料類型值的一部分傳送給 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_bindbcp_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_bindbcp_sendrow 會傳送整個資料值,不論長度為何。但是如果在支援的資料類型中,bcp_bind 具有 NULL pData 參數,則當從 bcp_sendrow 成功傳回 (指示已經處理具有資料的任何繫結資料行) 之後,可立即使用 bcp_moretext 來複製資料。

如果您使用 bcp_moretext 在資料列中傳送一個支援的資料類型資料行,您也必須用它在資料列中傳送所有其他支援的資料類型資料行。不能略過任何資料行。支援的資料類型為 SQLTEXT、SQLNTEXT、SQLIMAGE、SQLUDT 和 SQLXML。如果此資料行分別為 varchar(max)、nvarchar(max) 或 varbinary(max),則 SQLCHARACTER、SQLVARCHAR、SQNCHAR、SQLBINARY 和 SQLVARBINARY 也會列入這個類別目錄。

呼叫 bcp_bindbcp_collen 會設定要複製到 SQL Server 資料行之所有資料部分的總長度。如果嘗試傳送比 bcp_bindbcp_collen 呼叫中指定的位元組還要多的位元組給 SQL Server,將會產生錯誤。例如,如果應用程式使用 bcp_collen 將 SQL Server text 資料行的可用資料長度設定為 4500,然後呼叫 bcp_moretext 五次,並同時在每一個呼叫中指示資料緩衝區長度為 1000 個位元組,就會發生這個錯誤。

如果被佔據的資料列包含了一個以上的長型、變動長度資料行,bcp_moretext 會先將它的資料傳送給序數編號最低的資料行,接著是序數編號次低的資料行,依此類推。更正預期資料的總長度設定是很重要的一件事。除了使用長度設定以外,沒有任何方法可以指示大量複製已經收到資料行的所有資料。

當使用 bcp_sendrowbcp_moretext 將 var(max) 值傳送給伺服器時,不需要呼叫 bcp_collen 來設定資料行長度。而是藉由呼叫零長度的 bcp_sendrow 來結束此值 (僅限這些類型)。

應用程式通常會在迴圈內呼叫 bcp_sendrowbcp_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_bindbcp_sendrow 使用 bcp_moretext

// 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.

請參閱

參考