SQLBindCol – funkce

Soulad
Zavedená verze: Dodržování standardů ODBC 1.0: ISO 92

Summary
SQLBindCol připojuje aplikační datové buffery ke sloupcům ve výsledné sadě.

Syntax

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

Arguments

StatementHandle
[Vstup] Popisovač příkazu

Číslo sloupce
[Vstup] Číslo sloupce pro přiřazení výsledků. Sloupce jsou číslovány v rostoucím pořadí sloupců začínající od 0, kde sloupec 0 je sloupec záložek. Pokud se záložky nepoužívají – tedy atribut SQL_ATTR_USE_BOOKMARKS příkazu je nastaven na SQL_UB_OFF – pak čísla sloupců začínají na 1.

CílovýTyp
[Vstup] Identifikátor datového typu C bufferu *TargetValuePtr . Když ovladač získává data ze zdroje pomocí SQLFetch, SQLFetchScroll, SQLBulkOperations nebo SQLSetPos, převede data na tento typ; když odesílá data do datového zdroje pomocí SQLBulkOperations nebo SQLSetPos, ovladač převede data z tohoto typu. Pro seznam platných C datových typů a identifikátorů viz sekce C Datové typy v příloze D: Datové typy.

Pokud je argument TargetType intervalovým datovým typem, použijí se výchozí intervalová vedoucí přesnost (2) a výchozí intervalová přesnost sekund (6), jak jsou nastaveny v poli SQL_DESC_DATETIME_INTERVAL_PRECISION a SQL_DESC_PRECISION ARD, respektive. Pokud je argument TargetType SQL_C_NUMERIC, použijí se výchozí přesnost (definovaná ovladačem) a výchozí škála (0), jak jsou nastaveny v poli SQL_DESC_PRECISION a SQL_DESC_SCALE ARD. Pokud není vhodná žádná výchozí přesnost nebo škálování, aplikace by měla explicitně nastavit příslušné deskriptorové pole voláním do SQLSetDescField nebo SQLSetDescRec.

Můžete také zadat rozšířený typ dat v C. Další informace naleznete v tématu Datové typy jazyka C v rozhraní ODBC.

TargetValuePtr
[Odložený vstup/výstup] Ukazatel na datový buffer pro navázání na sloupec. SQLFetch a SQLFetchScroll vracejí data v tomto bufferu. SQLBulkOperations vrací data v tomto bufferu, když je Operation SQL_FETCH_BY_BOOKMARK; získává data z tohoto bufferu, když je Operation SQL_ADD nebo SQL_UPDATE_BY_BOOKMARK. SQLSetPos vrací data do tohoto bufferu, když je operace SQL_REFRESH; získává data z tohoto bufferu, když je Operation SQL_UPDATE.

Pokud je TargetValuePtr nullový ukazatel, ovladač odvázá datový buffer pro sloupec. Aplikace může všechny sloupce odvázat voláním SQLFreeStmt s volbou SQL_UNBIND. Aplikace může odvázat datový buffer pro sloupec, ale stále mít hranici délky/indikátorového bufferu pro sloupec, pokud je argument TargetValuePtr ve volání SQLBindCol nullovým ukazatelem, ale argument StrLen_or_IndPtr je platná hodnota.

BufferLength
[Vstup] Délka bufferu *TargetValuePtr v bajtech.

Ovladač používá BufferLength , aby se vyhnul zápisu za konec bufferu *TargetValuePtr , když vrací data proměnné délky, například znaková nebo binární data. Všimněte si, že ovladač počítá znak null-terminace, když vrací znaková data do *TargetValuePtr. * TargetValuePtr proto musí obsahovat místo pro znak null-terminace, jinak ovladač data zkrátí.

Když ovladač vrací data s pevnou délkou, například celočíselnou nebo datovou strukturu, ovladač ignoruje BufferLength a předpokládá, že buffer je dostatečně velký pro uložení dat. Proto je důležité, aby aplikace alokovala dostatečně velký buffer pro data s pevnou délkou, jinak ovladač zapíše za konec bufferu.

