bcp_moretext

适用于：SQL ServerAzure SQL 数据库Azure SQL 托管实例Azure 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可用于具有以下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文本列的可用数据长度设置为 4500 的应用程序中，然后调用 bcp_moretext五次，同时在每次调用时指示数据缓冲区长度为 1000 字节。

如果复制的行包含多个长度可变的长列， bcp_moretext 首先将其数据发送到序号最低的列，然后是下一个序号最低的列，依此进行排序。 正确设置所需的数据的总长度很重要。 无法在长度设置之外发出已通过大容量复制接收某列的所有数据的信号。

使用 bcp_sendrow 和 bcp_moretext 将 var (max ) 值发送到服务器时，无需调用 bcp_collen 来设置列长度。 相反，仅对于这些类型，通过调用长度为零的 bcp_sendrow 终止值。

应用程序通常调用 bcp_sendrow ，并在循环中 bcp_moretext 以发送多行数据。 下面概述了如何对包含两个 文本 列的表执行此操作：

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.  

另请参阅

大容量复制函数