SQLBrowseConnect-functie

Conformiteit
Versie geïntroduceerd: ODBC 1.0 Standaardnaleving: ODBC

Samenvatting
SQLBrowseConnect ondersteunt een iteratieve methode om de attributen en attribuutwaarden te ontdekken en op te sommen die nodig zijn om verbinding te maken met een databron. Elke aanroep naar SQLBrowseConnect levert opeenvolgende niveaus van attributen en attribuutwaarden terug. Wanneer alle niveaus zijn opgesomd, wordt een verbinding met de databron voltooid en wordt een volledige verbindingsreeks teruggegeven door SQLBrowseConnect. Een retourcode van SQL_SUCCESS of SQL_SUCCESS_WITH_INFO geeft aan dat alle verbindingsinformatie is opgegeven en dat de applicatie nu verbonden is met de databron.

Syntax

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

Arguments

ConnectionHandle
[Invoer] Verbindingsgreep.

InConnectionString
[Invoer] Blader door request verbindingsreeks (zie "InConnectionString Argument" in "Comments").

StringLength1
[Invoer] Lengte van *InConnectionString in tekens.

OutConnectionString
[Output] Wijs naar een tekenbuffer om de browseresultaat-verbindingsreeks terug te geven (zie "OutConnectionString Argument" in "Comments").

Als OutConnectionString NULL is, zal StringLength2Ptr nog steeds het totale aantal tekens teruggeven (exclusief het null-beëindigingsteken voor tekengegevens) dat beschikbaar is om terug te geven in de buffer waarnaar OutConnectionString wijst.

BufferLength
[Invoer] Lengte, in tekens, van de *OutConnectionString-buffer .

StringLength2Ptr
[Output] Het totale aantal tekens (exclusief null-termination) dat beschikbaar is om terug te geven in *OutConnectionString. Als het aantal beschikbare tekens groter is dan of gelijk aan BufferLength, wordt de verbindingsreeks in *OutConnectionString afgekapt tot BufferLength minus de lengte van een null-terminatiekarakter.

Returns

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

Diagnostics

Wanneer SQLBrowseConnect SQL_ERROR, SQL_SUCCESS_WITH_INFO of SQL_NEED_DATA teruggeeft, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec aan te roepen met een HandleType van SQL_HANDLE_STMT en een Handle van ConnectionHandle. De volgende tabel geeft een overzicht van de SQLSTATE-waarden die vaak door SQLBrowseConnect worden geretourneerd en legt elk uit in de context van deze functie; de notatie "(DM)" gaat vooraf aan de beschrijvingen van SQLSTATES die door de Driver Manager worden teruggegeven. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

InConnectionString-argument

Een browseverzoek-verbindingsreeks heeft de volgende syntaxis:

connection-string ::= attribuut[;] | Attribuut;verbindingsstring;
attribuut ::= attribuut-sleutelwoord=attribuut-waarde | DRIVER=[{]attribuut-waarde[}]
attribuut-sleutelwoord ::= DSN | | UID | PWDdriver-gedefinieerd-attribuut-sleutelwoord
attribuut-waarde ::= tekenstring
driver-gedefinieerd-attribuut-sleutelwoord ::= identificatie

waarbij de tekenreeks nul of meer tekens heeft; de identificatie heeft één of meer tekens; attribuut-sleutelwoord is niet hoofdlettergevoelig; attribuutwaarde kan hoofdlettergevoelig zijn; en de waarde van het DSN-sleutelwoord bestaat niet uitsluitend uit lege plekken. Vanwege de grammatica, trefwoorden en attribuutwaarden van verbindingsreeks en initialisatiebestanden, die de tekens []{}(),;? bevatten. *=!@ moet vermeden worden. Vanwege de grammatica in de systeeminformatie kunnen trefwoorden en databronnamen het backslash (\) teken niet bevatten. Voor een ODBC 2. x driver zijn er houvaste kramen nodig rond de attribuutwaarde van het DRIVER-sleutelwoord.

Als er zoekwoorden worden herhaald in de browseverzoek-verbindingsreeks, gebruikt de driver de waarde die hoort bij het eerste voorkomen van het sleutelwoord. Als de DSN- en DRIVER-trefwoorden in dezelfde browseverzoek-verbindingsreeks zijn opgenomen, gebruiken Driver Manager en driver het eerste trefwoord.

