bcp_bind

Artículo
07/04/2024

Se aplica a: SQL Server Azure SQL Database Azure SQL Instancia administrada Azure Synapse Analytics Analytics Platform System (PDW)

Enlaza 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 habilitada 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 pData NULL indica que los valores de datos largos se enviarán a SQL Server en fragmentos mediante bcp_moretext. El usuario solo debe establecer pData en NULL si la columna correspondiente al campo enlazado por el usuario es una columna BLOB; de lo contrario , se producirá un error bcp_bind .

Si en los datos hay indicadores, estos aparecen en la memoria directamente antes de los datos. El parámetro pData apunta a la variable de indicador en este caso, y el ancho del indicador, el parámetro cbIndicator , se usa mediante copia masiva para abordar los datos del usuario correctamente.

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 podría usarse para insertar valores enteros en una tabla de SQL Server mediante la copia masiva:

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

En el caso de 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 BCPBOUNDINT. El parámetro cbIndicator se establecería en el tamaño de un entero (sizeof(int)) y el parámetro cbData volvería a establecerse en el tamaño de un entero (sizeof(int)). Para copiar de forma masiva una fila en el servidor que contiene un valor NULL para la columna enlazada, el valor del miembro iIndicator de la instancia debe establecerse 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.

Al establecer cbData en SQL_NULL_DATA significa que todas las filas copiadas en el servidor contienen un valor NULL para la columna.

Si establece cbData en SQL_VARLEN_DATA indica que el sistema usará 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 lo tanto, para los tipos de datos de longitud fija, cbData puede ser SQL_VARLEN_DATA o la longitud de los datos.

En el caso de los tipos de datos binarios y caracteres 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 usa un indicador de longitud/null (si está presente) 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 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 cbData es 0 o un valor positivo, el sistema usa cbData como longitud de datos. Sin embargo, si, además de un valor cbData 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 del parámetro cbData representa el recuento de bytes de datos. Si los datos de caracteres se representan mediante caracteres anchos Unicode, un valor de parámetro cbData positivo representa el número de caracteres multiplicados 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 solo byte (el propio byte terminador), establezca cbTerm en 1. Por ejemplo, para indicar que la cadena de szName está terminada en null y que el terminador debe usarse para indicar la longitud:

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

Una forma noterminada de este ejemplo podría indicar que se copiarán 15 caracteres de la variable szName a 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, terminada por el valor del terminador NULL Unicode:

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

Si la columna de SQL Server enlazada tiene un carácter ancho, no se realiza ninguna conversión en bcp_sendrow. Si la columna de SQL Server es un tipo de carácter MBCS, la conversión de caracteres anchos a caracteres multibyte se realiza a medida que 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 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 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 un entero de dos bytes, SQL_C_SHORT de tipo ODBC, mediante el tipo específico de SQL Server SQLINT2.

SQL Server 2005 (9.x) introdujo compatibilidad con tokens de tipo de datos SQLXML y SQLUDT en el parámetro eDataType.

En esta tabla se muestran los tipos de datos enumerados válidos y los tipos de datos ODBC C correspondientes.

