bcp_bind

Aplica-se a: SQL ServerBase de Dados SQL do AzureAzure SQL Managed InstanceAzure Synapse AnalyticsSistema de Plataforma de Análise (PDW)

Vincula dados de uma variável de programa para uma coluna de tabela para cópia em massa no SQL Server.

Syntax

  
RETCODE bcp_bind (  
        HDBC hdbc,
        LPCBYTE pData,  
        INT cbIndicator,  
        DBINT cbData,  
        LPCBYTE pTerm,  
        INT cbTerm,  
        INT eDataType,  
        INT idxServerCol);  

Arguments

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

pDados
É um apontador para os dados copiados. Se o eDataType for SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR ou SQLIMAGE, o pData pode ser NULL. Um pData NULL indica que valores de dados longos serão enviados para SQL Server em blocos usando bcp_moretext. O utilizador só deve definir pData como NULL se a coluna correspondente ao campo limitado pelo utilizador for uma coluna BLOB, caso contrário bcp_bind falhará.

Se os indicadores estiverem presentes nos dados, aparecem na memória diretamente antes dos dados. O parâmetro pData aponta para a variável indicadora neste caso, e a largura do indicador, o parâmetro cbIndicator , é usada por cópia em massa para endereçar corretamente os dados do utilizador.

cbIndicator
É o comprimento, em bytes, de um indicador de comprimento ou nulo para os dados da coluna. Os valores válidos do comprimento do indicador são 0 (quando não se usa indicador), 1, 2, 4 ou 8. Os indicadores aparecem na memória diretamente antes de qualquer dado. Por exemplo, a seguinte definição de tipo de estrutura poderia ser usada para inserir valores inteiros numa tabela SQL Server usando cópia em massa:

typedef struct tagBCPBOUNDINT  
    {  
    int iIndicator;  
    int Value;  
    } BCPBOUNDINT;  

No caso de exemplo, o parâmetro pData seria definido para o endereço de uma instância declarada da estrutura, o endereço do membro da estrutura BCPBOUNDINT iIndicator . O parâmetro cbIndicator seria definido para o tamanho de um inteiro (sizeof(int)), e o parâmetro cbData seria novamente definido para o tamanho de um inteiro (sizeof(int)). Para copiar em massa uma linha para o servidor contendo um valor NULL para a coluna vinculada, o valor do membro iIndicator da instância deve ser definido para SQL_NULL_DATA.

cbData
É a contagem de bytes de dados na variável do programa, não incluindo o comprimento de qualquer comprimento ou indicador ou terminador nulo.

Definir cbData para SQL_NULL_DATA significa que todas as linhas copiadas para o servidor contêm um valor NULL para a coluna.

Definir cbData para SQL_VARLEN_DATA indica que o sistema usará um terminador de strings, ou outro método, para determinar o comprimento dos dados copiados.

Para tipos de dados de comprimento fixo, como inteiros, o tipo de dados indica o comprimento dos dados até ao sistema. Portanto, para tipos de dados de comprimento fixo, o cbData pode ser SQL_VARLEN_DATA com segurança ou o comprimento dos dados.

Para SQL Server tipos de caracteres e de dados binários, cbData pode ser SQL_VARLEN_DATA, SQL_NULL_DATA, algum valor positivo ou 0. Se o cbData for SQL_VARLEN_DATA, o sistema utiliza um indicador de comprimento/nulo (se presente) ou uma sequência de terminadores para determinar o comprimento dos dados. Se ambos forem fornecidos, o sistema usa aquele que resulta na menor quantidade de dados a ser copiado. Se cbData for SQL_VARLEN_DATA, o tipo de dado da coluna for de carácter SQL Server ou binário, e nem indicador de comprimento nem sequência de terminadores for especificado, o sistema devolve uma mensagem de erro.

Se cbData for 0 ou um valor positivo, o sistema usa cbData como comprimento de dados. No entanto, se, além de um valor cbData positivo, for fornecido um indicador de comprimento ou sequência de terminadores, o sistema determina o comprimento dos dados usando o método que resulta na menor quantidade de dados a ser copiada.

