Funzione SQLBrowseConnect

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ODBC

Riepilogo
SQLBrowseConnect supporta un metodo iterativo per individuare ed enumerare gli attributi e i valori degli attributi necessari per connettersi a un'origine dati. Ogni chiamata a SQLBrowseConnect restituisce livelli successivi di attributi e valori di attributo. Quando tutti i livelli sono stati enumerati, viene completata una connessione all'origine dati e viene restituita una stringa di connessione completa da SQLBrowseConnect. Un codice restituito di SQL_SUCCESS o SQL_SUCCESS_WITH_INFO indica che tutte le informazioni di connessione sono state specificate e l'applicazione è ora connessa all'origine dati.

Sintassi

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

Argomenti

ConnectionHandle
[Input] Handle di connessione.

InConnectionString
[Input] Sfogliare stringa di connessione richiesta (vedere "Argomento InConnectionString" in "Comments").

StringLength1
[Input] Lunghezza di *InConnectionString in caratteri.

OutConnectionString
[Output] Puntatore a un buffer di caratteri in cui restituire il risultato di esplorazione stringa di connessione (vedere "OutConnectionString Argument" in "Comments").

Se OutConnectionString è NULL, StringLength2Ptr restituirà comunque il numero totale di caratteri (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta OutConnectionString.

BufferLength
[Input] Lunghezza, in caratteri, del buffer *OutConnectionString .

StringLength2Ptr
[Output] Numero totale di caratteri (escluso terminazione null) disponibile per la restituzione in *OutConnectionString. Se il numero di caratteri disponibili per la restituzione è maggiore o uguale a BufferLength, il stringa di connessione in *OutConnectionString viene troncato a BufferLength meno la lunghezza di un carattere di terminazione Null.

Valori restituiti

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

Diagnostica

Quando SQLBrowseConnect restituisce SQL_ERROR, SQL_SUCCESS_WITH_INFO o SQL_NEED_DATA, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleType di SQL_HANDLE_STMT e handle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLBrowseConnect e spiega ognuno di essi nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Argomento InConnectionString

Una richiesta di esplorazione stringa di connessione ha la sintassi seguente:

connection-string ::= attribute[;] | attributo ; stringa di connessione;
attribute ::= attribute-keyword=attribute-valueDRIVER= | [{]attribute-value[}]
attribute-keyword ::= DSNPWD | UID | | driver-defined-attribute-keyword
attribute-value ::= character-string
identificatore driver-defined-attribute-keyword ::=

dove la stringa di caratteri ha zero o più caratteri; l'identificatore ha uno o più caratteri; attribute-keyword non fa distinzione tra maiuscole e minuscole; attribute-value può fare distinzione tra maiuscole e minuscole e il valore della parola chiave DSN non è costituito esclusivamente da spazi vuoti. A causa di stringa di connessione e la grammatica dei file di inizializzazione, parole chiave e valori di attributo che contengono i caratteri []{}(),;? *=!@ deve essere evitato. A causa della grammatica nelle informazioni di sistema, le parole chiave e i nomi delle origini dati non possono contenere il carattere barra rovesciata (\). Per odbc 2.X driver, le parentesi graffe sono necessarie intorno al valore dell'attributo per la parola chiave DRIVER.

Se nella richiesta di esplorazione stringa di connessione vengono ripetute parole chiave, il driver usa il valore associato alla prima occorrenza della parola chiave. Se le parole chiave DSN e DRIVER sono incluse nella stessa richiesta di esplorazione stringa di connessione, gestione driver e driver usano la parola chiave che viene visualizzata per prima.

Per informazioni su come un'applicazione sceglie un'origine dati o un driver, vedere Scelta di un'origine dati o di un driver.

Argomento OutConnectionString

Il risultato di esplorazione stringa di connessione è un elenco di attributi di connessione. Un attributo di connessione è costituito da una parola chiave attribute e da un valore di attributo corrispondente. Il risultato di esplorazione stringa di connessione ha la sintassi seguente:

connection-string ::= attribute[;] | attributo ; connection-string
attribute ::= [*]attribute-keyword=attribute-value
attribute-keyword ::= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = {UIDPWD | }[:localized-identifier] driver-defined-attribute-keyword ::= identifier[:localized-identifier] attribute-value ::= { attribute-value-list | }? (le parentesi graffe sono letterali; vengono restituite dal driver).
attribute-value-list ::= character-string [:stringa di caratteri localizzata] | character-string [:localized-character string] , attribute-value-list

dove la stringa di caratteri e la stringa di caratteri localizzati hanno zero o più caratteri; identificatore e identificatore localizzato hanno uno o più caratteri; attribute-keyword non fa distinzione tra maiuscole e minuscole e attribute-value può fare distinzione tra maiuscole e minuscole. A causa di stringa di connessione e la grammatica dei file di inizializzazione, parole chiave, identificatori localizzati e valori di attributo che contengono i caratteri []{}(),;? *=!@ deve essere evitato. A causa della grammatica nelle informazioni di sistema, le parole chiave e i nomi delle origini dati non possono contenere il carattere barra rovesciata (\).

Il risultato di esplorazione stringa di connessione sintassi viene usata in base alle regole semantiche seguenti:

• Se un asterisco (*) precede una parola chiave attribute, l'attributo è facoltativo e può essere omesso nella chiamata successiva a SQLBrowseConnect.

• Le parole chiave dell'attributo UID e PWD hanno lo stesso significato definito in SQLDriverConnect.

• Un driver-defined-attribute-keyword assegna un nome al tipo di attributo per il quale è possibile specificare un valore di attributo. Ad esempio, potrebbe trattarsi di SERVER, DATABASE, HOST o DBMS.

• ODBC-attribute-keywords e driver-defined-attribute-keywords includono una versione localizzata o intuitiva della parola chiave. Può essere usato dalle applicazioni come etichetta in una finestra di dialogo. Tuttavia, è necessario usare solo UID, PWD o l'identificatore quando si passa una stringa di richiesta di esplorazione al driver.

• {attribute-value-list} è un'enumerazione dei valori effettivi validi per la parola chiave attribute-keyword corrispondente. Si noti che le parentesi graffe ({}) non indicano un elenco di scelte, ma vengono restituite dal driver. Ad esempio, potrebbe trattarsi di un elenco di nomi di server o di un elenco di nomi di database.

• Se il valore dell'attributo è un singolo punto interrogativo (?), un singolo valore corrisponde alla parola chiave attribute. Ad esempio, UID=JohnS; PWD=Sesame.

• Ogni chiamata a SQLBrowseConnect restituisce solo le informazioni necessarie per soddisfare il livello successivo del processo di connessione. Il driver associa le informazioni sullo stato all'handle di connessione in modo che il contesto possa essere sempre determinato in ogni chiamata.

Uso di SQLBrowseConnect

SQLBrowseConnect richiede una connessione allocata. Gestione driver carica il driver specificato in o che corrisponde al nome dell'origine dati specificato nella richiesta di esplorazione iniziale stringa di connessione. Per informazioni su quando si verifica questa situazione, vedere la sezione "Commenti" in Funzione SQLConnect. Il driver può stabilire una connessione con l'origine dati durante il processo di esplorazione. Se SQLBrowseConnect restituisce SQL_ERROR, le connessioni in sospeso vengono terminate e la connessione viene restituita a uno stato non connesso.

Quando SQLBrowseConnect viene chiamato per la prima volta in una connessione, la richiesta di esplorazione stringa di connessione deve contenere la parola chiave DSN o la parola chiave DRIVER. Se la richiesta di esplorazione stringa di connessione contiene la parola chiave DSN, Gestione driver individua una specifica dell'origine dati corrispondente nelle informazioni di sistema:

• Se Gestione driver trova la specifica dell'origine dati corrispondente, carica la DLL del driver associata; il driver può recuperare informazioni sull'origine dati dalle informazioni di sistema.

• Se Gestione driver non riesce a trovare la specifica dell'origine dati corrispondente, individua la specifica dell'origine dati predefinita e carica la DLL del driver associata; il driver può recuperare informazioni sull'origine dati predefinita dalle informazioni di sistema. "DEFAULT" viene passato al driver per il DSN.

• Se Gestione driver non riesce a trovare la specifica dell'origine dati corrispondente e non esiste alcuna specifica dell'origine dati predefinita, restituisce SQL_ERROR con SQLSTATE IM002 (origine dati non trovata e nessun driver predefinito specificato).

Se la richiesta di esplorazione stringa di connessione contiene la parola chiave DRIVER, Gestione driver carica il driver specificato. Non tenta di individuare un'origine dati nelle informazioni di sistema. Poiché la parola chiave DRIVER non usa informazioni dalle informazioni di sistema, il driver deve definire parole chiave sufficienti in modo che un driver possa connettersi a un'origine dati usando solo le informazioni contenute nelle stringa di connessione di richiesta di esplorazione.

In ogni chiamata a SQLBrowseConnect, l'applicazione specifica i valori dell'attributo di connessione nella richiesta di esplorazione stringa di connessione. Il driver restituisce livelli successivi di attributi e valori di attributo nel stringa di connessione dei risultati di esplorazione. Restituisce SQL_NEED_DATA purché nella richiesta di esplorazione stringa di connessione non siano ancora stati enumerati attributi di connessione. L'applicazione usa il contenuto del risultato di esplorazione stringa di connessione per compilare la richiesta di esplorazione stringa di connessione per la chiamata successiva a SQLBrowseConnect. Tutti gli attributi obbligatori (quelli non preceduti da un asterisco nell'argomento OutConnectionString ) devono essere inclusi nella chiamata successiva a SQLBrowseConnect. Si noti che l'applicazione non può usare il contenuto dei risultati di esplorazione precedenti stringa di connessione durante la compilazione della richiesta di esplorazione corrente stringa di connessione, ovvero non può specificare valori diversi per gli attributi impostati nei livelli precedenti.

