Ejemplo de exploración de SQL Server

En el ejemplo siguiente se muestra cómo se puede usar SQLBrowseConnect para examinar las conexiones disponibles con un controlador para SQL Server. En primer lugar, la aplicación solicita un identificador de conexión:

SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  

A continuación, la aplicación llama a SQLBrowseConnect y especifica el controlador de SQL Server, con la descripción del controlador devuelta por SQLDrivers:

SQLBrowseConnect(hdbc, "DRIVER={SQL Server};", SQL_NTS, BrowseResult,  
                  sizeof(BrowseResult), &BrowseResultLen);  

Dado que esta es la primera llamada a SQLBrowseConnect, el Administrador de controladores carga el controlador de SQL Server y llama a la función SQLBrowseConnect del controlador con los mismos argumentos que recibió de la aplicación.

Nota:

Si se conecta a un proveedor de orígenes de datos que admite autenticación de Windows, debe especificar Trusted_Connection=yes en lugar de la información de identificador de usuario y contraseña en la cadena de conexión.

El controlador determina que esta es la primera llamada a SQLBrowseConnect y devuelve el segundo nivel de atributos de conexión: servidor, nombre de usuario, contraseña, nombre de aplicación e identificador de estación de trabajo. Para el atributo de servidor, devuelve una lista de nombres de servidor válidos. El código devuelto de SQLBrowseConnect es SQL_NEED_DATA. Esta es la cadena de resultado de navegación:

"SERVER:Server={red,blue,green,yellow};UID:Login ID=?;PWD:Password=?;  
   *APP:AppName=?;*WSID:WorkStation ID=?;"  

Cada palabra clave de la cadena de resultado de navegación va seguida de dos puntos y una o más palabras antes del signo igual. Estas palabras son el nombre descriptivo que una aplicación puede usar para crear un cuadro de diálogo. Las palabras clave APP y WSID tienen como prefijo un asterisco, lo que significa que son opcionales. Las palabras clave SERVER, UID y PWD no tienen el prefijo asterisco; los valores deben proporcionarse para ellos en la siguiente cadena de solicitud de navegación. El valor de la palabra clave SERVER puede ser uno de los servidores devueltos por SQLBrowseConnect o un nombre proporcionado por el usuario.

La aplicación llama a SQLBrowseConnect de nuevo, especificando el servidor verde y omitiendo las palabras clave APP y WSID y los nombres descriptivos después de cada palabra clave:

SQLBrowseConnect(hdbc, "SERVER=green;UID=Smith;PWD=Sesame;", SQL_NTS,  
                  BrowseResult, sizeof(BrowseResult), &BrowseResultLen);  

El controlador intenta conectarse al servidor verde. Si hay errores nofatales, como un par de palabras clave-valor que falta, SQLBrowseConnect devuelve SQL_NEED_DATA y permanece en el mismo estado que antes del error. La aplicación puede llamar a SQLGetDiagField o SQLGetDiagRec para determinar el error. Si la conexión se realiza correctamente, el controlador devuelve SQL_NEED_DATA y devuelve la cadena de resultado del examen:

"*DATABASE:Database={master,model,pubs,tempdb};  
   *LANGUAGE:Language={us_english,Franais};"  

Dado que los atributos de esta cadena son opcionales, la aplicación puede omitirlos. Sin embargo, la aplicación debe llamar a SQLBrowseConnect de nuevo. Si la aplicación decide omitir el nombre y el idioma de la base de datos, especifica una cadena de solicitud de exploración vacía. En este ejemplo, la aplicación elige la base de datos pubs y llama a SQLBrowseConnect una hora final, omitiendo la palabra clave LANGUAGE y el asterisco antes de la palabra clave DATABASE:

SQLBrowseConnect(hdbc, "DATABASE=pubs;", SQL_NTS, BrowseResult,  
                  sizeof(BrowseResult), &BrowseResultLen);  

Dado que el atributo DATABASE es el atributo de conexión final requerido por el controlador, el proceso de exploración se completa, la aplicación está conectada al origen de datos y SQLBrowseConnect devuelve SQL_SUCCESS. SQLBrowseConnect también devuelve la cadena de conexión completa como cadena de resultado de exploración:

"DSN=MySQLServer;SERVER=green;UID=Smith;PWD=Sesame;DATABASE=pubs;"  

La cadena de conexión final devuelta por el controlador no contiene los nombres descriptivos después de cada palabra clave, ni contiene palabras clave opcionales no especificadas por la aplicación. La aplicación puede usar esta cadena con SQLDriverConnect para volver a conectarse al origen de datos en el identificador de conexión actual (después de desconectar) o para conectarse al origen de datos en un identificador de conexión diferente. Por ejemplo:

SQLDriverConnect(hdbc, hwnd, BrowseResult, SQL_NTS, ConnStrOut,  
                  sizeof(ConnStrOut), &ConnStrOutLen, SQL_DRIVER_NOPROMPT);