Voor informatie over hoe een applicatie een databron of driver kiest, zie Kies van een gegevensbron of driver.

OutConnectionString-argument

De browseresultaat-verbindingsreeks is een lijst van verbindingsattributen. Een verbindingsattribuut bestaat uit een attribuutsleutelwoord en een bijbehorende attribuutwaarde. De browse-resultaat-verbindingsreeks heeft de volgende syntaxis:

connection-string ::= attribuut[;] | Attribuut;verbindingsstring
attribuut ::= [*]attribuut-sleutelwoord=attribuut-waarde
attribuut-sleutelwoord ::= ODBC-attribuut-sleutelwoord | driver-gedefinieerd-attribuut-sleutelwoord
ODBC-attribuut-sleutelwoord = {UID | PWD}[:gelokaliseerde-identifier] driver-gedefinieerd-attribuut-sleutelwoord ::= identifier[:lokalized-identifier] attribuut-waarde ::= {attribuut-waarde-lijst} | ? (De haakjes zijn letterlijk; ze worden door de bestuurder teruggegeven.)
attribuut-waarde-lijst ::= tekenstring [:gelokaliseerde-tekenreeks] | tekenstring [:gelokaliseerde tekenreeks] ,attribuut-waarde-lijst

waarbij tekenstring en gelokaliseerde tekenstring nul of meer tekens hebben; identifier en localized-identifier hebben één of meer tekens; attribuut-sleutelwoord is niet hoofdlettergevoelig; en attribuutwaarde kan hoofdlettergevoelig zijn. Vanwege de grammatica van verbindingsreeks en initialisatiebestand, trefwoorden, gelokaliseerde identificaties en attribuutwaarden die de tekens []{}(),;? bevatten. *=!@ moet vermeden worden. Vanwege de grammatica in de systeeminformatie kunnen trefwoorden en databronnamen het backslash (\) teken niet bevatten.

De syntaxis van de browse-resultaat verbindingsreeks wordt gebruikt volgens de volgende semantische regels:

• Als een asterisk (*) voorafgaat aan een attribuut-sleutelwoord, is het attribuut optioneel en kan het worden weggelaten bij de volgende aanroep naar SQLBrowseConnect.

• De attribuut-trefwoorden UID en PWD hebben dezelfde betekenis als gedefinieerd in SQLDriverConnect.

• Een driver-gedefinieerd-attribuut-sleutelwoord noemt het type attribuut waarvoor een attribuutwaarde kan worden opgegeven. Bijvoorbeeld, het kan SERVER,DATABASE, HOST of DBMS zijn.

• ODBC-attribuut-sleutelwoorden en driver-gedefinieerde-attribuut-sleutelwoorden bevatten een gelokaliseerde of gebruiksvriendelijke versie van het trefwoord. Dit kan door applicaties als label in een dialoogvenster worden gebruikt. UID, PWD of alleen de identifier moet echter worden gebruikt bij het doorgeven van een browse-verzoekstring aan de driver.

• De {attribuut-waarde-lijst} is een opsomming van werkelijke waarden die geldig zijn voor het bijbehorende attribuut-sleutelwoord. Let op dat de beugels ({}) geen lijst met keuzes aangeven; ze worden teruggegeven door de bestuurder. Bijvoorbeeld, het kan een lijst met servernamen zijn of een lijst met databasenamen.

• Als de attribuutwaarde een enkel vraagteken is (?), komt een enkele waarde overeen met het attribuut-sleutelwoord. Bijvoorbeeld, UID=JohnS; PWD=Sesam.

• Elke aanroep naar SQLBrowseConnect levert alleen de informatie terug die nodig is om aan het volgende niveau van het verbindingsproces te voldoen. De driver koppelt toestandsinformatie aan de verbindingshandle zodat de context altijd bij elke oproep kan worden bepaald.

Gebruik van SQLBrowseConnect

