bcp_colfmt

Sintaxis

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

Argumentos

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

• idxUserDataCol
  Es el número de columna ordinal del archivo de datos de usuario para el que se especifica el formato. La primera columna es 1.

• eUserDataType
  Es el tipo de datos de esta columna del archivo de usuario. Si es distinto del tipo de datos de la columna correspondiente en la tabla de base de datos (idxServerColumn), la copia masiva convierte los datos si es posible.

  SQL Server 2005 introdujo la compatibilidad con los tokens de tipo de datos SQLXML y SQLUDT del parámetro eUserDataType.

  Los tokens de tipo de datos de SQL Server en sqlncli.h enumeran el parámetro eUserDataType, no los enumeradores de tipos de datos C de ODBC. Por ejemplo, puede especificar una cadena de caracteres, tipo SQL_C_CHAR de ODBC, utilizando el tipo SQLCHARACTER específico 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 generar una salida de copia masiva de SQL Server en un archivo, cuando eUserDataType 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.

• cbIndicator
  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 u 8.

  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 la longitud de columna de un 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 una copia masiva cuando ninguna intervención de usuario ajusta el formato de los datos contienen indicadores cuando los datos de columna pueden variar de longitud o la columna puede aceptar valores NULL como valores.

• cbUserData
  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 de los terminadores.

  Establecer cbUserData en SQL_NULL_DATA indica que todos los valores de columna del archivo de datos son NULL o deben establecerse en NULL.

  Establecer cbUserData en SQL_VARLEN_DATA indica que el sistema debe determinar la longitud de datos de cada columna. Para algunas columnas, esto puede significar que se genera un indicador de longitud o nulo que precede a 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, cbUserData puede ser SQL_VARLEN_DATA, SQL_NULL_DATA, 0 o algún valor positivo. Si cbUserData 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 utiliza aquél por el que se copia la cantidad mínima de datos. Si cbUserData es SQL_VARLEN_DATA, el tipo de datos es un tipo de carácter o binario de SQL Server y no se especifica ni un indicador de longitud ni una secuencia de terminador, el sistema devuelve un mensaje de error.

  Si cbUserData es 0 o un valor positivo, el sistema utiliza cbUserData como longitud de datos máxima. Sin embargo, si además de un valor de cbUserData positivo, se proporciona un indicador de longitud o una secuencia de terminador, el sistema determina la longitud de los datos utilizando el método por el que se copia la cantidad mínima de datos.

  El valor de cbUserData representa el recuento de bytes de datos. Si los datos de caracteres se representan mediante caracteres anchos de Unicode, un valor del parámetro cbUserData positivo representa el número de caracteres multiplicado por el tamaño, en bytes, de cada carácter.

• pUserDataTerm
  Es la secuencia de terminador 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 registre 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 utiliza más de un medio de especificar una longitud de columna de archivo 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 establecen correctamente la cadena de bytes del terminador y la longitud de la cadena de bytes.

• cbUserDataTerm
  Es la longitud, en bytes, de la secuencia de terminador que se va a utilizar para esta columna. Si no hay ningún terminador presente o no se desea uno en los datos, establezca este valor en 0.

• idxServerCol
  Es la posición ordinal de la columna de la tabla de base de datos. El primer número de columna es 1. La posición ordinal de una columna se notifica mediante SQLColumns.

  Si este valor es 0, la copia masiva omite la columna en el archivo de datos.

Devuelve

SUCCEED o FAIL.

Notas

La función bcp_colfmt 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 de archivo de usuario.

• La longitud del indicador opcional para cada columna.

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

• La 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_colfmt 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_colfmt cinco veces, estableciendo con tres de esas llamadas el formato personalizado. Para las dos llamadas restantes, establezca eUserDataType en 0 y establezca cbIndicator, cbUserData y cbUserDataTerm en 0, SQL_VARLEN_DATA y 0, respectivamente. Este procedimiento copia las cinco columnas, tres con el formato personalizado y dos con el formato predeterminado.

Para cbIndicator, un valor de 8 para indicar un tipo de valor grande es válido ahora. Si se especifica el prefijo para un campo cuya columna correspondiente es un nuevo tipo max, sólo se puede establecer en 8. Para obtener información detallada, vea bcp_bind.

Se debe llamar a la función bcp_columns antes de realizar cualquier llamada a bcp_colfmt.

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

Llamar más de una vez a bcp_colfmt para cualquier columna del archivo de usuario produce un error.

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

Compatibilidad de bcp_colfmt con las características mejoradas de fecha y hora

Para obtener información sobre los tipos utilizados con el parámetro eUserDataType para los tipos de fecha y hora, vea 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