SQLDriverConnect függvény

Megfelelőség
Bemutatott verzió: ODBC 1.0 Szabványoknak megfelelés: ODBC

Összefoglalás
Az SQLDriverConnect alternatíva az SQLConnect-nek. Támogatja azokat az adatforrásokat, amelyek több kapcsolati információt igényelnek, mint az SQLConnect három argumentuma, párbeszédablakokat, amelyek minden kapcsolati információt kérnek a felhasználótól, valamint olyan adatforrásokat, amelyek nincsenek definiálva a rendszeradatokban. További információért lásd: Kapcsolat SQLDriverConnect-szel.

Syntax

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);

Arguments

ConnectionHandle
[Bemenet] Kapcsolati leíró.

WindowHandle
[Bemenet] Ablakkilincs. Az alkalmazás átadhatja az anyaablak fogantyúját, ha van ilyen, vagy null mutatót, ha az ablak fogantyúja nem alkalmazható, vagy az SQLDriverConnect nem jelenít meg párbeszédablakokat.

InConnectionString
[Bemenet] Teljes kapcsolati karakterlánc (lásd a szintaxist a "Kommentekben"), egy részleges kapcsolati karakterlánc vagy egy üres string.

StringLength1
[Bemenet] *InConnectionString hossza, karakterekben, ha a string Unicode, vagy bájtokban, ha a string ANSI vagy DBCS.

OutConnectionString
[Kimenet] Mutató a pufferre a befejezett kapcsolati karakterlánc számára. A célforráshoz való sikeres csatlakozás után ez a puffer tartalmazza a befejezett kapcsolati karakterlánc-et. Az alkalmazásoknak legalább 1 024 karaktert kell kijelölniük ehhez a pufferhez.

Ha az OutConnectionString NULL, akkor a StringLength2Ptr továbbra is visszaadja az összes karakterszámot (kivéve a null-terminációs karaktert a karakteradatokhoz), amelyek az OutConnectionString által mutatott pufferben elérhetőek vissza.

BufferLength
[Bemenet] A *OutConnectionString puffer hossza, karakterekben.

StringLength2Ptr
[Kimenet] Mutató egy pufferre, amelyben vissza lehet adni a *OutConnectionString-ben elérhető karakterek teljes számát (a null-terminációs karakter kivételével). Ha a visszaadható karakterek száma nagyobb, mint a BufferLength, akkor az *OutConnectionString kivégzett kapcsolati karakterlánc lerövidítése BufferLength-re mínusz egy null-terminációs karakter hosszára.

DriverCompletion
[Bemenet] Jelző, amely jelzi, hogy a Driver Manager vagy az illesztőprogram további kapcsolati információkat kér-e:

SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED vagy SQL_DRIVER_NOPROMPT.

(További információért lásd: "Hozzászólások".)

Returns

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

Diagnostics

Amikor az SQLDriverConnect SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad, egy hozzárendelt SQLSTATE érték megkapható SQLGetDiagRec hívásával, amely egy fHandleType SQL_HANDLE_DBC és egy hHandle of ConnectionHandle (ConnectionHandle) segítségével szól. Az alábbi táblázat felsorolja az SQLDriverConnect által gyakran visszaadott SQLSTATE értékeket, és mindegyiket ennek a függvénynek a kontextusában magyarázza; a "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATE-leírásokat. Az egyes SQLSTATE-értékekhez társított visszatérési kód SQL_ERROR, kivéve, ha másként van feltüntetve.

