bcp_setcolfmt

Articolo
01/10/2024

Si applica a: SQL Server Azure SQL Database 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 colonna.

La funzione bcp_setcolfmt specifica il formato di origine o di destinazione dei dati in un file utente. Quando viene usato come formato di origine, bcp_setcolfmt specifica il formato di un file di dati esistente usato come origine dati in una copia bulk in una tabella in SQL Server. Quando viene 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.

Campo
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 per SQL Server. Per specificare la rappresentazione dei dati predefinita per il tipo di dati 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 scalabilità predefinita. In caso contrario, se la colonna di origine è decimale o numerica, viene usata 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 un indicatore di lunghezza/null viene generato per precedere i dati in una copia da SQL Server o che l'indicatore è previsto nei dati copiati in SQL Server. Per SQL Server tipi di dati binari e caratteri, 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 SQL Server carattere o binario e non viene specificato alcun 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à.

Restituisce

SUCCEED o FAIL.

Commenti

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 usati con la proprietà BCP_FMT_TYPE per i tipi di data/ora sono specificati in 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).

Vedere anche

Funzioni di copia bulk