SQLBindCol vrací SQLSTATE HY090 (Neplatná délka řetězce nebo bufferu), když je BufferLength menší než 0, ale ne, když je BufferLength 0. Pokud však TargetType specifikuje typ znaku, aplikace by neměla nastavit BufferLength na 0, protože ovladače kompatibilní s ISO CLI v tomto případě vracejí SQLSTATE HY090 (Invalid string nebo buffer length).

StrLen_or_IndPtr
[Odložený vstup/výstup] Ukazatelem na buffer délky/indikátoru se navázá na sloupec. SQLFetch a SQLFetchScroll vracejí hodnotu v tomto bufferu. SQLBulkOperations získá hodnotu z tohoto bufferu, když je Operation SQL_ADD, SQL_UPDATE_BY_BOOKMARK nebo SQL_DELETE_BY_BOOKMARK. SQLBulkOperations vrací hodnotu v tomto bufferu, když je Operation SQL_FETCH_BY_BOOKMARK. SQLSetPos vrací hodnotu v tomto bufferu, když je Operation SQL_REFRESH; získá hodnotu z tohoto bufferu, když je operace SQL_UPDATE.

SQLFetch, SQLFetchScroll, SQLBulkOperations a SQLSetPos mohou v bufferu délky/indikátoru vracet následující hodnoty:

Délka dat, která lze vrátit
SQL_NO_TOTAL
SQL_NULL_DATA

Aplikace může do bufferu délky/indikátoru vložit následující hodnoty pro použití se SQLBulkOperations nebo SQLSetPos:

Délka odesílaných dat
SQL_NTS
SQL_NULL_DATA
SQL_DATA_AT_EXEC
Výsledek SQL_LEN_DATA_AT_EXEC makro
SQL_COLUMN_IGNORE

Pokud jsou indikátorový buffer a délkový buffer samostatné buffery, indikátorový buffer může vracet pouze SQL_NULL_DATA, zatímco buffer délky může vrátit všechny ostatní hodnoty.

Pro více informací viz SQLBulkOperations Function, SQLFetch Function, SQLSetPos Function a Použití hodnot délky/indikátoru.

Pokud je StrLen_or_IndPtr nulový ukazatel, nepoužívá se délka ani indikátorová hodnota. Jedná se o chybu při načítání dat a data jsou NULL.

Viz ODBC 64-Bit Information, pokud bude vaše aplikace běžet na 64bitovém operačním systému.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostika

Když SQLBindCol vrací SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, pokud se vyvolá SQLGetDiagRec s HandleType SQL_HANDLE_STMT a HandleStatementHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLBindCol obvykle vrací, a vysvětluje každou z nich v kontextu této funkce; notace "(DM)" předchází popisům SQLstavů vráceným Správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.

