IBCPSession::BCPColFmt (OLE DB)

Erstellt eine Bindung zwischen Programmvariablen und SQL Server-Spalten. 

Syntax

HRESULT BCPColFmt( 
      DBORDINAL idxUserDataCol,
      int eUserDataType,
      int cbIndicator,
      int cbUserData,
      BYTE *pbUserDataTerm,
      int cbUserDataTerm,
      DBORDINAL idxServerCol);

Hinweise

Die BCPColFmt-Methode wird verwendet, um eine Bindung zwischen BCP-Datendateifeldern und SQL Server-Spalten zu erstellen. Sie nimmt Länge, Typ, Abschlusszeichen und Präfixlänge einer Spalte als Parameter auf und legt jede dieser Eigenschaften für einzelne Felder fest.

Wenn der Benutzer die interaktive Methode wählt, wird diese Methode zweimal aufgerufen: einmal zum Festlegen des Spaltenformats den Standardwerten entsprechend (die sich nach dem Typ der Serverspalte richten) und einmal, um das Format für jede Spalte dem Spaltentyp der Wahl des Clients entsprechend festzulegen, der im interaktiven Modus ausgewählt wurde.

In nicht interaktiven Modi wird die Methode nur einmal pro Spalte aufgerufen, um den Typ der einzelnen Spalten auf den Zeichen- oder systemeigenen Typ festzulegen und die Spalten- und Zeilenabschlusszeichen festzulegen.

Mit der BCPColFmt-Methode können Sie das Benutzerdateiformat für Massenkopieren angeben. Für Massenkopieren besteht ein Format aus folgenden Bestandteilen:

• Eine Zuordnung von Benutzerdateifeldern zu Datenbankspalten

• Der Datentyp der einzelnen Benutzerdateifelder

• Die Länge des optionalen Indikators für jedes Feld

• Die maximale Länge der Daten pro Benutzerdateifeld

• Die optionale abschließende Bytesequenz für jedes Feld

• Die Länge der optionalen abschließenden Bytesequenz

Jeder Aufruf von BCPColFmt gibt das Format für ein Benutzerdateifeld an. Um die Standardeinstellungen für drei Felder in einer aus fünf Feldern bestehenden Benutzerdatendatei zu ändern, rufen Sie zuerst BCPColumns(5) auf und anschließend fünf Mal BCPColFmt, wobei mit drei dieser Aufrufe Ihr bentuzerdefiniertes Format festgelegt wird. Legen Sie für die restlichen zwei Aufrufe eUserDataType auf BCP_TYPE_DEFAULT und cbIndicator, cbUserData und cbUserDataTerm auf 0, BCP_VARIABLE_LENGTH bzw. 0 fest. Mit diesem Verfahren werden alle fünf Spalten kopiert, drei mit dem benutzerdefinierten Format und zwei mit dem Standardformat.

Hinweis
Die IBCPSession::BCPColumns-Methode muss vor einem Aufruf von BCPColFmt aufgerufen werden. Sie müssen BCPColFmt einmal für jede Spalte in der Benutzerdatei aufrufen. Wird BCPColFmt mehr als einmal für eine Benutzerdateispalte aufgerufen, tritt ein Fehler auf.

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 idxServerCol-Parameter auf 0 festlegen. Um ein Feld zu überspringen, sind dennoch alle Informationen erforderlich, damit die Methode ordnungsgemäß funktioniert.

Hinweis Mit der IBCPSession::BCPWriteFmt-Funktion kann die über BCPColFmt zur Verfügung gestellte Formatspezifikation persistent gespeichert werden.

Argumente

• idxUserDataCol[in]
  Der Feldindex in der Datendatei des Benutzers

