Freigeben über

bcp_bind

  • Artikel

Bindet Daten einer Programmvariablen an eine Tabellenspalte im Hinblick auf einen Massenkopiervorgang in SQL Server.

Syntax

RETCODE bcp_bind ( 
        HDBC hdbc,  
        LPCBYTE pData, 
        INT cbIndicator, 
        DBINT cbData, 
        LPCBYTE pTerm, 
        INT cbTerm, 
        INT eDataType, 
        INT idxServerCol);

Argumente

  • hdbc
    Das für das Massenkopieren aktivierte ODBC-Verbindungshandle.

  • pData
    Ein Zeiger auf die kopierten Daten. Wenn eDataType SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR oder SQLIMAGE ist, kann pData NULL sein. Ein pData-Zeiger mit dem Wert NULL gibt an, dass lange Datenwerte mithilfe von bcp_moretext in Segmenten an SQL Server gesendet werden. Der Benutzer sollte pData nur auf NULL festlegen, wenn die dem Benutzer-gebundenen Feld entsprechende Spalte eine BLOB-Spalte ist. Andernfalls generiert bcp_bind einen Fehler.

    Falls Indikatoren in den Daten vorhanden sind, stehen sie im Speicher direkt vor den Daten. Der pData-Parameter zeigt in diesem Fall auf die Indikatorvariable, und die Breite des Indikators, der cbIndicator-Parameter, wird vom Massenkopiervorgang verwendet, um die Benutzerdaten ordnungsgemäß zu verarbeiten.

  • cbIndicator
    Die Länge eines Längen- oder NULL-Indikators für die Spaltendaten in Byte. Gültige Indikatorlängenwerte sind 0 (wenn kein Indikator verwendet wird), 1, 2, 4 oder 8. Indikatoren stehen im Speicher direkt vor allen Daten. Beispielsweise könnte die folgende Strukturtypdefinition verwendet werden, um für einen Massenkopiervorgang Ganzzahlwerte in eine SQL Server-Tabelle einzufügen:

    typedef struct tagBCPBOUNDINT
    {
    int iIndicator;
    int Value;
    } BCPBOUNDINT;

    In diesem Beispiel würde der pData-Parameter auf die Adresse einer deklarierten Instanz der Struktur festgelegt werden, d. h. die Adresse des iIndicator-Strukturelements von BCPBOUNDINT. Der cbIndicator-Parameter würde auf die Größe einer ganzen Zahl (sizeof(int)) festgelegt werden, und der cbData-Parameter erneut auf die Größe einer ganzen Zahl (sizeof(int)). Zum Massenkopieren einer Zeile auf den Server, die einen NULL-Wert für die gebundene Spalte enthält, sollte der Wert des iIndicator-Elements der Instanz auf SQL_NULL_DATA festgelegt werden.

  • cbData
    Die Anzahl der Datenbytes in der Programmvariablen ohne die Länge eventuell vorhandener Längenindikatoren, NULL-Indikatoren oder Abschlusszeichen.

    Wenn Sie cbData auf SQL_NULL_DATA festlegen, bedeutet dies, dass alle auf den Server kopierten Zeilen einen NULL-Wert für die Spalte enthalten.

    Wenn Sie cbData auf SQL_VARLEN_DATA festlegen, geben Sie damit an, dass das System ein Zeichenfolgenabschlusszeichen oder eine andere Methode verwenden soll, um die Länge der kopierten Daten zu bestimmen.

    Bei Datentypen mit fester Länge wie ganzen Zahlen gibt der Datentyp dem System die Länge der Daten an. Daher kann cbData für Datentypen mit fester Länge problemlos auf SQL_VARLEN_DATA oder die Länge der Daten festgelegt werden.

    Für SQL Server-Zeichen- und Binärdatentypen kann cbData SQL_VARLEN_DATA, SQL_NULL_DATA, ein beliebiger positiver Wert oder 0 sein. Wenn cbData auf SQL_VARLEN_DATA festgelegt ist, verwendet das System entweder einen Längen-/NULL-Indikator, falls vorhanden, oder eine Abschlusszeichensequenz, um die Länge der Daten zu bestimmen. Wenn beide Indikatoren bereitgestellt werden, verwendet das System beim Massenkopieren den Wert, der zu der kleineren zu kopierenden Datenmenge führt. Wenn cbData auf SQL_VARLEN_DATA festgelegt, der Datentyp der Spalte ein SQL Server-Zeichen- oder Binärdatentyp, und weder ein Längenindikator noch eine Abschlusszeichensequenz angegeben ist, gibt das System eine Fehlermeldung zurück.

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

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

  • pTerm
    Ein Zeiger auf das Bytemuster, falls vorhanden, das das Ende dieser Programmvariablen markiert. Beispielsweise weisen ANSI- und MBCS-C-Zeichenfolgen normalerweise ein 1-Byte-Abschlusszeichen (\0) auf.

    Wenn kein Abschlusszeichen für die Variable vorhanden ist, legen Sie pTerm auf NULL fest.

    Sie können eine leere Zeichenfolge ("") verwenden, um das C-NULL-Abschlusszeichen als Programmvariablen-Abschlusszeichen festzulegen. Da die mit NULL endende leere Zeichenfolge ein einziges Byte (das Abschlusszeichenbyte selbst) aufweist, legen Sie cbTerm auf 1 fest. Wenn Sie beispielsweise angeben möchten, dass die Zeichenfolge in szName ein NULL-Abschlusszeichen aufweist und das Abschlusszeichen verwendet werden soll, um die Länge anzugeben, schreiben Sie folgenden Code:

    bcp_bind(hdbc, szName, 0,
   SQL_VARLEN_DATA, "", 1,
   SQLCHARACTER, 2)

    In einer abgewandelten Form dieses Beispiels ohne Abschlusszeichen könnte angegeben werden, dass 15 Zeichen von der szName-Variablen in die zweite Spalte der gebundenen Tabelle kopiert werden sollen:

    bcp_bind(hdbc, szName, 0, 15, 
   NULL, 0, SQLCHARACTER, 2)

    Die API für das Massenkopieren führt nach Bedarf eine Zeichenkonvertierung von Unicode in MBCS aus. Stellen Sie sicher, dass sowohl die Bytezeichenfolge des Abschlusszeichens als auch die Länge der Bytezeichenfolge richtig festgelegt sind. Wenn Sie beispielsweise angeben möchten, dass die Zeichenfolge in szName eine Unicode-Doppelbyte-Zeichenfolge mit dem Unicode-NULL-Abschlusszeichenwert sein soll, schreiben Sie folgenden Code:

    bcp_bind(hdbc, szName, 0, 
   SQL_VARLEN_DATA, L"",
   sizeof(WCHAR), SQLNCHAR, 2)

    Wenn die gebundene SQL Server-Spalte vom Typ Doppelbytezeichen ist, wird bei 'bcp_sendrow' keine Konvertierung ausgeführt. Wenn die SQL Server-Spalte vom Typ MBCS-Zeichen ist, wird eine Konvertierung von Doppelbytezeichen in Multibytezeichen durchgeführt, wenn die Daten an SQL Server gesendet werden.

  • cbTerm
    Anzahl von Bytes im Abschlusszeichen für die Programmvariable, falls vorhanden. Wenn kein Abschlusszeichen für die Variable vorhanden ist, legen Sie cbTerm auf 0 fest.

  • eDataType
    Der C-Datentyp der Programmvariablen. Die Daten in der Programmvariablen werden in den Typ der Datenbankspalte konvertiert. Wenn dieser Parameter 0 ist, wird keine Konvertierung ausgeführt.

    Der eDataType-Parameter wird von den SQL Server-Datentyptoken in sqlncli.h, nicht von den ODBC C-Datentypenumeratoren, aufgelistet. Beispielsweise können Sie eine 2-Byte-Ganzzahl, ODBC-Typ SQL_C_SHORT, angeben, indem Sie den SQL Server-spezifischen Typ SQLINT2 verwenden.

    Mit SQL Server 2005 wurde die Unterstützung für die Datentyptoken SQLXML und SQLUDT im eDataType-Parameter eingeführt.

  • idxServerCol
    Die Ordnungsposition der Spalte in der Datenbanktabelle, in die die Daten kopiert werden. Die erste Spalte einer Tabelle ist die Spalte 1. Die Ordnungsposition einer Spalte wird von SQLColumns ausgegeben.

