SQLBrowseConnect függvény

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

Összefoglalás
Az SQLBrowseConnect egy iteratív módszert támogat az adatforráshoz való csatlakozáshoz szükséges attribútumok és attribútumértékek felfedezésére és felsorolására. Minden SQLBrowseConnect hívás egymást követő szintű attribútumokat és attribútumértékeket ad vissza. Amikor minden szintet felsoroltak, az adatforráshoz való kapcsolat teljesül, és az SQLBrowseConnect egy teljes kapcsolati karakterlánc adja. Egy SQL_SUCCESS vagy SQL_SUCCESS_WITH_INFO visszajelző kód azt jelzi, hogy minden kapcsolati információ meg lett adva, és az alkalmazás most már csatlakozott az adatforráshoz.

Syntax

  
SQLRETURN SQLBrowseConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr);  

Arguments

ConnectionHandle
[Bemenet] Kapcsolati leíró.

InConnectionString
[Bemenet] Böngésszük a request kapcsolati karakterlánc (lásd "InConnectionString argument" a "Kommentek" részben).

StringLength1
[Bemenet] *InConnectionString hossza karakterekben.

OutConnectionString
[Kimenet] Mutató egy karakterpufferre, amelyben a böngészési eredmény kapcsolati karakterlánc visszaadható (lásd "OutConnectionString Argument" a "Comments" részben).

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] Az *OutConnectionString-ben vissza lehet térni a karakterek teljes száma (null-termináció nélkül). Ha a visszaadható karakterek száma nagyobb, mint a BufferLength, akkor az *OutConnectionString kapcsolati karakterlánc a null-terminációs karakter hosszát mínusz BufferLength-re vágjuk.

Returns

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

Diagnostics

Amikor SQLBrowseConnect SQL_ERROR, SQL_SUCCESS_WITH_INFO vagy SQL_NEED_DATA értéket ad vissza, egy hozzárendelt SQLSTATE érték elérhető SQLGetDiagRec hívásával, amely egy SQL_HANDLE_STMT HandleType és egy ConnectionHandle Handle nevű eszköz. Az alábbi táblázat felsorolja az SQLBrowseConnect á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.

InConnectionString érvelés

Egy böngészési kérés kapcsolati karakterlánc a következő szintaxissal rendelkezik:

connection-string ::= attribútum[;] | Attribútum;kapcsolat-lánc;
attribútum: := attribútum-kulcsszó-érték= | DRIVER=[{]attribútum-érték[}]
attribútum-kulcsszó ::= DSN | | UID | PWDdriver-determined-attribútum-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. A *=!@ kerülni kell. A rendszer nyelvtana miatt a kulcsszavak és az adatforrások nem tartalmazhatják a visszaoldali (\) karaktert. Egy ODBC 2-hez. x driver esetén a DRIVER kulcsszó attribútumértéke körül kell tartani a fogszabályzókat.

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

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

OutConnectionString érvelés

A böngésző eredmény kapcsolati karakterlánc a kapcsolat attribútumok listája. A kapcsolati attribútum egy attribútumkulcsszóból és egy hozzá tartozó attribútumértékből áll. A böngésző eredmény kapcsolati karakterlánc a következő szintaxissal rendelkezik:

connection-string ::= attribútum[;] | Attribútum;kapcsolódási lánc
attribútum ::= [*]attribútum-kulcsszó-érték=
attribútum-kulcsszó ::= ODBC-attribútum-kulcsszó | driver-defined-attributed-kulcsszó
ODBC-attribute-keyword = {UID | PWD}[:localized-identifier] driver-defined-attribute-keyword ::= identifier[:localized-identifier] attribute-value ::= {attribute-value-list} | ? (A fogszabályzók literálisak; a meghajtó adja vissza őket.)
attribútum-érték-lista ::= karakter-sorozat [:lokalizált karakterlánc] | karakter-string [:lokalizált karakterlánc],attribútum-érték-lista

ahol a karakterlánc és a lokalizált karakterlánc nulla vagy több karaktert tartalmaz; az azonosító és a lokalizált azonosító egy vagy több karakterből áll; attribútum-kulcsszó nem kis- és nagybetűérzékeny; és az attribútumérték is lehet kis-ezekre érzékeny. A kapcsolati karakterlánc és inicializációs fájl nyelvtan, kulcsszavak, lokalizált azonosítók és attribútumértékek miatt a []{}(),;? karaktereket tartalmazza. A *=!@ kerülni kell. A rendszer nyelvtana miatt a kulcsszavak és az adatforrások nem tartalmazhatják a visszaoldali (\) karaktert.

