Função SQLBrowseConnect

Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ODBC

Resumo
O SQLBrowseConnect dá suporte a um método iterativo de descoberta e enumeração dos atributos e valores de atributo necessários para se conectar a uma fonte de dados. Cada chamada para SQLBrowseConnect retorna níveis sucessivos de atributos e valores de atributo. Quando todos os níveis tiverem sido enumerados, uma conexão com a fonte de dados será concluída e uma cadeia de conexão completa será retornada por SQLBrowseConnect. Um código de retorno de SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO indica que todas as informações de conexão foram especificadas e o aplicativo agora está conectado à fonte de dados.

Sintaxe

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

Argumentos

Identificador de conexão
[Entrada] Identificador de conexão.

InConnectionString
[Entrada] Procure a cadeia de conexão de solicitação (consulte "Argumento InConnectionString " em "Comentários").

StringLength1
[Entrada] Comprimento de *InConnectionString em caracteres.

Cadeia de Conexão Externa
[Saída] Ponteiro para um buffer de caracteres no qual retornar a cadeia de conexão do resultado da navegação (consulte "Argumento OutConnectionString " em "Comentários").

Se OutConnectionString for NULL, StringLength2Ptr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caractere) disponíveis para retornar no buffer apontado por OutConnectionString.

BufferLength
[Entrada] Comprimento, em caracteres, do buffer *OutConnectionString .

Comprimento da cadeia de caracteres2Ptr
[Saída] O número total de caracteres (excluindo terminação nula) disponíveis para retornar em *OutConnectionString. Se o número de caracteres disponíveis para retorno for maior ou igual a BufferLength, a cadeia de conexão em *OutConnectionString será truncada para BufferLength menos o comprimento de um caractere de terminação nula.

Devoluções

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

Diagnósticos

Quando SQLBrowseConnect retorna SQL_ERROR, SQL_SUCCESS_WITH_INFO ou SQL_NEED_DATA, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de ConnectionHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados por SQLBrowseConnect e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

Argumento InConnectionString

Uma cadeia de conexão de solicitação de navegação tem a seguinte sintaxe:

cadeia de conexão ::= atributo [;] | cadeia de conexão de atributo;;
atributo ::= atributo-palavra-chave=atributo-valor | DRIVER=[{]atributo-valor[]}
palavra-chave de atributo ::=PWD | DSNUID | | palavra-chave de atributo definida pelo driver
valor do atributo ::= cadeia de caracteres
palavra-chave de atributo definida pelo driver ::= identificador

onde a cadeia de caracteres tem zero ou mais caracteres; identificador tem um ou mais caracteres; attribute-keyword não diferencia maiúsculas de minúsculas; attribute-value pode diferenciar maiúsculas de minúsculas; e o valor da palavra-chave DSN não consiste apenas em espaços em branco. Devido à cadeia de conexão e à gramática do arquivo de inicialização, palavras-chave e valores de atributo que contêm os caracteres []{}(),;? *=!@ deve ser evitado. Devido à gramática nas informações do sistema, as palavras-chave e os nomes das fontes de dados não podem conter o caractere de barra invertida (\). Para um ODBC 2.x driver, as chaves são necessárias em torno do valor do atributo para a palavra-chave DRIVER.

Se alguma palavra-chave for repetida na cadeia de conexão de solicitação de navegação, o driver usará o valor associado à primeira ocorrência da palavra-chave. Se as palavras-chave DSN e DRIVER estiverem incluídas na mesma cadeia de conexão de solicitação de navegação, o Gerenciador de Driver e o driver usarão a palavra-chave que aparecer primeiro.

Para obter informações sobre como um aplicativo escolhe uma fonte de dados ou um driver, consulte Escolhendo uma fonte de dados ou um driver.

Argumento OutConnectionString

A cadeia de conexão do resultado da procura é uma lista de atributos de conexão. Um atributo de conexão consiste em uma palavra-chave de atributo e um valor de atributo correspondente. A cadeia de conexão do resultado da navegação tem a seguinte sintaxe:

cadeia de conexão ::= atributo [;] | cadeia de conexão de atributo ;
atributo ::= [*]atributo-palavra-chave=atributo-valor
palavra-chave de atributo ::= palavra-chave de atributo ODBC palavra-chave | de atributo definida pelo driver
ODBC-attribute-keyword = {UID | PWD}[:identificador-localizado] palavra-chave-de-atributo-definido pelo driver ::= identificador[:identificador-localizado] valor-do-atributo ::= { lista } | ? de valores-de-atributo (As chaves são literais; elas são retornadas pelo driver.)
lista de valores de atributo ::= cadeia de caracteres [:cadeia de caracteres localizada] | cadeia de caracteres [:cadeia de caracteres localizada] , lista de valores de atributos

