PowerBuilder API 中文版参考与实践指南-优快云博客

本文链接：https://blog.youkuaiyun.com/weixin_42609225/article/details/144280197

简介：PowerBuilder API 是PowerBuilder语言中用于数据库应用程序开发的部分，支持数据的CRUD操作等。本资源提供了中文版的CHM帮助文件，消除了语言障碍，方便中国用户学习和使用。同时，包括了"api32.chm"和"pbapi"等文件，提供了详尽的函数、方法描述和示例代码，助开发者深入理解PB API的使用。 pb api

1. PB API概述与数据库交互

PowerBuilder（PB）是一种流行的开发工具，主要用于构建高性能、多层式的企业级应用。其中PB API作为PowerBuilder的编程接口，是连接前端应用与后端数据库的桥梁。

PB API的基础架构与工作原理

PB API本质上是一系列预先编程的函数库，它们使得开发者能够快速进行数据库连接、数据检索、事务处理等操作。这些函数库经过高度优化，以实现高效的数据通信和处理，适用于多种数据库管理系统。

PB API在数据库交互中的角色

在与数据库的交互中，PB API允许开发者使用SQL语句和存储过程来管理数据。通过PB API，可以实现数据的增删改查操作，进而使得应用程序能够对数据进行有效的读取和更新。

PB API的版本迭代与特性比较

随着技术的发展，PB API也在不断迭代更新，新版本往往会引入新的特性、优化性能，或者增强安全性。例如，新版本可能提供了对现代数据库系统的更好的支持，或在函数库中加入新的工具函数来简化开发过程。在选择使用某个版本的PB API时，需要对不同版本间的功能差异进行仔细比较，以便选择最适合项目需求的版本。

2. 中文CHM帮助文件的重要性

2.1 CHM帮助文件的制作与编辑

2.1.1 CHM文件的生成过程

CHM（Compiled HTML Help）文件是一种非常流行的电子文档格式，广泛用于软件的帮助系统中。它的生成过程通常涉及以下步骤：

内容收集 ：首先，需要收集所有需要纳入帮助文档的信息，这包括说明文本、图片、表格、索引以及相关链接等。
文档编写 ：使用HTML编辑器（例如Dreamweaver或Notepad++）编写各个帮助页面的HTML代码。在这一阶段，还可以添加CSS样式和JavaScript脚本以增强文档的可读性和交互性。
目录和索引设置 ：为了便于用户查询，通常需要创建一个目录（TOC）和索引（Index）。目录方便用户导航至特定帮助主题，索引则提供关键词搜索功能。
编译CHM ：使用工具如Microsoft HTML Help Workshop或更先进的工具比如HelpNDoc进行编译。编译器将HTML页面、图片、样式表、脚本等资源打包成单一的CHM文件。
测试与更新 ：在生成CHM文件后，需要对其内容和功能进行全面测试，确保链接正确、索引和目录都能正常工作。一旦发现问题或需要更新文档内容，需要重新编辑和编译CHM文件。

下面是一个简单的CHM生成过程的示例代码块，使用HTML Help Workshop工具的命令行指令：

hhc.exe "C:\path\to\project\yourproject.hhp"

这条指令会调用 hhc.exe 工具编译位于 C:\path\to\project\ 路径下名为 yourproject.hhp 的项目文件。

2.1.2 CHM编辑工具的选择与使用

CHM文件的编辑工具选择很重要，因为它影响了CHM文件最终的用户体验和功能实现。以下是一些流行的CHM编辑工具：

Microsoft HTML Help Workshop ：这是最原始的CHM编辑工具，虽然已经不再积极维护，但是很多开发者依然使用它，因为它稳定且功能全面。
HelpNDoc ：这是现代开发者常用的CHM编辑工具，它提供了强大的模板系统、WYSIWYG编辑器以及自动目录和索引生成等功能。
MadCap Flare ：这是专业级的帮助文档和在线帮助系统生成工具，支持CHM文件的创建，并且适用于复杂的多平台帮助系统开发。

选择合适的工具后，可以按照以下步骤使用这些工具生成CHM文件：