SQLSTATE	Error	Description
01000	Obecné upozornění	Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
07006	Porušení atributu omezeného datového typu	(DM) Argument ColumnNumber byl 0 a argument TargetType nebyl SQL_C_BOOKMARK ani SQL_C_VARBOOKMARK.
07009	Index neplatných deskriptorů	Hodnota zadaná pro argument ColumnNumber překročila maximální počet sloupců ve výsledné množině.
HY000	Obecná chyba	Došlo k chybě, pro kterou nebyla definována žádná specifická funkce SQLSTATE a pro kterou nebyla definována žádná implementace sqlSTATE. Chybová zpráva vrácená nástrojem SQLGetDiagRec v vyrovnávací paměti MessageText* popisuje chybu a její příčinu.
HY001	Chyba přidělení paměti	Ovladač nemohl přidělit paměť, která je nutná k podpoře provádění nebo dokončování funkce.
HY003	Neplatný typ aplikačního bufferu	Argument TargetType nebyl ani platným datovým typem, ani SQL_C_DEFAULT.
HY010	Chyba posloupnosti funkcí	(DM) Byla volána asynchronně spuštěná funkce pro popisovač připojení, který je přidružen k StatementHandle. Tato asynchronní funkce se stále spouštěla, když byl vyvolán SQLBindCol . (DM) SQLExecute, SQLExecDirect nebo SQLMoreResults byl volána pro StatementHandle a vrácena SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána před načtením dat pro všechny streamované parametry. (DM) Byla volána asynchronně vykonávající funkce pro CommandHandle a stále se spouštěla, když byla tato funkce vyvolána. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations nebo SQLSetPos byly volány pro StatementHandle a vráceny SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce.
HY013	Chyba správy paměti	Volání funkce nelze zpracovat, protože základní objekty paměti nelze získat přístup, pravděpodobně kvůli nedostatku paměti.
HY090	Neplatná délka řetězce nebo vyrovnávací paměti	(DM) Hodnota zadaná pro argument BufferLength byla menší než 0. (DM) Řidič byl ODBC 2. x ovladač, argument ColumnNumber byl nastaven na 0 a hodnota určená pro argument BufferLength nebyla rovna 4.
HY117	Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení.	(DM) Další informace o pozastaveném stavu naleznete v tématu FUNKCE SQLEndTran.
HYC00	Nepovinná funkce není implementována.	Ovladač nebo zdroj dat nepodporuje převod specifikovaný kombinací argumentu TargetType a specifického SQL datového typu příslušného sloupce. Argument ColumnNumber byl 0 a ovladač nepodporuje záložky. Ovladač podporuje pouze ODBC 2. x a argument TargetType byl jedním z následujících: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT a jakýkoli z intervalových typů dat C uvedených v C datových typech v příloze D: Datové typy. Ovladač podporuje pouze ODBC verze před verzí 3.50 a argument TargetType byl SQL_C_GUID.
HYT01	Vypršel časový limit připojení	Platnost časového limitu připojení vypršela, než zdroj dat odpověděl na žádost. Časový limit připojení je nastavený prostřednictvím sqlSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Ovladač tuto funkci nepodporuje.	(DM) Ovladač přidružený k StatementHandle nepodporuje funkci.

Comments

SQLBindCol se používá k přiřazení nebo vázání sloupců ve výsledné sadě s datovými buffery a buffery délky/indikátorů v aplikaci. Když aplikace volá SQLFetch, SQLFetchScroll nebo SQLSetPos pro načtení dat, ovladač vrátí data pro svázané sloupce ve specifikovaných bufferech; pro více informací viz SQLFetch Function. Když aplikace zavolá SQLBulkOperations k aktualizaci nebo vložení řádku, nebo SQLSetPos pro aktualizaci řádku, ovladač získá data pro vázané sloupce z daných bufferů; pro více informací viz SQLBulkOperations Function nebo SQLSetPos Function. Pro více informací o vazbě viz Vyhledávání výsledků (Basic).

Všimněte si, že sloupce nemusí být vázány, abyste z nich data získávali. Aplikace může také volat SQLGetData pro získání dat ze sloupců. Ačkoli je možné některé sloupce svázat do řádku a pro jiné volat SQLGetData , je to podřízeno určitým omezením. Pro více informací viz SQLGetData.

Sloupce pro vázání, rozvázání a opětovné vázání

Sloupec může být kdykoli omezen, uvolněn nebo znovu vyvolán, i poté, co byla data načtena z výsledné množiny. Nové svázání nabývá účinnosti při dalším volání funkce používající vazby. Například předpokládejme, že aplikace sváže sloupce ve výsledné množině a zavolá SQLFetch. Ovladač vrací data do vázaných bufferů. Nyní předpokládejme, že aplikace přiřadí sloupce k jiné sadě bufferů. Ovladač neukládá data pro právě načítaný řádek do nově vázaných bufferů. Místo toho počká, až bude SQLFetch znovu volán, a poté umístí data pro další řádek do nově vázaných bufferů.