Rückgabewerte

SUCCEED oder FAIL

Hinweise

Verwenden Sie bcp_bind als schnelle, effiziente Methode zum Kopieren von Daten von einer Programmvariablen in eine SQL Server-Tabelle.

Rufen Sie bcp_init auf, bevor Sie diese oder jede andere Funktion zum Massenkopieren aufrufen. Durch den Aufruf von bcp_init wird die SQL Server-Zieltabelle für den Massenkopiervorgang festgelegt. Wenn Sie bcp_init aufrufen, um anschließend bcp_bind und 'bcp_sendrow' zu verwenden, wird der bcp_init-szDataFile-Parameter, der die Datendatei angibt, auf NULL festgelegt, und der bcp_init-eDirection-Parameter auf DB_IN.

Führen Sie einen separaten Aufruf von bcp_bind für jede Spalte in der SQL Server-Tabelle aus, in die Daten kopiert werden sollen. Wenn alle erforderlichen Aufrufe von bcp_bind ausgeführt wurden, rufen Sie bcp_sendrow auf, um eine Datenzeile von Ihren Programmvariablen an SQL Server zu senden. Das erneute Binden einer Spalte wird nicht unterstützt.

Wenn Sie zu einem beliebigen Zeitpunkt möchten, dass SQL Server ein Commit für die bereits empfangenen Zeilen ausführt, rufen Sie bcp_batch auf. Rufen Sie bcp_batch beispielsweise nach dem Einfügen von jeweils 1000 Zeilen auf, oder wählen Sie ein beliebiges anderes Intervall.