创建一个新的项目，并为项目指定文件和设置。
添加或导入HTML页面、图像和其他媒体文件。
定义文件之间的链接和导航结构。
设定索引和目录项。
编译项目文件，生成CHM文件。

2.1.3 如何将CHM集成到开发环境中

将CHM帮助文件集成到开发环境中，通常需要以下几个步骤：

创建集成接口 ：创建一个用户界面元素，比如一个菜单项或者工具栏按钮，用于打开帮助文件。
设置CHM文件路径 ：在开发工具中设置CHM文件的存储路径，确保程序可以正确地访问到该文件。
编写代码以打开CHM文件 ：在应用程序中编写代码来响应用户的点击事件，并打开CHM文件。以下是一个简单的示例代码块，演示如何在Windows环境下打开CHM文件：

System.Diagnostics.Process.Start(@"C:\path\to\yourhelp.chm");

用户体验优化 ：如果可能，实现搜索功能的集成和上下文相关的帮助内容显示。

2.2 CHM帮助文件的优势与挑战

2.2.1 CHM在文档查阅中的便捷性

CHM文件格式具有以下优势：

快速访问信息 ：用户能够快速通过目录和索引定位到需要的内容。
离线访问 ：CHM文件可以在没有互联网连接的情况下访问，非常适合需要离线文档的应用程序。
安全性 ：CHM文件可以设置密码保护，限制访问权限，保护内容不被未经授权的用户查看。

2.2.2 CHM文件的维护与更新问题

CHM文件的维护和更新面临如下挑战：

更新困难 ：一旦用户已经下载了CHM文件，任何的更新都需要用户手动下载更新版本，增加了用户的负担。
版本控制 ：维护多个版本的CHM文件可能会导致混淆和管理上的复杂性。

为了克服这些问题，可以采取以下策略：

提供在线更新 ：为用户提供一个简单的更新机制，当新的CHM文件可用时，通过网络通知用户并提供下载选项。
文件版本控制 ：在文件名中加入版本号，确保用户总是使用最新版本的文档。

2.2.3 跨平台兼容性讨论

尽管CHM文件在Windows平台上运行良好，但是它在其他操作系统上并不支持，特别是在macOS和Linux上。这意味着跨平台软件无法使用CHM文件作为其帮助系统。对于这种情况，开发者可能需要考虑以下替代方案：

多平台帮助文件 ：为不同的操作系统创建不同格式的文档，比如使用PDF或在线文档作为替代方案。
Web帮助系统 ：创建一个在线帮助系统，它可以在所有主流操作系统和设备上访问。

表格：CHM文件与其他常见帮助文档格式的比较

| 格式 | 优点 | 缺点 | 适用平台 | | ---- | ---- | ---- | -------- | | CHM | 离线使用、索引和目录支持、Windows原生支持 | 无跨平台支持、更新不便捷 | Windows | | PDF | 跨平台、易于分享、可打印 | 不便于搜索、编辑困难 | 所有平台 | | HTML | 跨平台、易于更新和维护、搜索引擎优化 | 缺少离线支持、格式可能不一致 | 所有平台 | | Web | 实时更新、跨平台、可交互 | 需要稳定的网络连接 | 所有平台 |

通过以上内容，我们了解了CHM帮助文件的制作过程、编辑工具的选择、集成方式，以及它们的优势和面对的挑战。这将帮助开发人员和文档制作人员更好地利用CHM文件，为用户提供更好的文档阅读体验。

3. 函数与方法的详细说明

在PB API的使用过程中，函数与方法是执行具体任务的核心组件。了解它们的分类、特点、参数以及应用场景对于高效编程至关重要。接下来，我们将深入探讨PB API函数的不同分类、常用函数与方法的实例，以及它们在实际工作中的应用。

3.1 PB API函数的分类与特点

3.1.1 核心函数库的组成

PB API中的核心函数库是开发者日常工作中的基础。核心函数库包含了大多数应用程序所需的标准功能，如字符串处理、日期时间管理、文件系统操作等。这一库是由一系列经过优化的函数组成，它们可以执行各种常见的操作，并且通常都具备高度的跨平台兼容性。

