SQLBindCol függvény

Megfelelőség
Bevezetett verzió: ODBC 1.0 szabványmegfelelőség: ISO 92

Summary
SQLBindCol az alkalmazásadat-puffereket az eredményhalmaz oszlopaihoz köti.

Syntax

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

Arguments

StatementHandle
[Bemenet] Utasításkezelő.

Oszlopszám
[Bemenet] Az eredményhalmaz oszlopának száma kötött állapotban. Az oszlopokat növekvő oszlopsorrendben számozzák 0-tól kezdődően, ahol a 0-as oszlop a könyvjelzőoszlop. Ha nem használunk könyvjelzőket – vagyis az SQL_ATTR_USE_BOOKMARKS állítás attribútuma SQL_UB_OFF-re van állítva –, akkor az oszlopszámok 1-ről kezdődnek.

Céltípus
[Bemenet] A *TargetValuePtr puffer C adattípusának azonosítója. Amikor az adatforrásból származó adatokat a SQLFetch, SQLFetchScroll, SQLBulkOperations vagy SQLSetPos segítségével tölti be, az illesztőprogram ezt a típusba konvertálja; amikor az adatot az adatforrásba küldi SQLBulkOperations vagy SQLSetPos-szal, az illesztőprogram átalakítja az adatokat ebből a típusból. Az érvényes C adattípusok és típusazonosítók listájáért lásd a D melléklet: Adattípusok C adattípusok szekcióját.

Ha a TargetType érve intervallum adattípus, akkor az alapértelmezett intervallum vezető precitsiót (2) és az alapértelmezett intervallum másodperceket (6) használják, ahogyan az ARD SQL_DESC_DATETIME_INTERVAL_PRECISION és SQL_DESC_PRECISION mezőiben van beállítva, az adatokhoz. Ha a TargetType érve SQL_C_NUMERIC, akkor az alapértelmezett precizitást (driver-definifikált) és az alapértelmezett skálát (0) használják, ahogyan az ARD SQL_DESC_PRECISION és SQL_DESC_SCALE mezőiben van beállítva, az adatokhoz. Ha bármely alapértelmezett pontosság vagy skálázás nem megfelelő, az alkalmazásnak kifejezetten be kell állítania a megfelelő leíró mezőt SQLSetDescField vagy SQLSetDescRec hívással.

Megadhatsz egy kiterjesztett C adattípust is. További információ: C adattípusok az ODBC-ben.

TargetValuePtr
[Halasztott bemenet/kimenet] Mutatót az adatpufferre a kötődéshez az oszlophoz. Az SQLFetch és az SQLFetchScroll adatokat adnak vissza ebben a pufferben. Az SQLBulkOperations adatokat ad vissza ebben a pufferben, amikor az Operation SQL_FETCH_BY_BOOKMARK; adatokat kér ebből a pufferből, amikor az Operation SQL_ADD vagy SQL_UPDATE_BY_BOOKMARK. Az SQLSetPos adatokat ad vissza ebben a pufferben, amikor a művelet SQL_REFRESH; akkor kér adatokat ebből a pufferből, amikor az Operation SQL_UPDATE.

Ha a TargetValuePtr null mutató, az illesztőprogram megszünteti az oszlop adatpufferét. Egy alkalmazás az SQLFreeStmt hívásával az összes oszlopot megszüntetheti a SQL_UNBIND opcióval. Egy alkalmazás lebonthatja az adatpuffert egy oszlop számára, de továbbra is rendelkezik hossz/indikátor pufferhatárral az oszlophoz, ha az SQLBindCol hívásában szereplő TargetValuePtr argumentum null mutató, de az StrLen_or_IndPtr érve érvényes érték.

BufferLength
[Bemenet] A *TargetValuePtr puffer hossza bájtokban.