A böngészési eredmény kapcsolati karakterlánc szintaxisát a következő szemantikai szabályok szerint használják:

• Ha egy csillag (*) előzi meg egy attribútum-kulcsszót, az attribútum opcionális, és a következő SQLBrowseConnect hívásban kihagyható.

• Az UID és PWD attribútumkulcsszavak ugyanazt a jelentést kapják, mint az SQLDriverConnect-ben.

• Egy driver-determined-attribútum-kulcsszó megnevezi azt az attribútumtípust, amelyhez egy attribútumértéket megadhatnak. Például lehet SERVER, DATABASE, HOST vagy DBMS.

• Az ODBC-attribútum-kulcsszavak és az illesztővezető-definíciós-attribútum-kulcsszavak egy lokalizált vagy felhasználóbarát változatot tartalmaznak a kulcsszónak. Ezt az alkalmazások használhatják címkeként egy párbeszédablakban. Azonban az UID-t, a PWD-t vagy kizárólag az azonosítót kell használni, amikor böngészési kérelmek láncsort továbbítanak az illesztővezetőnek.

• Az {attribútum-értéklista} a megfelelő attribútum-kulcsszó érvényes tényleges értékeinek felsorolása. Fontos megjegyezni, hogy a fogszabályzók ({}) nem jelölnek választási listát; azokat a vezető adja vissza. Például lehet szervernevek listája vagy adatbázis-nevek listája.

• Ha az attribútum-érték egyetlen kérdőjel (?), akkor egyetlen érték felel meg az attribútum-kulcsszónak. Például UID=JohnS; PWD=Szezám.

• Minden SQLBrowseConnect-i hívás csak azt az információt adja vissza, amely a kapcsolati folyamat következő szintjének kielégítéséhez szükséges. Az illesztővezető állapotinformációt társít a kapcsolati fogantyúhoz, így a kontextus mindig meghatározható minden hívásnál.

SQLBrowseConnect használata

Az SQLBrowseConnect egy kijelölt kapcsolatot igényel. A Driver Manager betölti azt az illezőprogramot, amelyet az eredeti böngészési kérés kapcsolati karakterlánc megadott adatforrás névnek jelöltek vagy annak felelnek meg; ennek időpontjáról információért lásd az SQLConnect Function "Kommentek" szakaszát. Az illesztőprogram a böngészés során kapcsolatot teremthet az adatforrással. Ha az SQLBrowseConnect SQL_ERROR-t ad vissza, a fennálló kapcsolatok megszűnnek, és a kapcsolat visszakerül egy nem csatlakoztatott állapotba.

Amikor az SQLBrowseConnectet először hívják egy kapcsolaton, a böngészési kérés kapcsolati karakterlánc-nek tartalmaznia kell a DSN kulcsszót vagy a DRIVER kulcsszót. Ha a böngészési kérés kapcsolati karakterlánc tartalmazza a DSN kulcsszót, a Driver Manager a rendszerinformációban talál egy megfelelő adatforrás-specifikációt:

• Ha a Driver Manager megtalálja a megfelelő adatforrás-specifikációt, betölti a hozzá tartozó illegős DLL-t; Az illesztőprogram a rendszerinformációkból visszanyerheti az adatforrásról szóló információkat.

• Ha a Driver Manager nem találja meg a megfelelő adatforrás-specifikációt, megtalálja az alapértelmezett adatforrás-specifikációt, és betölti a hozzá tartozó illegős DLL-t; Az illesztőprogram a rendszerinformációkból visszanyerheti az alapértelmezett adatforrásról szóló információkat. "DEFAULT" a DSN illesztorának továbbítja.

• Ha a Driver Manager nem találja meg a megfelelő adatforrás-specifikációt, és nincs alapértelmezett adatforrás-specifikáció, akkor SQL_ERROR visszaadja az SQLSTATE IM002-vel (adatforrás nem talált, és nincs alapértelmezett illesztőprogram).

Ha a böngészési kérés kapcsolati karakterlánc tartalmazza a DRIVER kulcsszót, a Driver Manager betölti a megadott illezőprogramot; nem próbálja meg adatforrást találni a rendszerinformációban. Mivel a DRIVER kulcsszó nem használja a rendszer információiból, az illesztőnek elég kulcsszót kell definiálnia ahhoz, hogy az illezőmód csak a böngészési kérelmek kapcsolati láncsorainak információi alapján csatlakozhasson az adatforráshoz.

