bcp_bind
Gilt für:
SQL ServerAzure SQL-DatenbankAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)
Bindet Daten aus einer Programmvariablen an eine Tabellenspalte zum Massenkopieren 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-Wert gibt an, dass lange Datenwerte mithilfe von bcp_moretext an SQL Server in Blöcken 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 vom Massenkopiervorgang verwendet, um Benutzerdaten ordnungsgemäß 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 mithilfe von Massenkopiervorgängen in eine SQL Server Tabelle einzufügen:
typedef struct tagBCPBOUNDINT
{
int iIndicator;
int Value;
} BCPBOUNDINT;
Im Beispielfall wird der pData-Parameter auf die Adresse einer deklarierten Instanz der Struktur festgelegt, 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. 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.
Das Festlegen von cbData auf SQL_NULL_DATA bedeutet, dass alle auf den Server kopierten Zeilen einen NULL-Wert für die Spalte enthalten.
Das Festlegen von cbData auf SQL_VARLEN_DATA gibt an, dass das System einen Zeichenfolgenabschluss 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 bei Datentypen mit fester Länge sicher SQL_VARLEN_DATA oder die Länge der Daten sein.
Für SQL Server Zeichen- und Binärdatentypen 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-/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 SQL_VARLEN_DATA ist, der Datentyp der Spalte 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 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 wird, bestimmt das System die Datenlänge mithilfe der -Methode, die dazu führt, dass die geringste Datenmenge kopiert wird.
Der cbData-Parameterwert stellt die Anzahl der Byte von Daten dar. Wenn Zeichendaten durch Unicode-Breitzeichen dargestellt werden, stellt ein positiver cbData-Parameterwert die Anzahl der Zeichen dar, multipliziert mit der Größe in Byte jedes Zeichens.
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 leere Zeichenfolge mit NULL-Beendigung ein einzelnes Byte (das Abschlusszeichenbyte selbst) darstellt, legen Sie cbTerm auf 1 fest. Beispielsweise, um anzugeben, dass die Zeichenfolge in szName null-terminated ist und dass der Abschlusszeichen verwendet werden soll, um die Länge anzugeben:
bcp_bind(hdbc, szName, 0,
SQL_VARLEN_DATA, "", 1,
SQLCHARACTER, 2)
Eine nicht festgelegte Form dieses Beispiels kann darauf hindeuten, dass 15 Zeichen aus der Variablen szName 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-Breitzeichenzeichenfolge ist, die durch den Unicode-Nullabschlusswert beendet wird:
bcp_bind(hdbc, szName, 0,
SQL_VARLEN_DATA, L"",
sizeof(WCHAR), SQLNCHAR, 2)
Wenn die gebundene SQL Server Spalte Breitzeichen aufweist, wird für bcp_sendrow keine Konvertierung durchgeführt. Wenn die spalte SQL Server ein MBCS-Zeichentyp ist, wird beim Senden der Daten an SQL Server eine Breitzeichen-In-Multibyte-Zeichenkonvertierung ausgeführt.
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 und nicht von den ODBC C-Datentyp-Enumeratoren aufgezählt. Beispielsweise können Sie mit dem SQL Server-spezifischen Typ SQLINT2 eine ganzzahlige Zwei-Byte-Zahl angeben, den ODBC-Typ SQL_C_SHORT.
SQL Server 2005 (9.x) wurde die 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 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.
Bemerkungen
Verwenden Sie bcp_bind für eine schnelle und effiziente Möglichkeit zum Kopieren von Daten aus einer Programmvariablen in eine Tabelle in SQL Server.
Rufen Sie bcp_init auf, bevor Sie diese oder eine andere Massenkopierfunktion aufrufen. Durch aufrufen bcp_init wird die SQL Server Zieltabelle für massenkopieren festgelegt. Beim Aufrufen bcp_init zur Verwendung mit bcp_bind und bcp_sendrow wird der bcp_initparameter szDataFile , der die Datendatei angibt, auf NULL festgelegt. der parameter bcp_initeDirection ist 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 Zeile mit Daten aus Ihren Programmvariablen an SQL Server zu senden. Das erneute Binden einer Spalte wird nicht unterstützt.
Wenn Sie möchten, dass SQL Server die bereits empfangenen Zeilen committen, 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 werden, haben keine Auswirkungen auf bcp_bind Zeilenübertragungen.
Wenn pData für eine Spalte auf NULL festgelegt ist, da ihr Wert durch Aufrufe von bcp_moretext bereitgestellt wird, müssen alle nachfolgenden Spalten, in denen eDataType auf SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR oder SQLIMAGE festgelegt ist, ebenfalls mit pData gebunden werden, die auf NULL festgelegt ist, und ihre Werte müssen ebenfalls durch Aufrufe von bcp_moretext bereitgestellt werden.
Für neue Typen mit großen Werten wie 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 jeder Wert (1, 2, 4 oder 8) für das Präfix (cbIndicator) gültig. In diesem Fall sucht SQL Server Native Client nach dem Abschlusszeichen, berechnet die Datenlänge in Bezug auf den 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 cbIndicator 8 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, der zum effizienten Senden von Daten in Blöcken an den Server verwendet wird. Die Daten mit diesem speziellen Präfix weisen das folgende Format auf:
<><SPECIAL_PREFIX 0 oder mehr DATA CHUNKS><ZERO_CHUNK>, wobei Folgendes gilt:
SPECIAL_PREFIX 0xFFFFFFFFFFFFFFFE entspricht.
DATA_CHUNK ist ein 4-Byte-Präfix, das die Länge des Blöckes enthält, gefolgt von den tatsächlichen Daten, deren Länge im 4-Byte-Präfix angegeben ist.
ZERO_CHUNK ist ein 4-Byte-Wert, der alle Nullen (000000000) enthält, die das Ende der Daten angeben.
Jede andere gültige Länge von 8 Byte wird als reguläre 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 Massenkopieränderungen für erweiterte Datums- und Uhrzeittypen (OLE DB und ODBC).
Weitere Informationen finden Sie unter Verbesserungen an Datum und Uhrzeit (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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für