SQLSTATE Error Description
01000 Általános figyelmeztetés Illesztőprogram-specifikus tájékoztató üzenet. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
01004 Sztringadatok, jobb csonkolt Az *OutConnectionString puffer nem volt elég nagy ahhoz, hogy visszaadja az egész kapcsolati karakterlánc-et, ezért a kapcsolati karakterlánc lerövidített. A csonkítatlan kapcsolati karakterlánc hosszát a *StringLength2Ptr fájlban adjuk vissza. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
01S00 Invalid kapcsolati karakterlánc attribútum A kapcsolati karakterlánc (InConnectionString) egy érvénytelen attribútumkulcsszót megadott volt, de a meghajtó így is tudott csatlakozni az adatforráshoz. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
01S02 A beállítás értéke módosult Az illezser nem támogatta az SQLSetConnectAttrValuePtr argumentusa által kijelölt értéket, és hasonló értéket cserélt. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
01S08 DSN fájl hibamentése Az *InConnectionString szövegében szerepelt egy FILEDSN kulcsszó, de a .dsn fájl nem mentve el. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
01S09 Érvénytelen kulcsszó (DM) Az *InConnectionString szövegében szerepelt egy SAVEFILE kulcsszó, de nem volt DRIVER vagy FILEDSN kulcsszó. (A függvény SQL_SUCCESS_WITH_INFO ad vissza.)
08001 Az ügyfél nem tudja kapcsolatot teremteni A meghajtó nem tudott kapcsolatot teremteni az adatforrással.
08002 Használatban lévő kapcsolatnév (DM) A megadott ConnectionHandle már használódott egy adatforráshoz való kapcsolat létrehozására, és a kapcsolat még mindig nyitva volt.
08004 A szerver elutasította a kapcsolatot Az adatforrás elutasította a kapcsolat létrehozását megvalósítás által meghatározott okok miatt.
08S01 Kommunikációs kapcsolat hibája Az illesztőprogram és az adatforrás közötti kommunikációs kapcsolat, amelyhez az illezőgép csatlakozni próbált, meghibásodott, mielőtt az SQLDriverConnect funkció befejezte volna a feldolgozást.
28000 Érvénytelen jogosultsági specifikáció Vagy a felhasználói azonosító, akár az engedélyezési string, vagy mindkettő, ahogy a kapcsolati karakterlánc (InConnectionString) megjelöli, megsértette az adatforrás által meghatározott korlátozásokat.
HY000 Általános hiba Hiba történt, amely miatt nem volt konkrét SQLSTATE, és amelyhez nem definiáltak implementációspecifikus SQLSTATE-t. Az SQLGetDiagRec által a *szMessageText pufferben visszaadott hibaüzenet leírja a hibát és annak okát.
HY000 Általános hiba: Érvénytelen fájl dsn (DM) Az *InConnectionString szövegében szerepelt egy FILEDSN kulcsszó, de a .dsn fájl neve nem került elő.
HY000 Általános hiba: Nem sikerült fájlpuffert létrehozni (DM) A *InConnectionString szövegében szerepelt egy FILEDSN kulcsszó, de a .dsn fájl olvashatatlan volt.
HY001 Memóriafoglalási hiba A Driver Manager nem tudta lekötni a szükséges memóriát az SQLDriverConnect funkció végrehajtásához vagy befejezéséhez.

Az illesztőprogram nem tudta lefoglalni a függvény végrehajtásának vagy befejezésének támogatásához szükséges memóriát.
HY008 Művelet megszakítva Az aszinkron feldolgozás engedélyezett volt a ConnectionHandle számára. A függvényt meghívták, és mielőtt befejezte volna a végrehajtást, az SQLCancelHandle függvényt hívták meg a ConnectionHandle-en, majd az SQLDriverConnect funkciót ismét a ConnectionHandle-en.

Vagy az SQLDriverConnect függvényt hívták, és mielőtt befejezte volna a végrehajtást, az SQLCancelHandle-t a ConnectionHandle-en egy másik szálból hívták meg egy többszálú alkalmazásban.
HY010 Függvényütemezési hiba (DM) Egy másik aszinkron futó függvény (nem SQLDriverConnect) a ConnectionHandle számára volt meghívva, és még futott, amikor az SQLDriverConnect funkciót hívták.
HY013 Memóriakezelési hiba Az SQLDriverConnect függvényhívást nem lehetett feldolgozni, mert az alapul szolgáló memóriaobjektumokat nem lehetett elérni, valószínűleg alacsony memóriafeltételek miatt.
HY090 Érvénytelen sztring vagy puffer hossza (DM) A StringLength1 argumentus értéke kisebb volt 0-nál, és nem volt egyenlő SQL_NTS-vel.

(DM) A BufferLength argumentumhoz megadott érték kisebb, mint 0.
HY092 Érvénytelen attribútum/opcióazonosító (DM) A DriverCompletion érve SQL_DRIVER_PROMPT volt, míg a WindowHandle érve null pointer volt.
HY110 Érvénytelen driver-teljesítés (DM) A DriverCompletion argumentumhoz megadott érték nem volt egyenlő SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED vagy SQL_DRIVER_NOPROMPT.

(DM) A kapcsolat pooling engedélyezve volt, és a DriverCompletion argumentus értéke nem volt SQL_DRIVER_NOPROMPT.
HYC00 A választható funkció nem implementálva Az illezőprogram nem támogatja az alkalmazás által kért ODBC viselkedési verziót.
HYT00 Az időtúllépés lejárt A bejelentkezési időkorlát lejárt, mielőtt az adatforráshoz való csatlakozás befejeződött. Az időtúli időszakot az SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT segítségével állítják be.
HYT01 A kapcsolati időkorlát lejárt A kapcsolat időtúllépési időtartama lejárt, mielőtt az adatforrás válaszolt a kérésre. A kapcsolat időtúllépési időszaka az SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT keresztül van beállítva.
IM001 Az illesztőprogram nem támogatja ezt a függvényt (DM) A megadott adatforrás nevéhez tartozó illesztőprogram nem támogatja a funkciót.
IM002 Adatforrás nem talált, és alapértelmezett illesztőprogram nem volt megadva. (DM) A kapcsolati karakterlánc (InConnectionString) által megadott adatforrás név nem található meg a rendszerinformációkban, és nem volt alapértelmezett illesztőprogram-specifikáció.