O valor do parâmetro cbData representa a contagem de bytes de dados. Se os dados dos caracteres forem representados por caracteres de larga escala Unicode, então um valor positivo do parâmetro cbData representa o número de caracteres multiplicado pelo tamanho em bytes de cada carácter.

pTerm
É um apontador para o padrão de bytes, se existir, que marca o fim desta variável do programa. Por exemplo, as cadeias de Dó ANSI e MBCS geralmente têm um terminador de 1 byte (\0).

Se não houver terminador para a variável, defina pTerm para NULL.

Pode usar uma string vazia ("") para designar o terminador nulo C como terminador da variável de programa. Como a cadeia vazia terminada por null constitui um único byte (o próprio byte do terminador), defina cbTerm para 1. Por exemplo, para indicar que a cadeia em szName está terminada por nulo e que o terminador deve ser usado para indicar o comprimento:

bcp_bind(hdbc, szName, 0,  
   SQL_VARLEN_DATA, "", 1,  
   SQLCHARACTER, 2)  

Uma forma não terminada deste exemplo poderia indicar que 15 caracteres devem ser copiados da variável szName para a segunda coluna da tabela limitada:

bcp_bind(hdbc, szName, 0, 15,
   NULL, 0, SQLCHARACTER, 2)  

A API de cópia em massa realiza a conversão de caracteres de Unicode para MBCS conforme necessário. Certifique-se de que tanto a cadeia de bytes do terminador como o comprimento da cadeia de bytes estão definidos corretamente. Por exemplo, para indicar que a cadeia em szName é uma cadeia de caracteres de larga escala Unicode, terminada pelo valor do terminador nulo Unicode:

bcp_bind(hdbc, szName, 0,
   SQL_VARLEN_DATA, L"",  
   sizeof(WCHAR), SQLNCHAR, 2)  

Se a coluna de SQL Server limitada for de carácter largo, não é realizada conversão em bcp_sendrow. Se a coluna do SQL Server for um tipo de carácter MBCS, a conversão de carácter largo para multibyte é feita à medida que os dados são enviados para o SQL Server.

cbTerm
É a contagem de bytes presentes no terminador para a variável do programa, se existir. Se não houver terminador para a variável, defina cbTerm para 0.

eDataType É o tipo de dado C da variável do programa. Os dados na variável do programa são convertidos para o tipo da coluna da base de dados. Se este parâmetro for 0, não é realizada conversão.

O parâmetro eDataType é enumerado pelos tokens de tipo de dados do SQL Server em sqlncli.h, não pelos enumeradores de tipos de dados ODBC C. Por exemplo, pode especificar um inteiro de dois bytes, tipo ODBC SQL_C_SHORT, usando o tipo específico de SQL Server SQLINT2.

O SQL Server 2005 (9.x) introduziu suporte para tokens de tipo de dados SQLXML e SQLUDT no parâmetro eDataType.

A tabela seguinte lista os tipos de dados enumerados válidos e os correspondentes tipos de dados ODBC C.

idxServerCol É a posição ordinal da coluna na tabela da base de dados para onde os dados são copiados. A primeira coluna de uma tabela é a coluna 1. A posição ordinal de uma coluna é reportada por SQLColumns.

Devoluções

TER SUCESSO ou FALHAR.

Observações

Use bcp_bind como forma rápida e eficiente de copiar dados de uma variável de programa para uma tabela em SQL Server.

Ligue bcp_init antes de chamar esta ou qualquer outra função de cópia em massa. Chamar bcp_init define a tabela SQL Server alvo para cópia em massa. Ao chamar bcp_init para uso com bcp_bind e bcp_sendrow, o parâmetro bcp_initszDataFile , que indica o ficheiro de dados, é definido como NULL; o parâmetro bcp_initeDirection está definido para DB_IN.

Crie uma chamada de bcp_bind separada para cada coluna da tabela de SQL Server onde quer copiar. Depois de feitas as chamadas bcp_bind necessárias, ligue para bcp_sendrow para enviar uma linha de dados das variáveis do seu programa para SQL Server. Não é suportado reagrupar uma coluna.