Note

Atribut příkazu SQL_ATTR_USE_BOOKMARKS by měl být vždy nastaven před přiřazením sloupce 0. Není to povinné, ale důrazně doporučuji.

Propojení sloupců

Pro přiřazení sloupce aplikace volá SQLBindCol a předá číslo sloupce, typ, adresu a délku datového bufferu a adresu bufferu na délku/indikátor. Informace o tom, jak jsou tyto adresy používány, viz "Buffer Addresses" později v této části. Pro více informací o vazbě sloupců viz Používání SQLBindCol.

Používání těchto bufferů je odloženo; to znamená, že aplikace je připojí do SQLBindCol , ale ovladač k nim přistupuje z jiných funkcí – konkrétně SQLBulkOperations, SQLFetch, SQLFetchScroll nebo SQLSetPos. Je odpovědností aplikace zajistit, aby ukazatele uvedené v SQLBindCol zůstaly platné, dokud je vázání v platnosti. Pokud aplikace dovolí, aby se tyto ukazatele staly neplatnými – například uvolní buffer – a poté zavolá funkci, která očekává jejich platnost, důsledky nejsou definovány. Pro více informací viz Odložené buffery.

Vazba zůstává v platnosti, dokud není nahrazena novou vazbou, sloupec není uvolněn nebo dokud není příkaz uvolněn.

Rozvazující sloupy

Pro uvolnění jednoho sloupce aplikace volá SQLBindCol s číslem ColumnNumber nastaveným na číslo tohoto sloupce a TargetValuePtr nastaveným na nullový ukazatel. Pokud ColumnNumber odkazuje na nevázaný sloupec, SQLBindCol stále vrací SQL_SUCCESS.

Pro uvolnění všech sloupců aplikace volá SQLFreeStmt s fOption nastaveným na SQL_UNBIND. Toho lze také dosáhnout nastavením SQL_DESC_COUNT pole ARD na nulu.

Sloupy pro převazování

Aplikace může provést jednu ze dvou operací ke změně vazby:

Zavolejte SQLBindCol pro určení nového vazby pro sloupec, který je již vázaný. Ovladač přepíše starou vazbu novou.
Specifikujte offset, který bude přidán k adresě bufferu, která byla určena voláním vázání na SQLBindCol. Pro více informací viz další část "Vázání offsetů."

Vazebné posuny

Vazebný offset je hodnota, která se přidá k adresám datových a dlouho/indikátorových bufferů (jak je specifikováno v argumentu TargetValuePtr a StrLen_or_IndPtr ) před jejich dereferencací. Při použití offsetů jsou vazby "šablonou" toho, jak jsou buffery aplikace rozloženy, a aplikace může tuto "šablonu" přesunout do různých oblastí paměti změnou offsetu. Protože stejný offset je přidán ke každé adrese v každém bindingu, musí být relativní offsety mezi buffery pro různé sloupce stejné v rámci každé sady bufferů. To platí vždy při použití řadového vazby; aplikace musí pečlivě rozložit své buffery, aby to platilo při použití vazby po sloupcích.

Použití bounding offsetu má v podstatě stejný efekt jako převázání sloupce voláním SQLBindCol. Rozdíl je v tom, že nové volání SQLBindCol specifikuje nové adresy pro datový buffer a buffer délky/indikátoru, zatímco použití biningového offsetu adresy nemění, ale pouze k nim přidává offset. Aplikace může kdykoli nastavit nový offset a tento offset je vždy přidán k původně vázaným adresám. Konkrétně, pokud je offset nastaven na 0 nebo pokud je atribut příkazu na nulový ukazatel, ovladač používá původně vázané adresy.

