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
Zavedená verze: ODBC 1.0 Soulad standardů: ODBC
Shrnutí
SQLDriverConnect je alternativou k SQLConnect. Podporuje datové zdroje, které vyžadují více informací o spojení než ve třech argumentech v SQLConnect, dialogová okna pro vyzývání uživatele na všechny informace o připojení a datové zdroje, které nejsou definovány v systémových informacích. Pro více informací viz Connecting with SQLDriverConnect.
Syntax
SQLRETURN SQLDriverConnect(
SQLHDBC ConnectionHandle,
SQLHWND WindowHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
Arguments
ConnectionHandle
[Vstup] Popisovač připojení.
WindowHandle
[Vstup] Klika na okně. Aplikace může předat handle rodičovského okna, pokud je to relevantní, nebo null ukazatel, pokud není použitelný handle okna nebo SQLDriverConnect nezobrazí žádná dialogová okna.
InConnectionString
[Vstup] Plný připojovací řetězec (viz syntax v "Komentářích"), částečný připojovací řetězec nebo prázdný řetězec.
StringLength1
[Vstup] Délka *InConnectionString, v znacích, pokud je řetězec Unicode, nebo bajty, pokud je řetězec ANSI nebo DBCS.
OutConnectionString
[Výstup] Ukazatel na buffer pro dokončený připojovací řetězec. Po úspěšném připojení ke zdroji cílových dat tento buffer obsahuje dokončený připojovací řetězec. Aplikace by měly pro tento buffer vyčlenit alespoň 1 024 znaků.
Pokud je OutConnectionString NULL, StringLength2Ptr stále vrátí celkový počet znaků (kromě znaku null-termination pro znaková data), které lze vrátit v bufferu na který ukazuje OutConnectionString.
BufferLength
[Vstup] Délka bufferu *OutConnectionString , v znacích.
StringLength2Ptr
[Výstup] Ukazatel na buffer, do kterého se vrátí celkový počet znaků (bez znaku null-termination), které lze vrátit v *OutConnectionString. Pokud je počet znaků dostupných k vrácení větší nebo roven BufferLength, dokončený připojovací řetězec v *OutConnectionString se zkrátí na BufferLength minus délka znaku null-termination.
Dokončení ovladače
[Vstup] Příznak, který označuje, zda musí správce ovladačů nebo ovladač vyžádat další informace o připojení:
SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED nebo SQL_DRIVER_NOPROMPT.
(Pro další informace viz "Komentáře.")
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE nebo SQL_STILL_EXECUTING.
Diagnostics
Když SQLDriverConnect vrátí buď SQL_ERROR, nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, když se SQLGetDiagRec použije fHandleType SQL_HANDLE_DBC a hHandleConnectionHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLDriverConnect běžně 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.) |
| 01004 | Řetězcová data, zkrácená vpravo | Buffer *OutConnectionString nebyl dostatečně velký na vrácení celého připojovací řetězec, takže byl připojovací řetězec zkrácen. Délka neomezeného připojovací řetězec se vrací v *StringLength2Ptr. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 01S00 | Neplatný atribut připojovací řetězec | V připojovací řetězec (InConnectionString) bylo zadáno neplatné klíčové slovo atributu, ale ovladač se přesto mohl připojit ke zdroji dat. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Změna hodnoty možnosti | Ovladač nepodporoval specifikovanou hodnotu, na kterou odkazoval argument ValuePtr v SQLSetConnectAttr , a nahradil ji podobnou hodnotou. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 01S08 | DSN pro ukládání chyb | Řetězec v *InConnectionString obsahoval klíčové slovo FILEDSN , ale soubor .dsn nebyl uložen. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 01S09 | Neplatné klíčové slovo | (DM) Řetězec v *InConnectionString obsahoval klíčové slovo SAVEFILE , ale ne DRIVER ani FILEDSN klíčové slovo. (Funkce vrátí SQL_SUCCESS_WITH_INFO.) |
| 08001 | Klient nedokáže navázat spojení | Ovladač nebyl schopen navázat spojení se zdrojem dat. |
| 08002 | Používaný název spojení | (DM) Specifikovaný ConnectionHandle již byl použit k navázání spojení se zdrojem dat a spojení bylo stále otevřené. |
| 08004 | Server spojení odmítl | Datový zdroj odmítl navázání spojení z důvodů definovaných implementací. |
| 08S01 | Selhání komunikačního propojení | Komunikační spojení mezi ovladačem a zdrojem dat, ke kterému se ovladač pokoušel připojit, selhalo dříve, než funkce SQLDriverConnect dokončila zpracování. |
| 28000 | Specifikace neplatné autorizace | Buď uživatelský identifikátor, nebo autorizační řetězec, nebo obojí, jak je specifikováno v připojovací řetězec (InConnectionString), porušovaly omezení definovaná datovým zdrojem. |
| 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 *szMessageText popisuje chybu a její příčinu. |
| HY000 | Obecná chyba: Neplatný soubor dsn | (DM) Řetězec v *InConnectionString obsahoval klíčové slovo FILEDSN, ale název souboru .dsn nebyl nalezen. |
| HY000 | Obecná chyba: Nelze vytvořit souborový buffer | (DM) Řetězec v *InConnectionString obsahoval klíčové slovo FILEDSN, ale soubor .dsn byl nečitelný. |
| HY001 | Chyba přidělení paměti | Správce ovladačů nebyl schopen přidělit paměť potřebnou k podpoře spuštění nebo dokončení funkce SQLDriverConnect . Ovladač nemohl přidělit paměť potřebnou k podpoře provádění nebo dokončení funkce. |
| HY008 | Operace byla zrušena. | Asynchronní zpracování bylo povoleno pro ConnectionHandle. Funkce byla vyvolána a před dokončením byla funkce SQLCancelHandle vyvolána na ConnectionHandle a poté byla funkce SQLDriverConnect znovu volána na ConnectionHandle. Nebo byla volána funkce SQLDriverConnect a před dokončením spuštění byl SQLCancelHandle volán na ConnectionHandle z jiného vlákna v multithread aplikaci. |
| HY010 | Chyba posloupnosti funkcí | (DM) Další asynchronně vykonávající funkce (ne SQLDriverConnect) byla volána pro ConnectionHandle a stále se spouštěla, když byla volána funkce SQLDriverConnect . |
| HY013 | Chyba správy paměti | Volání funkce SQLDriverConnect nemohlo být zpracováno, protože základní paměťové objekty nebyly přístupné, pravděpodobně kvůli nízkému stavu paměti. |
| HY090 | Neplatná délka řetězce nebo vyrovnávací paměti | (DM) Hodnota zadaná pro argument StringLength1 byla menší než 0 a nebyla rovna SQL_NTS. (DM) Hodnota zadaná pro argument BufferLength byla menší než 0. |
| HY092 | Neplatný identifikátor atributu/opce | (DM) Argument DriverCompletion byl SQL_DRIVER_PROMPT a argument WindowHandle byl nulovým ukazatelem. |
| HY110 | Dokončení neplatného ovladače | (DM) Hodnota uvedená pro argument DriverCompletion nebyla rovna SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED ani SQL_DRIVER_NOPROMPT. (DM) Pooling spojení bylo povoleno a hodnota určená pro argument DriverCompletion nebyla rovna SQL_DRIVER_NOPROMPT. |
| HYC00 | Nepovinná funkce není implementována. | Ovladač nepodporuje verzi chování ODBC, kterou aplikace požadovala. |
| HYT00 | Vypršel časový limit. | Doba vypršení přihlašovacího systému vypršela dříve, než bylo spojení se zdrojem dat dokončeno. Časová doba je nastavena přes SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT. |
| 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č odpovídající specifikovanému názvu zdroje dat tuto funkci nepodporuje. |
| IM002 | Zdroj dat nenalezen a není uveden žádný výchozí ovladač | (DM) Název zdroje dat uvedený v připojovací řetězec (InConnectionString) nebyl nalezen v systémových informacích a neexistovala výchozí specifikace ovladače. (DM) Zdroj dat ODBC a výchozí informace o ovladači nebyly nalezeny v systémových informacích. |
| IM003 | Specifikovaný ovladač nemohl být načítán | (DM) Ovladač uvedený ve specifikaci zdroje dat v systémových informacích nebo specifikovaný klíčovým slovem DRIVER nebyl nalezen nebo nemohl být nahrán z jiného důvodu. |
| IM004 | Driver's SQLAllocHandle na SQL_HANDLE_ENV selhal | (DM) Během SQLDriverConnect správce ovladače volal funkci SQLAllocHandle ovladače pomocí fHandleType SQL_HANDLE_ENV a ovladač vrátil chybu. |
| IM005 | SQLAllocHandle ovladače na SQL_HANDLE_DBC selhal. | (DM) Během SQLDriverConnect správce ovladačů volal funkci SQLAllocHandle ovladače pomocí fHandleType SQL_HANDLE_DBC a ovladač vrátil chybu. |
| IM006 | Driver SQLSetConnectAttr selhal | (DM) Během SQLDriverConnect správce ovladačů volal funkci SQLSetConnectAttr ovladače a ovladač vrátil chybu. |
| IM007 | Není uveden žádný zdroj dat ani ovladač; Dialog zakázán | V připojovací řetězec nebyl uveden název zdroje dat ani ovladač a DriverCompletion byl SQL_DRIVER_NOPROMPT. |
| IM008 | Dialog selhal | Ovladač se pokusil zobrazit přihlašovací okno a neuspěl. WindowHandle byl nulový ukazatel a DriverCompletion nebyl SQL_DRIVER_NO_PROMPT. |
| IM009 | Nelze načíst překlad DLL | Ovladač nebyl schopen načíst překladovou DLL, která byla určena pro datový zdroj ani pro spojení. |
| IM010 | Název zdroje dat je příliš dlouhý | (DM) Hodnota atributu pro klíčové slovo DSN byla delší než SQL_MAX_DSN_LENGTH znaků. |
| IM011 | Jméno řidiče je příliš dlouhé | (DM) Hodnota atributu klíčového slova DRIVER byla delší než 255 znaků. |
| IM012 | Chyba syntaxe klíčových slov v DRIVER | (DM) Pár klíčových slov a hodnoty pro klíčové slovo DRIVER obsahoval syntaktickou chybu. (DM) Řetězec v *InConnectionString obsahoval klíčové slovo FILEDSN , ale soubor .dsn neobsahoval klíčové slovo DRIVER ani DSN . |
| IM014 | Specifikované DSN obsahuje architektonickou nesoulad mezi ovladačem a aplikací | (DM) 32bitová aplikace používá DSN připojené k 64bitovému ovladači; Nebo naopak. |
| IM015 | Driver SQLDriverConnect na SQL_HANDLE_DBC_INFO_HANDLE selhal | Pokud ovladač vrátí SQL_ERROR, správce ovladačů SQL_ERROR aplikaci vrátí a spojení selže. Pro více informací o SQL_HANDLE_DBC_INFO_TOKEN viz Rozvoj Connection-Pool povědomí u řidiče ODBC. |
| 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 | K dokončení předchozí asynchronní operace na tomto popisovači nebyla volána funkce SQLCompleteAsync. | Pokud předchozí volání funkce na popisovači vrátí SQL_STILL_EXECUTING a pokud je povolen režim oznámení, musí být sqlCompleteAsync volán na popisovači, aby bylo možné provést následné zpracování a dokončit operaci. |
| S1118 | Ovladač nepodporuje asynchronní notifikace | Pokud ovladač nepodporuje asynchronní oznámení, nelze nastavit SQL_ATTR_ASYNC_DBC_EVENT ani SQL_ATTR_ASYNC_DBC_RETCODE_PTR. |
Comments
připojovací řetězec má následující syntaxi:
connection-string ::= prázdný řetězec[;] | atribut[;] | atribut;spojovací řetězec
empty-string ::=attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSN | UID | PWD | ovladač-definovaný-atribut-klíčové slovo
attribute-value ::= znakový řetězec
identifikátor driver-defined-attribute-keyword ::= identifikátor
kde řetězec znaků má nula nebo více znaků; identifikátor má jeden nebo více znaků; attribute-keyword není rozlišující velká písmena; hodnota atributu může být rozlišující na velikost písmen; a hodnota klíčového slova DSN není pouze z prázdných míst.
Kvůli gramatice připojovací řetězec a inicializačního souboru jsou klíčová slova a hodnoty atributů obsahující znaky []{}(),;? *=!@ Nebýt uzavřen s rovnátkami by se měl vyhýbat. Hodnota klíčového slova DSN nemůže obsahovat pouze prázdné hodnoty a neměla by obsahovat úvodní prázdné hodnoty. Z důvodu gramatiky systémových informací nemohou klíčová slova a názvy zdrojů dat obsahovat zpětné lomítko (\).
Aplikace nemusí přidávat závorky kolem hodnoty atributu za klíčovým slovem DRIVER , pokud atribut neobsahuje středník (;), v takovém případě jsou závorky povinné. Pokud hodnota atributu, kterou ovladač obdrží, obsahuje složené závorky, ovladač by je neměl odebrat, ale měl by být součástí vráceného připojovacího řetězce.
DSN nebo hodnota připojovací řetězec ohraničena závorkami ({}) obsahující některý ze znaků []{}(),;? *=!@ je předán řidiči neporušený. Při použití těchto znaků v klíčovém slově však správce ovladačů vrací chybu při práci se souborovými DSN, ale pro běžné připojovací řetězecy předává připojovací řetězec ovladači. Nepoužívejte vložené složené závorky v hodnotě klíčového slova.
Připojovací řetězec může obsahovat libovolný počet klíčových slov definovaných ovladačem. Protože klíčové slovo DRIVER nevyužívá informace ze systémových informací, musí ovladač definovat dostatek klíčových slov, aby se ovladač mohl připojit ke zdroji dat pouze pomocí informací v připojovací řetězec. (Pro více informací viz "Pokyny pro řidiče" později v této sekci.) Ovladač definuje, která klíčová slova jsou potřeba k připojení ke zdroji dat.
Následující tabulka popisuje hodnoty atributů klíčových slov DSN, FILEDSN, DRIVER, UID, PWD a SAVEFILE .
| Keyword | Popis hodnoty atributu |
|---|---|
| DSN | Název datového zdroje vrácený SQLDataSources nebo dialogovým oknem SQLDriverConnect. |
| PODÁNO | Název .dsn souboru, ze kterého bude vytvořen připojovací řetězec pro datový zdroj. Tyto zdroje dat se nazývají soubory datových zdrojů. |
| ŘIDIČ | Popis ovladače vrácený funkcí SQLDrivers . Například Rdb nebo SQL Server. |
| UID | ID uživatele. |
| PWD | Heslo odpovídající uživatelskému ID, nebo prázdný řetězec, pokud k uživateli není uvedeno heslo (PWD=;). |
| SAVEFILE | Název souboru .dsn, ve kterém by měly být uloženy hodnoty atributů klíčových slov použitých při navazování aktuálního úspěšného spojení. |
Pro informace o tom, jak aplikace vybírá zdroj dat nebo ovladač, viz Výběr zdroje dat nebo ovladače.
Pokud jsou v připojovací řetězec opakována jakákoli klíčová slova, ovladač použije hodnotu spojenou s prvním výskytem klíčového slova. Pokud jsou klíčová slova DSN a DRIVER zahrnuta ve stejném připojovací řetězec, Driver Manager a ovladač použijí to klíčové slovo, které se objeví jako první.
Klíčová slova FILEDSN a DSN se vzájemně vylučují: použije se to klíčové slovo, které se objeví jako první, a to, které se objeví jako druhé, se ignoruje. Klíčová slova FILEDSN a DRIVER se naopak nevylučují. Pokud se v připojovací řetězec s FILEDSN objeví nějaké klíčové slovo, použije se hodnota atributu klíčového slova v připojovací řetězec místo hodnoty atributu stejného klíčového slova v souboru .dsn.
Pokud je použito klíčové slovo FILEDSN, klíčová slova zadaná v .dsn souboru se použijí k vytvoření připojovací řetězec. (Pro více informací viz "Zdroje datových souborů" později v této části.) Klíčové slovo UID je volitelné; .dsn soubor lze vytvořit pouze s klíčovým slovem DRIVER . Klíčové slovo PWD není uloženo v .dsn souboru. Výchozí adresář pro ukládání a načítání .dsn souboru bude kombinací cesty specifikované CommonFileDir v HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion a "ODBC\DataSources". (Pokud by CommonFileDir byl "C:\Program Files\Common Files", výchozí adresář by byl "C:\Program Files\Common Files\ODBC\Data Sources".)
Note
.dsn soubor lze přímo upravit vyvoláním funkcí SQLReadFileDSN a SQLWriteFileDSN v instalačním DLL.
Pokud je použito klíčové slovo SAVEFILE , hodnoty atributů klíčových slov použitých při vytvoření současného úspěšného připojení budou uloženy jako .dsn soubor s názvem hodnoty atributu klíčového slova SAVEFILE . Klíčové slovo SAVEFILE musí být použito společně s klíčovým slovem DRIVER , FILEDSN nebo oběma, jinak funkce vrátí SQL_SUCCESS_WITH_INFO pomocí SQLSTATE 01S09 (Invalid keyword). Klíčové slovo SAVEFILE musí být před klíčovým slovem DRIVER v připojovací řetězec, jinak výsledky nebudou definovány.
Pokyny pro řidiče
Driver Manager vytváří připojovací řetězec, který předá ovladači v argumentu InConnectionString funkce SQLDriverConnect ovladače. Správce ovladačů nemění argument InConnectionString , který mu aplikace předala.
Akce Driver Managera je založena na hodnotě argumentu DriverCompletion (DriverCompletion takové):
SQL_DRIVER_PROMPT: Pokud připojovací řetězec neobsahuje ani klíčové slovo DRIVER,DSN, ani FILEDSN, zobrazí se v Driver Manageru dialogové okno Zdroje dat. Vytváří připojovací řetězec z názvu zdroje dat, který mu vrátí dialogové okno, a z dalších klíčových slov předaných aplikací. Pokud je název zdroje dat vrácený dialogovým oknem prázdný, Správce ovladačů specifikuje pár klíčové slovo-hodnota DSN=Výchozí. (Toto dialogové okno nezobrazí zdroj dat s názvem "Výchozí".)
SQL_DRIVER_COMPLETE nebo SQL_DRIVER_COMPLETE_REQUIRED: Pokud připojovací řetězec specifikovaný aplikací obsahuje klíčové slovo DSN, správce ovladačů zkopíruje připojovací řetězec specifikované aplikací. Jinak provádí stejné akce jako při SQL_DRIVER_PROMPT DriverCompletion (dokončení ovladače ).
SQL_DRIVER_NOPROMPT: Správce ovladačů kopíruje připojovací řetězec specifikovaný aplikací.
Pokud připojovací řetězec specifikovaný aplikací obsahuje klíčové slovo DRIVER, Driver Manager zkopíruje připojovací řetězec určený aplikací.
Pomocí vytvořeného připojovací řetězec Manager určí, který ovladač použít, připojí se k tomuto ovladači a předá připojovací řetězec, který vytvořil; pro více informací o interakci mezi Driver Managerem a ovladačem viz sekce "Komentáře" ve funkci SQLConnect. Pokud připojovací řetězec neobsahuje klíčové slovo DRIVER, Driver Manager určí, který ovladač použít následovně:
Pokud připojovací řetězec obsahuje klíčové slovo DSN, správce ovladačů získá ovladač spojený se zdrojem dat ze systémových informací.
Pokud připojovací řetězec neobsahuje klíčové slovo DSN nebo není nalezen zdroj dat, správce ovladačů získá ovladač spojený s výchozím datovým zdrojem ze systémových informací. (Pro více informací viz Výchozí podklíč.) Driver Manager mění hodnotu DSN klíčového slova v připojovací řetězec na "DEFAULT".
Pokud je klíčové slovo DSN v připojovací řetězec nastaveno na "",DEFAULT správce ovladačů získá ovladač přiřazený k výchozímu datovému zdroji ze systémových informací.
Pokud není nalezen zdroj dat a výchozí zdroj dat není nalezen, správce ovladačů SQL_ERROR vrátí s SQLSTATE IM002 (Zdroj dat nenalezen a výchozí ovladač není specifikován).
Zdroje dat ve formě souborů
Pokud připojovací řetězec specifikovaný aplikací ve volání SQLDriverConnect obsahuje klíčové slovo FILEDSN a toto klíčové slovo není nahrazeno ani DSN, ani DRIVER, pak Driver Manager vytvoří připojovací řetězec pomocí informací ze souboru .dsn a argumentu InConnectionString. Vedoucí řidiče postupuje následovně:
Kontroluje, zda je název souboru .dsn platný. Pokud ne, vrátí SQL_ERROR pomocí SQLSTATE IM014 (Neplatné jméno souboru DSN). Pokud je název souboru prázdný řetězec ("") a SQL_DRIVER_NOPROMPT není specifikováno, zobrazí se dialogové okno File-Open . Pokud název souboru obsahuje platnou cestu, ale žádné jméno souboru nebo neplatné jméno souboru, a SQL_DRIVER_NOPROMPT není specifikováno, zobrazí se dialogové okno File-Open s aktuálním adresářem nastaveným na ten uvedený v názvu souboru. Pokud je název souboru prázdný řetězec ("") nebo název souboru obsahuje platnou cestu, ale žádné jméno souboru nebo neplatné jméno souboru, a SQL_DRIVER_NOPROMPT je specifikováno, pak SQL_ERROR vráceno s SQLSTATE IM014 (Neplatné jméno souboru DSN).
Čte všechna klíčová slova v sekci [ODBC] v souboru .dsn. Pokud klíčové slovo DRIVER není přítomno, vrátí SQL_ERROR pomocí SQLSTATE IM012 (chyba syntaxe klíčového slova ovladače), kromě případů, kdy je .dsn soubor nesdílitelný a obsahuje pouze klíčové slovo DSN .
Pokud je zdroj datových dat souboru nesdílitelný, správce ovladačů přečte hodnotu klíčového slova DSN a podle potřeby se připojí k uživatelskému nebo systémovému datovému zdroji, na který odkazuje zdroj nesdílených dat. Kroky 3 až 5 se neprovádějí.
Vytváří připojovací řetězec pro ovladač. Driver připojovací řetězec je sjednocení klíčových slov specifikovaných v .dsn souboru a těch v původním aplikačním připojovací řetězec. Pravidla pro konstrukci driver připojovací řetězec, kde se klíčová slova překrývají, jsou následující:
Pokud klíčové slovo DRIVER existuje v application připojovací řetězec a ovladače specifikované klíčovými slovy DRIVER nejsou stejné v .dsn souboru a application připojovací řetězec, pak se informace o ovladači v .dsn souboru ignorují a ovladače v application připojovací řetězec jsou použity. Pokud jsou ovladače specifikované klíčovým slovem DRIVER stejné v souboru .dsn a v připojovací řetězec aplikace, pak tam, kde se všechna klíčová slova překrývají, mají přednost ta uvedená v aplikačním připojovací řetězec před těmi, která jsou specifikována v .dsn souboru.
V novém připojovací řetězec je klíčové slovo FILEDSN odstraněno.
Načte ovladač tak, že se HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<záznamu Driver Name>\Driver načte, kde <je Driver Name> zadán klíčovým slovem DRIVER .
Předá ovladači řetězec nových spojů.
Pro příklady .dsn souborů viz Connecting Using File Data Sources.
Klíčové slovo SAVEFILE
Pokud připojovací řetězec specifikovaný aplikací obsahuje klíčové slovo SAVEFILE, pak Driver Manager uloží připojovací řetězec do .dsn souboru. Vedoucí řidiče postupuje následovně:
Kontroluje, zda je název souboru .dsn zahrnutý jako hodnota atributu klíčového slova SAVEFILE platný. Pokud ne, vrátí SQL_ERROR pomocí SQLSTATE IM014 (Neplatné jméno souboru DSN). Platnost názvu souboru je určena standardními pravidly systémového pojmenování. Pokud je název souboru prázdný řetězec ("") a argument DriverCompletion není SQL_DRIVER_NOPROMPT, pak je název souboru platný. Pokud název souboru již existuje, pak pokud je DriverCompletion SQL_DRIVER_NOPROMPT, soubor je přepsán. Pokud je DriverCompletion SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE nebo SQL_DRIVER_COMPLETE_REQUIRED, zobrazí se dialogové okno uživatele, aby určil, zda má být soubor přepsán. Pokud je zadáno Ne, zobrazí se dialogové okno Ukládání souborů .
Pokud ovladač vrátí SQL_SUCCESS a název souboru nebyl prázdný řetězec, pak správce ovladačů zapíše informace o spojení vrácené v argumentu OutConnectionString do určeného souboru s formátem uvedeným v sekci "Connection Strings" dříve v této sekci.
Pokud ovladač vrátí SQL_SUCCESS a název souboru byl prázdný řetězec (""), pak správce ovladačů volá společné dialogové okno File-Save s určeným hwnd a zapíše informace o spojení vrácené v OutConnectionString do souboru uvedeného v File-Save společném dialogovém okně s formátem uvedeným v sekci "Connection Strings" dříve v této sekci.
Pokud ovladač vrátí SQL_SUCCESS, vrátí aplikaci argument OutConnectionString obsahující připojovací řetězec.
Pokud ovladač vrátí SQL_SUCCESS_WITH_INFO nebo SQL_ERROR, správce ovladačů vrátí aplikaci SQLSTATE.
Pokyny pro řidiče
Ovladač kontroluje, zda připojovací řetězec předaný Driver Managerem obsahuje klíčové slovo DSN nebo DRIVER. Pokud připojovací řetězec obsahuje klíčové slovo DRIVER, ovladač nemůže získat informace o datovém zdroji ze systémových informací. Pokud připojovací řetězec obsahuje klíčové slovo DSN nebo neobsahuje ani DSN, ani DRIVER, může ovladač získat informace o datovém zdroji ze systémových informací následovně:
Pokud připojovací řetězec obsahuje klíčové slovo DSN, ovladač získá informace o daném datovém zdroji.
Pokud připojovací řetězec neobsahuje klíčové slovo DSN, není nalezen specifikovaný zdroj dat nebo je klíčové slovo DSN nastaveno na "",DEFAULT ovladač získá informace o výchozím datovém zdroji.
Ovladač využívá jakékoli informace, které získá ze systémových informací, k rozšíření informací předávaných v připojovací řetězec. Pokud informace v systémových informacích duplikují informace v připojovací řetězec, ovladač použije informace z připojovací řetězec.
Na základě hodnoty DriverCompletion ovladač vyzve uživatele k informacím o připojení, jako je uživatelské ID a heslo, a připojí se ke zdroji dat:
SQL_DRIVER_PROMPT: Ovladač zobrazí dialogové okno, přičemž jako počáteční hodnoty použije hodnoty z připojovací řetězec a systémové informace (pokud existují). Když uživatel opustí dialogové okno, ovladač se připojí ke zdroji dat. Také vytváří připojovací řetězec z hodnoty klíčového slova DSN nebo DRIVER v *InConnectionString a informací vrácených z dialogového okna. Tento připojovací řetězec umístí do bufferu *OutConnectionString.
SQL_DRIVER_COMPLETE nebo SQL_DRIVER_COMPLETE_REQUIRED: Pokud připojovací řetězec obsahuje dostatek informací a tyto informace jsou správné, ovladač se připojí ke zdroji dat a zkopíruje *InConnectionString do *OutConnectionString. Pokud chybí nebo jsou nesprávné informace, ovladač provede stejné kroky jako při SQL_DRIVER_PROMPT DriverCompletion (dokončení DriverCompletion SQL_DRIVER_COMPLETE_REQUIRED), ovladač deaktivuje ovládání pro informace, které nejsou nutné k připojení ke zdroji dat.
SQL_DRIVER_NOPROMPT: Pokud připojovací řetězec obsahuje dostatek informací, ovladač se připojí ke zdroji dat a zkopíruje *InConnectionString do *OutConnectionString. Jinak ovladač vrátí SQL_ERROR pro SQLDriverConnect.
Po úspěšném připojení ke zdroji dat ovladač také nastaví *StringLength2Ptr na délku výstupního připojovací řetězec, který je k dispozici pro vrácení v *OutConnectionString.
Pokud uživatel zruší dialogové okno zobrazené Správcem ovladačů nebo ovladačem, SQLDriverConnect vrátí SQL_NO_DATA.
Pro informace o tom, jak Správce ovladačů a ovladač během procesu připojení interagují, viz Funkce SQLConnect.
Pokud ovladač podporuje SQLDriverConnect, musí sekce klíčových slov v systémových informacích pro ovladač obsahovat klíčové slovo ConnectFunctions s druhou sadou znaků na "Y".
Připojení při povolení poolování připojení
Poolování spojení umožňuje aplikaci znovu použít již vytvořené spojení. Když je volán SQLDriverConnect , správce ovladačů se snaží navázat spojení pomocí spojení, které je součástí poolu spojení v prostředí určeném pro pooling spojení. Pro více informací o poolování spojení viz SQLConnect Function.
Aplikace může nastavit SQL_ATTR_RESET_CONNECTION před zavoláním SQLDisconnect na spojení, kde je pooling povolen. Další informace naleznete v tématu SQLSetConnectAttr – funkce.
Následující omezení platí, když aplikace volá SQLDriverConnect pro připojení k poolu:
Zpracování connection pooling se neprovádí, když je klíčové slovo SAVEFILE zadáno v připojovací řetězec.
Pokud je pooling připojení povolen, lze SQLDriverConnect volat pouze s argumentem DriverCompletion SQL_DRIVER_NOPROMPT; pokud je SQLDriverConnect vyvolán s jakýmkoli jiným DriverCompletion, vrátí se SQLSTATE HY110 (Invalid driver completion).
Atributy připojení
Atribut SQL_ATTR_LOGIN_TIMEOUT připojení, nastavený pomocí SQLSetConnectAttr, definuje počet sekund čekajících na dokončení přihlašovacího požadavku s úspěšným připojením ovladače před návratem do aplikace. Pokud je uživatel vyzván k dokončení připojovací řetězec, začíná čekací doba pro každý přihlašovací požadavek, kdy ovladač zahájí proces připojení.
Ovladač otevírá spojení ve výchozím SQL_MODE_READ_WRITE přístupovém režimu. Pro nastavení přístupového režimu na SQL_MODE_READ_ONLY musí aplikace před zavoláním SQLDriverConnect vyvolat SQLSetConnectAttr s atributem SQL_ATTR_ACCESS_MODE.
Pokud je v systémových informacích pro datový zdroj specifikována výchozí překladová knihovna, ovladač ji načte. Jinou překladovou knihovnu lze načíst voláním SQLSetConnectAttr s atributem SQL_ATTR_TRANSLATE_LIB. Možnost překladu lze zvolit voláním SQLSetConnectAttr s možností SQL_ATTR_TRANSLATE_OPTION.
Pro více informací viz Connecting with SQLDriverConnect.
// SQLDriverConnect_ref.cpp
// compile with: odbc32.lib user32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR OutConnStr[255];
SQLSMALLINT OutConnStrLen;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
// 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);
retcode = SQLDriverConnect( // SQL_NULL_HDBC
hdbc,
desktopHandle,
(SQLCHAR*)"driver=SQL Server",
_countof("driver=SQL Server"),
OutConnStr,
255,
&OutConnStrLen,
SQL_DRIVER_PROMPT );
// Allocate statement handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Process data
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
}
SQLDisconnect(hdbc);
}
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
}
Viz také ukázkový program ODBC.
Související funkce
| Informace o | Podívejte se |
|---|---|
| Přiřazení rukojeti | SQLAllocHandle Function |
| Objevování a vyčíslování hodnot potřebných k připojení ke zdroji dat | Funkce SQLBrowseConnect |
| Připojení ke zdroji dat | Funkce SQLConnect |
| Odpojení od datového zdroje | Funkce SQLDisconnect |
| Vracející se popisy a atributy jezdců | Funkce SQLDrivers |
| Uvolnění rukojeti | Funkce SQLFreeHandle |
| Nastavení atributu spojení | SQLSetConnectAttr – funkce |