Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Soulad
Představená verze: ODBC 3.0 Shoda s normami: ISO 92
Summary
SQLAllocHandle přiděluje prostředí, spojení, příkaz nebo deskriptor.
Note
Tato funkce je obecná funkce pro alokaci rukojetí, která nahrazuje funkce ODBC 2.0 SQLAllocConnect, SQLAllocEnv a SQLAllocStmt. Aby aplikace volající SQLAllocHandle mohly pracovat s ODBC 2. x driverů, volání SQLAllocHandle je v Driver Manageru mapováno na SQLAllocConnect, SQLAllocEnv nebo SQLAllocStmt, podle potřeby. Pro více informací viz "Komentáře." Pro více informací o tom, na co Driver Manager mapuje tuto funkci při ODBC 3. x aplikace pracuje s ODBC 2. x ovladač, viz Funkce nahrazování mapování pro zpětnou kompatibilitu aplikací.
Syntax
SQLRETURN SQLAllocHandle(
SQLSMALLINT HandleType,
SQLHANDLE InputHandle,
SQLHANDLE * OutputHandlePtr);
Arguments
HandleType
[Vstup] Typ rukojeti, který má přidělovat SQLAllocHandle. Toto musí být jedna z následujících hodnot:
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN popisovač používá pouze Správce ovladačů a ovladač. Aplikace by neměly používat tento typ popisovače. Pro více informací o SQL_HANDLE_DBC_INFO_TOKEN viz Rozvoj Connection-Pool povědomí u řidiče ODBC.
InputHandle
[Vstup] Vstupní rukojeť, v jehož kontextu má být nová přečka alokována. Pokud je HandleType SQL_HANDLE_ENV, je to SQL_NULL_HANDLE. Pokud je HandleType SQL_HANDLE_DBC, musí to být handle prostředí, a pokud je SQL_HANDLE_STMT nebo SQL_HANDLE_DESC, musí to být handle spojení.
OutputHandlePtr
[Výstup] Ukazatel na buffer, do kterého se handle vrátí nově alokované datové struktuře.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE nebo SQL_ERROR.
Při alokaci jiného handle než environment handle, pokud SQLAllocHandle vrátí SQL_ERROR, nastaví OutputHandlePtr na SQL_NULL_HDBC, SQL_NULL_HSTMT nebo SQL_NULL_HDESC, v závislosti na hodnotě HandleType, pokud výstupní argument není nulový ukazatel. Aplikace pak může získat další informace z diagnostické datové struktury spojené s handlem v argumentu InputHandle .
Chyby při alokaci prostředí
Alokace prostředí probíhá jak v rámci Správce ovladačů, tak v rámci každého ovladače. Chyba vrácená SQLAllocHandle s typem rukojeti SQL_HANDLE_ENV závisí na úrovni, na které chyba nastala.
Pokud správce ovladačů nemůže přidělit paměť pro *OutputHandlePtr , když je volán SQLAllocHandle s HandleType SQL_HANDLE_ENV, nebo aplikace poskytne null ukazatel pro OutputHandlePtr, SQLAllocHandle vrátí SQL_ERROR. Správce ovladačů nastaví *OutputHandlePtr na SQL_NULL_HENV (pokud aplikace neposkytla nulový ukazatel, který vrací SQL_ERROR). Neexistuje žádný přehled, se kterým by bylo možné spojit další diagnostické informace.
Správce ovladačů nevolá funkci řízení na úrovni ovladače v prostředí, dokud aplikace nezavolá SQLConnect, SQLBrowseConnect nebo SQLDriverConnect. Pokud dojde k chybě ve funkci SQLAllocHandle na úrovni ovladače, funkce SQLConnect, SQLBrowseConnect nebo SQLDriverConnect na úrovni Driver Manageru vrátí SQL_ERROR. Diagnostická datová struktura obsahuje SQLSTATE IM004 ( Driverův SQLAllocHandle selhal). Chyba se vrací na rukojeti spojení.
Pro více informací o toku volání funkcí mezi Správcem ovladačů a ovladačem viz SQLConnect Funkce.
Diagnostika
Když SQLAllocHandle vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLSTATE voláním SQLGetDiagRec s příslušným HandleType a Handle nastaveným na hodnotu InputHandle. SQL_SUCCESS_WITH_INFO (ale ne SQL_ERROR) lze vrátit pro argument OutputHandle . Následující tabulka uvádí hodnoty SQLSTATE, které obvykle vrací SQLAllocHandle , 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.) |
| 08003 | Připojení není otevřené | (DM) Argument HandleType byl SQL_HANDLE_STMT nebo SQL_HANDLE_DESC, ale spojení specifikované argumentem InputHandle nebylo otevřené. Proces spojení musí být úspěšně dokončen (a spojení musí být otevřené), aby ovladač mohl přidělit příkaz nebo deskriptor. |
| 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 bufferu *MessageText popisuje chybu a její příčinu. |
| HY001 | Chyba přidělení paměti | (DM) Správce ovladačů nebyl schopen přidělit paměť pro specifikovanou rukojeť. Ovladač nebyl schopen přidělit paměť pro specifikovanou rukojeť. |
| HY009 | Neplatné použití ukazatele null | (DM) Argument OutputHandlePtr byl nulovým ukazatelem. |
| HY010 | Chyba posloupnosti funkcí | (DM) Argument HandleType byl SQL_HANDLE_DBC a SQLSetEnvAttr nebyl vyvolán k nastavení atributu SQL_ODBC_VERSION prostředí. (DM) Asynchronně vykonávající funkce byla volána pro InputHandle a stále se spouštěla, když byla volána funkce SQLAllocHandle s HandleType nastaveným na SQL_HANDLE_STMT nebo SQL_HANDLE_DESC. |
| HY013 | Chyba správy paměti | Argument HandleType byl SQL_HANDLE_DBC, SQL_HANDLE_STMT nebo SQL_HANDLE_DESC; a volání funkce nemohlo být zpracováno, protože základní paměťové objekty nebylo možné přistupovat, pravděpodobně kvůli nízkému stavu paměti. |
| HY014 | Limit na počet překročených rukojetí | Limit definovaný ovladačem pro počet rukojetí, které lze alokovat pro typ rukojeti indikovaný argumentem HandleType , byl dosažen. |
| HY092 | Neplatný identifikátor atributu/opce | (DM) Argument HandleType nebyl: SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT ani SQL_HANDLE_DESC. |
| 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. | Argument HandleType byl SQL_HANDLE_DESC a ovladačem byl ODBC 2. X driver. |
| 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) Argument HandleType byl SQL_HANDLE_STMT a ovladač nebyl platným ODBC ovladačem. (DM) Argument HandleType byl SQL_HANDLE_DESC a ovladač nepodporuje alokaci descriptorové rukojeti. |
Comments
SQLAllocHandle se používá k přidělování rukojetí pro prostředí, spojení, příkazy a deskriptory, jak je popsáno v následujících sekcích. Pro obecné informace o rukojeti viz Rukojeti.
Aplikace může současně alokovat více prostředí, spojení nebo příkazových rukojetí, pokud ovladač podporuje více alokací. V ODBC není definován žádný limit na počet prostředí, spojení, příkazů nebo deskriptorových rukojetí, které lze alokovat najednou. Ovladače mohou stanovit limit na počet určitých typů rukojetí, které lze alokovat najednou; Pro více informací viz dokumentaci řidiče.
Pokud aplikace volá SQLAllocHandle s *OutputHandlePtr nastaveným na prostředí, spojení, příkaz nebo descriptor handle, který již existuje, ovladač přepíše informace spojené s handlem, pokud aplikace nepoužívá connection pooling (viz "Alocating an Environment Attribute for Connection Pooling" později v této sekci). Správce ovladačů nekontroluje, zda je handle zadaný v *OutputHandlePtr již používán, ani nekontroluje předchozí obsah handle před jeho přepsáním.
Note
Je nesprávné v ODBC aplikačním programování volat SQLAllocHandle dvakrát se stejnou aplikační proměnnou definovanou pro *OutputHandlePtr , aniž by se SQLFreeHandle uvolnil před jeho přerozdělením. Přepsání ODBC rukojetí tímto způsobem může vést k nekonzistentnímu chování nebo chybám ze strany ovladačů ODBC.
Na operačních systémech, které podporují více vláken, mohou aplikace používat stejné prostředí, spojení, příkaz nebo deskriptor handle na různých vláknech. Ovladače proto musí podporovat bezpečný, vícevláknový přístup k těmto informacím; Jedním ze způsobů, jak toho dosáhnout, je například použití kritické sekce nebo semaforu. Pro více informací o vláknění viz Multithreading.
SQLAllocHandle nenastavuje atribut SQL_ATTR_ODBC_VERSION prostředí, když je vyvolán k alokaci handle prostředí; atribut prostředí musí být nastaven aplikací, jinak se při volání SQLAllocHandle vrátí SQLSTATE HY010 (Function sequence error) pro přidělení handle spojení.
Pro aplikace splňující standardy je SQLAllocHandle při kompilaci mapován na SQLAllocHandleStd . Rozdíl mezi těmito dvěma funkcemi je v tom, že SQLAllocHandleStd nastavuje atribut SQL_ATTR_ODBC_VERSION prostředí na SQL_OV_ODBC3, když je volán s argumentem HandleType nastaveným na SQL_HANDLE_ENV. To se dělá proto, že aplikace splňující standardy jsou vždy ODBC 3. x aplikací. Navíc standardy nevyžadují registraci verze aplikace. To je jediný rozdíl mezi těmito dvěma funkcemi; jinak jsou totožné. SQLAllocHandleStd je namapován na SQLAllocHandle uvnitř správce ovladačů. Proto ovladače třetích stran nemusí implementovat SQLAllocHandleStd.
Aplikace ODBC 3.8 by měly využívat:
SQLAllocHandle a ne SQLAllocHandleStd pro alokaci environment handle.
SQLSetEnvAttr pro nastavení atributu SQL_ATTR_ODBC_VERSION environment na SQL_OV_ODBC3_80.
Přidělování popisovače prostředí
Handle prostředí poskytuje přístup k globálním informacím, jako jsou platné handle připojení a aktivní handle připojení. Pro obecné informace o environmentálních rukojetech viz Environment Handles.
Pro požadavek na handle prostředí aplikace volá SQLAllocHandle s HandleType SQL_HANDLE_ENV a InputHandle SQL_NULL_HANDLE. Ovladač alokuje paměť pro informace o prostředí a předává hodnotu příslušného handle zpět do argumentu *OutputHandlePtr . Aplikace předává hodnotu *OutputHandle ve všech následujících voláních, která vyžadují argument environment handle. Další informace naleznete v tématu Přidělení popisovače prostředí.
Pod handlem prostředí Driver Manageru, pokud již existuje handle prostředí ovladače, pak se SQLAllocHandle s HandleType SQL_HANDLE_ENV nevolá v tomto ovladači při navázání připojení, pouze SQLAllocHandle s HandleType SQL_HANDLE_DBC. Pokud pod handlem prostředí správce ovladače neexistuje handle prostředí, jsou v ovladači volány SQLAllocHandle s HandleType SQL_HANDLE_ENV a SQLAllocHandle s HandleType SQL_HANDLE_DBC v ovladači, když je první handle pro spojení prostředí připojen k ovladači.
Když správce ovladačů zpracuje funkci SQLAllocHandle pomocí HandleType SQL_HANDLE_ENV, zkontroluje klíčové slovo Trace v sekci [ODBC] systémových informací. Pokud je nastavena na 1, Driver Manager umožní sledování aktuální aplikace. Pokud je příznak trace nastaven, trasování začíná, když je alokován první handle prostředí, a končí, když je uvolněn poslední handle prostředí. Pro více informací viz Konfigurace datových zdrojů.
Po přidělení handle prostředí musí aplikace zavolat SQLSetEnvAttr na handle prostředí, aby nastavila atribut SQL_ATTR_ODBC_VERSION prostředí. Pokud tento atribut není nastaven před vyvoláním SQLAllocHandle pro přidělení handle spojení v prostředí, volání k alokaci připojení vrátí SQLSTATE HY010 (chyba sekvence funkcí). Pro více informací viz Deklarace ODBC verze aplikace.
Přidělování sdílených prostředí pro pooling spojení
Prostředí lze sdílet mezi více komponentami v jednom procesu. Sdílené prostředí může používat více než jedna komponenta současně. Když komponenta používá sdílené prostředí, může použít spojení, která jí umožňují alokovat a využívat existující spojení bez jeho opětovného vytváření.
Před alokací sdíleného prostředí, které lze použít pro pooling spojení, musí aplikace zavolat SQLSetEnvAttr , aby nastavila atribut SQL_ATTR_CONNECTION_POOLING prostředí na SQL_CP_ONE_PER_DRIVER nebo SQL_CP_ONE_PER_HENV. SQLSetEnvAttr se v tomto případě volá s nastavením EnvironmentHandle na null, což z atributu činí atribut na úrovni procesu.
Po povolení poolování spojení aplikace volá SQLAllocHandle s argumentem HandleType nastaveným na SQL_HANDLE_ENV. Prostředí přidělené tímto voláním bude implicitním sdíleným prostředím, protože bylo povoleno sdružování připojení.
Když je sdílené prostředí alokováno, prostředí použité není určeno až do vyvolání SQLAllocHandle s HandleType SQL_HANDLE_DBC. V tu chvíli se Driver Manager snaží najít existující prostředí, které odpovídá atributům prostředí požadovaným aplikací. Pokud takové prostředí neexistuje, vytváří se jako sdílené prostředí. Správce ovladačů udržuje referenční počet pro každé sdílené prostředí; Počet je nastaven na 1 při prvním vytvoření prostředí. Pokud je nalezeno odpovídající prostředí, aplikace se vrátí handle tohoto prostředí a počet referencí se zvýší. Handle prostředí alokovaný tímto způsobem může být použit v jakékoli funkci ODBC, která přijímá handle prostředí jako vstupní argument.
Přidělení identifikátoru připojení
Handle spojení poskytuje přístup k informacím, jako je platný příkaz a handle descriptorů o spojení a zda je transakce aktuálně otevřená. Pro obecné informace o rukojetech spojení viz Handle spojení.
Pro požadavek na handle spojení aplikace volá SQLAllocHandle pomocí HandleType of SQL_HANDLE_DBC. Argument InputHandle je nastaven na handle prostředí, který byl vrácen voláním SQLAllocHandle , které tuto handle alokovalo. Ovladač přiděluje paměť pro informace o spojení a předává hodnotu příslušného handle zpět do *OutputHandlePtr. Aplikace předává hodnotu *OutputHandlePtr ve všech následujících voláních, která vyžadují handle. Pro více informací viz Přidělení rukojeti spojení.
Správce ovladačů zpracuje funkci SQLAllocHandle a volá funkci SQLAllocHandle ovladače, když aplikace volá SQLConnect, SQLBrowseConnect nebo SQLDriverConnect. (Pro více informací viz SQLConnect Function.)
Pokud není atribut SQL_ATTR_ODBC_VERSION prostředí nastaven před vyvoláním SQLAllocHandle pro přidělení handle spojení v prostředí, volání pro alokaci spojení vrátí SQLSTATE HY010 (chyba sekvence funkcí).
Když aplikace volá SQLAllocHandle s argumentem InputHandle nastaveným na SQL_HANDLE_DBC a zároveň na sdílený environment handle, Driver Manager se snaží najít existující sdílené prostředí, které odpovídá atributům prostředí nastaveným aplikací. Pokud takové prostředí neexistuje, vytvoří se prostředí s referenčním počtem (udržovaným Správcem ovladačů) 1. Pokud je nalezeno odpovídající sdílené prostředí, tato adresa se aplikaci vrátí a její počet referencí se zvýší.
Skutečné spojení, které bude použito, není určeno Driver Managerem, dokud není vyvoláno SQLConnect nebo SQLDriverConnect . Správce ovladačů používá možnosti připojení ve volání funkce SQLConnect (nebo klíčových slov připojení ve volání SQLDriverConnect) a atributy připojení nastavené po přidělení připojení k určení, které připojení ve fondu by mělo být použito. Pro více informací viz SQLConnect Function.
Přidělení popisovače SQL příkazu
Handle příkazu poskytuje přístup k informacím o příkazech, jako jsou chybové zprávy, název kurzoru a informace o stavu pro zpracování SQL příkazů. Pro obecné informace o rukojeti příkazů viz Rukojeti příkazů.
Pro požadavek na handle příkazu se aplikace připojí ke zdroji dat a poté zavolá SQLAllocHandle před odesláním SQL příkazů. V tomto volání by měl být HandleType nastaven na SQL_HANDLE_STMT a InputHandle na connection handle, který byl vrácen voláním SQLAllocHandle , jenž tento handle přidělil. Ovladač přiděluje paměť pro informace o příkazu, přiřazuje příkazovou rukojeť k určenému spojení a předává hodnotu příslušné rukojeti zpět do *OutputHandlePtr. Aplikace předává hodnotu *OutputHandlePtr ve všech následujících voláních, která vyžadují příkazovou rukojet. Pro více informací viz Přiřazení rukojeti příkazu.
Když je handle příkazu alokován, ovladač automaticky přidělí sadu čtyř deskriptorů a přiřadí tyto rukojeti atributům SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC a SQL_ATTR_IMP_PARAM_DESC. Tyto se označují jako implicitně alokované deskriptory. Pro explicitní přidělení aplikačního deskriptoru viz následující sekce "Přidělení rukojeti Descriptoru."
Přiřazení rukojeti Descriptoru
Když aplikace volá SQLAllocHandle s HandleType SQL_HANDLE_DESC, ovladač přidělí aplikační deskriptor. Tyto se označují jako explicitně přidělené deskriptory. Aplikace nařizuje ovladači, aby použil explicitně přidělený aplikační deskriptor místo automaticky přiděleného pro daný příkazový handle tím, že volá funkci SQLSetStmtAttr s atributem SQL_ATTR_APP_ROW_DESC nebo SQL_ATTR_APP_PARAM_DESC. Implementační deskriptor nelze explicitně alokovat, ani implementační deskriptor nelze specifikovat ve volání funkce SQLSetStmtAttr .
Explicitně přidělené deskriptory jsou přiřazeny k handle spojení místo příkazového handle (jako jsou automaticky alokované deskriptory). Descriptory zůstávají alokovány pouze tehdy, když je aplikace skutečně připojena k databázi. Protože explicitně přidělené deskriptory jsou spojeny s handlem spojení, může aplikace přiřadit explicitně přidělený deskriptor více než jednomu příkazu v rámci spojení. Implicitně alokovaný aplikační deskriptor naopak nemůže být přiřazen k více než jedné rukojeti příkazu. (Nelze jej spojit s žádným jiným příkazovým handlem než s tím, pro který byl přidělen.) Explicitně přidělené descriptorové handles lze explicitně uvolnit buď aplikací, nebo voláním SQLFreeHandle s HandleType SQL_HANDLE_DESC, případně implicitně při uzavření spojení.
Když je explicitně přidělený deskriptor uvolněn, implicitně alokovaný deskriptor je opět přiřazen k příkazu. (Atribut SQL_ATTR_APP_ROW_DESC nebo SQL_ATTR_APP_PARAM_DESC pro toto tvrzení je opět nastaven na implicitně alokovaný descriptor handle.) To platí pro všechna tvrzení, která byla spojena s explicitně přiděleným deskriptorem na spojení.
Další informace o popisovačích naleznete v tématu Popisovače.
Příklad kódu
Viz ukázkový program ODBC, funkce SQLBrowseConnect, funkce SQLConnect a funkce SQLSetCursorName.
Související funkce
| Informace o | Podívejte se |
|---|---|
| Provádění SQL příkazu | SQLExecDirect Function |
| Spuštění připraveného příkazu SQL | FUNKCE SQLExecute |
| Uvolnění prostředí, spojení, příkazu nebo popisu | Funkce SQLFreeHandle |
| Příprava příkazu pro spuštění | Funkce SQLPrepare |
| Nastavení atributu spojení | SQLSetConnectAttr – funkce |
| Nastavení deskriptorového pole | SQLSetDescField Function |
| Nastavení atributu prostředí | SQLSetEnvAttr Function |
| Nastavení atributu příkazu | FUNKCE SQLSetStmtAttr |