bcp_moretext

適用対象: SQL Server Azure SQL Database Azure SQL Managed Instance 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 は、 text、 ntext、 image、 varchar(max)、 nvarchar(max)、 varbinary(max)、ユーザー定義型 (UDT)、XML の各データ型を持つ列で使用できます。 データ変換をサポートしていないbcp_moretext は、指定されたデータがターゲット列のデータ型と一致している必要があります。

bcp_moretextでサポートされているデータ型に対して null 以外の pData パラメーターを使用してbcp_bindが呼び出された場合、bcp_sendrowは長さに関係なくデータ値全体を送信します。 ただし、サポートされているデータ型に NULL pData パラメーターがbcp_bindされている場合は、bcp_moretextを使用して、データが存在するバインドされた列が処理されたことを示すbcp_sendrowから正常に戻った直後にデータをコピーできます。

bcp_moretextを使用して、サポートされている 1 つのデータ型列を 1 行に送信する場合は、その列を使用して、サポートされている他のすべてのデータ型列を行に送信する必要もあります。 列はスキップされません。 サポートされるデータ型は、SQLTEXT、SQLNTEXT、SQLIMAGE、SQLUDT、および SQLXML です。 列の型が varchar(max)、nvarchar(max)、または varbinary(max) の場合、SQLCHARACTER、SQLVARCHAR、SQNCHAR、SQLBINARY、SQLVARBINARY も、サポート対象となります。

bcp_bindまたはbcp_collenを呼び出すと、SQL Server 列にコピーされるすべてのデータ パーツの合計長が設定されます。 bcp_bindまたはbcp_collenへの呼び出しで指定されたバイト数を超える SQL Server を送信しようとすると、エラーが発生します。 このエラーは、たとえば、 bcp_collen を使用して SQL Server text 列の使用可能なデータの長さを 4500 に設定したアプリケーションで、データ バッファーの長さが 1000 バイトであることを呼び出すたびに 5 回 bcp_moretext 呼び出されます。

コピーした行に複数の長い可変長列が含まれている場合、 bcp_moretext 最初にデータを最下位の序数列に送信し、その後に次に小さい序数の列を送信します。 コピーするデータの合計長を正しく設定することが重要です。 長さの設定以外に、一括コピーによって列のすべてのデータを受け取ったことを示す方法はありません。

var(max)値がbcp_sendrowとbcp_moretextを使用してサーバーに送信される場合、列の長さを設定するためにbcp_collenを呼び出す必要はありません。 代わりに、これらの型の場合のみ、長さが 0 のbcp_sendrowを呼び出すことによって値が終了します。

通常、アプリケーションは bcp_sendrow を呼び出し、ループ内で bcp_moretext して、多数のデータ行を送信します。 2 つの text 列を含むテーブルに対してこれを行う方法の概要を次に示します。

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_bindとbcp_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.  

参照

一括コピー関数