bcp_bind
Associa dati provenienti da una variabile di programma a una colonna di tabella per eseguire la copia bulk in SQL Server.
Sintassi
RETCODE bcp_bind (
HDBC hdbc,
LPCBYTE pData,
INT cbIndicator,
DBINT cbData,
LPCBYTE pTerm,
INT cbTerm,
INT eDataType,
INT idxServerCol);
Argomenti
hdbc
Handle di connessione ODBC abilitato per la copia bulk.pData
Puntatore ai dati copiati. Se eDataType è SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR o SQLIMAGE, pData può essere NULL. Un valore NULL per pData indica che i valori dei dati long verranno inviati a SQL Server in blocchi mediante bcp_moretext. Se la colonna che corrisponde al campo associato dell'utente è una colonna BLOB, l'utente deve solo impostare pData su NULL. In caso contrario, non sarà possibile eseguire bcp_bind.Se presenti nei dati, gli indicatori vengono visualizzati in memoria direttamente prima dei dati. In questo caso il parametro pData punta alla variabile dell'indicatore e la larghezza dell'indicatore, ovvero il parametro cbIndicator, viene utilizzata dalla copia bulk per indirizzare correttamente i dati dell'utente.
cbIndicator
Lunghezza, espressa in byte, di un indicatore di lunghezza o Null per i dati della colonna. Valori di lunghezza di indicatore validi sono 0 (nel caso in cui non venga utilizzato un indicatore), 1, 2, 4 o 8. Gli indicatori vengono visualizzati in memoria direttamente prima di qualsiasi dato. La definizione del tipo di struttura seguente, ad esempio, potrebbe essere utilizzata per inserire valori integer in una tabella di SQL Server mediante la copia bulk:typedef struct tagBCPBOUNDINT { int iIndicator; int Value; } BCPBOUNDINT;Nel caso di esempio il parametro pData verrebbe impostato sull'indirizzo di un'istanza dichiarata della struttura, ovvero l'indirizzo del membro della struttura iIndicator BCPBOUNDINT. Il parametro cbIndicator verrebbe impostato sulla dimensione di un numero intero (sizeof(int)) e il parametro cbData verrebbe impostato nuovamente sulla dimensione di un numero intero (sizeof(int)). Per eseguire la copia bulk di una riga nel server che contiene un valore NULL per la colonna associata, il valore del membro iIndicator dell'istanza deve essere impostato su SQL_NULL_DATA.
cbData
Numero di byte dei dati nella variabile di programma che non include la lunghezza di un carattere di terminazione o di un indicatore di lunghezza o Null.Se si imposta cbData su SQL_NULL_DATA, tutte le righe copiate nel server contengono un valore NULL per la colonna.
L'impostazione di cbData su SQL_VARLEN_DATA indica che il sistema utilizzerà un carattere di terminazione della stringa, o un altro metodo, per determinare la lunghezza dei dati copiati.
Per tipi di dati a lunghezza fissa, ad esempio numeri interi, il tipo di dati indica la lunghezza dei dati al sistema. Per i tipi di dati a lunghezza fissa, cbData può pertanto essere SQL_VARLEN_DATA o la lunghezza dei dati.
Per i tipi di dati character e binary di SQL Server, cbData può essere SQL_VARLEN_DATA, SQL_NULL_DATA, un valore positivo o 0. Se cbData è SQL_VARLEN_DATA, il sistema utilizza l'indicatore di lunghezza o Null, se disponibile, o una sequenza di caratteri di terminazione per determinare la lunghezza dei dati. Se vengono forniti entrambi, il sistema utilizza quello che comporta la copia del minori numero di dati. Se cbData è SQL_VARLEN_DATA, i dati della colonna appartengono al tipo character o binary di SQL Server e non viene specificato né un indicatore di lunghezza né una sequenza di caratteri di terminazione, il sistema restituisce un messaggio di errore.
Se cbData è 0 o un valore positivo, verrà utilizzato dal sistema come lunghezza dei dati. Se, tuttavia, oltre a un valore cbData positivo, viene specificato un indicatore di lunghezza o una sequenza di caratteri di terminazione, il sistema determina la lunghezza dei dati utilizzando il metodo che comporta la copia del minor numero di dati.
Il valore del parametro cbData rappresenta il numero di byte dei dati. Se i dati character vengono rappresentati come caratteri estesi Unicode, un valore positivo per il parametro cbData rappresenta il numero di caratteri moltiplicato per la dimensione, espressa in byte, di ogni carattere.
pTerm
Puntatore al modello di byte, se presente, che contrassegna la fine di questa variabile di programma. Le stringhe ANSI e MBCS C, ad esempio, presentano generalmente un carattere di terminazione di 1 byte (\0).Se non è presente alcun carattere di terminazione per la variabile, impostare pTerm su NULL.
È possibile utilizzare una stringa vuota ("") per definire il carattere di terminazione Null C come carattere di terminazione della variabile di programma. Dal momento che la stringa vuota con terminazione Null costituisce un solo byte (il byte del carattere di terminazione stesso), impostare cbTerm su 1. Per indicare, ad esempio, che la stringa in szName è con terminazione Null e che per indicare la lunghezza deve essere utilizzato il carattere di terminazione:
bcp_bind(hdbc, szName, 0, SQL_VARLEN_DATA, "", 1, SQLCHARACTER, 2)Una versione senza carattere di terminazione di questo esempio potrebbe indicare che 15 caratteri devono essere copiati dalla variabile szName nella seconda colonna della tabella associata:
bcp_bind(hdbc, szName, 0, 15, NULL, 0, SQLCHARACTER, 2)L'API della copia bulk esegue la conversione dei caratteri da Unicode a MBCS in base alle necessità. Verificare che la stringa di byte del carattere di terminazione e la lunghezza della stringa di byte siano impostate correttamente. Per indicare, ad esempio, che la stringa in szName è una stringa di caratteri estesi Unicode terminata dal carattere di terminatozione Null di Unicode:
bcp_bind(hdbc, szName, 0, SQL_VARLEN_DATA, L"", sizeof(WCHAR), SQLNCHAR, 2)Se la colonna di SQL Server associata è di tipo carattere esteso, non viene eseguita alcuna conversione su bcp_sendrow. Se la colonna di SQL Server è un tipo di carattere MBCS, la conversione da carattere esteso a carattere multibyte viene eseguita quando i dati vengono inviati a SQL Server.
cbTerm
Numero dei byte presenti nel carattere di terminazione per la variabile di programma, se presente. Se non è presente alcun carattere di terminazione per la variabile, impostare cbTerm su NULL.eDataType
Tipo di dati C della variabile di programma. I dati della variabile di programma vengono convertiti nel tipo della colonna di database. Se questo parametro è 0, non viene eseguita alcuna conversione.Il parametro eDataType viene enumerato in base ai token dei tipi di dati di SQL Server in sqlncli.h e non in base agli enumeratori dei tipi di dati ODBC C. È ad esempio possibile specificare un numero intero a due byte, SQL_C_SHORT di tipo ODBC, utilizzando il tipo specifico di SQL Server SQLINT2.
In SQL Server 2005 è stato introdotto il supporto per i token dei tipi di dati SQLXML e SQLUDT nel parametro eDataType.
idxServerCol
Posizione ordinale della colonna nella tabella di database in cui vengono copiati i dati. La prima colonna di una tabella è la colonna 1. La posizione ordinale di una colonna viene indicata da SQLColumns.
Restituisce
SUCCEED o FAIL.
Osservazioni
Utilizzare bcp_bind per copiare in modo rapido ed efficace i dati da una variabile di programma in una tabella in SQL Server.
Chiamare bcp_init prima di chiamare questa o un'altra funzione di copia bulk. Se si chiama bcp_init, viene impostata la tabella di destinazione per la copia bulk di SQL Server. Quando si chiama bcp_init per l'utilizzo con bcp_bind e bcp_sendrow, il parametro szDataFile di bcp_init che indica il file di dati, viene impostato su NULL. Il parametro eDirection di bcp_init viene impostato su DB_IN.
Effettuare una chiamata al metodo bcp_bind separata per ogni colonna della tabella di SQL Server nella quale si desidera eseguire la copia. Dopo che sono state effettuate le chiamate a bcp_bind necessarie, chiamare bcp_sendrow per inviare una riga di dati dalle variabili di programma a SQL Server.
Ogni volta che si desidera che SQL Server esegua il commit delle righe già ricevute, chiamare bcp_batch. Chiamare ad esempio bcp_batch ogni 1000 righe inserite o in base a un altro intervallo.
Quando non sono più presenti righe da inserire, chiamare bcp_done. In caso contrario, si determina un errore.
Le impostazioni dei parametri di controllo specificate con bcp_control non hanno effetto sui trasferimenti di righe di bcp_bind.
Se per una colonna pData è impostato su NULL, in quanto il rispettivo valore verrà fornito dalle chiamate a bcp_moretext, anche eventuali colonne successive in cui eDataType è impostato su SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR o SQLIMAGE devono essere associate con pData impostato su NULL e anche i rispettivi valori devono essere forniti dalle chiamate a bcp_moretext.
Per i nuovi tipi di valori di grandi dimensioni, quali varchar(max), varbinary(max) o nvarchar(max), è possibile utilizzare SQLCHARACTER,SQLVARCHAR,SQLVARBINARY,SQLBINARY eSQLNCHAR come indicatori di tipo nel parametro eDataType.
Se cbTerm non è 0, qualsiasi valore (1, 2, 4 o 8) sarà valido per il prefisso (cbIndicator). In questa situazione SQL Server Native Client eseguirà la ricerca del carattere di terminazione, calcolerà la lunghezza dei dati rispetto al carattere di terminazione (i) e imposterà cbData sul valore più piccolo di i e sul valore del prefisso.
Se cbTerm è 0 e cbIndicator (il prefisso) non è 0, cbIndicator deve essere 8. Al prefisso a 8 byte possono essere assegnati i valori seguenti:
0xFFFFFFFFFFFFFFFF indica un valore Null per il campo
0xFFFFFFFFFFFFFFFE viene trattato come valore di prefisso speciale utilizzato per inviare dati in blocchi al server in modo efficace. Il formato dei dati con questo prefisso speciale è:
<SPECIAL_PREFIX> <0 o più DATA CHUNKS> <ZERO_CHUNK> dove:
SPECIAL_PREFIX è 0xFFFFFFFFFFFFFFFE
DATA_CHUNK è un prefisso a 4 byte che contiene la lunghezza del blocco, seguita dai dati effettivi la cui lunghezza viene specificata nel prefisso a 4 byte.
ZERO_CHUNK è un valore a 4 byte che contiene tutti zeri (00000000) che indicano la fine dei dati.
Qualsiasi altra lunghezza a 8 byte valida viene trattata come una lunghezza dei dati normale.
Se si chiama bcp_columns quando si utilizza bcp_bind, viene restituito un errore.
Supporto di bcp_bind per le funzionalità avanzate di data e ora
Per informazioni sui tipi utilizzati con il parametro eDataType per i tipi data e ora, vedere Modifiche apportate alla copia bulk per i tipi di data/ora migliorati (OLE DB e ODBC).
Per ulteriori informazioni, vedere Miglioramenti relativi a data e ora (ODBC).
Esempio
#include sql.h
#include sqlext.h
#include odbcss.h
// Variables like henv not specified.
HDBC hdbc;
char szCompanyName[MAXNAME];
DBINT idCompany;
DBINT nRowsProcessed;
DBBOOL bMoreData;
char* pTerm = "\t\t";
// 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 bcp.
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL
DB_IN) == FAIL)
{
// Raise error and return.
return;
}
// Bind program variables to table columns.
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,
SQLINT4, 1) == FAIL)
{
// Raise error and return.
return;
}
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,
(LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)
{
// Raise error and return.
return;
}
while (TRUE)
{
// Retrieve and process program data.
if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)
{
// Send the data.
if (bcp_sendrow(hdbc) == FAIL)
{
// Raise error and return.
return;
}
}
else
{
// Break out of loop.
break;
}
}
// Terminate the bulk copy operation.
if ((nRowsProcessed = bcp_done(hdbc)) == -1)
{
printf_s("Bulk-copy unsuccessful.\n");
return;
}
printf_s("%ld rows copied.\n", nRowsProcessed);