Funkce SQLGetData

Článek
01/02/2025

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

souhrnu
SQLGetData načte data pro jeden sloupec v sadě výsledků nebo pro jeden parametr po SQLParamData vrátí SQL_PARAM_DATA_AVAILABLE. Lze ji volat vícekrát, aby se data o proměnlivé délce načítala v částech.

Syntax

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

Argumenty

StatementHandle
[Vstup] Popisovač příkazu

Col_or_Param_Num
[Vstup] Pro načtení dat sloupce se jedná o počet sloupců, pro který se mají vrátit data. Sloupce sady výsledků jsou očíslovány vzestupným pořadím sloupců počínaje číslem 1. Sloupec záložky je sloupec číslo 0; tuto možnost lze zadat pouze v případě, že jsou povoleny záložky.

Při načítání dat parametrů se jedná o pořadové číslo parametru, které začíná na 1.

TargetType
[Vstup] Identifikátor typu C datového typu *TargetValuePtr vyrovnávací paměti. Seznam platných datových typů a identifikátorů typů jazyka C najdete v části datové typy C v dodatku D: Datové typy.

Pokud je TargetType SQL_ARD_TYPE, ovladač použije identifikátor typu zadaný v poli SQL_DESC_CONCISE_TYPE ARD. Pokud TargetType SQL_APD_TYPE, SQLGetData použije stejný datový typ C, který byl zadán v SQLBindParameter. V opačném případě datový typ jazyka C zadaný v SQLGetData přepíše datový typ jazyka C zadaný v SQLBindParameter. Pokud je SQL_C_DEFAULT, ovladač vybere výchozí datový typ C na základě datového typu SQL zdroje.

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

TargetValuePtr
[Výstup] Ukazatel na vyrovnávací paměť, ve které se mají vrátit data.

TargetValuePtr nemůže mít hodnotu NULL.

bufferLength
[Vstup] Délka vyrovnávací pamětiTargetValuePtr v bajtech.

Ovladač používá BufferLength, aby se zabránilo zápisu po konci *TargetValuePtr vyrovnávací paměti při vrácení dat o délce proměnné, jako jsou znaková nebo binární data. Všimněte si, že ovladač spočítá znak ukončení null při vrácení znakových dat do *TargetValuePtr. * TargetValuePtr proto musí obsahovat mezeru pro znak ukončení null nebo ovladač zkrátí data.

Pokud ovladač vrátí data s pevnou délkou, jako je celé číslo nebo struktura kalendářních dat, ovladač ignoruje BufferLength a předpokládá, že vyrovnávací paměť je dostatečně velká, aby data držela. Proto je důležité, aby aplikace přidělila dostatečnou vyrovnávací paměť pro data s pevnou délkou nebo ovladač zapíše za konec vyrovnávací paměti.

SQLGetData vrátí hodnotu SQLSTATE HY090 (neplatný řetězec nebo délka vyrovnávací paměti), pokud BufferLength je menší než 0, ale ne, pokud BufferLength je 0.

StrLen_or_IndPtr
[Výstup] Ukazatel na vyrovnávací paměť, ve které se má vrátit délka nebo hodnota ukazatele. Pokud se jedná o ukazatel null, nevrátí se žádná délka nebo hodnota ukazatele. Tato chyba vrátí chybu, když načtená data mají hodnotu NULL.

SQLGetData může v vyrovnávací paměti délky nebo ukazatele vrátit následující hodnoty:

Délka dostupných dat pro vrácení
SQL_NO_TOTAL
SQL_NULL_DATA

Další informace najdete v tématu Použití hodnot délky a ukazatele a Komentáře v tomto tématu.

Návraty

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostika

Když SQLGetData vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze přidruženou hodnotu SQLSTATE získat voláním SQLGetDiagRec s HandleType SQL_HANDLE_STMT a popisovačStatementHandle . Následující tabulka uvádí hodnoty SQLSTATE, které běžně vrací SQLGetData a vysvětluje každý z nich v kontextu této funkce; notace "(DM)" předchází popisy funkcí SQLSTATEs vrácených správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.

