bcp_moretext

Sintassi

RETCODE bcp_moretext (
        HDBC hdbc,
        DBINT cbData,
        LPCBYTE pData);

Argomenti

• hdbc
  Handle di connessione ODBC abilitato per la copia bulk.

• cbData
  Numero di byte dei dati copiati in SQL Server dai dati di riferimento di pData. Un valore di SQL_NULL_DATA indica NULL.

• pData
  Puntatore al blocco di dati Long a lunghezza variabile supportati da inviare a SQL Server.

Restituisce

SUCCEED o FAIL.

Osservazioni

Questa funzione può essere utilizzata in combinazione con bcp_bind e bcp_sendrow per copiare valori dei dati Long a lunghezza variabile in SQL Server in blocchi più piccoli.. bcp_moretext può essere utilizzata con le colonne che includono i tipi di dati SQL Server seguenti: text, ntext, image, varchar(max), nvarchar(max), varbinary(max), tipo definito dall'utente e XML. bcp_moretext non supporta le conversioni dei dati e i dati forniti devono corrispondere al tipo di dati della colonna di destinazione.

Se bcp_bind viene chiamata con un parametro pData non NULL per i tipi di dati supportati da bcp_moretext, bcp_sendrow invia l'intero valore dei dati, indipendentemente dalla lunghezza. Se tuttavia bcp_bind include un parametro pData NULL per i tipi di dati supportati, bcp_moretext può essere utilizzata per copiare i dati immediatamente dopo una corretta restituzione da bcp_sendrow, che indica che qualsiasi colonna associata contenente dati è stata elaborata.

Se si utilizza bcp_moretext per inviare una colonna del tipo di dati supportato in una riga, è necessario utilizzarla anche per inviare tutte le altre colonne del tipo di dati supportato nella riga. Non è possibile ignorare alcuna colonna. I tipi di dati supportati sono SQLTEXT, SQLNTEXT, SQLIMAGE, SQLUDT e SQLXML. Anche SQLCHARACTER, SQLVARCHAR, SQNCHAR, SQLBINARY e SQLVARBINARY rientrano in questa categoria se la colonna è di tipo varchar(max), nvarchar(max) o varbinary(max), rispettivamente.

La chiamata di bcp_bind o bcp_collen imposta la lunghezza totale di tutte le parti di dati da copiare nella colonna di SQL Server. Un tentativo di inviare a SQL Server un numero di byte maggiore rispetto a quello specificato nella chiamata a bcp_bind o bcp_collen genera un errore. L'errore può essere causato, ad esempio, in un'applicazione che ha utilizzato bcp_collen per impostare su 4500 la lunghezza dei dati disponibili da una colonna text di SQL Server e ha quindi chiamato bcp_moretext cinque volte indicando in ogni chiamata che la lunghezza del buffer di dati era pari a 1000 byte.

Se una riga copiata contiene più di una colonna Long a lunghezza variabile, bcp_moretext invia i dati alle colonne, a partire da quella con la numerazione ordinale più bassa, seguita dalla colonna con la numerazione ordinale più bassa successiva e così via. Una corretta impostazione della lunghezza totale dei dati previsti è importante. Non è possibile segnalare, al di fuori dell'impostazione della lunghezza, che tutti i dati per una colonna sono stati ricevuti dalla copia bulk.

Quando i valori di var(max) vengono inviati al server mediante bcp_sendrow e bcp_moretext, non è necessario chiamare bcp_collen per impostare la lunghezza della colonna. Al contrario, solo per questi tipi, il valore viene terminato chiamando bcp_sendrow con una lunghezza pari a zero.

Un'applicazione in genere chiama bcp_sendrow e bcp_moretext all'interno di cicli per inviare diverse righe di dati. Di seguito viene riportato il codice che consente di eseguire questa operazione per una tabella contenente due colonne 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);

}

Esempio

// 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.

Vedere anche

Riferimento