Compartir a través de

  • Artículo

bcp_bind

Enlaza los datos de una variable de programa a una columna de tabla para la copia masiva en SQL Server.

Sintaxis

RETCODE bcp_bind (
        HDBC hdbc, 
        LPCBYTE pData,
        INT cbIndicator,
        DBINT cbData,
        LPCBYTE pTerm,
        INT cbTerm,
        INT eDataType,
        INT idxServerCol);

Argumentos

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

  • pData
    Es un puntero a los datos copiados. Si eDataType es SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR o SQLIMAGE, pData puede ser NULL. Un valor de pData NULL indica que los valores de datos largos se enviarán en fragmentos a SQL Server utilizando bcp_moretext. El usuario sólo debe establecer pData en NULL si la columna que corresponde al campo enlazado por el usuario es una columna BLOB; en caso contrario, bcp_bind producirá un error.

    Si en los datos hay indicadores, estos aparecen en la memoria directamente antes de los datos. En ese caso, el parámetro pData señala a la variable de indicador y la copia masiva utiliza el ancho del indicador, el parámetro cbIndicator, para direccionar correctamente los datos del usuario.

  • cbIndicator
    Es la longitud, en bytes, de un indicador de longitud o nulo para los datos de la columna. Los valores de longitud de indicador válidos son 0 (cuando no se utiliza ningún indicador), 1, 2, 4 u 8. Los indicadores aparecen en la memoria directamente antes de ningún dato. Por ejemplo, la siguiente definición de tipo de estructura se puede utilizar para insertar valores enteros en una tabla de SQL Server utilizando la copia masiva:

    typedef struct tagBCPBOUNDINT
    {
    int iIndicator;
    int Value;
    } BCPBOUNDINT;

    En el caso del ejemplo, el parámetro pData se establecería en la dirección de una instancia declarada de la estructura, la dirección del miembro de estructura iIndicator de BCPBOUNDINT. El parámetro cbIndicator se establecería en el tamaño de un entero (sizeof (int)), así como el parámetro cbData, que también se establecería en el tamaño de un entero (sizeof (int)). Para realizar una copia masiva de una fila en el servidor que contiene un valor NULL para la columna enlazada, el valor del miembro iIndicator de la instancia debe estar establecido en SQL_NULL_DATA.

  • cbData
    Es el número de bytes de datos de la variable de programa, sin incluir la longitud de ningún terminador o indicador de longitud o nulo.

    Si se establece cbData en SQL_NULL_DATA, significa que todas las filas copiadas en el servidor contienen un valor NULL para la columna.

    Si se establece cbData en SQL_VARLEN_DATA, indica que el sistema utilizará un terminador de cadena u otro método para determinar la longitud de los datos copiados.

    En el caso de los tipos de datos de longitud fija, como los enteros, el tipo de datos indica la longitud de los datos al sistema. Por consiguiente, para los tipos de datos de longitud fija, cbData puede ser sin ningún riesgo SQL_VARLEN_DATA o la longitud de los datos.

    Para los tipos de datos de caracteres y binarios de SQL Server, cbData puede ser SQL_VARLEN_DATA, SQL_NULL_DATA, algún valor positivo o 0. Si cbData es SQL_VARLEN_DATA, el sistema utiliza un indicador de longitud/nulo (si lo hay) o una secuencia de terminador para determinar la longitud de los datos. Si se proporciona ambos, el sistema utiliza el que hace que se copie una menor cantidad de datos. Si cbData es SQL_VARLEN_DATA, el tipo de datos de la columna es un tipo de carácter o 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 cbData es 0 o un valor positivo, el sistema utiliza cbData como longitud de los datos. Sin embargo, si además de un valor de cbData positivo, se proporciona un indicador de longitud o una secuencia de terminador, el sistema determina la longitud de los datos utilizando el método que haga que se copie la menor cantidad de datos.

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

  • pTerm
    Es un puntero al modelo de bytes que marca el fin de esta variable de programa, en caso de haberlo. Por ejemplo, las cadenas ANSI y MBCS de C suelen tener un terminador de 1 byte (\0).

    Si no hay ningún terminador para la variable, establezca pTerm en NULL.

    Puede utilizar una cadena vacía ("") para designar el terminador nulo de C como el terminador de la variable de programa. Dado que la cadena vacía terminada en NULL constituye un byte único (el propio byte del terminador), establezca cbTerm en 1. Por ejemplo, para indicar que la cadena de szName está terminada en NULL y que se debe utilizar el terminador para indicar la longitud:

    bcp_bind(hdbc, szName, 0,
   SQL_VARLEN_DATA, "", 1,
   SQLCHARACTER, 2)

    Una forma sin terminación de este ejemplo podría indicar que se copien 15 caracteres de la variable szName en la segunda columna de la tabla enlazada:

    bcp_bind(hdbc, szName, 0, 15, 
   NULL, 0, SQLCHARACTER, 2)

    La API de copia masiva realiza la conversión de caracteres Unicode a MBCS según sea necesario. Asegúrese de que tanto la cadena de bytes de terminador como la longitud de la cadena de bytes están correctamente establecidas. Por ejemplo, para indicar que la cadena de szName es una cadena de caracteres anchos Unicode que termina con el valor terminador nulo de Unicode:

    bcp_bind(hdbc, szName, 0, 
   SQL_VARLEN_DATA, L"",
   sizeof(WCHAR), SQLNCHAR, 2)

    Si la columna enlazada de SQL Server es de caracteres anchos, no se realiza ninguna conversión en bcp_sendrow. Si el tipo de caracteres de la columna de SQL Server es MBCS, la conversión de caracteres anchos a caracteres multibyte se realiza cuando los datos se envían a SQL Server.

  • cbTerm
    Es el número de bytes que hay en el terminador para la variable de programa, si existe. Si no hay ningún terminador para la variable, establezca cbTerm en 0.

  • eDataType
    Es el tipo de datos de C de la variable de programa. Los datos de la variable de programa se convierten al tipo de la columna de base de datos. Si este parámetro es 0, no se realiza ninguna conversión.

    El parámetro eDataType lo enumeran los tokens de tipo de datos de SQL Server en sqlncli.h, no los enumeradores de tipo de datos ODBC de C. Por ejemplo, puede especificar un entero de dos bytes, el tipo ODBC SQL_C_SHORT, utilizando el tipo SQLINT2 específico de SQL Server.

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

  • idxServerCol
    Es la posición ordinal de la columna en la tabla de base de datos en la que se copian los datos. La primera columna de una tabla es la columna 1. SQLColumns indica la posición ordinal de una columna.

