bcp_moretext

Aplica-se a:SQL ServerBase de Dados SQL do AzureInstância Gerida do Azure SQLAzure Synapse Analytics

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

Syntax

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

Arguments

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

cbData
É o número de bytes de dados copiados para o SQL Server a partir dos dados referenciados pelo pData. Um valor de SQL_NULL_DATA indica NULL.

pDados
É um apontador para o bloco de dados longo, de comprimento variável suportado a ser enviado para o SQL Server.

Devoluções

TER SUCESSO ou FALHAR.

Observações

Esta função pode ser usada em conjunto com bcp_bind e bcp_sendrow para copiar valores longos de dados de comprimento variável para SQL Server em vários blocos mais pequenos. bcp_moretext pode ser usado com colunas que contêm os seguintes tipos de dados SQL Server: texto, ntext, imagem, varchar(max), nvarchar(max), varbinary(max), tipo definido pelo utilizador (UDT) e XML. bcp_moretext não suporta conversões de dados, os dados fornecidos devem corresponder ao tipo de dado da coluna de destino.

Se bcp_bind for chamado com um parâmetro pData não-NULL para tipos de dados suportados por bcp_moretext, bcp_sendrow envia o valor total dos dados, independentemente do comprimento. Se, no entanto, bcp_bind tiver um parâmetro NULL pData para tipos de dados suportados, bcp_moretext pode ser usado para copiar dados imediatamente após um retorno bem-sucedido de bcp_sendrow indicando que quaisquer colunas limitadas com dados presentes foram processadas.

Se usar bcp_moretext para enviar uma coluna de tipo de dado suportado numa linha, deve também usá-la para enviar todas as outras colunas de tipos de dados suportadas na linha. Nenhuma coluna pode ser ignorada. Os tipos de dados suportados são SQLTEXT, SQLNTEXT, SQLIMAGE, SQLUDT e SQLXML. SQLCHARACTER, SQLVARCHAR, SQNCHAR, SQLBINARY e SQLVARBINARY também se enquadram nesta categoria se a coluna for varchar(max), nvarchar(max) ou varbinary(max), respetivamente.

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. Este erro surgiria, por exemplo, numa aplicação que usava bcp_collen para definir o comprimento dos dados disponíveis para uma coluna de texto SQL Server para 4500, e depois chamava bcp_moretext cinco vezes, indicando em cada chamada que o comprimento do buffer de dados tinha 1000 bytes.

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

Quando valores var(max) são enviados ao servidor usando bcp_sendrow e bcp_moretext, não é necessário chamar bcp_collen para definir o comprimento da coluna. Em vez disso, apenas para estes tipos, o valor é terminado ao chamar bcp_sendrow com comprimento zero.

Uma aplicação normalmente chama bcp_sendrow e bcp_moretext dentro de ciclos para enviar várias linhas de dados. Aqui está um esboço de como fazer isto 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);  
  
}

Example

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.

Conteúdo relacionado

  • Última atualização a