Funkce SQLSetEnvAttr

Soulad
Představená verze: ODBC 3.0 Shoda s normami: ISO 92

Summary
SQLSetEnvAttr nastavuje atributy, které řídí aspekty prostředí.

Syntax

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);

Arguments

EnvironmentHandle
[Vstup] Ovládání prostředí.

Atribut
[Vstup] Atribut k množině, uvedeno v "Komentářích."

ValuePtr
[Vstup] Ukazatel na hodnotu, která má být spojena s atributem. V závislosti na hodnotě atributubude ValuePtr 32bitová celočíselná hodnota nebo ukazuje na znakový řetězec ukončený nulovým kódem.

StringLength
[Vstup] Pokud ValuePtr ukazuje na znakový řetězec nebo binární buffer, tento argument by měl být délka *ValuePtr. Pro data řetězce znaků by tento argument měl obsahovat počet bajtů v řetězci.

Pokud je ValuePtr celé číslo, StringLength se ignoruje.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostika

Když SQLSetEnvAttr vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLSTATE voláním SQLGetDiagRec s HandleType SQL_HANDLE_ENV a HandlemEnvironmentHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLSetEnvAttr 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. Pokud ovladač nepodporuje atribut prostředí, chyba se může vrátit pouze během doby připojení.

SQLSTATE Error Description
01000 Obecné upozornění Informační zpráva specifická pro řidiče (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
01S02 Změna hodnoty možnosti Ovladač nepodporoval hodnotu zadanou v ValuePtr a nahradil ji podobnou hodnotou. (Funkce vrátí SQL_SUCCESS_WITH_INFO.)
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ěť potřebnou k podpoře provádění nebo dokončení funkce.
HY009 Neplatné použití ukazatele null Argument Attribute identifikoval atribut prostředí, který vyžadoval hodnotu řetězce, a argument ValuePtr byl nulový ukazatel.
HY010 Chyba posloupnosti funkcí (DM) Na EnvironmentHandle byla přidělena connection handle.

(DM) SQL_ATTR_ODBC_VERSION nebylo nastaveno pomocí SQLSetEnvAttr a atribut není roven SQL_ATTR_ODBC_VERSION. Nemusíte SQL_ATTR_ODBC_VERSION explicitně nastavovat, pokud používáte SQLAllocHandleStd.
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.
HY024 Neplatná hodnota atributu Při dané dané hodnotě atributu byla v ValuePtr zadána neplatná hodnota.
HY090 Neplatná délka řetězce nebo vyrovnávací paměti Argument StringLength byl menší než 0, ale nebyl SQL_NTS.
HY092 Neplatný identifikátor atributu/opce (DM) Hodnota určená pro argument Attribute nebyla platná pro verzi ODBC podporovanou ovladačem.
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. Hodnota určená pro argument Attribute byla platným atributem prostředí ODBC pro verzi ODBC podporovanou ovladačem, ale nebyla podporována samotným ovladačem.

(DM) Argument atributu byl SQL_ATTR_OUTPUT_NTS a ValuePtr byl SQL_FALSE.

Comments

Aplikace může volat SQLSetEnvAttr pouze tehdy, pokud v prostředí není přidělena žádná ovládací páka spojení. Všechny atributy prostředí úspěšně nastavené aplikací pro dané prostředí přetrvávají až do momentu, kdy je v prostředí vyvolán SQLFreeHandle . V ODBC 3.x lze současně alokovat více než jednu rukojeť prostředí.

Formát informační množiny pomocí ValuePtr závisí na specifikovaném atributu. SQLSetEnvAttr přijímá informace o atributech ve dvou různých formátech: jako znak ukončený nulovou kategorií nebo jako 32bitová celočíselná hodnota. Formát každého je uveden v popisu atributu.

Nejsou zde žádné specifické atributy prostředí pro ovladače.

Atributy spojení nelze nastavit voláním do SQLSetEnvAttr. Pokud se o to pokusíte, vrátíte SQLSTATE HY092 (Neplatný identifikátor atributu/volby).

Atribut Obsah ValuePtr
SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) 32bitová SQLUINTEGER hodnota, která umožňuje nebo zakazuje poolování spojení na úrovni prostředí. Používají se následující hodnoty:

