bcp_bind

Articolo
01/10/2024

Si applica a: SQL Server Database SQL di Azure Istanza gestita di SQL di Azure Azure Synapse Analytics Piattaforma di strumenti analitici (PDW)

Associa i dati da una variabile di programma a una colonna di tabella per 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 pData NULL indica che i valori di dati lunghi verranno inviati a SQL Server in blocchi usando bcp_moretext. L'utente deve impostare pData su NULL solo se la colonna corrispondente al campo associato all'utente è una colonna BLOB; in caso contrario , bcp_bind avrà esito negativo.

Se presenti nei dati, gli indicatori vengono visualizzati in memoria direttamente prima dei dati. Il parametro pData punta alla variabile indicatore in questo caso e la larghezza dell'indicatore, il parametro cbIndicator , viene usato dalla copia bulk per indirizzare correttamente i dati 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. Ad esempio, la definizione del tipo di struttura seguente può essere usata per inserire valori integer in una tabella di SQL Server usando la copia bulk:

typedef struct tagBCPBOUNDINT  
    {  
    int iIndicator;  
    int Value;  
    } BCPBOUNDINT;

Nel caso di esempio, il parametro pData viene impostato sull'indirizzo di un'istanza dichiarata della struttura, l'indirizzo del membro della struttura IIndicator BCPBOUNDINT. Il parametro cbIndicator verrà impostato sulle dimensioni di un numero intero (sizeof(int) e il parametro cbData verrà impostato di nuovo sulle dimensioni di un numero intero (sizeof(int)). Per copiare in blocco una riga nel server contenente 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.

L'impostazione di cbData su SQL_NULL_DATA indica che 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 userà un carattere di terminazione 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. Pertanto, per i tipi di dati a lunghezza fissa, cbData può essere SQL_VARLEN_DATA o la lunghezza dei dati.

Per i tipi di dati di tipo carattere e binario di SQL Server, cbData può essere SQL_VARLEN_DATA, SQL_NULL_DATA, un valore positivo o 0. Se cbData è SQL_VARLEN_DATA, il sistema usa un indicatore length/null (se presente) 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, il tipo di dati della colonna è un carattere o un tipo binario di SQL Server e non viene specificato né un indicatore di lunghezza né una sequenza di terminazione, il sistema restituisce un messaggio di errore.

Se cbData è 0 o un valore positivo, il sistema usa cbData come lunghezza dei dati. Tuttavia, se, oltre a un valore cbData positivo, viene fornita una sequenza di indicatore di lunghezza o di terminazione, il sistema determina la lunghezza dei dati usando il metodo che restituisce la quantità minima di dati copiati.

Il valore del parametro cbData rappresenta il numero di byte di dati. Se i dati di tipo carattere sono rappresentati da caratteri wide Unicode, un valore di parametro cbData positivo rappresenta il numero di caratteri moltiplicati per le dimensioni 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. Poiché la stringa vuota con terminazione Null costituisce un singolo byte (il byte del terminatore stesso), impostare cbTerm su 1. Ad esempio, per indicare che la stringa in szName è con terminazione Null e che il terminatore deve essere usato per indicare la lunghezza:

bcp_bind(hdbc, szName, 0,  
   SQL_VARLEN_DATA, "", 1,  
   SQLCHARACTER, 2)

Una forma non terminata di questo esempio potrebbe indicare che 15 caratteri devono essere copiati dalla variabile szName alla 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. Ad esempio, per indicare che la stringa in szName è una stringa di caratteri wide Unicode, terminata dal valore del carattere di terminazione Null Unicode:

bcp_bind(hdbc, szName, 0,
   SQL_VARLEN_DATA, L"",  
   sizeof(WCHAR), SQLNCHAR, 2)

Se la colonna di SQL Server associata è di tipo wide, non viene eseguita alcuna conversione in bcp_sendrow. Se la colonna di SQL Server è un tipo di carattere MBCS, la conversione da caratteri wide a caratteri 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 0.

eDataType È il 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 dai token del tipo di dati di SQL Server in sqlncli.h, non dagli enumeratori del tipo di dati ODBC C. Ad esempio, è possibile specificare un numero intero a due byte, il tipo ODBC SQL_C_SHORT, usando il tipo specifico di SQL Server SQLINT2.

SQL Server 2005 (9.x) ha introdotto il supporto per i token del tipo di dati SQLXML e SQLUDT nel parametro eDataType.

La tabella seguente elenca i tipi di dati enumerati validi e i tipi di dati ODBC C corrispondenti.

