IBCPSession::BCPColFmt (OLE DB)
Crea un'associazione tra variabili di programma e colonne di SQL Server.
Sintassi
HRESULT BCPColFmt(
DBORDINAL idxUserDataCol,
int eUserDataType,
int cbIndicator,
int cbUserData,
BYTE *pbUserDataTerm,
int cbUserDataTerm,
DBORDINAL idxServerCol);
Osservazioni
Il metodo BCPColFmt viene utilizzato per creare un'associazione tra campi del file di dati BCP e colonne di SQL Server. Accetta come parametri la lunghezza, il tipo, il carattere di terminazione e la lunghezza del prefisso di una colonna e imposta ciascuna di queste proprietà per i singoli campi.
Se l'utente sceglie la modalità interattiva, questo metodo viene chiamato due volte, una volta per impostare il formato della colonna in base ai valori predefiniti (che dipendono dal tipo di colonna del server) e una volta per impostare il formato in base al tipo di client selezionato durante la modalità interattiva, per ogni colonna.
Nelle modalità non interattive, viene chiamato una sola volta per colonna per impostare il tipo di ogni colonna sul carattere o sul tipo nativo e impostare i caratteri di terminazione di colonna e riga.
Il metodo BCPColFmt consente di specificare il formato del file utente per le copie bulk. Per la copia bulk, un formato contiene le parti seguenti:
Un mapping dai campi del file utente alle colonne del database.
Il tipo di dati di ogni campo del file utente.
La lunghezza dell'indicatore facoltativo per ogni campo.
La lunghezza massima dei dati per ogni campo del file utente.
La sequenza di byte di terminazione facoltativa per ogni campo.
La lunghezza della sequenza di byte di terminazione facoltativa.
Ogni chiamata a BCPColFmt specifica il formato per un campo del file utente. Per modificare ad esempio le impostazioni predefinite per tre campi in un file di dati dell'utente con cinque campi, chiamare innanzitutto BCPColumns(5), quindi chiamare BCPColFmt cinque volte, con tre di queste chiamate che impostano il formato personalizzato. Per le due chiamate rimanenti, impostare eUserDataType su BCP_TYPE_DEFAULT e cbIndicator, cbUserData e cbUserDataTerm su 0, BCP_VARIABLE_LENGTH, e 0 rispettivamente. Questa procedura consente di copiare tutte e cinque le colonne, tre con il formato personalizzato e due con il formato predefinito.
[!NOTA]
Il metodo IBCPSession::BCPColumns deve essere chiamato prima di qualsiasi chiamata a BCPColFmt. È necessario chiamare BCPColFmt una volta per ogni colonna del file utente. Se BCPColFmt viene chiamato più di una volta per qualsiasi colonna del file utente, viene generato un errore.
Non è necessario copiare tutti i dati di un file utente in una tabella SQL Server. Per ignorare una colonna, specificare il formato dei dati per la colonna impostando il parametro idxServerCol su 0. Per ignorare un campo, è necessario comunque disporre di tutte le informazioni affinché il metodo possa funzionare correttamente.
Nota La funzione IBCPSession::BCPWriteFmt può essere utilizzata per rendere persistente la specifica del formato fornita tramite BCPColFmt.
Argomenti
idxUserDataCol[in]
Indice del campo nel file di dati dell'utente.eUserDataType[in]
Il tipo di dati del campo nel file di dati dell'utente. I tipi di dati disponibili sono elencati nel file di intestazione di SQL Server Native Client (sqlncli.h) con il formato BCP_TYPE_XXX, ad esempio, BCP_TYPE_SQLINT4. Se viene specificato il valore BCP_TYPE_DEFAULT, il provider tenta di utilizzare lo stesso tipo della colonna della tabella o della vista. Per le operazioni di copia bulk al di fuori di SQL Server e in un file quando l'argomento eUserDataType è BCP_TYPE_SQLDECIMAL o BCP_TYPE_SQLNUMERIC:Se la colonna di origine non è decimal o numeric, vengono utilizzate la precisione e la scala predefinite.
Se la colonna di origine è decimal o numeric, vengono utilizzate la precisione e la scala della colonna di origine.
cbIndicator[in]
Lunghezza del prefisso per il campo. Il prefisso predefinito è BCP_PREFIX_DEFAULT. Le lunghezze valide per il prefisso sono 0, 1, 2, 4 e 8. Una dimensione del prefisso pari a 8 in genere viene utilizzata per indicare che il campo è Chunked e consente di eseguire in modo efficace la copia bulk di colonne del tipo valore di grandi dimensioni.cbUserData[in]
Lunghezza massima, espressa in byte, dei dati del campo nel file utente, senza includere la lunghezza di un carattere di terminazione o di un indicatore di lunghezza.L'impostazione di cbUserData su BCP_LENGTH_NULL indica che tutti i valori nei campi del file di dati sono o dovrebbero essere impostati su NULL. L'impostazione di cbUserData su BCP_LENGTH_VARIABLE indica che la lunghezza dei dati per ogni campo deve essere determinata dal sistema. Per alcuni campi, questo potrebbe indicare che viene generato un indicatore di lunghezza o Null da anteporre ai dati in una copia da SQL Server o che l'indicatore è previsto nei dati copiati in SQL Server.
Per i dati di tipo carattere o binario di SQL Server, cbUserData può essere BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0 o un valore positivo. Se cbUserData è BCP_LENGTH_VARIABLE, il sistema utilizza l'indicatore di lunghezza, se disponibile, o una sequenza di caratteri di terminazione per determinare la lunghezza dei dati. Se vengono specificati sia un indicatore di lunghezza che una sequenza di caratteri di terminazione, la copia bulk utilizzerà la modalità che comporta la copia del minor numero di dati. Se cbUserData è BCP_LENGTH_VARIABLE, vengono utilizzati dati di tipo carattere o binario 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 cbUserData è 0 o un valore positivo, verrà utilizzato come lunghezza massima dei dati. Se, tuttavia, oltre a un valore positivo di cbUserData, 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 di cbUserData rappresenta il numero di byte dei dati. Se i dati di tipo carattere vengono rappresentati come caratteri wide Unicode, un valore positivo per il parametro cbUserData rappresenta il numero di caratteri moltiplicato per la dimensione, espressa in byte, di ogni carattere.
pbUserDataTerm[size_is] [in]
Sequenza di caratteri di terminazione da utilizzare per il campo. Questo parametro risulta particolarmente utile per i dati di tipo carattere perché tutti gli altri tipi hanno una lunghezza fissa o, nel caso dei dati binari, richiedono un indicatore di lunghezza per registrare in modo preciso il numero di byte presenti.Per evitare di terminare i dati estratti o per indicare che i dati di un file utente non devono essere terminati, impostare questo parametro su NULL.
Se si utilizzano più modalità per definire la lunghezza delle colonne di un file utente, ad esempio un carattere di terminazione e un indicatore di lunghezza o un carattere di terminazione e una lunghezza di colonna massima, la copia bulk sceglierà quella che comporta la copia del minor numero di dati.
L'API della copia bulk esegue la conversione dei caratteri da Unicode a MBCS in base alle necessità. Verificare attentamente che la stringa di byte del carattere di terminazione e la lunghezza della stringa di byte vengano impostate correttamente.
cbUserDataTerm[in]
Lunghezza, espressa in byte, della sequenza di caratteri di terminazione da utilizzare per la colonna. Se non sono presenti caratteri di terminazione nei dati o non si desidera includerli, impostare questo valore su 0.idxServerCol[in]
Posizione ordinale della colonna nella tabella del database. Il numero della prima colonna è 1. La posizione ordinale di una colonna viene indicata da IColumnsInfo::GetColumnInfo o da metodi simili. Se questo valore è 0, la copia bulk ignora il campo nel file di dati.
Valori restituiti
S_OK
Il metodo è riuscito.E_FAIL
Si è verificato un errore specifico del provider. Per informazioni dettagliate, utilizzare l'interfaccia ISQLServerErrorInfo.E_UNEXPECTED
La chiamata al metodo è stata effettuata in modo imprevisto. Non è stato ad esempio chiamato il metodo IBCPSession::BCPInit prima della chiamata a questo metodo.E_INVALIDARG
L'argomento non è valido.E_OUTOFMEMORY
Errore di memoria insufficiente.
Vedere anche
Concetti
Esecuzione di operazioni di copia bulk