SQLBindCol-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standardefterlevnad: ISO 92

Summary
SQLBindCol binder applikationsdatabuffertar till kolumner i resultatuppsättningen.

Syntax

  
SQLRETURN SQLBindCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);  

Arguments

StatementHandle
[Indata] Instruktionshandtag.

Kolumnnummer
[Input] Nummer i resultatuppsättningskolumnen att binda. Kolumnerna numreras i ökande kolumnordning med start 0, där kolumn 0 är bokmärkeskolumnen. Om bokmärken inte används – det vill säga att attributet SQL_ATTR_USE_BOOKMARKS sats sätts till SQL_UB_OFF – börjar kolumnnummer på 1.

MålTyp
[Input] Identifieraren för C-datatypen i *TargetValuePtr-bufferten . När den hämtar data från datakällan med SQLFetch, SQLFetchScroll, SQLBulkOperations eller SQLSetPos, konverterar drivrutinen datan till denna typ; när den skickar data till datakällan med SQLBulkOperations eller SQLSetPos, konverterar drivrutinen datan från denna typ. För en lista över giltiga C-datatyper och typidentifierare, se avsnittet C Data Types i Appendix D: Data Types.

Om TargetType-argumentet är en intervalldatatyp används standardintervall-ledande precision (2) och standardintervallsekundsprecision (6), som satts i fälten SQL_DESC_DATETIME_INTERVAL_PRECISION respektive SQL_DESC_PRECISION i ARD, för datan. Om TargetType-argumentet är SQL_C_NUMERIC används standardprecisionen (drivrutinsdefinierad) och standardskalan (0), som anges i fälten SQL_DESC_PRECISION och SQL_DESC_SCALE i ARD, för datan. Om någon standardprecision eller skala inte är lämplig bör applikationen uttryckligen ställa in rätt deskriptorfält genom ett anrop till SQLSetDescField eller SQLSetDescRec.

Du kan också ange en utökad C-datatyp. Mer information finns i C-datatyper i ODBC.

TargetValuePtr
[Uppskjuten ingång/utgång] Peka till databufferten för att binda till kolumnen. SQLFetch och SQLFetchScroll returnerar data i denna buffert. SQLBulkOperations returnerar data i denna buffert när Operation är SQL_FETCH_BY_BOOKMARK; den hämtar data från denna buffert när Operation är SQL_ADD eller SQL_UPDATE_BY_BOOKMARK. SQLSetPos returnerar data i denna buffert när Operation är SQL_REFRESH; den hämtar data från denna buffert när Operation är SQL_UPDATE.

Om TargetValuePtr är en nullpekare avbinder drivrutinen databufferten för kolumnen. En applikation kan avbinda alla kolumner genom att anropa SQLFreeStmt med alternativet SQL_UNBIND. En applikation kan avbinda databufferten för en kolumn men ändå ha en längd-/indikatorbuffertgräns för kolumnen, om argumentet TargetValuePtr i anropet till SQLBindCol är en nullpekare men StrLen_or_IndPtr-argumentet är ett giltigt värde.

BufferLength
[Input] Längden på *TargetValuePtr-bufferten i bytes.

Drivrutinen använder BufferLength för att undvika att skriva förbi slutet av *TargetValuePtr-bufferten när den returnerar variabellängdsdata, såsom tecken- eller binärdata. Observera att drivrutinen räknar null-termineringstecknet när den returnerar teckendata till *TargetValuePtr. * TargetValuePtr måste därför innehålla utrymme för tecken null-terminering, annars kommer drivrutinen att trunkera datan.

När drivrutinen returnerar data med fast längd, såsom ett heltal eller en datumstruktur, ignorerar drivrutinen BufferLength och antar att bufferten är tillräckligt stor för att lagra datan. Därför är det viktigt för applikationen att allokera en tillräckligt stor buffert för data med fast längd, annars skriver drivrutinen förbi buffertens slut.

SQLBindCol returnerar SQLSTATE HY090 (Ogiltig sträng- eller buffertlängd) när BufferLength är mindre än 0, men inte när BufferLength är 0. Men om TargetType specificerar en teckentyp bör en applikation inte sätta BufferLength till 0, eftersom ISO CLI-kompatibla drivrutiner returnerar SQLSTATE HY090 (Ogiltig sträng- eller bufferlängd) i det fallet.