Wenn keine weiteren einzufügenden Zeilen mehr vorhanden sind, rufen Sie 'bcp_done' auf. Andernfalls wird ein Fehler ausgelöst.

Steuerparametereinstellungen, die mit bcp_control angegeben werden, haben keine Auswirkung auf mit bcp_bind durchgeführte Zeilenübertragungen.

Wenn für eine Spalte pData auf NULL festgelegt wird, weil deren Wert durch Aufrufe von bcp_moretext bereitgestellt wird, müssen alle darauffolgenden Spalten, für die eDataType SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR oder SQLIMAGE ist, ebenfalls mit einem auf NULL festgelegten pData-Parameter gebunden werden, und deren Werte müssen ebenfalls durch Aufrufe von bcp_moretext bereitgestellt werden.

Für die neuen Datentypen für große Werte wie varchar(max), varbinary(max) und nvarchar(max) können Sie SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY und SQLNCHAR als Typindikatoren im eDataType-Parameter verwenden.

Wenn cbTerm nicht 0 ist, sind Werte von 1, 2, 4 oder 8 für das Präfix (cbIndicator) gültig. In diesem Fall sucht SQL Server Native Client das Abschlusszeichen, berechnet die Datenlänge in Bezug auf das Abschlusszeichen (i) und legt cbData auf den kleineren Wert von i und den Wert des Präfixes fest.

Wenn cbTerm 0 und cbIndicator (das Präfix) nicht 0 ist, muss cbIndicator8 sein. Das 8-Byte-Präfix kann die folgenden Werte annehmen:

  • 0xFFFFFFFFFFFFFFFF bedeutet einen NULL-Wert für das Feld.

  • 0xFFFFFFFFFFFFFFFE wird als spezieller Präfixwert behandelt und wird für die effiziente Übertragung von Datensegmenten an den Server verwendet. Die Daten mit diesem speziellen Präfix weisen das folgende Format auf:

  • <SPECIAL_PREFIX> <0 oder mehr DATA CHUNKS> <ZERO_CHUNK>, wobei:

  • SPECIAL_PREFIX 0xFFFFFFFFFFFFFFFE entspricht.

  • DATA_CHUNK ist ein 4-Byte-Präfix, das die Länge des Segments enthält, gefolgt von den Daten selbst, deren Länge in dem 4-Byte-Präfix angegeben ist.

  • ZERO_CHUNK ist ein 4-Byte-Wert, der alle Nullen (00000000) enthält, die das Ende der Daten angeben.

  • Jede andere gültige 8 Byte-Länge wird als reguläre Datenlänge behandelt.

Der Aufruf von bcp_columns mit bcp_bind löst einen Fehler aus.

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

Informationen zu diesen Typen und deren Verwendung mit dem eDataType-Parameter für Datums-/Uhrzeittypen finden Sie unter Massenkopieränderungen für verbesserte Datum-/Uhrzeittypen (OLE DB und ODBC).

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

Beispiel

#include sql.h
#include sqlext.h
#include odbcss.h
// Variables like henv not specified.
HDBC      hdbc;
char         szCompanyName[MAXNAME];
DBINT      idCompany;
DBINT      nRowsProcessed;
DBBOOL      bMoreData;
char*      pTerm = "\t\t";

// Application initiation, get an ODBC environment handle, allocate the
// hdbc, and so on.
... 

// Enable bulk copy prior to connecting on allocated hdbc.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_BCP, (SQLPOINTER) SQL_BCP_ON,
   SQL_IS_INTEGER);

// Connect to the data source; return on error.
if (!SQL_SUCCEEDED(SQLConnect(hdbc, _T("myDSN"), SQL_NTS,
   _T("myUser"), SQL_NTS, _T("myPwd"), SQL_NTS)))
   {
   // Raise error and return.
   return;
   }

// Initialize bcp. 
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL
   DB_IN) == FAIL)
   {
   // Raise error and return.
   return;
   }

// Bind program variables to table columns. 
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,
   SQLINT4, 1)    == FAIL)
   {
   // Raise error and return.
   return;
   }
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,
   (LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)
   {
   // Raise error and return.
   return;
   }

while (TRUE)
   {
   // Retrieve and process program data. 
   if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)
      {
      // Send the data. 
      if (bcp_sendrow(hdbc) == FAIL)
         {
         // Raise error and return.
         return;
         }
      }
   else
      {
      // Break out of loop.
      break;
      }
   }

// Terminate the bulk copy operation.
if ((nRowsProcessed = bcp_done(hdbc)) == -1)
   {
   printf_s("Bulk-copy unsuccessful.\n");
   return;
   }

printf_s("%ld rows copied.\n", nRowsProcessed);

Siehe auch

Verweis

Massenkopierfunktionen