Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

Connecting to a database

UltraLite applications must connect to the database before performing operations on its data. This section describes how to connect to an UltraLite database.

You can find sample code in the samples-dir\UltraLite\CustDB\ directory.

• Commit behavior    In the UltraLite C++ API, there is no AutoCommit mode. Each transaction must be followed by a Conn->Commit() statement.

  See Managing transactions.

• User authentication    You can change the user ID and password for the application (from the default values of DBA and sql, respectively) by using methods to grant and revoke connection permissions. Each database can have a maximum of four user IDs.

  See Authenticating users.

• Synchronization    You can synchronize an UltraLite database with a consolidated database by using methods of the Connection object.

  See Synchronizing data.

• Tables    UltraLite database tables are accessed using methods of the Connection object.

  See Accessing data with the Table API.

• Prepared statements    Methods are provided to handle the execution of SQL statements.

  See Accessing data using SQL and UltraLite_PreparedStatement class.

To connect to an UltraLite database

1. Use the UltraLite namespace.

   Using the UltraLite namespace allows you to use simple names for classes in the C++ interface.

   using namespace UltraLite;

2. Create and initialize a DatabaseManager object and an UltraLite SQL communications area (ULSqlca). The ULSqlca is a structure that handles communication between the application and the database.

   The DatabaseManager object is at the root of the object hierarchy. You create only one DatabaseManager object per application. It is often best to declare the DatabaseManager object as global to the application.

   ULSqlca sqlca;
   sqlca.Initialize();
   DatabaseManager * dbMgr = ULInitDatabaseManager(sqlca);

   If the application does not require SQL support and directly links the UltraLite runtime, the application can call ULInitDatabaseManagerNoSQL to initialize the ULSqlca. This variant reduces the size of the application.

   See UltraLite_DatabaseManager_iface class.

3. Open a connection to an existing database, or create a new database if the specified database file does not exist. See OpenConnection function.

   UltraLite applications can be deployed with an initial empty database or the application can create the UltraLite database if it does not already exist. Deploying an initial database is the simplest solution; otherwise, the application must call the ULCreateDatabase function to create the database and must create all the tables the application requires. See ULCreateDatabase function.

   COnnection * conn = dbMgr->OpenConnection( sqlca, UL_TEXT("dbf=mydb.udb") );
   if( sqlca.GetSQLCode() == 
     SQLE_ULTRALITE_DATABASE_NOT_FOUND ) {
       printf( "Open failed with sql code: %d.\n" , sqlca.GetSQLCode() );
     }
   }

Each connection and all objects created from it should be used by a single thread. If an application requires multiple threads accessing the UltraLite database, each thread requires a separate connection.