bcp_colfmt
Specifica il formato di origine o di destinazione dei dati in un file utente. Quando viene utilizzato come formato di origine, bcp_colfmt specifica il formato di un file di dati esistente utilizzato come origine dei dati in una copia bulk di una tabella di SQL Server. Quando viene utilizzato come formato di destinazione, il file di dati viene creato utilizzando i formati di colonna specificati con bcp_colfmt.
Sintassi
RETCODE bcp_colfmt (
HDBC hdbc,
INT idxUserDataCol,
BYTE eUserDataType,
INT cbIndicator,
DBINT cbUserData,
LPCBYTE pUserDataTerm,
INT cbUserDataTerm,
INT idxServerCol);
Argomenti
hdbc
Handle di connessione ODBC abilitato per la copia bulk.idxUserDataCol
Numero ordinale di colonna nel file di dati dell'utente per il quale viene specificato il formato. La prima colonna è 1.eUserDataType
Tipo di dati della colonna nel file utente. Se diverso dal tipo di dati della colonna corrispondente nella tabella di database (idxServerColumn), la copia bulk converte i dati, se possibile.In SQL Server 2005 è stato introdotto il supporto per i token dei tipi di dati SQLXML e SQLUDT nel parametro eUserDataType.
Il parametro eUserDataType viene enumerato in base ai token dei tipi di dati SQL Server in sqlncli.h e non in base agli enumeratori dei tipi di dati ODBC C. È ad esempio possibile specificare una stringa di caratteri SQL_C_CHAR di tipo ODBC utilizzando il tipo SQLCHARACTER specifico di SQL Server.
Per specificare la rappresentazione predefinita dei dati per il tipo di dati SQL Server, impostare questo parametro su 0.
Per una copia bulk esterna a SQL Server in un file, quando eUserDataType è SQLDECIMAL o 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
Lunghezza, espressa in byte, di un indicatore di lunghezza o Null nei dati della colonna. I valori validi per la lunghezza dell'indicatore sono 0 (nel caso in cui non venga utilizzato un indicatore), 1, 2, 4 o 8.Per specificare l'utilizzo di un indicatore di copia bulk predefinito, impostare questo parametro su SQL_VARLEN_DATA.
Gli indicatori vengono visualizzati in memoria direttamente prima dei dati e nel file di dati direttamente prima dei dati a cui si riferiscono.
Se si utilizzano più modalità di specifica della lunghezza delle colonne del file di dati, ad esempio un indicatore e una lunghezza di colonna massima o un indicatore e una sequenza di caratteri di terminazione, la copia bulk sceglie quella che comporta la copia del minor numero di dati.
I file di dati generati dalla copia bulk quando il formato dei dati non viene modificato dall'utente contengono indicatori se la lunghezza dei dati di colonna può variare o se la colonna può accettare NULL come valore.
cbUserData
Lunghezza massima, espressa in byte, dei dati della colonna nel file utente, senza includere la lunghezza di un carattere di terminazione o di un indicatore di lunghezza.L'impostazione di cbUserData su SQL_NULL_DATA indica che tutti i valori nella colonna del file di dati sono o dovrebbero essere impostati su NULL.
L'impostazione di cbUserData su SQL_VARLEN_DATA indica che il sistema deve determinare la lunghezza dei dati in ogni colonna. Per alcune colonne, questo potrebbe indicare che viene generato un indicatore di lunghezza o Null da anteporre ai dati in una copia da SQL Server o che è previsto l'indicatore nei dati copiati in SQL Server.
Per i dati di tipo carattere o binario di SQL Server, cbUserData può essere SQL_VARLEN_DATA, SQL_NULL_DATA, 0 o un valore positivo. Se cbUserData è SQL_VARLEN_DATA, 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 utilizza la modalità che comporta la copia del minor numero di dati. Se cbUserData è SQL_VARLEN_DATA, 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, il sistema utilizza cbUserData come lunghezza massima dei dati. Se, tuttavia, oltre a un cbUserData 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 cbUserData rappresenta il numero di byte dei dati. Se i dati di tipo carattere vengono rappresentati come caratteri estesi Unicode, un valore positivo per il parametro cbUserData rappresenta il numero di caratteri moltiplicato per la dimensione, espressa in byte, di ogni carattere.
pUserDataTerm
Sequenza di caratteri di terminazione da utilizzare per la colonna. 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 che un indicatore di lunghezza registri 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 vengano terminati, impostare questo parametro su NULL.
Se si utilizzano più modalità di specifica della 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 sceglie 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.
pUserDataTerm
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
Posizione ordinale della colonna nella tabella di database. Il numero della prima colonna è 1. La posizione ordinale di una colonna viene indicata da SQLColumns.Se questo valore è 0, la copia bulk ignora la colonna nel file di dati.
Restituisce
SUCCEED o FAIL.
Osservazioni
La funzione bcp_colfmt consente di specificare il formato del file utente per le copie bulk. Per la copia bulk, un formato contiene le parti seguenti:
Un mapping dalle colonne del file utente alle colonne del database.
Il tipo di dati di ogni colonna del file utente.
La lunghezza dell'indicatore facoltativo per ogni colonna.
La lunghezza massima dei dati per ogni colonna del file utente.
La sequenza di byte di terminazione facoltativa per ogni colonna.
La lunghezza della sequenza di byte di terminazione facoltativa.
Ogni chiamata a bcp_colfmt specifica il formato per una colonna del file utente. Per modificare, ad esempio, le impostazioni predefinite per tre colonne in un file di dati dell'utente con cinque colonne, chiamare innanzitutto bcp_columns(5), quindi chiamare bcp_colfmt cinque volte, con tre di queste chiamate che impostano il formato personalizzato. Per le due chiamate rimanenti, impostare eUserDataType su 0 e cbIndicator, cbUserData e cbUserDataTerm su 0, SQL_VARLEN_DATA e 0 rispettivamente. Questa procedura consente di copiare tutte e cinque le colonne, tre con il formato personalizzato e due con il formato predefinito.
Per cbIndicator, è ora supportato il valore 8 che indica un tipo per valori di grandi dimensioni. Se si specifica il prefisso per un campo la cui colonna corrispondente è un nuovo tipo max, può essere impostato solo su 8. Per informazioni dettagliate, vedere bcp_bind.
La funzione bcp_columns deve essere chiamata prima delle chiamate a bcp_colfmt.
È necessario chiamare bcp_colfmt una volta per ogni colonna del file utente.
Se bcp_colfmt viene chiamato più volte per una colonna del file utente, viene generato un errore.
Non è necessario copiare tutti i dati di un file utente nella tabella SQL Server. Per ignorare una colonna, specificarne il formato dei dati impostando il parametro idxServerCol su 0. La specifica del tipo di una colonna consente di ignorarla.
La funzione bcp_writefmt può essere utilizzata per rendere persistente la specifica del formato.
Supporto di bcp_colfmt per le funzionalità avanzate di data e ora
Per informazioni sui tipi utilizzati con il parametro eUserDataType 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).