Funkce SQLDriverConnect

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ě:

  1. 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í.

  2. 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".

  3. 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í.

  4. 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ě:

  1. 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).

  2. Č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í.

  3. 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.

  4. 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 .

  5. 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ě:

  1. 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ů .

  2. 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.

  3. 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.

  4. Pokud ovladač vrátí SQL_SUCCESS, vrátí aplikaci argument OutConnectionString obsahující připojovací řetězec.

  5. 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ě:

  1. Pokud připojovací řetězec obsahuje klíčové slovo DSN, ovladač získá informace o daném datovém zdroji.

  2. 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.

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

Viz také

Referenční rozhraní ODBC API
Soubory hlaviček ODBC