bcp_colfmt

Especifica o formato de origem ou destino dos dados em um arquivo de usuário. Quando usado como um formato de origem, bcp_colfmt especifica o formato de um arquivo de dados existente usado como a fonte de dados em uma cópia em massa para uma tabela do SQL Server. Quando usado como um formato de destino, o arquivo de dados é criado usando os formatos de coluna especificados com bcp_colfmt.

Sintaxe

  
RETCODE bcp_colfmt (  
HDBC   
hdbc  
,  
INT  
idxUserDataCol  
,  
BYTE   
eUserDataType  
,  
INT   
cbIndicator  
,  
DBINT   
cbUserData  
,  
LPCBYTE   
pUserDataTerm  
,  
INT   
cbUserDataTerm  
,  
INT   
idxServerCol  
);  
  

Argumentos

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

idxUserDataCol
É o número da coluna ordinal no arquivo de dados do usuário para o qual o formato está sendo especificado. A primeira coluna é 1.

eUserDataType
É o tipo de dados desta coluna no arquivo de usuário. Se diferente do tipo de dados da coluna correspondente na tabela de banco de dados (idxServerColumn), a cópia em massa converterá os dados, se possível.

O SQL Server 2005 introduziu suporte para tokens de tipo de dados SQLXML e SQLUDT no parâmetro eUserDataType .

O parâmetro eUserDataType é 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 uma cadeia de caracteres, tipo ODBC SQL_C_CHAR, usando o SQL Server tipo específico SQLCHARACTER.

Para especificar a representação de dados padrão para o tipo de dados do SQL Server, defina esse parâmetro como 0.

Para uma cópia em massa do SQL Server em um arquivo, quando eUserDataType for SQLDECIMAL ou 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
É o comprimento, em bytes, de um indicador de comprimento/nulo dentro dos dados da coluna. Os valores de comprimento de indicador válidos são 0 (quando nenhum indicador é usado), 1, 2, 4 ou 8.

Para especificar o uso padrão do indicador de cópia em massa, defina esse parâmetro como SQL_VARLEN_DATA.

Os indicadores aparecem na memória diretamente antes de qualquer dado e no arquivo de dados diretamente antes dos dados aos quais eles se aplicam.

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

Os arquivos de dados gerados pela cópia em massa quando nenhuma intervenção do usuário ajusta o formato dos dados contêm indicadores quando os dados da coluna podem variar de comprimento ou a coluna pode aceitar NULL como um valor.

cbUserData
É o comprimento máximo, em bytes, dos dados desta coluna no arquivo de usuário, não incluindo o comprimento de qualquer indicador de comprimento ou terminador.

Definir cbUserData como SQL_NULL_DATA indica que todos os valores na coluna do arquivo de dados estão ou devem ser definidos como NULL.

Definir cbUserData como SQL_VARLEN_DATA indica que o sistema deve determinar o comprimento dos dados em cada coluna. Para algumas colunas, 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 dados binários e de caracteres do SQL Server, cbUserData pode ser SQL_VARLEN_DATA, SQL_NULL_DATA, 0 ou algum valor positivo. Se cbUserData for SQL_VARLEN_DATA, 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 SQL_VARLEN_DATA, o tipo de dados será um caractere do SQL Server ou um tipo binário e nem um indicador de comprimento nem uma sequência de terminador serão especificados, o sistema retornará uma mensagem de erro.

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

pUserDataTerm
É a sequência do terminador a ser usada para esta coluna. 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
É o comprimento, em bytes, da sequência do terminador a ser usada para esta coluna. Se nenhum terminador estiver presente ou desejado nos dados, defina esse valor como 0.

idxServerCol
É 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 SQLColumns.

Se esse valor for 0, a cópia em massa ignorará a coluna no arquivo de dados.

Devoluções

SUCCEED ou FAIL.

Observações

A função bcp_colfmt 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 colunas de arquivo de usuário para colunas de banco de dados.

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

• O comprimento do indicador opcional para cada coluna.

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

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

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

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

Para cbIndicator, um valor de 8 para indicar um tipo de valor grande agora é válido. Se o prefixo for especificado para um campo cuja coluna correspondente é um novo tipo máximo, ele só poderá ser definido como 8. Para obter detalhes, consulte bcp_bind.

A função bcp_columns deve ser chamada antes de qualquer chamada para bcp_colfmt.

Você deve chamar bcp_colfmt uma vez para cada coluna no arquivo de usuário.

Chamar bcp_colfmt mais de uma vez para qualquer coluna de arquivo de usuário causa um erro.

Você não precisa copiar todos os dados em um arquivo de usuário para a tabela do SQL Server. Para ignorar uma coluna, especifique o formato dos dados da coluna, definindo o parâmetro idxServerCol como 0. Se quiser ignorar uma coluna, especifique seu tipo.

A função bcp_writefmt pode ser usada para persistir a especificação de formato.

suporte bcp_colfmt para recursos avançados de data e hora

Para obter informações sobre os tipos usados com o parâmetro eUserDataType para tipos de data/hora, consulte Alterações de cópia em massa para tipos avançados de data e hora (OLE DB e ODBC).

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

Consulte Também

Funções de cópia em massa