Set the VCINSTALLDIR environment variable to the root directory of your Visual C++ installation if the variable does not already exist.

Add %VCINSTALLDIR%\VC\atlmfc\src\atl to your INCLUDE environment variable.

Create a directory to contain the files you will create in this tutorial.

The remainder of this tutorial assumes that this directory is C:\tutorial\cpp\. If you create a directory with a different name, use that directory instead of C:\tutorial\cpp\.

Using UltraLite in Sybase Central, create a database named ULCustomer.udb in your new directory with the default characteristics.

For more information about using UltraLite in Sybase Central, see Create a database with the Create Database Wizard.

Add a table named ULCustomer to the database. Use the following specifications for the ULCustomer table:

Disconnect from the database in Sybase Central, otherwise your executable will not be able to connect.

In Microsoft Visual C++, choose File » New.

On the Files tab, choose C++ Source File.

Save the file as customer.cpp in your tutorial directory.

Include the UltraLite libraries.

Copy the code below into customer.cpp:

#include <tchar.h>
#include <stdio.h>
#include "ulcpp.h"
#define MAX_NAME_LEN 100

Define connection parameters to connect to the database.

In this code fragment, the connection parameters are hard coded. In a real application, the locations might be specified at runtime.

Copy the code below into customer.cpp.

static ul_char const * ConnectionParms =
    "UID=DBA;PWD=sql;DBF=C:\\tutorial\\cpp\\ULCustomer.udb";

For more information about connection parameters, see UltraLite connection parameters.

Define a method for handling database errors in the application.

UltraLite provides a callback mechanism to notify the application of errors. In a development environment this method can be useful as a mechanism to handle errors that were not anticipated. A production application typically includes code to handle all common error situations. An application can check for errors after every call to an UltraLite method or can choose to use an error callback function.

The following code is a sample callback function:

ul_error_action UL_CALLBACK_FN MyErrorCallBack(
    const ULError *  error,
    ul_void *        user_data )
{
    ul_error_action rc;
    an_sql_code code = error->GetSQLCode();
    
    (void) user_data;

    switch( code ){
        // The following error is used for flow control - don't report it here
        case SQLE_NOTFOUND:
            rc = UL_ERROR_ACTION_CONTINUE;  
        break;

        default:
            if (code >= 0) { // warning or success
                rc = UL_ERROR_ACTION_DEFAULT; 
            } else { // negative is real error
                _tprintf( "Error %ld: %s\n", code, error->GetString() );
                rc = UL_ERROR_ACTION_CANCEL;
            }
        break;
     }
    return rc;
 }

In UltraLite, the error SQLE_NOTFOUND is often used to control application flow. That error is signaled to mark the end of a loop over a result set. The generic error handler coded above does not output a message for this error condition.

For more information about error handling, see Handling errors.

Define a method to open a connection to a database.

If the database file does not exist, an error message is displayed, otherwise a connection is established.

static ULConnection * open_conn( void ) 
{
    ULConnection * conn = ULDatabaseManager::OpenConnection( ConnectionParms );
    if( conn == UL_NULL ) {
      _tprintf("Unable to open existing database.\n");
   }
  return conn;
}

Implement the main method to carry out the following tasks:

int main() {
    ul_char		buffer[ MAX_NAME_LEN ];
    ULConnection *	conn;

    ULDatabaseManager::Init();  
    ULDatabaseManager::SetErrorCallback( MyErrorCallBack, NULL );

    conn = open_conn();
    if ( conn == UL_NULL ) {
        ULDatabaseManager::Fini();
        return 1;  
    }

    // Main processing code goes here ...

    conn->Close();
    ULDatabaseManager::Fini();
    return 0;
}

Compile and link the source file.

The method you use to compile the source file depends on your compiler. The following instructions are for the Microsoft Visual C++ command line compiler using a makefile:

Run the application.

At the command prompt, enter customer.