(DM) Az ODBC adatforrás és alapértelmezett illesztőprogram-információk nem találhatók meg a rendszer adataiban.
IM003 A megadott illesztőprogramot nem lehetett betölteni (DM) Az adatforrás specifikációjában a rendszerinformációban vagy a DRIVER kulcsszavaban megadott illesztőprogramot nem találták meg, vagy más okból nem lehetett betölteni.
IM004 Driver SQLAllocHandle SQL_HANDLE_ENV hibás (DM) SQLDriverConnect során a Driver Manager a driverek SQLAllocHandle funkcióját hívta egy fHandleType SQL_HANDLE_ENV értékű eszközzel, és az illezser hibát adott vissza.
IM005 A driver-SQL_HANDLE_DBC SQLAllocHandle meghibásodott. (DM) Az SQLDriverConnect során a Driver Manager hívta az illezser SQLAllocHandle funkcióját egy fHandleType SQL_HANDLE_DBC jelmel, és az illezőprogram hibát adott vissza.
IM006 Driver's SQLSetConnectAttr hibás (DM) Az SQLDriverConnect során a Driver Manager hívta az illezser SQLSetConnectAttr funkcióját, és az illesztőprogram hibát adott vissza.
IM007 Nem tartalmaz adatforrást vagy meghajtót; Párbeszéd tiltott A kapcsolati karakterlánc nem tartalmazott adatforrás nevet vagy illesztőprogramot, és a DriverCompletion SQL_DRIVER_NOPROMPT.
IM008 Párbeszéd sikertelen A meghajtó megpróbálta megjeleníteni a bejelentkezési párbeszédablakot, de sikertelenül.

A WindowHandle null pointer volt, a DriverCompletion pedig nem volt SQL_DRIVER_NO_PROMPT.
IM009 Nem lehet betölteni a fordítási DLL-t Az illezser nem tudta betölteni a fordítási DLL-t, amely az adatforráshoz vagy a kapcsolathoz volt megadva.
IM010 Az adatforrás neve túl hosszú (DM) A DSN kulcsszavanak attribútumértéke hosszabb volt, mint SQL_MAX_DSN_LENGTH karakter.
IM011 A versenyző neve túl hosszú (DM) A DRIVER kulcsszó attribútumértéke hosszabb volt 255 karakternél.
IM012 DRIVER kulcsszó szintaktishiba (DM) A DRIVER kulcsszó kulcsszó-érték párja szintaktishibat tartalmazott.

(DM) Az *InConnectionString stringje tartalmazott egy FILEDSN kulcsszót, de a .dsn fájl nem tartalmazott DRIVER kulcsszót vagy DSN kulcsszót.
IM014 A megadott DSN architektúrabeli eltérést tartalmaz az illesztőprogram és az alkalmazás között (DM) 32 bites alkalmazás DSN-t használ, amely egy 64 bites illezőprogramhoz csatlakozik; vagy fordítva.
IM015 Az illevezető SQLDriverConnect SQL_HANDLE_DBC_INFO_HANDLE-n hibás Ha egy illesztőprogram SQL_ERROR visszaad, a Driver Manager visszaadja SQL_ERROR az alkalmazásnak, és a kapcsolat meghibásodik.

További információért SQL_HANDLE_DBC_INFO_TOKEN lásd: Fejlődés Connection-Pool tudatosság egy ODBC meghajtóban.
IM017 A lekérdezés aszinkron értesítési módban le van tiltva Az értesítési modell használata esetén a lekérdezés le van tiltva.
IM018 Az SQLCompleteAsync nem lett meghívva az előző aszinkron művelet végrehajtásához ezen a leírón. Ha a leíró előző függvényhívása SQL_STILL_EXECUTING ad vissza, és ha az értesítési mód engedélyezve van, az SQLCompleteAsync-et a leírón kell meghívni a művelet utófeldolgozásához és befejezéséhez.
S1118 Az illesztőprogram nem támogatja az aszinkron értesítést Ha az illesztőprogram nem támogatja az aszinkron értesítést, nem lehet beállítani SQL_ATTR_ASYNC_DBC_EVENT vagy SQL_ATTR_ASYNC_DBC_RETCODE_PTR.

Comments

Egy kapcsolati karakterlánc a következő szintaxissal rendelkezik:

connection-string ::= üres-string[;] | attribútum[;] | attribútum; kapcsolódási lánc

üres-string ::=attribútum ::= attribútum-kulcsszó-érték= | DRIVER=[{]attribute-value[}]

attribútum-kulcsszó ::= DSN | UID | PWD | driver-defined-attributed-kulcsszó