eDataType	Tipo de C
SQLTEXT	char *
SQLNTEXT	wchar_t *
SQLCHARACTER	char *
SQLBIGCHAR	char *
SQLVARCHAR	char *
SQLBIGVARCHAR	char *
SQLNCHAR	wchar_t *
SQLNVARCHAR	wchar_t *
SQLBINARY	unsigned char *
SQLBIGBINARY	unsigned char *
SQLVARBINARY	unsigned char *
SQLBIGVARBINARY	unsigned char *
SQLBIT	char
SQLBITN	char
SQLINT1	char
SQLINT2	short int
SQLINT4	int
SQLINT8	_int64
SQLINTN	cbIndicator 1: SQLINT1 2: SQLINT2 4: SQLINT4 8: SQLINT8
SQLFLT4	flotante
SQLFLT8	flotante
SQLFLTN	cbIndicator 4: SQLFLT4 8: SQLFLT8
SQLDECIMALN	SQL_NUMERIC_STRUCT
SQLNUMERICN	SQL_NUMERIC_STRUCT
SQLMONEY	DBMONEY
SQLMONEY4	DBMONEY4
SQLMONEYN	cbIndicator 4: SQLMONEY4 8: SQLMONEY
SQLTIMEN	SQL_SS_TIME2_STRUCT
SQLDATEN	SQL_DATE_STRUCT
SQLDATETIM4	DBDATETIM4
SQLDATETIME	DBDATETIME
SQLDATETIMN	cbIndicator 4: SQLDATETIM4 8: SQLDATETIME
SQLDATETIME2N	SQL_TIMESTAMP_STRUCT
SQLDATETIMEOFFSETN	SQL_SS_TIMESTAMPOFFSET_STRUCT
SQLIMAGE	unsigned char *
SQLUDT	unsigned char *
SQLUNIQUEID	SQLGUID
SQLVARIANT	Cualquier tipo de datos excepto: -Mensaje de texto - ntext -imagen - varchar(max) - varbinary(max) - nvarchar(max) - xml - timestamp
SQLXML	Tipos de datos C admitidos: - char* - wchar_t * - unsigned char *

idxServerCol Es la posición ordinal de la columna de la tabla de base de datos a la que se copian los datos. La primera columna de una tabla es la columna 1. La posición ordinal de una columna se notifica mediante SQLColumns.

Devoluciones

SUCCEED o FAIL.

Comentarios

Use bcp_bind para una manera rápida y eficaz de copiar datos de una variable de programa en una tabla de SQL Server.

Llame a bcp_init antes de llamar a esta o a 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. Al llamar a bcp_init para su uso con bcp_bind y bcp_sendrow, bcp_init el parámetro s szDataFile, que indica el archivo de datos, se establece en NULL; el parámetro bcp_initeDirection se establece en DB_IN.

Realice una llamada de bcp_bind independiente para cada columna de la tabla de SQL Server en la que desea copiar. Una vez realizadas las llamadas bcp_bind necesarias, llame a bcp_sendrow para enviar una fila de datos de las variables de programa a SQL Server. No se permite volver a enlazar una columna.

Siempre que quiera que SQL Server confirme las filas que ya se han recibido, llame a bcp_batch. Por ejemplo, llame a bcp_batch una vez por cada 1000 filas insertadas o en cualquier otro intervalo.

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

La configuración del parámetro de control, especificada con bcp_control, no tiene ningún efecto en las transferencias de fila bcp_bind .

Si pData para una columna se establece en NULL porque su valor se proporcionará mediante llamadas a bcp_moretext, las columnas posteriores con eDataType establecidas en SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR o SQLIMAGE también deben enlazarse con pData establecido en NULL y sus valores también deben proporcionarse mediante llamadas a bcp_moretext.

Para los nuevos tipos de valor grande, como varchar(max), varbinary(max)o nvarchar(max), puede usar 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 o 8) es 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 siguientes valores:

0xFFFFFFFFFFFFFFFF significa un valor nulo para el campo.
0xFFFFFFFFFFFFFFFE se trata como un valor de prefijo especial, que se usa para enviar datos de forma eficaz en fragmentos al servidor. El formato de los datos con este prefijo especial es el siguiente:
<><SPECIAL_PREFIX 0 o más fragmentos<>de datos ZERO_CHUNK> donde:
PREFIJO_ESPECIAL es 0xFFFFFFFFFFFFFFFE
DATA_CHUNK es un prefijo de 4 bytes que contiene la longitud del fragmento, seguido de los datos reales cuya longitud se especifica en el prefijo de 4 bytes.
ZERO_CHUNK es un valor de 4 bytes que contiene todos los ceros (00000000) que indica el final de los datos.
Cualquier otra longitud válida de 8 bytes se trata como una longitud de datos normal.

Al llamar a bcp_columns cuando se usa 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 usados 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 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);

Consulte también

Funciones de copia masiva

Compartir a través de

bcp_bind

Sintaxis

Argumentos

Devoluciones

Comentarios

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

Ejemplo

Consulte también

Comentarios

Recursos adicionales