Conectar con un origen de datos (ODBC)

SQLConnect

SQLConnect es la función de conexión más simple. Acepta tres parámetros: nombre del origen de datos, identificador de usuario y contraseña. Utilice SQLConnect si estos tres parámetros contienen toda la información necesaria para conectarse a la base de datos. Para ello, genere una lista de orígenes de datos utilizando SQLDataSources; solicite al usuario un origen de datos, identificador de usuario y contraseña; y, a continuación, llame a SQLConnect.

SQLConnect considera que el nombre del origen de datos, el identificador de usuario y la contraseña son suficientes para conectarse a un origen de datos y que el origen de datos ODBC contiene todo el resto de información que el controlador ODBC necesita para realizar la conexión. A diferencia de SQLDriverConnect y SQLBrowseConnect, SQLConnect no utiliza una cadena de conexión.

SQLDriverConnect

Se utiliza SQLDriverConnect cuando es necesaria más información aparte del nombre del origen de datos, identificador de usuario y contraseña. Uno de los parámetros de SQLDriverConnect es una cadena de conexión que contiene información específica del controlador. Podría utilizar SQLDriverConnect en lugar de SQLConnect por las razones siguientes:

• Para especificar la información específica del controlador durante la conexión.

• Para solicitar que el controlador solicite al usuario la información de conexión.

• Para conectarse sin utilizar un origen de datos ODBC.

La cadena de conexión de SQLDriverConnect contiene una serie de pares de palabra clave y valor que especifican toda la información de conexión admitida por un controlador ODBC. Cada controlador admite las palabras clave de ODBC estándar (DSN, FILEDSN, DRIVER, UID, PWD y SAVEFILE) además de las palabras clave específicas del controlador para toda la información de conexión admitida por el controlador. SQLDriverConnect se puede utilizar para conectarse sin un origen de datos. Por ejemplo, una aplicación diseñada para realizar una conexión "sin DSN" a una instancia de SQL Server puede llamar a SQLDriverConnect con una cadena de conexión que define el identificador de inicio de sesión, contraseña, biblioteca de red, nombre de servidor para conectarse y la base de datos predeterminada que se va a utilizar.

Al utilizar SQLDriverConnect, hay dos opciones para solicitar al usuario la información de conexión necesaria:

• Cuadro de diálogo de la aplicación

  Puede crear un cuadro de diálogo de la aplicación que solicita información de conexión y, a continuación, llama a SQLDriverConnect con un identificador de ventana NULL y DriverCompletion establecido en SQL_DRIVER_NOPROMPT. Estos valores de parámetro evitan que el controlador ODBC abra su propio cuadro de diálogo. Se utiliza este método cuando es importante controlar la interfaz de usuario de la aplicación.

• Cuadro de diálogo del controlador

  Puede codificar la aplicación para que pase un identificador de ventana válido a SQLDriverConnect y establezca el parámetro DriverCompletion en SQL_DRIVER_COMPLETE, SQL_DRIVER_PROMPT o SQL_DRIVER_COMPLETE_REQUIRED. El controlador genera después un cuadro de diálogo para solicitar al usuario la información de conexión. Este método simplifica el código de aplicación.

SQLBrowseConnect

SQLBrowseConnect, como SQLDriverConnect, utiliza una cadena de conexión. Sin embargo, utilizando SQLBrowseConnect, una aplicación puede construir en tiempo de ejecución una cadena de conexión completa de forma iterativa con el origen de datos. Esto permite a la aplicación hacer dos cosas:

• Construir sus propios cuadros de diálogo para solicitar esta información, reteniendo así el control sobre la interfaz de usuario.

• Buscar en el sistema los orígenes de datos que un controlador determinado puede utilizar, posiblemente en varios pasos.

  Por ejemplo, el usuario podría buscar primero en la red los servidores y, después de elegir un servidor, buscar en el servidor las bases de datos accesibles para el controlador.

Cuando SQLBrowseConnect completa una conexión que se ha realizado correctamente, devuelve una cadena de conexión que se puede utilizar en llamadas subsiguientes a SQLDriverConnect.

El controlador ODBC de SQL Server Native Client siempre devuelve SQL_SUCCESS_WITH_INFO en un SQLConnect, SQLDriverConnect o SQLBrowseConnect correcto. Cuando una aplicación ODBC llama a SQLGetDiagRec después de obtener SQL_SUCCESS_WITH_INFO, puede recibir los mensajes siguientes:

• 5701
  Indica que SQL Server pone el contexto del usuario en la base de datos predeterminada definida en el origen de datos, o en la base de datos predeterminada definida para el identificador de inicio de sesión utilizado en la conexión si el origen de datos no tenía una base de datos predeterminada.

• 5703
  Indica el lenguaje utilizado en el servidor.

En el ejemplo siguiente se muestra el mensaje devuelto por el administrador del sistema al realizarse una conexión correctamente:

szSqlState = "01000", *pfNativeError = 5701,
szErrorMsg="[Microsoft][SQL Server Native Client][SQL Server]
       Changed database context to 'pubs'."
szSqlState = "01000", *pfNativeError = 5703,
szErrorMsg="[Microsoft][SQL Server Native Client][SQL Server]
       Changed language setting to 'us_english'."

Puede omitir los mensajes 5701 y 5703; sólo son informativos. No debe, sin embargo, omitir un código de retorno SQL_SUCCESS_WITH_INFO porque se pueden devolver mensajes distintos de 5701 ó 5703. Por ejemplo, si un controlador se conecta a un servidor que ejecuta una instancia de SQL Server con procedimientos almacenados de catálogo anticuados, uno de los errores devueltos a través de SQLGetDiagRec después de SQL_SUCCESS_WITH_INFO es:

SqlState:   01000
pfNative:   0
szErrorMsg: "[Microsoft][SQL Server Native Client]The ODBC
            catalog stored procedures installed on server
            my65server are version 06.50.0193; version 07.00.0205
            or later is required to ensure proper operation.
            Please contact your system administrator."

La función de tratamiento de errores de una aplicación de conexiones SQL Server debe llamar a SQLGetDiagRec hasta que devuelva SQL_NO_DATA. A continuación, debe actuar sobre los mensajes que no contengan un código pfNative de 5701 ó 5703.

Comprobar el estado de conexión

El comportamiento de SQL_ATTR_CONNECTION_DEAD y SQL_COPT_SS_CONNECTION_DEAD en SQL Server 2000 y posteriores es distinto del comportamiento en versiones anteriores. En SQL Server 2000 y posteriores, SQL_ATTR_CONNECTION_DEAD devuelve el estado de conexión más reciente, que no puede ser el estado de conexión actual. Sin embargo, SQL_COPT_SS_CONNECTION_DEAD siempre consulta en la biblioteca de red el estado actual de la conexión.

Para diferenciar entre estos comportamientos, se proporciona un nuevo valor a SQL_COPT_SS_CONNECTION_DEAD en los archivos de inclusión de SQL Server 2000 y posteriores. Las aplicaciones que utilizan este atributo que están generadas con encabezados de SQL Server 2000 y posteriores devolverán un error (HY092, Identificador de opción o atributo o no válido) si se ejecutan las aplicaciones utilizando un controlador SQL Server versión 7.0. Recomendamos que la aplicación compruebe la versión de controlador utilizada antes de llamar a SQLGetConnectAttr y, a continuación, utilice SQL_ATTR_CONNECTION_DEAD en lugar de SQL_COPT_SS_CONNECTION_DEAD si la aplicación se está ejecutando en un controlador SQL Server 7.0.

Vea también

Conceptos