bcp_moretext
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 pelo 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 de comprimento variável longos 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 nonNULL para tipos de dados compatíveis com bcp_moretext, bcp_sendrow enviará todo o valor de dados, independentemente do comprimento. Se, no entanto, 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 indicando bcp_sendrow 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 costumava bcp_collen definir o comprimento dos dados disponíveis para uma coluna de SQL Server text como 4500 e, em seguida, chamado bcp_moretext cinco vezes enquanto indicava em cada chamada que o comprimento do buffer de dados tinha 1000 bytes de comprimento.
Se uma linha copiada contiver mais de uma coluna de comprimento variável longa, bcp_moretext primeiro enviará seus dados para a coluna numerada ordinal mais baixa, seguida pela próxima coluna numerada ordinalmente 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 var(max) os valores 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, somente para esses tipos, o valor é encerrado chamando bcp_sendrow com um comprimento de zero.
Um aplicativo normalmente chama bcp_sendrow e bcp_moretext dentro de 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 text colunas:
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.