bcp_setcolfmt

Artikel
07/04/2024

Gilt für: SQL Server Azure SQL-Datenbank Azure SQL verwaltete Instanz Azure Synapse Analytics Analytics Platform System (PDW)

Die bcp_setcolfmt funktion ersetzt die bcp_colfmt. Bei der Angabe der Spaltensortierung muss die bcp_setcolfmt-Funktion verwendet werden. bcp_setbulkmode können verwendet werden, um mehr als ein Spaltenformat anzugeben.

Diese Funktion bietet einen flexiblen Ansatz für das Angeben des Spaltenformats in einem Massenkopiervorgang. Sie wird verwendet, um einzelne Spaltenformatattribute festzulegen. Jeder Aufruf von bcp_setcolfmt legt ein Spaltenformatattribut fest.

Die bcp_setcolfmt-Funktion gibt das Quell- oder Zielformat der Daten in einer Benutzerdatei an. Wenn bcp_setcolfmt als Quellformat verwendet wird, gibt bcp_setcolfmt das Format einer vorhandenen Datendatei an, die als Datenquelle in einer Massenkopie in einer Tabelle in SQL Server verwendet wird. Bei Verwendung als Zielformat wird die Datendatei mit den spaltenformaten erstellt, die mit bcp_setcolfmt angegeben sind.

Syntax

  
RETCODE bcp_setcolfmt (  
        HDBC hdbc,  
        INT field,  
        INT property,  
        void* pValue,  
        INT cbValue);

Argumente

hdbc
Das für den Massenkopiervorgang aktivierte ODBC-Verbindungshandle.

field
Die Spaltenordnungszahl, für die die Eigenschaft festgelegt wird

property
Eine der Eigenschaftskonstanten. Eigenschaftskonstanten werden in dieser Tabelle definiert.

