IBCPSession::BCPColFmt (OLE DB)

Sintaxis

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

Comentarios

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. Un formato de copia masiva incluye estos elementos:

• 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, 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, 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 a través de 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 de SQL Server Native Client (sqlncli.h) con el formato BCP_TYPE_XXX como, 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 Server o 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 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 que determina la longitud de los datos. Si se proporciona tanto un indicador de longitud como una secuencia de terminador, la copia masiva usará el que copie la mínima cantidad de datos de los dos. 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 usa cbUserData como la longitud de datos máxima. Sin embargo, si además de un valor 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 copia la mínima cantidad de datos.

  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 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 resulta muy útil sobre todo 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 no tener que terminar los datos extraídos o indicar que los datos de un archivo de usuario no están terminados, 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 el que copia la cantidad mínima de datos.

  La API de copia masiva realiza la conversión de caracteres de Unicode a MBCS que sea precisa. Deben extremarse 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 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 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 ejecutó correctamente.

• E_FAIL
  Se produjo un error específico del proveedor; para obtener información detallada, 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.

Vea también

Conceptos

Otros recursos