bcp_bind

van toepassing op:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)

Bindt data van een programmavariabele aan een tabelkolom voor bulkkopieën naar SQL Server.

Syntax

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

Arguments

hdbc-
Is de ODBC-verbindingshandgreep waarvoor bulksgewijs kopiëren is ingeschakeld.

pData-
Is een verwijzing naar de gekopieerde data. Als eDataType SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR of SQLIMAGE is, kan pData NULL zijn. Een NULL pData geeft aan dat lange datawaarden in chunks naar SQL Server worden gestuurd met behulp van bcp_moretext. De gebruiker mag pData alleen op NULL zetten als de kolom die overeenkomt met het door de gebruiker gebonden veld een BLOB-kolom is, anders zal bcp_bind falen.

Als indicatoren aanwezig zijn in de data, verschijnen deze direct in het geheugen vóór de data. De pData-parameter wijst in dit geval naar de indicatorvariabele, en de breedte van de indicator, de cbIndicator-parameter , wordt door bulk copy gebruikt om gebruikersgegevens correct te adresseren.

cbIndicator
Is de lengte, in bytes, van een lengte- of nulindicator voor de gegevens van de kolom. Geldige indicatorlengtewaarden zijn 0 (zonder indicator), 1, 2, 4 of 8. Indicatoren verschijnen direct in het geheugen vóór alle data. Bijvoorbeeld, de volgende structuurtypedefinitie kan worden gebruikt om gehele getallen in een SQL Server-tabel in te voegen met bulk copy:

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

In het voorbeeldgeval zou de pData-parameter worden ingesteld op het adres van een gedeclareerde instantie van de structuur, het adres van het BCPBOUNDINT iIndicator-structuurlid . De cbIndicator-parameter zou worden ingesteld op de grootte van een geheel getal (sizeof(int)), en de cbData-parameter zou opnieuw worden ingesteld op de grootte van een geheel getal (sizeof(int)). Om een rij met een NULL-waarde voor de gebonden kolom bulk-te kopiëren naar de server, moet de waarde van het iIndicator-lid van de instantie worden ingesteld op SQL_NULL_DATA.

cbData
Is het aantal bytes data in de programmavariabele, exclusief de lengte van een lengte- of nulindicator of terminator.

Het instellen van cbData op SQL_NULL_DATA geeft aan dat alle rijen die naar de server zijn gekopieerd een NULL-waarde voor de kolom bevatten.

Het instellen van cbData op SQL_VARLEN_DATA geeft aan dat het systeem een stringterminator of een andere methode zal gebruiken om de lengte van de gekopieerde data te bepalen.

Voor datatypes met vaste lengte, zoals gehele getallen, geeft het datatype de lengte van de data aan voor het systeem. Daarom kan cbData voor datatypes met vaste lengte veilig worden SQL_VARLEN_DATA of de lengte van de data.

Voor SQL Server teken- en binaire datatypes kan cbData SQL_VARLEN_DATA, SQL_NULL_DATA, een positieve waarde of 0 zijn. Als cbData SQL_VARLEN_DATA is, gebruikt het systeem ofwel een lengte/nul-indicator (indien aanwezig) of een terminatorsequentie om de lengte van de data te bepalen. Als beide worden geleverd, gebruikt het systeem degene die resulteert in de minste hoeveelheid datakopieën. Als cbData SQL_VARLEN_DATA is, is het datatype van de kolom een SQL Server teken of binair type, en is er noch een lengteindicator noch een terminatorsequentie gespecificeerd, geeft het systeem een foutmelding terug.

Als cbData 0 is of een positieve waarde, gebruikt het systeem cbData als de gegevenslengte. Als echter, naast een positieve cbData-waarde , een lengte-indicator of terminatorsequentie wordt geleverd, bepaalt het systeem de gegevenslengte door de methode te gebruiken die resulteert in de minimale hoeveelheid data.

De waarde van de cbData-parameter geeft het aantal bytes aan data weer aan. Als tekengegevens wordt weergegeven door Unicode-brede tekens, dan geeft een positieve cbData-parameterwaarde het aantal tekens vermenigvuldigd met de grootte in bytes van elk teken weer.

pTerm
Is een pointer naar het bytepatroon, indien aanwezig, dat het einde van deze programmavariabele markeert. Bijvoorbeeld, ANSI- en MBCS C-strings hebben meestal een terminator van 1 byte (\0).

Als er geen terminator voor de variabele is, zet pTerm dan op NULL.

Je kunt een lege string ("") gebruiken om de C nul-terminator aan te duiden als de programmavariabele-terminator. Omdat de null-terminated lege string een enkele byte vormt (de terminatorbyte zelf), stel cbTerm in op 1. Bijvoorbeeld, om aan te geven dat de string in szName null-termined is en dat de terminator gebruikt moet worden om de lengte aan te geven:

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

Een niet-beëindigde vorm van dit voorbeeld kan aangeven dat 15 tekens van de szName-variabele naar de tweede kolom van de gebonden tabel worden gekopieerd:

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

De bulk copy API voert Unicode-naar-MBCS tekenconversie uit waar nodig. Zorg ervoor dat zowel de terminator-bytestring als de lengte van de bytestring correct zijn ingesteld. Bijvoorbeeld, om aan te geven dat de string in szName een Unicode-brede tekenreeks is, beëindigd door de Unicode null-terminatorwaarde:

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