Pro určení vázacího offsetu aplikace nastaví atribut příkazu SQL_ATTR_ROW_BIND_OFFSET_PTR na adresu SQLINTEGER bufferu. Než aplikace zavolá funkci, která používá vazby, vloží do tohoto bufferu offset v bajtech. Pro určení adresy bufferu, který se použije, ovladač přidá offset k adrese ve vazbě. Součet adresy a offsetu musí být platná adresa, ale adresa, ke které je offset přidán, nemusí být platná. Pro více informací o tom, jak se vázavací offsety používají, viz "Buffer Addresses" později v této části.

Vazebná pole

Pokud je velikost řádku (hodnota atributu SQL_ATTR_ROW_ARRAY_SIZE příkazu) větší než 1, aplikace sváže pole bufferů místo jednotlivých bufferů. Pro více informací viz Blokové kurzory.

Aplikace může svazovat pole dvěma způsoby:

Připojte pole ke každému sloupci. Tomu se říká sloupcové vázání , protože každá datová struktura (pole) obsahuje data pro jeden sloupec.
Definujte strukturu, která uchovává data pro celý řádek, a svážejte pole těchto struktur. Tomu se říká vazba po řádcích , protože každá datová struktura obsahuje data pro jeden řádek.

Každé pole bufferů musí obsahovat alespoň tolik prvků, kolik je velikost sady řádků.

Note

Aplikace musí ověřit, že zarovnání je platné. Pro více informací o zvažování zarovnání viz Geometrie.

Column-Wise vazba

Při vázání po sloupcích aplikace přiřadí ke každému sloupci samostatná data a pole délky/indikátorů.

Pro použití vazby po sloupcích aplikace nejprve nastaví atribut SQL_ATTR_ROW_BIND_TYPE příkazu na SQL_BIND_BY_COLUMN. (Toto je výchozí nastavení.) Pro omezení každého sloupce aplikace provádí následující kroky:

Přiděluje pole datového bufferu.
Přiděluje pole bufferů délky/indikátorů.

Note

Pokud aplikace zapisuje přímo do deskriptorů při použití sloupcového vazby, lze použít samostatná pole pro délková a indikační data.
Volá SQLBindCol s následujícími argumenty:
- TargetType je typ jednoho prvku v datovém bufferu.
- TargetValuePtr je adresa pole datového bufferu.
- BufferLength je velikost jednoho prvku v poli datové buffery. Argument BufferLength je ignorován, pokud jsou data s pevnou délkou.
- StrLen_or_IndPtr je adresa pole délky/indikátorů.

Pro více informací o tom, jak jsou tyto informace využívány, viz "Buffer Addresses" později v této části. Pro více informací o vázání po sloupcích viz Column-Wise Binding.

Row-Wise Vazba

Při řádkovém bindingu aplikace definuje strukturu, která obsahuje datová a dlouho/indikátorové buffery pro každý sloupec, který má být omezen.

Pro použití vazby po řádcích aplikace provádí následující kroky:

Definuje strukturu, která uchovává jeden řádek dat (včetně datových i dlouhový/indikátorových bufferů) a přiděluje pole těchto struktur.

Note

Pokud aplikace zapisuje přímo do deskriptorů při použití řádkového přiřazení, lze použít samostatná pole pro délku a indikátorová data.
Nastaví atribut SQL_ATTR_ROW_BIND_TYPE příkazu na velikost struktury obsahující jeden řádek dat nebo na velikost instance bufferu, do kterého budou sloupce s výsledky vázány. Délka musí zahrnovat prostor pro všechny vázané sloupce a jakékoli vyplnění struktury nebo bufferu, aby bylo zajištěno, že když se adresa vázaného sloupce zvýší o zadanou délku, výsledek ukáže na začátek stejného sloupce v následujícím řádku. Při použití operátoru sizeof v ANSI C je toto chování zaručené.
Volá SQLBindCol s následujícími argumenty pro každý sloupec, který má být omezen:
- TargetType je typ člena datového bufferu, který má být vázán na sloupec.
- TargetValuePtr je adresa člena datového bufferu v prvním prvku pole.
- BufferLength je velikost člena datového bufferu.
- StrLen_or_IndPtr je adresa člena délky/indikátoru, který má být vázán.

Pro více informací o tom, jak jsou tyto informace využívány, viz "Buffer Addresses" později v této části. Pro více informací o vázání po sloupcích viz Row-Wise Binding.

Adresy bufferů

Adresa bufferu je skutečná adresa datového nebo dlouho-indikátorového bufferu. Ovladač vypočítá adresu bufferu těsně před zápisem do bufferů (například během času načítání). Je vypočítán z následujícího vzorce, který využívá adresy specifikované v argumentech TargetValuePtr a StrLen_or_IndPtr , posun vázání a číslo řádku:

Vázaná adresa + Posuv vázání + ((číslo řádku - 1) x velikost prvku)

kde proměnné formule jsou definovány tak, jak je popsáno v následující tabulce.

Variable	Description
Vázaná adresa	U datových bufferů je adresa specifikována argumentem TargetValuePtr v SQLBindCol. Pro buffery délky/indikátorů je adresa zadaná argumentem StrLen_or_IndPtr v SQLBindCol. Pro více informací viz "Další komentáře" v sekci "Descriptors and SQLBindCol". Pokud je vázaná adresa 0, žádná datová hodnota se nevrátí, i když adresa vypočítaná předchozím vzorcem není nulová.
Vazebný offset	Pokud je použito řádkové přiřazení, hodnota uložená na adrese uvedené s atributem SQL_ATTR_ROW_BIND_OFFSET_PTR příkazu. Pokud je použito vázání po sloupcích nebo pokud je hodnota atributu SQL_ATTR_ROW_BIND_OFFSET_PTR příkazu null, posuv vázání je 0.
Číslo řádku	Číslo založené na 1 řádku v sadě řádků. Pro načítání z jednoho řádku, což je výchozí nastavení, je to 1.
Velikost prvku	Velikost prvku ve vázaném poli. Pokud se používá vazba po sloupcích, je to sizeof(SQLINTEGER) pro buffery délky/indikátorů. Pro datové buffery je to hodnota argumentu BufferLength v SQLBindCol , pokud je datový typ proměnné délky, a velikost datového typu, pokud je datový typ pevné délky. Pokud je použito řádkové vázání, jedná se o hodnotu atributu SQL_ATTR_ROW_BIND_TYPE příkazu jak pro data, tak pro buffery délky/indikátorů.

Descriptors a SQLBindCol

Následující sekce popisují, jak SQLBindCol interaguje s descriptory.

Caution

Volání SQLBindCol pro jeden příkaz může ovlivnit i jiné. K tomu dochází, když je ARD přiřazený k příkazu explicitně alokován a je také spojen s dalšími příkazy. Protože SQLBindCol upravuje deskriptor, úpravy se vztahují na všechny příkazy, s nimiž je tento deskriptor spojen. Pokud toto chování není požadované, měla by aplikace tento deskriptor oddělit od ostatních příkazů před zavoláním SQLBindCol.

Argumentové mapování

Konceptuálně SQLBindCol provádí následující kroky v pořadí:

Volá SQLGetStmtAttr pro získání ARD přezdívky.
Volá SQLGetDescField , aby získal SQL_DESC_COUNT pole tohoto popisu, a pokud hodnota v argumentu ColumnNumber překročí hodnotu SQL_DESC_COUNT, zavolá SQLSetDescField , aby zvýšil hodnotu SQL_DESC_COUNT na ColumnNumber.
Volá SQLSetDescField několikrát, aby přiřadil hodnoty následujícím polím ARD:
- Nastavuje SQL_DESC_TYPE a SQL_DESC_CONCISE_TYPE na hodnotu TargetType, kromě toho, že pokud je TargetType jedním z stručných identifikátorů podtypu datetime nebo interval, nastaví SQL_DESC_TYPE na SQL_DATETIME nebo SQL_INTERVAL; SQL_DESC_CONCISE_TYPE na stručný identifikátor; a nastavuje SQL_DESC_DATETIME_INTERVAL_CODE na odpovídající datetime nebo intervalový podkód.
- Nastaví jeden nebo více kusů SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE a SQL_DESC_DATETIME_INTERVAL_PRECISION, podle potřeby pro TargetType.
- Nastaví pole SQL_DESC_OCTET_LENGTH na hodnotu BufferLength.
- Nastaví pole SQL_DESC_DATA_PTR na hodnotu TargetValuePtr.
- Nastaví pole SQL_DESC_INDICATOR_PTR na hodnotu StrLen_or_IndPtr. (Viz následující odstavec.)
- Nastaví pole SQL_DESC_OCTET_LENGTH_PTR na hodnotu StrLen_or_IndPtr. (Viz následující odstavec.)

