bcp_moretext
Se aplica a: SQL Server
Azure SQL Database
Azure SQL Instancia administrada
Azure Synapse Analytics Analytics
Platform System (PDW)
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 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 de longitud variable admitido y largo que se va a enviar a SQL Server.
Devoluciones
SUCCEED o FAIL.
Comentarios
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 pueden usar con columnas que tienen 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 que no es 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 puede usar para copiar datos inmediatamente después de un retorno correcto de bcp_sendrow que indica 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 de 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 surgiría, por ejemplo, en una aplicación que usaba bcp_collen para establecer la longitud de los datos disponibles para una columna de texto de SQL Server 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, seguidos de la siguiente columna con números más bajos, 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 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 a bcp_sendrow 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 columnas de texto :
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.