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

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

♦ 创建 UltraLite 数据库

将 VCINSTALLDIR 环境变量设置到 Visual C++ 安装的根目录（如果该变量不存在）。
将 %VCINSTALLDIR%\VC\atlmfc\src\atl 添加到 INCLUDE 环境变量。
创建一个目录，用于存放在本教程中要创建的文件。

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

将名为 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 库。

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

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

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

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

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

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

注意

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

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

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

以下代码是一个示例回调函数：

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
                ul_char etext[ MAX_NAME_LEN ];
                error->GetString( etext, MAX_NAME_LEN );
                _tprintf( "Error %ld: %s\n", code, etext );
                rc = UL_ERROR_ACTION_CANCEL;
            }
        break;
     }
    return rc;
 }

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

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

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

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

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

注册错误处理方法。
打开与数据库的连接。
关闭连接并关闭数据库管理器。

int main() {
    ULConnection *	conn;

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

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

    // Main processing code goes here ...
    do_insert( conn );
    do_select( conn );
    do_sync( conn );

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

编译并链接源文件。

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

打开命令提示符，然后更改至教程目录。
创建一个名为 makefile 的生成文件。

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

IncludeFolders=/I"$(SQLANY12)\SDK\Include"

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

LibraryFolders=/LIBPATH:"$(SQLANY12)\UltraLite\Windows\x86\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

运行 vsvars32.bat。

%VCINSTALLDIR%\Tools\vsvars32.bat

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

运行应用程序。

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

应用程序将连接到数据库，然后断开连接。如果您未看到任何错误消息，则应用程序会成功运行。

另请参见

使用DocCommentXchange讨论此页。