Az illesztőprogram a BufferLength-t használja, hogy elkerülje a *TargetValuePtr puffer végére írni, amikor változó hosszúságú adatokat, például karakter- vagy bináris adatokat ad vissza. Figyeljük meg, hogy az illesztőprogram a null-terminációs karaktert számolja, amikor visszaadja a karakteradatokat a *TargetValuePtr-nek. * Ezért a TargetValuePtr-nek helyet kell tartalmaznia a null-terminációs karakter számára, különben az illesztőprogram lerövidíti az adatokat.

Amikor az illesztőprogram fix hosszúságú adatokat ad vissza, például egész számot vagy dátumstruktúrát, az illesztőprogram figyelmen kívül hagyja a BufferLength-t , és feltételezi, hogy a puffer elég nagy az adatok tárolására. Ezért fontos, hogy az alkalmazás elég nagy puffert foglaljon rögzített hosszúságú adatokhoz, különben az illesztőprogram a puffer végénél túl ír.

Az SQLBindCol akkor adja vissza az SQLSTATE HY090-et (Invalid string or buffer length) akkor (Invalid string or buffer length), ha a BufferLength kevesebb, mint 0, de nem, ha a BufferLength 0. Ha azonban a TargetType karaktertípust ad meg, egy alkalmazásnak nem kell 0-ra állítania a BufferLength-et , mert az ISO CLI-kompatibilis illezserek akkor SQLSTATE HY090-et (Invalid string vagy buffer length) adnak vissza.

StrLen_or_IndPtr
[Halasztott bemenet/kimenet] A hosszúság/indikátor pufferre mutatót kell használni, hogy az oszlophoz kötődjön. Az SQLFetch és az SQLFetchScroll egy értéket ad vissza ebben a pufferben. Az SQLBulkOperations értéket nyer ki ebből a pufferből, amikor az Operation SQL_ADD, SQL_UPDATE_BY_BOOKMARK vagy SQL_DELETE_BY_BOOKMARK. Az SQLBulkOperations értéket ad vissza ebben a pufferben, amikor az Operation SQL_FETCH_BY_BOOKMARK. Az SQLSetPos értéket ad vissza ebben a pufferben, amikor az Operation SQL_REFRESH; akkor nyer egy értéket ebből a pufferből, amikor az Operation SQL_UPDATE.

Az SQLFetch, SQLFetchScroll, SQLBulkOperations és SQLSetPos a következő értékeket adhatja vissza a hosszúság/indikátor pufferben:

• A rendelkezésre álló adatok hossza

• SQL_NO_TOTAL

• SQL_NULL_DATA

Az alkalmazás a következő értékeket teheti a hosszúság/indikátor pufferbe SQLBulkOperations vagy SQLSetPos használatához:

• Az adott adatok hossza

• SQL_NTS

• SQL_NULL_DATA

• SQL_DATA_AT_EXEC

• A SQL_LEN_DATA_AT_EXEC makró eredménye

• SQL_COLUMN_IGNORE

Ha az indikátor puffer és a hosszpuffer külön pufferek, akkor az indikátorpuffer csak SQL_NULL_DATA-et tud visszaadni, míg a hosszpuffer minden más értéket visszaadhat.

További információért lásd: SQLBulkOperations Function, SQLFetch Function, SQLSetPos Function és Using Length/Indicator Values.

Ha StrLen_or_IndPtr nullmutató, akkor nem használnak hosszt vagy indikátorértéket. Ez hiba adat letöltésekor és az adat NULL.

Lásd : ODBC 64-bites információk, ha az alkalmazásod 64 bites operációs rendszeren fut-e.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR vagy SQL_INVALID_HANDLE.

Diagnostics

Amikor az SQLBindCol SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad vissza, egy hozzárendelt SQLSTATE érték elérhető SQLGetDiagRec hívásával, amely egy SQL_HANDLE_STMT HandleType és egy HandleType of StatementHandle (Handle) segítségével érhető el. Az alábbi táblázat felsorolja az SQLSTATE értékeket, amelyeket az SQLBindCol általában visszaad, és mindegyiket elmagyarázza ezen függvény kontextusában; a "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATE-leírásokat. Az egyes SQLSTATE-értékekhez társított visszatérési kód SQL_ERROR, kivéve, ha másként van feltüntetve.

