Partilhar via

  • Artigo

bcp_bind

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, SQLNCHAR 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 deve definir pData como NULL somente se a coluna correspondente ao campo associado ao usuário for uma coluna BLOB; caso contrário bcp_bind irá falhar.

    Se houve indicadores presentes nos dados, eles aparecerão na memória diretamente antes dos dados. Neste caso, o parâmetro pData aponta para a variável de indicador e a largura do indicador, o parâmetro cbIndicator, é usada pela cópia em massa para endereçar os dados de 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 definição do tipo de estrutura a seguir poderia ser usada para inserir valores inteiros em uma tabela do SQL Server usando a 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 iIndicator BCPBOUNDINT. O parâmetro cbIndicator seria definido com o tamanho de um inteiro (sizeof(int)), e o parâmetro cbData seria novamente definido com o tamanho de um inteiro (sizeof(int)). Para copiar uma linha em massa para o servidor que contém um valor NULL na 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.

    A definição de cbData como SQL_NULL_DATA significa que todas as linhas copiadas para o servidor contêm um valor NULL na coluna.

    A definição de cbData como SQL_VARLEN_DATA indica que o sistema irá 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. Assim, para tipos de dados de comprimento fixo, cbData pode seguramente ser SQL_VARLEN_DATA ou o comprimento dos dados.

    Para os tipos de dados de caracteres e binários 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 irá usar um indicador de comprimento/nulo (se presente) ou uma seqüê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 tipo de caracteres ou binário do SQL Server e não houver um indicador de comprimento nem uma seqüência de terminador especificados, o sistema retornará uma mensagem de erro.

    Se cbData for 0 ou um valor positivo, o sistema usará cbData como o comprimento de dados. Entretanto, se, além de um valor de cbData positivo, for fornecido um indicador de comprimento ou uma seqüência de terminador, 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 dados de caracteres forem representados por caracteres que abrangem Unicode, um valor de parâmetro cbData positivo representará o número de caracteres multiplicado pelo tamanho, em bytes, de cada caractere.

  • pTerm
    É 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 um 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 desse exemplo poderia indicar que 15 fossem 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 que abrange Unicode, finalizada pelo valor de terminador nulo Unicode:

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

    Se a coluna associada do SQL Server for do tipo caractere largo, nenhuma conversão será executada em bcp_sendrow. Se a coluna do SQL Server for do tipo caractere do MBCS, a conversão de caracteres largo em caracteres multibyte será executada conforme os dados são enviados para o SQL Server.

  • cbTerm
    É a contagem de bytes presentes no terminador da variável de programa, se houver. Se não houver um 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 SQL Server em sqlncli.h e não pelos enumeradores de tipo de dados ODBC C. Por exemplo, você pode especificar um inteiro de dois bytes, ODBC tipo SQL_C_SHORT, usando o tipo SQLINT2 específico do SQL Server.

    O SQL Server 2005 introduziu o suporte a tokens de tipo de dados SQLXML e SQLUDT no parâmetro eDataType.

  • idxServerCol
    É a posição ordinal da coluna na tabela do banco de dados na 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.

Retorna

SUCCEED ou FAIL.

Comentários

Use bcp_bind para obter um modo rápido e eficiente de copiar dados de uma variável de programa em 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 szDataFile de bcp_init, indicando o arquivo de dados, é definido como NULL; o parâmetro eDirection de bcp_init é definido como DB_IN.

Chame um bcp_bind separado para cada coluna da tabela do SQL Server na 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.

Sempre que desejar que o SQL Server confirme as linhas já recebidas, chame bcp_batch. Por exemplo, chame bcp_batch uma vez a 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âmetros de controle, especificadas com bcp_control, não têm qualquer efeito sobre as transferências de linha de bcp_bind.

Se pData de uma coluna for definido como NULL porque seu valor será fornecido pelas chamadas de bcp_moretext, todas as colunas subseqüentes com eDataType definido como SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR ou SQLIMAGE também devem ser associadas com pData definido como NULL, e seus valores também devem ser fornecidos por chamadas de 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 irá pesquisar o terminador, calcular o comprimento dos dados com relação ao terminador (i) e definir cbData com o menor valor de i e o valor do prefixo.

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

  • 0xFFFFFFFFFFFFFFFF significa um valor nulo para o campo

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

  • <SPECIAL_PREFIX> <0 ou mais DATA CHUNKS> <ZERO_CHUNK> onde:

  • SPECIAL_PREFIX é 0xFFFFFFFFFFFFFFFE

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

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

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

Chamar bcp_columns ao usar bcp_bind gera 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/hora aprimorados (OLE DB e ODBC).

Para obter mais informações, consulte Aprimoramentos de data/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);

Consulte também

Referência

Funções de cópia em massa