bcp_bind

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics Analytics Platform System (PDW)

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

Sintaxe

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

Argumentos

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

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

Se houve indicadores presentes nos dados, eles aparecerão na memória diretamente antes dos dados. O parâmetro pData aponta para a variável do indicador neste caso, e a largura do indicador, o parâmetro cbIndicator , é usado por cópia em massa para endereçar os dados do usuário corretamente.

cbIndicator
É o comprimento, em bytes, de um indicador de comprimento ou nulo para os dados da coluna. Os valores de comprimento de indicador válidos são 0 (quando nenhum indicador é usado), 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 pode ser usada para inserir valores inteiros em uma tabela do 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 como 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 como o tamanho de um inteiro (sizeof(int)), e o parâmetro cbData seria novamente definido como o tamanho de um inteiro (sizeof(int)). Para copiar em massa uma linha para o servidor que contém um valor NULL para a coluna associada, o valor do membro iIndicator da instância deve ser definido como SQL_NULL_DATA.

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

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

Definir cbData como SQL_VARLEN_DATA indica que o sistema usará um terminador de cadeia de caracteres, 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 para o sistema. Portanto, para tipos de dados de comprimento fixo, cbData pode ser SQL_VARLEN_DATA com segurança ou o comprimento dos dados.

Para tipos de dados binários e de caracteres do SQL Server, cbData pode ser SQL_VARLEN_DATA, SQL_NULL_DATA, algum valor positivo ou 0. Se cbData for SQL_VARLEN_DATA, o sistema usará um indicador de comprimento/nulo (se presente) ou uma sequência de terminador para determinar o comprimento dos dados. Se os dois forem fornecidos, o sistema irá usar aquele que resulta na menos quantidade de dados sendo copiados. Se cbData for SQL_VARLEN_DATA, o tipo de dados da coluna for um caractere ou tipo binário do SQL Server e nem um indicador de comprimento nem uma sequência de terminador forem especificados, o sistema retornará uma mensagem de erro.

Se cbData for 0 ou um valor positivo, o sistema usará cbData como o comprimento dos dados. No entanto, se, além de um valor cbData positivo, um indicador de comprimento ou uma sequência de terminador for fornecido, o sistema determinará o comprimento dos dados usando o método que resulta na menor quantidade de dados sendo copiados.

O valor do parâmetro cbData representa a contagem de bytes de dados. Se os dados de caracteres forem representados por caracteres largos Unicode, um valor de parâmetro cbData positivo representará o número de caracteres multiplicado pelo tamanho em bytes de cada caractere.

pTermo
É um ponteiro para o padrão de bytes, se houver, que marca o fim desta variável de programa. Por exemplo, geralmente, as cadeias de caracteres C ANSI e MBCS têm um terminador com 1 byte (\0).

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

Você pode usar uma cadeia de caracteres vazia ("") para designar o terminador nulo C como o terminador de variável do programa. Como a cadeia de caracteres vazia terminada em nulo constitui um único byte (o próprio byte do terminador), defina cbTerm como 1. Por exemplo, para indicar que a cadeia de caracteres em szName é terminada em 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 pode indicar que 15 caracteres sejam copiados da variável szName para a segunda coluna da tabela associada:

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

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

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

Se a coluna vinculada do SQL Server for de caractere largo, nenhuma conversão será executada em bcp_sendrow. Se a coluna do SQL Server for um tipo de caractere MBCS, a conversão de caracteres largos em caracteres multibyte será executada à medida que os dados forem enviados ao SQL Server.

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

eDataType É o tipo de dados C da variável de programa. Os dados na variável de programa são convertidos para o tipo da coluna do banco de dados. Se esse parâmetro for 0, nenhuma conversão será executada.

O parâmetro eDataType é enumerado pelos tokens de tipo de dados do SQL Server em sqlncli.h, não pelos enumeradores de tipo de dados ODBC C. Por exemplo, você pode especificar um inteiro de dois bytes, tipo ODBC SQL_C_SHORT, usando o tipo específico do 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 a seguir lista os tipos de dados enumerados válidos e os tipos de dados ODBC C correspondentes.

idxServerCol É a posição ordinal da coluna na tabela do banco de dados para a qual os dados são copiados. A primeira coluna em uma tabela é a coluna 1. A posição ordinal de uma coluna é relatada por SQLColumns.

Devoluções

SUCCEED ou FAIL.

Comentários

Use bcp_bind para obter uma maneira rápida e eficiente de copiar dados de uma variável de programa para uma tabela no SQL Server.

Chame bcp_init antes de chamar essa ou qualquer outra função de cópia em massa. Chamar bcp_init define a tabela de destino do SQL Server para cópia em massa. Ao chamar bcp_init para uso com bcp_bind e bcp_sendrow, o parâmetro bcp_init szDataFile , indicando o arquivo de dados, é definido como NULL; o parâmetro bcp_initeDirection é definido como DB_IN.

Faça uma chamada de bcp_bind separada para cada coluna na tabela do SQL Server para a qual você deseja copiar. Depois que as chamadas de bcp_bind necessárias forem feitas, chame bcp_sendrow para enviar uma linha de dados de suas variáveis de programa para o SQL Server. Reassociar uma coluna não tem suporte.

Sempre que quiser que o SQL Server confirme as linhas já recebidas, chame bcp_batch. Por exemplo, chame bcp_batch uma vez para cada 1000 linhas inseridas ou em qualquer outro intervalo.

Quando não houver mais linhas a serem inseridas, chame bcp_done. Caso isso não seja feito, será gerado um erro.

As configurações de parâmetro de controle, especificadas com bcp_control, não têm efeito sobre bcp_bind transferências de linha.

Se pData para uma coluna for definida como NULL porque seu valor será fornecido por chamadas para bcp_moretext, todas as colunas subsequentes com eDataType definido como SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHER ou SQLIMAGE também deverão ser associadas a pData definido como NULL e seus valores também deverão ser fornecidos por chamadas para bcp_moretext.

Para novos tipos de valor grande, como varchar(max), varbinary(max) ou nvarchar(max), você 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) será válido para o prefixo (cbIndicator). Nessa situação, o SQL Server Native Client procurará o terminador, calculará o comprimento dos dados em relação ao terminador (i) e definirá o cbData como o menor valor de i e o valor de prefixo.

Se cbTerm for 0 e cbIndicator (o prefixo) não for 0, cbIndicator deverá 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 de prefixo especial, que é usado para enviar dados com eficiência em partes para o servidor. O formato dos dados com este prefixo especial é:

• <><SPECIAL_PREFIX 0 ou mais BLOCOS DE<>DADOS ZERO_CHUNK> em que:

• SPECIAL_PREFIX é 0xFFFFFFFFFFFFFFFE

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

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

• Qualquer outro comprimento válido de 8 bytes é tratado como um comprimento de dados regular.

Chamar bcp_columns ao usar bcp_bind resulta em um erro.

Suporte do bcp_bind a recursos aprimorados de data e hora

Para obter 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 aprimorados (OLE DB e ODBC).

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

Exemplo

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

Confira também

Funções de cópia em massa