SQLSTATE	Hiba	Description
01000	Általános figyelmeztetés	Illesztőprogram-specifikus tájékoztató üzenet. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
07006	Korlátozott adattípus-attribútumok megsértése	(DM) Az ColumnNumber érve 0 volt, a TargetType érve pedig nem volt SQL_C_BOOKMARK vagy SQL_C_VARBOOKMARK.
07009	Érvénytelen descriptor index	A ColumnNumber argumentumhoz megadott érték meghaladta az eredményhalmaz maximális oszlopszámát.
HY000	Általános hiba	Hiba történt, amely miatt nem volt konkrét SQLSTATE, és amelyhez nem definiáltak implementációspecifikus SQLSTATE-t. Az SQLGetDiagRec által a *MessageText pufferben visszaadott hibaüzenet leírja a hibát és annak okát.
HY001	Memóriafoglalási hiba	Az illesztőprogram nem tudta lefoglalni a függvény végrehajtásának vagy befejezésének támogatásához szükséges memóriát.
HY003	Érvénytelen alkalmazáspuffer típus	A TargetType érv sem érvényes adattípus, sem SQL_C_DEFAULT.
HY010	Függvényütemezési hiba	(DM) A StatementHandle-hez társított kapcsolati leíróhoz aszinkron módon végrehajtó függvény lett meghívva. Ez az aszinkron függvény még akkor futott, amikor az SQLBindCol-t hívták. (DM) SQLExecute, SQLExecDirect vagy SQLMoreResults lett meghívva az Utasításkezelőhöz , és SQL_PARAM_DATA_AVAILABLE ad vissza. Ez a függvény az összes streamelt paraméter adatainak lekérése előtt lett meghívva. (DM) Egy aszinkron futó függvényt hívtak a StatementHandle számára, és még akkor futott, amikor ezt a függvényt hívták. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations vagy SQLSetPos lett meghívva az Utasításkezelőhöz , és SQL_NEED_DATA. Ezt a függvényt az összes adatvégrehajtási paraméter vagy oszlop adatküldése előtt hívták meg.
HY013	Memóriakezelési hiba	A függvényhívás nem dolgozható fel, mert a mögöttes memóriaobjektumok nem érhetők el, esetleg a memóriahiány miatt.
HY090	Érvénytelen sztring vagy puffer hossza	(DM) A BufferLength argument értéke kevesebb volt, mint 0. (DM) A sofőr egy ODBC 2 volt. x driver esetén a ColumnNumber argumentum 0-ra volt állítva, és a BufferLength érve értéke nem volt 4-es.
HY117	A kapcsolat ismeretlen tranzakciós állapot miatt fel van függesztve. Csak a leválasztási és írásvédett függvények engedélyezettek.	(DM) A felfüggesztett állapotról további információt az SQLEndTran függvényben talál.
HYC00	A választható funkció nem implementálva	Az illesztőprogram vagy adatforrás nem támogatja azt az átalakítást, amelyet a TargetType érve és a megfelelő oszlop illesztő-specifikus SQL adattípusának kombinációja határoz meg. Az argumentum ColumnNumber 0 volt, és az illesztőprogram nem támogatja a könyvjelzőket. A meghajtó csak az ODBC 2-t támogatja. x és az érv a TargetType az alábbiak egyike volt: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT valamint bármely C intervallum adattípus, amely a D melléklet C adattípusok című részében szerepel. Az illezőprogram csak az ODBC verziókat támogatja a 3.50 előtti verziókban, és a TargetType argumentum SQL_C_GUID volt.
HYT01	A kapcsolati időkorlát lejárt	A kapcsolat időtúllépési időtartama lejárt, mielőtt az adatforrás válaszolt a kérésre. A kapcsolat időtúllépési időszaka az SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT keresztül van beállítva.
IM001	Az illesztőprogram nem támogatja ezt a függvényt	(DM) Az StatementHandle-hez társított illesztőprogram nem támogatja a függvényt.

Comments