StrLen_or_IndPtr
[Uppskjuten ingång/utgång] Peka på längd-/indikatorbufferten för att binda till kolumnen. SQLFetch och SQLFetchScroll returnerar ett värde i denna buffert. SQLBulkOperations hämtar ett värde från denna buffert när Operation är SQL_ADD, SQL_UPDATE_BY_BOOKMARK eller SQL_DELETE_BY_BOOKMARK. SQLBulkOperations returnerar ett värde i denna buffert när Operation är SQL_FETCH_BY_BOOKMARK. SQLSetPos returnerar ett värde i denna buffert när Operation är SQL_REFRESH; den hämtar ett värde från denna buffert när Operation är SQL_UPDATE.

SQLFetch, SQLFetchScroll, SQLBulkOperations och SQLSetPos kan returnera följande värden i längd-/indikatorbufferten:

  • Längden på de data som är tillgängliga att returnera

  • SQL_NO_TOTAL

  • SQL_NULL_DATA

Applikationen kan lägga följande värden i längd-/indikatorbufferten för användning med SQLBulkOperations eller SQLSetPos:

  • Längden på den data som skickas

  • SQL_NTS

  • SQL_NULL_DATA

  • SQL_DATA_AT_EXEC

  • Resultatet av SQL_LEN_DATA_AT_EXEC makro

  • SQL_COLUMN_IGNORE

Om indikatorbufferten och längdbufferten är separata buffertar kan indikatorbufferten endast returnera SQL_NULL_DATA, medan längdbufferten kan returnera alla andra värden.

För mer information, se SQLBulkOperations Function, SQLFetch Function, SQLSetPos Function och Using Length/Indicator Values.

Om StrLen_or_IndPtr är en nollpekare används varken längd eller indikatorvärde. Detta är ett fel när man hämtar data och datan är NULL.

Se ODBC 64-bitars information om din applikation kommer att köras på ett 64-bitars operativsystem.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostics

När SQLBindCol returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med HandleType SQL_HANDLE_STMT och Handle of StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLBindCol och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

SQLSTATE Error Beskrivning
01000 Allmän varning Informationsmeddelande för drivrutinsspecifikt. (Funktionen returnerar SQL_SUCCESS_WITH_INFO.)
07006 Attributöverträdelse för begränsad datatyp (DM) Kolumnnummerargumentet var 0, och TargetType-argumentet var varken SQL_C_BOOKMARK eller SQL_C_VARBOOKMARK.
07009 Ogiltigt deskriptorindex Värdet som angavs för argumentet ColumnNumber översteg det maximala antalet kolumner i resultatuppsättningen.
HY000 Allmänt fel Ett fel uppstod för vilket det inte fanns någon specifik SQLSTATE och för vilken ingen implementeringsspecifik SQLSTATE definierades. Felmeddelandet som returnerades av SQLGetDiagRec i *MessageText-bufferten beskriver felet och dess orsak.
HY001 Fel vid minnesallokering Drivrutinen kunde inte allokera minne som krävs för att stödja körning eller slutförande av funktionen.
HY003 Ogiltig applikationsbufferttyp Argumentet TargetType var varken en gyldig datatyp eller SQL_C_DEFAULT.
HY010 Funktionssekvensfel (DM) En asynkront körande funktion anropades för anslutningshandtaget som är associerat med StatementHandle. Denna asynkrona funktion kördes fortfarande när SQLBindCol anropades.

(DM) SQLExecute, SQLExecDirect eller SQLMoreResults anropades för StatementHandle och returnerades SQL_PARAM_DATA_AVAILABLE. Den här funktionen anropades innan data hämtades för alla strömmade parametrar.