Quando tutti i livelli di connessione e i relativi attributi associati sono stati enumerati, il driver restituisce SQL_SUCCESS, la connessione all'origine dati è completa e viene restituita una stringa di connessione completa all'applicazione. Il stringa di connessione è adatto per l'uso, insieme a SQLDriverConnect, con l'opzione SQL_DRIVER_NOPROMPT per stabilire un'altra connessione. Il stringa di connessione completo non può essere usato in un'altra chiamata a SQLBrowseConnect, ma se SQLBrowseConnect è stato chiamato di nuovo, l'intera sequenza di chiamate dovrà essere ripetuta.

SQLBrowseConnect restituisce anche SQL_NEED_DATA se sono presenti errori ripristinabili e non irreversibili durante il processo di esplorazione, ad esempio una password o una parola chiave di attributo non valida fornita dall'applicazione. Quando viene restituito SQL_NEED_DATA e il risultato di esplorazione stringa di connessione è invariato, si è verificato un errore e l'applicazione può chiamare SQLGetDiagRec per restituire SQLSTATE per gli errori in fase di esplorazione. In questo modo l'applicazione può correggere l'attributo e continuare l'esplorazione.

Un'applicazione può terminare il processo di esplorazione in qualsiasi momento chiamando SQLDisconnect. Il driver terminerà tutte le connessioni in sospeso e restituirà la connessione a uno stato non connesso.