Az SQLBindCol az eredményhalmazban lévő oszlopokat az alkalmazásban lévő adatpufferekhez és hosszú/indikátor pufferekhez társítja vagy köti . Amikor az alkalmazás az SQLFetch-et, SQLFetchScroll vagy SQLSetPos fájlokat hívja az adatok behozatalához, az illesztőprogram visszaadja az adatokat a megadott pufferekben lévő kötött oszlopokhoz; További információért lásd: SQLFetch függvény. Amikor az alkalmazás SQLBulkOperations-t hív sor frissítésére vagy hozzáadására, vagy SQLSetPos-t a sor frissítéséhez, az illesztőprogram lekéri a megadott pufferekből a kötött oszlopok adatait; további információért lásd: SQLBulkOperations Function vagy SQLSetPos Function. További információért a kötésről lásd: Eredmények (Alap) lekérdezése.

Figyeld meg, hogy az oszlopoknak nem kell kötöttek legyenek ahhoz, hogy adatokat szerezzenek elő belőlük. Egy alkalmazás az SQLGetData-t is hívhatja, hogy adatokat gyűjtsön az oszlopokról. Bár lehetséges egyes oszlopokat sorba kötni, másoknál SQLGetData-t hívni, ez bizonyos korlátozásoknak van kitéve. További információért lásd: SQLGetData.

Kötés, kibontás és újrakötés oszlopok

Egy oszlop bármikor lehet bekötözhető, nem kötött vagy visszapattanódhat, még akkor is, ha az adatokat az eredményhalmazból leváltották. Az új kötés akkor lép életbe, amikor legközelebb egy függvényt, amely kötéseket használ, meghívják. Például, tegyük fel, hogy egy alkalmazás köti az eredményhalmaz oszlopait, és meghívja az SQLFetch-et. Az illesztőprogram visszaadja az adatokat a kötött pufferekben. Most tegyük fel, hogy az alkalmazás egy másik pufferkészlethez köti az oszlopokat. Az illeszpress nem teszi be az éppen lehozott sor adatait az újonnan kötött pufferekben. Ehelyett megvárja, amíg az SQLFetch újra meghívásra kerül, majd a következő sor adatait az újonnan kötött pufferekre helyezi.

Note

Az utasítás attribútumot SQL_ATTR_USE_BOOKMARKS mindig be kell állítani, mielőtt egy oszlopot a 0-as oszlophoz kötnék. Ez nem kötelező, de erősen ajánlott.

Kötésoszlopok

Egy oszlop kötéséhez egy alkalmazás meghívja az SQLBindCol-t , és továbbítja az adatpuffer oszlopszámát, típusát, címét és hosszát, valamint a hossz/indikátor puffer címét. A címek használatáról további információért lásd a "Puffercímek" (Puffercímek) részt ebben a szakaszban. További információért a kötési oszlopokról lásd: Using SQLBindCol.

Ezeknek a puffereknek a használatát elhalasztják; vagyis az alkalmazás az SQLBindCol-ban köti őket, de az illezőprogram más funkciókból – nevezetesen SQLBulkOperations, SQLFetch, SQLFetchScroll vagy SQLSetPos – keresztül fér hozzájuk. Az alkalmazás felelőssége, hogy az SQLBindCol-ban megadott mutatók érvényesek maradjanak, amíg a kötés életben marad. Ha az alkalmazás lehetővé teszi, hogy ezek az indikátorok érvénytelenné váljanak – például felszabadít egy puffert –, majd egy olyan függvényt hív, amely érvényesnek számít, a következmények nem meghatározottak. További információért lásd: Halasztott pufferek.

A kötés életben marad, amíg új kötéssel helyettesítik, az oszlop nem lesz kötelve, vagy az állítás szabadul fel.

Oszlopok kibontása

Egy oszlop megszüntetéséhez egy alkalmazás az SQLBindCol-t hívja, ahol a ColumnNumber az adott oszlop száma, a TargetValuePtr pedig null mutatóra van állítva. Ha a ColumnNumber egy korlátlan oszlopra utal, az SQLBindCol továbbra is SQL_SUCCESS-t ad vissza.

