bcp_moretext
Envía parte de un valor de tipo de datos de longitud variable larga 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 datos que se copian en SQL Server de los datos a los que hace referencia pData. Un valor de SQL_NULL_DATA indica NULL.
pData
Es un puntero al fragmento de datos de longitud variable admitido y largo que se va a enviar a SQL Server.
Devoluciones
SUCCEED o FAIL.
Observaciones
Esta función se puede usar junto con bcp_bind y bcp_sendrow para copiar valores de datos largos y de longitud variable en SQL Server en varios fragmentos más pequeños. bcp_moretext se puede usar con columnas que tienen los siguientes tipos de datos SQL Server: text, varchar(max)nvarchar(max)ntextimage, 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 distinto de NULL para los tipos de datos admitidos por bcp_moretext, bcp_sendrow envía todo el valor de datos, independientemente de la longitud. Sin embargo, si bcp_bind tiene un parámetro pData NULL para los tipos de datos admitidos, bcp_moretext se pueden usar para copiar datos inmediatamente después de que se devuelva correctamente bcp_sendrow indicando que se han procesado las columnas enlazadas con datos presentes.
Si usa bcp_moretext para enviar una columna de tipo de datos compatible en una fila, también debe usarla para enviar todas las demás columnas de tipo de datos admitidas en 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 todos los elementos de datos que se van a copiar en la columna SQL Server. Un intento de enviar SQL Server más bytes de los especificados en la llamada a bcp_bind o bcp_collen genera un error. Este error se produciría, por ejemplo, en una aplicación que utilizaba bcp_collen para establecer la longitud de los datos disponibles para una columna de SQL Server text en 4500 y, a continuación, se llama a bcp_moretext cinco veces mientras se indica en cada llamada que la longitud del búfer de datos tenía 1000 bytes de longitud.
Si una fila copiada contiene más de una columna larga, de longitud variable, bcp_moretext primero envía sus datos a la columna con números más bajos o numerados de forma ordinal, seguidas de la siguiente columna numerada de forma ordinal más baja, 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 var(max) los valores 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, solo para estos tipos, el valor finaliza llamando a bcp_sendrow con una longitud de cero.
Normalmente, una aplicación llama bcp_sendrow a y bcp_moretext en bucles para enviar una serie de filas de datos. Este es un esquema de cómo hacerlo para una tabla que contiene dos text columnas:
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.