bcp_bind

Dotyczy:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)

Przypisuje dane ze zmiennej programowej do kolumny tabeli w celu masowego kopiowania do SQL Server.

Syntax

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

Arguments

hdbc
Czy obsługa połączenia ODBC z obsługą kopiowania zbiorczego.

pData
To wskaźnik do skopiowanych danych. Jeśli eDataType to SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR lub SQLIMAGE, pData może być NULL. NULL pData oznacza, że długie wartości danych będą wysyłane do SQL Server w blokach za pomocą bcp_moretext. Użytkownik powinien ustawić pData na NULL tylko wtedy, gdy kolumna odpowiadająca polu powiązanemu z użytkownikiem jest kolumną BLOB, w przeciwnym razie bcp_bind zawiod.

Jeśli wskaźniki są obecne w danych, pojawiają się w pamięci bezpośrednio przed danymi. Parametr pData wskazuje w tym przypadku zmienną wskaźnikową, a szerokość wskaźnika, parametr cbIndicator , jest wykorzystywana przez kopiowanie masowe do poprawnego adresowania danych użytkownika.

cbIndicator
To długość w bajtach wskaźnika długości lub zerowego dla danych kolumny. Prawidłowe wartości długości wskaźnika to 0 (przy braku wskaźnika), 1, 2, 4 lub 8. Wskaźniki pojawiają się w pamięci bezpośrednio przed jakimikolwiek danymi. Na przykład następująca definicja typu struktury może być użyta do wstawiania wartości całkowitoliczbowych do tabeli SQL Server za pomocą kopii masowej:

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

W przykładzie parametr pData byłby ustawiony na adres zadeklarowanej instancji struktury, czyli adres członka struktury BCPBOUNDINT iIndicator . Parametr cbIndicator byłby ustawiony na rozmiar liczby całkowitej (sizeof(int)), a parametr cbData ponownie na rozmiar liczby całkowitej (sizeof(int)). Aby masowo skopiować wiersz na serwer zawierający wartość NULL dla kolumny powiązanej, wartość członka iIndicator instancji należy ustawić na SQL_NULL_DATA.

cbData
To liczba bajtów danych w zmiennej programowej, nie licząc długości żadnego wskaźnika długości lub zerowego czy terminatora.

Ustawienie cbData na SQL_NULL_DATA oznacza, że wszystkie wiersze skopiowane na serwer zawierają wartość NULL dla kolumny.

Ustawienie cbData na SQL_VARLEN_DATA oznacza, że system użyje terminatora łańcucha lub inną metodę do określenia długości kopiowanych danych.

Dla typów danych o stałej długości, takich jak liczby całkowite, typ danych wskazuje długość danych do systemu. Dlatego dla typów danych o stałej długości cbData może bezpiecznie być SQL_VARLEN_DATA długości danych.

Dla SQL Server znaków i typów danych binarnych, cbData może być SQL_VARLEN_DATA, SQL_NULL_DATA, pewną dodatnią wartością lub 0. Jeśli cbData jest SQL_VARLEN_DATA, system używa albo wskaźnika długości/zera (jeśli występuje), albo sekwencji terminatora do określenia długości danych. Jeśli oba są dostarczone, system korzysta z tego, co skutkuje najmniejszą kopią danych. Jeśli cbData jest SQL_VARLEN_DATA, typ danych w kolumnie to znak SQL Server lub typ binarny, a nie jest określony ani wskaźnik długości, ani sekwencja terminatora, system zwraca komunikat o błędzie.

Jeśli cbData wynosi 0 lub ma wartość dodatnią, system używa cbData jako długości danych. Jednak jeśli oprócz dodatniej wartości cbData dostępny jest wskaźnik długości lub sekwencja terminatora, system określa długość danych metodą skutkującą najmniejszą kopią danych.

Wartość parametru cbData reprezentuje liczbę bajtów danych. Jeśli dane znaków są reprezentowane znakami ogólnymi Unicode, to dodatnia wartość parametru cbData oznacza liczbę znaków pomnożoną przez rozmiar w bajtach każdego znaku.

pTerm
Jest wskaźnikiem do wzorca bajtów, jeśli taki istnieje, który oznacza koniec tej zmiennej programowej. Na przykład stringi C ANSI i MBCS zwykle mają terminator o długości 1 bajtu (\0).

Jeśli nie ma terminatora dla zmiennej, ustaw pTerm na NULL.

Możesz użyć pustego ciągu (""), aby oznaczyć terminator null C jako terminator zmiennej programowej. Ponieważ pusty ciąg zakończony zerowym stanowi pojedynczy bajt (bajt terminatora), ustaw cbTerm na 1. Na przykład, aby wskazać, że ciąg w szName jest zakończony zerowo i że terminator powinien być użyty do wskazania długości:

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

Niezakończona forma tego przykładu mogłaby oznaczać, że ze zmiennej szName do drugiej kolumny tabeli powiązanej należy skopiować 15 znaków:

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

API kopiowania masowego wykonuje konwersję znaków Unicode na MBCS w razie potrzeby. Upewnij się, że zarówno ciąg bajtów terminatora, jak i długość tego ciągu są poprawnie ustawione. Na przykład, aby wskazać, że ciąg znaków w szName jest ciągiem znaków ogólno-Unicode, zakończonym wartością zakończenia null w Unicode:

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

Jeśli kolumna SQL Server jest szeroka, konwersja nie jest wykonywana na bcp_sendrow. Jeśli kolumna SQL Server jest typem znaku MBCS, konwersja znaków szerokich na wielobajtowe wykonywana jest podczas przesyłania danych do SQL Server.