(DM) En asynkront exekverande funktion anropades för StatementHandle och kördes fortfarande när denna funktion anropades.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations eller SQLSetPos anropades för StatementHandle och returnerades SQL_NEED_DATA. Den här funktionen anropades innan data skickades för alla data-at-execution-parametrar eller kolumner.
HY013 Minneshanteringsfel Det gick inte att bearbeta funktionsanropet eftersom det inte gick att komma åt underliggande minnesobjekt, möjligen på grund av minnesbrist.
HY090 Ogiltig sträng- eller buffertlängd (DM) Värdet som specificerades för argumentet BufferLength var mindre än 0.

(DM) Föraren var en ODBC 2. x-drivrutin , sattes ColumnNumber-argumentet till 0, och värdet som specificerades för argumentet BufferLength var inte lika med 4.
HY117 Anslutningen pausas på grund av okänt transaktionstillstånd. Endast frånkopplings- och skrivskyddade funktioner tillåts. (DM) Mer information om pausat tillstånd finns i SQLEndTran-funktion.
HYC00 Valfri funktion har inte implementerats Drivrutinen eller datakällan stöder inte den konvertering som anges av kombinationen av TargetType-argumentet och den drivrutinsspecifika SQL-datatypen i motsvarande kolumn.

Argumentet ColumnNumber var 0 och drivrutinen stöder inte bokmärken.

Drivrutinen stöder endast ODBC 2. x och argumentet TargetType var ett av följande:

SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT

och någon av de intervall C-datatyper som listas i C Data Types i Appendix D: Data Types.

Drivrutinen stödjer endast ODBC-versioner före 3.50, och argumentet TargetType var SQL_C_GUID.
HYT01 Tidsgränsen för anslutningen gick ut Tidsgränsen för anslutningen löpte ut innan datakällan svarade på begäran. Tidsgränsen för anslutningen anges via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Drivrutinen stöder inte den här funktionen (DM) Drivrutinen som är associerad med StatementHandle stöder inte funktionen.

Comments

SQLBindCol används för att associera eller binda kolumner i resultatuppsättningen till databuffertar och buffertar för längd/indikatorer i applikationen. När applikationen anropar SQLFetch, SQLFetchScroll eller SQLSetPos för att hämta data, returnerar drivrutinen data för de bundna kolumnerna i de angivna buffertarna; för mer information, se SQLFetch Function. När applikationen anropar SQLBulkOperations för att uppdatera eller infoga en rad eller SQLSetPos för att uppdatera en rad, hämtar drivrutinen data för de bundna kolumnerna från de angivna buffertarna; för mer information, se SQLBulkOperations Function eller SQLSetPos Function. För mer information om bindning, se Hämta resultat (Basic).

Observera att kolumner inte behöver bindas för att hämta data från dem. En applikation kan också anropa SQLGetData för att hämta data från kolumner. Även om det är möjligt att binda vissa kolumner i en rad och anropa SQLGetData för andra, är detta föremål för vissa begränsningar. För mer information, se SQLGetData.

Bindning, avbindning och ombindning av kolumner

En kolumn kan vara bunden, obunden eller reboundad när som helst, även efter att data har hämtats från resultatmängden. Den nya bindningen träder i kraft nästa gång en funktion som använder bindningar anropas. Till exempel, anta att en applikation binder kolumnerna i en resultatmängd och anropar SQLFetch. Drivrutinen returnerar data i boundbuffers. Antag nu att applikationen binder kolumnerna till en annan uppsättning buffertar. Drivrutinen lägger inte in data för den nyss hämtade raden i de nybundna buffertarna. Istället väntar den tills SQLFetch anropas igen och placerar sedan datan för nästa rad i de nyavgränsade buffertarna.

Note

Attributet för satsen SQL_ATTR_USE_BOOKMARKS bör alltid sättas innan en kolumn binds till kolumn 0. Detta är inte ett krav men rekommenderas starkt.

Bindningskolumner

För att binda en kolumn anropar en applikation SQLBindCol och skickar kolumnnummer, typ, adress och längd på en databuffert samt adressen på en längd-/indikatorbuffert. För information om hur dessa adresser används, se "Buffer Addresses" senare i detta avsnitt. För mer information om bindningskolumner, se Using SQLBindCol.

Användningen av dessa buffertar skjuts upp; det vill säga, applikationen binder dem i SQLBindCol men drivrutinen får åtkomst till dem från andra funktioner – nämligen SQLBulkOperations, SQLFetch, SQLFetchScroll eller SQLSetPos. Det är applikationens ansvar att se till att pekarna som anges i SQLBindCol förblir giltiga så länge bindningen är i kraft. Om applikationen tillåter dessa pekare att bli ogiltiga – till exempel frigör den en buffert – och sedan anropar en funktion som förväntar sig att de ska vara giltiga, är konsekvenserna odefinierade. För mer information, se Deferred Buffers.

Bindningen gäller tills den ersätts av en ny, kolumnen är obunden eller uttalandet frigörs.

Uppbindande kolumner

För att avbinda en enda kolumn anropar en applikation SQLBindCol med ColumnNumber satt till kolumnens nummer och TargetValuePtr satt till en nullpekare. Om ColumnNumber refererar till en obunden kolumn returnerar SQLBindCol fortfarande SQL_SUCCESS.

För att avbinda alla kolumner anropar en applikation SQLFreeStmt med fOption satt till SQL_UNBIND. Detta kan också uppnås genom att sätta ARD:s SQL_DESC_COUNT fält till noll.

Ombindning av kolumner

En applikation kan utföra någon av två operationer för att ändra en bindning:

  • Anropa SQLBindCol för att specificera en ny bindning för en kolumn som redan är bunden. Drivrutinen skriver över den gamla bindningen med den nya.

  • Ange en offset som ska läggas till buffertadressen och som angavs av bindningsanropet till SQLBindCol. För mer information, se nästa avsnitt, "Bindningsoffsets."

Bindningsoffsets

En bindningsoffset är ett värde som läggs till adresserna för data- och längd-/indikatorbuffertar (enligt TargetValuePtr- och StrLen_or_IndPtr-argumentet) innan de derefereras. När offsets används är bindningarna en "mall" för hur applikationens buffertar är upplagda, och applikationen kan flytta denna "mall" till olika minnesområden genom att ändra offseten. Eftersom samma offset läggs till varje adress i varje bindning måste de relativa offseten mellan buffertar för olika kolumner vara desamma inom varje uppsättning buffertar. Detta gäller alltid när radvis bindning används; Applikationen måste noggrant lägga ut sina buffertar för att detta ska gälla när kolumnvis bindning används.

Att använda en bindningsoffset har i princip samma effekt som att binda om en kolumn genom att anropa SQLBindCol. Skillnaden är att ett nytt anrop till SQLBindCol specificerar nya adresser för databufferten och längd-/indikatorbufferten, medan användning av bindningsoffset inte ändrar adresserna utan bara lägger till en offset till dem. Applikationen kan ange en ny offset när den vill, och denna offset läggs alltid till de ursprungligen bundna adresserna. Specifikt, om offsetet sätts till 0 eller om satsattributet sätts till en nullpekare, använder drivrutinen de ursprungligen bundna adresserna.

För att specificera en bindningsförskjutning sätter applikationen attributet SQL_ATTR_ROW_BIND_OFFSET_PTR statement till adressen till en SQLINTEGER-buffert. Innan applikationen anropar en funktion som använder bindningar, lägger den in en offset i byte i denna buffert. För att bestämma adressen till bufferten som ska användas lägger drivrutinen till offsetet till adressen i bindningen. Summan av adressen och offsetet måste vara en giltig adress, men adressen där offsetet läggs till behöver inte vara giltig. För mer information om hur bindningsoffsets används, se "Buffer Addresses" senare i detta avsnitt.

Bindningsarrayer

Om raduppsättningsstorleken (värdet på attributet SQL_ATTR_ROW_ARRAY_SIZE-satsen) är större än 1, binder applikationen arrayer av buffertar istället för enskilda buffertar. För mer information, se Block Cursors.

Applikationen kan binda arrayer på två sätt:

  • Binda en matris till varje kolumn. Detta kallas kolumnvis bindning eftersom varje datastruktur (array) innehåller data för en enda kolumn.

  • Definiera en struktur som håller data för en hel rad och bind en array av dessa strukturer. Detta kallas radbunden bindning eftersom varje datastruktur innehåller data för en enda rad.