Eigenschaft	Wert	Beschreibung
BCP_FMT_TYPE	BYTE	Der Datentyp dieser Spalte in der Benutzerdatei. Wenn die Daten nicht mit dem Datentyp der entsprechenden Spalte in der Datenbanktabelle übereinstimmen, werden die Daten, wenn möglich, durch das Massenkopieren konvertiert. Der BCP_FMT_TYPE-Parameter wird von den SQL Server-Datentyptoken in sqlncli.h anstelle der ODBC C-Datentypenumeratoren aufgelistet. Sie können z. B. eine Zeichenfolge, einen ODBC-Typ SQL_C_CHAR, mithilfe des sqlCHARACTER-Typs angeben, der für SQL Server spezifisch ist. Um die Standarddatendarstellung für den SQL Server-Datentyp anzugeben, legen Sie diesen Parameter auf 0 fest. Bei einer Massenkopie aus SQL Server in eine Datei, wenn BCP_FMT_TYPE SQLDECIMAL oder SQLNUMERIC ist, wenn die Quellspalte nicht dezimal oder numerisch ist, werden die Standardgenauigkeit und -skalierung verwendet. Andernfalls wird die Genauigkeit und Skalierung der Quellspalte verwendet, wenn die Quellspalte dezimal oder numerisch ist.
BCP_FMT_INDICATOR_LEN	INT	Die Länge des Indikators (Präfix) in Bytes Die Länge eines Längen-/NULL-Indikators innerhalb der Spaltendaten in Bytes. Gültige Indikatorlängenwerte sind 0 (wenn kein Indikator verwendet wird), 1, 2 oder 4. Legen Sie diesen Parameter auf SQL_VARLEN_DATA fest, um die Verwendung eines standardmäßigen Massenkopierindikators anzugeben. Indikatoren werden im Speicher direkt vor allen anderen Daten angezeigt. In der Datendatei werden sie direkt vor den Daten, auf die sie sich beziehen, angezeigt. Wird mehr als eine Methode zur Angabe der Länge der Datendateispalte verwendet (z. B. ein Indikator und eine maximale Spaltenlänge oder ein Indikator und eine Abschlusszeichensequenz), wird beim Massenkopieren die Methode ausgewählt, die zu der kleineren zu kopierenden Datenmenge führt. Datendateien, die durch Massenkopieren generiert wurden, wobei das Datenformat nicht durch Benutzereingriff angepasst wird, enthalten Indikatoren, wenn die Spaltendaten eine unterschiedliche Länge haben oder die Spalte NULL als Wert akzeptieren kann.
BCP_FMT_DATA_LEN	DBINT	Die Länge der Daten (Spaltenlänge) in Bytes Dies ist die maximale Länge (in Bytes) der Daten dieser Spalte in der Benutzerdatei, ohne die Länge eines Längenindikators oder Abschlusszeichens. Durch Festlegen von BCP_FMT_DATA_LEN auf SQL_NULL_DATA wird angegeben, dass alle Werte in der Datendateispalte auf NULL festgelegt sind oder sein sollten. Wird BCP_FMT_DATA_LEN auf SQL_VARLEN_DATA festgelegt, bedeutet dies, dass das System die Länge der Daten für jede Spalte bestimmen soll. Bei einigen Spalten kann dies bedeuten, dass ein Längen-/NULL-Indikator generiert wird, um Daten einer Kopie aus SQL Server vorauszugehen, oder dass der Indikator in Daten in SQL Server kopiert wird. Bei SQL Server-Zeichen- und Binärdatentypen kann BCP_FMT_DATA_LEN SQL_VARLEN_DATA, SQL_NULL_DATA, 0 oder ein positiver Wert sein. Wenn BCP_FMT_DATA_LEN auf SQL_VARLEN_DATA festgelegt ist, verwendet das System entweder den Längenindikator, sofern vorhanden, oder eine Abschlusszeichensequenz, um die Länge der Daten zu bestimmen. Wenn sowohl ein Längenindikator als auch eine Abschlusszeichensequenz angegeben sind, wird beim Massenkopieren der Wert verwendet, der zu der kleineren zu kopierenden Datenmenge führt. Wenn BCP_FMT_DATA_LEN SQL_VARLEN_DATA ist, handelt es sich beim Datentyp um ein SQL Server-Zeichen oder einen binären Typ, und weder ein Längenindikator noch eine Terminatorsequenz wird angegeben, gibt das System eine Fehlermeldung zurück. Wenn BCP_FMT_DATA_LEN 0 oder ein positiver Wert ist, verwendet das System BCP_FMT_DATA_LEN als maximale Datenlänge. Wenn jedoch zusätzlich zu einem positiven BCP_FMT_DATA_LEN-Wert ein Längenindikator oder eine Abschlusszeichensequenz angegeben ist, bestimmt das System die Datenlänge mithilfe der Methode, die zu der kleineren zu kopierenden Datenmenge führt. Der BCP_FMT_DATA_LEN-Wert stellt die Anzahl der Datenbytes dar. Werden Zeichendaten durch Unicode-Zeichen dargestellt, repräsentiert ein positiver BCP_FMT_DATA_LEN-Parameterwert die Anzahl der Zeichen multipliziert mit der Größe (in Bytes) der einzelnen Zeichen.
BCP_FMT_TERMINATOR	LPCBYTE	Zeiger auf die Abschlusszeichensequenz (entweder ANSI oder Unicode), die für diese Spalte verwendet werden soll. Dieser Parameter ist in erster Linie für Zeichendatentypen nützlich, da alle anderen Typen eine feste Länge besitzen oder, im Falle von Binärdaten, einen Indikator für die Länge erfordern, um die Anzahl der vorhandenen Bytes präzise zu erfassen. Legen Sie diesen Parameter auf NULL fest, um zu vermeiden, dass extrahierte Daten terminiert werden, oder um anzugeben, dass Daten in einer Benutzerdatei nicht terminiert werden. Wird mehr als eine Methode zur Angabe der Länge der Benutzerdateispalte verwendet (z. B. ein Abschlusszeichen und ein Längenindikator oder ein Abschlusszeichen und eine maximale Spaltenlänge), wird beim Massenkopieren die Methode ausgewählt, die zu der kleineren zu kopierenden Datenmenge führt. Die API für das Massenkopieren führt nach Bedarf eine Zeichenkonvertierung von Unicode in MBCS aus. Stellen Sie unbedingt sicher, dass sowohl die Bytezeichenfolge des Abschlusszeichens und die Länge der Bytezeichenfolge richtig festgelegt werden.
BCP_FMT_SERVER_COL	INT	Die Position einer Spalte innerhalb der Datenbank
BCP_FMT_COLLATION	LPCSTR	Sortierungsname.

