IBCPSession::BCPColFmt (OLE DB)

Cria uma associação entre variáveis de programa e colunas do SQL Server.

Sintaxe

  
HRESULT BCPColFmt(   
DBORDINALidxUserDataCol,  
inteUserDataType,  
intcbIndicator,  
intcbUserData,  
BYTE *pbUserDataTerm,  
intcbUserDataTerm,  
DBORDINALidxServerCol);  

Observações

O método BCPColFmt é usado para criar uma associação entre campos de arquivo de dados BCP e colunas do SQL Server. Ele usa o comprimento, o tipo, o terminador e o comprimento do prefixo de uma coluna como parâmetros e define cada uma dessas propriedades para campos individuais.

Se o usuário escolher o modo interativo, esse método será chamado duas vezes; uma vez para definir o formato da coluna de acordo com os valores padrão (que estão de acordo com o tipo da coluna do servidor) e uma vez para definir o formato de acordo com o tipo de coluna da escolha do cliente escolhido durante o modo interativo, para cada coluna.

Em modos não interativos, ele é chamado apenas uma vez por coluna para definir o tipo de cada coluna como caractere ou tipo nativo e definir os terminadores de coluna e linha.

O método BCPColFmt permite que você especifique o formato de arquivo de usuário para cópias em massa. Para cópia em massa, um formato contém as seguintes partes:

• Um mapeamento de campos de arquivo de usuário para colunas de banco de dados.

• O tipo de dados de cada campo de arquivo de usuário.

• O comprimento do indicador opcional para cada campo.

• O comprimento máximo dos dados por campo de arquivo de usuário.

• A sequência de bytes de encerramento opcional para cada campo.

• O comprimento da sequência de bytes de encerramento opcional.

Cada chamada para BCPColFmt especifica o formato de um campo de arquivo de usuário. Por exemplo, para alterar as configurações padrão de três campos em um arquivo de dados de usuário de cinco campos, primeiro chame BCPColumns(5)e, em seguida, chame BCPColFmt cinco vezes, com três dessas chamadas definindo seu formato personalizado. Para as duas chamadas restantes, defina eUserDataType como BCP_TYPE_DEFAULT e defina cbIndicator, cbUserData e cbUserDataTerm como 0, BCP_VARIABLE_LENGTH e 0, respectivamente. Este procedimento copia todas as cinco colunas, três com o formato personalizado e duas com o formato padrão.

Você não precisa copiar todos os dados em um arquivo de usuário para uma tabela do SQL Server. Para ignorar uma coluna, especifique o formato dos dados para a coluna que define o parâmetro idxServerCol como 0. Para ignorar um campo, você ainda precisa de todas as informações para que o método funcione corretamente.

Nota A função IBCPSession::BCPWriteFmt pode ser usada para persistir a especificação de formato fornecida por meio de BCPColFmt.

Argumentos

idxUserDataCol[in]
Índice do campo no arquivo de dados do usuário.

eUserDataType[in]
O tipo de dados do campo no arquivo de dados do usuário. Os tipos de dados disponíveis são listados no arquivo de cabeçalho do SQL Server Native Client (sqlncli.h) com formato BCP_TYPE_XXX, por exemplo, BCP_TYPE_SQLINT4. Se o valor BCP_TYPE_DEFAULT for especificado, o provedor tentará usar o mesmo tipo que o tipo de coluna de tabela ou exibição. Para operações de cópia em massa do SQL Server e em um arquivo quando o eUserDataType argumento é BCP_TYPE_SQLDECIMAL ou BCP_TYPE_SQLNUMERIC:

• Se a coluna de origem não for decimal ou numérica, a precisão e a escala padrão serão usadas.

• Se a coluna de origem for decimal ou numérica, a precisão e a escala da coluna de origem serão usadas.

cbIndicator[in]
Comprimento do prefixo para o campo. O padrão é BCP_PREFIX_DEFAULT. Os comprimentos válidos para o prefixo são 0, 1, 2, 4 e 8. Um tamanho de prefixo de 8 é mais comumente usado para indicar que o campo é agrupado. Isso é usado para copiar colunas de tipo de valor grandes com eficiência em massa.