Az összes oszlop megszüntetéséhez egy alkalmazás az SQLFreeStmt-t hívja SQL_UNBIND-re beállítva fOption-val . Ez úgy is megvalósítható, hogy az ARD SQL_DESC_COUNT mezőjét nullára állítjuk.

Újrakötési oszlopok

Egy alkalmazás két műveletet végezhet a kötés megváltoztatásához:

• Hívjuk az SQLBindCol-t , hogy új kötést határozz meg egy már kötött oszlophoz. A meghajtó felülírja a régi kötést az újabbal.

• Megadjunk egy olyan eltérést, amelyet a puffercímhez adunk hozzá, amelyet az SQLBindCol kötési hívása adott meg. További információért lásd a következő szakaszt, "Kötési eltolások."

Kötési eltolások

A kötési eltolás egy olyan érték, amelyet az adatok és a hosszúság/indikátor puffereinek címeihez (ahogy a TargetValuePtr és StrLen_or_IndPtr érve megadja) adják hozzá, mielőtt azokat dereferálnák. Eltolások használatában a kötések egy "sablon" a pufferek elrendezésének "sablonjaként" szolgálnak, és az alkalmazás ezt a "sablont" a memória különböző területeire tudja áthelyezni az eltérés megváltoztatásával. Mivel ugyanazt az eltolást adják hozzá minden címhez minden kötésben, a különböző oszlopok pufferei közötti relatív eltolásoknak ugyanazoknak kell lenniük minden pufferkészleten belül. Ez mindig igaz, ha soronként kötött kötvényt alkalmazunk; Az alkalmazásnak gondosan kell elhelyeznie a puffereket, hogy ez igaz legyen oszloponkénti kötés esetén.

A kötési offset használata gyakorlatilag ugyanazt a hatást nyújtja, mint az oszlop újrakötése SQLBindCol hívásával. A különbség az, hogy egy új SQLBindCol-hívás új címeket ad az adatpufferhez és a hosszúság/indikátor pufferhez, míg a kötési offset használata nem változtatja meg a címeket, csak hozzáad egy eltolást hozzájuk. Az alkalmazás bármikor beállíthat egy új elzárást, és ezt az eltérést mindig hozzáadják az eredetileg kötött címekhez. Különösen, ha az eloszlás 0-ra van állítva, vagy ha az utasítás attribútuma null mutatóra van állítva, az illesztőprogram az eredetileg kötött címeket használja.

A kötési eltolás megadásához az alkalmazás a SQL_ATTR_ROW_BIND_OFFSET_PTR utasítás attribútumát egy SQLINTEGER puffer címére állítja be. Mielőtt az alkalmazás meghív egy függvényt, amely bindingeket használ, egy bájtban eloszlat tesz ebben a pufferben. A puffer címének meghatározásához az illesztő hozzáadja az offsetet a kötésben lévő címhez. A cím és az eltolás összegének érvényesnek kell lennie, de az a cím, amelyhez az eltolás hozzáadódik, nem feltétlenül érvényes. További információért a kötési eltérések használatáról lásd a "Puffercímek" (Puffercímek) oldalán ebben a szakaszban.

Kötési tömbök

Ha a sorhalmaz mérete (az SQL_ATTR_ROW_ARRAY_SIZE utasítás attribútumának értéke) nagyobb, mint 1, az alkalmazás puffertömböket köt egyetlen puffer helyett. További információért lásd: Blokkkurzorok.

Az alkalmazás kétféleképpen kötheti meg a tömböket:

• Kössön tömböt minden oszlophoz. Ezt oszloponkénti kötésnek nevezik, mert minden adatszerkezet (tömb) egyetlen oszlop adatait tartalmazza.

• Definiáljunk egy struktúrát, amely egy egész sorra tárolja az adatokat, és köt be ezekből a struktúrákból álló tömböket. Ezt soronkénti kötésnek nevezik, mert minden adatszerkezet tartalmazza egyetlen sor adatait.