Varje array av buffertar måste ha minst lika många element som radmängdens storlek.

Note

En applikation måste verifiera att justeringen är giltig. För mer information om justeringsöverväganden, se Justering.

Column-Wise Bindning

Vid kolumnvis bindning binder applikationen separata data och längd-/indikatorarrayer till varje kolumn.

För att använda kolumnvis bindning sätter applikationen först attributet SQL_ATTR_ROW_BIND_TYPE statement till SQL_BIND_BY_COLUMN. (Detta är standarden.) För att varje kolumn ska bindas utför applikationen följande steg:

  1. Allokerar en databuffertarray.

  2. Allokerar en array av längd-/indikatorbuffertar.

    Note

    Om applikationen skriver direkt till deskriptorer när kolumnvis bindning används, kan separata arrayer användas för längd- och indikatordata.

  3. Anropar SQLBindCol med följande argument:

    • TargetType är typen av ett enskilt element i databuffertarrayen.

    • TargetValuePtr är adressen till databuffertarrayen.

    • BufferLength är storleken på ett enskilt element i databuffertarrayen. BufferLength-argumentet ignoreras när datan är data med fast längd.

    • StrLen_or_IndPtr är adressen till längd-/indikatorarrayen.

För mer information om hur denna information används, se "Buffer Addresses" senare i detta avsnitt. För mer information om kolumnvis bindning, se Column-Wise Bindning.

Row-Wise Bindning

Vid radvis bindning definierar applikationen en struktur som innehåller data och buffertar för längd/indikatorer för varje kolumn som ska bindas.

För att använda radvis bindning utför applikationen följande steg:

  1. Definierar en struktur för att innehålla en enda rad data (inklusive både data och buffertar för längd/indikator) och tilldelar en array av dessa strukturer.

    Note

    Om applikationen skriver direkt till deskriptorer när radvis bindning används, kan separata fält användas för längd- och indikatordata.

  2. Sätter attributet SQL_ATTR_ROW_BIND_TYPE till storleken på strukturen som innehåller en enda datarad eller till storleken på en instans av en buffert där resultatkolumnerna kommer att bindas. Längden måste inkludera utrymme för alla bundna kolumner och eventuell utfyllnad av strukturen eller bufferten, för att säkerställa att när adressen till en bunden kolumn ökar med den angivna längden, kommer resultatet att peka på början av samma kolumn i nästa rad. När man använder sizeof-operatorn i ANSI C är detta beteende garanterat.

  3. Kallar SQLBindCol med följande argument för varje kolumn som ska bindas:

    • TargetType är typen av databuffertmedlem som ska bindas till kolumnen.

    • TargetValuePtr är adressen till databuffertmedlemmen i det första arrayelementet.

    • BufferLength är storleken på databuffertmedlemmen.

    • StrLen_or_IndPtr är adressen till längden/indikatorn som ska bindas.

För mer information om hur denna information används, se "Buffer Addresses" senare i detta avsnitt. För mer information om kolumnvis bindning, se Row-Wise Bindning.

Buffertadresser

Buffertadressen är den faktiska adressen till datan eller längd-/indikatorbufferten. Drivrutinen beräknar buffertadressen precis innan den skriver till buffertarna (till exempel under hämtningstiden). Den beräknas från följande formel, som använder adresserna specificerade i argumenten TargetValuePtr och StrLen_or_IndPtr , bindningsoffset och radnumret:

Bunden adress + Bindningsoffset + ((Radnummer - 1) x elementstorlek)

där formelns variabler definieras som beskrivs i följande tabell.

Variable Beskrivning
Bunden adress För databuffertar är adressen som anges med argumentet TargetValuePtr i SQLBindCol.

För längd-/indikatorbuffertar används adressen som anges med argumentet StrLen_or_IndPtr i SQLBindCol. För mer information, se "Ytterligare kommentarer" i avsnittet "Descriptors and SQLBindCol".

Om den bundna adressen är 0 returneras inget datavärde, även om adressen som beräknats enligt föregående formel är icke noll.
Bindningsoffset Om radvis bindning används, lagras värdet på adressen som anges med attributet SQL_ATTR_ROW_BIND_OFFSET_PTR-satsen.

