bcp_moretext

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

bcp_moretextでサポートされているデータ型に対して null 以外の pData パラメーターを使用してbcp_bindが呼び出された場合、bcp_sendrowは長さに関係なくデータ値全体を送信します。 ただし、サポートされているデータ型 bcp_bind NULL pData パラメーターがある場合は、 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テキスト列で使用可能なデータの長さを 4500 に設定したアプリケーションでは、このエラーが発生し、データ バッファーの長さが 1000 バイトであることを各呼び出しで示しながら、bcp_moretext 5 回呼び出されます。

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

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

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

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.  

参照

一括コピー関数