Minden puffertömbnek legalább annyi elemet kell tartalmaznia, mint a sorhalmaz mérete.

Note

Az alkalmazásnak igazolnia kell, hogy az igazítás érvényes. További információért az igazítási szempontokról lásd: Igazítás.

Column-Wise kötés

Oszloponkénti kötésben az alkalmazás külön adat- és hosszú/indikátor tömböket köt minden oszlophoz.

Oszloponkénti kötéshez az alkalmazás először a SQL_ATTR_ROW_BIND_TYPE állítás attribútumát SQL_BIND_BY_COLUMN-re állítja be. (Ez az alapértelmezett.) Minden oszlop kötözéséhez az alkalmazás a következő lépéseket végzi:

1. Adatpuffer tömböt oszt ki.

2. Hossz/indikátor pufferekből álló tömböt oszt ki.

   Note

   Ha az alkalmazás közvetlenül írja a leírókat oszloponkénti kötés esetén, külön tömbök használhatók a hosszúsághoz és az indikátoradatokhoz.

3. Az SQLBindCol-t a következő argumentumokkal hívja:

   • A TargetType egyetlen elem típusa az adatpuffer tömbben.

   • A TargetValuePtr az adatpuffer tömb címe.

   • A BufferLength egyetlen elem mérete az adatpuffer tömbben. A BufferLength érvet figyelmen kívül hagyják, ha az adat fix hosszúságú adat.

   • StrLen_or_IndPtr a hosszúság/mutató tömb címe.

További információért az információ felhasználásáról lásd a "Puffercímek" (Puffercímek) rész későbbi részében. További információért az oszloponkénti kötésről lásd aColumn-Wise Kötést.

Row-Wise kötés

Soronkénti kötésben az alkalmazás olyan struktúrát definiál, amely adatokat és hosszú/indikátor puffereket tartalmaz minden egyes oszlophoz, amelyeket kötöttek.

A soronkénti kötés alkalmazásához az alkalmazás a következő lépéseket végzi:

1. Definiál egy struktúrát, amely egyetlen adatsort tárol (beleértve az adatot és a hosszúság/indikátor puffereket), és ezek tömbje ezeket a struktúrákat osztja ki.

   Note

   Ha az alkalmazás közvetlenül írja a leírókat soronkénti kötés során, külön mezők használhatók a hosszúság- és indikátoradatokhoz.

2. A SQL_ATTR_ROW_BIND_TYPE állítás attribútumát annak a struktúrának a méretére állítja, amely egyetlen adatsort tartalmaz, vagy egy puffer példányának méretére, amelybe az eredményoszlopok kötődnek. A hosszúságnak tartalmaznia kell a teret az összes kötött oszlophoz, valamint a szerkezet vagy puffer bármilyen tömbesítését, hogy biztosítsák, hogy amikor egy kötött oszlop címét a megadott hosszúsággal növeljük, az eredmény a következő sorban ugyanazon oszlop elejére mutat. Az ANSI C méretoperátorának alkalmazásával ez a viselkedés garantált.

3. Az SQLBindCol-t hívja az alábbi argumentumokkal minden egyes oszlopra, amelyet kötöttek:

   • A TargetType az a típus, amelyet az adatpuffer tag az oszlophoz köt.

   • A TargetValuePtr az adatpuffer tagjának címe az első tömbelemben.

   • BufferLength az adatpuffer tag mérete.

   • StrLen_or_IndPtr a kötözendő hosszúság/mutató tag címe.

További információért az információ felhasználásáról lásd a "Puffercímek" (Puffercímek) rész későbbi részében. További információért az oszloponkénti kötésről lásd aRow-Wise Kötést.

Puffercímek

A puffercím az adat vagy a hosszúság/indikátor puffer tényleges címe. Az illesztőprogram pont azelőtt számolja ki a puffercímet, hogy írna a pufferekhez (például a bevonási idő alatt). A következő képletből számítjuk, amely a TargetValuePtr és StrLen_or_IndPtr argumentumokban megadott címeket, a kötési eltolást és a sorszámot használja:

