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. Set the VCINSTALLDIR environment variable to the root directory of your Visual C++ installation if the variable does not already exist.

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

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

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

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

    Column name Data type (size) Column allows NULL values? Default value Primary Key
    cust_id integer No autoincrement ascending
    cust_name varchar(30) No None
  6. Disconnect from the database in Sybase Central, otherwise your executable will not be able to connect.

 To connect to the UltraLite database
  1. In Microsoft Visual C++, 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.

    Copy the code below into customer.cpp:

    #include <tchar.h>
    #include <stdio.h>
    #include "ulcpp.h"
    #define MAX_NAME_LEN 100
  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 =
        "UID=DBA;PWD=sql;DBF=C:\\tutorial\\cpp\\ULCustomer.udb";

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

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

  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.

    static ULConnection * open_conn( void ) 
    {
        ULConnection * conn = ULDatabaseManager::OpenConnection( ConnectionParms );
        if( conn == UL_NULL ) {
          _tprintf("Unable to open existing database.\n");
       }
      return conn;
    }
  8. Implement the main method to carry out the following tasks:

    • Registers the error handling method.

    • Opens a connection to the database.

    • Closes the connection and finalizes the database manager.



    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;
    }
  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:

    • Open a command prompt and change to your tutorial directory.

    • Create a makefile named makefile.

    • In the makefile, add directories to your include path.

      IncludeFolders=/I"$(SQLANY12)\SDK\Include"
    • In the makefile, add directories to your libraries path.

      LibraryFolders=/LIBPATH:"$(SQLANY12)\UltraLite\win32\386\Lib\vs8"
    • In the makefile, add libraries to your linker options.

      Libraries=ulimp.lib

      The UltraLite runtime library is named ulimp.lib.

    • In the makefile, set compiler options. You must enter these options on a single line.

      CompileOptions=/c /nologo /W3 /Od /Zi /DWIN32 /DUL_USE_DLL
    • In the makefile, add an instruction for linking the application.

      customer.exe: customer.obj
         link /NOLOGO /DEBUG customer.obj $(LibraryFolders) $(Libraries)
    • In the makefile, add an instruction for compiling the application.

      customer.obj: customer.cpp
         cl $(CompileOptions) $(IncludeFolders) customer.cpp
    • Run vsvars32.bat.

      %VCINSTALLDIR%\Tools\vsvars32.bat
    • Run the makefile.

      nmake

      This creates an executable named customer.exe.

  10. Run the application.

    At the command prompt, enter customer.