bcp_moretext

适用于：SQL Server Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics Analytics 平台系统（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 5 次，同时指示数据缓冲区长度为 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.  

另请参阅

大容量复制函数