Kötött cím + Kötés eloszlás + ((sorszám - 1) x elemméret)

ahol a képlet változói a következő táblázatban leírtak szerint definiálódnak.

Variable	Description
Kötött cím	Adatpufferek esetén az SQLBindColTargetValuePtr argumentumával megadott cím. Hosszú/indikátor puffereknél az SQLBindColStrLen_or_IndPtr argumentumával megadott cím. További információért lásd a "Additional Comments" (További hozzászólások) részt a "Descriptors and SQLBindCol" részben. Ha a határcím 0, akkor nem tér vissza az adatérték, még akkor sem, ha az előző képlet által kiszámított cím nem nulla.
Kötés elmozdulás	Ha soronként kötött kötést alkalmazunk, az érték a megadott címen tárolt érték a SQL_ATTR_ROW_BIND_OFFSET_PTR utasítás attribútumjával. Ha oszloponként kötött kötést alkalmazunk, vagy ha a SQL_ATTR_ROW_BIND_OFFSET_PTR állítás attribútumának értéke null mutató, akkor a kötési eltolás 0.
Sor szám	A sorban lévő sor 1-es száma. Az alapértelmezett, egysoros fetch-ek esetén ez 1.
Elemméret	Egy elem mérete a kötött tömbben. Ha oszloponként kötést alkalmazunk, ez sizeof (SQLINTEGER) hosszúság/indikátor pufferekhez. Adatpufferek esetén ez a BufferLength argumentus értéke az SQLBindCol-ban , ha az adattípus változó hosszúságú, és az adattípus mérete, ha az adattípus fix hosszúságú. Ha soronként kötést alkalmazunk, ez az SQL_ATTR_ROW_BIND_TYPE állítás attribútumának értéke mind az adatokra, mind a hosszúság/indikátor pufferekre.

Leírók és SQLBindCol

Az alábbi szakaszok bemutatják, hogyan lép kölcsönhatásba az SQLBindCol a leírókkal.

Caution

Az SQLBindCol hívása egy utasításra hatással lehet más utasításokra. Ez akkor történik, amikor az állításhoz kapcsolódó ARD kifejezetten el van osztva, és más állításokkal is összefügg. Mivel az SQLBindCol módosítja a leírót, a módosítások minden olyan állításra vonatkoznak, amelyekhez ez a leíró kapcsolódik. Ha ez nem a szükséges viselkedés, az alkalmazásnak szét kell választania ezt a leírót a többi utasítástól, mielőtt az SQLBindCol-t hívja.

Érvelési összeegyeztetések

Koncepcionálisan az SQLBindCol a következő lépéseket végzi sorban:

1. Meghívja az SQLGetStmtAttr-t , hogy megkapja az ARD handle-t.

2. Meghívja az SQLGetDescField-et, hogy megkapja ennek a leírónak a SQL_DESC_COUNT mezőjét, és ha a ColumnNumber érve értéke meghaladja a SQL_DESC_COUNT értékét, akkor az SQLSetDescField segítségével növeli SQL_DESC_COUNT értékét ColumnNumber-re.

3. Többször is hívja az SQLSetDescField-et , hogy értékeket rendeljen az ARD következő mezőinek:

   • A TargetType értékéhez SQL_DESC_TYPE és SQL_DESC_CONCISE_TYPE beállítja, kivéve, hogy ha a TargetType egy dátum vagy intervallum altípus egyik tömör azonosítója, akkor SQL_DESC_TYPE-t SQL_DATETIME-re vagy SQL_INTERVAL-re állítja be; SQL_DESC_CONCISE_TYPE állítja be a rövid azonosítóra; és SQL_DESC_DATETIME_INTERVAL_CODE a megfelelő dátumidő- vagy intervallum alkódot állítja be.

   • Egy vagy több SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE és SQL_DESC_DATETIME_INTERVAL_PRECISION beállítja, ahogy a TargetType megfelelő.

   • A SQL_DESC_OCTET_LENGTH mezőt BufferLength értékre állítja be.

   • A SQL_DESC_DATA_PTR mezőt TargetValuePtr értékére állítja be.

   • A SQL_DESC_INDICATOR_PTR mezőt StrLen_or_IndPtr értékre állítja. (Lásd a következő bekezdést.)

   • A SQL_DESC_OCTET_LENGTH_PTR mezőt StrLen_or_IndPtr értékre állítja. (Lásd a következő bekezdést.)

