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_bind 和 bcp_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_bind，则无论数据值的长度如何，bcp_sendrow 将发送整个数据值。但是，如果 bcp_bind 具有所支持的数据类型的 NULL pData 参数，则 bcp_moretext 可用于在从 bcp_sendrow（指示已处理含现有数据的任何绑定列）成功返回后立即复制数据。
如果使用 bcp_moretext 发送某一行中一个支持的数据类型列，则还必须使用它发送该行中所有其他支持的数据类型列。不可以跳过任何列。支持的数据类型为 SQLTEXT、SQLNTEXT、SQLIMAGE、SQLUDT 和 SQLXML。如果列分别为 varchar(max)、nvarchar(max) 或 varbinary(max)，则 SQLCHARACTER、SQLVARCHAR、SQNCHAR、SQLBINARY 和 SQLVARBINARY 也属于此类别。
调用 bcp_bind 或 bcp_collen 可设置要复制到 SQL Server 列的所有数据部分的总长度。尝试向 SQL Server 发送的字节数多于在对 bcp_bind 或 bcp_collen 的调用中指定的字节数会生成错误。例如，在使用 bcp_collen 将 SQL Server text 列的可用数据的长度设置为 4500，然后调用 bcp_moretext 五次，同时在每次调用时指示数据缓冲区长度为 1000 字节的应用程序中，就会发生这种错误。
如果复制的行包含多个较长的可变长度列，则 bcp_moretext 首先将其数据发送到按序号编号最靠前的列，后面紧跟下一个按序号编号最靠前的列，以此类推。正确设置所需的数据的总长度很重要。无法在长度设置之外发出已通过大容量复制接收某列的所有数据的信号。
在使用 bcp_sendrow 和 bcp_moretext 将 var(max) 值发送到服务器时，不需要调用 bcp_collen 来设置列长度。相反，仅对于这些类型，通过用长度零调用 bcp_sendrow 来终止值。
应用程序通常在循环内调用 bcp_sendrow 和 bcp_moretext 来发送多行数据。下面概述了如何为包含两个 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_moretext 与 bcp_bind 和 bcp_sendrow 一起使用：
// 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.