3.1.2 各类型函数的应用场景

PB API将函数进行了分类，其中主要的有数据操作函数、网络通信函数、系统管理函数等。数据操作函数主要用于与数据库进行交云，实现数据的增删改查功能。网络通信函数允许开发者在应用程序中实现客户端与服务器端的通信，以获取或发送数据。系统管理函数提供了对操作系统的底层访问能力，比如进程管理和文件管理。

3.1.3 函数与方法的参数与返回值

每个函数或方法都有一套特定的参数，这些参数定义了函数的行为。参数的类型可以是基本数据类型，也可以是复杂类型如对象和结构体。函数调用后通常会返回一个值，这个值可以表示执行成功或失败，或者可以是操作结果的具体内容。

3.2 常用函数与方法的实例剖析

接下来，我们将通过几个常用的函数与方法实例，来进一步理解如何在PB API中实现具体的操作。

3.2.1 数据库操作相关的函数

在PB API中，数据库操作函数是执行SQL语句并处理结果集的关键。例如， Execute() 函数可以执行一个SQL命令，并返回一个结果集对象，通过它我们可以进一步操作数据。

// PB API中的Execute函数示例
SQLCA.DBMS = "ODBC"
SQLCA.Database = "YourDatabaseName"
SQLCA.ServerName = "YourServerName"
SQLCA.UserName = "YourUsername"
SQLCA.Password = "YourPassword"

Connect;
SQLCA.AutoCommit = True
SQLCA.LogPass = False

string ls_query, ls_message
ls_query = "SELECT * FROM your_table"
EXECUTE IMMEDIATE :ls_query;

// 处理返回的数据，使用游标
FOR EACH rowname IN :SQLCA
    // 根据字段名访问数据，假设有一个字段名为Field1
    ls_message = rowname.Field1
    MessageBox("Result", ls_message)
END FOR
Disconnect;

在以上示例中，我们使用了PB API的数据库连接和执行查询操作。代码逻辑清晰，易于理解。其中， EXECUTE IMMEDIATE 用于执行动态SQL命令，而 FOR EACH 则用于遍历返回的结果集。

3.2.2 字符串处理与转换函数

字符串处理在任何编程语言中都非常重要。PB API提供了丰富的字符串处理函数，如 String() , Left() , Right() , Mid() 等。这些函数能够实现字符串的拼接、截取、格式化等操作。

// 字符串函数使用示例
string ls_test, ls_first, ls_last
ls_test = "John Doe"
ls_first = Left(ls_test, 4) // 提取前四个字符
ls_last = Right(ls_test, 3) // 提取后三个字符

// 拼接字符串
string ls_fullname
ls_fullname = ls_first + " " + ls_last
MessageBox("Full Name", ls_fullname)

在上述示例中，我们展示了如何使用PB API中的字符串函数对字符串进行简单的操作。

3.2.3 文件与目录管理函数

文件和目录管理对于应用程序来说也是基本需求。PB API提供了诸如创建、读取、修改、删除文件和目录等功能。例如， FileOpen() , FileRead() , FileWrite() , FileDelete() 等函数是常用的文件操作函数。

// 文件操作函数使用示例
// 假设我们有一个文件路径
string ls_file_path
ls_file_path = "C:\path\to\your\file.txt"

// 打开文件
int li_file_id = FileOpen(ls_file_path, StreamMode!, Write!, LockRead!, ShareDenyNone!)
IF li_file_id < 0 THEN
    MessageBox("Error", "无法打开文件")
ELSE
    // 写入文件内容
    FileWrite(li_file_id, "Hello, PB API!")
    // 关闭文件
    FileClose(li_file_id)
    MessageBox("Success", "文件写入成功")
END IF

在该示例中，我们演示了如何使用PB API打开一个文件，向其中写入数据，并最终关闭文件。

通过上述章节的内容，我们对PB API中的函数和方法有了较为全面的认识，包括它们的分类、特点、参数以及应用场景。在下一节中，我们将进一步探索PB API在数据类型转换与错误处理方面的机制与策略。