SQLBrowseConnect vereist een toegewezen verbinding. De Driver Manager laadt de driver die is gespecificeerd in of die overeenkomt met de naam van de gegevensbron die is vermeld in de initiële browseverzoek-verbindingsreeks; voor informatie over wanneer dit gebeurt, zie de sectie "Comments" in de SQLConnect Function. De driver kan tijdens het browsen een verbinding met de databron opbouwen. Als SQLBrowseConnect SQL_ERROR terugkeert, worden openstaande verbindingen beëindigd en wordt de verbinding teruggebracht naar een niet-verbonden toestand.

Wanneer SQLBrowseConnect voor het eerst wordt aangeroepen tijdens een verbinding, moet de browseverzoek-verbindingsreeks het DSN-sleutelwoord of het DRIVER-sleutelwoord bevatten. Als de browseverzoek-verbindingsreeks het DSN-sleutelwoord bevat, vindt de Driver Manager een overeenkomstige gegevensbronspecificatie in de systeeminformatie:

• Als de Driver Manager de bijbehorende databronspecificatie vindt, laadt hij de bijbehorende driver DLL; De driver kan informatie over de databron ophalen uit de systeeminformatie.

• Als de Driver Manager de bijbehorende gegevensbronspecificatie niet kan vinden, zoekt hij de standaard gegevensbronspecificatie op en laadt de bijbehorende driver-DLL; De driver kan informatie over de standaardgegevensbron uit de systeeminformatie ophalen. "DEFAULT" wordt doorgegeven aan de bestuurder voor het DSN.

• Als de Driver Manager de bijbehorende gegevensbronspecificatie niet kan vinden en er geen standaard databronspecificatie is, geeft hij SQL_ERROR terug met SQLSTATE IM002 (Gegevensbron niet gevonden en geen standaard driver gespecificeerd).

Als de browse request verbindingsreeks het sleutelwoord DRIVER bevat, laadt de Driver Manager de gespecificeerde driver; hij probeert geen databron in de systeeminformatie te vinden. Omdat het DRIVER-sleutelwoord geen informatie uit de systeeminformatie gebruikt, moet de driver voldoende trefwoorden definiëren zodat een driver verbinding kan maken met een databron die alleen de informatie uit de browseverzoek-verbindingsstrings gebruikt.

Bij elke aanroep naar SQLBrowseConnect specificeert de applicatie de verbindingsattributen in de browseverzoek-verbindingsreeks. De driver geeft opeenvolgende niveaus van attributen en attribuutwaarden terug in het browseresultaat verbindingsreeks; hij geeft SQL_NEED_DATA terug zolang er verbindingsattributen zijn die nog niet zijn opgesomd in het browseverzoek verbindingsreeks. De applicatie gebruikt de inhoud van de browseresultaat-verbindingsreeks om de browse-verzoek-verbindingsreeks te bouwen voor de volgende aanroep naar SQLBrowseConnect. Alle verplichte attributen (die niet voorafgegaan worden door een asterisk in het OutConnectionString-argument ) moeten worden opgenomen in de volgende aanroep naar SQLBrowseConnect. Let op dat de applicatie de inhoud van eerdere browse-resultaatverbindingsstrings niet kan gebruiken bij het bouwen van de huidige browse request verbindingsreeks; dat wil zeggen, het kan geen verschillende waarden specificeren voor attributen die in eerdere niveaus zijn ingesteld.

Wanneer alle verbindingsniveaus en hun bijbehorende attributen zijn opgesomd, retourneert de driver SQL_SUCCESS, is de verbinding met de databron voltooid en wordt een volledige verbindingsreeks teruggegeven aan de applicatie. De verbindingsreeks is geschikt om te gebruiken, in combinatie met SQLDriverConnect, met de SQL_DRIVER_NOPROMPT optie om een andere verbinding te maken. De volledige verbindingsreeks kan echter niet worden gebruikt in een andere aanroep naar SQLBrowseConnect; als SQLBrowseConnect opnieuw wordt aangeroepen, moet de volledige reeks aanroepen worden herhaald.

