bcp_moretext
適用対象: 
SQL Server Azure SQL データベース 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は、テキスト、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 最初にデータを最下位の序数列に送信し、その後に次に小さい序数の列を送信します。 コピーするデータの合計長を正しく設定することが重要です。 長さの設定以外に、一括コピーによって列のすべてのデータを受け取ったことを示す方法はありません。
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.