4. 错误处理与数据类型转换

4.1 错误处理机制与策略

4.1.1 错误捕获与异常处理

在任何软件开发中，错误处理都是一项基础而重要的任务。PB API 提供了一系列机制和策略来有效地处理运行时发生的错误，从而保证软件的健壮性和稳定性。错误捕获与异常处理是确保程序流程可预测和可控的关键环节。

错误捕获通常涉及到编程中的异常处理，比如在 PB API 中，可以使用 Try...Catch...Finally 结构来捕捉代码执行过程中可能抛出的异常。这一结构能够捕获由系统、数据库或其他资源抛出的异常，允许开发者在程序中加入自定义的错误处理逻辑。在 PB 中，一个简单的异常处理示例如下：

Try
   // 尝试执行的代码块
   // 如果出现错误，则会抛出异常
Catch ex As Exception
   // 捕获异常，ex 是异常对象，包含错误信息
   MessageBox("错误：", ex.Message) // 显示错误信息
Finally
   // 总是会执行的代码块，不论是否发生异常
End Try

在上述代码块中， Try 代码块内包含可能引发异常的代码， Catch 代码块则负责处理捕获到的异常。 Finally 代码块的内容不管是否发生异常都将被执行。这允许开发者在异常发生时执行清理任务，如关闭数据库连接、释放资源等。

4.1.2 日志记录与问题定位

有效的错误日志记录对于问题定位与调试至关重要。PB API 中的错误日志记录包括记录关键操作的执行、系统状态的变化、异常和错误信息等。日志可以帮助开发者快速地追溯问题原因，对性能瓶颈进行分析，同时也有助于应用程序的安全审计。

开发者可以使用 PB 内建的日志记录函数，如 LogMessage 或自定义日志框架来实现日志记录功能。为了日志的可读性和易管理性，通常需要对日志级别进行分类，如 Debug 、 Info 、 Warning 、 Error 和 Fatal 。一个典型的日志记录示例如下：

LogMessage("开始更新操作", Information) // 记录信息级别的日志
LogMessage("发生错误：" + SQLCA.SQLERRText, Error) // 记录错误级别的日志

合理的日志级别可以帮助开发者快速筛选和查看重要信息，而对于错误和异常，还需要结合 Try...Catch...Finally 结构进行深入分析。

4.1.3 常见错误代码解析与预防

在 PB API 的使用中，常常会遇到一些常见的错误代码。理解这些错误代码有助于快速定位和解决问题。例如，错误代码 -121 表示数据库连接失败，而错误代码 -113 则可能表示数据类型不匹配。每个错误代码都对应一种错误类型，开发者可以通过查阅官方文档，了解每一个错误代码的具体含义，并在代码中加入针对性的处理逻辑。

// 检查数据库连接错误代码
If SQLCA.SqlCode = -121 Then
   // 处理数据库连接错误
   MessageBox("数据库连接失败！请检查数据库服务器是否运行以及连接信息是否正确。")
End If

错误的预防通常是在编码阶段就需要进行的，包括但不限于使用强类型变量、进行输入验证、定期测试代码以及使用静态代码分析工具来发现潜在问题。通过这些策略，开发者可以在程序投入生产环境之前，最大程度地减少可能发生的错误。

4.2 数据类型转换的原理与方法

4.2.1 PB API支持的数据类型概览

PB API 支持多种数据类型，并且能够处理不同类型之间的转换。PB API 基础数据类型包括整型、浮点型、字符串、日期和时间等。了解这些数据类型及其转换规则对于开发者来说是基本功。

除了基础数据类型外，PB API 还支持更复杂的数据结构，如结构体、数组和对象等。在进行数据类型转换时，开发者必须了解不同类型之间转换的规则和限制。

4.2.2 数据类型转换规则与技巧

数据类型转换规则是指在 PB API 中不同数据类型间转换的正确方式。数据类型转换可以是显式的，也可以是隐式的。显式转换通常需要使用到转换函数，而隐式转换则在某些情况下由编译器自动完成。

例如，将字符串转换为数字，开发者可以使用 Val 函数：

String myString = "123"
Number myNumber = Val(myString) // 正确的显式转换

反之，将数字转换为字符串可以使用 String 函数：

Number myNumber = 123
String myString = String(myNumber) // 正确的显式转换

进行类型转换时需格外注意数据的精度和范围，因为不恰当的转换可能导致数据丢失或错误。例如，尝试将超出 Integer 范围的数字转换为 Integer 类型将引发错误。

4.2.3 转换过程中的常见问题及解决

在数据类型转换的过程中，开发者可能会遇到一些问题，如数据溢出、数据丢失或数据格式不匹配等。为了处理这些问题，开发者需要掌握一些常见的解决技巧。

以下是一些常见的类型转换问题及其解决方法：

数据溢出 ：在转换较大范围的数值类型到较小范围的数值类型时，可能会发生溢出。解决此类问题通常需要先检查数值是否在目标类型的有效范围内。
数据丢失 ：浮点数到整型的转换可能造成小数部分的数据丢失。在转换前，开发者需要决定是否需要对数值进行四舍五入或其他处理。
数据格式不匹配 ：在进行字符串与日期时间类型转换时，格式不匹配会导致转换失败。开发者需要确保字符串的格式与目标类型兼容，或者使用适当的日期时间解析函数。

正确处理数据类型转换能够提高程序的健壮性和用户体验。因此，开发者需要在编码阶段就对可能的转换问题进行预见和预防。

通过本章节的介绍，我们了解了 PB API 中错误处理和数据类型转换的基础知识，包括错误捕获和异常处理的机制，日志记录在问题定位中的作用，以及数据类型转换的规则和技巧。这些内容对于保证程序的稳定运行和提升用户体验至关重要。下一章节，我们将探讨数据窗口对象的操作，包括其创建、配置以及高级功能的实现。

5. 数据窗口对象的操作

5.1 数据窗口对象的创建与配置

5.1.1 数据窗口的设计与属性设置

数据窗口对象是PowerBuilder（PB）中一个非常强大的功能组件，允许用户直观地与数据库交互。它通过提供不同的数据展示样式来满足用户的各种需求。设计数据窗口对象需要关注几个核心的步骤，从基本的数据结构和布局到更高级的样式和格式化。

在PB中，创建一个数据窗口对象通常有两种方式：使用DataWindow painter，或者通过编程方式。在这两种方法中，数据窗口的属性设置是关键，因为它们定义了数据窗口的行为和外观。

属性设置包括：

Data Source ：确定数据窗口将展示的数据源类型，比如是直接绑定到一个数据库表还是使用一个查询结果。
Data Layout ：定义数据如何在数据窗口中展示，包括列的顺序、宽度等。
Band ：数据窗口的设计基础，可将数据窗口分成不同的Band，如Header、Detail和Footer Band，以便于对数据进行分组和汇总。

5.1.2 数据窗口与数据源的绑定

数据窗口与数据源的绑定是将数据窗口对象和数据库中的数据连接起来的过程。PB提供了多种方法来完成这一过程，例如通过SQL语句、存储过程或直接与表绑定。

使用SQL语句 ：这是一种灵活的方法，可以定制哪些列和行被检索。例如：

SELECT customer_id, company_name, contact_name, address, city, postal_code, country
FROM customers
WHERE country = 'USA'
ORDER BY company_name

这个SQL查询定义了一个数据窗口，它仅显示在“USA”的客户信息，并按公司名称排序。

使用存储过程 ：存储过程提供了更多的灵活性，能够执行更复杂的业务逻辑。

CREATE PROCEDURE GetCustomersByCountry
   @country varchar(25)
AS
BEGIN
   SELECT customer_id, company_name, contact_name, address, city, postal_code, country
   FROM customers
   WHERE country = @country
   ORDER BY company_name
END

数据窗口可以绑定到该存储过程，并传递参数。

直接与表绑定 ：对于简单的场景，可以直接将数据窗口绑定到数据库表。

5.1.3 数据窗口的样式与格式化

数据窗口对象的样式和格式化是提升用户体验的关键。PB允许开发者在DataWindow painter中详细设置字体、颜色、边框、背景图像以及数据的显示格式等。

Font ：设置文本的字体类型、大小和样式。
Color ：定制文本和背景颜色。
Border ：定义单元格的边框。
Format ：根据字段数据类型定义显示格式，比如日期、货币和百分比等。

此外，可以通过编程方式动态地应用样式和格式化。以下是一个简单的例子：

// 设置字体
lo_datawindowcontrol.GetItem(1).Font.Name = "Arial"
lo_datawindowcontrol.GetItem(1).Font.PointSize = 10

// 设置背景颜色
lo_datawindowcontrol.GetItem(1).BackGround.Color = RGB(255, 255, 255)

// 设置数据显示格式
lo_datawindowcontrol.GetItem(1).DataFormat = "000.00"

在上述代码块中，首先获取数据窗口控件中的第一个数据项，然后对其进行格式化设置，包括字体名称、字号和背景颜色。

5.2 数据窗口的高级功能与应用

5.2.1 动态SQL语句与数据窗口

在许多情况下，数据窗口需要展示由用户提供的动态查询条件所生成的数据。动态SQL提供了一种方式，使得数据窗口可以根据运行时提供的条件来展示结果。

通过编程，可以将用户输入的参数拼接到SQL语句中，生成动态SQL语句：

string ls_sql
string ls_country

ls_country = "USA" // 假设从用户输入获得此值

ls_sql = "SELECT customer_id, company_name, contact_name, address, city, postal_code, country " +
         "FROM customers " +
         "WHERE country = '" + ls_country + "' " +
         "ORDER BY company_name"

lo_datawindowcontrol.SetTransObject(SQLCA) // 设置数据窗口的事务对象
lo_datawindowcontrol.SetSQLText(ls_sql) // 应用动态SQL语句
lo_datawindowcontrol.Retrieve() // 执行检索

5.2.2 数据窗口的分组与排序

数据窗口中的分组与排序功能极大地增强了数据展示的能力，使得数据的可视化更加直观。

分组：分组是将具有相同值的行放在一起来集中展示信息。例如，可以根据“国家”字段将客户分组。

lo_datawindowcontrol.SetTransObject(SQLCA)
lo_datawindowcontrol.SetTransObject(SQLCA)
lo_datawindowcontrol.SetTransObject(SQLCA)
lo_datawindowcontrol.SetTransObject(SQLCA)

lo_datawindowcontrol.SetGroup(1, "country", "Ascending") // 按国家分组，并以升序排列
lo_datawindowcontrol.Retrieve()

排序：排序功能允许用户根据特定字段对数据进行排序，这可以通过DataWindow painter设置，也可以通过编程设置。

lo_datawindowcontrol.SetTransObject(SQLCA)
lo_datawindowcontrol.SetSort("company_name, ascending") // 按公司名称升序排序
lo_datawindowcontrol.Retrieve()

5.2.3 高级用户界面控件的应用

PB API提供了广泛的用户界面控件，这些控件可以与数据窗口对象结合使用，增强应用程序的交互性和用户体验。例如，使用树控件（Tree Control）和数据窗口来展示具有父子关系的数据。

以下是一个使用树控件与数据窗口的简单示例：

// 假设已经创建了Tree控件和DataWindow控件
Tree t
DataWindow dw

// 假设已经填充了树控件的节点

// 当用户选择树控件中的一个节点时，我们需要根据该节点的值设置数据窗口的数据源
t.SelectionMade()
string ls_node_value = t.GetSelectedData()

// 从树节点获取值，并使用它来过滤数据窗口的数据
dw.SetTransObject(SQLCA)
dw.SetFilter("country = '" + ls_node_value + "'")
dw.Retrieve()

在这个例子中，当用户在树控件中选择一个节点时，它会触发一个事件，通过这个事件我们获取选中节点的值，并用这个值来过滤数据窗口中的数据。

通过这些高级功能，开发者可以创建更加复杂和功能丰富的应用程序，从而满足更高级的业务需求。