bcp_moretext

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsPDW (Analytics Platform System)

Envia parte de um valor de tipo de dados longo e de comprimento variável para SQL Server.

Sintaxe

  
RETCODE bcp_moretext (  
        HDBC hdbc,  
        DBINT cbData,  
        LPCBYTE pData);  

Argumentos

hdbc
É o identificador de conexão ODBC habilitado para cópia em massa.

cbData
É o número de bytes de dados que estão sendo copiados para SQL Server dos dados referenciados por pData. Um valor igual a SQL_NULL_DATA indica NULL.

pData
É um ponteiro para a parte de dados com suporte, longa e de comprimento variável a ser enviada para SQL Server.

Retornos

SUCCEED ou FAIL.

Comentários

Essa função pode ser usada em conjunto com bcp_bind e bcp_sendrow para copiar valores de dados longos e de comprimento variável para SQL Server em várias partes menores. bcp_moretext pode ser usado com colunas que têm os seguintes tipos de dados SQL Server: text, ntext, image, varchar(max), nvarchar(max), varbinary(max), UDT (tipo definido pelo usuário) e XML. bcp_moretext não dá suporte a conversões de dados, os dados fornecidos devem corresponder ao tipo de dados da coluna de destino.

Se bcp_bind for chamado com um parâmetro pData não NULL para tipos de dados compatíveis com bcp_moretext, bcp_sendrow enviará todo o valor de dados, independentemente do comprimento. No entanto, se bcp_bind tiver um parâmetro pData NULL para tipos de dados com suporte, bcp_moretext poderá ser usado para copiar dados imediatamente após um retorno bem-sucedido de bcp_sendrow indicando que todas as colunas associadas com os dados presentes foram processadas.

Se você usar bcp_moretext para enviar uma coluna de tipo de dados com suporte em uma linha, também deverá usá-la para enviar todas as outras colunas de tipo de dados com suporte na linha. Nenhuma coluna pode ser ignorada. Os tipos de dados para os quais há suporte são SQLTEXT, SQLNTEXT, SQLIMAGE, SQLUDT e SQLXML. SQLCHARACTER, SQLVARCHAR, SQNCHAR, SQLBINARY e SQLVARBINARY também se encontram nessa categoria caso a coluna seja varchar(max), nvarchar(max) ou varbinary(max), respectivamente.

Chamar bcp_bind ou bcp_collen define o comprimento total de todas as partes de dados a serem copiadas para a coluna SQL Server. Uma tentativa de enviar SQL Server mais bytes do que o especificado na chamada para bcp_bind ou bcp_collen gera um erro. Esse erro surgiria, por exemplo, em um aplicativo que usou bcp_collen para definir o comprimento dos dados disponíveis para uma coluna de texto SQL Server como 4500 e, em seguida, chamado bcp_moretext cinco vezes, indicando em cada chamada que o comprimento do buffer de dados tinha 1000 bytes de comprimento.

Se uma linha copiada contiver mais de uma coluna longa de comprimento variável, bcp_moretext primeiro enviará seus dados para a coluna numerada ordinicamente mais baixa, seguida pela próxima coluna numerada ordinicamente mais baixa e assim por diante. A configuração correta do comprimento total dos dados esperados é importante. Não há nenhuma forma de sinalizar, fora da configuração de comprimento, que todos os dados de uma coluna foram recebidos pela cópia em massa.

Quando os valores var(max) são enviados para o servidor usando bcp_sendrow e bcp_moretext, não é necessário chamar bcp_collen para definir o comprimento da coluna. Em vez disso, somente para esses tipos, o valor é encerrado chamando bcp_sendrow com um comprimento de zero.

Um aplicativo normalmente chama bcp_sendrow e bcp_moretext em loops para enviar várias linhas de dados. Aqui está uma estrutura de tópicos de como fazer isso para uma tabela que contém duas colunas de texto :

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);  
  
}  
  

Exemplo

Este exemplo mostra como usar bcp_moretext com bcp_bind e 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.  

Consulte Também

Bulk Copy Functions