attribútum-érték ::= karakter-lánc

driver-defined-attribute-keyword ::= azonosító

ahol a karakterlánc nulla vagy több karaktert tartalmaz; az azonosító egy vagy több karakterből áll; attribútum-kulcsszó nem kis- és nagybetűérzékeny; az attribútumérték lehet kis-kis- érzékeny; és a DSN kulcsszó értéke nem kizárólag üres pontokból áll.

A kapcsolati karakterlánc és inicializációs fájl nyelvtana miatt, kulcsszavak és attribútumértékek tartalmazzák a []{}(),;? karaktereket. *=!@ nem zárva fogszabályzóval zárva, kerülni kell. A DSN-kulcsszó értéke nem állhat csak üres elemekből, és nem tartalmazhat kezdő üres elemeket. A rendszerinformációk nyelvtana miatt a kulcsszavak és az adatforrásnevek nem tartalmazhatják a fordított perjel (\) karaktert.

Az alkalmazásoknak nem kell a DRIVER kulcsszó után az attribútum értéke köré fogszabályzókat hozzáadniuk, kivéve, ha az attribútum tartalmaz egy félbasszút (;), ebben az esetben a fogszabályzók szükségesek. Ha az illesztőprogram által kapott attribútumérték kapcsos zárójeleket tartalmaz, az illesztőprogramnak nem szabad eltávolítania őket, hanem a visszaadott kapcsolati karakterlánc kell részesítenie őket.

Egy DSN vagy kapcsolati karakterlánc érték, amelyet rögzítők ({}) tartalmaznak () és tartalmazza a []{}(),;? *=!@ érintetlenül adja át a vezetőnek. Azonban amikor ezeket a karaktereket használják kulcsszóban, a Driver Manager hibát ad vissza DSN-ek fájl kezelése során, de a kapcsolati karakterlánc átvitele a meghajtónak a hagyományos kapcsolódási láncok esetén. Kerülje a beágyazott zárójelek használatát egy kulcsszóértékben.

A kapcsolati karakterlánc bármilyen számú illesztőprogram által definiált kulcsszót tartalmazhatnak. Mivel a DRIVER kulcsszó nem használja a rendszer információiból, az illesztővezetőnek elég kulcsszavakat kell definiálnia ahhoz, hogy egy illesztőgép csak a kapcsolati karakterlánc információi alapján csatlakozhasson egy adatforráshoz. (További információért lásd a "Vezetői irányelveket" ebben a szakaszban.) Az illeszőr határozza meg, hogy mely kulcsszavak szükségesek az adatforráshoz való kapcsoláshoz.

Az alábbi táblázat a DSN, FILEDSN, DRIVER, UID, PWD és SAVEFILE kulcsszavak attribútumértékeit írja le.

Keyword Attribútumérték leírása
DSN Az adatforrás neve az SQLDataSources vagy az SQLDriverConnect adatforrások párbeszédablaka alapján.
FILEDSN Egy .dsn fájl neve, amelyből kapcsolati karakterlánc épül az adatforráshoz. Ezeket az adatforrásokat fájlforrásoknak nevezzük.
VERSENYZŐ Az illesztőprogram leírása, ahogy az SQLDrivers függvény által visszaadott. Például az Rdb vagy az SQL Server.
UID Egy felhasználói azonosító.
PWD A felhasználói azonosítóhoz tartozó jelszó, vagy üres lánc, ha nincs jelszó (PWD=;).
MENTÉS Egy .dsn fájl fájlneve, amelyben a jelenlegi, sikeres kapcsolat létrehozásához használt kulcsszavak attribútumértékeit el kell menteni.

Arról, hogyan választ egy alkalmazás adatforrást vagy illevezetőt, lásd: Adatforrás vagy driver kiválasztása.

Ha bármilyen kulcsszó ismétlődik a kapcsolati karakterlánc-ben, az illesztőprogram az első előforduláshoz tartozó értéket használja. Ha a DSN és a DRIVER kulcsszavak ugyanabban a kapcsolati karakterlánc-ben vannak, a Driver Manager és az illezőprogram azt a kulcsszót használja, amely először jelenik meg.

A FILEDSN és DSN kulcsszavak kizárják egymást: melyik kulcsszót használják először, a másodszor megjelenő kulcsszót figyelmen kívül hagyjuk. A FILEDSN és a DRIVER kulcsszavak viszont nem zárják ki egymást. Ha bármely kulcsszó megjelenik egy FILEDSN-rel rendelkező kapcsolati karakterlánc-ben, akkor a kulcsszavanak attribútumértékét használják a kapcsolati karakterlánc értékében, nem pedig ugyanazon a kulcsszavanak a .dsn fájlban lévő attribútumértékét.