em que a cadeia de caracteres e a cadeia de caracteres localizada têm zero ou mais caracteres; identifier e localized-identifier têm um ou mais caracteres; attribute-keyword não diferencia maiúsculas de minúsculas; e attribute-value pode diferenciar maiúsculas de minúsculas. Devido à cadeia de conexão e à gramática do arquivo de inicialização, palavras-chave, identificadores localizados e valores de atributo que contêm os caracteres []{}(),;? *=!@ deve ser evitado. Devido à gramática nas informações do sistema, as palavras-chave e os nomes das fontes de dados não podem conter o caractere de barra invertida (\).

A sintaxe da cadeia de conexão do resultado da navegação é usada de acordo com as seguintes regras semânticas:

• Se um asterisco (*) preceder uma palavra-chave de atributo, o atributo será opcional e poderá ser omitido na próxima chamada para SQLBrowseConnect.

• As palavras-chave de atributo UID e PWD têm o mesmo significado definido em SQLDriverConnect.

• Uma palavra-chave driver-defined-attribute-name Por exemplo, pode ser SERVER, DATABASE, HOST ou DBMS.

• ODBC-attribute-keywords e driver-defined-attribute-keywords incluem uma versão localizada ou amigável da palavra-chave. Isso pode ser usado por aplicativos como um rótulo em uma caixa de diálogo. No entanto, UID, PWD ou o identificador sozinho devem ser usados ao passar uma cadeia de caracteres de solicitação de navegação para o driver.

• O {attribute-value-list} é uma enumeração de valores reais válidos para a palavra-chave de atributo correspondente. Observe que as chaves ({}) não indicam uma lista de opções; elas são retornadas pelo driver. Por exemplo, pode ser uma lista de nomes de servidor ou uma lista de nomes de banco de dados.

• Se o valor do atributo for um único ponto de interrogação (?), um único valor corresponderá à palavra-chave do atributo. Por exemplo, UID=JohnS; PWD = Gergelim.

• Cada chamada para SQLBrowseConnect retorna apenas as informações necessárias para satisfazer o próximo nível do processo de conexão. O driver associa informações de estado ao identificador de conexão para que o contexto sempre possa ser determinado em cada chamada.

Usando SQLBrowseConnect

SQLBrowseConnect requer uma conexão alocada. O Gerenciador de Driver carrega o driver que foi especificado ou que corresponde ao nome da fonte de dados especificado na cadeia de conexão de solicitação de navegação inicial; para obter informações sobre quando isso ocorre, consulte a seção "Comentários" na função SQLConnect. O driver pode estabelecer uma conexão com a fonte de dados durante o processo de navegação. Se SQLBrowseConnect retornar SQL_ERROR, as conexões pendentes serão encerradas e a conexão será retornada a um estado desconectado.

Quando SQLBrowseConnect é chamado pela primeira vez em uma conexão, a cadeia de conexão da solicitação de navegação deve conter a palavra-chave DSN ou a palavra-chave DRIVER . Se a cadeia de conexão da solicitação de navegação contiver a palavra-chave DSN , o Gerenciador de Driver localizará uma especificação de fonte de dados correspondente nas informações do sistema:

• Se o Gerenciador de Driver encontrar a especificação de fonte de dados correspondente, ele carregará a DLL do driver associada; O driver pode recuperar informações sobre a fonte de dados das informações do sistema.

• Se o Gerenciador de Driver não puder encontrar a especificação de fonte de dados correspondente, ele localizará a especificação de fonte de dados padrão e carregará a DLL do driver associada; O driver pode recuperar informações sobre a fonte de dados padrão das informações do sistema. "DEFAULT" é passado para o driver do DSN.

• Se o Gerenciador de Driver não puder encontrar a especificação de fonte de dados correspondente e não houver nenhuma especificação de fonte de dados padrão, ele retornará SQL_ERROR com SQLSTATE IM002 (fonte de dados não encontrada e nenhum driver padrão especificado).

Se a cadeia de conexão de solicitação de navegação contiver a palavra-chave DRIVER , o Gerenciador de Driver carregará o driver especificado; ele não tentará localizar uma fonte de dados nas informações do sistema. Como a palavra-chave DRIVER não usa informações das informações do sistema, o driver deve definir palavras-chave suficientes para que um driver possa se conectar a uma fonte de dados usando apenas as informações nas cadeias de conexão da solicitação de navegação.

Em cada chamada para SQLBrowseConnect, o aplicativo especifica os valores de atributo de conexão na cadeia de conexão da solicitação de navegação. O driver retorna níveis sucessivos de atributos e valores de atributo na cadeia de conexão de resultado de procura; Ele retorna SQL_NEED_DATA desde que haja atributos de conexão que ainda não foram enumerados na cadeia de conexão da solicitação de navegação. O aplicativo usa o conteúdo da cadeia de conexão de resultado de procura para criar a cadeia de conexão de solicitação de navegação para a próxima chamada para SQLBrowseConnect. Todos os atributos obrigatórios (aqueles não precedidos por um asterisco no argumento OutConnectionString ) devem ser incluídos na próxima chamada para SQLBrowseConnect. Observe que o aplicativo não pode usar o conteúdo das cadeias de conexão de resultado de navegação anteriores ao criar a cadeia de conexão de solicitação de navegação atual; ou seja, não pode especificar valores diferentes para atributos definidos em níveis anteriores.