Valores devueltos

SUCCEED o FAIL.

Notas

Utilice bcp_bind para copiar datos de una variable de programa en una tabla de SQL Server con rapidez y eficiencia.

Llame a bcp_init antes de llamar a esta o cualquier otra función de copia masiva. Al llamar a bcp_init, se establece la tabla de destino de SQL Server para la copia masiva. Cuando se llama a bcp_init para utilizarlo con bcp_bind y bcp_sendrow, el parámetro szDataFile de bcp_init, que indica el archivo de datos, se establece en NULL; el parámetro eDirection de bcp_init se establece en DB_IN.

Realice una llamada independiente a bcp_bind por cada columna de la tabla de SQL Server en la que desee hacer la copia. Una vez realizadas las llamadas necesarias a bcp_bind, llame a bcp_sendrow para enviar una fila de datos desde las variables de programa a SQL Server.

Cada vez que desee que SQL Server confirme las filas ya recibidas, llame a bcp_batch. Por ejemplo, llame una vez a bcp_batch por cada 1000 filas insertadas o en cualquier otro intervalo.

Cuando no haya más filas que insertar, llame a bcp_done. Si no lo hace, se producirá un error.

La configuración del parámetro de control, que se especifica con bcp_control, no tiene ningún efecto en las transferencias de filas de bcp_bind.

