bcp_moretext

構文

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 でサポートされるデータ型に対して、pData パラメータに NULL 以外の値を指定して bcp_bind を呼び出すと、bcp_sendrow ではデータの長さにかかわらずデータ値全体が送信されます。一方、サポートされるデータ型に対して pData パラメータに NULL を指定して bcp_bind を呼び出すと、データが存在するバインド済みの列がすべて処理されたことを示す値が bcp_sendrow から正常に返された直後に、bcp_moretext を使用してデータをコピーできます。

bcp_moretext を使用して、行内のサポートされるデータ型の列を送信する場合、その行内にあるサポートされる他のすべてのデータ型の列を送信するときにも、このメソッドを使用する必要があります。列はスキップされません。サポートされるデータ型は、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 に送信しようとすると、エラーが発生します。たとえば、SQL Server text 型の列で使用できるデータの長さを 4500 に設定して bcp_collen を呼び出してから、毎回データ バッファの長さを 1000 バイトに指定して bcp_moretext を 5 回呼び出すと、このエラーが発生することになります。

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

var(max) の値が、bcp_sendrow および bcp_moretext を使用してサーバーに送信される場合は、bcp_collen を呼び出して列の長さを設定する必要はありません。代わりに、これらの型に限り、長さゼロを指定して 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);

}

例

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

関連項目

参照