IBCPSession::BCPColFmt (OLE DB)

Crea un enlace entre variables de programa y columnas de SQL Server.

Sintaxis

  
HRESULT BCPColFmt(   
DBORDINALidxUserDataCol,  
inteUserDataType,  
intcbIndicator,  
intcbUserData,  
BYTE *pbUserDataTerm,  
intcbUserDataTerm,  
DBORDINALidxServerCol);  

Observaciones

El método BCPColFmt se usa para crear un enlace entre campos de archivo de datos BCP y columnas de SQL Server. Toma la longitud, el tipo, el terminador y la longitud del prefijo de una columna como parámetros y establece cada una de estas propiedades para campos individuales.

Si el usuario elige el modo interactivo, se llama a este método dos veces; una vez que se establece el formato de columna según los valores predeterminados (que son según el tipo de la columna de servidor) y una vez para establecer el formato según el tipo de columna de la elección del cliente elegido durante el modo interactivo, para cada columna.

En modos no interactivos, se llama solo una vez por columna para establecer el tipo de cada columna en carácter o tipo nativo, y para establecer los terminadores de columna y fila.

El método BCPColFmt permite especificar el formato de archivo de usuario para copias masivas. Para la copia masiva, un formato contiene las siguientes partes:

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

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

• Longitud del indicador opcional para cada campo.

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

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

• Longitud de la secuencia de bytes de terminación opcional.

Cada llamada a BCPColFmt especifica el formato de un campo de archivo de usuario. Por ejemplo, para cambiar la configuración predeterminada de tres campos en un archivo de datos de usuario de cinco campos, primero llame a y, a continuación, llame BCPColumns(5)a BCPColFmt cinco veces, con tres de esas llamadas estableciendo el formato personalizado. Para las dos llamadas restantes, establezca eUserDataType en BCP_TYPE_DEFAULT y establezca cbIndicator, cbUserData y cbUserDataTerm en 0, BCP_VARIABLE_LENGTH y 0 respectivamente. Este procedimiento copia las cinco columnas, tres con el formato personalizado y dos con el formato predeterminado.

No es necesario copiar todos los datos de un archivo de usuario en una tabla de SQL Server. Para omitir una columna, especifique el formato de los datos de la columna estableciendo el parámetro idxServerCol en 0. Para omitir un campo, todavía necesita toda la información para que el método funcione correctamente.

Nota La función IBCPSession::BCPWriteFmt se puede usar para conservar la especificación de formato proporcionada a través de BCPColFmt.

Argumentos

idxUserDataCol[in]
Índice de campo en el archivo de datos del usuario.

eUserDataType[in]
Tipo de datos del campo en el archivo de datos del usuario. Los tipos de datos disponibles se muestran en el archivo de encabezado de SQL Server Native Client (sqlncli.h) con formato BCP_TYPE_XXX, por ejemplo, BCP_TYPE_SQLINT4. Si se especifica el valor BCP_TYPE_DEFAULT, el proveedor intenta usar el mismo tipo que el tipo de columna de tabla o vista. Para las operaciones de copia masiva fuera de SQL Server y en un archivo cuando el eUserDataType argumento es BCP_TYPE_SQLDECIMAL o BCP_TYPE_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[in]
Longitud del prefijo para el campo. El valor predeterminado es BCP_PREFIX_DEFAULT. Las longitudes válidas para el prefijo son 0, 1, 2, 4 y 8. Normalmente se usa un tamaño de prefijo de 8 para indicar que el campo está fragmentado. Esto se usa para copiar de forma eficaz columnas de tipo de valor grande de forma masiva.

cbUserData[in]
Longitud máxima, en bytes, de los datos de este campo en el archivo de usuario, no incluida la longitud de ningún indicador o terminador de longitud.

Si se establece cbUserData en BCP_LENGTH_NULL indica que todos los valores de los campos del archivo de datos son o deben establecerse en NULL. Si se establece cbUserData en BCP_LENGTH_VARIABLE indica que el sistema debe determinar la longitud de los datos de cada campo. En algunos campos, 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 BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0 o algún valor positivo. Si cbUserData es BCP_LENGTH_VARIABLE, 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 BCP_LENGTH_VARIABLE, el tipo de datos es un carácter de SQL Server o un tipo binario y, si 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 longitud máxima de datos. Sin embargo, si, además de un positivo cbUserData, 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 cbUserData valor representa el recuento de bytes de datos. Si los datos de caracteres se representan mediante caracteres anchos Unicode, un valor de parámetro positivo cbUserData representa el número de caracteres multiplicados por el tamaño, en bytes, de cada carácter.

pbUserDataTerm[size_is][in]
Secuencia de terminador que se va a usar para el campo. 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[in]
Longitud, en bytes, de la secuencia de terminador que se va a usar para la columna. Si no hay ningún terminador presente o deseado en los datos, establezca este valor en 0.

idxServerCol[in]
Posición ordinal de la columna en la tabla de base de datos. El primer número de columna es 1. La posición ordinal de una columna se notifica mediante IColumnsInfo::GetColumnInfo o métodos similares. Si este valor es 0, la copia masiva omite el campo del archivo de datos.

Valores de código de retorno

S_OK
El método se realizó correctamente.

E_FAIL
Se produjo un error específico del proveedor para obtener información detallada sobre el uso de la interfaz ISQLServerErrorInfo .

E_UNEXPECTED
La llamada al método fue inesperada. Por ejemplo, no se llamó al método IBCPSession::BCPInit antes de llamar a este método.

E_INVALIDARG
El argumento no era válido.

E_MEMORIA_INSUFICIENTE
Error de memoria insuficiente.

Véase también

IBCPSession (OLE DB)
Realización de operaciones de copia masiva