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. Add c:\vendor\visualstudio8\VC\atlmfc\src\atl to your INCLUDE environment variable.

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

3. 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 Create a database with the Create Database Wizard.

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

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

Connecting 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 and use the UltraLite namespace.

   Copy the code below into customer.cpp:

   #include <tchar.h> #include <stdio.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:

   • Instantiates a DatabaseManager object. All UltraLite objects are created from the DatabaseManager object.

   • Registers the error handling function.

   • Opens a connection to the database.

   • Closes the connection and shuts down the database manager.

   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:

   • 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"$(SQLANY11)\SDK\Include"

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

     LibraryFolders=/LIBPATH:"$(SQLANY11)\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 the makefile.

     nmake

     This creates an executable named customer.exe.

10. Run the application.

    At the command prompt, enter customer.