bcp_setcolfmt

Sintaxis

RETCODE bcp_setcolfmt (
        HDBC hdbc,
        INT field,
        INT property,
        void* pValue,
        INT cbValue);

Argumentos

• hdbc
  Es el identificador de la conexión ODBC habilitado para la copia masiva.

• field
  Es el número de columnas ordinal para el que se establece la propiedad.

• property
  Es una de las constantes de propiedad. Las constantes de propiedad se definen en esta tabla.

  Propiedad	Valor	Descripción
  BCP_FMT_TYPE	BYTE	Es el tipo de datos de esta columna del archivo de usuario. Si es distinto del tipo de datos de la columna correspondiente de la tabla de base de datos, la copia masiva convierte los datos si es posible. Los símbolos (token) de tipo de datos de SQL Server enumeran el parámetro BCP_FMT_TYPE en sqlncli.h, en lugar de los enumeradores de tipo de datos de ODBC C. Por ejemplo, puede especificar una cadena de caracteres, tipo SQL_C_CHAR de ODBC, utilizando el tipo específico SQLCHARACTER de SQL Server. Para especificar la representación de datos predeterminada para el tipo de datos de SQL Server, establezca este parámetro en 0. Para la salida de copia masiva de SQL Server en un archivo, cuando BCP_FMT_TYPE es SQLDECIMAL o SQLNUMERIC: Si la columna de origen no es decimal o numérica, se utilizan la precisión y escala predeterminadas. Si la columna de origen es decimal o numérica, se utilizan la precisión y escala de la columna de origen.
  BCP_FMT_INDICATOR_LEN	INT	Es la longitud en bytes del indicador (prefijo). Es la longitud, en bytes, de un indicador de longitud o nulo en los datos de columna. Los valores de longitud de indicador válidos son 0 (cuando no se utiliza ningún indicador), 1, 2 ó 4. Para especificar el uso del indicador de copia masiva predeterminado, establezca este parámetro en SQL_VARLEN_DATA. Los indicadores aparecen directamente en memoria antes de cualquier dato y en el archivo de datos directamente antes de los datos a los que se aplican. Si se utiliza más de un medio de especificar una longitud de columna del archivo de datos (como un indicador y una longitud máxima de columna o un indicador y una secuencia de terminador) , la copia masiva elige aquél por el que se copia la cantidad mínima de datos. Los archivos de datos generados mediante la copia masiva cuando ninguna intervención de usuario ajusta el formato de los datos contienen indicadores acerca de cuándo los datos de columna pueden variar en longitud o cuándo la columna puede aceptar como valores los valores NULL.
  BCP_FMT_DATA_LEN	DBINT	Es la longitud en bytes de los datos (longitud de columna). Es la longitud máxima, en bytes, de los datos de esta columna del archivo de usuario, sin incluir la longitud de los indicadores de longitud o terminadores. Establecer BCP_FMT_DATA_LEN en SQL_NULL_DATA indica que todos los valores de columna del archivo de datos son NULL o deben establecerse en NULL. Establecer BCP_FMT_DATA_LEN en SQL_VARLEN_DATA indica que el sistema debe determinar la longitud de los datos de cada columna. Para algunas columnas, esto podría significar que se genera un indicador de longitud/nulo para preceder los datos en una copia de SQL Server o que se espera el indicador en los datos copiados en SQL Server. Para los tipos de datos de caracteres y binarios de SQL Server, BCP_FMT_DATA_LEN puede ser SQL_VARLEN_DATA, SQL_NULL_DATA, algún valor positivo o 0. Si BCP_FMT_DATA_LEN es SQL_VARLEN_DATA, el sistema utiliza un indicador de longitud, si lo hay, o una secuencia de terminador para determinar la longitud de los datos. Si se proporciona un indicador de longitud y una secuencia de terminador, la copia masiva usa aquél por el que se copia la mínima cantidad de datos. Si BCP_FMT_DATA_LEN es SQL_VARLEN_DATA, el tipo de datos es carácter o binario de SQL Server y no se especifica un indicador de longitud ni una secuencia de terminador, el sistema devuelve un mensaje de error. Si BCP_FMT_DATA_LEN es 0 o un valor positivo, el sistema utiliza BCP_FMT_DATA_LEN como la longitud máxima de los datos. Sin embargo, si además de un valor de BCP_FMT_DATA_LEN positivo, se proporciona un indicador de longitud o una secuencia de terminador, el sistema determina la longitud de los datos mediante el método por el cuál se copia la mínima cantidad de datos. El valor de BCP_FMT_DATA_LEN representa el recuento de bytes de datos. Si los datos de caracteres se representan mediante caracteres anchos de Unicode, un valor del parámetro BCP_FMT_DATA_LEN positivo representa el número de caracteres multiplicado por el tamaño, en bytes, de cada carácter.
  BCP_FMT_TERMINATOR	LPCBYTE	Puntero a la secuencia de terminador (ANSI o Unicode según corresponda) que se va a utilizar para esta columna. Este parámetro es principalmente útil para los tipos de datos de caracteres porque todos los demás tipos son de longitud fija o, en el caso de los datos binarios, requieren un indicador de longitud que grabe con precisión el número de bytes presentes. Para evitar la terminación de los datos extraídos o indicar que no se terminen los datos de un archivo de usuario, establezca este parámetro en NULL. Si se usa más de un medio para especificar una longitud de columna de usuario (como un terminador y un indicador de longitud, o un terminador y una longitud máxima de columna), la copia masiva elige aquél por el que se copia la cantidad mínima de datos. La API de copia masiva realiza la conversión de caracteres Unicode a MBCS según sea necesario. Se deben extremar las precauciones para asegurarse de que se establece correctamente la cadena de bytes del terminador y la longitud de la cadena de bytes.
  BCP_FMT_SERVER_COL	INT	Posición ordinal de la columna en la base de datos.
  BCP_FMT_COLLATION	LPCSTR	Nombre de intercalación.

• pValue
  Es el puntero al valor que se va a asociar a la property. Permite establecer cada propiedad de formato de columna individualmente.

• cbvalue
  Es la longitud del búfer de propiedad en bytes.

Devuelve

SUCCEED o FAIL.

Comentarios

Esta función reemplaza la función bcp_colfmt. Toda la funcionalidad de bcp_colfmt se proporciona en la función bcp_setcolfmt. Además, también se proporciona compatibilidad con la intercalación de columna. Se recomienda que los atributos de formato de columna siguientes se establezcan en el orden proporcionado a continuación:

BCP_FMT_SERVER_COL

BCP_FMT_DATA_LEN

BCP_FMT_TYPE

La función bcp_setcolfmt le permite especificar el formato de archivo de usuario para las copias masivas. Para la copia masiva, un formato contiene los componentes siguientes:

• Una asignación de las columnas de archivo de usuario a las columnas de base de datos.

• El tipo de datos de cada columna del archivo de usuario.

• La longitud del indicador opcional para cada columna.

• La longitud máxima de los datos por columna de archivo de usuario.

• Secuencia de bytes de terminación opcional para cada columna.

• La longitud de la secuencia de bytes de terminación opcional.

Cada llamada a bcp_setcolfmt especifica el formato de una columna de archivo de usuario. Por ejemplo, para cambiar la configuración predeterminada de tres columnas de un archivo de datos de usuario de cinco columnas, primero llame a bcp_columns(5) y, a continuación, llame a bcp_setcolfmt cinco veces y con tres de esas llamadas establezca el formato personalizado. Para las dos llamadas restantes, establezca BCP_FMT_TYPE en 0 y establezca respectivamente BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN y cbValue en 0, SQL_VARLEN_DATA y 0. Este procedimiento copia las cinco columnas, tres con el formato personalizado y dos con el formato predeterminado.

Se debe llamar a la función bcp_columns antes de llamar a bcp_setcolfmt.

Debe llamar una vez a bcp_setcolfmt para cada propiedad de cada columna del archivo de usuario.

No tiene que copiar todos los datos de un archivo de usuario en la tabla de SQL Server. Para omitir una columna, especifique el formato de los datos de la columna, para ello establezca el parámetro BCP_FMT_SERVER_COL en 0. Si desea omitir una columna, debe especificar su tipo.

La función bcp_writefmt se puede utilizar para conservar la especificación de formato.

bcp_setcolfmt admite las características mejoradas de fecha y hora

Los tipos utilizados con la propiedad BCP_FMT_TYPE para los tipos de fecha y hora son los que se especifican en Cambios de copia masiva para tipos de fecha y hora mejorados (OLE DB y ODBC).

Para obtener más información, vea Mejoras en los tipos de datos de fecha y hora (ODBC).

Vea también

Referencia