更新日期：2024年09月11日
缺省情况下，
GBase 8s ESQL/C 应用程序不会执行任何 SQL 语句的异常处理。
因此，
除非您显式提供这些代码，否则在执行时继续执行。虽然这种行为对于成功执行、警告和
NOT FOUND 条件可能不太严重，但是在运行错误的情况下可能产生严重后果。
运行错误可能会停止程序执行。除非您在应用程序代码中检查并梳理这些错误，否则
这种行为可能会导致用户混淆和困惑。它还使应用程序处于不一致的状态。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 308 -
在 GBase 8s ESQL/C 应用程序中，请为异常处理选择一致的策略。可以选择以下一
种异常处理策略：
可以在每条 SQL 语句执行后检查，这意味着您在每个 SQL 语句之后包含测试
SQLSTATE （或 SQLCODE）值的代码。
可以使用 WHENEVER 语句将响应关联到每次发生特定类型的异常的时候。
重要： 请在开发前考虑如何在应用程序中执行异常处理，以致于可以采取一致和可
维护的方法。
在执行每条 SQL 语句后检查
要检查异常，可以包含代码来显式测试 SQLSTATE（或 SQLCODE）的值。
提示： 请确定使用 SQLSTATE （和诊断区域）或 SQLCODE（和 sqlca 结构）来
确定异常值。选择的异常处理变量需一致。如果混淆这两个变量，则您创建的代码很难维
护。请记住在这两个选项中 SQLSTATE 更灵活更便捷。
例如，如果要使用 SQLSTATE 检查 CREATE DATABASE 语句是否按期望执行，
则可以使用下图显示的代码。
图: 使用 SQLSTATE 测试错误是否是在 SQL 语句执行期间执行statement
EXEC SQL create database personnel with log;
if(strncmp(SQLSTATE, "02", 2) > 0) /* > 02 is an error */
{
EXEC SQL get diagnostics exception 1
:message = MESSAGE_TEXT, :messlen = MESSAGE_LENGTH;
message[messlen] ='\0'; /* terminate the string. */
printf("SQLSTATE: %s, %s\n", SQLSTATE, message);
exit(1);
}
作为备选方案，可以编写处理任何异常的异常处理函数。您的程序然后可以在每个
SQL 语句之后调用一个异常处理函数。
下图显示的 sqlstate_exception() 函数是异常处理函数的示例，它使用 SQLSTATE
变量和诊断区域检查警告、
NOT FOUND 条件和运行错误。
它在每条 SQL 语句之后调用。
图: 使用 SQLSTATE 的异常处理函数的示例
EXEC SQL select * from customer where fname not like "%y";
sqlstate_exception("select");
⋮
int4 sqlstate_exception(s)
char *s;
{
int err = 0;
if(!strncmp(SQLSTATE, "00", 2) ||
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 309 -
!strncmp(SQLSTATE,"02",2))
return(SQLSTATE[1]);
if(!strncmp(SQLSTATE, "01", 2))
printf("\n********Warning encountered in %s********\n",
statement);
else /* SQLSTATE class > "02" */
{
printf("\n********Error encountered in %s********\n",
statement);
err = 1;
}
disp_sqlstate_err(); /* See the getdiag sample program */
if(err)
{
printf("********Program terminated*******\n\n");
exit(1);
}
/*
* Return the SQLCODE
*/
return(SQLCODE);
}
图 2中显示的 sqlstate_exception() 函数处理下列异常：
如果语句成功，则 sqlstate_exception() 返回零。
如果在 SELECT 或 FETCH 语句发生 NOT FOUND 条件，则 sqlstate_exception()
返回值 2。
如果发生警告或运行错误—即，如果 SQLSTATE 的前两个字节是 "01"（警告）
或大于 "02" （错误）— sqlstate_exception() 函数调用 disp_sqlstate_err() 函数显示异常信
息。0
如果 SQLSTATE 指示错误，
则 sqlstate_exception() 函数使用 exit() 系统调用退出
程序。如果不调用 exit()，则会在发生错误的一个语句后的下一个 SQL 语句继续执行。
要处理错误，sqlstate_exception() 函数可以省略 exit() 调用，并允许执行继续执行。
在此情况中，函数必须返回 SQLSTATE 或 SQLCODE（特定于 GBase 8s 的错误）
值，而此调用的程序可以确定对此运行错误采取哪种操作。
WHENEVER 语句
可以使用 WHENEVER 语句追踪 SQL 语句执行期间的发生异常。
WHENEVER 语句提供下列信息：
检查哪些条件：
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 310 -
SQLERROR 检查 SQL 语句是否失败。当数据库服务器将 SQLCODE
（sqlca.sqlcode）设置为负值，并将 SQLSTATE 的类代码设置为大于 "02" 的值时，应
用程序执行特定的操作。
NOT FOUND 检查是否找到特定的数据。当数据库服务器将 SQLCODE
（sqlca.sqlcode）
设置为 SQLNOTFOUND ，
并将 SQLSTATE 的类代码设置为 "02" 时，
应用程序执行特定的操作。
SQLWARNING 检查 SQL 语句是否生成警告。当数据库服务器将
sqlca.sqlwarn.sqlwarn0
（某些 sqlca.sqlwarn 的其它字段）
设置为 W ，
并将 SQLSTATE
的类代码设置为 "01" 时，应用程序执行特定的操作。
在 Windows™ 环境中，不能在要编译为 DLL 的 GBase 8s ESQL/C 程序中使用
WHENEVER ERROR STOP 约束。.
当特定条件发生时，采用什么操作：
CONTINUE 忽略此异常并在 SQL 语句之后的下一个语句中继续执行。
GO TO label 键异常传输到指定 label 介绍的代码节。
STOP 立即停止程序执行。
CALL 函数名称将执行传输到指定的函数名称。
如果不存在 WHENEVER 语句符合给出的条件，则 GBase 8s ESQL/C 预处理器使用
CONTINUE 作为缺省的操作。
要在每次错误发生时执行 sqlstate_exception() 函数
（如图 2
所示示），可以使用 WHENEVER SQLERROR 语句的 GOTO 操作，如果指定了
WHENEVER 的 SQLERROR 条件，则可以获得与每个 SQL 语句之后检查 SQLCODE
或 SQLSTATE 变量的错误相同的行为。
GOTO 操作的 WHENEVER 语句可以采取以下两种形式：
ANSI 标准形式使用关键字 GOTO （一个词），并使用冒号（:）引入标签名称：
EXEC SQL whenever goto :error_label;
GBase 8s 扩展使用关键字 GO TO（两个词）并仅指定 label 名称：
EXEC SQL whenever go to error_label;
使用 GOTO 操作，当 SQL 语句生成异常时，程序会自动将控件传输到 error_label
标签。
当使用 WHENEVER 语句的 GOTO label 操作时，
您的代码必须包含标签和适当逻
辑来处理错误条件。在以下示例中， label 中的逻辑只是调用 sqlstate_exception() 函数：
error_label:
sqlstate_exception (msg);
您必须在包含 SQL 语句的每个程序块中定义此 error_label 标签。
如果您的程序包
含多个函数，则可能需要在每个函数中包含 error_label 标签和代码。否则，预处理器到
达不包含 error_label 的函数时会产生错误。
它尝试插入 WHENEVER...GOTO 语句请求
的代码，但该函数尚未定义 error_label 标签。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 311 -
要删除预处理器错误，您可以在每个函数中放置带有相同标签名称的带标签的语句，
您可以为 WHENEVER 语句发出另一个操作来重置错误条件，也可以使用 CALL 操作替
换 GOTO 操作，以调用分离函数。
当错误发生时，还可以在 WHENEVER 语句中使用 CALL 关键字调用
sqlstate_exception() 函数。（CALL 选项是 ANSI 标准的 GBase 8s 扩展名。）
如果您要在程序中每次发生 SQL 错误时调用 sqlstate_exception() 函数，请执行以下
步骤：
修改 sqlstate_exception() 函数，使其不需要任何参数。 CALL 操作指定的函数不能
接受参数。要传递信息，请改用全局变量。
在任何 SQL 语句之前，将以下 WHENEVER 语句放置程序的前面部分：
EXEC SQL whenever sqlerror call sqlstate_exception;
提示： 在之前的代码段中，不能在 sqlstate_exception() 函数之后包含括号。
但是，请确保，WHENEVER...CALL 影响的所有函数都可以找到 sqlstate_exception()
函数的声明。
下表对比了 Client SDK 和 GBase 8s Connect 的四种备选安装方法。
该表使用了命令格式的 Client SDK 安装示例；对于 GBase 8s Connect 安装，请替
换相应的 GBase 8s Connect 命令。
表 1. 备用安装方法
安装方
法
命令格式
安装的产
品
使用的理由
限制
静默安
装
./installclientsdk
-silent -options
mysilent.ini
./installclientsdk
-i silent -f
path_name
用于以定
制配置安
装 Client
SDK 或
GBase 8s
Connect
使用预设置的
安装文件
（.ini
文件）
，
此文件
可保存并作为
模板复用
通过使用响应
文件（在 -f
path_name 选
项中调用）
，
只
以 root 用户身份安装。
除非在命令行指定
-acceptlicense=yes，或
将 -W lafiles.license
Accepted 属性设为值
true，否则安装将无法继
续。
如果使用
csdk.properties 或
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 26 -
安装方
法
命令格式
安装的产
品
使用的理由
限制
需使用极少或
不使用任何用
户交互，
即可复
制多台计算机
上的特定安装
配置。
对于某些
用户场景，
静默
安装可以节约
很多时间。
conn.properties 文件作
为响应文件的模板，必须
更改响应文件设置以接受
许可条款协议。要接受许
可条款协议，请将
LICENSE_ACCEPTED=FALSE
更新为
LICENSE_ACCEPTED=TRUE
使用命
令行脚
本解压
./installclientsdk
-legacy
./installclientsdk
-DLEGACY=TRUE
用于单独
安装
Client
SDK
或 GBase
8s
Connect。
使用命令行解
压来进行安装
的备用方法在
以下某个场景
中会很有帮助：
您希望
安装产品以
将其快速重
新分发到多
台计算机，
并且占用的
磁盘空间极
少
您希望
在产品重新
分发期间避
免使用
Java™ 运行
无
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 27 -
安装方
法
命令格式
安装的产
品
使用的理由
限制
时环境
(JRE)
直接调
用 JAR
文件
java -cp csdk.jar
run
用于以特
定于产品
的命令安
装 Client
SDK 或
GBase 8s
Connect
是较快的安装
方法
要使用此安装选项，
必须有
JRE V1.3.2 或更高版本。
表 2. 备用安装方法
安装方
法
命令格式
安装的产品
使用的理由
限制
静默安
装
./installclientsdk
-silent -options
mysilent.ini
./installclientsdk
-i silent -f
path_name
用于以特定
于产品的命
令安装
Client SDK
或 GBase
8s Connect
使用预设置的
安装文件
（.ini
文件），此文件
可保存并作为
模板复用
通过使用响应
文件（在 -f
path_name 选
项中调用），只
需使用极少或
不使用任何用
户交互，
即可复
制多台计算机
上的特定安装
以 root 用户身份安
装。除非在命令行指定
-acceptlicense=yes，
或将 -W
lafiles.license
Accepted 属性设为值
true，否则安装将无法
继续。
如果使用
bundle.properties 文
件作为响应文件的模
板，必须将产品许可条
款协议的响应文件设置
更改为“Accept”，该
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 28 -
安装方
法
命令格式
安装的产品
使用的理由
限制
配置。
对于某些
用户场景，
静默
安装可以节约
很多时间。
文件才能在静默安装期
间起作用。
使用命
令行脚
本解压
./installclientsdk
-legacy
./installclientsdk
-DLEGACY=TRUE
用于单独安
装 Client
SDK 或
GBase 8s
Connect。
使用命令行解
压来进行安装
的备用方法在
以下某个场景
中会很有帮助：
您希望
安装产品以
将其快速重
新分发到多
台计算机，
并且占用的
磁盘空间极
少
您希望
在产品重新
分发期间避
免使用
Java 运行
时环境
(JRE)
无
以静默方式安装
在编辑 .ini 文件中的属性后，
可以在无用户交互的情况下安装 Client
SDK 和
GBase 8s Connect。 下列语法图说明了静默安装的安装选项。
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 29 -
静默安装语法
表 1. 静默安装选项的元素
元素
用途
限制
optionfile
指定要预设置安装属性的 .ini 文件的文件名
无
Java™ dir
指定安装期间要使用的主机上的 JRE，
以代替安装程序提供
的 JRE
该 JRE 必须是
V1.4.2 或更高
版本。
logfilename
指定非缺省日志文件名
无
temp path
指定临时目录的路径。如果文件解压期间收到错误消息，表
示 /tmp 目录中没有足够空间，
那么请将 -tempdir 选项设
为其他临时目录。
无
下表描述了静默安装选项。
表 2. 静默安装选项
选项
含义
-silent
将安装程序设为静默方式
-acceptlicense=yes
接受许可协议
-options
提供用于预设置安装属性的 .ini 文件的位置
installconn
仅安装 GBase 8s Connect
installclientsdk
仅安装 Client SDK
-log
记录安装程序的进度
-javahome
使用指定的 JRE。要强制安装程序使用捆绑的 JRE 并忽略任何本地
JRE，请使用 -javahome none 参数。
-tempdir
指向除 /tmp 以外的临时目录
-is:freediskblocks
开始安装之前用来确定是否有足够的空间可用于产品安装文件。
-is:nospacecheck
用来阻止安装程序检查是否有足够的空间可用于产品安装文件。请谨
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 30 -
选项
含义
慎使用：如果没有足够空间来解压临时文件，那么安装程序将会失败。
-help-?
显示所支持选项以及它们的功能的列表
要执行 Client SDK 的静默安装，可以修改 csdk.ini 文件中的值，以设置属
性或接受缺省值。
要执行 GBase 8s Connect 的静默安装，可以修改 conn.ini 文件中的值，或
接受缺省值。
下表描述了这些属性。
表 3. silent.ini 文件的属性
属性
可能的值
描述
-P installLocation=
有效的目录；例如：
/usr/gbasedbt（缺省
值）
指定要安装产品的目录
-W setupTypes.selectedSetupTypeId=
typical（缺省值）
custom
指定安装类型
-P csdk.active=
true
false（缺省值）
指示是否选定产品或功能部
件以进行安装。
GBase 8s Connect 和完整
Client SDK 不能同时安装，
也不能安装在同一位置。
-P iconnect.active=
true（缺省值）
false
指示是否选定产品或功能部
件以进行安装。
GBase 8s Connect 和
Client SDK 不能同时安装。
-SP CSDK/UNIX/csdk.jar
clientfeature.active=
true（缺省值）
false
指示是否选定产品或功能部
件以进行安装。
仅适用于“定制”选项的
Client SDK 安装。
-P messagesfeature.active=
true（缺省值）
false
指示是否选定错误消息功能
部件以进行安装
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 31 -
属性
可能的值
描述
-P glsfeature.active=
true（缺省值）
false
指示是否选定错误 GLS 功
能部件以进行安装
-G licenseAccepted
true
false
接受许可协议。false 值会
停止安装过程。如果在命令
行接受许可协议，那么无需
任何值。
可以在
$MEDIADIR/doc/license 中
找到许可协议。
执行静默安装
按照以下步骤执行静默安装。
要执行静默安装：
1.
将 csdk.ini 或 conn.ini 复制到任何可读取的位置，并重命名：
myclient.ini。
2.
编辑目录中的 *.ini 文件。
使用此文件，以指定选项配置安装。在指定静默安装时，如果不编辑这些值或指定
*.ini 文件，安装程序将使用缺省值。
3.
以 root 用户身份，使用以下方式运行 Client SDK 或 GBase 8s Connect 的
静默安装：
installclientsdk -silent -options myclient.ini
或者使用以下方式运行 GBase 8s Connect 的静默安装：
installconn -silent -options myclient.ini
在 UNIX™ 和 Linux™ 上执行静默客户机产品安装
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 32 -
要执行静默安装（有时称为无人照管安装），必须创建响应文件，其中包含有
关希望如何安装产品的信息。可在命令行选项中调用此响应文件以执行静默安
装。
必须以 root 用户身份登录才能运行安装应用程序。
注意： 如果使用 csdk.properties 文件或 conn.properties 文件作为响应文件的模板，必须
将产品许可条款协议的响应文件设置更改为“Accept”，该文件才能在静默安装期间起作用。
要在多个目录中部署 Client SDK 或 GBase 8s Connect：
1.
通过执行以下某项操作来创建响应文件：
在命令行上，以 GUI 或控制台方式启动产品安装应用程序，并指定 -r
选项以生成响应文件。
保存安装介质上 csdk.properties 文件或 conn.properties 文件的
本地副本，重命名该文件，并配置环境设置以及同意许可条款。跳至步骤
3。
2.
将响应文件复制到要安装客户机产品的计算机。
3.
针对要安装的一个或多个产品运行静默安装命令，同时在 -f 选项后指明响应
文件的绝对路径：
./installclientsdk -i silent -f path_name，用来安装 Client SDK。
./installconnect -i silent -f path_name，用来安装 GBase 8s
Connect。
4.
为要部署相同安装设置的每个位置重复步骤 2 和 3。
通过命令行脚本使用解压来安装
作为使用安装程序的备选，您可以生成基于脚本的可安装介质，并且可以在以
后使用命令行选项来安装 Client SDK 和 GBase 8s Connect。解压方式使用安
装程序来解压介质并提供“软件许可协议”。解压以后，当您准备安装产品时，
必须运行命令行安装脚本。
解压语法
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 33 -
下表说明了语法元素。
表 1. 语法元素
元素
用途
限制
Java™ dir
指定安装期间要使用的主机上的 JRE，以代替安装程序
提供的 JRE
该 JRE 必须是
V1.4.2 或更高
版本。
logfilename
指定非缺省日志文件名
无
temp path
指定临时目录的路径。如果文件解压期间收到错误消息，
表示 /tmp 目录中没有足够空间，那么请将 -tempdir
选项设为其他临时目录。
无
下表描述了解压选项。
表 2. 安装选项
选项
含义
installconn
仅抽取 GBase 8s Connect
installclientsdk
仅抽取 Client SDK
-gui
以 GUI 方式启动解压过程
-log
记录安装程序的进度
-javahome
使用指定的 JRE。
要强制安装程序使用捆绑的 JRE 并忽略任何本地
JRE，请使用 -javahome none 参数。
-tempdir
指向除 /tmp 以外的临时目录
-is:freediskblocks 开始解压之前用来确定是否有足够的空间可用于产品安装文件。
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 34 -
选项
含义
-is:nospacecheck
用来阻止安装程序检查是否有足够的空间可用于产品安装文件。请
谨慎使用：如果没有足够空间来解压临时文件，那么解压程序将会
失败。
-help
显示所支持选项以及它们的功能的列表
在此安装以后，不会出现提供安装的 JRE，也不会出现卸载程序。
如果想将产品安装在不同位置或重新分发产品，请使用该选项。
使用脚本解压并重新分发客户机产品
可以使用带 -DLEGACY=TRUE 选项的安装命令从 GBase 8s 客户机产品介质解压
文件，然后使用脚本将软件重新分发到其他计算机。此方法仅在 UNIX™ 和
Linux™ 操作系统上可用。
如果要解压客户机产品文件以在不将 JRE 或卸载应用程序添加到多个主机系统的情况下重新
分发这些文件，请使用这种命令格式。通过在一台计算机上使用 -DLEGACY=TRUE 命令启动安装
应用程序来解压产品文件。完成安装应用程序的运行后，可以复制第一台计算机的安装目录中
的文件，以将产品重新分发到其他计算机上。
1.
根据您要使用的产品，运行以下某个命令：
./installclientsdk -DLEGACY=TRUE
./installconnect -DLEGACY=TRUE
缺省情况下安装应用程序以控制台方式打开。如果要以 GUI 方式运行安装应用程
序，请在命令末尾输入 -i gui 选项。
2.
遵循安装应用程序中的指示信息。
3.
复制安装目录的内容，并将它们放入要重新分发产品的其他计算机的目录中。
这些内容包括用于重新分发的 RUNasroot 脚本。
4.
为要在其他计算机上部署的产品运行脚本。
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 35 -
可以在一个位置中部署 Client SDK 或 GBase 8s Connect，但不能两者都部署。
选项
描述
RUNasroot.installclientsdk
完成 Client SDK 文件的重新分发。
RUNasroot.installconnect
完成 GBase 8s Connect 文件的重新分发。
以命令行抽取方式安装 Client SDK 和 GBase 8s Connect
使用这些指示信息以命令行抽取方式安装 Client SDK 和 GBase 8s Connect。
要以命令行抽取方式安装 Client SDK 和 GBase 8s Connect：
1.
以 root 用户身份，运行下列一个选项以解压产品文件：
./installclientsdk -legacy
或
./installconn -legacy
安装程序用于抽取。
可以按缺省控制台方式或 GUI 方式使用 -legacy 参数，但不能以静默安装方式使
用。以下指示信息适用于缺省控制台方式。
2.
输入 1 在安装屏幕之间前进。
此时会显示“软件许可协议”。
3.
阅读许可协议后，输入 1 接受条款。
4.
指定安装目录或接受缺省目录。
将解压客户机产品和安装文件。
5.
选择“完成”退出向导。
可安装介质现在已可用。此时，可以复制、归档或分发文件。然后，您可以在不使
用安装程序或 Java™ 的情况下来安装 Client SDK 或 GBase 8s Connect。
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 36 -
6.
要安装 Client SDK 或 GBase 8s Connect，请将 $GBASEDBTDIR 设为可单独安
装产品的目标目录，并且以 root 用户身份运行安装脚本：
./installclientsdk
或
./installconn
通过直接调用 JAR 文件进行安装
以下语法图说明了直接调用 Client SDK 或 GBase 8s Connect .jar 文件时可
以使用的安装选项。要使用此安装选项，必须有 JRE V1.3.2 或更高版本。
直接 JAR 调用安装语法
表 1. 调用 JAR 的安装选项的元素
元素
用途
限制
relative_directory
指定所指定 .jar 文件的路径。如果从 .jar 文
件所在的目录运行命令，那么不要指定路径。
无
logfile
指定非缺省日志文件名
无
optionfile
指定要预设置安装属性的 .ini 文件的文件名
无
下表描述了 Java 调用的应用程序选项。
表 2. 调用 JAR 的安装选项
选项
含义
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 37 -
选项
含义
csdk.jar
Client SDK 的安装应用程序
conn.jar
GBase 8s Connect 的安装应用程序
-P legacy.active=true 解压文件但不安装产品
-p logfile
记录安装程序的进度
-is:freediskblocks
开始安装之前用来确定是否有足够的空间可用于产品安装文件。
-is:nospacecheck
用来阻止安装程序检查是否有足够的空间可用于产品安装文件。
请谨慎使用：
如果没有足够空间来解压临时文件，
那么安装程序
将会失败。
-swing
将调用 Java™ 的应用程序设置为 GUI 方式
-silent
将调用 Java 的应用程序设置为静默方式
-options
与 optionfile 一起使用。
指定要预设置安装属性的 .ini 文件
的文件名
通过调用 JAR 文件来安装 Client SDK 或 GBase 8s Connect
可通过直接调用 JAR 文件进行安装 Client SDK 或 GBase 8s Connect。
要通过直接调用 JAR 文件进行安装 Client SDK 或 GBase 8s Connect：
使用与要安装产品相对应的命令在安装应用程序上调用 Java™，例如：
java -cp csdk.jar run
必须从 csdk.jar 文件的目录中运行此命令。