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

SQL Anywhere 10.0.1 » UltraLite - C and C++ Programming » Tutorial: Build an Application Using the C++ API

Introduction to UltraLite C++ development Next Page

Lesson 1: Create database and connect to database


In the first procedure, you create a local UltraLite database. You then write, compile, and run a C++ application that accesses the database you created.

To create an UltraLite database
  1. Create a directory to hold the files you 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\ .

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

    For more information about using UltraLite in Sybase Central, see Creating an UltraLite database from Sybase Central.

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

    Column nameData type (size)Column allows NULL values?Default valuePrimary Key
    cust_idintegerNoautoincrementascending
    cust_namevarchar(30)NoNone
Connecting to the UltraLite database
  1. In Microsoft Visual C++ .NET, choose File > New.

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

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

  4. Include the UltraLite libraries and use the UltraLite namespace.

    Copy the code below into customer.cpp:

    #include <stdafx.h>
    #include "uliface.h"
    using namespace UltraLite;
    #define MAX_NAME_LEN 100
    ULSqlca Tutca;

    This code fragment defines an UltraLite SQL communications area (ULSqlca) named Tutca.

    For more information about using the UltraLite namespace to make class declarations simpler, see Using the UltraLite namespace.

  5. 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 =
      UL_TEXT( "UID=DBA;PWD=sql" )
      UL_TEXT( ";DBF=C:\\tutorial\\cpp\\ULCustomer.udb" );

    For more information about connection parameters, see UltraLite_Connection_iface class.

    Special Character handling

    A backslash character that appears in the file name location string must be escaped by a preceding backslash character.

  6. 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 function 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 function or can choose to use an error callback function.

    This is a sample callback function.

    ul_error_action UL_GENNED_FN_MOD MyErrorCallBack(
     SQLCA *  Tutca,
     ul_void * user_data,
     ul_char * message_param )
    {
        ul_error_action rc;
        
        (void) user_data;
    
        switch( Tutca->sqlcode ){
            // The following error is used for flow control - don't report it here
            case SQLE_NOTFOUND:
                rc = UL_ERROR_ACTION_CONTINUE;  
            break;
    
            default:
                if (Tutca->sqlcode >= 0) { // warning or success
                    rc = UL_ERROR_ACTION_DEFAULT; 
                } else { // negative is real error
                    _tprintf( _TEXT( "Error %ld: %s\n" ), Tutca->sqlcode, message_param );
                    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.

  7. 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.

    Connection * open_conn( DatabaseManager * dm ) {
      Connection * conn = dm->OpenConnection( Tutca, ConnectionParms );
    
      if( conn == UL_NULL ) {
          _tprintf( _TEXT("Unable to open existing database.\n") );
       }
      return conn;
    }
  8. Implement the main method to carry out the following tasks:

    int main() {
      ul_char buffer[ MAX_NAME_LEN ];
      
      Connection * conn;
    
      Tutca.Initialize();  
    
      ULRegisterErrorCallback(
        Tutca.GetCA(), MyErrorCallBack,
        UL_NULL, buffer, sizeof (buffer));
    
      DatabaseManager * dm = ULInitDatabaseManager( Tutca );
      
      conn = open_conn( dm );
      
      if( conn == UL_NULL ){
       dm->Shutdown( Tutca );
          Tutca.Finalize();
          return 1;  
      }
      // main processing code to be inserted here 
      dm->Shutdown( Tutca );
      Tutca.Finalize();
      return 0;
    }
  9. 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:

  10. Run the application.

    At the command prompt, enter customer.