IBCPSession::BCPColFmt (OLE DB)

Aplica-se a:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSistema de Plataforma de Análise (PDW)Base de dados SQL no Microsoft Fabric

Baixar driver OLE DB

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

Sintaxe

  
HRESULT BCPColFmt(   
      DBORDINAL idxUserDataCol,  
      int eUserDataType,  
      int cbIndicator,  
      int cbUserData,  
      BYTE *pbUserDataTerm,  
      int cbUserDataTerm,  
      DBORDINAL idxServerCol);  

Observações

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

Se o utilizador escolher o modo interativo, este método é chamado duas vezes; uma vez para definir o formato da coluna de acordo com os valores padrão (que correspondem ao tipo da coluna do servidor), e outra para definir o formato de acordo com o tipo de coluna escolhida pelo cliente escolhido durante o modo interativo, para cada coluna.

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

O método BCPColFmt permite especificar o formato de ficheiro de utilizador para cópias em massa. Para cópias em massa, um formato contém as seguintes partes:

• Um mapeamento dos campos do ficheiro de utilizador para as colunas da base de dados.

• O tipo de dado de cada campo de ficheiro de utilizador.

• O comprimento do indicador opcional para cada campo.

• O comprimento máximo de dados por campo de ficheiro de utilizador.

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

• O comprimento da sequência opcional de bytes ^{terminais 1}.

Cada chamada ao BCPColFmt especifica o formato de um campo de ficheiro de utilizador. Por exemplo, para alterar as definições predefinidas de três campos num ficheiro de dados de utilizador com cinco campos, primeiro ligue BCPColumns(5), e depois ligue ao BCPColFmt cinco vezes, com três dessas chamadas a definir o seu formato personalizado. Para as duas chamadas restantes, defina o eUserDataType para BCP_TYPE_DEFAULT e defina cbIndicator, cbUserData e cbUserDataTerm para 0, BCP_VARIABLE_LENGTH e 0, respetivamente. Este procedimento copia as cinco colunas, três com o seu formato personalizado e duas com o formato padrão.

Não tens de copiar todos os dados de um ficheiro de utilizador para uma tabela SQL Server. Para saltar uma coluna, especifique o formato dos dados da coluna definindo o parâmetro idxServerCol para 0. Para saltar um campo, ainda precisa de toda a informação para que o método funcione corretamente.

A função IBCPSession::BCPWriteFmt pode ser usada para persistir a especificação de formato fornecida através do BCPColFmt.

Arguments

idxUserDataCol[in]
Índice do campo no ficheiro de dados do utilizador.

eUserDataType[in]
O tipo de dado do campo no ficheiro de dados do utilizador. Os tipos de dados disponíveis estão listados no ficheiro de cabeçalho do OLE DB DB Driver for SQL Server (msoledbsql.h) com formato BCP_TYPE_XXX, por exemplo, BCP_TYPE_SQLINT4. Se o valor BCP_TYPE_DEFAULT for especificado, o fornecedor tenta usar o mesmo tipo que o tipo de tabela ou coluna de vista. Para operações de cópia em massa a partir do SQL Server para um ficheiro quando o argumento eUserDataType está BCP_TYPE_SQLDECIMAL ou BCP_TYPE_SQLNUMERIC:

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

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

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 8 é mais comummente usado para indicar que o campo é fragmentado. Isto é usado para copiar em massa de forma eficiente colunas de grandes valores.

cbUserData[in]
O comprimento máximo, em bytes, dos dados deste campo no ficheiro de utilizador, sem incluir o comprimento de qualquer indicador de comprimento ou terminador.

Definir cbUserData para BCP_LENGTH_NULL indica que todos os valores nos campos do ficheiro de dados são, ou devem ser, definidos como NULL. Definir o cbUserData para BCP_LENGTH_VARIABLE indica que o sistema deve determinar o comprimento dos dados para cada campo. Para alguns campos, isto pode significar que um indicador de comprimento/nulo é gerado para preceder dados numa cópia do SQL Server, ou que o indicador é esperado nos dados copiados para o SQL Server.

Para tipos de caracteres e dados binários SQL Server, cbUserData pode ser BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0 ou algum valor positivo. Se o cbUserData estiver BCP_LENGTH_VARIABLE, o sistema utiliza o indicador de comprimento, se presente, ou uma sequência de terminadores para determinar o comprimento dos dados. Se forem fornecidos tanto um indicador de comprimento como uma sequência de terminadores, a cópia em massa utiliza aquela que resulta na menor quantidade de dados a ser copiada. Se cbUserData for BCP_LENGTH_VARIABLE, o tipo de dado é um carácter SQL Server ou tipo binário, e se não for especificado indicador de comprimento nem sequência de terminadores, o sistema devolve uma mensagem de erro.

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

O valor cbUserData 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 cbUserData representa o número de caracteres multiplicado pelo tamanho, em bytes, de cada carácter.

pbUserDataTerm[size_is][em]
A sequência de terminadores a ser usada para o campo. Este parâmetro é útil principalmente para tipos de dados de caracteres porque todos os outros tipos têm comprimento fixo ou, no caso de dados binários, requerem um indicador de comprimento para registar com precisão o número de bytes presentes.

Para evitar terminar dados extraídos, ou para indicar que os dados num ficheiro de utilizador não estão terminados, defina este parâmetro para NULL.

Se forem usados mais do que um meio para especificar o comprimento da coluna de um ficheiro de utilizador (como um terminador e um indicador de comprimento, ou um terminador e um comprimento máximo de coluna), a cópia em massa escolhe aquele que resulta na cópia da menor quantidade de dados.

A API de cópia em massa realiza a conversão de caracteres de Unicode para MBCS conforme necessário. Deve-se ter cuidado para garantir que tanto a cadeia de bytes do terminador como o comprimento da cadeia de bytes estão corretamente definidos. Consulte a secção de Observações acima para as limitações de codificação do UTF-8.

cbUserDataTerm[in]
O comprimento, em bytes, da sequência de terminadores a ser usada para a coluna. Se não houver terminador presente ou desejado nos dados, defina esse valor para 0. Consulte a secção de Observações acima para as limitações de codificação do UTF-8.

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

Valores do código de retorno

S_OK
O método teve sucesso.

E_FAIL
Ocorreu um erro específico do fornecedor; para informações detalhadas, utilize a interface ISQLServerErrorInfo .

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

E_INVALIDARG
O argumento era inválido.

E_OUTOFMEMORY
Erro de falta de memória.

Ver também

IBCPSession (OLE DB)
Realização de Operações de Cópia em Massa