Establishing a database connection from the Database<Toolkit> Client consists of connecting to the Database<Toolkit> Server machine, identifying a Data Source Name (DSN) that an administrator has configured within the remote machine's ODBC environment, and providing any necessary authentication information. This is normally done within the constructor for os_db_connection objects.

A DSN is the name that identifies a particular database resource visible to ODBC applications. Note that DSN names available to the Database<Toolkit> Client are just those visible to the Database<Toolkit> Server, that is to say, the DSN's configured within the ODBC environment on the Database<Toolkit> Server machine. For information on configuring ODBC Data Source Names consult the platform ODBC documentation.

In the example below connection1 illustrates establishing a database connection using the dsn, user, and auth strings.

Also connection2 is established with the same information but uses a single string constructed with attributes "DSN=", "UID=", and "PWD=". This type of connection allows additional driver specific connection attributes to be added to the connection string.

Example <ospace/database/examples/connect1.cpp>


  #include <ospace/std/iostream>
#include <ospace/network.h>
#include <ospace/stream.h>
#include <ospace/database.h>

using OS_STD_IO cin;
using OS_STD_IO cout;
using OS_STD_IO cerr;
using OS_STD_IO endl;
using OS_STD os_string;
using os_db::os_db_error;

/**
 * Usage {program} [dbserver_hostname [dsn [user [auth]]]]
 */
int main(int argc, char** argv)
  {
  os_network_toolkit init_network;
  os_streaming_toolkit init_streaming;
  os_database_toolkit init_database;

  os_string target_hostname;
  os_string dsn;      // dsn name
  os_string user;     // user name
  os_string auth;     // auth info

  // Use local host if none specified on command line
  (argc > 1) ? target_hostname = argv[1] : target_hostname = os_host::my_host().name();
  (argc > 2) ? dsn  = argv[2] : dsn  = "dbtoolkit";
  (argc > 3) ? user = argv[3] : user = "guest";
  (argc > 4) ? auth = argv[4] : auth = "";

  try
    {
    //
    // Build a connection to the database server.
    //
    os_ip_address iaddr( target_hostname );
    os_db_connection connection1( os_socket_address( iaddr, 3006),    // target machine, port 3006
                                  dsn,          // ODBC Data Source Name
                                  user,         // user
                                  auth );       // authentication


    if ( connection1.dsn_is_connected() )
      {
      cout << "connection1 succeeded." << endl;
      }

    // Another connection allowing driver specific connection attributes

    os_string connect_info =
      "DSN=" + dsn +
      ";UID=" + user +
      ";PWD=" + auth +
      ";";
      
    os_db_connection connection2( os_socket_address(iaddr, 3006),
                                  connect_info );

    //
    // Take manual control of transactions.
    // We will call commit() or rollback() as needed for this connection.
    //
    connection2.set_commit_mode( os_db_connection::txn_manual );

    if ( connection2.dsn_is_connected() )
      {
      cout << "connection2 succeeded." << endl;
      }
    }
  catch ( os_db_error& error )
    {
    cout << "Caught database error:" << endl;
    cout << "\t" << error.description( error.get_code() ) << endl;
    cout << "\t" << error.what() << endl;
    cout << "Native Error Code: " << error.get_native() << endl;
    }
  catch ( os_streaming_toolkit_error& error )
    {
    cout << "Caught streaming error:" << endl;
    cout << "\t" << error.description( error.code() ) << endl;
    cout << "\t" << error.what() << endl;
    cout << "Native Error Code: " << error.native() << endl;
    }
  catch ( os_network_toolkit_error& error )
    {
    cout << "Caught network toolkit error:" << endl;
    cout << "\t" << error.description( error.code() ) << endl;
    cout << "\t" << error.what() << endl;
    cout << "Native Error Code: " << error.native() << endl;
    }

  return 0;
  }


connection1 succeeded.
connection2 succeeded.

Modifying the Remote ODBC Environment

It is also possible to construct an os_db_connection without initially specifying the database to connect to. The motivation for doing so may be to access or modify low-level remote ODBC environment or connection attributes before a database connection is made.

Note that if no DSN is specified during construction of the os_db_connection object then a call to the object's dsn_connect() must be made before the connection can be used by os_db_statement objects.

The following example illustrates construction of a connection in a way that low-level streaming ODBC API calls can be issued on the ODBC environment handle, and/or the ODBC connection handle, before a database connection is made.

Example <ospace/database/examples/connect2.cpp>


  #include <ospace/std/iostream>
#include <ospace/network.h>
#include <ospace/stream.h>
#include <ospace/database.h>

using OS_STD_IO cin;
using OS_STD_IO cout;
using OS_STD_IO cerr;
using OS_STD_IO endl;
using OS_STD os_string;
using os_db::os_db_error;

/**
 * Usage {program} [dbserver_hostname [dsn [user [auth]]]]
 */
int main(int argc, char** argv)
  {
  os_network_toolkit init_network;
  os_streaming_toolkit init_streaming;
  os_database_toolkit init_database;

  os_string target_hostname;
  os_string dsn;      // dsn name
  os_string user;     // user name
  os_string auth;     // auth info

  // Use local host if none specified on command line
  (argc > 1) ? target_hostname = argv[1] : target_hostname = os_host::my_host().name();
  (argc > 2) ? dsn  = argv[2] : dsn  = "dbtoolkit";
  (argc > 3) ? user = argv[3] : user = "guest";
  (argc > 4) ? auth = argv[4] : auth = "";

  try
    {
    //
    // Build a connection to the database server, delaying DSN connection.
    //
    os_ip_address iaddr( target_hostname );
    os_db_connection connect( os_socket_address( iaddr, 3006) );

    OSSQLHANDLE env_handle = connect.get_env_handle();
    //
    // Can perform raw ODBC API calls on this env_handle now.
    // No dbc_handles exist yet for this env_handle.
    //

    // ...

    
    OSSQLHANDLE dbc_handle = connect.get_dbc_handle();
    //
    // Can perform raw ODBC API calls on this dbc_handle now.
    // No DSN connection exists.
    //

    // ...

    // Make the DSN connection
    os_string connect_info =
      "DSN=" + dsn +
      ";UID=" + user +
      ";PWD=" + auth +
      ";";

    if (connect.dsn_connect(connect_info))
      {
      cout << "connect succeeded" << endl;
      }
    }
  catch ( os_db_error& error )
    {
    cout << "Caught database error:" << endl;
    cout << "\t" << error.description( error.get_code() ) << endl;
    cout << "\t" << error.what() << endl;
    cout << "Native Error Code: " << error.get_native() << endl;
    }
  catch ( os_streaming_toolkit_error& error )
    {
    cout << "Caught streaming error:" << endl;
    cout << "\t" << error.description( error.code() ) << endl;
    cout << "\t" << error.what() << endl;
    cout << "Native Error Code: " << error.native() << endl;
    }
  catch ( os_network_toolkit_error& error )
    {
    cout << "Caught network toolkit error:" << endl;
    cout << "\t" << error.description( error.code() ) << endl;
    cout << "\t" << error.what() << endl;
    cout << "Native Error Code: " << error.native() << endl;
    }

  return 0;
  }


connect succeeded.

Connecting to Databases

Establishing Database Connections

Example <ospace/database/examples/connect1.cpp>

Modifying the Remote ODBC Environment

Example <ospace/database/examples/connect2.cpp>