bcp_bind

Artikel
07/04/2024

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

Bindet Daten aus einer Programmvariable an eine Tabellenspalte für die Massenkopie 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 den Massenkopiervorgang 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 NULL pData gibt an, dass lange Datenwerte mithilfe von bcp_moretext in Blöcken an SQL Server gesendet werden. Der Benutzer sollte pData nur auf NULL festlegen, wenn die Spalte, die dem benutzergebundenen Feld entspricht, eine BLOB-Spalte ist, andernfalls schlägt bcp_bind fehl.

Falls Indikatoren in den Daten vorhanden sind, stehen sie im Speicher direkt vor den Daten. Der pData-Parameter verweist in diesem Fall auf die Indikatorvariable, und die Breite des Indikators, der cbIndicator-Parameter , wird von massenkopie verwendet, um Benutzerdaten korrekt zu adressieren.

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. Die folgende Strukturtypdefinition kann beispielsweise verwendet werden, um ganzzahlige Werte in eine SQL Server-Tabelle mithilfe einer Massenkopie einzufügen:

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

Im Beispielfall würde der pData-Parameter auf die Adresse einer deklarierten Instanz der Struktur festgelegt werden, die Adresse des BCPBOUNDINT iIndicator-Strukturelements . Der cbIndicator-Parameter wird auf die Größe einer ganzen Zahl (sizeof(int)) festgelegt, und der cbData-Parameter wird erneut auf die Größe einer ganzen Zahl (sizeof(int)) festgelegt. Um eine Zeile in massenweise auf den Server zu kopieren, der einen NULL-Wert für die gebundene Spalte enthält, sollte der Wert des iIndicator-Members 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.

Das Festlegen von cbData auf SQL_NULL_DATA bedeutet, dass alle zeilen, die auf den Server kopiert wurden, einen NULL-Wert für die Spalte enthalten.

Wenn cbData auf SQL_VARLEN_DATA festgelegt wird, wird angegeben, dass das System einen Zeichenfolgenendpunkt oder eine andere Methode verwendet, 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 sicher SQL_VARLEN_DATA oder die Länge der Daten sein.

Bei SQL Server-Zeichen- und Binären Datentypen kann cbData SQL_VARLEN_DATA, SQL_NULL_DATA, ein positiver Wert oder 0 sein. Wenn cbData SQL_VARLEN_DATA ist, verwendet das System entweder einen Längen-/Nullindikator (sofern vorhanden) oder eine Terminatorsequenz, 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 SQL_VARLEN_DATA ist, handelt es sich bei dem Datentyp der Spalte um ein SQL Server-Zeichen oder einen Binärtyp, und weder ein Längenindikator noch eine Terminatorsequenz wird angegeben, 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 Terminatorsequenz bereitgestellt wird, bestimmt das System die Datenlänge mithilfe der Methode, die zu der geringsten Datenmenge führt, die kopiert wird.

Der Wert des cbData-Parameters stellt die Anzahl der Bytes von Daten dar. Wenn Zeichendaten durch Unicode-Breite zeichen dargestellt werden, stellt ein positiver cbData-Parameterwert die Anzahl von Zeichen dar, die mit der Größe in Bytes jedes Zeichens multipliziert werden.

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 für die Variable kein Terminator 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 leere Zeichenfolge mit NULL-Zeichenfolge ein einzelnes Byte (das Endatorbyte selbst) darstellt, legen Sie cbTerm auf 1 fest. Um beispielsweise anzugeben, dass die Zeichenfolge in szName null-terminated ist und dass der Terminator verwendet werden soll, um die Länge anzugeben:

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

Eine nicht bestimmte Form dieses Beispiels könnte darauf hinweisen, dass 15 Zeichen aus der szName-Variablen in die zweite Spalte der gebundenen Tabelle kopiert werden:

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. Um beispielsweise anzugeben, dass die Zeichenfolge in szName eine Unicode-breite Zeichenfolge ist, die durch den Unicode-Null-Endatorwert beendet wird:

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

Wenn die gebundene SQL Server-Spalte breit ist, wird für bcp_sendrow keine Konvertierung ausgeführt. Wenn die SQL Server-Spalte ein MBCS-Zeichentyp ist, wird die Konvertierung von breitem Zeichen in Multibyte ausgeführt, wenn die Daten an SQL Server gesendet werden.

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

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

Der Parameter "eDataType " wird von den SQL Server-Datentyptoken in "sqlncli.h" und nicht von den ODBC-C-Datentypen aufgezählt. Sie können z. B. eine ganzzahlige Zahl mit zwei Byte, ODBC-Typ SQL_C_SHORT, mithilfe des SQL Server-spezifischen Typs SQLINT2 angeben.

SQL Server 2005 (9.x) hat unterstützung für SQLXML- und SQLUDT-Datentyptoken im eDataType-Parameter eingeführt.

Die folgende Tabelle führt gültige enumerierte Datentypen und die entsprechenden ODBC-C-Datentypen auf.

eDataType	C-Typ
SQLTEXT	char *
SQLNTEXT	wchar_t *
SQLCHARACTER	char *
SQLBIGCHAR	char *
SQLVARCHAR	char *
SQLBIGVARCHAR	char *
SQLNCHAR	wchar_t *
SQLNVARCHAR	wchar_t *
SQLBINARY	unsigned char *
SQLBIGBINARY	unsigned char *
SQLVARBINARY	unsigned char *
SQLBIGVARBINARY	unsigned char *
SQLBIT	char
SQLBITN	char
SQLINT1	char
SQLINT2	short int
SQLINT4	int
SQLINT8	_int64
SQLINTN	cbIndicator 1: SQLINT1 2: SQLINT2 4: SQLINT4 8: SQLINT8
SQLFLT4	float
SQLFLT8	float
SQLFLTN	cbIndicator 4: SQLFLT4 8: SQLFLT8
SQLDECIMALN	SQL_NUMERIC_STRUCT
SQLNUMERICN	SQL_NUMERIC_STRUCT
SQLMONEY	DBMONEY
SQLMONEY4	DBMONEY4
SQLMONEYN	cbIndicator 4: SQLMONEY4 8: SQLMONEY
SQLTIMEN	SQL_SS_TIME2_STRUCT
SQLDATEN	SQL_DATE_STRUCT
SQLDATETIM4	DBDATETIM4
SQLDATETIME	DBDATETIME
SQLDATETIMN	cbIndicator 4: SQLDATETIM4 8: SQLDATETIME
SQLDATETIME2N	SQL_TIMESTAMP_STRUCT
SQLDATETIMEOFFSETN	SQL_SS_TIMESTAMPOFFSET_STRUCT
SQLIMAGE	unsigned char *
SQLUDT	unsigned char *
SQLUNIQUEID	SQLGUID
SQLVARIANT	Jeder Datentyp außer: -Text - ntext -Bild - varchar(max) - varbinary(max) - nvarchar(max) - xml - timestamp
SQLXML	Unterstützte C-Datentypen: - char* - wchar_t * - unsigned char *

idxServerCol Ist 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 SQLColumnsausgegeben.

Gibt zurück

SUCCEED oder FAIL.

Hinweise

Verwenden Sie bcp_bind für eine schnelle, effiziente Möglichkeit, Daten aus einer Programmvariable in eine Tabelle in SQL Server zu kopieren.

Rufen Sie bcp_init auf, bevor Sie diese oder eine andere Massenkopiefunktion aufrufen. Durch Aufrufen bcp_init wird die SQL Server-Zieltabelle für die Massenkopie festgelegt. Beim Aufrufen von bcp_init für die Verwendung mit bcp_bind und bcp_sendrow wird der parameter bcp_init szDataFile, der die Datendatei angibt, auf NULL festgelegt. Der parameter bcp_initeDirection wird auf DB_IN festgelegt.

Erstellen Sie einen separaten bcp_bind Aufruf für jede Spalte in der SQL Server-Tabelle, in die Sie kopieren möchten. Nachdem die erforderlichen bcp_bind Aufrufe durchgeführt wurden, rufen Sie bcp_sendrow auf, um eine Datenzeile aus Den Programmvariablen an SQL Server zu senden. Das erneute Binden einer Spalte wird nicht unterstützt.

Wenn SQL Server die bereits empfangenen Zeilen übernehmen soll, rufen Sie bcp_batch auf. Rufen Sie beispielsweise bcp_batch einmal für alle eingefügten 1000 Zeilen oder in einem anderen Intervall auf.

Wenn keine zeilen mehr eingefügt werden sollen, rufen Sie bcp_done auf. Andernfalls wird ein Fehler ausgelöst.

Steuerelementparametereinstellungen, die mit bcp_control angegeben wurden, wirken sich nicht auf bcp_bind Zeilenübertragungen aus.

Wenn pData für eine Spalte auf NULL festgelegt ist, da ihr Wert durch Aufrufe an bcp_moretext bereitgestellt wird, müssen alle nachfolgenden Spalten mit eDataType auf SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR oder SQLIMAGE ebenfalls mit pData gebunden werden, die auf NULL festgelegt sind, und ihre Werte müssen auch durch Aufrufe von bcp_moretext bereitgestellt werden.

Für neue große Werttypen, z . B. varchar(max), varbinary(max), oder nvarchar(max), können Sie SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY und SQLNCHAR als Typindikatoren im eDataType-Parameter verwenden.

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

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

0xFFFFFFFFFFFFFFFF bedeutet einen NULL-Wert für das Feld.
0xFFFFFFFFFFFFFFFE wird als spezieller Präfixwert behandelt, der zum effizienten Senden von Daten in Datenblöcken an den Server verwendet wird. Die Daten mit diesem speziellen Präfix weisen das folgende Format auf:
<><SPECIAL_PREFIX 0 oder mehr DATENBLÖCKE><ZERO_CHUNK>:
SPECIAL_PREFIX 0xFFFFFFFFFFFFFFFE entspricht.
DATA_CHUNK ist ein 4-Byte-Präfix, das die Länge des Abschnitts enthält, gefolgt von den tatsächlichen Daten, deren Länge im Präfix 4 Byte angegeben ist.
ZERO_CHUNK ist ein 4-Byte-Wert mit allen Nullen (000000000), der das Ende der Daten angibt.
Alle anderen gültigen 8-Byte-Längen werden als normale Datenlänge behandelt.

Das Aufrufen bcp_columns bei Verwendung von bcp_bind führt zu einem Fehler.

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

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

Weitere Informationen finden Sie unter "Datums- und 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);

Weitere Informationen

Massenkopierfunktionen

Freigeben über