Ha a FILEDSN kulcsszót használják, a .dsn fájlban megadott kulcsszavakat használják egy kapcsolati karakterlánc létrehozásához. (További információért lásd a "Fájl adatforrások" (Fájl adatforrások) oldalán ebben a szakaszban.) Az UID kulcsszó opcionális; .dsn fájl csak a DRIVER kulcsszóval hozható létre. A PWD kulcsszó nem tárolható .dsn fájlban. A .dsn fájl alapértelmezett mentése és betöltése a CommonFileDir által a HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion és az "ODBC\DataSources" által meghatározott útvonal kombinációja lesz. (Ha a CommonFileDir "C:\Program Files\Common Files" lenne, az alapértelmezett könyvtár a "C:\Program Files\Common Files\ODBC\Data Sources" lenne.)

Note

Egy .dsn fájl közvetlenül manipulálható az telepítő DLL-ben az SQLReadFileDSN és SQLWriteFileDSN funkciók hívásával.

Ha a SAVEFILE kulcsszót használják, a jelenlegi, sikeres kapcsolat létrehozásához használt kulcsszavak attribútumértékei .dsn fájlként kerülnek elmentve, amelyen a SAVEFILE kulcsszó attribútumértékének neve szerepel. A SAVEFILE kulcsszót a DRIVER kulcsszavsal, a FILEDSN kulcsszóval vagy mindkettővel együtt kell használni, különben a függvény SQL_SUCCESS_WITH_INFO SQLSTATE 01S09 (Invalid kulcsszó) értéket ad vissza. A SAVEFILE kulcsszavanak a DRIVER kulcsszavanál kell megjelennie a kapcsolati karakterlánc-ben, különben az eredmények nem lesznek meghatározva.

Versenyzővezetői irányelvek

A Driver Manager egy kapcsolati karakterlánc-et épít, amely továbbítja az illezőgépnek az SQLDriverConnectfüggvény InConnectionString argumentumában. A Driver Manager nem módosítja az alkalmazás által továbbított InConnectionString argumentumot.

A Driver Manager akciója a DriverCompletion érv értékén alapul:

  • SQL_DRIVER_PROMPT: Ha a kapcsolati karakterlánc nem tartalmazza sem a DRIVER, sem DSN, sem FILEDSN kulcsszót, a Driver Manager megjeleníti az Adatforrások párbeszédablakot. A párbeszédablak által visszaadott adatforrás nevéből és az alkalmazás által továbbított egyéb kulcsszavakból épít kapcsolati karakterlánc-et. Ha a párbeszédablak által visszaadott adatforrás neve üres, a Driver Manager megadja a kulcsszó-érték párt a DSN=Default. (Ez a párbeszédablak nem jelenít meg "Default" nevű adatforrást.)

  • SQL_DRIVER_COMPLETE vagy SQL_DRIVER_COMPLETE_REQUIRED: Ha az alkalmazás által megadott kapcsolati karakterlánc tartalmazza a DSN kulcsszót, a Driver Manager az alkalmazás által megadott kapcsolati karakterlánc másolja. Egyébként ugyanazokat a műveleteket hajtja végre, mint amikor a DriverCompletion SQL_DRIVER_PROMPT.

  • SQL_DRIVER_NOPROMPT: A Driver Manager az alkalmazás által megadott kapcsolati karakterlánc másolja le.

Ha az alkalmazás által megadott kapcsolati karakterlánc tartalmazza a DRIVER kulcsszót, a Driver Manager lemásolja az alkalmazás által megadott kapcsolati karakterlánc-et.

Az általa létrehozott kapcsolati karakterlánc segítségével a Driver Manager eldönti, melyik illesztőprogramot használja, csatlakozik ahhoz, és átadja az általa létrehozott kapcsolati karakterlánc a drivernek; további információért a Driver Manager és az illesztőgép kölcsönhatásáról lásd az SQLConnect Function "Kommentek" szakaszát. Ha a kapcsolati karakterlánc nem tartalmazza a DRIVER kulcsszót, a Driver Manager a következőképpen határozza meg, melyik illevezetőt használja:

  1. Ha a kapcsolati karakterlánc tartalmazza a DSN kulcsszót, a Driver Manager a rendszerinformációból leállítja az adatforráshoz kapcsolódó illezőprogramot.

  2. Ha a kapcsolati karakterlánc nem tartalmazza a DSN kulcsszót, vagy az adatforrás nem található, a Driver Manager a rendszerinformációból leállítja az alapértelmezett adatforráshoz tartozó illezőprogramot. (További információért lásd: Alapértelmezett alkulcs.) A Driver Manager megváltoztatja a DSN kulcsszavanak értékét a kapcsolati karakterlánc "DEFAULT"-re.

  3. Ha a DSN kulcsszó a kapcsolati karakterlánc "DEFAULT" szintjére van állítva, a Driver Manager a rendszerinformációkból visszanyeri az alapértelmezett adatforráshoz tartozó illezőprogramot.

  4. Ha az adatforrás nem található, és az alapértelmezett adatforrás sem található, a Driver Manager SQL_ERROR SQLSTATE IM002-vel (adatforrás nem talált és alapértelmezett illesztőprogram nem van megadva).

