Getting a Connection
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. The DB Interface Module simplifies the process. Using this module, you establish a database connection by requesting an RWDBDatabase instance from the RWDBManager.
The DB Interface Module 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 the DB Interface Module. 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 the DB Interface Module, or this program may not work. To use this code, the <ver> placeholder in any library names would need to be replaced with the actual digits representing the library version number.
Example 1 – Establishing connectivity
// Example Program 1 - Establishing connectivity
#include <rw/rstream.h>
#include <rw/db/db.h>
int
main() {
RWDBDatabase myDbase = RWDBManager::database(
"libctl<ver>15d.so", // access module name //1
"sybase_server", // server name //2
"user", // user name //3
"pwd", // password //4
"DEMO_DB" // database name //5
);
if (myDbase.isValid()) {
std::cout << "Connected!" << std::endl;
}
else {
std::cout << myDbase.status().message() << std::endl;
}
return 0;
}
Let's look at the parameters for the RWDBManager::database() call:
//1 Access Module name: This string identifies the DB Access Module that contains the specific implementation classes for the database you are connecting to. Its form depends upon whether the access module was built as a static or a dynamic library.
NOTE: SourcePro DB supports both static and dynamic linking of access modules. 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_CT or ORACLE_OCI. Your DB Access Module guide specifies the appropriate name for each library in the section entitled Databases and Connections.
//2 Server name: 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 "". (You can instead provide a password using the callback API, which may provide more security. See Providing a Password using connParams() in the Callbacks chapter.)
//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 Module 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.
