bcp_moretext

Se aplica a:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)

Envía parte de un valor de tipo de datos de longitud variable largo 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.

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 puede usar con columnas que tienen los siguientes tipos de datos 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 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 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 admitida 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 todas las partes 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 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 llamó 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 y de longitud variable, bcp_moretext primero envía sus datos a la columna numerada más baja o dinámicamente, seguida de la siguiente columna con números más bajos o numerados, 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, 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 dentro de 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.  

Consulte también

Bulk Copy Functions