Fájl adatforrásai

Ha az alkalmazás által az SQLDriverConnect hívásában megadott kapcsolati karakterlánc tartalmazza a FILEDSN kulcsszót, és ezt a kulcsszót sem a DSN, sem a DRIVER kulcsszó váltja fel, akkor a Driver Manager létrehoz egy kapcsolati karakterlánc a .dsn fájl információi és az InConnectionString argumentum alapján. A vezetővezető a következőképpen jár el:

  1. Ellenőrzi, hogy a .dsn fájl neve érvényes-e. Ha nem, akkor SQL_ERROR SQLSTATE IM014-et (Fault name of file name DSN) is visszaad. Ha a fájlnév üres string ("") és SQL_DRIVER_NOPROMPT nincs megadva, akkor megjelenik a Fájlnyitás (File-Open párbeszédablak). Ha a fájlnév érvényes útvonalat tartalmaz, de nincs fájlnév vagy érvénytelen fájlnév, és SQL_DRIVER_NOPROMPT nincs megadva, akkor a Fájlnyitás párbeszédablak megjelenik azzal, hogy a jelenlegi könyvtár a fájlnévben megadott könyvtárra van állítva. Ha a fájlnév üres string ("") vagy a fájlnév érvényes útvonalat tartalmaz, de nincs fájlnév vagy érvénytelen fájlnév, és SQL_DRIVER_NOPROMPT meg van jelölve, akkor SQL_ERROR SQLSTATE IM014 (Invalid name of file DSN) jelenik meg.

  2. Olvassa az összes kulcsszót a .dsn fájl [ODBC] részében. Ha a DRIVER kulcsszó nincs jelen, akkor az SQLSTATE IM012-vel (Driver kulcsszava-szintaxishiba) SQL_ERROR-t ad, kivéve akkor, ha a .dsn fájl nem osztható meg, így csak a DSN kulcsszót tartalmazza.

    Ha a fájl adatforrása megoszthatatlan, a Driver Manager olvassa a DSN kulcsszó értékét, és szükség esetén csatlakozik a felhasználóhoz vagy rendszerforráshoz, amelyet a nem megosztható fájlforrás mutat. A 3–5. lépések nem kerülnek el.

  3. Létrehoz egy kapcsolati karakterlánc a meghajtóhoz. A driver kapcsolati karakterlánc a .dsn fájlban megadott kulcsszavak és az eredeti alkalmazási kapcsolati karakterlánc kulcsszavak uniója. A driver kapcsolati karakterlánc építésének szabályai, ahol kulcsszavak átfednek, a következők:

    • Ha a DRIVER kulcsszó létezik az alkalmazás kapcsolati karakterlánc-ben, és a DRIVER kulcsszavak által megadott illezserek nem egyeznek meg a .dsn fájlban és az application kapcsolati karakterlánc-ben, akkor a .dsn fájlban szereplő illesztőprogram-információkat figyelmen kívül hagyjuk, és az alkalmazás kapcsolati karakterlánc illegser adatait használják. Ha a DRIVER kulcsszavanál megegyeztek a .dsn fájlban és az alkalmazás kapcsolati karakterlánc-jében, akkor ahol minden kulcsszó átfed, az alkalmazás kapcsolati karakterlánc által megadott kulcsszavak előnyben részelik a .dsn fájlban megjelöltekkel szemben.

    • Az új kapcsolati karakterlánc során a FILEDSN kulcsszó kiszűnik.

  4. A meghajtót úgy tölti be, hogy a Driver Name>\Driver HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<regisztrációs bejegyzésben keresi, ahol <a Driver név> a DRIVER kulcsszó által megjelölve.

  5. Átadja az illesztőprogramnak az új csatlakozási láncot.

A .dsn fájlok példáiért lásd : Fájladatforrások használatával való kapcsolódás.

SAVEFILE kulcsszó

