bcp_setcolfmt
Si applica a:
SQL Server database SQL di Azure Istanza gestita di SQL di Azure azure Synapse Analytics Analytics Platform System (PDW)
La funzione bcp_setcolfmt sostituisce il bcp_colfmt. Nella specifica delle regole di confronto della colonna, è necessario usare la funzione bcp_setcolfmt . bcp_setbulkmode può essere usato per specificare più di un formato di 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 destinazione dei dati in un file utente. Se usato come formato di origine, bcp_setcolfmt specifica il formato di un file di dati esistente usato come origine dati di dati in una copia bulk in una tabella in SQL Server. Se usato come formato di destinazione, il file di dati viene creato usando 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.
field
Numero di colonna ordinale per cui viene impostata la proprietà.
property
Una delle costanti di 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. Ad esempio, è possibile specificare una stringa di caratteri, il tipo ODBC SQL_C_CHAR, usando il tipo SQLCHARACTER specifico di SQL Server. Per specificare la rappresentazione dei dati predefinita per il tipo di dati di SQL Server, impostare questo parametro su 0. Per una copia bulk di SQL Server in un file, quando BCP_FMT_TYPE è SQLDECIMAL o SQLNUMERIC, se la colonna di origine non è decimale o numerica, viene usata la precisione e la scala predefinite. In caso contrario, se la colonna di origine è decimale o numerica, viene utilizzata 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, questo potrebbe significare che viene generato un indicatore di lunghezza/null per precedere i dati in una copia da SQL Server o che l'indicatore è previsto nei dati copiati in SQL Server. Per i tipi di dati binari e carattere di SQL Server, BCP_FMT_DATA_LEN possono 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 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 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 alla proprietà . 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 nella 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 di 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 di file utente. Ad esempio, per modificare le impostazioni predefinite per tre colonne in un file di dati utente a cinque colonne, chiamare prima bcp_columns(5) e quindi chiamare bcp_setcolfmt cinque volte, con tre di queste chiamate impostando il formato personalizzato. Per le due chiamate rimanenti, impostare BCP_FMT_TYPE su 0 e impostare rispettivamente BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN e cbValue 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 nel 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 usata 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 specificati in Modifiche di copia bulk per i tipi di data e ora avanzati (OLE DB e ODBC).
Per altre informazioni, vedere Miglioramenti di data e ora (ODBC).