SQLConnect--Conectar con una fuente de datos

Finalidad

SQLConnect() establece una conexión con la base de datos destino.

Antes de invocar esta función se debe asignar un descriptor de conexión utilizando SQLAllocHandle().

Esta función se debe invocar antes de asignar un descriptor de sentencia utilizando SQLAllocHandle().

Sintaxis

SQLRETURN   SQLConnect       (
                SQLHDBC               ConnectionHandle,   /* hdbc */
                SQLCHAR      *FAR ServerName,        /* szDSN */
                SQLSMALLINT       NameLength1,       /* cbDSN */
                SQLCHAR      *FAR UserName,          /* szUID */
                SQLSMALLINT       NameLength2,       /* cbUID */
                SQLCHAR      *FAR Authentication,    /* szAuthStr */
                SQLSMALLINT       NameLength3);      /* cbAuthStr */

Argumentos de la función

Tabla 36. Argumentos de SQLConnect

Notas

Un usuario no registrado (alguien que no existe en la tabla DB2eSYSUSERS) recibirá el mensaje de aviso, 42704 (objeto no definido) al intentar conectar con una base de datos DB2 Everyplace cifrada durante una llamada a la función SQLGetDiagRec() de CLI. Un usuario registrado no recibirá este aviso. En cambio, tanto un usuario registrado como un usuario no registrado pueden conectar con la base de datos durante la llamada a la función SQLConnect() y no recibirán un mensaje de aviso.

Uso

SQLConnect() se puede utilizar para conectar con fuentes de datos en ubicaciones distintas.

Para acceder a una fuente de datos en un dispositivo local, se establece el argumento ServerName en un nombre de fuente de datos. DB2 Everyplace ignora el nombre de la fuente de datos y se accede a la fuente de datos local.

Para aplicaciones que utilizan dispositivos de almacenamiento secundario, el argumento ServerName acepta una serie que apunte a la ubicación de una DataSource que existe localmente o que existe en un dispositivo de almacenamiento secundario soportado tales como IBM Microdrive, Sony Memory Stick, Compact Flash, SD Memory Card o MultiMediaCard. El formato de la serie ServerName es el siguiente:

ServerName=Device:/Path/DataSource

Dispositivo

Es el nombre del dispositivo donde se almacena la fuente de datos (DataSource). El carácter reservado # se utiliza para acceder a cualquier dispositivo de almacenamiento Compact Flash (CF) de Tipo II (en dispositivos Palm OS con soporte para CF). El almacenamiento secundario se direcciona utilizando el carácter reservado #. #0 y #1 especifican la ranura de almacenamiento secundario que se debe acceder. # es equivalente a #0. Por ejemplo:

ServerName=#:/storage/

DB2 Everyplace se conecta a DataSource en el directorio storage de IBM Microdrive en la primera ranura CF.

Vía

Es la vía de acceso de la DataSource ubicada en el Dispositivo. Si se especifica Vía sin especificar Dispositivo:/, se utiliza la vía de acceso del sistema de archivos local referida a la ubicación de la aplicación. No se debe grabar ningún archivo en el directorio raíz de un volumen. Algunos tipos de soportes no dan soporte a los archivos en el directorio raíz. Por ejemplo:

ServerName=dir1/dir2/DATA1

Nota:

En DB2 Everyplace no existe límite en la longitud de la vía de acceso.

Si la aplicación se encuentra en /myapp en el sistema de archivos local, DB2 Everyplace se conecta a la DataSource ubicada en /myapp/dir1/dir2/. El nombre DATA1 de la DataSource no se tiene en cuenta.

DataSource

Opcional: Es el nombre de la fuente de datos con el que se establece una conexión. DB2 Everyplace no tiene en cuenta este nombre.

Para acceder a un procedimiento almacenado remoto utilizando el adaptador de Consulta remota y Procedimiento almacenado, se utiliza el argumento ServerName para identificar la ubicación y el nombre de la base de datos. Para aplicaciones que utilizan el adaptador de Consulta remota y Procedimiento almacenado para acceder a bases de datos remotas, el argumento ServerName acepta el formato URL:

http://IPAddress:portNumber/path?DB=DataSource 

Se necesitan IPAddress y Authentication.

Si utiliza almacenamiento de objetos de Windows CE en lugar de un sistema de archivos convencional, deberá:

• establecer el parámetro de vía de acceso de la función SQLConnect de CLI en "@:\"

o bien

• en CLP, ejecutar 'connect to @:\'

En el almacenamiento de objetos de Windows CE no existe el concepto de "directorio". Cuando se utiliza el almacenamiento de objetos, el usuario no puede especificar el directorio, o vía de acceso, en que se crean las tablas. Todas las tablas del almacenamiento de objetos se crean en el mismo espacio de nombres. Debido a esta limitación, no se pueden establecer varias conexiones simultáneas con el almacenamiento de objetos. A efectos de serialización de conexiones, el archivo de bloqueo se crea en la vía de acceso raíz del sistema de archivos.

Cuando se utiliza almacenamiento de objetos, los archivos DB2 Everyplace no se pueden suprimir de forma manual, a diferencia de la utilización de un sistema de archivos convencional.

Ejemplos

Para conectar con la fuente de datos situada localmente en c:\dir1\dir2\. Se ignora el nombre de fuente de datos DS1:

ServerName=c:/dir1/dir2/DS1

Para conectar localmente con la fuente de datos situada en /dir1/dir2/ utilizando la notación de sistema de archivos propia de UNIX:

ServerName=/dir1/dir2/

Para conectar con la fuente de datos situada localmente en el directorio dir1\, relativo a la vía de acceso de la aplicación. Si la aplicación está situada en c:\myapp\, se accede a la fuente de datos de c:\myapp\dir1\:

ServerName=dir1\

Para conectar con la fuente de datos situada en el directorio /dir1/ de la memoria de almacenamiento en la ranura 1 del almacenamiento intermedio:

ServerName=#1:/dir1/

Conectar con el DB2 Everyplace Sync Server 192.168.0.1 en el puerto 8080 y con la base de datos mysample utilizando el adaptador de consulta remota y procedimiento almacenado.

ServerName=
 http://192.168.0.1:8080/db2e/servlet/com.ibm.mobileservices.adapter
                .agent.AgentServlet?DB=mysample

Conectar con la fuente de datos utilizando el almacenamiento de Windows CE.

ServerName=@:\
 

Serialización de conexiones

Consulte el apartado Serialización de conexiones para obtener información sobre la serialización de la conexión.

Autentificación de conexiones

El cifrado de una base de datos requiere una autentificación rudimentaria del usuario. DB2 Everyplace utiliza el UserName y la Authentication para autentificar el usuario durante la conexión.

La autentificación funciona del modo siguiente: Si la tabla de catálogos de DB2eSYSUSERS no existe en la base de datos con la que conecta SQLConnect, se ignora la información de UserName y Authentication. DB2 Everyplace distingue entre usuarios registrados y no registrados. Un usuario registrado es un usuario que está relacionado en la tabla DB2eSYSUSERS y que se ha añadido mediante la sentencia GRANT SQL. Durante la conexión, si existe una tabla DB2eSYSUSERS y el UserName pertenece a un usuario registrado, se intenta la autentificación. Si la contraseña suministrada en el parámetro Authentication no es correcta, se devuelve un error (42505). Si el UserName no está registrado, la función SQLConnect resultará satisfactoria. Sin embargo, una llamada posterior a SQLGetDiagRec devolverá el aviso 42704 (objeto no definido). Esto permite que las aplicaciones distingan entre el caso de un usuario registrado que se conecta satisfactoriamente y un usuario no registrado que se conecta satisfactoriamente. Para obtener más información, vea el Visión general del cifrado local de los datos, *** y GRANT.

Códigos de retorno

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

Diagnósticos

Tabla 37. SQLSTATE de SQLConnect

Restricciones

Se debe invocar SQLConnect() para poder ejecutar cualquier sentencia de SQL.

Conceptos relacionados

• Serialización de conexiones
• SQLAllocHandle--Asignar descriptor de contexto
• SQLDisconnect--Desconectar de una fuente de datos

Consulta relacionada

• Clave para las descripciones de funciones de CLI de DB2
• Resumen de las funciones de CLI de DB2
• SQLAllocHandle--Asignar descriptor de contexto
• SQLDisconnect--Desconectar de una fuente de datos