SQL_CP_OFF = Pooling spojení je vypnutý. Toto je výchozí hodnota.

SQL_CP_ONE_PER_DRIVER = Pro každý ovladač je podporován jeden spojovací pool. Každé spojení v poolu je přiřazeno k jednomu ovladači.

SQL_CP_ONE_PER_HENV = Pro každé prostředí je podporován jeden pool připojení. Každé spojení v poolu je spojeno s jedním prostředím.

SQL_CP_DRIVER_AWARE = Použijte funkci povědomí o spojení v ovladači, pokud je dostupná. Pokud ovladač nepodporuje povědomí o spojení poolu, SQL_CP_DRIVER_AWARE je ignorováno a SQL_CP_ONE_PER_HENV se použije. Další informace najdete v tématu Driver-Aware sdružování připojení. V prostředí, kde některé ovladače podporují a jiné ne, může SQL_CP_DRIVER_AWARE zapnout funkci povědomí o poolu připojení u těch ovladačů, ale je to ekvivalentní nastavení SQL_CP_ONE_PER_HENV u těch ovladačů, které nepodporují funkci povědomí o poolu připojení.

Poolování spojení je povoleno voláním SQLSetEnvAttr , který nastaví atribut SQL_ATTR_CONNECTION_POOLING na SQL_CP_ONE_PER_DRIVER nebo SQL_CP_ONE_PER_HENV. Toto volání musí být provedeno před přidělením sdíleného prostředí, pro které má být povoleno sdružování připojení. Handle prostředí ve volání SQLSetEnvAttr je nastaven na null, což SQL_ATTR_CONNECTION_POOLING činí atributem na úrovni procesu. Po povolení poolování spojení aplikace přidělí implicitní sdílené prostředí voláním SQLAllocHandle s argumentem InputHandle nastaveným na SQL_HANDLE_ENV.

Po povolení poolování spojení a výběru sdíleného prostředí pro aplikaci nelze SQL_ATTR_CONNECTION_POOLING pro toto prostředí resetovat, protože při nastavení tohoto atributu je volán SQLSetEnvAttr s null environment handlem. Pokud je tento atribut nastaven, zatímco je pooling spojení již povolen ve sdíleném prostředí, atribut ovlivňuje pouze sdílená prostředí, která jsou alokována následně.

Je také možné povolit pooling připojení v prostředí. Všimněte si následujícího ohledně poolování propojení s prostředím:

- Povolení poolování spojení na NULL handle je atribut na úrovni procesu. Následně budou alokovaná prostředí sdíleným prostředím a zdědí nastavení poolování spojení na úrovni procesů.
- Po alokaci prostředí může aplikace stále změnit nastavení svého poolu připojení.
- Pokud je pooling připojení v prostředí povolen a ovladač připojení používá pooling ovladačů, preference má pooling v prostředí přednost.

SQL_ATTR_CONNECTION_POOLING je implementováno uvnitř Správce ovladačů. Ovladač nemusí implementovat SQL_ATTR_CONNECTION_POOLING. Aplikace ODBC 2.0 a 3.0 mohou nastavit tento atribut prostředí.

Další informace najdete v tématu Sdružování připojení ODBC.
SQL_ATTR_CP_MATCH (ODBC 3.0) 32bitová SQLUINTEGER hodnota, která určuje, jak je spojení vybíráno z poolu spojů. Když je volán SQLConnect nebo SQLDriverConnect , Driver Manager určí, které spojení se z poolu znovu použije. Driver Manager se snaží sladit možnosti spojení ve volání a atributy připojení nastavené aplikací ke klíčovým slovům a atributům spojení v poolu. Hodnota tohoto atributu určuje úroveň přesnosti kritérií shody.

K nastavení hodnoty tohoto atributu se používají následující hodnoty:

