bcp_bind
Se aplica a:
SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics 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 al 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 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 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 se volvería a establecer 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.
Establecer cbData en SQL_NULL_DATA significa que todas las filas copiadas en el servidor contienen un valor NULL para la columna.
Establecer 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 de forma segura SQL_VARLEN_DATA o la longitud de los datos.
Para SQL Server tipos de datos binarios y caracteres, 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 tipo binario o 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 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 van a copiar.
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 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 solo byte (el propio byte del terminador), establezca cbTerm en 1. Por ejemplo, para indicar que la cadena de szName termina 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 no designada de este ejemplo podría indicar que se copiarán 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, 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 es de caracteres anchos, no se realiza ninguna conversión en bcp_sendrow. Si la columna SQL Server es un tipo de carácter MBCS, se realiza una conversión de caracteres anchos a caracteres multibyte 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 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 los 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 | FLOAT |
| SQLFLT8 | FLOAT |
| 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: -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 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, el parámetro bcp_initszDataFile , que indica el archivo de datos, se establece en NULL; El parámetro bcp_initeDirection se establece en DB_IN.
Realice una llamada bcp_bind independiente para cada columna de la tabla 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 SQL Server confirmar las filas ya recibidas, 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 filas de 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 valores grandes, 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 (000000000) que indica el final de los datos.
Cualquier otra longitud válida de 8 bytes se trata como una longitud de datos normal.
Llamar a bcp_columns cuando se usa bcp_bind 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
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de