SQLSTATE	Chyba	Popis
01000	Obecné upozornění	Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
01004	Řetězcová data, zkrácená vpravo	Ne všechna data pro zadaný sloupec, Col_or_Param_Num, lze načíst v jednom volání funkce. SQL_NO_TOTAL nebo délku dat zbývajících v zadaném sloupci před aktuálním voláním sqlGetData se vrátí v *StrLen_or_IndPtr. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) Další informace o použití více volání SQLGetData pro jeden sloupec najdete v tématu Komentáře.
01S07	Zlomkové zkrácení	Data vrácená pro jeden nebo více sloupců byla zkrácena. U číselných datových typů byla zlomková část čísla zkrácena. Pro čas, časové razítko a intervalové datové typy obsahující časovou komponentu se zlomková část času zkrátila. (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
07006	Porušení atributu omezeného datového typu	Datovou hodnotu sloupce v sadě výsledků nelze převést na datový typ jazyka C určený argumentem TargetType.
07009	Neplatný index popisovače	Hodnota zadaná pro argument Col_or_Param_Num byla 0 a atribut příkazu SQL_ATTR_USE_BOOKMARKS byl nastaven na SQL_UB_OFF. Hodnota zadaná pro argument Col_or_Param_Num byla větší než počet sloupců v sadě výsledků. Hodnota Col_or_Param_Num nebyla rovna pořadové hodnotě parametru, který je k dispozici. (DM) Zadaný sloupec byl vázán. Tento popis se nevztahuje na ovladače, které vrací SQL_GD_BOUND bitová maska pro možnost SQL_GETDATA_EXTENSIONS v SQLGetInfo. (DM) Počet zadaného sloupce byl menší nebo roven počtu nejvyššího vázaného sloupce. Tento popis se nevztahuje na ovladače, které vrací SQL_GD_ANY_COLUMN bitová maska pro možnost SQL_GETDATA_EXTENSIONS v SQLGetInfo. (DM) Aplikace již volala SQLGetData pro aktuální řádek; číslo sloupce zadaného v aktuálním volání bylo menší než číslo sloupce zadaného v předchozím volání; a ovladač nevrací SQL_GD_ANY_ORDER bitovou masku pro možnost SQL_GETDATA_EXTENSIONS v SQLGetInfo. (DM) Argument TargetType byl SQL_ARD_TYPE a záznam popisovače Col_or_Param_Num v ARD neprošel kontrolou konzistence. (DM) Argument TargetType byl SQL_ARD_TYPE a hodnota v poli SQL_DESC_COUNT ARD byla menší než argument Col_or_Param_Num.
08S01	Selhání komunikačního propojení	Komunikační propojení mezi ovladačem a zdrojem dat, ke kterému byl ovladač připojen, selhalo před dokončením zpracování funkce.
22002	Požadovaná proměnná ukazatele, ale není zadána	StrLen_or_IndPtr byl ukazatel null a data NULL byla načtena.
22003	Číselná hodnota mimo rozsah	Vrácení číselné hodnoty (jako číselného nebo řetězce) pro sloupec by způsobilo zkrácení celé části čísla (na rozdíl od zlomků). Další informace naleznete v Dodatku D: Datové typy.
22007	Neplatný formát data a času	Sloupec znaků v sadě výsledků byl vázán na strukturu data, času nebo časového razítka jazyka C a hodnota ve sloupci byla neplatné datum, čas nebo časové razítko. Další informace naleznete v Dodatku D: Datové typy.
22012	Dělení nulou	Byla vrácena hodnota z aritmetického výrazu, který způsobil dělení nulou.
22015	Přetečení pole intervalu	Přiřazení z přesného číselného nebo intervalového typu SQL k typu intervalu jazyka C způsobilo ztrátu významných číslic v úvodním poli. Při vracení dat do typu C intervalu neexistovala žádná reprezentace hodnoty typu SQL v typu interval C.
22018	Neplatná hodnota znaku pro specifikaci přetypování	Sloupec znaků v sadě výsledků byl vrácen do vyrovnávací paměti znaku C a sloupec obsahoval znak, pro který nebyla v znakové sadě vyrovnávací paměti žádná reprezentace. Typ C byl přesný nebo přibližný číselný typ, datum a čas nebo datový typ intervalu; typ SQL sloupce byl datový typ znaku; a hodnota ve sloupci nebyla platným literálem vázaného typu C.
24000	Neplatný stav kurzoru	(DM) Funkce byla volána bez prvního volání SQLFetch nebo SQLFetchScroll pro umístění kurzoru na řádek požadovaných dat. (DM) StatementHandle byl ve spuštěném stavu, ale žádná sada výsledků nebyla přidružena k StatementHandle. Kurzor byl otevřen na StatementHandle a SQLFetch nebo sqlFetchScroll byl volána, ale kurzor byl umístěn před začátkem sady výsledků nebo za koncem sady výsledků.
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á SQLGetDiagRec v MessageText vyrovnávací paměti popisuje chybu a její příčinu.
HY001	Chyba přidělení paměti	Ovladač nemohl přidělit paměť potřebnou k podpoře provádění nebo dokončení funkce.
HY003	Typ programu mimo rozsah	(DM) Argument TargetType nebyl platný datový typ, SQL_C_DEFAULT, SQL_ARD_TYPE (v případě načítání dat sloupce) nebo SQL_APD_TYPE (v případě načítání dat parametrů). (DM) Argument Col_or_Param_Num byl 0 a argument TargetType nebyl SQL_C_BOOKMARK záložky s pevnou délkou nebo SQL_C_VARBOOKMARK pro záložku s proměnnou délkou.
HY008	Operace byla zrušena.	Asynchronní zpracování bylo povoleno pro StatementHandle. Funkce byla volána a před dokončením provádění SQLCancel nebo SQLCancelHandle byla volána na StatementHandlea pak byla funkce znovu volána na StatementHandle. Funkce byla volána a před dokončením provádění SQLCancel nebo SQLCancelHandle byla volána na StatementHandle z jiného vlákna v aplikaci s více vlákny a funkce byla znovu volána na StatementHandle.
HY009	Neplatné použití ukazatele null	(DM) Argument TargetValuePtr byl ukazatel null.
HY010	Chyba posloupnosti funkcí	(DM) Zadaný StatementHandle nebyl ve spuštěném stavu. Funkce byla volána bez prvního volání SQLExecDirect, SQLExecute nebo funkce katalogu. (DM) Byla volána asynchronně spouštěná funkce pro popisovač připojení, který je přidružen k StatementHandle. Tato asynchronní funkce se stále spouštěla, když byla volána funkce SQLGetData. (DM) Pro StatementHandle byla volána asynchronně spouštěná funkce (ne tato) a při zavolání této funkce se stále spouštěla. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationsnebo SQLSetPos byl volána pro StatementHandle a vrácena SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce. (DM) StatementHandle byl ve spuštěném stavu, ale žádná sada výsledků nebyla přidružena k StatementHandle. Volání SQLExecute, SQLExecDirectnebo SQLMoreResults vráceny SQL_PARAM_DATA_AVAILABLE, ale SQLGetData byl volána místo SQLParamData.
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. Hodnota zadaná pro argument BufferLength byla menší než 4, argument Col_or_Param_Num byl nastaven na hodnotu 0 a ovladač byl ovladač ODBC 2.x.
HY109	Neplatná pozice kurzoru	Kurzor byl umístěn (SQLSetPos, SQLFetch, SQLFetchScrollnebo SQLBulkOperations) na řádku, který byl odstraněn nebo nelze načíst. Kurzor byl kurzorem pouze vpřed a velikost sady řádků byla větší než jedna.
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 použití SQLGetData s více řádky v SQLFetchScroll. Tento popis se nevztahuje na ovladače, které vrací SQL_GD_BLOCK bitová maska pro možnost SQL_GETDATA_EXTENSIONS v SQLGetInfo. Ovladač nebo zdroj dat nepodporuje převod zadaný kombinací argumentu TargetType a datového typu SQL odpovídajícího sloupce. Tato chyba platí pouze v případě, že byl datový typ sloupce namapován na datový typ SQL specifický pro ovladač. Ovladač podporuje pouze rozhraní ODBC 2.x a argument TargetType byl jedním z následujících způsobů: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT a kterýkoli z datových typů jazyka C intervalu uvedených v datových typech jazyka C v dodatku D: Datové typy. Ovladač podporuje pouze verze ODBC starší než 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. Doba časového limitu připojení je nastavena prostřednictvím SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Ovladač tuto funkci nepodporuje.	(DM) Ovladač odpovídající StatementHandle funkci nepodporuje.
IM017	Dotazování je zakázané v asynchronním režimu oznámení.	Při každém použití modelu oznámení je dotazování zakázané.
IM018	sqlCompleteAsync nebyl volán k dokončení předchozí asynchronní operace na tomto popisovači.	Pokud předchozí volání funkce na popisovači vrátí SQL_STILL_EXECUTING a pokud je povolený režim oznámení, SQLCompleteAsync musí být volána v popisovači, aby bylo možné provést následné zpracování a dokončit operaci.

Komentáře

SQLGetData vrátí data v zadaném sloupci. sqlGetData lze volat pouze po načtení jednoho nebo více řádků ze sady výsledků SQLFetch, SQLFetchScrollnebo SQLExtendedFetchfetch. Pokud jsou data o délce proměnné příliš velká, aby se vrátila v jednom volání sqlGetData (kvůli omezení v aplikaci), SQLGetData je může načíst v částech. Je možné svázat některé sloupce v řádku a volat SQLGetData pro jiné, i když to podléhá určitým omezením. Další informace naleznete v tématu Získávání dlouhých dat.

Informace o použití SQLGetData s streamovanými výstupními parametry naleznete v tématu Načítání výstupních parametrů pomocí sqlGetData.

Použití SQLGetData

Pokud ovladač nepodporuje rozšíření pro SQLGetData, může funkce vrátit data pouze pro nevázané sloupce s číslem větším než u posledního vázaného sloupce. Kromě toho v řádku dat musí být hodnota argumentu Col_or_Param_Num v každém volání SQLGetData větší nebo rovna hodnotě Col_or_Param_Num v předchozím volání; to znamená, že data musí být načtena v rostoucím pořadí čísel sloupců. Pokud nejsou podporována žádná rozšíření, SQLGetData nelze volat, pokud je velikost sady řádků větší než 1.

Ovladače mohou některé z těchto omezení zmírnit. Pokud chcete zjistit, jaká omezení ovladač uvolní, volá aplikace SQLGetInfo s některou z následujících možností SQL_GETDATA_EXTENSIONS:

SQL_GD_OUTPUT_PARAMS = sqlGetData lze volat k vrácení hodnot výstupních parametrů. Další informace naleznete v tématu Načítání výstupních parametrů pomocí sqlGetData.
SQL_GD_ANY_COLUMN. Pokud se tato možnost vrátí, SQLGetData lze volat pro libovolný nevázaný sloupec, včetně těch, které předchází poslednímu vázanému sloupci.
SQL_GD_ANY_ORDER. Pokud se tato možnost vrátí, SQLGetData lze volat pro nevázané sloupce v libovolném pořadí.
SQL_GD_BLOCK. Pokud tuto možnost vrátí SQLGetInfo pro SQL_GETDATA_EXTENSIONS InfoType, ovladač podporuje volání SQLGetData, pokud je velikost sady řádků větší než 1 a aplikace může volat SQLSetPos s možností SQL_POSITION umístit kurzor na správný řádek před voláním SQLGetData.
SQL_GD_BOUND. Pokud se tato možnost vrátí, SQLGetData lze volat pro vázané sloupce i pro nevázané sloupce.

Existují dvě výjimky těchto omezení a schopnost řidiče je uvolnit. Za prvé, SQLGetData by nikdy neměl být volána pro kurzor jen vpřed, pokud je velikost sady řádků větší než 1. Za druhé, pokud ovladač podporuje záložky, musí vždy podporovat schopnost volat SQLGetData pro sloupec 0, i když neumožňuje aplikacím volat SQLGetData pro ostatní sloupce před posledním vázaným sloupcem. (Když aplikace pracuje s ovladačem ODBC 2*.x*, SQLGetData úspěšně vrátí záložku při volání Col_or_Param_Num rovnou 0 po volání SQLFetch, protože SQLFetch je mapován správcem ovladačů ODBC 3*.x* na SQLExtendedFetch s FetchOrientation SQL_FETCH_NEXT, a SQLGetData s Col_or_Param_Num 0 je mapován správcem ovladačů ODBC 3*.x* na SQLGetStmtOption s fOption SQL_GET_BOOKMARK.)

sqlGetData nelze použít k načtení záložky pro řádek právě vložený voláním SQLBulkOperation s s možností SQL_ADD, protože kurzor není umístěn na řádku. Aplikace může načíst záložku pro takový řádek vazbou sloupce 0 před voláním SQLBulkOperations s SQL_ADD, v takovém případě SQLBulkOperations vrátí záložku v vázané vyrovnávací paměti. SQLFetchScroll je možné volat pomocí SQL_FETCH_BOOKMARK a přemístit kurzor na tento řádek.

Pokud je argument TargetType datový typ intervalu, použije se pro data výchozí přesnost intervalu (2) a výchozí přesnost sekund intervalu (6), jak je nastaveno v SQL_DESC_DATETIME_INTERVAL_PRECISION a SQL_DESC_PRECISION polích ARD. Pokud je argument TargetType datový typ SQL_C_NUMERIC, použijí se pro data výchozí přesnost (definovaná ovladač) a výchozí měřítko (0), jak je nastaveno v SQL_DESC_PRECISION a SQL_DESC_SCALE polích ARD. Pokud není vhodná žádná výchozí přesnost nebo měřítko, měla by aplikace explicitně nastavit příslušné pole popisovače voláním SQLSetDescField nebo SQLSetDescRec. Pole SQL_DESC_CONCISE_TYPE může nastavit na SQL_C_NUMERIC a volat SQLGetData s argumentem TargetType SQL_ARD_TYPE, což způsobí použití hodnot přesnosti a měřítka v polích popisovače.

Poznámka

V rozhraní ODBC 2*.x* aplikace nastavují TargetType na SQL_C_DATE, SQL_C_TIME nebo SQL_C_TIMESTAMP označující, že *TargetValuePtr je struktura data, času nebo časového razítka. V rozhraní ODBC 3*.x* aplikace nastavily TargetType na SQL_C_TYPE_DATE, SQL_C_TYPE_TIME nebo SQL_C_TYPE_TIMESTAMP. Správce ovladačů v případě potřeby provede odpovídající mapování na základě verze aplikace a ovladače.

Načítání dat Variable-Length v částech

sqlGetData lze použít k načtení dat ze sloupce, který obsahuje data o délce proměnných v částech . To znamená, že pokud je identifikátor datového typu SQL sloupce SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY nebo identifikátor specifický pro typ proměnné.

Pokud chcete načíst data ze sloupce v částech, aplikace volá SQLGetData vícekrát po sobě pro stejný sloupec. Při každém volání SQLGetData vrátí další část dat. Je na aplikaci, aby znovu sesestavila části, a proto je potřeba odebrat znak ukončení null z přechodných částí dat znaků. Pokud je k ukončení znaku přiděleno více dat, která se mají vrátit nebo není dostatek vyrovnávací paměti, SQLGetData vrátí SQL_SUCCESS_WITH_INFO a SQLSTATE 01004 (data zkrácena). Když vrátí poslední část dat, SQLGetData vrátí SQL_SUCCESS. Ani SQL_NO_TOTAL ani nula nelze vrátit při posledním platném volání pro načtení dat ze sloupce, protože aplikace by pak neměla žádný způsob, jak zjistit, kolik dat v vyrovnávací paměti aplikace je platné. Pokud sqlGetData je volána za tímto názvem, vrátí SQL_NO_DATA. Další informace najdete v další části Načítání dat pomocí SQLGetData.

Záložky s proměnnou délkou mohou být vráceny v částech SQLGetData. Stejně jako u jiných dat vrátí volání SQLGetData vrácení záložek s proměnnou délkou v částech vrátí SQLSTATE 01004 (řetězcová data, zkrácená práva) a SQL_SUCCESS_WITH_INFO, když se vrátí více dat. To se liší od případu, kdy je záložka s proměnnou délkou zkrácena voláním SQLFetch nebo SQLFetchScroll, která vrací SQL_ERROR a SQLSTATE 22001 (řetězcová data, zkrácená vpravo).

sqlGetData nelze použít k vrácení dat s pevnou délkou v částech. Pokud SQLGetData se pro sloupec obsahující data s pevnou délkou nazývá více než jednou v řádku, vrátí SQL_NO_DATA pro všechna volání za prvním voláním.

Načítání streamovaných výstupních parametrů

Pokud ovladač podporuje streamované výstupní parametry, může aplikace volat SQLGetData s malou vyrovnávací pamětí mnohokrát k načtení velké hodnoty parametru. Další informace o streamovaných výstupních parametrech najdete v tématu Načítání výstupních parametrů pomocí sqlGetData.

Načítání dat pomocí SQLGetData

Pokud chcete vrátit data pro zadaný sloupec, SQLGetData provede následující posloupnost kroků:

Vrátí SQL_NO_DATA, pokud už vrátila všechna data pro sloupec.
Nastaví *StrLen_or_IndPtr na SQL_NULL_DATA, pokud jsou data null. Pokud jsou data NULL a StrLen_or_IndPtr byl ukazatel null, SQLGetData vrátí SQLSTATE 22002 (proměnná ukazatele je požadována, ale není zadána).

Pokud data pro sloupec nemají hodnotu NULL, SQLGetData pokračuje ke kroku 3.
Pokud je atribut příkazu SQL_ATTR_MAX_LENGTH nastaven na nenulovou hodnotu, pokud sloupec obsahuje znaková nebo binární data a pokud SQLGetData nebyl dříve volána pro sloupec, data jsou zkrácena na SQL_ATTR_MAX_LENGTH bajty.

Poznámka

Atribut příkazu SQL_ATTR_MAX_LENGTH je určen ke snížení síťového provozu. Obecně se implementuje zdrojem dat, který zkracuje data před jejich vrácením v síti. Ovladače a zdroje dat se k jeho podpoře nevyžadují. Aby se tedy zajistilo zkrácení dat na konkrétní velikost, měla by aplikace přidělit vyrovnávací paměť této velikosti a určit velikost v argumentu BufferLength.
Převede data na typ zadaný v TargetType. Data mají pro tento datový typ výchozí přesnost a měřítko. Pokud je SQL_ARD_TYPE TargetType, použije se datový typ v poli SQL_DESC_CONCISE_TYPE ARD. Pokud je SQL_ARD_TYPE TargetType SQL_ARD_TYPE, data mají v SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION a SQL_DESC_SCALE polích ARD přesnost a měřítko v závislosti na datovém typu v poli SQL_DESC_CONCISE_TYPE. Pokud není vhodná žádná výchozí přesnost nebo měřítko, měla by aplikace explicitně nastavit příslušné pole popisovače voláním SQLSetDescField nebo SQLSetDescRec.
Pokud byla data převedena na datový typ s proměnnou délkou, například znak nebo binární, SQLGetData zkontroluje, zda délka dat překračuje BufferLength. Pokud délka znakových dat (včetně znaku ukončení null) překročí BufferLength, SQLGetData zkrátí data na BufferLength menší délku znaku ukončení null. Data se pak ukončí hodnotou null. Pokud délka binárních dat překročí délku vyrovnávací paměti dat, SQLGetData ji zkrátí na BufferLength bajtů.

Pokud je zadaná vyrovnávací paměť dat příliš malá pro uložení znaku ukončení null, SQLGetData vrátí SQL_SUCCESS_WITH_INFO a SQLSTATE 01004.

SQLGetData nikdy nezkrátí data převedená na datové typy s pevnou délkou; vždy předpokládá, že délka *TargetValuePtr je velikost datového typu.
Umístí převedená (a pravděpodobně zkrácená) data v *TargetValuePtr. Všimněte si, že SQLGetData nemůže vracet data z řádku.
Umístí délku dat do *StrLen_or_IndPtr. Pokud StrLen_or_IndPtr byl ukazatel null, SQLGetData nevrací délku.
- U znakových nebo binárních dat je to délka dat po převodu a před zkrácením kvůli BufferLength. Pokud ovladač nemůže určit délku dat po převodu, stejně jako v některých případech s dlouhými daty, vrátí SQL_SUCCESS_WITH_INFO a nastaví délku na SQL_NO_TOTAL. (Poslední volání SQLGetData musí vždy vracet délku dat, nikoli nula nebo SQL_NO_TOTAL.) Pokud byla data zkrácena z důvodu atributu příkazu SQL_ATTR_MAX_LENGTH, hodnota tohoto atributu – na rozdíl od skutečné délky – je umístěna v *StrLen_or_IndPtr. Důvodem je to, že tento atribut je navržen tak, aby před převodem zkrátil data na serveru, takže ovladač nemá způsob, jak zjistit, jaká je skutečná délka. Pokud SQLGetData se pro stejný sloupec volá vícekrát po sobě, jedná se o délku dat dostupných na začátku aktuálního volání; to znamená, že délka se zmenšuje při každém následném volání.
- U všech ostatních datových typů se jedná o délku dat po převodu; to znamená, že se jedná o velikost typu, na který byla data převedena.
Pokud jsou data během převodu zkrácena bez ztráty významnosti (například Reálné číslo 1,234 je zkráceno při převodu na celé číslo 1) nebo protože BufferLength je příliš malý (například řetězec "abcdef" je umístěn do vyrovnávací paměti 4 bajtů), SQLGetData vrátí SQLSTATE 01004 (data zkrácena) a SQL_SUCCESS_WITH_INFO. Pokud jsou data zkrácena bez ztráty významnosti z důvodu atributu příkazu SQL_ATTR_MAX_LENGTH, SQLGetData vrátí SQL_SUCCESS a nevrací hodnotu SQLSTATE 01004 (Data zkrácena).

Obsah vázané vyrovnávací paměti dat (pokud je SQLGetData volána ve vázaném sloupci) a vyrovnávací paměť délky a indikátoru nejsou definovány, pokud SQLGetData nevrací SQL_SUCCESS ani SQL_SUCCESS_WITH_INFO.

Následná volání SQLGetData načte data z posledního požadovaného sloupce; předchozí posuny jsou neplatné. Například při provedení následující sekvence:

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)