pValue
Ist der Zeiger auf den Wert, der der Eigenschaft zugeordnet werden soll. Er ermöglicht es, jede Spaltenformateigenschaft einzeln festzulegen.

cbvalue
Die Länge des Puffers der Eigenschaft in Bytes.

Gibt zurück

SUCCEED oder FAIL.

Hinweise

Diese Funktion ersetzt die funktion bcp_colfmt . Alle Funktionen von bcp_colfmt werden in bcp_setcolfmt Funktion bereitgestellt. Zusätzlich wird auch Unterstützung für Spaltensortierung bereitgestellt. Es wird empfohlen, die folgenden Spaltenformatattribute in der unten gegebenen Reihenfolge festzulegen:

BCP_FMT_SERVER_COL

BCP_FMT_DATA_LEN

BCP_FMT_TYPE

Mit der funktion bcp_setcolfmt können Sie das Benutzerdateiformat für Massenkopien angeben. Für Massenkopieren besteht ein Format aus folgenden Bestandteilen:

Eine Zuordnung von Benutzerdateispalten zu Datenbankspalten
Der Datentyp der einzelnen Benutzerdateispalten
Die Länge des optionalen Indikators für jede Spalte
Die maximale Länge der Daten pro Benutzerdateispalte
Die optionale abschließende Bytesequenz für jede Spalte
Die Länge der optionalen abschließenden Bytesequenz

Jeder Aufruf von bcp_setcolfmt gibt das Format für eine Benutzerdateispalte an. Wenn Sie beispielsweise die Standardeinstellungen für drei Spalten in einer Datendatei mit fünf Spalten ändern möchten, rufen Sie zuerst bcp_columns(5) auf, und rufen Sie dann bcp_setcolfmt fünf Mal auf, wobei drei dieser Anrufe ihr benutzerdefiniertes Format festlegen. Legen Sie für die verbleibenden beiden Aufrufe BCP_FMT_TYPE auf 0 fest, und legen Sie BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN und cbValue auf 0, SQL_VARLEN_DATA bzw. 0 fest. Mit diesem Verfahren werden alle fünf Spalten kopiert, drei mit dem benutzerdefinierten Format und zwei mit dem Standardformat.

Die bcp_columns-Funktion muss aufgerufen werden, bevor bcp_setcolfmt aufgerufen wird.

Sie müssen bcp_setcolfmt einmal für jede Eigenschaft jeder Spalte in der Benutzerdatei aufrufen.

Sie müssen nicht alle Daten in einer Benutzerdatei in eine SQL Server-Tabelle kopieren. Um eine Spalte zu überspringen, geben Sie das Format der Daten für die Spalte an, indem Sie den BCP_FMT_SERVER_COL-Parameter auf 0 festlegen. Wenn Sie eine Spalte überspringen möchten, müssen Sie ihren Typ angeben.

Die bcp_writefmt-Funktion kann verwendet werden, um die Formatspezifikation beizubehalten.

bcp_setcolfmt-Unterstützung für erweiterte Funktionen für Datum und Uhrzeit

Die Typen, die mit der BCP_FMT_TYPE-Eigenschaft für Datums-/Uhrzeittypen verwendet werden, sind in " Massenkopieänderungen für erweiterte Datums- und Uhrzeittypen (OLE DB und ODBC)" angegeben.

Weitere Informationen finden Sie unter "Datums- und Uhrzeitverbesserungen (ODBC)".

Weitere Informationen

Massenkopierfunktionen

Teilen über