Om kolumnvis bindning används eller om värdet på attributet SQL_ATTR_ROW_BIND_OFFSET_PTR statement är en nullpekare, är bindningsoffset 0.
Radnummer Det 1-baserade numret för raden i raduppsättningen. För enkelradshämtningar, som är standard, är detta 1.
Elementstorlek Storleken på ett element i den bundna matrisen.

Om kolumnvis bindning används, är detta sizeof(SQLINTEGER) för buffertar för längd/indikator. För databuffertar är det värdet av BufferLength-argumentet i SQLBindCol om datatypen är variabel längd, och storleken på datatypen om datatypen har fast längd.

Om radvis bindning används är detta värdet av attributet SQL_ATTR_ROW_BIND_TYPE statement för både data och längd/indikatorbuffertar.

Deskriptorer och SQLBindCol

Följande avsnitt beskriver hur SQLBindCol interagerar med deskriptorer.

Caution

Att anropa SQLBindCol för en sats kan påverka andra satser. Detta sker när ARD som är kopplad till satsen uttryckligen tilldelas och även är kopplad till andra uttalanden. Eftersom SQLBindCol modifierar deskriptorn gäller ändringarna för alla satser som denna deskriptor är associerad med. Om detta inte är det nödvändiga beteendet bör applikationen separera denna deskriptor från de andra satserna innan den anropar SQLBindCol.

Argumentavbildningar

Konceptuellt utför SQLBindCol följande steg i följd:

  1. Anropar SQLGetStmtAttr för att hämta ARD-handtaget.

  2. Kallar SQLGetDescField för att hämta denna beskrivares SQL_DESC_COUNT-fält, och om värdet i ColumnNumber-argumentet överstiger värdet av SQL_DESC_COUNT, anropar SQLSetDescField för att öka värdet av SQL_DESC_COUNT till ColumnNumber.

  3. Anropar SQLSetDescField flera gånger för att tilldela värden till följande fält i ARD:n:

    • Sätter SQL_DESC_TYPE och SQL_DESC_CONCISE_TYPE till värdet TargetType, förutom att om TargetType är en av de koncisa identifierarna för en datetime- eller intervalsubtype, sätter den SQL_DESC_TYPE till SQL_DATETIME respektive SQL_INTERVAL; sätter SQL_DESC_CONCISE_TYPE till den korta identifieraren; och sätter SQL_DESC_DATETIME_INTERVAL_CODE till motsvarande datum-, tid- eller intervallsubkod.

    • Sätter en eller flera av SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE och SQL_DESC_DATETIME_INTERVAL_PRECISION, beroende på vad som är lämpligt för TargetType.

    • Sätter SQL_DESC_OCTET_LENGTH fältet till värdet BufferLength.

    • Sätter SQL_DESC_DATA_PTR fältet till värdet TargetValuePtr.

    • Sätter SQL_DESC_INDICATOR_PTR fältet till värdet StrLen_or_IndPtr. (Se följande stycke.)

    • Sätter SQL_DESC_OCTET_LENGTH_PTR fältet till värdet StrLen_or_IndPtr. (Se följande stycke.)

Variabeln som StrLen_or_IndPtr-argumentet syftar på används både för indikator- och längdinformation. Om en hämtning stöter på ett nollvärde för kolumnen, lagrar den SQL_NULL_DATA i denna variabel; annars lagrar den datalängden i denna variabel. Att skicka en nullpekare som StrLen_or_IndPtr hindrar hämtaoperationen från att returnera datans längd men gör att hämtan misslyckas om den stöter på ett nullvärde och inte har något sätt att returnera SQL_NULL_DATA.

Om anropet till SQLBindCol misslyckas är innehållet i deskriptorfälten som skulle ha satt i ARD odefinierat och värdet på det SQL_DESC_COUNT fältet i ARD förblir oförändrat.

Implicit återställning av COUNT-fältet

SQLBindCol sätter SQL_DESC_COUNT till värdet av ColumnNumber-argumentet endast när detta skulle öka värdet av SQL_DESC_COUNT. Om värdet i argumentet TargetValuePtr är en nullpekare och värdet i argumentet ColumnNumber är lika med SQL_DESC_COUNT (det vill säga när kolumnen med högst gräns avbinds), så sätts SQL_DESC_COUNT till antalet kolumner med högst kvarvarande gräns.