Als de gebonden kolom SQL Server breed karakter is, wordt er geen conversie uitgevoerd op bcp_sendrow. Als de SQL Server-kolom een MBCS-tekentype is, wordt een brede karakter-naar-multibyte tekenconversie uitgevoerd terwijl de gegevens naar SQL Server worden gestuurd.

cbTerm
Is het aantal bytes dat aanwezig is in de terminator voor de programmavariabele, indien aanwezig. Als er geen terminator voor de variabele is, zet cbTerm dan op 0.

eDataType Is het C-datatype van de programmavariabele. De gegevens in de programmavariabele worden omgezet naar het type van de databasekolom. Als deze parameter 0 is, wordt er geen conversie uitgevoerd.

De eDataType-parameter wordt geënumereerd door de SQL Server datatypetokens in sqlncli.h, niet door de ODBC C datatype-enumerators. Je kunt bijvoorbeeld een tweebyte integer, ODBC-type SQL_C_SHORT, specificeren met het SQL Server-specifieke type SQLINT2.

SQL Server 2005 (9.x) introduceerde ondersteuning voor SQLXML- en SQLUDT-datatypetokens in de eDataType-parameter.

De volgende tabel geeft een overzicht van geldige geenummerde datatypes en de bijbehorende ODBC C-datatypes.

idxServerCol Is de ordinaalpositie van de kolom in de databasetabel waarnaar de gegevens worden gekopieerd. De eerste kolom in een tabel is kolom 1. De ordinaalpositie van een kolom wordt gerapporteerd door SQLColumns.

Returns

SLAGEN OF MISLUKKEN.

Remarks

Gebruik bcp_bind voor een snelle, efficiënte manier om gegevens van een programmavariabele in een tabel te kopiëren in SQL Server.

Roep bcp_init aan voordat je deze of een andere bulk-copy functie aanroept. Het aanroepen van bcp_init stelt de SQL Server doeltabel in voor bulkkopie. Bij het aanroepen van bcp_init voor gebruik met bcp_bind en bcp_sendrow wordt de parameter bcp_initszDataFile , die het databestand aangeeft, op NULL gezet; de parameter bcp_initeDirection is ingesteld op DB_IN.

Maak een aparte bcp_bind aanroep voor elke kolom in de SQL Server-tabel waarin je wilt kopiëren. Nadat de benodigde bcp_bind aanroepen zijn gedaan, roep je bcp_sendrow aan om een rij data van je programmavariabelen naar SQL Server te sturen. Het opnieuw binden van een kolom wordt niet ondersteund.

Wanneer je wilt dat SQL Server de reeds ontvangen rijen committen, bel bcp_batch. Roep bijvoorbeeld bcp_batch één keer aan voor elke 1000 ingevoegde rijen of op een ander tijdstip.

Als er geen rijen meer zijn om in te voegen, roep dan bcp_done. Als u dit niet doet, treedt er een fout op.

Instellingen voor controleparameters, gespecificeerd met bcp_control, hebben geen effect op bcp_bind rijoverdrachten.

Als pData voor een kolom op NULL wordt gezet omdat de waarde wordt geleverd door aanroepen naar bcp_moretext, moeten alle volgende kolommen met eDataType gezet op SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR of SQLIMAGE ook worden gebonden met pData op NULL, en hun waarden moeten ook worden geleverd door aanroepen naar bcp_moretext.

Voor nieuwe grote waardetypen, zoals varchar(max), varbinary(max) of nvarchar(max), kun je SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY en SQLNCHAR gebruiken als type-indicatoren in de eDataType-parameter.

Als cbTerm niet 0 is, is elke waarde (1, 2, 4 of 8) geldig voor het voorvoegsel (cbIndicator). In deze situatie zal de SQL Server Native Client zoeken naar de terminator, de gegevenslengte berekenen ten opzichte van de terminator (i), en de cbData instellen op de kleinere waarde van i en de waarde van het voorvoegsel.

Als cbTerm 0 is en cbIndicator (het voorvoegsel) niet 0, moet cbIndicator 8 zijn. Het 8-byte prefix kan de volgende waarden aannemen:

• 0xFFFFFFFFFFFFFFFF betekent een nulwaarde voor het veld

• 0xFFFFFFFFFFFFFFFE wordt behandeld als een speciale prefixwaarde, die wordt gebruikt om data efficiënt in stukken naar de server te sturen. Het formaat van gegevens met dit speciale voorvoegsel is:

• <SPECIAL_PREFIX><0 of meer DATA-CHUNKS><ZERO_CHUNK> waarbij:

• SPECIAL_PREFIX is 0xFFFFFFFFFFFFFFFE

• DATA_CHUNK is een prefix van 4 bytes dat de lengte van het stuk bevat, gevolgd door de daadwerkelijke gegevens waarvan de lengte is opgegeven in het 4-byte prefix.

• ZERO_CHUNK is een 4-byte waarde die alle nullen (000000000) bevat, wat het einde van de data aangeeft.

• Elke andere geldige lengte van 8 bytes wordt behandeld als een reguliere datalengte.

Het aanroepen van bcp_columns bij het gebruik van bcp_bind resulteert in een foutmelding.

bcp_bind Ondersteuning voor verbeterde datum- en tijdfuncties

Voor informatie over de typen die worden gebruikt met de eDataType-parameter voor datum/tijd-typen, zie Bulk Copy Changes for Enhanced Date and Time Types (OLE DB en ODBC).

Zie ODBC-(Datum- en tijdverbeteringen) voor meer informatie.

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

Verwante onderwerpen

• SQL Server Driver Extensions - Bulk Copy Functions