druhé volání SQLGetData(icol=n) načte data ze začátku sloupce n. Jakékoli posuny dat z důvodu dřívějších volání SQLGetData pro sloupec již nejsou platné.

Popisovače a SQLGetData

SQLGetData nepracuje přímo s žádnými poli popisovače.

Pokud je SQL_ARD_TYPE TargetType, použije se datový typ v poli SQL_DESC_CONCISE_TYPE ARD. Pokud je targetType SQL_ARD_TYPE nebo SQL_C_DEFAULT, data mají v SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION a SQL_DESC_SCALE polích ARD v závislosti na datovém typu v poli SQL_DESC_CONCISE_TYPE.

Příklad kódu

V následujícím příkladu aplikace spustí příkaz SELECT a vrátí sadu výsledků ID, jmen a telefonních čísel seřazených podle jména, ID a telefonního čísla. Pro každý řádek dat volá SQLFetch umístit kurzor na další řádek. Volá SQLGetData k načtení načtených dat; vyrovnávací paměti pro data a vrácený počet bajtů jsou zadány ve volání SQLGetData. Nakonec se vypíše jméno, ID a telefonní číslo každého zaměstnance.

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}

Informace o	Vidět
Přiřazení úložiště pro sloupec v sadě výsledků	SQLBindCol
Provádění hromadných operací, které nesouvisí s polohou kurzoru bloku	SQLBulkOperations
Zrušení zpracování příkazů	SQLCancel
Spuštění příkazu SQL	SQLExecDirect
Spuštění připraveného příkazu SQL	SQLExecute
Načtení bloku dat nebo procházení sady výsledků	SQLFetchScroll
Načtení jednoho řádku dat nebo bloku dat ve směru jen dopředu	SQLFetch
Odesílání dat parametrů v době provádění	SQLPutData
Umístění kurzoru, aktualizace dat v sadě řádků nebo aktualizace nebo odstranění dat v sadě řádků	SQLSetPos

Viz také

Referenční rozhraní ODBC API
soubory hlaviček ODBC
načítání výstupních parametrů pomocí SQLGetData

Sdílet prostřednictvím

Funkce SQLGetData

Syntax

Argumenty

Návraty

Diagnostika

Komentáře

Použití SQLGetData

Načítání dat Variable-Length v částech

Načítání streamovaných výstupních parametrů

Načítání dat pomocí SQLGetData

Popisovače a SQLGetData

Příklad kódu

Viz také

Váš názor

Další materiály

Sdílet prostřednictvím

Funkce SQLGetData

Syntax

Argumenty

Návraty

Diagnostika

Komentáře

Použití SQLGetData

Načítání dat Variable-Length v částech

Načítání streamovaných výstupních parametrů

Načítání dat pomocí SQLGetData

Popisovače a SQLGetData

Příklad kódu

Související funkce

Viz také

Váš názor

Další materiály