bcp_setcolfmt
La funzione bcp_setcolfmt sostituisce la funzione bcp_colfmt. Nello specificare le regole di confronto delle colonne, è necessario utilizzare la funzione bcp_setcolfmt. bcp_setbulkmode può essere utilizzata per specificare più di un formato della colonna.
Questa funzione fornisce un approccio flessibile alla definizione del formato delle colonne in un'operazione di copia bulk. La funzione viene utilizzata per impostare singoli attributi di formato di colonna. Ogni chiamata a bcp_setcolfmt imposta un attributo di formato di colonna.
La funzione bcp_setcolfmt specifica il formato di origine o di destinazione dei dati in un file utente. Se utilizzata come formato di origine, la funzione bcp_setcolfmt specifica il formato di un file di dati esistente utilizzato come origine dati in una copia bulk in una tabella di SQL Server. Se la funzione viene utilizzata come formato di destinazione, il file di dati viene creato utilizzando i formati di colonna specificati con bcp_setcolfmt.
Sintassi
RETCODE bcp_setcolfmt (
HDBC hdbc,
INT field,
INT property,
void* pValue,
INT cbValue);
Argomenti
hdbc
Handle di connessione ODBC abilitato per la copia bulk.campo
Numero di colonna ordinale per cui viene impostata la proprietà.proprietà
Una delle costanti delle proprietà. Le costanti della proprietà sono definite nella tabella seguente.Proprietà
Valore
Descrizione
BCP_FMT_TYPE
BYTE
Tipo di dati della colonna nel file utente. Se differisce dal tipo di dati della colonna corrispondente nella tabella del database, la copia bulk converte i dati, se possibile.
Il parametro BCP_FMT_TYPE viene enumerato in base ai token dei tipi di dati in sqlncli.h e non in base agli enumeratori dei tipi di dati C ODBC. È possibile, ad esempio, 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 di SQL Server, impostare questo parametro su 0.
Per una copia bulk esterna a SQL Server in un file, quando BCP_FMT_TYPE è 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.
BCP_FMT_INDICATOR_LEN
INT
Lunghezza in byte dell'indicatore (prefisso).
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 (quando non si utilizza alcun indicatore), 1, 2 o 4.
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 immediatamente prima dei dati a cui si riferiscono.
Se si utilizzano più modalità per specificare la 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.
BCP_FMT_DATA_LEN
DBINT
Lunghezza in byte dei dati (lunghezza di colonna)
Lunghezza massima, espressa in byte, dei dati della colonna nel file utente, esclusa la lunghezza di eventuali caratteri di terminazione o di indicatori di lunghezza.
L'impostazione di BCP_FMT_DATA_LEN su SQL_NULL_DATA indica che tutti i valori nella colonna del file di dati sono o devono essere impostati su NULL.
L'impostazione di BCP_FMT_DATA_LEN su SQL_VARLEN_DATA indica che il sistema deve determinare la lunghezza dei dati in ogni colonna. Per alcune colonne, ciò può 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 tipi di dati character e binary di SQL Server, BCP_FMT_DATA_LEN può essere SQL_VARLEN_DATA, SQL_NULL_DATA, 0 o un valore positivo. Se BCP_FMT_DATA_LEN è 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 BCP_FMT_DATA_LEN è SQL_VARLEN_DATA, il tipo di dati è un 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 BCP_FMT_DATA_LEN è 0 o un valore positivo, viene utilizzato come lunghezza massima dei dati. Se, tuttavia, oltre a un valore positivo per BCP_FMT_DATA_LEN 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 BCP_FMT_DATA_LEN 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 BCP_FMT_DATA_LEN rappresenta il numero di caratteri moltiplicato per le dimensioni, espresse in byte, di ogni carattere.
BCP_FMT_TERMINATOR
LPCBYTE
Puntatore alla sequenza di caratteri di terminazione (ANSI o Unicode in base alle esigenze) da utilizzare per la colonna. Questo parametro risulta particolarmente utile per i dati di tipo carattere, in quanto tutti gli altri tipi hanno una lunghezza fissa o, nel caso dei dati binari, richiedono un indicatore di lunghezza per registrare in modo accurato 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 siano impostate correttamente.
BCP_FMT_SERVER_COL
INT
Posizione ordinale della colonna nel database.
BCP_FMT_COLLATION
LPCSTR
Nome delle regole di confronto.
pValue
Puntatore al valore da associare all'argomento property. Consente di impostare singolarmente ogni proprietà di formato di colonna.cbvalue
Lunghezza in byte del buffer delle proprietà.
Valori restituiti
SUCCEED o FAIL.
Osservazioni
Questa funzione sostituisce la funzione bcp_colfmt. Tutte le funzionalità di bcp_colfmt vengono fornite dalla funzione bcp_setcolfmt. Sono inoltre supportate le regole di confronto delle colonne. È consigliabile impostare gli attributi di formato di colonna seguenti nell'ordine indicato:
BCP_FMT_SERVER_COL
BCP_FMT_DATA_LEN
BCP_FMT_TYPE
La funzione bcp_setcolfmt 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_setcolfmt 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_setcolfmt cinque volte. Tre di queste chiamate impostano il formato predefinito. Per le due chiamate rimanenti, impostare BCP_FMT_TYPE su 0 e BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN e cbValue rispettivamente su 0, SQL_VARLEN_DATA e 0. Questa procedura consente di copiare tutte e cinque le colonne, tre con il formato personalizzato e due con il formato predefinito.
La funzione bcp_columns deve essere chiamata prima di chiamare bcp_setcolfmt.
È necessario chiamare bcp_setcolfmt una volta per ogni proprietà di ogni colonna del file utente.
Non è necessario copiare tutti i dati di un file utente nella tabella di SQL Server. Per ignorare una colonna, specificarne il formato dei dati impostando il parametro BCP_FMT_SERVER_COL su 0. Se si desidera ignorare una colonna, è necessario specificarne il tipo.
La funzione bcp_writefmt può essere utilizzata per rendere persistente la specifica del formato.
Supporto di bcp_setcolfmt per le caratteristiche avanzate di data e ora
I tipi utilizzati con la proprietà BCP_FMT_TYPE per i tipi di data/ora sono indicati in 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).