Proměnná, na kterou se StrLen_or_IndPtr argument odkazuje, se používá jak pro indikátory, tak pro informace o délce. Pokud fetch narazí na nulovou hodnotu sloupce, uloží SQL_NULL_DATA do této proměnné; jinak ukládá délku dat do této proměnné. Předání nullového ukazatele jako StrLen_or_IndPtr zabrání načtení vrátit délku dat, ale způsobí, že načtení selže, pokud narazí na nulovou hodnotu a nemá možnost SQL_NULL_DATA vrátit.

Pokud volání SQLBindCol selže, obsah deskriptorových polí, která by v ARD nastavoval, není definován a hodnota SQL_DESC_COUNT pole ARD zůstává nezměněna.

Implicitní resetování pole COUNT

SQLBindCol nastavuje SQL_DESC_COUNT na hodnotu argumentu ColumnNumber pouze tehdy, když by to zvýšilo hodnotu SQL_DESC_COUNT. Pokud je hodnota v argumentu TargetValuePtr nulový ukazatel a hodnota v argumentu ColumnNumber je rovna SQL_DESC_COUNT (tedy při odvázání sloupce s nejvyšší hranicí), pak je SQL_DESC_COUNT nastaveno na číslo nejvyšší zbývající zůstávající sloupce.

Varování ohledně SQL_DEFAULT

Pro úspěšné získání sloupcových dat musí aplikace správně určit délku a výchozí bod dat v aplikačním bufferu. Když aplikace specifikuje explicitní TargetType, mylné představy o aplikaci jsou snadno detekovatelné. Pokud však aplikace specifikuje TargetType SQL_DEFAULT, lze SQLBindCol aplikovat na sloupec jiného datového typu, než jaký aplikace zamýšlela, buď změnami metadat, nebo aplikací kódu na jiný sloupec. V takovém případě nemusí aplikace vždy určit začátek nebo délku načítaných sloupcových dat. To může vést k nehlášeným chybám v datech nebo narušení paměti.

Příklad kódu

V následujícím příkladu aplikace vykoná příkaz SELECT v tabulce Customers, aby vrátila sadu výsledků s ID zákazníků, jmény a telefonními čísly, seřazenou podle jména. Poté volá SQLBindCol , aby sloupce dat navázal na lokální buffery. Nakonec aplikace načítá každý řádek dat pomocí SQLFetch a vytiskne jméno, ID a telefonní číslo každého zákazníka.

Pro více příkladů kódu viz SQLBulkOperations Function, SQLColumns Function, SQLFetchScroll Function a 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);  
   }  
}

Viz také ukázkový program ODBC.

Informace o	Podívejte se
Vrácení informací o sloupci v množině výsledků	SQLDescribeCol Function
Načtení bloku dat nebo procházení sady výsledků	SQLFetchScroll – funkce
Načítání více řádků dat	Funkce SQLFetch
Uvolnění sloupcových bufferů na výpisu	FUNKCE SQLFreeStmt
Načtení části nebo celého sloupce dat	Funkce SQLGetData
Vrácení počtu sloupců výsledků	SQLNumResultCols Function

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-08-24