Quando todos os níveis de conexão e seus atributos associados tiverem sido enumerados, o driver retornará SQL_SUCCESS, a conexão com a fonte de dados será concluída e uma cadeia de conexão completa será retornada ao aplicativo. A cadeia de conexão é adequada para uso, em conjunto com SQLDriverConnect, com a opção SQL_DRIVER_NOPROMPT para estabelecer outra conexão. No entanto, a cadeia de conexão completa não pode ser usada em outra chamada para SQLBrowseConnect; se SQLBrowseConnect fosse chamado novamente, toda a sequência de chamadas teria que ser repetida.

O SQLBrowseConnect também retorna SQL_NEED_DATA se houver erros recuperáveis e não fatais durante o processo de navegação; por exemplo, uma palavra-chave de senha ou atributo inválida fornecida pelo aplicativo. Quando SQL_NEED_DATA é retornado e a cadeia de conexão do resultado da procura não é alterada, ocorreu um erro e o aplicativo pode chamar SQLGetDiagRec para retornar o SQLSTATE para erros de tempo de navegação. Isso permite que o aplicativo corrija o atributo e continue a navegação.

Um aplicativo pode encerrar o processo de navegação a qualquer momento chamando SQLDisconnect. O driver encerrará todas as conexões pendentes e retornará a conexão para um estado desconectado.

Se as operações assíncronas estiverem habilitadas no identificador de conexão, o SQLBrowseConnect também poderá retornar SQL_STILL_EXECUTING. Quando ele retorna SQL_NEED_DATA, um aplicativo deve usar SQLDisconnect para cancelar o processo de navegação. Se SQLBrowseConnect retornar SQL_STILL_EXECUTING, um aplicativo deverá usar SQLCancelHandle para cancelar a operação em andamento. Chamar SQLCancelHandle depois que a função retorna SQL_NEED_DATA não tem efeito.

Para obter mais informações, consulte Conectando-se com SQLBrowseConnect.

Se um driver der suporte a SQLBrowseConnect, a seção de palavra-chave driver nas informações do sistema para o driver deverá conter a palavra-chave ConnectFunctions com o terceiro caractere definido como "Y".

Exemplo de código

No exemplo a seguir, um aplicativo chama SQLBrowseConnect repetidamente. Cada vez que o SQLBrowseConnect retorna SQL_NEED_DATA, ele retorna informações sobre os dados necessários em *OutConnectionString. O aplicativo passa OutConnectionString para sua rotina GetUserInput (não mostrada). GetUserInput analisa as informações, cria e exibe uma caixa de diálogo e retorna as informações inseridas pelo usuário em *InConnectionString. O aplicativo passa as informações do usuário para o driver na próxima chamada para SQLBrowseConnect. Depois que o aplicativo tiver fornecido todas as informações necessárias para que o driver se conecte à fonte de dados, o SQLBrowseConnect retornará SQL_SUCCESS e o aplicativo continuará.

Para obter um exemplo mais detalhado de como se conectar a um driver do SQL Server chamando SQLBrowseConnect, consulte Exemplo de navegação do SQL Server.

Por exemplo, para se conectar à fonte de dados Sales, as ações a seguir podem ocorrer. Primeiro, o aplicativo passa a seguinte cadeia de caracteres para SQLBrowseConnect:

"DSN=Sales"  

O Gerenciador de Driver carrega o driver associado à fonte de dados Sales. Em seguida, ele chama a função SQLBrowseConnect do driver com os mesmos argumentos recebidos do aplicativo. O driver retorna a seguinte cadeia de caracteres em *OutConnectionString:

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

O aplicativo passa essa cadeia de caracteres para sua rotina GetUserInput , que cria uma caixa de diálogo que solicita que o usuário selecione o servidor vermelho, azul ou verde e insira uma ID de usuário e senha. A rotina passa as seguintes informações especificadas pelo usuário de volta em *InConnectionString, que o aplicativo passa para SQLBrowseConnect:

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

SQLBrowseConnect usa essas informações para se conectar ao servidor vermelho como Smith com a senha Sésamo e, em seguida, retorna a seguinte cadeia de caracteres em *OutConnectionString:

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

O aplicativo passa essa cadeia de caracteres para sua rotina GetUserInput , que cria uma caixa de diálogo que solicita que o usuário selecione um banco de dados. O usuário seleciona empdata e o aplicativo chama SQLBrowseConnect uma última vez com esta cadeia de caracteres:

"DATABASE=SalesOrders"  

Essa é a informação final que o driver precisa para se conectar à fonte de dados; SQLBrowseConnect retorna SQL_SUCCESS e *OutConnectionString contém a cadeia de conexão concluída:

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

Funções relacionadas

Confira também

Referência de API do ODBC
Arquivos de cabeçalho ODBC