bcp_moretext
Envía parte de un valor de tipo de datos largo, de longitud variable a SQL Server.
Sintaxis
RETCODE bcp_moretext (
HDBC hdbc,
DBINT cbData,
LPCBYTE pData);
Argumentos
hdbc
Es el identificador de la conexión ODBC habilitada para la copia masiva.cbData
Es el número de bytes de los datos que se están copiando en SQL Server desde los datos a los que hace referencia pData. Un valor de SQL_NULL_DATA indica NULL.pData
Es un puntero al fragmento de datos compatible, largo y de longitud variable que se va a enviar a SQL Server.
Devuelve
SUCCEED o FAIL.
Comentarios
Esta función se puede usar junto con bcp_bind y bcp_sendrow para copiar valores de datos largos de longitud variable en SQL Server en varios fragmentos más pequeños. bcp_moretext se puede usar con columnas con los siguientes tipos de datos de SQL Server: text, ntext, image, varchar(max), nvarchar(max), varbinary(max), tipo definido por el usuario (UDT) y XML. bcp_moretext no admite conversiones de datos, los datos proporcionados deben coincidir con el tipo de datos de la columna de destino.
Si se llama a bcp_bind con un parámetro pData nonNULL para los tipos de datos que admite bcp_moretext, bcp_sendrow envía el valor completo de los datos, con independencia de la longitud. Sin embargo, si bcp_bind tiene un parámetro pData NULL para los tipos de datos compatibles, bcp_moretext se pueden usar para copiar los datos inmediatamente después de una devolución correcta de bcp_sendrow que indica que se han procesado las columnas enlazadas con los datos presentes.
Si usa bcp_moretext para enviar una columna de tipo de datos compatibles en una fila, también debe usarlo para enviar todas las demás columnas de tipo de datos compatibles de la fila. No se puede omitir ninguna columna. Los tipos de datos admitidos son SQLTEXT, SQLNTEXT, SQLIMAGE, SQLUDT y SQLXML. SQLCHARACTER, SQLVARCHAR, SQNCHAR, SQLBINARY y SQLVARBINARY también pertenecen a esta categoría si la columna es de tipo varchar (max), nvarchar (max) o varbinary (max), respectivamente.
Al llamar a bcp_bind o bcp_collen se establece la longitud total de todas las partes de datos que se copiarán en la columna SQL Server. Si se intenta enviar más bytes de SQL Server que los especificados en la llamada a bcp_bind o bcp_collen, se genera un error. Por ejemplo, este error se producirá en una aplicación que usaba bcp_collen para establecer en 4500 la longitud de datos disponibles de una columna text de SQL Server y, a continuación, llamaba cinco veces a bcp_moretext indicando en cada llamada que la longitud del búfer de datos era de 1000 bytes.
Si una fila copiada contiene más de una columna larga, de longitud variable, bcp_moretext envía primero sus datos a la columna con el número ordinal más bajo, seguido de la columna con el siguiente número ordinal más bajo, etc. Es importante una configuración correcta de la longitud total de datos esperados. No hay ninguna manera de indicar, fuera de la configuración de longitud, que la copia masiva ha recibido todos los datos de una columna.
Cuando los valores var(max) se envían al servidor mediante bcp_sendrow y bcp_moretext, no es necesario llamar a bcp_collen para establecer la longitud de la columna. En su lugar, únicamente para estos tipos, el valor se termina llamando a bcp_sendrow con una longitud de cero.
Una aplicación suele llamar a bcp_sendrow y bcp_moretext dentro de los bucles para enviar varias filas de datos. A continuación se describe cómo hacerlo en una tabla que consta de dos columnas text:
while (there are still rows to send)
{
bcp_sendrow(...);
for (all the data in the first varbinary(max) column)
bcp_moretext(...);
bcp_moretext(hdbc, 0, NULL);
for (all the data in the second varbinary(max) column)
bcp_moretext(...);
bcp_moretext(hdbc, 0, NULL);
}
Ejemplo
En este ejemplo se muestra cómo usar bcp_moretext con bcp_bind y bcp_sendrow:
// Variables like henv not specified.
HDBC hdbc;
DBINT idRow = 5;
char* pPart1 = "This text value isn't very long,";
char* pPart2 = " but it's broken into three parts";
char* pPart3 = " anyhow.";
DBINT cbAllParts;
DBINT nRowsProcessed;
// 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 bulk copy.
if (bcp_init(hdbc, "comdb..articles", NULL, NULL, DB_IN) == FAIL)
{
// Raise error and return.
return;
}
// Bind program variables to table columns.
if (bcp_bind(hdbc, (LPCBYTE) &idRow, 0, SQL_VARLEN_DATA, NULL, 0,
SQLINT4, 1) == FAIL)
{
// Raise error and return.
return;
}
cbAllParts = (DBINT) (strnlen(pPart1, sizeof(pPart1) + 1) + strnlen(pPart2, sizeof(pPart2) + 1) + strnlen(pPart3, sizeof(pPart3) + 1));
if (bcp_bind(hdbc, NULL, 0, cbAllParts, NULL, 0, SQLTEXT, 2) == FAIL)
{
// Raise error and return.
return;
}
// Send this row, with the text value broken into three chunks.
if (bcp_sendrow(hdbc) == FAIL)
{
// Raise error and return.
return;
}
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart1, sizeof(pPart1) + 1), pPart1) == FAIL)
{
// Raise error and return.
return;
}
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart2, sizeof(pPart2) + 1), pPart2) == FAIL)
{
// Raise error and return.
return;
}
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart3, sizeof(pPart3) + 1), pPart3) == FAIL)
{
// Raise error and return.
return;
}
// All done. Get the number of rows processed (should be one).
nRowsProcessed = bcp_done(hdbc);
// Carry on.