第 1 课：创建数据库并连接到数据库

在第一个过程中，创建一个本地 UltraLite 数据库。然后编写、编译并运行一个访问创建的数据库的 C++ 应用程序。

♦ 创建 UltraLite 数据库

将 c:\vendor\visualstudio8\VC\atlmfc\src\atl 添加到 INCLUDE 环境变量。
创建一个目录，用于存放在本教程中要创建的文件。

在本教程的剩余部分中，假定此目录是 C:\tutorial\cpp\。如果您创建具有不同名称的目录，则使用该目录代替 C:\tutorial\cpp\。
在 Sybase Central 中使用 UltraLite，在新目录中创建一个名为 ULCustomer.udb 且具有以下特性的数据库。

有关在 Sybase Central 中使用 UltraLite 的详细信息，请参见使用 [创建数据库向导] 创建数据库。

将名为 ULCustomer 的表添加到数据库。对 ULCustomer 表使用以下说明：

列名	数据类型（大小）	列是否允许 NULL 值？	缺省值	主键
cust_id	integer	否	自动增量	升序
cust_name	varchar(30)	否	无

在 Sybase Central 中断开与数据库的连接，否则可执行文件将无法进行连接。

♦ 连接到 UltraLite 数据库

在 Microsoft Visual C++ 中，选择 [File] » [New]。
在 [Files] 选项卡上，选择 [C++ Source File]。
在教程目录中将文件另存为 customer.cpp。

包括 UltraLite 库并使用 UltraLite 命名空间。

将以下代码复制到 customer.cpp：

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

此代码段定义一个名为 Tutca 的 UltraLite SQL 通信区 (ULSqlca)。

有关使用 UltraLite 命名空间来简化类声明的详细信息，请参见使用 UltraLite 命名空间。

定义连接到数据库的连接参数。

在此代码段中，连接参数是硬编码的。在实际的应用程序中，这些位置可在运行时指定。

将以下代码复制到 customer.cpp。

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

有关连接参数的详细信息，请参见UltraLite_Connection_iface 类。

特殊字符处理

文件名位置字符串中出现的反斜线字符必须使用前导反斜线字符进行转义。

定义一个方法，用于处理应用程序中出现的数据库错误。

UltraLite 提供通知应用程序出错的回调机制。在开发环境中，作为一种处理意外错误的机制，此函数很有用。生产应用程序通常包括用于处理所有常见错误情况的代码。应用程序可在每次调用 UltraLite 函数之后检查错误，也可以选择使用错误回调函数。

下面是一个回调函数示例。

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

在 UltraLite 中，错误 SQLE_NOTFOUND 常用于控制应用程序流。发出此错误信号，标记结果集循环结束。上面编码的通用错误处理程序不为此错误情况输出消息。

有关错误处理的详细信息，请参见处理错误。

定义打开到数据库的连接的方法。

如果数据库文件不存在，则显示错误消息，否则建立连接。

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

实现 main 方法以执行以下任务：

实例化 DatabaseManager 对象。所有 UltraLite 对象都创建自 DatabaseManager 对象。
注册错误处理函数。
打开与数据库的连接。
关闭连接并关闭数据库管理器。

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

编译并链接源文件。

您编译源文件所用的方法取决于您的编译器。以下是对使用生成文件 (makefile) 的 Microsoft Visual C++ 命令行编译器的说明：

打开命令提示符，然后更改至教程目录。
创建一个名为 makefile 的生成文件。
在生成文件中，将目录添加到包括路径。
IncludeFolders=/I"$(SQLANY11)\SDK\Include"

在生成文件中，将目录添加到库路径。

LibraryFolders=/LIBPATH:"$(SQLANY11)\UltraLite\win32\386\Lib\vs8"

在生成文件中，将库添加到链接器选项。
Libraries=ulimp.lib
UltraLite 运行时库名为 ulimp.lib。

在生成文件中，设置编译器选项。您必须在一行上输入这些选项。

CompileOptions=/c /nologo /W3 /Od /Zi /DWIN32 /DUL_USE_DLL

在生成文件中，添加链接应用程序的指令。

customer.exe: customer.obj
   link /NOLOGO /DEBUG customer.obj $(LibraryFolders) $(Libraries)

在生成文件中，添加编译应用程序的指令。

customer.obj: customer.cpp
   cl $(CompileOptions) $(IncludeFolders) customer.cpp

运行生成文件。
nmake
这将创建一个名为 customer.exe 的可执行文件。

运行应用程序。

在命令提示符下，输入 customer。