Se le operazioni asincrone sono abilitate nell'handle di connessione, SQLBrowseConnect potrebbe restituire anche SQL_STILL_EXECUTING. Quando restituisce SQL_NEED_DATA, un'applicazione deve usare SQLDisconnect per annullare il processo di esplorazione. Se SQLBrowseConnect restituisce SQL_STILL_EXECUTING, un'applicazione deve usare SQLCancelHandle per annullare l'operazione in corso. La chiamata a SQLCancelHandle dopo che la funzione restituisce SQL_NEED_DATA non ha alcun effetto.

Per altre informazioni, vedere Connessione con SQLBrowseConnect.

Se un driver supporta SQLBrowseConnect, la sezione della parola chiave driver nelle informazioni di sistema per il driver deve contenere la parola chiave ConnectFunctions con il terzo set di caratteri su "Y".

Esempio di codice

Nell'esempio seguente un'applicazione chiama ripetutamente SQLBrowseConnect . Ogni volta che SQLBrowseConnect restituisce SQL_NEED_DATA, restituisce informazioni sui dati necessari in *OutConnectionString. L'applicazione passa OutConnectionString alla routine GetUserInput (non visualizzata). GetUserInput analizza le informazioni, compila e visualizza una finestra di dialogo e restituisce le informazioni immesse dall'utente in *InConnectionString. L'applicazione passa le informazioni dell'utente al driver nella chiamata successiva a SQLBrowseConnect. Dopo che l'applicazione ha fornito tutte le informazioni necessarie per la connessione del driver all'origine dati, SQLBrowseConnect restituisce SQL_SUCCESS e l'applicazione procede.

Per un esempio più dettagliato di connessione a un driver di SQL Server chiamando SQLBrowseConnect, vedere Esempio di esplorazione di SQL Server.

Ad esempio, per connettersi all'origine dati Sales, potrebbero verificarsi le azioni seguenti. Prima di tutto, l'applicazione passa la stringa seguente a SQLBrowseConnect:

"DSN=Sales"  

Gestione driver carica il driver associato all'origine dati Sales. Chiama quindi la funzione SQLBrowseConnect del driver con gli stessi argomenti ricevuti dall'applicazione. Il driver restituisce la stringa seguente in *OutConnectionString:

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

L'applicazione passa questa stringa alla routine GetUserInput , che crea una finestra di dialogo che chiede all'utente di selezionare il server rosso, blu o verde e di immettere un ID utente e una password. La routine passa di nuovo le informazioni specificate dall'utente seguenti in *InConnectionString, che l'applicazione passa a SQLBrowseConnect:

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

SQLBrowseConnect usa queste informazioni per connettersi al server rosso come Smith con la password Sesame e quindi restituisce la stringa seguente in *OutConnectionString:

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

L'applicazione passa questa stringa alla routine GetUserInput , che compila una finestra di dialogo che chiede all'utente di selezionare un database. L'utente seleziona empdata e l'applicazione chiama SQLBrowseConnetti un'ora finale con questa stringa:

"DATABASE=SalesOrders"  

Questa è la parte finale di informazioni che il driver deve connettersi all'origine dati; SQLBrowseConnect restituisce SQL_SUCCESS e *OutConnectionString contiene il stringa di connessione completato:

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

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC