SQLConnect--Connect to a data source

Purpose

SQLConnect() establishes a connection to the target database.

A connection handle must be allocated using SQLAllocHandle() before calling this function.

This function must be called before allocating a statement handle using SQLAllocHandle().

Syntax

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 */

Function arguments

Tabelle 36. SQLConnect arguments

Notes

A non-registered user (someone who doesn't exist in the DB2eSYSUSERS table) will receive the warning message, 42704 (object not defined), when attempting to connect to an encrypted DB2 Everyplace database during a call to the SQLGetDiagRec() CLI function. A registered user will not receive this warning. In contrast, both a non-registered and registered user is able to connect to the database during the SQLConnect() function call and will not receive a warning message.

Usage

SQLConnect() can be used to connect to data sources in different locations.

To access a data source on the local device, the ServerName argument is set to a data source name. The data source name is ignored by DB2 Everyplace and the local data source is accessed.

For applications using secondary storage devices, the ServerName argument accepts a string pointing to the location of a DataSource that exists locally or on a supported secondary storage device such as the IBM Microdrive, Sony Memory Stick, Compact Flash, SD Memory Card, or MultiMediaCard. The ServerName string format is:

ServerName=Device:/Path/DataSource

Device

This is the name of the device on which the DataSource is stored. The reserved character # is used to access any Compact Flash (CF) Type II storage device (on Palm OS devices with CF support). The secondary storage is addressed using the reserved characters #. #0 and #1 specify which secondary storage slot to access. # is equivalent to #0. For example:

ServerName=#:/storage/

DB2 Everyplace connects to the DataSource in the storage directory of the IBM Microdrive in the first CF slot.

Path

This is the path to the DataSource on the Device. When Path is specified without a Device:/, the local file system path relative to the application location is used. Files should not be written to the root directory of a volume. Files in the root directory are not supported by some media types. For example:

ServerName=dir1/dir2/DATA1

Anmerkung:

There is no path length limit in DB2 Everyplace.

If the application is located in /myapp on the local file system, DB2 Everyplace connects to the DataSource located in /myapp/dir1/dir2/. The DataSource name DATA1 is ignored.

DataSource

Optional: The name of the data source to connect to. This name is ignored by DB2 Everyplace.

To access a remote stored procedure using the Remote Query and Stored Procedure adapter, the ServerName argument is used to identify the location and name of the database. For applications using the Remote Query and Stored Procedure adapter to access remote databases, the ServerName argument accepts a URL format:

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

If using Windows CE object storage rather then a conventional file system, either:

• set the path parameter of CLI function SQLConnect to "@:\"

or

• in CLP, execute 'connect to @:\'

There is no "directory" concept in Windows CE object storage. When using object storage, the user cannot specify the directory, or path, in which tables are created. All tables in object storage are created in the same namespace. Because of this limitation, multiple simultaneous connections to object storage cannot be established. The lock file for connection serialization purposes is created in the root path of the file system.

When using object storage, DB2 Everyplace files cannot be deleted manually, unlike when using a conventional file system.

Examples

Connect to the data source locally at c:\dir1\dir2\. The data source name DS1 is ignored:

ServerName=c:/dir1/dir2/DS1

Connect to the data source locally at /dir1/dir2/ using UNIX file system notation:

ServerName=/dir1/dir2/

Connect to the data source locally in the dir1\ directory relative to the application path. If the application is located in c:\myapp\, the c:\myapp\dir1\ data source is accessed:

ServerName=dir1\

Connect to the data source in the /dir1/ directory on the storage memory in secondary storage slot 1:

ServerName=#1:/dir1/

Connect to the DB2 Everyplace Sync Server 192.168.0.1 on port 8080 and database mysample using the remote query and stored procedure adapter.

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

Connect to the data source using Windows CE storage.

ServerName=@:\
 

Connection Serialization

See Connection serialization for information about connection serialization.

Connection Authentication

Database encryption requires rudimentary user authentication. DB2 Everyplace uses the UserName and Authentication to authenticate the user at connect time.

The authentication works as follows: If the DB2eSYSUSERS catalog table does not exist in the database that SQLConnect connects to, then the UserName and Authentication information is ignored. DB2 Everyplace distinguish between registered and non-registered users. A registered user is a user that is listed in the DB2eSYSUSERS table added through the GRANT SQL statement. At connect time, if there is a DB2eSYSUSERS table and the UserName belongs to a registered user, authentication is attempted. If the password given in the Authentication parameter is not correct, an error (42505) is returned. If the UserName is non-registered, then the SQLConnect function will succeed. However, a subsequent call to SQLGetDiagRec will return the warning 42704 (object not defined). This allows applications to distinguish between the case of a registered user successfully connecting and a non-registered user who is successfully connected. For more information, see Overview of local data encryption, ***, and GRANT.

Return codes

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

Diagnostics

Tabelle 37. SQLConnect SQLSTATEs

Restrictions

SQLConnect() must be called before any SQL statements can be executed.

Zugehörige Konzepte

• Connection serialization
• SQLAllocHandle--Allocate handle
• SQLDisconnect--Disconnect from a data source

Zugehörige Referenzen

• Key to CLI function descriptions
• CLI function summary
• SQLAllocHandle--Allocate handle
• SQLDisconnect--Disconnect from a data source