Si el pData de una columna está establecido en NULL porque su valor será proporcionado mediante llamadas a bcp_moretext, las columnas siguientes que tengan eDataType establecido en SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR o SQLIMAGE también se deben enlazar con pData establecido en NULL, y sus valores también deben ser proporcionados mediante llamadas a bcp_moretext.

Para los nuevos tipos de valores grandes, como varchar(max), varbinary(max) o nvarchar(max), puede utilizar SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY y SQLNCHAR como indicadores de tipo en el parámetro eDataType.

Si cbTerm no es 0, cualquier valor (1, 2, 4 u 8) será válido para el prefijo (cbIndicator). En esta situación, SQL Server Native Client buscará el terminador, calculará la longitud de los datos con respecto al terminador (i) y establecerá cbData en el valor más pequeño de i y el valor de prefijo.

Si cbTerm es 0 y cbIndicator (el prefijo) no es 0, cbIndicator debe ser 8. El prefijo de 8 bytes puede tomar los valores siguientes:

  • 0xFFFFFFFFFFFFFFFF significa un valor nulo para el campo.

  • 0xFFFFFFFFFFFFFFFE se trata como un valor de prefijo especial que se utiliza para enviar los datos en fragmentos al servidor de forma eficaz. El formato de los datos con este prefijo especial es el siguiente:

  • <PREFIJO_ESPECIAL> <0 o más FRAGMENTO_DATOS> <FRAGMENTO_CERO>, donde:

  • PREFIJO_ESPECIAL es 0xFFFFFFFFFFFFFFFE

  • FRAGMENTO_DATOS es un prefijo de 4 bytes que contiene la longitud del fragmento, seguido por los datos reales cuya longitud se especifica en el prefijo de 4 bytes.

  • FRAGMENTO_CERO es un valor de 4 bytes que contiene todos los ceros (00000000) que indican el fin de los datos.

  • Cualquier otra longitud válida de 8 bytes se tratará como una longitud de datos normal.

Si se llama a bcp_columns cuando se utiliza bcp_bind, se produce un error.

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

Para obtener información sobre los tipos utilizados con el parámetro eDataType 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).

Ejemplo

#include sql.h
#include sqlext.h
#include odbcss.h
// Variables like henv not specified.
HDBC      hdbc;
char         szCompanyName[MAXNAME];
DBINT      idCompany;
DBINT      nRowsProcessed;
DBBOOL      bMoreData;
char*      pTerm = "\t\t";

// Application initiation, get an ODBC environment handle, allocate the
// hdbc, and so on.
... 

// Enable bulk copy prior to connecting on allocated hdbc.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_BCP, (SQLPOINTER) SQL_BCP_ON,
   SQL_IS_INTEGER);

// Connect to the data source; return on error.
if (!SQL_SUCCEEDED(SQLConnect(hdbc, _T("myDSN"), SQL_NTS,
   _T("myUser"), SQL_NTS, _T("myPwd"), SQL_NTS)))
   {
   // Raise error and return.
   return;
   }

// Initialize bcp. 
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL
   DB_IN) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Bind program variables to table columns. 
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,
   SQLINT4, 1)    == FAIL)
   {
   // Raise error and return.
   return;
   }
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,
   (LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)
   {
   // Raise error and return.
   return;
   }

while (TRUE)
   {
   // Retrieve and process program data. 
   if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)
      {
      // Send the data. 
      if (bcp_sendrow(hdbc) == FAIL)
         {
         // Raise error and return.
         return;
         }
      }
   else
      {
      // Break out of loop.
      break;
      }
   }

// Terminate the bulk copy operation.
if ((nRowsProcessed = bcp_done(hdbc)) == -1)
   {
   printf_s("Bulk-copy unsuccessful.\n");
   return;
   }

printf_s("%ld rows copied.\n", nRowsProcessed);

Vea también

Referencia

Funciones de copia masiva