Minden SQLBrowseConnect-hívásnál az alkalmazás megadja a kapcsolati attribútumértékeket a böngészési kérelmek kapcsolati karakterlánc-ben. A meghajtó egymás utáni attribútum- és attribútum-értékeket ad vissza a böngészési eredményben, kapcsolati karakterlánc SQL_NEED_DATA adja, amennyiben vannak olyan kapcsolati attribútumok, amelyeket még nem soroltak fel a böngészési kérésben, kapcsolati karakterlánc. Az alkalmazás a browse result kapcsolati karakterlánc tartalmát használja a browse request kapcsolati karakterlánc létrehozásához a következő SQLBrowseConnect híváshoz. Minden kötelező attribútumot (amelyeket nem előzi meg csillag az OutConnectionString érvelésben) be kell foglalni a következő SQLBrowseConnect hívásban. Fontos megjegyezni, hogy az alkalmazás nem használhatja a korábbi böngészési eredmény kapcsolati stringek tartalmát a jelenlegi böngészési kérelmek kapcsolati karakterlánc építésekor; vagyis nem tud különböző értékeket megadni az előző szinteken beállított attribútumokra.

Amikor minden kapcsolati szintet és hozzájuk tartozó attribútumokat felsoroltak, az illesztőprogram SQL_SUCCESS-t ad, a kapcsolat az adatforráshoz teljes, és egy teljes kapcsolati karakterlánc érkezik az alkalmazáshoz. A kapcsolati karakterlánc alkalmas SQLDriverConnect-tel együtt, SQL_DRIVER_NOPROMPT opcióval egy másik kapcsolat létrehozására. A teljes kapcsolati karakterlánc azonban nem használható egy másik SQLBrowseConnect hívásban; ha az SQLBrowseConnectet újra hívják, az egész hívássorozatot meg kell ismételni.

Az SQLBrowseConnect SQL_NEED_DATA is visszaadja, ha a böngészés során helyreállítható, nem halálos hibák vannak; például egy érvénytelen jelszó vagy attribútumkulcsszó, amelyet az alkalmazás biztosít. Amikor SQL_NEED_DATA visszakerül, és a böngészési eredmény kapcsolati karakterlánc változatlan, hiba keletkezik, és az alkalmazás hívhatja az SQLGetDiagRec-et, hogy visszaadja az SQLSTATE-et a börgészési idő hibáira. Ez lehetővé teszi az alkalmazás számára, hogy javítsa az attribútumot és folytassa a böngészést.

Egy alkalmazás bármikor lezárhatja a böngészési folyamatot az SQLDisconnect hívásával. Az illesztővezető megszünteti a függőleges kapcsolatokat, és visszaállítja a kapcsolatot egy nem csatlakoztatott állapotba.

Ha aszinkron műveletek engedélyezve vannak a kapcsolati fogantyún, az SQLBrowseConnect szintén vissza SQL_STILL_EXECUTING visszaadhatja. Amikor SQL_NEED_DATA visszaad, az alkalmazásnak SQLDisconnectet kell használnia a böngészési folyamat megszüntetéséhez. Ha az SQLBrowseConnect SQL_STILL_EXECUTING visszaad, egy alkalmazásnak SQLCancelHandle segítségével kell törölnie a folyamatban lévő műveletet. Az SQLCancelHandle hívása a függvény SQL_NEED_DATA visszaadása után nem működik.

További információért lásd: Connecting with SQLBrowseConnect.

Ha egy illesztőprogram támogatja az SQLBrowseConnect-et, az illezőgép rendszerinformációinak kulcsszószekciójában tartalmaznia kell a ConnectFunctions kulcsszót, amelynek harmadik karaktere "Y" lesz.

Kódpélda