Sempre que quiseres SQL Server confirmar as linhas já recebidas, liga para bcp_batch. Por exemplo, chame bcp_batch uma vez por cada 1000 linhas inseridas ou em qualquer outro intervalo.

Quando não houver mais linhas para inserir, chame bcp_done. Se não o fizer, registar-se-á um erro.

As definições dos parâmetros de controlo, especificadas com bcp_control, não têm qualquer efeito nas transferências bcp_bind linhas.

Se o pData de uma coluna for definido como NULL porque o seu valor será fornecido por chamadas a bcp_moretext, quaisquer colunas subsequentes com eDataType definido como SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR ou SQLIMAGE também devem ser atribuídas com pData definido para NULL, e os seus valores também devem ser fornecidos por chamadas a bcp_moretext.

Para novos tipos de grande valor, como varchar(max), varbinary(max) ou nvarchar(max), pode usar SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY e SQLNCHAR como indicadores de tipo no parâmetro eDataType .

Se cbTerm não for 0, qualquer valor (1, 2, 4 ou 8) é válido para o prefixo (cbIndicator). Nesta situação, o SQL Server Native Client procura o terminador, calcula o comprimento dos dados em relação ao terminador (i) e define cbData para o valor menor de i e o valor do prefixo.

Se cbTerm for 0 e cbIndicator (o prefixo) não for 0, cbIndicator deve ser 8. O prefixo de 8 bytes pode assumir os seguintes valores:

• 0xFFFFFFFFFFFFFFFF significa um valor nulo para o campo

• 0xFFFFFFFFFFFFFFFE é tratado como um valor especial de prefixo, que é usado para enviar dados de forma eficiente em blocos para o servidor. O formato dos dados com este prefixo especial é:

• <SPECIAL_PREFIX><0 ou mais BLOCOS><de DADOS ZERO_CHUNK> onde:

• SPECIAL_PREFIX é 0xFFFFFFFFFFFFFFFE

• DATA_CHUNK é um prefixo de 4 bytes que contém o comprimento do bloco, seguido pelos dados reais cujo comprimento é especificado no prefixo de 4 bytes.

• ZERO_CHUNK é um valor de 4 bytes contendo todos os zeros (00000000) indicando o fim dos dados.

• Qualquer outro comprimento válido de 8 bytes é tratado como um comprimento de dado normal.

Chamar bcp_columns ao usar bcp_bind resulta num erro.

bcp_bind Suporte a Funcionalidades Melhoradas de Data e Hora

Para informações sobre os tipos usados com o parâmetro eDataType para tipos de data/hora, consulte Alterações de Cópia em Massa para Tipos de Data e Hora Melhorados (OLE DB e ODBC).

Para obter mais informações, consulte Melhorias de data e hora (ODBC).

Example

#include sql.h  
#include sqlext.h  
#include odbcss.h  
// Variables like henv not specified.  
HDBC      hdbc;  
char         szCompanyName[MAXNAME];  
DBINT      idCompany;  
DBINT      nRowsProcessed;  
DBBOOL      bMoreData;  
char*      pTerm = "\t\t";  
  
// 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 bcp.
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL  
   DB_IN) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Bind program variables to table columns.
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,  
   SQLINT4, 1)    == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,  
   (LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
while (TRUE)  
   {  
   // Retrieve and process program data.
   if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)  
      {  
      // Send the data.
      if (bcp_sendrow(hdbc) == FAIL)  
         {  
         // Raise error and return.  
         return;  
         }  
      }  
   else  
      {  
      // Break out of loop.  
      break;  
      }  
   }  
  
// Terminate the bulk copy operation.  
if ((nRowsProcessed = bcp_done(hdbc)) == -1)  
   {  
   printf_s("Bulk-copy unsuccessful.\n");  
   return;  
   }  
  
printf_s("%ld rows copied.\n", nRowsProcessed);  

Conteúdo relacionado

• Extensões de Drivers SQL Server - Funções de Cópia em Massa