• eUserDataType[in]
  Der Felddatentyp in der Datendatei des Benutzers. Die verfügbaren Datentypen werden in der SQL Server Native Client-Headerdatei (sqlncli.h) im Format BCP_TYPE_XXX aufgeführt, z. B. BCP_TYPE_SQLINT4. Ist der BCP_TYPE_DEFAULT-Wert festgelegt, versucht der Anbieter den gleichen Typ zu verwenden wie der Tabellen- oder Sichtspaltentyp. Für Massenkopiervorgänge aus SQL Server in eine Datei, wenn das eUserDataType-Argument BCP_TYPE_SQLDECIMAL oder BCP_TYPE_SQLNUMERIC lautet, gilt:

  • Wenn die Quellspalte nicht dezimal oder numerisch ist, werden die Standardgenauigkeit und die Standardanzahl von Dezimalstellen verwendet.

  • Wenn die Quellspalte dezimal oder numerisch ist, werden die Genauigkeit und die Anzahl von Dezimalstellen der Quellspalte verwendet.

• cbIndicator[in]
  Die Präfixlänge für das Feld. Der Standardwert ist BCP_PREFIX_DEFAULT. Gültige Präfixlängen sind 0, 1, 2, 4 und 8. Eine Präfixgröße von 8 wird üblicherweise verwendet, um anzugeben, dass das Feld segmentiert ist. Dies wird zum effizienten Massenkopieren von großen Werttypspalten verwendet.

• cbUserData[in]
  Die maximale Länge (in Byte) der Daten in diesem Feld der Benutzerdatei, ohne die Länge eines Längenindikators oder Abschlusszeichens

  Durch Festlegen von cbUserData auf BCP_LENGTH_NULL wird angegeben, dass alle Werte in den Datendateifeldern auf NULL festgelegt sind oder sein sollten. Ist cbUserData auf BCP_LENGTH_VARIABLE festgelegt, bedeutet dies, dass das System die Länge der Daten für jedes Feld bestimmen soll. Für einige Felder könnte dies bedeuten, dass ein Längen-/NULL-Indikator generiert wird, der den Daten in einer Kopie von SQL Server vorangestellt wird, oder dass der Indikator in Daten, die in SQL Server kopiert werden, erwartet wird.

  Für SQL Server-Zeichen und Binärdatentypen kann cbUserData BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0 oder ein positiver Wert sein. Wenn cbUserData auf BCP_LENGTH_VARIABLE 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 ist, wird beim Massenkopieren der Wert verwendet, der zu der kleineren zu kopierenden Datenmenge führt. Ist cbUserData auf BCP_LENGTH_VARIABLE festgelegt, ist der Datentyp ein SQL Server-Zeichen oder Binärtyp, und ist weder ein Längenindikator noch eine Abschlusszeichensequenz angegeben, 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.

• pbUserDataTerm[size_is] [in]
  Die Abschlusszeichensequenz, die für das Feld 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 Abschlusszeichenbyte-Zeichenfolge als auch die Länge der Bytezeichenfolge richtig festgelegt werden.

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

• idxServerCol[in]
  Die Ordnungsposition der Spalte innerhalb der Datenbanktabelle. Die erste Spaltennummer ist 1. Die Ordnungsposition einer Spalte wird von IColumnsInfo::GetColumnInfo oder ähnlichen Methoden gemeldet. Wenn dieser Wert 0 ist, wird beim Massenkopieren das Feld in der Datendatei ignoriert.

Rückgabecodewerte

• S_OK
  Die Methode wurde erfolgreich ausgeführt.

• E_FAIL
  Ein anwenderspezifischer Fehler ist aufgetreten. Ausführliche Informationen erhalten Sie über die ISQLServerErrorInfo-Schnittstelle.

• E_UNEXPECTED
  Die Methode wurde unerwartet aufgerufen. Die IBCPSession::BCPInit-Methode wurde beispielsweise erst nach dem Aufruf dieser Methode aufgerufen.

• E_INVALIDARG
  Das Argument war ungültig.

• E_OUTOFMEMORY
  Fehler aufgrund von nicht genügend Arbeitsspeicher.

Siehe auch

Konzepte

Durchführen von Massenkopiervorgängen

Andere Ressourcen

IBCPSession (OLE DB)