A következő példában egy alkalmazás ismételten hívja az SQLBrowseConnectet . Minden alkalommal, amikor az SQLBrowseConnect SQL_NEED_DATA visszaad, visszaadja az *OutConnectionString-ben az adatokat, amelyekre szüksége van. Az alkalmazás továbbítja az OutConnectionString-et a rutinjának, a GetUserInputnak (nincs megjelenítve). A GetUserInput elemzi az információkat, létrehoz és megjelenít egy párbeszédablakot, majd visszaadja a felhasználó által a *InConnectionString-be beírt információkat. Az alkalmazás a felhasználó adatait a következő SQLBrowseConnect hívásban továbbítja a drivernek. Miután az alkalmazás minden szükséges információt megadott az illesztőprogram adatforráshoz való csatlakozásához, az SQLBrowseConnect visszaadja SQL_SUCCESS, és az alkalmazás folytatja.

Részletesebb példát az SQL Server illesztőprogramhoz való csatlakozásra az SQLBrowseConnect hívásával lásd: az SQL Server böngészési példa.

Például, ha az Sales adatforráshoz csatlakozunk, a következő műveletek történhetnek. Először az alkalmazás a következő stringet továbbítja az SQLBrowseConnect-nek:

"DSN=Sales"  

A Driver Manager betölti az Értékesítéshez tartozó illesztőprogramot. Ezután ugyanazokkal az argumentumokkal hívja az illesztőprogram SQLBrowseConnect függvényét, mint amiket az alkalmazástól kapott. Az illezőprogram a következő stringet adja vissza az *OutConnectionString sorban:

"HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?"  

Az alkalmazás ezt a sort továbbítja a GetUserInput rutinnak, amely egy párbeszédablakot hoz létre, amelyben a felhasználónak a piros, kék vagy zöld szerver kiválasztását kéri, valamint felhasználóazonosítót és jelszót kell megadnia. A rutin a következő felhasználó által megadott információkat továbbítja vissza az *InConnectionString-ben, amelyeket az alkalmazás továbbít az SQLBrowseConnect-nek:

"HOST=red;UID=Smith;PWD=Sesame"  

Az SQLBrowseConnect ezt az információt használja arra, hogy csatlakozzon a piros szerverhez Smith néven a Sesame jelszóval, majd a következő stringet adja vissza az *OutConnectionString-ben:

"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"  

Az alkalmazás továbbítja ezt a stringet a GetUserInput rutinjába, amely egy párbeszédablakot hoz létre, amelyben a felhasználót arra kéri, hogy válasszon egy adatbázist. A felhasználó kiválasztja az empdata-t, és az alkalmazás végleg az SQLBrowseConnectet hívja ezzel a stringtel:

"DATABASE=SalesOrders"  

Ez az utolsó információ, amire a sofőrnek szüksége van az adatforráshoz való kapcsoláshoz; Az SQLBrowseConnect SQL_SUCCESS-t ad, és az *OutConnectionString tartalmazza a befejezett kapcsolati karakterlánc:

// SQLBrowseConnect_Function.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define BRWS_LEN 100  
SQLHENV henv;  
SQLHDBC hdbc;  
SQLHSTMT hstmt;  
SQLRETURN retcode;  
SQLCHAR szConnStrIn[BRWS_LEN], szConnStrOut[BRWS_LEN];  
SQLSMALLINT cbConnStrOut;  
  
void GetUserInput(SQLCHAR * szConnStrOut, SQLCHAR * szConnStrIn) {}  
  
int main() {  
   // Allocate the environment handle.  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);        
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
      // Set the version environment attribute.  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
         // Allocate the connection handle.  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            // Call SQLBrowseConnect until it returns a value other than SQL_NEED_DATA   
            // (pass data source name the first time).  If SQL_NEED_DATA is returned, call GetUserInput   
            // (not shown) to build a dialog from the values in szConnStrOut.  The user-supplied values   
            // are returned in szConnStrIn, which is passed in the next call to SQLBrowseConnect.  
  
            strcpy_s((char*)szConnStrIn, _countof(szConnStrIn), "DSN=Sales");  
            do {  
               retcode = SQLBrowseConnect(hdbc, szConnStrIn, SQL_NTS,  
                  szConnStrOut, BRWS_LEN, &cbConnStrOut);  
               if (retcode == SQL_NEED_DATA)  
                  GetUserInput(szConnStrOut, szConnStrIn);  
            } while (retcode == SQL_NEED_DATA);  
  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
               // Allocate the statement handle.  
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                  // Process data after successful connection  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               SQLDisconnect(hdbc);  
            }  
         }  
         SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      }  
   }  
   SQLFreeHandle(SQL_HANDLE_ENV, henv);  
}  

Kapcsolódó funkciók

Lásd még

ODBC API-referencia
ODBC-fejlécfájlok