bcp_bind

gäller för:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics

Binder data från en programvariabel till en tabellkolumn för masskopiering till SQL Server.

Syntax

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

Arguments

hdbc
Är den masskopieringsaktiverade ODBC-anslutningshandtaget.

pData (på engelska)
Är en pekare till den data som kopierats. Om eDataType är SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR eller SQLIMAGE, kan pData vara NULL. En NULL pData indikerar att långa datavärden skickas till SQL Server i chunkar med hjälp av bcp_moretext. Användaren bör endast sätta pData till NULL om kolumnen som motsvarar det användarbegränsade fältet är en BLOB-kolumn, annars kommer bcp_bind att misslyckas.

Om indikatorer finns i datan visas de i minnet direkt före datan. pData-parametern pekar på indikatorvariabeln i detta fall, och indikatorns bredd, cbIndicator-parametern, används av bulkkopiering för att korrekt adressera användardata.

cbIndicator
Är längden, i bytes, för en längd- eller nollindikator för kolumnens data. Giltiga indikatorlängdvärden är 0 (utan indikator), 1, 2, 4 eller 8. Indikatorer visas i minnet direkt före någon data. Till exempel kan följande strukturtypdefinition användas för att infoga heltalsvärden i en SQL Server-tabell med hjälp av bulkkopia:

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

I exemplet skulle pData-parametern sättas till adressen för en deklarerad instans av strukturen, adressen till BCPBOUNDINT iIndicator-strukturmedlemmen . Parametern cbIndicator skulle sättas till storleken av ett heltal (sizeof(int)), och parametern cbData skulle återigen sättas till storleken av ett heltal (sizeof(int)). För att bulkkopiera en rad till servern som innehåller ett NULL-värde för den bundna kolumnen, ska värdet på instansens iIndicator-medlem sättas till SQL_NULL_DATA.

cbData
Är antalet bytes data i programvariabeln, exklusive längden på någon längdindikator eller nollindikator eller terminator.

Att sätta cbData till SQL_NULL_DATA innebär att alla rader som kopieras till servern innehåller ett NULL-värde för kolumnen.

Att ställa in cbData på SQL_VARLEN_DATA indikerar att systemet kommer att använda en strängterminator eller annan metod för att bestämma längden på den kopierade datan.

För datatyper med fast längd, såsom heltal, anger datatypen längden på datan till systemet. Därför kan cbData för datatyper med fast längd säkert vara SQL_VARLEN_DATA eller längden på datan.

För SQL Server tecken- och binära datatyper kan cbData vara SQL_VARLEN_DATA, SQL_NULL_DATA, något positivt värde eller 0. Om cbData är SQL_VARLEN_DATA använder systemet antingen en längd/noll-indikator (om det finns) eller en terminatorsekvens för att bestämma datans längd. Om båda tillhandahålls använder systemet den som resulterar i minst datakopiering. Om cbData är SQL_VARLEN_DATA är kolumnens datatyp en SQL Server tecken- eller binärtyp, och varken längdindikator eller terminatorsekvens specificeras, returnerar systemet ett felmeddelande.

Om cbData är 0 eller ett positivt värde använder systemet cbData som datans längd. Om däremot, utöver ett positivt cbData-värde , finns en längdindikator eller terminatorsekvens, bestämmer systemet datalängden genom att använda den metod som resulterar i minst mängd data som kopieras.

Värdet på cbData-parametern representerar antalet bytes data. Om teckendata representeras av Unicode-breda tecken, representerar ett positivt cbData-parametervärde antalet tecken multiplicerat med storleken i byte av varje tecken.

pTerm
Är en pekare till bytemönstret, om något, som markerar slutet på denna programvariabel. Till exempel har ANSI- och MBCS C-strängar vanligtvis en 1-bytes terminator (\0).

Om det inte finns någon terminator för variabeln, sätt pTerm till NULL.

Du kan använda en tom sträng ("") för att beteckna C nullterminator som programvariabelterminator. Eftersom den nullterminerade tomma strängen utgör en enda byte (terminatorbytet självt), sätt cbTerm till 1. Till exempel, för att indikera att strängen i szName är nullterminerad och att terminatorn ska användas för att ange längden:

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

En icke-terminerad form av detta exempel kan indikera att 15 tecken kopieras från variabeln szName till den andra kolumnen i den bundna tabellen:

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

Bulkkopierings-API:et utför Unicode-till-MBCS-teckenkonvertering vid behov. Se till att både terminatorbytesträngen och bytesträngens längd är korrekt inställda. Till exempel, för att indikera att strängen i szName är en Unicode-omfattande teckensträng, avslutad med Unicode-nullterminatorvärdet:

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

Om den begränsade SQL Server kolumnen är bred teckning utförs ingen konvertering på bcp_sendrow. Om SQL Server-kolumnen är en MBCS-teckentyp utförs bred tecken-till-multibyte-teckenkonvertering när data skickas till SQL Server.

cbTerm
Är antalet bytes som finns i terminatorn för programvariabeln, om några. Om det inte finns någon terminator för variabeln, sätt cbTerm till 0.

eDataType Är C-datatypen för programvariabeln. Datan i programvariabeln konverteras till typen av databaskolumn. Om denna parameter är 0 utförs ingen konvertering.

eDataType-parametern enumereras av SQL Server-datatyptokens i sqlncli.h, inte ODBC C:s datatyp-enumeratorer. Till exempel kan du ange ett tvåbytes heltal av ODBC-typ SQL_C_SHORT, med den SQL Server-specifika typen SQLINT2.

SQL Server 2005 (9.x) introducerade stöd för SQLXML- och SQLUDT-datatyptokens i eDataType-parametern.

Följande tabell listar giltiga uppräknade datatyper och motsvarande ODBC C-datatyper.

idxServerCol Är den ordinala positionen för kolumnen i databastabellen som datan kopieras till. Den första kolumnen i en tabell är kolumn 1. Kolumnens ordinala position rapporteras av SQLColumns.

Returns

SUCCEED eller FAIL.

Remarks

Använd bcp_bind för ett snabbt och effektivt sätt att kopiera data från en programvariabel till en tabell i SQL Server.

Anropa bcp_init innan du anropar denna eller någon annan bulk-kopieringsfunktion. Anrop bcp_init sätter SQL Server måltabellen för bulkkopiering. När bcp_init anropas för användning med bcp_bind och bcp_sendrow sätts parametern bcp_initszDataFile , som anger datafilen, till NULL; parametern bcp_initeDirection är satt till DB_IN.

Gör ett separat bcp_bind anrop för varje kolumn i den SQL Server tabellen som du vill kopiera till. När de nödvändiga bcp_bind anropen har gjorts, anropa sedan bcp_sendrow för att skicka en rad data från dina programvariabler till SQL Server. Att binda om en kolumn stöds inte.

När du vill att SQL Server ska committa de rader som redan mottagits, ring bcp_batch. Till exempel, anropa bcp_batch en gång per 1000 insatta rader eller vid något annat intervall.

När det inte finns fler rader att sätta in, ring bcp_done. Om du inte gör det resulterar det i ett fel.

Kontrollparameterinställningar, specificerade med bcp_control, påverkar inte överföringar bcp_bind rader.

Om pData för en kolumn sätts till NULL eftersom dess värde kommer att tillhandahållas av anrop till bcp_moretext, måste alla efterföljande kolumner med eDataType satt till SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR eller SQLIMAGE också bindas med pData satt till NULL, och deras värden måste också tillhandahållas av anrop till bcp_moretext.

För nya stora värdetyper, såsom varchar(max),varbinary(max) eller nvarchar(max), kan du använda SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY och SQLNCHAR som typindikatorer i eDataType-parametern .

Om cbTerm inte är 0 är vilket värde som helst (1, 2, 4 eller 8) giltigt för prefixet (cbIndicator). I denna situation kommer SQL Server Native Client att söka efter terminatorn, beräkna datalängden med avseende på terminatorn (i) och ställa in cbData till det mindre värdet i och värdet av prefixet.

Om cbTerm är 0 och cbIndicator (prefixet) inte är 0, måste cbIndicator vara 8. Prefixet på 8 byte kan anta följande värden:

• 0xFFFFFFFFFFFFFFFF betyder ett nollvärde för fältet

• 0xFFFFFFFFFFFFFFFE behandlas som ett speciellt prefixvärde, som används för att effektivt skicka data i bitar till servern. Dataformatet med detta speciella prefix är:

• <SPECIAL_PREFIX><0 eller fler DATABITAR><ZERO_CHUNK> där:

• SPECIAL_PREFIX är 0xFFFFFFFFFFFFFFFE

• DATA_CHUNK är ett prefix på 4 byte som innehåller längden på chunken, följt av den faktiska data vars längd anges i prefixet 4 byte.

• ZERO_CHUNK är ett 4-bytesvärde som innehåller alla nollor (000000000) som anger slutet på data.

• Alla andra giltiga 8-bytes längder behandlas som en vanlig datalängd.

Att anropa bcp_columns när man använder bcp_bind resulterar i ett fel.

bcp_bind Stöd för förbättrade datum- och tidsfunktioner

För information om vilka typer som används med eDataType-parametern för datum/tid-typer, se Bulk Copy Changes for Enhanced Date and Time Types (OLE DB och ODBC).

Mer information finns i Förbättringar av datum och tid (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);  

Relaterat innehåll

• SQL Server drivrutinstillägg - Bulkkopieringsfunktioner