Ha az alkalmazás által megadott kapcsolati karakterlánc tartalmazza a SAVEFILE kulcsszót, akkor a Driver Manager elmenti a kapcsolati karakterlánc-et egy .dsn fájlba. A vezetővezető a következőképpen jár el:

  1. Ellenőrzi, hogy a .dsn fájl fájlneve, amely a SAVEFILE kulcsszavahoz tartozó attribútumértékként szerepel, érvényes-e. Ha nem, akkor SQL_ERROR SQLSTATE IM014-et (Fault name of file name DSN) is visszaad. A fájlnév érvényességét a szabványos rendszerelnevezési szabályok határozzák meg. Ha a fájlnév üres string ("") és a DriverCompletion érve nem SQL_DRIVER_NOPROMPT, akkor a fájlnév érvényes. Ha a fájlnév már létezik, akkor ha a DriverCompletion SQL_DRIVER_NOPROMPT, a fájl felülír. Ha a DriverCompletion SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE vagy SQL_DRIVER_COMPLETE_REQUIRED, egy párbeszédablak arra kéri a felhasználót, hogy megadja, felülírja-e a fájlt. Ha a Nem jelölik be, akkor megjelenik a Fájlmentés párbeszédablak.

  2. Ha az illezser SQL_SUCCESS-ot ad vissza, és a fájlnév nem üres string, akkor a Driver Manager az OutConnectionString argumentumban visszaadott kapcsolati adatokat írja a megadott fájlba, a korábban említett "Connection Strings" szakaszban megadott formátumban.

  3. Ha az illesztőprogram SQL_SUCCESS-ot ad vissza, és a fájl neve üres string (""), akkor a Driver Manager a Fájlmentés közös párbeszédablakát a hwnd megadott számmal hívja, és az OutConnectionStringben visszaküldött kapcsolati adatokat a File-Save közös párbeszédablakban megadott fájlba írja a korábbi "Kapcsolati stringek" szakaszban megadott formátummal.

  4. Ha az illesztőprogram SQL_SUCCESS-t ad, akkor az OutConnectionString argumentumot adja vissza, amely tartalmazza a kapcsolati karakterlánc az alkalmazásnak.

  5. Ha az illezőprogram SQL_SUCCESS_WITH_INFO vagy SQL_ERROR visszaadja az SQLSTATE-t, akkor a Driver Manager visszaadja az SQLSTATE-et az alkalmazásnak.

Vezetői irányelvek

Az illesztőprogram ellenőrzi, hogy a Driver Manager által átadott kapcsolati karakterlánc tartalmazza-e a DSN vagy DRIVER kulcsszót. Ha a kapcsolati karakterlánc tartalmazza a DRIVER kulcsszót, az illesztőprogram nem tudja visszanyerni az adatforrásról szóló információkat a rendszerinformációkból. Ha a kapcsolati karakterlánc tartalmazza a DSN kulcsszót, vagy nem tartalmazza sem a DSN-t, sem a DRIVER kulcsszót, az illesztőprogram az alábbi módon kérheti le az adatforrásról szóló információkat:

  1. Ha a kapcsolati karakterlánc tartalmazza a DSN kulcsszót, az illesztőprogram visszanyeri az adott adatforrás adatait.

  2. Ha a kapcsolati karakterlánc nem tartalmazza a DSN kulcsszót, a megadott adatforrás nem található, vagy a DSN kulcsszó "DEFAULT" lesz, az illesztőprogram lekéri az alapértelmezett adatforrás adatait.

A meghajtó minden információt, amit a rendszerinformációból nyer, felhasználja a kapcsolati karakterlánc által továbbított információ kiegészítésére. Ha a rendszerinformációban lévő információ másolja a kapcsolati karakterlánc információit, akkor a meghajtó a kapcsolati karakterlánc információját használja.

A DriverComplete értéke alapján az illesztőprogram a felhasználó számára a kapcsolati információkat, például a felhasználói azonosítót és jelszót, majd csatlakozik az adatforráshoz:

  • SQL_DRIVER_PROMPT: Az illesztőprogram egy párbeszédablakot jelenít meg, amely a kapcsolati karakterlánc értékeit és a rendszerinformációkat (ha van) használja kezdeti értékként. Amikor a felhasználó kilép a párbeszédablakból, az illesztőprogram csatlakozik az adatforráshoz. Emellett egy kapcsolati karakterlánc is épít a *InConnectionStringDSN vagy DRIVER kulcsszavajának értékéből, valamint a párbeszédablakból visszaadott információkból. Ezt a kapcsolati karakterlánc a *OutConnectionString pufferbe helyezi.

  • SQL_DRIVER_COMPLETE vagy SQL_DRIVER_COMPLETE_REQUIRED: Ha a kapcsolati karakterlánc elegendő információt tartalmaz, és az információ helyes, az illesztőprogram csatlakozik az adatforráshoz, és az *InConnectionString-et *OutConnectionString-re másolja. Ha bármilyen információ hiányzik vagy hibás, az illesztőprogram ugyanazokat a lépéseket teszi, mint amikor a DriverCompletion SQL_DRIVER_PROMPT, kivéve, hogy ha a DriverCompletion SQL_DRIVER_COMPLETE_REQUIRED, az illesztőprogram kitiltja azokat az adatokat, amelyek nem szükségesek az adatforráshoz való csatlakozáshoz.

  • SQL_DRIVER_NOPROMPT: Ha a kapcsolati karakterlánc elegendő információt tartalmaz, az illezőgép csatlakozik az adatforráshoz, és az *InConnectionString-et az *OutConnectionString-re másolja. Ellenkező esetben az illesztőprogram SQL_ERROR SQLDriverConnect esetén ad vissza.

