4.2 Getting Connected

To begin, let's log on.

In the old days, connecting to a database was more or less a matter of opening a few files. These days, the complications of networking, RDBMSs, client/server computing, and a host of other considerations have made database connection a major hurdle to overcome in building applications. DBTools.h++ simplifies the process.

NOTE: With DBTools.h++, you establish a database connection by requesting an RWDBDatabase instance from the RWDBManager.

DBTools.h++ is designed to provide a single, global instance of the class RWDBManager. RWDBManager is responsible for providing your applications with correctly typed RWDBDatabase objects, based upon parameters provided to its static database() member function.

The following example shows how to establish connectivity using DBTools.h++. Unlike the code fragments you have seen so far, this is a complete program. After changing the parameters in the database() call to fit your system, you can and should compile and run this program before you attempt anything more ambitious. Remember that you must first establish connectivity without DBTools.h++, or this program may not work.

// Example Program 1 - Establishing connectivity
#include <rw/rstream.h>
#include <rw/db/db.h>
#include <rw/db/dbmgr.h>

int 
main() {
  RWDBDatabase myDbase = RWDBManager::database(
          "libctl0d.so",    // access library name             //1
          "sybase_host",    // server name                     //2
          "dbxx",           // user name                       //3
          "demodb",         // password                        //4
          "DEMO_DB"         // database name                   //5
      );
  if (myDbase.isValid()) {
    cout << "Connected!" << endl; 
  }
  else {
    cout << myDbase.status().message() << endl;
  }
  return 0;
}

Let's look at the parameters for the RWDBManager::database() call:

//1	Access library name: This string identifies the DBTools.h++ access library containing the specific implementation classes for the database you are connecting to. Its form depends upon whether the access library was built as a static or a dynamic library. NOTE: DBTools.h++ supports both static and dynamic linking of its access libraries. RWDBManager is responsible for dealing with the operating system details of runtime loading of dynamic libraries, including the important detail of deciding whether to load any libraries at all. For dynamic libraries or shared libraries, you must supply the name of the library, as we have done in the example. For static libraries, you must supply a string uniquely identifying the library type, such as `SYBASE` or `ORACLE`. Your DBTools.h++ access library guide specifies the appropriate name for each library in the section entitled Databases and Connections.
//2	Server name: Here you must supply the name of your database server, as it is known to your database client. Typically, the server name is established when your database is installed. See your system administrator if you are in doubt.
//3	User name: Supply the user name that you use to log into your database. Some RDBMS systems require that this be the same as your operating system login name; others maintain their own collections of valid user names. See your system administrator if you are in doubt.
//4	Password: Supply the password that you use to log into your database. If your database does not require a password, supply an empty string `""`.
//5	Database name: If your RDBMS system supports the notion of multiple databases driven by a single server, supply the name of the database you wish to use. If not, supply an empty string `""`.

It is also possible to establish multiple login sessions to a database. The information you provide in the RWDBManager::database() call is retained in each database object, so that you don't have to repeat it every time.

When you can successfully run the example program above and obtain an RWDBDatabase whose isValid() member function returns true, you can be confident that:

The access library you specified has been located.
An RWDBConnection object has been successfully instantiated and reserved by the database object for use as a default connection.

In other words, your database connectivity has been established, and you are ready to continue.