cbUserData[in]
O comprimento máximo, em bytes, dos dados desse campo no arquivo de usuário, não incluindo o comprimento de qualquer indicador de comprimento ou terminador.

A configuração cbUserData para BCP_LENGTH_NULL indica que todos os valores nos campos de arquivo de dados estão ou devem ser definidos como NULL. A configuração cbUserData para BCP_LENGTH_VARIABLE indica que o sistema deve determinar o comprimento dos dados para cada campo. Para alguns campos, isso pode significar que um indicador de comprimento/nulo é gerado para preceder dados em uma cópia do SQL Server ou que o indicador é esperado em dados copiados para o SQL Server.

Para tipos de caracteres e de dados binários do SQL Server, cbUserData pode ser BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0 ou algum valor positivo. Se cbUserData for BCP_LENGTH_VARIABLE, o sistema usará o indicador de comprimento, se presente, ou uma sequência de terminador para determinar o comprimento dos dados. Se um indicador de comprimento e uma sequência de terminador forem fornecidos, a cópia em massa usará aquele que resulta na menor quantidade de dados sendo copiados. Se cbUserData for BCP_LENGTH_VARIABLE, o tipo de dados será um caractere ou um tipo binário do SQL Server e, se nem um indicador de comprimento nem uma sequência de terminador forem especificados, o sistema retornará uma mensagem de erro.

Se cbUserData for 0 ou um valor positivo, o sistema usará cbUserData como o tamanho máximo dos dados. No entanto, se, além de um positivo cbUserData, um indicador de comprimento ou 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 cbUserData valor representa a contagem de bytes de dados. Se os dados de caracteres forem representados por caracteres largos Unicode, um valor de parâmetro positivo cbUserData representará o número de caracteres multiplicados pelo tamanho, em bytes, de cada caractere.

pbUserDataTerm[size_is][in]
A sequência do terminador a ser usada para o campo. Esse parâmetro é útil principalmente para tipos de dados de caractere porque todos os outros tipos têm comprimento fixo ou, no caso de dados binários, exigem um indicador de comprimento para registrar com precisão o número de bytes presentes.

Para evitar o término dos dados extraídos ou para indicar que os dados em um arquivo de usuário não foram encerrados, defina esse parâmetro como NULL.

Se mais de um meio de especificar um comprimento de coluna de arquivo de usuário for usado (como um terminador e um indicador de comprimento, ou um terminador e um comprimento máximo de coluna), a cópia em massa escolherá a que resulta na menor quantidade de dados sendo copiados.

A API de cópia em massa executa a conversão de caracteres Unicode em MBCS conforme necessário. É necessário ter cuidado para garantir que a cadeia de caracteres de byte do terminador e o comprimento da cadeia de caracteres de bytes sejam definidos corretamente.

cbUserDataTerm[in]
O comprimento, em bytes, da sequência do terminador a ser usada para a coluna. Se nenhum terminador estiver presente ou desejado nos dados, defina esse valor como 0.

idxServerCol[in]
A posição ordinal da coluna na tabela de banco de dados. O número da primeira coluna é 1. A posição ordinal de uma coluna é relatada por IColumnsInfo::GetColumnInfo ou métodos semelhantes. Se esse valor for 0, a cópia em massa ignorará o campo no arquivo de dados.

Valores do código de retorno

S_OK
O método foi bem-sucedido.

E_FAIL
Ocorreu um erro específico do provedor, para obter informações detalhadas, use a interface ISQLServerErrorInfo .

E_UNEXPECTED
A chamada para o método foi inesperada. Por exemplo, o método IBCPSession::BCPInit não foi chamado antes de chamar esse método.

E_INVALIDARG
O argumento era inválido.

E_OUTOFMEMORY
Erro de memória insuficiente.

Consulte Também

IBCPSession (OLE DB)
Executando operações de cópia em massa