Sikeres kapcsolat esetén az illesztőprogram beállítja a *StringLength2Ptr formátumot annak a kimeneti kapcsolati karakterlánc hosszára, amely az *OutConnectionString-ben vissza van adva.

Ha a felhasználó töröl egy Driver Manager vagy az illesztőprogram által bemutatott párbeszédablakot, az SQLDriverConnect SQL_NO_DATA visszaad.

Arról, hogyan lép kölcsönhatásba a Driver Manager és az illezőgép a csatlakozási folyamat során, lásd: SQLConnect Function.

Ha egy illesztőprogram támogatja az SQLDriverConnect-et, akkor a meghajtó kulcsszavajának tartalmaznia kell a ConnectFunctions kulcsszót, amelynek második karaktere "Y"-re.

Csatlakozás, amikor a kapcsolat feltöltése engedélyezve van

A kapcsolat pooling lehetővé teszi, hogy az alkalmazás újrahasznosítsa a már létrehozott kapcsolatot. Amikor az SQLDriverConnectet hívják, a Driver Manager megpróbálja létrehozni a kapcsolatot egy olyan kapcsolat segítségével, amely egy olyan kapcsolati csoport része, amelyet egy olyan környezetben jelöltek ki, amelyeket a kapcsolat pooling-ra jelöltek. További információért a kapcsolati poolingről lásd: SQLConnect Function.

Egy alkalmazás beállíthatja SQL_ATTR_RESET_CONNECTION az SQLDisconnect hívása előtt egy olyan kapcsolaton, ahol a pooling engedélyezett. További információ: SQLSetConnectAttr függvény.

Az alábbi korlátozások érvényesek, amikor egy alkalmazás SQLDriverConnectet hív egy csoportos kapcsolathoz való csatlakozáshoz:

  • A kapcsolat pooling feldolgozása nem történik, ha a SAVEFILE kulcsszó meg van jelölve a kapcsolati karakterlánc-ben.

  • Ha a kapcsolat pooling engedélyezett, az SQLDriverConnect csak SQL_DRIVER_NOPROMPT DriverCompletion argumentummal hívható; ha SQLDriverConnectet bármely más DriverCompletion-lel hívják, akkor visszakerül a SQLSTATE HY110 (Invalid driver completion).

Kapcsolati attribútumok

Az SQL_ATTR_LOGIN_TIMEOUT kapcsolat attribútum, amelyet SQLSetConnectAttr segítségével állítanak be, meghatározza a másodpercek számát, amíg a bejelentkezési kérelmek sikeres a meghajtó által befejeződnek, mielőtt visszatérne az alkalmazáshoz. Ha a felhasználót arra kérik, hogy fejezze be a kapcsolati karakterlánc, minden bejelentkezési kérelmet várakozó idővel kezdődik, amikor az illesztőprogram elindítja a kapcsolati folyamatot.

A meghajtó alapértelmezés szerint SQL_MODE_READ_WRITE hozzáférési módban nyitja meg a kapcsolatot. Ahhoz, hogy a hozzáférési módot SQL_MODE_READ_ONLY-re állítsuk, az alkalmazásnak az SQLDriverConnect hívása előtt az SQLSetConnectAttr-t kell hívnia a SQL_ATTR_ACCESS_MODE attribútummal.

Ha az adatforrás rendszerinformációiban egy alapértelmezett fordítási könyvtár van megadva, az illesztőprogram betölti azt. Egy másik fordító könyvtár betölthető, ha az SQLSetConnectAttr hívása a SQL_ATTR_TRANSLATE_LIB attribútummal működik. Fordítási opció megadható SQLSetConnectAttr hívásával a SQL_ATTR_TRANSLATE_OPTION opcióval.

További információért lásd: Kapcsolat SQLDriverConnect-szel.

// 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);  
   }  
}

Lásd még a Sample ODBC programot.

Információ erről: Nézze
Kiosztás egy fogantyú SQLAllocHandle függvény
Az adatforráshoz való csatlakozáshoz szükséges értékek felfedezése és felsorolása SQLBrowseConnect függvény
Csatlakozás adatforráshoz SQLConnect-függvény
Adatforrásról való kikapcsolás SQLDisconnect függvény
Visszatérő versenyző leírásai és attribútumok SQLDrivers Function
Egy fogantyú felszabadítása SQLFreeHandle függvény
Kapcsolati attribútumot beállítás SQLSetConnectAttr függvény

Lásd még

ODBC API-referencia
ODBC-fejlécfájlok

  • Last updated on