Försiktighetsåtgärder angående SQL_DEFAULT

För att framgångsrikt hämta kolumndata måste applikationen korrekt bestämma längden och startpunkten för datan i applikationsbufferten. När applikationen specificerar en explicit TargetType upptäcks missuppfattningar i applikationen lätt. När applikationen anger en TargetType av SQL_DEFAULT kan SQLBindCol tillämpas på en kolumn med en annan datatyp än den applikationen avser, antingen genom ändringar i metadata eller genom att applicera koden på en annan kolumn. I detta fall kan applikationen inte alltid bestämma början eller längden på den hämtade kolumndatan. Detta kan leda till orapporterade datafel eller minnesbrott.

Kodexempel

I följande exempel kör en applikation en SELECT-sats på tabellen Customers för att returnera en resultatuppsättning av kund-ID:n, namn och telefonnummer, sorterade efter namn. Den anropar sedan SQLBindCol för att binda kolumnerna med data till lokala buffertar. Slutligen hämtar applikationen varje datarad med SQLFetch och skriver ut varje kunds namn, ID och telefonnummer.

För fler kodexempel, se SQLBulkOperations Function, SQLColumns Function, SQLFetchScroll Function och SQLSetPos Function.

// SQLBindCol_ref.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <stdio.h>  
  
#define UNICODE  
#include <sqlext.h>  
  
#define NAME_LEN 50  
#define PHONE_LEN 60
  
void show_error() {  
   printf("error\n");  
}  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt = 0;  
   SQLRETURN retcode;  
   SQLWCHAR szName[NAME_LEN], szPhone[PHONE_LEN], sCustID[NAME_LEN];  
   SQLLEN cbName = 0, cbCustID = 0, cbPhone = 0;  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            // Connect to data source  
            retcode = SQLConnect(hdbc, (SQLWCHAR*) L"NorthWind", SQL_NTS, (SQLWCHAR*) NULL, 0, NULL, 0);  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {   
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               retcode = SQLExecDirect(hstmt, (SQLWCHAR *) L"SELECT CustomerID, ContactName, Phone FROM CUSTOMERS ORDER BY 2, 1, 3", SQL_NTS);  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
                  // Bind columns 1, 2, and 3  
                  retcode = SQLBindCol(hstmt, 1, SQL_C_WCHAR, &sCustID, 100, &cbCustID);  
                  retcode = SQLBindCol(hstmt, 2, SQL_C_WCHAR, szName, NAME_LEN, &cbName);  
                  retcode = SQLBindCol(hstmt, 3, SQL_C_WCHAR, szPhone, PHONE_LEN, &cbPhone);   
  
                  // Fetch and print each row of data. On an error, display a message and exit.  
                  for (int i=0 ; ; i++) {  
                     retcode = SQLFetch(hstmt);  
                     if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO)  
                        show_error();  
                     if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                     {
                        //replace wprintf with printf
                        //%S with %ls
                        //warning C4477: 'wprintf' : format string '%S' requires an argument of type 'char *'
                        //but variadic argument 2 has type 'SQLWCHAR *'
                        //wprintf(L"%d: %S %S %S\n", i + 1, sCustID, szName, szPhone);  
                        printf("%d: %ls %ls %ls\n", i + 1, sCustID, szName, szPhone);  
                    }    
                     else  
                        break;  
                  }  
               }  
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLCancel(hstmt);  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}  

Se även exempel på ODBC-program.

Mer information om Se
Returnerar information om en kolumn i en resultatmängd SQLDescribeCol-funktionen
Hämtar ett datablock eller bläddrar igenom en resultatuppsättning SQLFetchScroll-funktion
Hämtar flera rader med data SQLFetch-funktion
Släpper kolumnbuffertar på påståendet SQLFreeStmt-funktion
Hämtar en del av eller hela en datakolumn SQLGetData-funktion
Returnerar antalet resultatuppsättningskolumner SQLNumResultCols-funktionen