bcp_bind
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 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 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 introdujo compatibilidad con tokens de tipo de datos SQLXML y SQLUDT en el eDataType paramenter.
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. 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 valores grandes, como , o nvarchar(max), puede usar SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY y SQLNCHAR como indicadores de tipo en el parámetro eDataType. varbinary(max)varchar(max)
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 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:
<><SPECIAL_PREFIX 0 o más fragmentos<>de datos ZERO_CHUNK> 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.
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);