bcp_colfmt
Si applica a:
SQL Server database SQL di Azure Istanza gestita di SQL di Azure azure Synapse Analytics Analytics Platform System (PDW)
Specifica il formato di origine o di destinazione dei dati in un file utente. Se usato come formato di origine, bcp_colfmt specifica il formato di un file di dati esistente usato come origine dei dati in una copia bulk in una tabella di SQL Server. Se usato come formato di destinazione, il file di dati viene creato usando 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.
SQL Server 2005 (9.x) ha introdotto il supporto per i token del tipo di dati SQLXML e SQLUDT nel parametro eUserDataType .
Il parametro eUserDataType viene enumerato dai token del tipo di dati di SQL Server in sqlncli.h, non dagli enumeratori del tipo di dati ODBC C. Ad esempio, è possibile specificare una stringa di caratteri, il tipo ODBC SQL_C_CHAR, usando il tipo specifico di SQL Server SQLCHARACTER.
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 eUserDataType è SQLDECIMAL o SQLNUMERIC:
Se la colonna di origine non è decimale o numerica, viene utilizzata la precisione e la scala predefinite.
Se la colonna di origine è decimale o numerica, 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. Valori di lunghezza di indicatore validi 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 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.
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 devono 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 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 di tipo carattere e 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 usa l'indicatore di lunghezza, se presente o una sequenza 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, 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 cbUserData è 0 o un valore positivo, il sistema usa 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 usando il metodo che comporta la copia della quantità minima di dati.
Il valore cbUserData rappresenta il numero di byte dei dati. Se i dati di tipo carattere sono rappresentati da 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.
pUserDataTerm
Sequenza di caratteri di terminazione 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.
cbUserDataTerm
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 segnalata da SQLColumns.
Se questo valore è 0, la copia bulk ignora la colonna nel file di dati.
Valori restituiti
SUCCEED o FAIL.
Osservazioni:
La funzione bcp_colfmt 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_colfmt 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_colfmt cinque volte, con tre di queste chiamate impostando il formato personalizzato. Per le due chiamate rimanenti, impostare eUserDataType su 0 e impostare rispettivamente cbIndicator, cbUserData e cbUserDataTerm 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.
Per cbIndicator, un valore pari a 8 per indicare che un tipo di valore di grandi dimensioni è ora valido. 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 di qualsiasi chiamata a bcp_colfmt.
È necessario chiamare bcp_colfmt una volta per ogni colonna nel file utente.
La chiamata bcp_colfmt più volte per qualsiasi colonna di file utente genera un errore.
Non è necessario copiare tutti i dati di un file utente nella tabella di SQL Server. Per ignorare una colonna, specificare il formato dei dati per la colonna, impostando il parametro idxServerCol 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_colfmt per le caratteristiche avanzate di data e ora
Per informazioni sui tipi usati con il parametro eUserDataType per i tipi di data/ora, vedere 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).