eDataType	Tipo C
SQLTEXT	char *
SQLNTEXT	wchar_t *
SQLCHARACTER	char *
SQLBIGCHAR	char *
SQLVARCHAR	char *
SQLBIGVARCHAR	char *
SQLNCHAR	wchar_t *
SQLNVARCHAR	wchar_t *
SQLBINARY	unsigned char *
SQLBIGBINARY	unsigned char *
SQLVARBINARY	unsigned char *
SQLBIGVARBINARY	unsigned char *
SQLBIT	char
SQLBITN	char
SQLINT1	char
SQLINT2	short int
SQLINT4	int
SQLINT8	_int64
SQLINTN	cbIndicator 1: SQLINT1 2: SQLINT2 4: SQLINT4 8: SQLINT8
SQLFLT4	float
SQLFLT8	float
SQLFLTN	cbIndicator 4: SQLFLT4 8: SQLFLT8
SQLDECIMALN	SQL_NUMERIC_STRUCT
SQLNUMERICN	SQL_NUMERIC_STRUCT
SQLMONEY	DBMONEY
SQLMONEY4	DBMONEY4
SQLMONEYN	cbIndicator 4: SQLMONEY4 8: SQLMONEY
SQLTIMEN	SQL_SS_TIME2_STRUCT
SQLDATEN	SQL_DATE_STRUCT
SQLDATETIM4	DBDATETIM4
SQLDATETIME	DBDATETIME
SQLDATETIMN	cbIndicator 4: SQLDATETIM4 8: SQLDATETIME
SQLDATETIME2N	SQL_TIMESTAMP_STRUCT
SQLDATETIMEOFFSETN	SQL_SS_TIMESTAMPOFFSET_STRUCT
SQLIMAGE	unsigned char *
SQLUDT	unsigned char *
SQLUNIQUEID	SQLGUID
SQLVARIANT	Qualsiasi tipo di dati ad eccezione di: - text - ntext - image - varchar(max) - varbinary(max) - nvarchar(max) - xml - timestamp
SQLXML	Tipi di dati C supportati: - char* - wchar_t * - unsigned char *

idxServerCol È la 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 segnalata da SQLColumns.

Valori restituiti

SUCCEED o FAIL.

Osservazioni:

Usare bcp_bind per un modo rapido ed efficiente per copiare dati da una variabile di programma in una tabella in SQL Server.

Chiamare bcp_init prima di chiamare questa funzione o qualsiasi altra funzione di copia bulk. La chiamata bcp_init imposta la tabella di destinazione di SQL Server per la copia bulk. Quando si chiama bcp_init per l'uso con bcp_bind e bcp_sendrow, il parametro bcp_init szDataFile, che indica il file di dati, è impostato su NULL. Il parametro bcp_initeDirection viene impostato su DB_IN.

Effettuare una chiamata bcp_bind separata per ogni colonna della tabella di SQL Server in cui si desidera copiare. Dopo aver effettuato le chiamate bcp_bind necessarie, chiamare bcp_sendrow per inviare una riga di dati dalle variabili di programma a SQL Server. La riassociazione della colonna non è supportata.

Ogni volta che si vuole che SQL Server esemetta il commit delle righe già ricevute, chiamare bcp_batch. Ad esempio, chiamare bcp_batch una volta per ogni 1000 righe inserite o in qualsiasi altro intervallo.

Quando non sono presenti più righe da inserire, chiamare bcp_done. In caso contrario, viene generato un errore.

Le impostazioni dei parametri di controllo, specificate con bcp_control, non hanno alcun effetto sui trasferimenti di riga bcp_bind .

Se pData per una colonna è impostato su NULL perché il relativo valore verrà fornito dalle chiamate a bcp_moretext, tutte le colonne successive con eDataType impostate su SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLBINARY, SQLNCHAR o SQLIMAGE devono essere associate anche a pData impostato su NULL e i relativi valori devono essere forniti anche dalle chiamate a bcp_moretext.

Per i nuovi tipi valore di grandi dimensioni, ad esempio varchar(max), varbinary(max)o nvarchar(max), è possibile usare SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY e SQLNCHAR come indicatori di tipo nel parametro eDataType .

Se cbTerm non è 0, qualsiasi valore (1, 2, 4 o 8) è valido per il prefisso (cbIndicator). In questo caso, SQL Server Native Client cercherà il carattere di terminazione, calcolerà la lunghezza dei dati rispetto al terminatore (i) e imposta cbData sul valore minore di i e il valore del prefisso.

Se cbTerm è 0 e cbIndicator (il prefisso) non è 0, cbIndicator deve essere 8. Il prefisso a 8 byte può accettare i valori seguenti:

0xFFFFFFFFFFFFFFFF indica un valore Null per il campo
0xFFFFFFFFFFFFFFFE viene considerato come un valore di prefisso speciale, usato per l'invio efficiente di dati in blocchi al server. Il formato dei dati con questo prefisso speciale è:
<><SPECIAL_PREFIX 0 o più blocchi DI DATI><ZERO_CHUNK> dove:
SPECIAL_PREFIX è 0xFFFFFFFFFFFFFFFE
DATA_CHUNK è un prefisso a 4 byte contenente la lunghezza del blocco, seguito dai dati effettivi la cui lunghezza è specificata nel prefisso a 4 byte.
ZERO_CHUNK è un valore a 4 byte contenente tutti gli zeri (000000000) che indica la fine dei dati.
Qualsiasi altra lunghezza valida a 8 byte viene considerata come una lunghezza regolare dei dati.

La chiamata di bcp_columns quando si usa bcp_bind genera un errore.

Supporto di bcp_bind per le caratteristiche avanzate di data e ora

Per informazioni sui tipi usati con il parametro eDataType per i tipi di data/ora, vedere Modifiche di copia bulk per tipi di data e ora avanzati (OLE DB e ODBC).

Per altre informazioni, vedere Miglioramenti di 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);

Vedi anche

Funzioni di copia bulk

Condividi tramite