bcp_moretext

Artigo
05/07/2013

Envia parte de um valor de tipo de dados longo, de tamanho variável, para o 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 copiados para o SQL Server dos dados referenciado por pData. Um valor igual a SQL_NULL_DATA indica NULL.
pData
É um ponteiro da parte de dados de tamanho variável, longa, para a qual há suporte a ser enviado para o SQL Server.

Retorna

SUCCEED ou FAIL.

Comentários

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

Caso bcp_bind seja chamado com um parâmetro pData nonNULL para os tipos de dados para os quais bcp_moretext oferecem suporte, bcp_sendrow envia todo o valor de dados, independentemente do comprimento. No entanto, caso bcp_bind tenha um parâmetro pData NULL para os tipos de dados para os quais há suporte, bcp_moretext pode ser usado para copiar dados logo após um retorno bem-sucedido de bcp_sendrow, o que indica que todas as colunas associadas aos dados presentes foram processadas.

Caso use bcp_moretext para enviar uma coluna de tipo de dados para a qual há suporte, você também deve usá-lo para enviar todas as demais colunas de tipo de dados na sequência. 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 do SQL Server. Uma tentativa de enviar ao 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 text do SQL Server como 4500 e chamou bcp_moretext cinco vezes enquanto indicava em cada chamada que o comprimento do buffer de dados tinha 1.000 bytes.

Caso uma linha copiada contenha mais de uma coluna de comprimento variável, longa, bcp_moretext envia primeiro os dados para a menor coluna numerada ordinalmente, seguida da próxima menor coluna numerada ordinalmente 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 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. Na verdade, somente para esses tipos, o valor é encerrado chamando bcp_sendrow com um comprimento igual a zero.

Um aplicativo normalmente chama bcp_sendrow e bcp_moretext em loops enviar várias linhas de dados. Eis um esboço de como fazer isso para uma tabela que contém duas colunas 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);

}

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

Referência

Funções de cópia em massa

Compartilhar via