bcp_setcolfmt
A função bcp_setcolfmt substitui o bcp_colfmt. Ao especificar o agrupamento de coluna, a função bcp_setcolfmt precisa ser usada.
Essa função oferece uma abordagem flexível à especificação do formato de coluna em uma operação de cópia em massa. Ela é usada para definir atributos de formato de coluna individuais. Cada chamada para bcp_setcolfmt define um atributo de formato de coluna.
A função bcp_setcolfmt especifica o formato de origem ou destino dos dados em um arquivo de usuário. Quando usada como formato de origem, bcp_setcolfmt especifica o formato de um arquivo de dados existente usado como 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_setcolfmt.
Sintaxe
RETCODE bcp_setcolfmt (
HDBC hdbc,
INT field,
INT property,
void* pValue,
INT cbValue);
Argumentos
hdbc
É o identificador de conexão ODBC habilitado para cópia em massa.field
É o número de coluna ordinal para o qual a propriedade está sendo definida.property
É um das constantes de propriedade. As constantes de propriedade são definidas nesta tabela.Propriedade
Valor
Descrição
BCP_FMT_TYPE
BYTE
É o tipo de dados desta coluna no arquivo de usuário. Se for diferente do tipo de dados da coluna correspondente na tabela do banco de dados, a cópia em massa converterá os dados se possível.
O parâmetro BCP_FMT_TYPE é enumerado pelos tokens de tipo de dados do SQL Server em sqlncli.h, e não nos enumeradores de tipo de dados ODBC C. Por exemplo, você pode especificar uma cadeia de caracteres, o tipo ODBC SQL_C_CHAR, usando o tipo SQLCHARACTER específico do SQL Server.
Para especificar a representação de dados padrão do tipo de dados do SQL Server, defina esse parâmetro como 0.
Para uma cópia em massa do SQL Server para um arquivo, quando BCP_FMT_TYPE for SQLDECIMAL ou SQLNUMERIC:
Se a coluna de origem não for decimal ou numeric, serão usadas a precisão e escala padrão.
Se a coluna de origem não for decimal ou numeric, serão usadas a precisão e escala da coluna de origem.
BCP_FMT_INDICATOR_LEN
INT
É o comprimento em bytes do indicador (prefixo).
É o comprimento, em bytes, de um indicador de comprimento/nulo nos dados de coluna. Os valores de comprimento de indicador válidos são 0 (quando nenhum indicador é usado), 1, 2 ou 4.
Para especificar o uso do indicador de cópia em massa padrão, defina esse parâmetro como SQL_VARLEN_DATA.
Os indicadores aparecem na memória diretamente antes de quaisquer dados, e no arquivo de dados diretamente antes dos dados aos quais se aplicam.
Se for usada mais de uma maneira de especificar um comprimento de coluna de arquivo de dados (como um indicador e um comprimento de coluna máximo ou um indicador e uma seqüência de terminador), a cópia em massa escolherá aquela que resultar na menor quantidade de dados sendo copiados.
Os arquivos de dados gerados pela cópia em massa quando nenhuma intervenção de usuário ajusta o formato dos dados contêm indicadores quando os dados de coluna podem variar em comprimento ou a coluna pode aceitar NULL como valor.
BCP_FMT_DATA_LEN
DBINT
É o comprimento em bytes dos dados (comprimento da coluna).
É o comprimento máximo, em bytes, dos dados dessa coluna no arquivo de usuário, sem incluir o comprimento de qualquer indicador de comprimento ou terminador.
A definição de BCP_FMT_DATA_LEN como SQL_NULL_DATA indica que todos os valores na coluna de arquivo de dados são, ou deveriam ser, definidos como NULL.
A definição de BCP_FMT_DATA_LEN como SQL_VARLEN_DATA indica que o sistema deveria determinar o comprimento dos dados em cada coluna. Para algumas colunas, isso poderia significar que um indicador de comprimento/nulo é gerado para anteceder os dados em uma cópia do SQL Server ou que o indicador é esperado nos dados copiados para o SQL Server.
Para tipos de dados binários e de caractere do SQL Server, BCP_FMT_DATA_LEN pode ser SQL_VARLEN_DATA, SQL_NULL_DATA, 0 ou algum valor positivo. Se BCP_FMT_DATA_LEN for SQL_VARLEN_DATA, o sistema usará o indicador de comprimento, se estiver presente, ou uma seqüência de terminador para determinar o comprimento dos dados. Se forem fornecidos um indicador de comprimento e uma seqüência de terminador, a cópia em massa usará aquele que resultar na menor quantidade de dados sendo copiados. Se BCP_FMT_DATA_LEN for SQL_VARLEN_DATA, o tipo de dados for um tipo binário ou de caractere do SQL Server e nem um indicador de comprimento nem uma seqüência de terminador for especificado, o sistema retornará uma mensagem de erro.
Se BCP_FMT_DATA_LEN for 0 ou um valor positivo, o sistema usará BCP_FMT_DATA_LEN como o comprimento de dados máximo. Entretanto, se, além de um BCP_FMT_DATA_LEN 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 resultar na menor quantidade de dados sendo copiados.
O valor BCP_FMT_DATA_LEN representa a contagem de bytes dos dados. Se os dados de caractere forem representados por caracteres que abranjam Unicode, um valor de parâmetro BCP_FMT_DATA_LEN positivo representará a quantidade de caracteres multiplicada pelo tamanho, em bytes, de cada caractere.
BCP_FMT_TERMINATOR
LPCBYTE
Ponteiro para a seqüência de terminador (ANSI ou Unicode, conforme apropriado) a ser usado para esta coluna. Este parâmetro é útil principalmente para tipos de dados character porque todos os outros tipos têm comprimento fixo ou, no caso de dados binary, exigem um indicador de comprimento que permite registrar com precisão o número de bytes presentes.
Para evitar encerrar os dados extraídos ou indicar que os dados em um arquivo de usuário não foram encerrados, defina este parâmetro como NULL.
Se for usada mais de uma maneira de especificar um comprimento de coluna de arquivo de usuário (como um terminador e um indicador de comprimento ou um terminador e um comprimento de coluna máximo), a cópia em massa escolherá aquela que resultar 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 tomar cuidado para garantir que tanto a cadeia de caracteres de bytes do terminador quanto o comprimento da cadeia de caracteres de bytes estejam definidos corretamente.
BCP_FMT_SERVER_COL
INT
Posição ordinal da coluna no banco de dados
BCP_FMT_COLLATION
LPCSTR
Nome do agrupamento.
pValue
É o ponteiro para o valor que será associado a property. Ele permite que cada propriedade de formato de coluna seja definida individualmente.cbvalue
É o comprimento do buffer da propriedade em bytes.
Retorna
SUCCEED ou FAIL.
Comentários
Esta função substitui a função bcp_colfmt. É oferecida toda a funcionalidade de bcp_colfmt na função bcp_setcolfmt. Além disso, também há suporte ao agrupamento de coluna. É recomendável que os atributos de formato de coluna a seguir sejam definidos nesta ordem:
BCP_FMT_SERVER_COL
BCP_FMT_DATA_LEN
BCP_FMT_TYPE
A função bcp_setcolfmt permite especificar o formato do 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 do arquivo de usuário para colunas de banco de dados.
O tipo de dados de cada coluna do arquivo de usuário.
O comprimento do indicador opcional para cada coluna.
O comprimento máximo dos dados por coluna do arquivo de usuário.
A seqüência de bytes de encerramento opcional para cada coluna.
O comprimento da seqüência de bytes de encerramento opcional.
Cada chamada para bcp_setcolfmt especifica o formato para uma coluna do arquivo de usuário. Por exemplo, para alterar as configurações padrão para três colunas em um arquivo de dados de usuário de cinco colunas, primeiro chame bcp_columns(5) e bcp_setcolfmt cinco vezes, sendo três dessas chamadas para definir o seu formato personalizado. Para as duas chamadas restantes, defina BCP_FMT_TYPE como 0 e defina BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN e cbValue como 0, SQL_VARLEN_DATA e 0, respectivamente. Esse procedimento copia todas as cinco colunas, três com o seu formato personalizado e duas com o formato padrão.
A função bcp_columns deve ser chamada antes de chamar bcp_setcolfmt.
Você deve chamar bcp_setcolfmt uma vez para cada propriedade de cada coluna no arquivo de usuário.
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 para a coluna, definindo o parâmetro BCP_FMT_SERVER_COL como 0. Se desejar ignorar uma coluna, especifique seu tipo.
A função bcp_writefmt pode ser usada para persistir a especificação de formato.
Suporte do bcp_setcolfmt a recursos aprimorados de data e hora
Os tipos usados com a propriedade BCP_FMT_TYPE para tipos de data/hora são como especificados em 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).