IBCPSession::BCPColFmt (proveedor OLE DB de Native Client)

Artículo
01/10/2024

Se aplica a:SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

Importante

SQL Server Native Client (a menudo abreviado SNAC) se ha quitado de SQL Server 2022 (16.x) y SQL Server Management Studio 19 (SSMS). Para nuevos trabajos de desarrollo, no se recomiendan ni el proveedor OLE DB de SQL Server Native Client (SQLNCLI o SQLNCLI11) ni el proveedor OLE DB de Microsoft para SQL Server (SQLOLEDB) heredado. Cambie al nuevo Controlador Microsoft OLE DB para SQL Server de ahora en adelante.

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

Sintaxis

  
HRESULT BCPColFmt(   
      DBORDINAL idxUserDataCol,  
      int eUserDataType,  
      int cbIndicator,  
      int cbUserData,  
      BYTE *pbUserDataTerm,  
      int cbUserDataTerm,  
      DBORDINAL idxServerCol);

Observaciones

El método BCPColFmt se usa para crear un enlace entre los campos de archivo de datos BCP y las columnas de SQL Server. Toma como parámetros la longitud, el tipo, el terminador y la longitud de prefijo de una columna 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 para establecer el formato de columna en función de los valores predeterminados (según el tipo de columna de servidor) y otra para establecer el formato en función del tipo de columna elegido por el cliente durante el modo interactivo para cada columna.

En modos no interactivos, se llama a este método una sola vez por columna para establecer el tipo de cada columna en el tipo de caracteres 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 las copias masivas. Para la copia masiva, un formato contiene los componentes siguientes:

Una asignación de los campos de archivo de usuario a las columnas de base de datos.
El tipo de datos de cada campo de archivo de usuario.
La longitud del indicador opcional para cada campo.
La longitud máxima de los datos por campo de archivo de usuario.
La secuencia de bytes de terminación opcional para cada campo.
La longitud de la secuencia de bytes de terminación opcional.

En cada llamada a BCPColFmt se especifica el formato para 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 debe llamar a BCPColumns(5)y, a continuación, debe llamar a BCPColFmt cinco veces, con tres de cuyas llamadas establecerá el formato personalizado. Para las dos llamadas restantes, establezca eUserDataType en BCP_TYPE_DEFAULT y establezca cbIndicator, cbUserDatay 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.

Nota

Es necesario llamar al método IBCPSession::BCPColumns antes de realizar cualquier llamada a BCPColFmt. Debe llamar a BCPColFmt una vez para cada columna del archivo de usuario. Si llama más de una vez a BCPColFmt para cualquier columna de archivo de usuario, se generará un error.

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

Nota La función IBCPSession::BCPWriteFmt puede usarse para conservar la especificación de formato que se proporciona mediante BCPColFmt.

Argumentos

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

eUserDataType[in]
Tipo de datos de campo del archivo de datos del usuario. Los tipos de datos disponibles se muestran en el archivo de encabezado 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 operaciones de copia masiva fuera de SQL Server y en un archivo, cuando el argumento eUserDataType sea BCP_TYPE_SQLDECIMAL o BCP_TYPE_SQLNUMERIC:

Si la columna de origen no es decimal o numérica, se usarán la precisión y la escala predeterminadas.
Si la columna de origen es decimal o numérica, se usarán la precisión y la escala de la columna de origen.

cbIndicator[in]
Longitud de prefijo del campo. El valor predeterminado es BCP_PREFIX_DEFAULT. Las longitudes válidas para el prefijo son 0, 1, 2, 4 y 8. Un prefijo de tamaño 8 se usa normalmente para indicar que el campo está fragmentado. Se usa para realizar copias masivas de columnas de tipo de valor grande de forma eficaz.

cbUserData[in]
Longitud máxima (en bytes) de los datos de este campo del archivo de usuario, sin incluir la longitud de los indicadores de longitud o terminadores.

Al establecer cbUserData en BCP_LENGTH_NULL se indica que todos los valores de los campos del archivo de datos están, o debería estar, establecidos en NULL. Al establecer cbUserData en BCP_LENGTH_VARIABLE se indica que el sistema debería determinar la longitud de datos para cada campo. Para algunos campos, esto podría significar que se genera un indicador de longitud o NULL que precede a los datos en una copia de SQL Servero que se espera el indicador en los datos copiados en SQL Server.

Para el carácter y los tipos de datos binarios de SQL Server, cbUserData puede ser BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0 o un valor positivo. Si cbUserData es BCP_LENGTH_VARIABLE, el sistema usa el indicador de longitud, si está presente, o una secuencia de terminador que determina 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 cbUserData es BCP_LENGTH_VARIABLE, el tipo de datos es un carácter o un tipo 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 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 cbUserDatapositivo, 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.

pbUserDataTerm[size_is][in]
Secuencia de terminador que se va a usar para el campo. 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.

cbUserDataTerm[in]
Longitud (en bytes) de la secuencia de terminador que va a usarse para la columna. Si no hay ningún terminador presente o no se desea uno 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 la notifica el método IColumnsInfo::GetColumnInfo u otros métodos similares. Si este valor es 0, la copia masiva omite el campo en el archivo de datos.

Valores de código de retorno

S_OK
El método se ha llevado a cabo de forma correcta.

E_FAIL
Se ha producido un error específico del proveedor; para obtener más información, use la interfaz ISQLServerErrorInfo.

E_UNEXPECTED
No se esperaba la llamada al método. 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_OUTOFMEMORY
Error de memoria insuficiente.

Consulte también

IBCPSession (OLE DB)
Realizar operaciones de copia masiva

Share via