SQL_CP_STRICT_MATCH = Znovu se používají pouze spojení, která přesně odpovídají možnostem spojení ve volání a atributům spojení nastaveným aplikací. Toto je výchozí hodnota.

SQL_CP_RELAXED_MATCH = Lze použít spojení s odpovídajícími připojovací řetězec klíčovými slovy. Klíčová slova musí odpovídat, ale ne všechny atributy spojení musí odpovídat.

Pro více informací o tom, jak Driver Manager provádí zápas při připojení ke skupinovému připojení, viz SQLConnect. Další informace o sdružování připojení naleznete v tématu Sdružování připojení ODBC.
SQL_ATTR_ODBC_VERSION (ODBC 3.0) 32bitové celé číslo, které určuje, zda určitá funkcionalita vykazuje chování ODBC 2.x nebo ODBC 3.x . K nastavení hodnoty tohoto atributu se používají následující hodnoty:

SQL_OV_ODBC3_80 = Správce ovladačů a ovladač vykazují následující chování podle ODBC 3.8:

- Řidič se vrací a očekává kódy ODBC 3.x pro datum, čas a časové razítko.
- Ovladač vrací ODBC 3.x SQLSTATE kódy, když jsou volány SQLError, SQLGetDiagField nebo SQLGetDiagRec .
- Argument CatalogName ve volání do SQLTables přijímá vyhledávací vzor.
- Driver Manager podporuje rozšiřitelnost datových typů v C. Pro více informací o rozšiřitelnosti typů dat v C viz C datové typy v ODBC.

Pro více informací viz Co je nového v ODBC 3.8.

SQL_OV_ODBC3 = Správce ovladačů a ovladač vykazují následující chování v ODBC 3.x :

- Řidič se vrací a očekává kódy ODBC 3.x pro datum, čas a časové razítko.
- Ovladač vrací ODBC 3.x SQLSTATE kódy, když jsou volány SQLError, SQLGetDiagField nebo SQLGetDiagRec .
- Argument CatalogName ve volání do SQLTables přijímá vyhledávací vzor.
- Driver Manager nepodporuje rozšiřitelnost datových typů v C.

SQL_OV_ODBC2 = Správce ovladačů a ovladač vykazují následující chování v ODBC 2.x . To je obzvlášť užitečné pro aplikaci ODBC 2.x pracující s ovladačem ODBC 3.x .

- Řidič vrací a očekává kódy ODBC 2.x pro datum, čas a časové razítko.
- Ovladač vrací ODBC 2.x SQLSTATE kódy, když jsou volány SQLError, SQLGetDiagField nebo SQLGetDiagRec .
- Argument CatalogName ve volání SQLTables nepřijímá vyhledávací vzor.
- Driver Manager nepodporuje rozšiřitelnost datových typů v C.

Aplikace musí nastavit tento atribut prostředí před zavoláním jakékoli funkce, která má argument SQLHENV, jinak volání vrátí SQLSTATE HY010 (chyba sekvence funkcí). Je specifické pro řidiče, zda existují další chování těchto environmentálních vlajek.

- Pro více informací viz Deklarace ODBC verze aplikace a změny chování.
SQL_ATTR_OUTPUT_NTS (ODBC 3.0) 32bitové celé číslo, které určuje, jak ovladač vrací data řetězce. Pokud SQL_TRUE, ovladač vrátí data řetězce ukončená null-terminl. Pokud SQL_FALSE, ovladač nevrátí data řetězce ukončená null-terminem.

Tento atribut se automaticky zobrazuje na SQL_TRUE. Volání SQLSetEnvAttr pro nastavení na SQL_TRUE vrátí SQL_SUCCESS. Volání SQLSetEnvAttr pro nastavení na SQL_FALSE vrátí SQL_ERROR a SQLSTATE HYC00 (volitelná funkce není implementována).
Informace o Podívejte se
Přiřazení rukojeti SQLAllocHandle Function
Vrácení nastavení atributu prostředí SQLGetEnvAttr Function

Související obsah

  • Last updated on