Mimer SQL Documentation TOC PREV NEXT INDEX

Mimer SQL Developer Site


Initializing the ODBC Environment


The first task for any ODBC application is to initialize the ODBC environment by allocating an environment handle (SQL_HANDLE_ENV):

 /* Allocate environment handle */
 if ( SQLAllocHandle( SQL_HANDLE_ENV,
                      SQL_NULL_HANDLE,
                      &henv ) == SQL_ERROR )
 {
     printf( "Failed to allocate environment handle\n" );
     . . .
 }
 

Before an application allocates a connection, it should declare the version of ODBC that it has been written for (this mainly affects SQLSTATE values and datetime data types), and then allocate a connection handle:

 /* Set the ODBC version environment */
 SQLSetEnvAttr( henv,
                SQL_ATTR_ODBC_VERSION,
                (SQLPOINTER)SQL_OV_ODBC3,
                SQL_IS_INTEGER );
 
 /* Allocate connection handle */
 if ( SQLAllocHandle( SQL_HANDLE_DBC,
                      henv,
                      &hdbc ) == SQL_ERROR )
 {
     printf( "Failed to allocate connection handle\n" );
     . . .
 }

Making a Connection

After an ODBC data source has been defined, ODBC applications can connect to Mimer SQL by using the data source name.

There are a number of mechanisms to get the information required to make a connection; some applications supply the connection details, others use the ODBC dialog box to allow the user to complete the information.

The simplest form of connection uses SQLConnect, which requires a data source name, user ID and password, for example:

 SQLRETURN retcode;
 . . .
 
 /* Set connection timeout - 10 seconds */
 SQLSetConnectAttr( hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0 );
 
 /* Connect - DSN, User ID, Password */
 retcode = SQLConnect( hdbc,
                       (SQLCHAR*) "EXAMPLEDB", SQL_NTS,
                       (SQLCHAR*) "MIMER_ADM", SQL_NTS,
                       (SQLCHAR*) "admin", SQL_NTS );
 if ( retcode == SQL_SUCCESS
 ||   retcode == SQL_SUCCESS_WITH_INFO )
 {
     /* User connected */
 

SQLDriverConnect allows the driver to connect by supplying the connection information as a number of keyword-value pairs:

 "DSN=EXAMPLEDB;UID=MIMER_ADM;PWD=admin;"

There is an option for the Driver Manager to enter into a dialog with the user to complete any missing connection information (the handle of the parent window needs to be supplied to use this facility).

In the following example, the Driver Manager displays a window containing a combo box listing all the Mimer SQL database names and prompts for the user name and password:

 SQLCHAR     OutConnectString[256];
 SQLSMALLINT StringLength;
 
 . . .
 
 retcode = SQLDriverConnect( hdbc,
                             hwnd,
                             (SQLCHAR*) "DRIVER=Mimer;", SQL_NTS,
                             (SQLCHAR*)OutConnectString,
                             sizeof(OutConnectString),
                             &StringLength,
                             SQL_DRIVER_COMPLETE );
 if (SQL_SUCCEEDED(retcode))
 {
     /* User connected */
     printf( "connection string used: %s\n, OutConnectString );
 
Note: The macro SQL_SUCCEEDED replaces the test against SQL_SUCCESS or SQL_SUCCESS_WITH_INFO.

Controlling Interaction with the User

You may wish to have more control over the interaction with the user, SQLDataSources provides a mechanism to get information about the data sources configured on the client:

 SQLCHAR   DSNname[SQL_MAX_DSN_LENGTH+1];
 SQLCHAR   driver[33];
 
 . . .
 
 /* Enumerate the system data source names */
 retcode = SQLDataSources( henv,
                           SQL_FETCH_FIRST_SYSTEM,
                          (SQLCHAR*)DSNname,
                           sizeof(DSNname),
                           NULL,
                           SQLCHAR*)driver,
                           sizeof(driver),
                           NULL );
 
 while (SQL_SUCCEEDED(retcode))
 {
     printf( "%-32s     %s\n", DSNname, driver );  // Display details
 
     /* Fetch next */
     retcode = SQLDataSources( henv,
                               SQL_FETCH_NEXT,
                              (SQLCHAR*)DSNname,
                               sizeof(DSNname),
                               NULL,
                               (SQLCHAR*)driver,
                               sizeof(driver),
                               NULL );		
 }

Connecting Using a File Data Source

Another way of making a connection is to create a file data source. The file has a .dsn extension and contains the keyword-value pairs to make the connection.

Although it is possible to include the password, this would make the system insecure and therefore has little to recommend it:

 [ODBC]
 DSN=EXAMPLEDB
 UID=MIMER_ADM
 

To make a connection using a file data source, use the option for the Driver Manager to enter into a dialog with the user to complete any missing connection information (again, the handle of the parent window needs to be supplied to use this facility):

 retcode = SQLDriverConnect( hdbc,
                             hwnd,
                             (SQLCHAR*) "FILEDSN=example.dsn;",
                             SQL_NTS,
                             (SQLCHAR*)OutConnectString,
                             sizeof(OutConnectString),
                             &StringLength,
                             SQL_DRIVER_COMPLETE );
 if (SQL_SUCCEEDED(retcode))
 {
     /* User connected */
 

Determining Driver and Data Source Capabilities

After connection to the database, use SQLGetInfo to determine the capabilities of the driver and the data source associated with the connection:

 /* Display DBMS version details */
 SQLGetInfo( hdbc,
             SQL_DBMS_VER,
             (SQLPOINTER)&str_value,
             sizeof(str_value),
             &str_len );
 printf( "%s\n", str_value );
 
 /* Display SQL conformance level */
 SQLGetInfo( hdbc,
             SQL_SQL_CONFORMANCE,
             (SQLPOINTER)&int_value,
             sizeof(int_value),
             NULL );
 if (int_value & SQL_SC_SQL92_ENTRY)
    printf( "Entry level SQL-92\n" );
 if (int_value & SQL_SC_FIPS127_2_TRANSITIONAL)
    printf( "FIPS 127-2 transitional level\n" );
 if (int_value & SQL_SC_SQL92_INTERMEDIATE)
    printf( "Intermediate level SQL-92\n" );
 if (int_value & SQL_SC_SQL92_FULL)
    printf( "Full level SQL-92\n" );</pre>

Disconnecting

When the application has finished using a data source, it calls SQLDisconnect.

After disconnecting, the application should call SQLFreeHandle to release the connection handle and, if appropriate, to release the environment handle.


Mimer
Mimer Information Technology AB
Voice: +46 18 780 92 00
Fax: +46 18 780 92 40
info@mimer.se
Mimer SQL Documentation TOC PREV NEXT INDEX