cbTerm
To liczba bajtów obecnych w terminatorze dla zmiennej programowej, jeśli w ogóle występuje. Jeśli nie ma terminatora dla zmiennej, ustaw cbTerm na 0.

eDataType Jest typem danych C zmiennej programowej. Dane w zmiennej programowej są przekształcane na typ kolumny bazy danych. Jeśli ten parametr wynosi 0, nie wykonuje się konwersji.

Parametr eDataType jest wyliczany przez tokeny typów danych SQL Server w sqlncli.h, a nie przez enumeratory typów danych ODBC C. Na przykład możesz określić dwubajtową liczbę całkowitą, ODBC typu SQL_C_SHORT, używając specyficznego dla SQL Server typu SQLINT2.

SQL Server 2005 (9.x) wprowadził wsparcie dla tokenów typów danych SQLXML i SQLUDT w parametrze eDataType.

Poniższa tabela przedstawia poprawne wyliczone typy danych oraz odpowiadające im typy danych ODBC C.

idxServerCol To pozycja porządkowa kolumny w tabeli bazy danych, do której kopiowane są dane. Pierwsza kolumna w tabeli to kolumna 1. Pozycja porządkowa kolumny jest podawana przez SQLColumns.

Zwroty

POWODZENIE lub NIEPOWODZENIE.

Remarks

Użyj bcp_bind jako szybkiego i efektywnego sposobu kopiowania danych ze zmiennej programu do tabeli w SQL Server.

Zadzwoń do bcp_init zanim wywołasz tę lub jakąkolwiek inną funkcję kopiowania zbiorowego. Wywołanie bcp_init ustawia tabelę docelową SQL Server do kopiowania masowego. Podczas wywoływania bcp_init do użycia z bcp_bind i bcp_sendrow, parametr bcp_initszDataFile wskazujący plik danych jest ustawiony na NULL; parametr bcp_initeDirection jest ustawiony na DB_IN.

Zrób osobny bcp_bind wywołać dla każdej kolumny w tabeli SQL Server, do której chcesz skopiować. Po wykonaniu niezbędnych bcp_bind wywołań, następnie wywołaj bcp_sendrow, aby przesłać wiersz danych ze zmiennych programowych do SQL Server. Ponowne oprawianie kolumny nie jest obsługiwane.

Kiedy chcesz SQL Server zatwierdzić już otrzymane wiersze, zadzwoń do bcp_batch. Na przykład wywołaj bcp_batch raz na każde 1000 wstawionych wierszy lub w dowolnym innym odstępie czasu.

Gdy nie ma już więcej wierszy do wstawienia, wywołaj bcp_done. Niepowodzenie w tym celu powoduje wystąpienie błędu.

Ustawienia parametrów sterujących, określone bcp_control, nie mają wpływu na bcp_bind przenosy wierszy.

Jeśli pData dla kolumny jest ustawiony na NULL, ponieważ jego wartość zostanie dostarczona przez wywołania bcp_moretext, wszystkie kolejne kolumny z eDataType ustawionym na SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR lub SQLIMAGE muszą być również powiązane z pData ustawionym na NULL, a ich wartości muszą być również dostarczone przez wywołania bcp_moretext.

Dla nowych typów dużych wartości, takich jak varchar(max),varbinary(max) lub nvarchar(max), możesz użyć SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY i SQLNCHAR jako wskaźników typów w parametrze eDataType .

Jeśli cbTerm nie jest równy 0, każda wartość (1, 2, 4 lub 8) jest prawidłowa dla prefiksu (cbIndicator). W takiej sytuacji natywny klient SQL Server wyszukuje terminator, oblicza długość danych względem terminatora (i) i ustawia cbData na mniejszą wartość i oraz wartość prefiksu.

Jeśli cbTerm wynosi 0, a cbIndicator (prefiks) nie jest 0, cbIndicator musi mieć wartość 8. Prefiks 8-bajtowy może przyjmować następujące wartości:

• 0xFFFFFFFFFFFFFFFF oznacza wartość zerową dla pola

• 0xFFFFFFFFFFFFFFFE traktowany jest jako specjalna wartość prefiksowa, która służy do efektywnego przesyłania danych w fragmentach do serwera. Format danych z tym specjalnym przedrostkiem to:

• <SPECIAL_PREFIX><0 lub więcej FRAGMENTÓW><DANYCH ZERO_CHUNK> gdzie:

• SPECIAL_PREFIX jest 0xFFFFFFFFFFFFFFFE

• DATA_CHUNK to przedrostek 4-bajtowy zawierający długość bloku, po którym następuje rzeczywiste dane, których długość jest określona w prefiksie 4-bajtowym.

• ZERO_CHUNK to wartość 4-bajtowa zawierająca wszystkie zera (00000000), oznaczająca koniec danych.

• Każda inna prawidłowa długość 8-bajtowa traktowana jest jako regularna długość danych.

Dzwonienie do bcp_columns podczas korzystania z bcp_bind powoduje błąd.

bcp_bind Wsparcie dla ulepszonych funkcji daty i godziny

Aby uzyskać informacje o typach używanych z parametrem eDataType dla typów dat/godzin, zobacz Bulk Copy Changes for Enhanced Date and Time Types (OLE DB i ODBC).

Aby uzyskać więcej informacji, zobacz ulepszenia daty i godziny (ODBC).

Example

#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);  

Treści powiązane

• Rozszerzenia sterowników SQL Server - funkcje kopiowania masowego