使用 GET DIAGNOSTICS 语句来返回关于最近执行的 SQL 语句的诊断信息。
语法
用法
请随同 GBase 8s ESQL/C 使用此语句。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 643
GET DIAGNOSTICS 语句检索数据库服务器记录在名为诊断区域中的指定的状态
信息。使用 GET DIAGNOSTICS 不会更改诊断区域的内容。
GET DIAGNOSTICS 语句使用下列两个子句中的一个：
Statement 子句返回关于最近的 SQL 语句生成的错误和警告的计数和溢
出信息。
EXCEPTION 子句提供关于最近的 SQL 语句生成的错误和警告的特定信
息。
使用 SQLSTATE 错误状态代码
在执行 SQL 语句时，自动地生成错误状态代码。此代码表示success、
failure、warning 或 no data found。该错误状态代码存储在名为
SQLSTATE 的内建变量中。
类和子类代码
SQLSTATE 状态代码是一个仅可包含数字和大写字母的五字符的字符串。
SQLSTATE 状态代码的前两个字符表示类。SQLSTATE 代码的后三个字符表示子
类。图 1 展示 SQLSTATE 代码的结构。此示例使用值 08001，此处 08 是类代
码，001 是子类代码。值 08001 表示 unable to connect with database
environment 错误。
图: SQLSTATE 代码的结构
下列表时解释类代码值的快速参考。
SQLSTATE 类代码值 结果
00 成功
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 644
01 成功但有警告
02 找不到数据
> 02 错误或警告
SQLSTATE 支持 SQL 的 ANSI/ISO 标准
返回到 SQLSTATE 变量的所有状态代码都符合 ANSI，除了以下几种情况：
带有 01 类代码和以 I 开头的子类代码的 SQLSTATE 代码是特定于
GBase 8s 的警告消息。
带有 IX 类代码和任何子类代码的 SQLSTATE 代码是特定于 GBase 8s
的错误消息。
带有以从 5 到 9 中的一个数字或从 I 到 Z 中的一个大写字母开头的
SQLSTATE 代码，表示 SQL 的 ANSI/ISO 标准当前未定义的条件。唯
一的例外是类代码为 IX 的 SQLSTATE 代码，这些代码是特定于
GBase 8s 的错误消息。
GBase 8s 的客户端/服务器通信协议，诸如 SQLI 和 DRDA®，支持这些
SQLSTATE 代码值。
SQLSTATE 代码列表
此表描述与 SQLSTATE 变量相关联的类代码、子类代码和所有有效警告和错误代
码的含义。
类
子类
含义
00
000
成功。
01
000
成功但有警告。
01
002
断开连接错误。事务回滚。
01
003
在集合函数中消除的 NULL 值。
01
004
字符串数据，右截断。
01
005
项描述符区域不足。
01
006
未调用的权限。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 645
类
子类
含义
01
007
未授予的权限。
01
I01
数据库有事务。
01
I03
选择了符合 ANSI 的数据库。
01
I04
选择了GBase 8s 数据库服务器。
01
I05
使用了浮点到十进制转换。
01
I06
GBase 8s 扩展到符合 ANSI 的语法。
01
I07
UPDATE 或 DELETE 语句没有 WHERE 子句。
01
I08
使用 ANSI 关键字作为游标名称。
01
I09
投影列表的基数与 INTO 列表的基数不相等。
01
I10
运行在备用模式下的数据库服务器。
01
I11
打开 Dataskip。
02
000
找不到数据。
07
000
动态的 SQL 错误。
07
001
USING 子句与动态参数不匹配。
07
002
USING 子句与目标规范不匹配。
07
003
不可执行游标规范。
07
004
动态参数需要 USING 子句。
07
005
准备好的语句不是游标规范。
07
006
违背受限的数据类型属性。
07
008
无效的描述符计数。
07
009
无效的描述符索引。
08
000
连接异常。
08
001
数据库服务器拒绝连接。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 646
类
子类
含义
08
002
连接名称在用。
08
003
连接不存在。
08
004
客户端无法建立连接。
08
006
事务已回滚。
08
007
事务状态未知。
08
S01
通信失败。
0A
000
不支持的特性。
0A
001
多服务器事务。
21
000
基数违反。
21
S01
插入数据列表与列列表不匹配。
21
S02
派生表的程度与列列表不匹配。
22
000
数据异常。
22
001
字符串数据，右截断。
22
002
NULL 值，无指示符参数。
22
003
分数值超范围。
22
005
赋值错误。
22
027
数据异常调整错误。
22
012
除以零（0）。
22
019
无效的转义字符。
22
024
未终止的字符串。
22
025
无效的转义顺序。
23
000
完整性约束未被。
24
000
无效的游标状态。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 647
类
子类
含义
25
000
无效的事务状态。
2B
000
从属的权限描述符仍存在。
2D
000
无效的事务终止。
26
000
无效的 SQL 语句标识符。
2E
000
无效的连接名称。
28
000
无效的用户授权规范。
33
000
无效的 SQL 描述符名称。
34
000
无效的游标名称。
35
000
无效的异常号。
37
000
在PREPARE 或 EXECUTE IMMEDIATE 中的语法错误或访问违
背。
3C
000
重复的游标名称。
40
000
事务回滚。
40
003
语句完成未知。
42
000
语法错误或访问违背。
S0
000
无效的名称。
S0
001
基础表或视图表已存在。
S0
002
未找到基础表。
S0
011
索引已存在。
S0
021
列已存在。
S1
001
内存分配失败。
IX
000
GBase 8s 保留的错误消息。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 648
在应用中使用 SQLSTATE
您可在程序中使用名为 SQLSTATE 的内建变量，无需声明。SQLSTATE 包含
对错误处理不可或缺的状态代码，程序每一次执行 SQL 语句都会生成状态代
码。自动地创建 SQLSTATE。您可检测 SQLSTATE 变量来确定 SQL 语句是
否成功。如果 SQLSTATE 变量指出语句失败，则可执行 GET DIAGNOSTICS
语句来获取附加的错误信息。
要获取展现如何在程序中使用 SQLSTATE 变量的示例，请参阅 使用 GET
DIAGNOSTICS 进行错误检查。
Statement 子句
Statement 子句
元素
描述
限制
语法
status_var 主变量，用于接收关于指定的状态域名称
的最近 SQL 语句的状态信息
必须与域的
数据类型相
匹配
特定
于语
言
在检索计数和溢出信息时，GET DIAGNOSTICS 可将这三个语句域的值存入对应的
主变量。主变量数据类型必须与请求的域的数据类型相同。下列关键字表示这三
个域。
域名称关键字
域数据类型
域内容
ESQL/C 主变量数据类型
MORE
字符
Y 或 N
char[2]
NUMBER
整数
1 至 35,000
int
ROW_COUNT
整数
0 至 999,999,999 int
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 649
使用 MORE 关键字
使用 MORE 关键字来确定最近执行的 SQL 语句是否导致数据库服务器的下列
操作：
将它检测到的所有异常存储在诊断区域中
如果如此，则 GET DIAGNOSTICS 返回值 N。
检测到的异常多于它存储在诊断区域中的异常
如果如此，则 GET DIAGNOSTICS 返回值 Y。（MORE 的值通常为
N。）
使用 ROW_COUNT 关键字
ROW_COUNT 关键字返回最近执行的 DML 语句处理的行数。ROW_COUNT
对这些行计数：
插入到表内的行
在表中更新的行
从表删除的行
使用 NUMBER 关键字
NUMBER 关键字返回最近执行的 SQL 语句发生的异常的数量。根据计数得到的
异常数，NUMBER 字段可保留从 1 至 35,000 的值。
EXCEPTION 子句
Exception 子句
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 650
元素
描述
限制
语法
exception_num 异常的数量
从 1 至 35,000
的整数
精确数值
exception_var 存储 exception_num
的变量
必须为 SMALLINT
或 INT
特定于语言
information
接收指定的异常域的
值的主变量
数据类型必须与指
定的字段的数据类
型向匹配
特定于语言
exception_num 文字表示从 Statement 子句中的 NUMBER 字段返回的异常的数
量的异常值之一。
在检索异常信息时，GET DIAGNOSTICS 将七个字段中的每一个的值写到相应的
主变量内。这些域定位在诊断区域中，并从最近的 SQL 语句产生的异常派生而
来。
主变量数据类型必须与请求的域的数据类型相同。下表描述这七个异常信息域。
域名称关键字
域数据类型
域内容
ESQL/C 主变量数
据类型
RETURNED_SQLSTATE
字符
SQLSTATE 值
char[6]
GBASEDBT_SQLCODE
整数
特定于 GBase
8s 的状态代码
int4
CLASS_ORIGIN
字符
字符串
char[255]
SUBCLASS_ORIGIN
字符
字符串
char[255]
MESSAGE_TEXT
字符
字符串
char[255]
MESSAGE_LENGTH
整数
数值
int
SERVER_NAME
字符
字符串
char[255]
CONNECTION_NAME
字符
字符串
char[255]
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 651
应用通过编号指定异常，或使用无符号的整数，或使用整数主变量（小数位为 0
的精确数值）。值为 1 的异常对应于由最近的 SQL 语句而不是 GET
DIAGNOSTICS 设置的 SQLSTATE 值。其他异常编号与由 SQL 语句产生的其
他异常之间的关联未定义。这样，不存在设置顺序，异常值依次顺序填充到诊断
区域。您通常会得到至少一个异常，即使 SQLSTATE 值表示成功。
如果在 GET DIAGNOSTICS 语句内发生错误（即，如果请求了无效的异常编
号），则将 GBase 8s 内部的 SQLCODE 和 SQLSTATE 变量设置为那个异常
的值。此外，未定义 GET DIAGNOSTICS 字段。
使用 RETURNED_SQLSTATE 关键字
RETURNED_SQLSTATE 关键字返回该异常描述的 SQLSTATE 值。
使用 GBASEDBT_SQLCODE 关键字
GBASEDBT_SQLCODE 关键字返回特定于 GBase 8s 的状态代码。在全局的
SQLCODE 变量中也可得到相同的值。要获取更多信息，请参阅 GBase 8s
ESQL/C 程序员手册 中对 SQLCODE 变量的讨论。
使用 CLASS_ORIGIN 关键字
使用 CLASS_ORIGIN 关键字来检索 RETURNED_SQLSTATE 值的类部分。如
果 SQL 的 ISO 标准定义该类，则 CLASS_ORIGIN 的值等于 ISO 9075。否
则，由 CLASS_ORIGIN 返回的值是由 GBase 8s 定义的，且不可为 ISO 9075。
术语 ANSI SQL 和 ISO SQL 是同义词。
使用 SUBCLASS_ORIGIN 关键字
SUBCLASS_ORIGIN 关键字返回 RETURNED_SQLSTATE 子类上的数据。（如
果该子类定义 ISO 标准，则此值为 ISO 9075。）
使用 MESSAGE_TEXT 关键字
MESSAGE_TEXT 关键字返回异常的消息文本（例如，错误消息）。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 652
使用 MESSAGE_LENGTH 关键字
MESSAGE_LENGTH 关键字返回以字节计的当前消息文本字符串的长度。
使用 SERVER_NAME 关键字
SERVER_NAME 关键字返回与 CONNECT 或 DATABASE 语句相关的数据库
服务器的名称。在发生任何下列事件时，GET DIAGNOSTICS 更新
SERVER_NAME 字段：
CONNECT 语句成功地执行。
SET CONNECTION 语句成功地执行。
DISCONNECT 语句成功地终止当前连接。
DISCONNECT ALL 语句失败。
然而，在这些事件之后，不更新 SERVER_NAME 字段：
CONNECT 语句失败。
DISCONNECT 语句失败（但这不包括 DISCONNECT ALL 语句）。
SET CONNECTION 语句失败。
SERVER_NAME 字段保留在先前的 SQL 语句中设置的值。如果在执行的第一个
SQL 语句上发生任何上述情况，则 SERVER_NAME 字段为空白。
SERVER_NAME 域的内容
在您执行下列语句之后，SERVER_NAME 域包含不同的信息。
执行的语句 SERVER_NAME 域内容
CONNECT 包含您连接到得或不能连接到的数据库服务器的名称。如果您
没有当前连接，或使用缺省连接，则域为空白。
DATABASE 包含指定的数据库所在的数据库服务器的名称。
DISCONNECT 包含您断开连接的或未能断开连接的数据库服务器的名称。如
果您切断连接，然后执行非当前连接的 DISCONNECT 语句，
则 SERVER_NAME 域保持不变。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 653
DISCONNECT ALL 如果该语句执行成功，则将此域设置为空白。如果该语句失
败，则 SERVER_NAME 包含您未断开连接的所有数据库
服务器的名称。（此信息不表示连接仍存在。）
SET CONNECTION 包含您切换到的或未切换到的数据库服务器的名称
如果 CONNECT 成功，则将 SERVER_NAME 设置为下列值之一：
GBASEDBTSERVER 值（如果该连接是连接到缺省的数据库服务器，因
为 CONNECT 未指定数据库服务器）
数据库服务器的名称（如果该连接是连接到特定的数据库服务器）
使用 CONNECTION_NAME 关键字
使用 CONNECTION_NAME 关键字来返回您在 CONNECT 或 SET
CONNECTION 语句中指定的连接的名称。
在更新 CONNECTION_NAME 关键字时
在发生下列情况时，GET DIAGNOSTICS 更新 CONNECTION_NAME 域
CONNECT 语句成功地执行。
SET CONNECTION 语句成功地执行。
在当前的连接中 DISCONNECT 语句成功地执行。
GET DIAGNOSTICS 以空白填充 CONNECTION_NAME 域，因为不存在
当前连接。
DISCONNECT ALL 语句失败。
在未更新 CONNECTION_NAME 时
在下列情况下，不更新 CONNECTION_NAME 域：
CONNECT 语句失败。
DISCONNECT 语句失败（但这不包括 DISCONNECT ALL 语句）。
SET CONNECTION 语句失败。
CONNECTION_NAME 域保留在先前的 SQL 语句中设置的值。如果在执行第一
个 SQL 语句时发生上述任何情况，则 CONNECTION_NAME 域为空白。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 654
隐式连接没有名称。在 DATABASE 语句成功地创建隐式连接之后，
CONNECTION_NAME 域为空白。
CONNECTION_NAME 域的内容
CONNECTION_NAME 域包含依赖于先前执行的 CONNECT、SET
CONNECTION、DISCONNECT 或 DISCONNECT ALL 语句的连接信息。
在您执行下列语句之后，CONNECTION_NAME 域包含不同的信息
执行的语句 CONNECTION_NAME 域内容
CONNECT 包含连接或未连接的连接名称，在 CONNECT 语句中指
定。对于无当前连接或缺省连接，该区域为空白。
SET CONNECTION 包含切换或未切换的连接名称，在 SET CONNECTION
语句中指定。
DISCONNECT 包含断开连接或未断开连接的连接名称，在
DISCONNECT 语句中指定。如果您成功地断开连接，然
后执行非当前连接的 DISCONNECT 语句，则
CONNECTION_NAME 域保持不变。
DISCONNECT ALL 如果成功地执行 DISCONNECT ALL 语句，则不包含信
息。如果未成功地执行该语句，则
CONNECTION_NAME 与包含在 CONNECT 语句中指定
的未断开连接的所有连接的名称。然而，此信息不意味着
连接仍存在。
如果 CONNECT 成功，则 CONNECTION_NAME 取这些值之一：
在 CONNECT 语句中指定的数据库环境的名称，如果 CONNECT 语句
不包括 AS 子句
连接的名称（在 AS 关键字之后声明了的标识符），如果 CONNECT 语
句包括 AS 子句
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 655
使用 GET DIAGNOSTICS 进行错误检查
GET DIAGNOSTICS 从诊断区域中的各种域返回值。对于您想要访问的诊断区域
中的每一域，必须支持兼容数据类型的主变量。
下列示例展示如何使用 GET DIAGNOSTICS 语句来显示错误信息。该示例展示名为
disp_sqlstate_err( ) 的 GBase 8s ESQL/C 错误显示例程：
void disp_sqlstate_err()
{
int j;
EXEC SQL BEGIN DECLARE SECTION;
int exception_count;
char overflow[2];
int exception_num=1;
char class_id[255];
char subclass_id[255];
char message[255];
int messlen;
char sqlstate_code[6];
int i;
EXEC SQL END DECLARE SECTION;
printf("---------------------------------");
printf("-------------------------\n");
printf("SQLSTATE:
printf("SQLCODE: %d\n", SQLCODE);
printf("\n");
EXEC SQL get diagnostics :exception_count = NUMBER,
:overflow = MORE;
printf("EXCEPTIONS: Number=%d\t", exception_count);
printf("More? %s\n", overflow);
for (i = 1; i <= exception_count; i++)
{
EXEC SQL get diagnostics exception :i
:sqlstate_code = RETURNED_SQLSTATE,
:class_id = CLASS_ORIGIN, :subclass_id = SUBCLASS_ORIGIN,
:message = MESSAGE_TEXT, :messlen = MESSAGE_LENGTH;
printf("- - - - - - - - - - - - - - - - - - - -\n");
printf("EXCEPTION %d: SQLSTATE=%s\n", i, sqlstate_code);
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 656
message[messlen-1] ='\0';
printf("MESSAGE TEXT: %s\n", message);
j = stleng(class_id);
while((class_id[j] == '\0') ||
(class_id[j] == ' '))
j--;
class_id[j+1] = '\0';
printf("CLASS ORIGIN:
j = stleng(subclass_id);
while((subclass_id[j] == '\0') ||
(subclass_id[j] == ' '))
j--;
subclass_id[j+1] = '\0';
printf("SUBCLASS ORIGIN:
}
printf("---------------------------------");
printf("-------------------------\n");
}