Az a változó, amelyre a StrLen_or_IndPtr argumentum utal, mind az indikátor, mind a hossz információra szolgál. Ha egy fetch null értéket talál az oszlopban, SQL_NULL_DATA tárolja ebben a változóban; egyébként az adathosszt ebben a változóban tárolja. Ha null mutatót passzolunk StrLen_or_IndPtr-ként , az megakadályozza, hogy a fetch művelet visszaadja az adathosszt, de a fetch sikertelenné válik, ha null értéket talál, és nincs mód visszaadni SQL_NULL_DATA.

Ha az SQLBindCol hívása sikertelen, az ARD-ben beállított definitormezők tartalma nem lesz, és az ARD SQL_DESC_COUNT mezőjének értéke változatlan.

A COUNT mező implicit újraindítása

Az SQLBindCol csak akkor állítja be SQL_DESC_COUNT-t a ColumnNumber argumentum értékére, amikor ez növelné a SQL_DESC_COUNT értékét. Ha a TargetValuePtr argumentum értéke null mutató, és a ColumnNumber argumentus értéke egyenlő SQL_DESC_COUNT-vel (azaz a legmagasabb korlátú oszlop megszüntetésekor), akkor SQL_DESC_COUNT a legmagasabb megmaradt szárnyú oszlop számára van állítva.

Figyelmeztetések SQL_DEFAULT

Az oszlopadatok sikeres lekéréséhez az alkalmazásnak helyesen meg kell határoznia az alkalmazás pufferben lévő adatok hosszát és kezdőpontját. Ha az alkalmazás explicit TargetType-t ad meg, az alkalmazás tévhitei könnyen felismerhetők. Azonban, ha az alkalmazás meghatározza a SQL_DEFAULT TargetType-jét , az SQLBindCol alkalmazható egy másik adattípusú oszlopra, mint amit az alkalmazás tervezett, akár a metaadat módosításából, akár a kód egy másik oszlopba való alkalmazásával. Ebben az esetben az alkalmazás nem mindig határozza meg a lehozott oszlopadatok kezdetét vagy hosszát. Ez jelentetlen adathibákhoz vagy memóriazavarokhoz vezethet.

Kódpélda

A következő példában egy alkalmazás egy SELECT utasítást hajt végre az Ügyfelek táblán, hogy visszaadja az ügyfélazonosítók, nevek és telefonszámok eredménykészletét, név szerint rendezve. Ezután az SQLBindCol-t hívja, hogy az adatoszlopokat helyi pufferekhez kötje. Végül az alkalmazás minden adatsort letölt SQLFetch-kel , és kinyomtatja minden ügyfél nevét, azonosítóját és telefonszámát.

További kódpéldákért lásd: SQLBulkOperations Function, SQLColumns Function, SQLFetchScroll Function és 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);  
   }  
}  

Lásd minta ODBC programot.

Kapcsolódó funkciók

Információ erről:	Nézze
Információ visszaküldése egy oszlopról az eredményhalmazban	SQLDescribeCol függvény
Adatblokk beolvasása vagy egy eredményhalmaz görgetése	SQLFetchScroll függvény
Több adatsor beolvasása	SQLFetch függvény
Oszloppufferek felszabadítása az állításon	SQLFreeStmt függvény
Adatoszlop egy részének vagy egészének beolvasása	SQLGetData függvény
Az eredményhalmaz oszlopainak számának visszaállítása	SQLNumResultCols függvény

Kapcsolódó tartalom

• ODBC API referencia
• ODBC-fejlécfájlok