bcp_colfmt

Especifica el formato de origen o destino de los datos en un archivo de usuario. Cuando se usa como formato de origen, bcp_colfmt especifica el formato de un archivo de datos existente utilizado como origen de datos en una copia masiva en una tabla de SQL Server. Cuando se usa como formato de destino, el archivo de datos se crea mediante los formatos de columna especificados con 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 habilitada 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 en el archivo de usuario. Si es diferente 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 compatibilidad con tokens de tipo de datos SQLXML y SQLUDT en el parámetro eUserDataType .

El parámetro eUserDataType se enumera mediante los tokens de tipo de datos de SQL Server en sqlncli.h, no los enumeradores de tipo de datos ODBC C. Por ejemplo, puede especificar una cadena de caracteres, un tipo ODBC SQL_C_CHAR, mediante el tipo específico de SQL Server SQLCHARACTER.

Para especificar la representación de datos predeterminada para el tipo de datos de SQL Server, establezca este parámetro en 0.

Para una 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 usan la precisión y la escala predeterminadas.

• Si la columna de origen es decimal o numérica, se usa la precisión y la escala de la columna de origen.

cbIndicator
Es la longitud, en bytes, de un indicador length/null dentro de los datos de columna. Los valores válidos de longitud del indicador son 0 (cuando no se usa ningún indicador), 1, 2, 4 o 8.

Para especificar el uso predeterminado del indicador de copia masiva, establezca este parámetro en SQL_VARLEN_DATA.

Los indicadores aparecen en memoria directamente antes de cualquier dato y en el archivo de datos directamente antes de los datos a los que se aplican.

Si se usa más de un medio para especificar una longitud de columna de 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 la que da como resultado la menor cantidad de datos que se copian.

Los archivos de datos generados por copia masiva cuando ninguna intervención del usuario ajusta el formato de los datos contienen indicadores cuando los datos de columna pueden variar en longitud o la columna puede aceptar NULL como valor.

cbUserData
Es la longitud máxima, en bytes, de los datos de esta columna en el archivo de usuario, sin incluir la longitud de ningún indicador o terminador de longitud.

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

Al establecer cbUserData en SQL_VARLEN_DATA se indica que el sistema debe determinar la longitud de los datos de cada columna. En algunas columnas, esto podría significar que se genera un indicador de longitud/null para preceder a los datos de una copia de SQL Server o que el indicador se espera en los datos copiados en SQL Server.

En el caso de los tipos de datos binarios y caracteres 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 usa el indicador de longitud, si está presente, 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 la que da como resultado la menor cantidad de datos que se copian. Si cbUserData es SQL_VARLEN_DATA, el tipo de datos es un carácter de SQL Server o un tipo binario, y no se especifica 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 usa cbUserData como la longitud máxima de los datos. Sin embargo, si, además de un cbUserData positivo, se proporciona un indicador de longitud o una secuencia de terminador, el sistema determina la longitud de los datos mediante el método que da como resultado la menor cantidad de datos que se copian.

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

pUserDataTerm
Es la secuencia de terminador que se va a usar para esta columna. Este parámetro es útil principalmente 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 para registrar con precisión el número de bytes presentes.

Para evitar la terminación de los datos extraídos o para indicar que no se han terminado 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 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 la que da como resultado la menor cantidad de datos que se copian.

La API de copia masiva realiza la conversión de caracteres Unicode a MBCS según sea necesario. Se debe tener cuidado para asegurarse de que la cadena de bytes del terminador y la longitud de la cadena de bytes se establecen correctamente.

cbUserDataTerm
Es la longitud, en bytes, de la secuencia de terminador que se va a usar para esta columna. Si no hay ningún terminador presente o deseado 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. SQLColumns notifica la posición ordinal de una columna.

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

Devoluciones

SUCCEED o FAIL.

Observaciones

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

• Asignación de columnas de archivo de usuario a columnas de base de datos.

• Tipo de datos de cada columna de archivo de usuario.

• Longitud del indicador opcional para cada columna.

• Longitud máxima de datos por columna de archivo de usuario.

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

• 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 en 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, con tres de esas llamadas estableciendo 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, ahora es válido un valor de 8 para indicar que un tipo de valor grande es válido. Si se especifica el prefijo para un campo cuya columna correspondiente es un nuevo tipo máximo, solo se puede establecer en 8. Para obtener más información, consulte bcp_bind.

Se debe llamar a la función bcp_columns antes de que las llamadas a bcp_colfmt.

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

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

No es necesario 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, estableciendo el parámetro idxServerCol en 0. Si desea omitir una columna, debe especificar su tipo.

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

bcp_colfmt compatibilidad con características mejoradas de fecha y hora

Para obtener información sobre los tipos que usa con el parámetro eUserDataType para los tipos de fecha y hora, vea Cambios de copia masiva para tipos mejorados de fecha y hora (OLE DB y ODBC).

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

Véase también

Funciones de copia masiva