bcp_colfmt

Artikel
01/10/2024

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

Gibt das Quell- oder Zielformat der Daten in einer Benutzerdatei an. Bei Verwendung als Quellformat gibt bcp_colfmt das Format einer vorhandenen Datendatei an, die als Datenquelle in einem Massenkopiervorgang in eine SQL Server Tabelle verwendet wird. Bei Verwendung als Zielformat wird die Datendatei mit den spaltenformaten erstellt, die mit bcp_colfmt angegeben sind.

Syntax

  
RETCODE bcp_colfmt (  
        HDBC hdbc,  
        INT idxUserDataCol,  
        BYTE eUserDataType,  
        INT cbIndicator,  
        DBINT cbUserData,  
        LPCBYTE pUserDataTerm,  
        INT cbUserDataTerm,  
        INT idxServerCol);

Argumente

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

idxUserDataCol
Die Ordnungsnummer der Spalte in der Benutzerdatendatei, für die das Format angegeben wird. Die erste Spalte ist 1.

eUserDataType
Der Datentyp dieser Spalte in der Benutzerdatei. Wenn sich der Datentyp der entsprechenden Spalte in der Datenbanktabelle (idxServerColumn) unterscheidet, werden die Daten nach Möglichkeit per Massenkopiervorgang konvertiert.

SQL Server 2005 (9.x) wurde die Unterstützung für SQLXML- und SQLUDT-Datentyptoken im eUserDataType-Parameter eingeführt.

Der eUserDataType-Parameter wird von den SQL Server Datentyptoken in sqlncli.h und nicht von den ODBC C-Datentypen aufgezählt. Sie können beispielsweise eine Zeichenfolge, den ODBC-Typ SQL_C_CHAR, mithilfe des SQL Server-spezifischen Typs SQLCHARACTER angeben.

Legen Sie diesen Parameter auf 0 fest, um die Standarddatendarstellung für den Datentyp SQL Server anzugeben.

Für einen Massenkopiervorgang aus SQL Server in eine Datei, wenn eUserDataType SQLDECIMAL oder SQLNUMERIC ist:

Wenn die Quellspalte nicht dezimal oder numerisch ist, werden die Standardgenauigkeit und -skalierung verwendet.
Wenn die Quellspalte dezimal oder numerisch ist, werden die Genauigkeit und skalierung der Quellspalte verwendet.

cbIndicator
Die Länge eines Längen-/NULL-Indikators innerhalb der Spaltendaten in Byte. Gültige Indikatorlängenwerte sind 0 (wenn kein Indikator verwendet wird), 1, 2, 4 oder 8.

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.

cbUserData
Die maximale Länge (in Byte) der Daten dieser Spalte in der Benutzerdatei, ohne die Länge eines Längenindikators oder Abschlusszeichens.

Das Festlegen von cbUserData auf SQL_NULL_DATA gibt an, dass alle Werte in der Datendateispalte null sind oder festgelegt werden sollen.

Das Festlegen von cbUserData auf SQL_VARLEN_DATA gibt an, dass das System die Länge der Daten in jeder Spalte bestimmen soll. Für einige Spalten kann dies bedeuten, dass ein Längen-/NULL-Indikator generiert wird, der daten auf einer Kopie aus SQL Server vorangestellt wird, oder dass der Indikator in Daten erwartet wird, die in SQL Server kopiert werden.

Für SQL Server Zeichen- und Binärdatentypen kann cbUserData SQL_VARLEN_DATA, SQL_NULL_DATA, 0 oder ein positiver Wert sein. Wenn cbUserData SQL_VARLEN_DATA 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 cbUserData SQL_VARLEN_DATA ist, der Datentyp ein SQL Server Zeichen- oder Binärtyp ist und weder ein Längenindikator noch eine Abschlusszeichensequenz angegeben wird, gibt das System eine Fehlermeldung zurück.

Wenn cbUserData 0 oder ein positiver Wert ist, verwendet das System cbUserData als maximale Datenlänge. Wenn jedoch zusätzlich zu einem positiven cbUserData-Wert ein Längenindikator oder eine Abschlusszeichensequenz angegeben ist, bestimmt das System die Datenlänge mit der Methode, die zu der kleineren zu kopierenden Datenmenge führt.

Der cbUserData -Wert stellt die Anzahl der Datenbytes dar. Werden Zeichendaten durch Unicode-Zeichen dargestellt, repräsentiert ein positiver cbUserData -Parameterwert die Anzahl der Zeichen multipliziert mit der Größe (in Byte) der einzelnen Zeichen.

pUserDataTerm
Die Abschlusszeichensequenz, 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.

cbUserDataTerm
Die Länge (in Byte) der Abschlusszeichensequenz, die für diese Spalte verwendet werden soll. Wenn kein Abschlusszeichen vorhanden ist oder in den Daten gewünscht wird, legen Sie diesen Wert auf 0 fest.

idxServerCol
Die Ordnungsposition der Spalte in der Datenbanktabelle. Die erste Spaltennummer ist 1. Die Ordnungsposition einer Spalte wird von SQLColumnsausgegeben.

Wenn dieser Wert 0 ist, wird beim Massenkopieren die Spalte in der Datendatei ignoriert.

Gibt zurück

SUCCEED oder FAIL.

Bemerkungen

Mit der funktion bcp_colfmt können Sie das Format der Benutzerdatei 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_colfmt gibt das Format für eine Benutzerdateispalte an. Wenn Sie beispielsweise die Standardeinstellungen für drei Spalten in einer fünfspaltigen Benutzerdatendatei ändern möchten, rufen Sie zuerst bcp_columns(5) auf, und rufen Sie dann bcp_colfmt fünfMal auf, wobei drei dieser Aufrufe Ihr benutzerdefiniertes Format festlegen. Legen Sie für die verbleibenden beiden Aufrufe eUserDataType auf 0 und cbIndicator, cbUserData und cbUserDataTerm 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.

Für cbIndicator ist der Wert 8, der angibt, dass ein großer Werttyp jetzt gültig ist. Wenn das Präfix für ein Feld angegeben wird, dessen entsprechende Spalte den neuen max-Typ aufweist, kann dafür nur 8 festgelegt werden. Weitere Informationen finden Sie unter bcp_bind.

Die bcp_columns-Funktion muss vor jedem Aufruf von bcp_colfmt aufgerufen werden.

Sie müssen bcp_colfmt einmal für jede Spalte in der Benutzerdatei aufrufen.

Wenn sie bcp_colfmt für jede Benutzerdateispalte mehrmals aufrufen, wird ein Fehler verursacht.

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, und legen Sie den Parameter idxServerCol auf 0 fest. 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_colfmt'-Unterstützung für erweiterte Funktionen für Datum und Uhrzeit

Informationen zu den Typen, die mit dem eUserDataType-Parameter für Datums-/Uhrzeittypen verwendet werden, finden Sie unter Massenkopieränderungen für erweiterte Datums- und Uhrzeittypen (OLE DB und ODBC).

Weitere Informationen finden Sie unter Verbesserungen an Datum und Uhrzeit (ODBC).

Weitere Informationen

Bulk Copy Functions

Share via