SQLBrowseConnect geeft ook SQL_NEED_DATA terug als er herstelbare, niet-fatale fouten zijn tijdens het browseproces; bijvoorbeeld een ongeldig wachtwoord of attribuutsleutelwoord dat door de applicatie wordt opgegeven. Wanneer SQL_NEED_DATA wordt teruggegeven en het browseresultaat verbindingsreeks ongewijzigd blijft, is er een fout opgetreden en kan de applicatie SQLGetDiagRec aanroepen om de SQLSTATE terug te geven voor browse-time fouten. Dit stelt de applicatie in staat het attribuut te corrigeren en het browsen voort te zetten.

Een applicatie kan het browseproces op elk moment beëindigen door SQLDisconnect aan te roepen. De driver beëindigt alle openstaande verbindingen en brengt de verbinding terug naar een niet-verbonden toestand.

Als asynchrone bewerkingen op de verbindingshandle zijn ingeschakeld, kan SQLBrowseConnect ook SQL_STILL_EXECUTING teruggeven. Wanneer het SQL_NEED_DATA terugkeert, moet een applicatie SQLDisconnect gebruiken om het browseproces te annuleren. Als SQLBrowseConnect SQL_STILL_EXECUTING terugkeert, moet een applicatie SQLCancelHandle gebruiken om de lopende bewerking te annuleren. Het aanroepen van SQLCancelHandle nadat de functie SQL_NEED_DATA teruggeeft, heeft geen effect.

Voor meer informatie, zie Verbinden met SQLBrowseConnect.

Als een driver SQLBrowseConnect ondersteunt, moet het driversleutelwoord in de systeeminformatie van de driver het ConnectFunctions-sleutelwoord bevatten met het derde teken op "Y."

Codevoorbeeld

In het volgende voorbeeld roept een applicatie herhaaldelijk SQLBrowseConnect aan. Elke keer dat SQLBrowseConnect SQL_NEED_DATA terugkeert, geeft het informatie over de benodigde data terug in *OutConnectionString. De applicatie geeft OutConnectionString door aan zijn routine GetUserInput (niet getoond). GetUserInput ontleedt de informatie, bouwt en toont een dialoogvenster, en geeft de informatie terug die de gebruiker in *InConnectionString heeft ingevoerd. De applicatie geeft de gebruikersinformatie door aan de driver in de volgende aanroep naar SQLBrowseConnect. Nadat de applicatie alle benodigde informatie heeft verstrekt zodat de driver verbinding kan maken met de databron, keert SQLBrowseConnect SQL_SUCCESS terug en gaat de applicatie verder.

Voor een gedetailleerder voorbeeld van het verbinden met een SQL Server-driver door SQLBrowseConnect aan te roepen, zie SQL Server Browsing Voorbeeld.

Om bijvoorbeeld verbinding te maken met de databron Sales, kunnen de volgende acties plaatsvinden. Eerst geeft de applicatie de volgende string door aan SQLBrowseConnect:

"DSN=Sales"  

De Driver Manager laadt de driver die is gekoppeld aan de databron Sales. Vervolgens roept het de SQLBrowseConnect-functie van de driver aan met dezelfde argumenten die het van de applicatie heeft ontvangen. De driver geeft de volgende string terug in *OutConnectionString:

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

De applicatie geeft deze string door aan zijn GetUserInput-routine , die een dialoogvenster opstelt waarin de gebruiker wordt gevraagd de rode, blauwe of groene server te selecteren en een gebruikers-ID en wachtwoord in te voeren. De routine geeft de volgende door de gebruiker opgegeven informatie terug naar *InConnectionString, die de applicatie doorgeeft aan SQLBrowseConnect:

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

SQLBrowseConnect gebruikt deze informatie om als Smith met het wachtwoord Sesame verbinding te maken met de rode server, en geeft vervolgens de volgende string terug in *OutConnectionString:

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

De applicatie geeft deze string door aan zijn GetUserInput-routine , die een dialoogvenster opbouwt waarin de gebruiker wordt gevraagd een database te selecteren. De gebruiker selecteert empdata en de applicatie roept SQLBrowseConnect voor de laatste keer aan met deze string:

"DATABASE=SalesOrders"  

Dit is het laatste stukje informatie dat de driver nodig heeft om aan de databron te koppelen; SQLBrowseConnect geeft SQL_SUCCESS terug, en *OutConnectionString bevat de voltooide verbindingsreeks:

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

Gerelateerde functies

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden