Función SQLBrowseConnect

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ODBC

Resumen
SQLBrowseConnect admite un método iterativo para detectar y enumerar los atributos y los valores de atributo necesarios para conectarse a un origen de datos. Cada llamada a SQLBrowseConnect devuelve niveles sucesivos de atributos y valores de atributo. Cuando se han enumerado todos los niveles, sqlBrowseConnect devuelve una conexión al origen de datos y sqlBrowseConnect devuelve una cadena de conexión completa. Un código devuelto de SQL_SUCCESS o SQL_SUCCESS_WITH_INFO indica que se ha especificado toda la información de conexión y que la aplicación ahora está conectada al origen de datos.

Sintaxis

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

Argumentos

ConnectionHandle
[Entrada] Identificador de conexión.

InConnectionString
[Entrada] Examine la solicitud cadena de conexión (vea "InConnectionString Argument" en "Comments").

StringLength1
[Entrada] Longitud de *InConnectionString en caracteres.

OutConnectionString
[Salida] Puntero a un búfer de caracteres en el que se va a devolver el resultado de exploración cadena de conexión (vea "OutConnectionString Argument" en "Comments").

Si OutConnectionString es NULL, StringLength2Ptr seguirá devolviendo el número total de caracteres (excepto el carácter de terminación NULL para los datos de caracteres) disponible para devolver en el búfer al que apunta OutConnectionString.

BufferLength
[Entrada] Longitud, en caracteres, del búfer *OutConnectionString .

StringLength2Ptr
[Salida] Número total de caracteres (excepto la terminación null) disponible para devolver en *OutConnectionString. Si el número de caracteres disponibles para devolver es mayor o igual que BufferLength, el cadena de conexión de *OutConnectionString se trunca en BufferLength menos la longitud de un carácter de terminación NULL.

Devoluciones

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

Diagnóstico

Cuando SQLBrowseConnect devuelve SQL_ERROR, SQL_SUCCESS_WITH_INFO o SQL_NEED_DATA, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de ConnectionHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLBrowseConnect y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

Argumento InConnectionString

Una solicitud de exploración cadena de conexión tiene la sintaxis siguiente:

connection-string ::= attribute[;] | atributo ; connection-string;
attribute ::= attribute-keyword=attribute-valueDRIVER= | [{]attribute-value[}]
attribute-keyword ::= DSNPWD | UID | | driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier

donde la cadena de caracteres tiene cero o más caracteres; el identificador tiene uno o varios caracteres; attribute-keyword no distingue mayúsculas de minúsculas; attribute-value puede distinguir mayúsculas de minúsculas y el valor de la palabra clave DSN no consta únicamente de espacios en blanco. Debido a cadena de conexión y la gramática del archivo de inicialización, las palabras clave y los valores de atributo que contienen los caracteres []{}(),;? *=!@ debe evitarse. Debido a la gramática de la información del sistema, las palabras clave y los nombres de origen de datos no pueden contener el carácter de barra diagonal inversa (\). Para odbc 2.x driver, se requieren llaves alrededor del valor del atributo para la palabra clave DRIVER.

Si se repiten palabras clave en la solicitud de exploración cadena de conexión, el controlador usa el valor asociado a la primera aparición de la palabra clave. Si las palabras clave DSN y DRIVER se incluyen en la misma solicitud de exploración cadena de conexión, el Administrador de controladores y el controlador usan la palabra clave que aparezca primero.

Para obtener información sobre cómo una aplicación elige un origen de datos o un controlador, consulte Elección de un origen de datos o un controlador.

Argumento OutConnectionString

El resultado del examen cadena de conexión es una lista de atributos de conexión. Un atributo de conexión consta de una palabra clave de atributo y un valor de atributo correspondiente. El resultado del examen cadena de conexión tiene la sintaxis siguiente:

connection-string ::= attribute[;] | cadena de conexión de atributo ;
atributo ::= [*]attribute-keyword=attribute-value
attribute-keyword ::= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = {UID | PWD}[:localized-identifier] driver-defined-attribute-keyword ::= identifier[:localized-identifier] attribute-value ::= { attribute-value-list } | ? (Las llaves son literales; el controlador los devuelve).
attribute-value-list ::= character-string [:localized-character string] | character-string [:localized-character string] , attribute-value-list

donde la cadena de caracteres y la cadena de caracteres localizados tienen cero o más caracteres; identificador y identificador localizado tienen uno o varios caracteres; attribute-keyword no distingue mayúsculas de minúsculas y el valor de atributo puede distinguir mayúsculas de minúsculas. Debido a cadena de conexión y la gramática del archivo de inicialización, palabras clave, identificadores localizados y valores de atributo que contienen los caracteres []{}(),;? *=!@ debe evitarse. Debido a la gramática de la información del sistema, las palabras clave y los nombres de origen de datos no pueden contener el carácter de barra diagonal inversa (\).

El resultado del examen cadena de conexión sintaxis se usa según las siguientes reglas semánticas:

• Si un asterisco (*) precede a una palabra clave de atributo, el atributo es opcional y se puede omitir en la siguiente llamada a SQLBrowseConnect.

• Las palabras clave de atributo UID y PWD tienen el mismo significado que se define en SQLDriverConnect.

• Una palabra clave driver-defined-attribute-keyword asigna el tipo de atributo para el que se puede proporcionar un valor de atributo. Por ejemplo, puede ser SERVER, DATABASE, HOST o DBMS.

• Las palabras clave ODBC-attribute-keywords y driver-defined-attribute-keywords incluyen una versión localizada o fácil de usar de la palabra clave. Esto puede ser utilizado por las aplicaciones como una etiqueta en un cuadro de diálogo. Sin embargo, se debe usar UID, PWD o el identificador solo al pasar una cadena de solicitud de exploración al controlador.

• {attribute-value-list} es una enumeración de valores reales válidos para la palabra clave attribute-correspondiente. Tenga en cuenta que las llaves ({}) no indican una lista de opciones; el controlador los devuelve. Por ejemplo, puede ser una lista de nombres de servidor o una lista de nombres de base de datos.

• Si el valor de atributo es un signo de interrogación único (?), un valor único corresponde a la palabra clave attribute-. Por ejemplo, UID=JohnS; PWD=Sésamo.

• Cada llamada a SQLBrowseConnect devuelve solo la información necesaria para satisfacer el siguiente nivel del proceso de conexión. El controlador asocia información de estado con el identificador de conexión para que el contexto siempre se pueda determinar en cada llamada.

Uso de SQLBrowseConnect

SQLBrowseConnect requiere una conexión asignada. El Administrador de controladores carga el controlador especificado en o que corresponde al nombre del origen de datos especificado en el cadena de conexión de solicitud de exploración inicial; para obtener información sobre cuándo ocurre esto, vea la sección "Comentarios" de la función SQLConnect. El controlador puede establecer una conexión con el origen de datos durante el proceso de exploración. Si SQLBrowseConnect devuelve SQL_ERROR, se finalizan las conexiones pendientes y la conexión se devuelve a un estado no conectado.

Cuando se llama a SQLBrowseConnect por primera vez en una conexión, la solicitud de exploración cadena de conexión debe contener la palabra clave DSN o la palabra clave DRIVER. Si la solicitud de exploración cadena de conexión contiene la palabra clave DSN, el Administrador de controladores busca una especificación de origen de datos correspondiente en la información del sistema:

• Si el Administrador de controladores encuentra la especificación del origen de datos correspondiente, carga el archivo DLL del controlador asociado; el controlador puede recuperar información sobre el origen de datos de la información del sistema.

• Si el Administrador de controladores no encuentra la especificación del origen de datos correspondiente, busca la especificación predeterminada del origen de datos y carga el archivo DLL del controlador asociado; el controlador puede recuperar información sobre el origen de datos predeterminado de la información del sistema. "DEFAULT" se pasa al controlador para el DSN.

• Si el Administrador de controladores no encuentra la especificación del origen de datos correspondiente y no hay ninguna especificación de origen de datos predeterminada, devuelve SQL_ERROR con SQLSTATE IM002 (no se encontró el origen de datos y no se ha especificado ningún controlador predeterminado).

Si la solicitud de exploración cadena de conexión contiene la palabra clave DRIVER, driver Manager carga el controlador especificado; no intenta localizar un origen de datos en la información del sistema. Dado que la palabra clave DRIVER no usa información de la información del sistema, el controlador debe definir suficientes palabras clave para que un controlador pueda conectarse a un origen de datos con solo la información de la solicitud de exploración cadena de conexión s.

En cada llamada a SQLBrowseConnect, la aplicación especifica los valores de atributo de conexión en el cadena de conexión de solicitud de exploración. El controlador devuelve niveles sucesivos de atributos y valores de atributo en el cadena de conexión del resultado de exploración; devuelve SQL_NEED_DATA siempre que haya atributos de conexión que aún no se hayan enumerado en la solicitud de exploración cadena de conexión. La aplicación usa el contenido del resultado de exploración cadena de conexión para compilar la solicitud de exploración cadena de conexión para la siguiente llamada a SQLBrowseConnect. Todos los atributos obligatorios (no precedidos por un asterisco en el argumento OutConnectionString ) deben incluirse en la siguiente llamada a SQLBrowseConnect. Tenga en cuenta que la aplicación no puede usar el contenido del resultado de exploración anterior cadena de conexión al compilar la solicitud de exploración actual cadena de conexión; es decir, no puede especificar valores diferentes para los atributos establecidos en niveles anteriores.

Cuando se han enumerado todos los niveles de conexión y sus atributos asociados, el controlador devuelve SQL_SUCCESS, se completa la conexión al origen de datos y se devuelve un cadena de conexión completo a la aplicación. El cadena de conexión es adecuado para usar, junto con SQLDriverConnect, con la opción SQL_DRIVER_NOPROMPT para establecer otra conexión. El cadena de conexión completo no se puede usar en otra llamada a SQLBrowseConnect; sin embargo, si se llamó a SQLBrowseConnect de nuevo, toda la secuencia de llamadas tendría que repetirse.

SQLBrowseConnect también devuelve SQL_NEED_DATA si hay errores recuperables y nofatales durante el proceso de exploración; por ejemplo, una palabra clave de atributo o contraseña no válida proporcionada por la aplicación. Cuando se devuelve SQL_NEED_DATA y el resultado del examen cadena de conexión no cambia, se ha producido un error y la aplicación puede llamar a SQLGetDiagRec para devolver SQLSTATE para detectar errores en tiempo de exploración. Esto permite que la aplicación corrija el atributo y continúe con el examen.

Una aplicación puede finalizar el proceso de exploración en cualquier momento llamando a SQLDisconnect. El controlador finalizará las conexiones pendientes y devolverá la conexión a un estado no conectado.

Si las operaciones asincrónicas están habilitadas en el identificador de conexión, SQLBrowseConnect también puede devolver SQL_STILL_EXECUTING. Cuando devuelve SQL_NEED_DATA, una aplicación debe usar SQLDisconnect para cancelar el proceso de exploración. Si SQLBrowseConnect devuelve SQL_STILL_EXECUTING, una aplicación debe usar SQLCancelHandle para cancelar la operación en curso. Llamar a SQLCancelHandle después de que la función devuelva SQL_NEED_DATA no tiene ningún efecto.

Para obtener más información, consulte Conexión con SQLBrowseConnect.

Si un controlador admite SQLBrowseConnect, la sección de palabra clave driver de la información del sistema del controlador debe contener la palabra clave ConnectFunctions con el tercer carácter establecido en "Y".

Ejemplo de código

En el ejemplo siguiente, una aplicación llama a SQLBrowseConnect repetidamente. Cada vez que SQLBrowseConnect devuelve SQL_NEED_DATA, pasa información sobre los datos que necesita en *OutConnectionString. La aplicación pasa OutConnectionString a su rutina GetUserInput (no se muestra). GetUserInput analiza la información, compila y muestra un cuadro de diálogo y devuelve la información especificada por el usuario en *InConnectionString. La aplicación pasa la información del usuario al controlador en la siguiente llamada a SQLBrowseConnect. Una vez que la aplicación ha proporcionado toda la información necesaria para que el controlador se conecte al origen de datos, SQLBrowseConnect devuelve SQL_SUCCESS y la aplicación continúa.

Para obtener un ejemplo más detallado de cómo conectarse a un controlador de SQL Server mediante una llamada a SQLBrowseConnect, vea Ejemplo de exploración de SQL Server.

Por ejemplo, para conectarse al origen de datos Sales, se pueden producir las siguientes acciones. En primer lugar, la aplicación pasa la siguiente cadena a SQLBrowseConnect:

"DSN=Sales"  

El Administrador de controladores carga el controlador asociado con el origen de datos Sales. A continuación, llama a la función SQLBrowseConnect del controlador con los mismos argumentos que recibió de la aplicación. El controlador devuelve la siguiente cadena en *OutConnectionString:

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

La aplicación pasa esta cadena a su rutina GetUserInput , que crea un cuadro de diálogo que pide al usuario que seleccione el servidor rojo, azul o verde y escriba un identificador de usuario y una contraseña. La rutina pasa la siguiente información especificada por el usuario en *InConnectionString, que la aplicación pasa a SQLBrowseConnect:

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

SQLBrowseConnect usa esta información para conectarse al servidor rojo como Smith con el sésamo de contraseña y, a continuación, devuelve la siguiente cadena en *OutConnectionString:

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

La aplicación pasa esta cadena a su rutina GetUserInput , que crea un cuadro de diálogo que pide al usuario que seleccione una base de datos. El usuario selecciona empdata y la aplicación llama a SQLBrowseConnect una hora final con esta cadena:

"DATABASE=SalesOrders"  

Esta es la última información que el controlador necesita para conectarse al origen de datos; SQLBrowseConnect devuelve SQL_SUCCESS y *OutConnectionString contiene el cadena de conexión completado:

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

Funciones relacionadas

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC