UltraLite C++ User's Guide
Tutorial: An Introductory Application
In this lesson you write, compile, and run a C++ application that connects to a database using a schema you have created.
The application attempts to connect to a database. If the specified database file does not exist, UltraLite uses the schema file to create the database.
Before you begin
Create a directory to hold the files you create in this tutorial.
The remainder of this tutorial assumes the directory is c:\tutorial\cpp. If you create a directory with a different name, use that directory instead of c:\tutorial\cpp throughout the tutorial.
Using the UltraLite Schema Painter, create a database schema in your new directory with the following characteristics:
Schema file name: tutcustomer.usm
Table name: customer
Columns in customer:
| Column Name | Data Type (Size) | Column allows NULL values? | Default value |
|---|---|---|---|
| id | integer | No | autoincrement |
| fname | char(15) | No | None |
| lname | char(20) | No | None |
| city | char(20) | Yes | None |
| phone | char(12) | Yes | 555-1234 |
Primary key: ascending id
For more information, see UltraLite Schema Painter Tutorial.
To connect to an UltraLite database
In your tutorial directory, create a file named customer.cpp.
Copy the code below into customer.cpp. This code carries out the following tasks:
Imports the UltraLite libraries.
Defines connection parameters to connect to the database. Here, the parameters are the location of the database file and the location of a schema file to use in the creation of a database file if the database does not exist.
These locations are hardwired for convenience. In a real application, they would not be hardwired. In addition, these connection parameters are sufficient only for connections in the development environment; additional parameters are needed for the application to run on a Windows CE device. The additional parameters are described later in the tutorial.
Defines a method for error handling.
For more information about error handling, see Error handling.
Defines a method to open a connection to a database.
If the database file does not exist, a SQLException is thrown. The code that catches this exception uses the schema file to create a new database and establish a connection to it.
If the database file does exist, a connection is established.
#include "uliface.h"
#include <stdio.h>
#include <tchar.h>
using namespace UltraLite;
#define MAX_NAME_LEN 100
UlSqlca Sqlca;
static ul_char const * ConnectionParms =
UL_TEXT( "uid=dba;pwd=sql" )
UL_TEXT( ";dbf=tutcustomer.udb" )
UL_TEXT( ";schema_file=tutcustomer.usm" );
static void handle_error( ul_char const * context ) {
ul_char buf[80];
// Report error details...
_tprintf( _TEXT("Error at '%s' [%ld"),
context ? context : UL_TEXT("?"),
Sqlca.GetSQLCode() );
for( ul_u_long i = 1; i < Sqlca.GetParameterCount(); i++ ) {
Sqlca.GetParameter( i, buf, 80 );
_tprintf( UL_TEXT(", %s"), buf );
}
_tprintf( UL_TEXT("]\n") );
}
// Check for and report errors
#define __HANDLE_ERROR( line ) handle_error( UL_TEXT( "line " ) UL_TEXT( #line ) )
#define _HANDLE_ERROR( line ) __HANDLE_ERROR( line )
#define CHECK_ERROR() (Sqlca.LastCodeOK() ? (void)0 : _HANDLE_ERROR( __LINE__ ))
Connection * open_conn(DatabaseManager * dm, ULSqlca & sqlca) {
Connection * conn;
conn = dm->OpenConnection( Sqlca, ConnectionParms );
if( Sqlca.GetSQLCode() ==
SQLE_ULTRALITE_DATABASE_NOT_FOUND ) {
conn = dm->CreateAndOpenDatabase( sqlca, ConnectionParms );
if( conn == NULL ) {
handle_error( UL_TEXT("create database") );
} else {
_tprintf( UL_TEXT("Connected to a new database.\n") );
}
}
else {
_tprintf( UL_TEXT("Connected to an existing database.\n") );
}
return( conn );
}Copy the main method below into customer.cpp. The main method carries out the following tasks:
Instantiates a DatabaseManager object. All UltraLite objects are created from the DatabaseManager object.
Opens a connection to the database.
Closes the connection and shuts down the database manager.
int main() {
DatabaseManager * dm;
Connection * conn;
Sqlca.Initialize();
dm = ULInitDatabaseManager( Sqlca );
if( dm == UL_NULL ){
// You may have mismatched UNICODE
// vs. ANSI runtimes.
Sqlca.Finalize();
return 1;
}
conn = open_conn( dm );
conn->Release();
dm->Shutdown( Sqlca );
Sqlca.Finalize();
return 0;
}Compile and link the Customer class.
The particular method you use to compile the class depends on your compiler. The following instructions are for the Microsoft Visual C++ command line compiler using a makefile.
From a command prompt, browse to your tutorial directory.
Create a makefile named makefile. In the makefile, set the following compiler options:
CompileOptions = /c /nologo /W3 \ /Od /Zi /DWIN32 /DUL_USE_DLL
In the makefile, add directories to your include path as follows:
IncludeFolders = /I"$(ASANY9)\h"
In the makefile, add directories to your libraries path as follows:
LibraryFolders = \ /LIBPATH:"$(ASANY9)\ultralite\win32\386\lib"
In the makefile, add libraries to your linker command line options as follows:
Libraries = ulimp.lib
The UltraLite runtime library (ulimp.lib) is an ASCII version of the library. If you choose the Unicode version (ulimpw.lib), you should add /DUNICODE to the compiler options.
In the makefile, add an instruction for compiling the application:
customer.obj: customer.cpp cl $(CompileOptions) $(IncludeFolders) \ customer.cpp
In the makefile, add an instruction for linking the application.
customer.exe: customer.obj link /NOLOGO /DEBUG customer.obj \ $(LibraryFolders) $(Libraries) customer.obj
Run the makefile as follows:
nmake
An executable named customer.exe is created.
Run the application.
At the command prompt, enter customer.
The first time you run the application, it should write the following text to the command line:
Connected to a new database.
Subsequent times, it writes the following text to the command line:
Connected to an existing database.