更新日期：2024年09月11日
可通过卸载应用程序来卸载 GBase 8s 客户机产品，在大多数操作系统中都可
以通过不同的方式运行该应用程序。
重要：
l
不要通过手动删除文件来除去任何 GBase 8s 产品。
l
如果 Client SDK 与 GBase 8s 数据库服务器安装在同一个目录中：
n 卸载 Client SDK 之前，必须先卸载 GBase 8s。
GBase 8s 客户机产品安装指南
南大通用数据技术股份有限公司 - 37 -
n 不要除去 Global Language Support (GLS)，因为这两个产品在此功能部件上
具有依赖关系。
使用以下任何控制台、GUI 或静默方法来卸载 UNIX™ 或 Linux™ 上的 Client SDK 和
GBase 8s Connect。
以控制台（缺省）方式卸载（UNIX、Linux）
要以控制台（缺省）方式卸载 GBase 8s 客户机产品：
1.
以 root 用户身份，从 $GBASEDBTDIR 运行下列某条命令：
o
java -jar uninstall_conn/uninstall.jar
o
java -jar uninstall_csdk/uninstall.jar
2.
按照提示完成卸载。
以 GUI 方式卸载（UNIX、Linux）
要以 GUI 方式卸载 UNIX 或 Linux 中的 GBase 8s 客户机产品：
1.
以 root 用户身份，从 $GBASEDBTDIR 运行下列某条命令：
o
java -jar uninstall_conn/uninstall.jar -gui
o
java -jar uninstall_csdk/uninstall.jar -gui
2.
按照提示完成卸载。
以静默方式卸载（UNIX、Linux）
要以静默方式卸载 GBase 8s 客户机产品：
1.
以 root 用户身份，从 $GBASEDBTDIR 运行下列某条命令：
o
java -jar uninstall_conn/uninstall.jar -silent
o
java -jar uninstall_csdk/uninstall.jar -silent
2.
以静默方式无需交互即可完成卸载。
将 lvarchar 数据类型用于具有外部表示字符串的不透明类型列的操作。
要在 SQL 语句中使用不透明类型的外部格式，不透明数据类型必须具有定义的输入
和输出支持函数。
当客户端应用程序使用 lvarchar 主机变量将数据传输到不透明类型类或
从不透明类型列传输数据时，数据库服务器调用以下不透明数据类型的支持函数：
输入支持函数描述如何将不透明数据类型的数据从 lvarchar 主机变量传输到不透明
类型的列中。
数据库服务器调用此输入支持函数，用于将数据库服务器发送不透明类型的外部格式
的操作（ INSERT 和 UPDATE 语句）。
输出支持函数描述如何将透明数据类型的数据从不透明类型的列传输到 lvarchar 主
机变量中。
数据库服务器调用此输出函数，用于将诸如 SELECT 和 FETCH 语句的操作发送到
客户端应用程序的不透明类型的外部格式。
重要：
如果 CREATE OPAQUE TYPE 语句指定了最大长度限制，
则该值是数据库服
务器存储此列的最大长度（忽略了客户端应用程序发送的数据的大小）。如果数据的长度
大于此最大大小，则数据库服务器截断此数据并通知应用程序。
按照以下步骤在数据库服务器和 GBase 8s ESQL/C 应用程序之间传输不透明类型列
的外部格式：
声明一个 lvarchar 主机变量；
在 SQL 语句中使用 lvarchar 主机变量在不透明类型列的外部格式上执行 select 、
insert 、update 或 delete 操作。
声明 lvarchar 主机变量
使用 lvarchar 数据类型对不透明数据类型的外部格式声明主机变量。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 259 -
下图描述了声明 lvarchar 主机变量的语法。
要声明，
使用 lvarchar 关键字作为变量
数据类型，如下所示： GBase 8s 扩展lvarchar’opaque type’,variable name[variable
size]*variable name;
元素
意义
限制
SQL 语法
opaque
type
外部格式要存储到
lvarchar 变量中的不透明
数据类型的名称
必须已经在数据库
中定义
GBase 8s SQL 指南：
语法中的标识符段
variabl
e name
要声明为 lvarchar
变量的 GBase 8s ESQL/C
变量名
名称必须符合变量
名的特定语言规则
*varia
ble name
未指定长度的数据
的 lvarchar 指针变量的
名称
不等同于 C 字符指针
（char *）。指向此类
型的内部 ESQL/C 表
示。必须使用
ifx_var() 函数操纵
数据。
名称必须符合变量名
的特定语言规则
variabl
e size
分配给 lvarchar 变
量的字节数
可以是 1 - 32,000
字节（32 KB）中的整数
提示： 要对 LVARCHAR 列声明 lvarchar 主机变量，请使用 lvarchar 数据类
型中显示的语法。
下图显示了四个 lvarchar 变量的声明，它们保存了不透明类型列的外部格式。
图 5. 不透明数据类型 lvarchar 主机变量示例
#define CIRCLESZ 20
EXEC SQL BEGIN DECLARE SECTION;
lvarchar 'shape' a_polygon[100];
lvarchar 'circle' circle1[CIRCLESZ],
circle2[CIRCLESZ];
lvarchar 'circle' *a_crcl_ptr;
EXEC SQL END DECLARE SECTION;
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 260 -
可以在当声明行中声明多个 lvarchar 变量。但是，所有变量必须是相同的不
透明类型，如 图 1中显示的 circle1 和 circle2 的声明那样。图 1还显示了
a_crcl_ptr 主机变量的 lvarchar 指针声明。
固定大小的 lvarchar 主机变量
如果未指定 lvarchar 主机变量的大小，
则该大小等价于一个 C 语言 char 数据类型。
如果指定了大小，则 lvarchar 主机变量等价于具有此大小的 C 语言 char 数据类型。如
果您指定固定大小的 lvarchar 主机变量，
则当获取此列时，
任何超出此指定大小的数据都
会被截断。使用指示变量检查此截断。
因为固定大小的 lvarchar 主机变量等价于 C 语言 char 数据类型，
所以可以使用 C
语言字符字符串操作来操纵它们。
lvarchar 指针主机变量
lvarchar 指针主机变量设计用于插入或选择可以以字符串格式表示的用户定义或不透
明类型。
不透明列的字符串表示形式的大小可能因行而异。因此数据的大小是未知的，直到列
被提取到主变量中为止。lvarchar 指针主机变量引用的数据大小最多可达 2 GB。
lvarchar 指针类型不是 C 语言 char 指针。GBase 8s ESQL/C 维护自己的
lvarchar 指针类型的内部表示。该表示与 var binary 主机变量的表示相同，
不同之处在于它支持 ASCII 数据而不是二进制数据。必须使用 ifx_var() 函
数操纵 lvarchar 指针主机变量。ifx_var() 函数只能用于声明为指针的
lvarchar 变量和 var binary 变量，而不能用于固定大小的 lvarchar 变量。
因为不透明类型列中的数据大小可能会从表中的第一行变化到另一行，因此您无法知
道数据库服务器将返回的数据的最大大小。
当您使用 lvarchar 指针主机变量时，
可以根据
来自数据库服务器的数据大小，让 GBase 8s ESQL/C 分配内存来保存数据，也可以自行分
配内存。使用 ifx_var_flag() 函数指定您将要使用的函数。在这两种情况下，您必须通过使
用 ifx_var_dealloc() 函数显式释放内存。
自行分配内存
要指定您正在分配内存以存储 lvarchar 主机变量，必须首先调用 ifx_var_flag()，给
出 lvarchar 指针的地址，将标志值设置为零（0），如下所示：
ifx_var_flag(&mypoly, 0);
然后您必须将数据获取到 sqlda 或相同描述符结构中。之后使用 ifx_var_getllen() 函
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 261 -
数获取数据的长度，使用 ifx_var_alloc() 函数为此大小分配内存。
#include
exec sql include “polyvar.h” /* includes udt - polygon_type */
main()
{
exec sql begin declare section;
lvarchar ‘polygon_type’ *mypoly1
char *buffer;
int size, p_id, len;
exec sql end declare section;
ifx_var_flag(&mypoly1, 0); /* specifies that appl. will allocate
memory */
exec sql select poly into :mypoly1 from polygon_tab where p_id = 1;
if ( ifx_var_getlen(&mypoly1) > 0 ) { /* If select returns valid data
*/
buffer = (char *)ifx_var_getdata(&mypoly1); /*Access data in
* mypoly1*/
printf(“Length of data : %ld \n”, (int)ifx_var_getlen(&mypoly) );
ifx_var_dealloc(&mypoly1); /* Always users responsibility to free */
}
不透明类型名称
此不透明类型名称是可选的；其存在影响声明如下：
当您从 lvarchar 声明中省略不透明类型时，数据库服务器将尝试识别在 lvarchar 和
不透明数据类型之间转换时使用的适当的支持和转换函数。
可以使用 lvarchar 主机变量保存多个不同的不透明类型的数据。（只要数据库服务
器可以找到合适的支持函数）
当在 lvarchar 声明中指定不透明类型时，数据库服务器会精确地知道在 lvarchar 和
不透明数据类型之间转换时要使用的支持和转换声明。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 262 -
使用不透明类型可以使数据转换更有效率。但是，在这种情况下，lvarchar 主机变量
只能保存特定的不透明类型的数据。
在 lvarchar 主机变量的声明中，不透明类型的名称必须是带引号的字符串。
重要： 单引号（'）和双引号（"）都是 lvarchar 声明中的有效的引用字符串。但是，
起始的引号和结束的引号必须匹配。
lvarchar 主机变量
您的 GBase 8s ESQL/C 程序必须操纵 lvarchar 主机变量的外部数据。
如果来自不透
明类型列的数据的长度不变，或者如何您指定不透明类型列中数据的最大长度，则可以使
用固定大小的 lvarchar主机变量。但是，如果数据的大小从一个表行变成另一个表行，则
使用 lvarchar 指针变量并使用 ifx_var() 函数操纵数据。
固定大小 lvarchar 主机变量
下图显示了如何使用固定大小的 lvarchar 主机变量向 circle_tab 表（参见图 4）中的
circle_col 列插入或选择数据。
图 6. 访问 circle 不透明数据类型的外部格式
EXEC SQL BEGIN DECLARE SECTION;
lvarchar 'circle' lv_circle[30];
char *x_coord;
EXEC SQL END DECLARE SECTION;
/* Insert a new circle_tab row with a literal opaque
* value */
EXEC SQL insert into circle_tab
values ('(3.00, 2.00, 11.5)');
/* Insert data into column circle of table circle_tab using an lvarchar host
* variable */
strcpy(lv_circle, "(1.00, 17.00, 15.25)");
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 263 -
EXEC SQL insert into circle_tab values (:lv_circle);
/* Select column circle in circle_tab from into an lvarchar host variable
*/
EXEC SQL select circle_col into :lv_circle
from circle_tab
where radius(circle_col) = 15.25;
从固定大小的 lvarchar 主机变量插入
要将来自固定大小的 lvarchar 主机变量的数据插入到不透明类型列，请
按照以下步骤操作，它们在图 1中有所描述：
定义固定大小的 lvarchar 主机变量。
此示例显式对 lv_circle 主机变量保留 30 字节。
将与不透明类型外部格式相对应的字符串放到 lvarchar 主机变量中。
当将数据放到 lvarchar 主机变量中时，
必须知道不透明类型的外部格式。
要使 INSERT 语句成功，lvarchar 主机变量 lv_circle 中的数据必须符合不
透明数据类型的外部格式（图 3中显示）。
将 lvarchar 主机变量包含的数据插入到不透明类型列。
当数据库服务器执行 INSERT 语句时，它为 circle 数据类型(circle_in）调用输入支
持函数，
以将 GBase 8s ESQL/C 客户端应用程序发送的内部数据的外部格式解释为存储在
磁盘上的内部格式。
图 1还显示将文字值插入到 circle_col 列的 INSERT 语句。INSERT （或
UPDATE）语句中的文字值必须还符合不透明数据类型的外部格式。
可以按照以下步骤使用固定大小的 lvarchar 主机变量将空值插入到不透明列中：
将 lvarchar 主机变量设置为空字符串。
将 lvarchar 主机变量的指示变量设置为 -1。
以下代码段使用 lv_circle 主机变量将空值插入到 circle_col 列：
EXEC SQL BEGIN DECLARE SECTION;
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 264 -
lvarchar lv_circle[30];
int circle_ind;
EXEC SQL END DECLARE SECTION;
⋮
strcpy(lv_circle, "");
circle_ind = -1;
EXEC SQL insert into circle_tab
values (:lv_circle:circle_ind)l;
将数据选择到固定大小的 lvarchar 主机变量中
要将不透明数据类型的数据选择到固定大小的 lvarchar 主机变量，图 1
中的代码片段采用以下步骤：
将 circle_col 不透明类型列中包含的数据选择到 lv_circle 主机变量中。
当数据库服务器执行 SELECT 语句时，它为它为circle 数据类型
(circle_in）调用输出支持函数，以将从磁盘检索到的内部格式翻译
为 GBase 8s ESQL/C 应用程序所需的外部格式。此SELECT 语句还使
用名为 radius （参见图 2）的用户定义的函数来校准来自不透明列
的半径值。此函数必须在数据库服务器中注册，才能使 SELECT 语句
成功执行。
访问来自 lvarchar 主机变量的 circle 数据。
SELECT 语句之后，lv_circle 主机变量包含的数据库是 circle数据类型的外部格式。
当将不透明类型列的空值选择到 lvarchar 主机变量中时，GBase 8s ESQL/C 将任何
附加的指示变量设置为 -1。
lvarchar 指针变量
以下章节描述如何使用 lvarchar 指针主机变量插入和从不透明类型列中进行选择。
示例使用的不透明类型列的结构表示被称为 polygon_type，并且具有如下定义：
struct {
int no_of_edges; /* No of sides in the polygon */
int length[100]; /* Maximum number of edges in this polygon
is 100 */
int center_x; /* Center x co-ordinate of the polygon */
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 265 -
int center_y; /* Center y co-ordinate of the polygon */
}
下行描述了此列的字符串表示法：
"no_of_edges, length_of_edge 1, . . . length_of_edge n, -1, center_x,
center_y”
从 lvarchar 指针主变量插入
以下示例代码描述了将 lvarchar 指针主机变量的数据插入到不透明类型列的步骤。
为了简化此示例，此代码不会检查错误的返回的值。
#include
exec sql include “polyvar.h” /* includes udt - polygon_type */
main()
{
exec sql begin declare section;
lvarchar ‘polygon_type’ *mypoly1
char *buffer;
int size, p_id, len;
exec sql end declare section;
exec sql create table polygon_tab (p_id int, poly polygon_type);
ifx_var_flag(&mypoly1, 0); /* User does allocation */
buffer = malloc(50);
/* String representation of mypoly1 copied into buffer*/
strcpy(buffer, “5, 10, 20 15, 10, 5, -1, 0, 0”);
size = strlen(buffer);
ifx_var_alloc(&myploy1, size+1); /* Allocate memory for data in
* mypoly1 */
ifx_var_setlen(&myploy1, size); /* Set length of data bufferin
* mypoly1 */
ifx_var_setdata(&mypoly1, buffer, size); /* Store data inside mypoly1
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 266 -
*/
exec sql insert into polygon_tab values (1, :mypoly1);
ifx_var_setnull(&mypoly1, 1); /* Set data buffer in mypoly1 to NULL
*/
ifx_var_dealloc(&mypoly1); /* Deallocate the data buffer in mypoly1
*/
free (buffer);
}
该示例代码执行以下步骤：
声明 lvarchar 指针主机变量 *mypoly1。
创建表，它包含整数 ID 列 p_id 和 polygon 列 polygon_type。
调用 ifx_var_flag() 函数指定它要为数据缓冲区分配的内存（flag 等于 0）。
创建缓冲区，复制 polygon 的字符串表示法，将 size 变量设置为缓冲区的大小。
调用 ifx_var_alloc() 、ifx_var_setlen() 和 ifx_var_setdata() 来分配数据传输缓冲区，
将应用程序缓冲区的数据复制到数据传输缓冲区。
将 ID 值 1 和 mypoly1 插入到 polygon_tab 表。
将数据选择到 lvarchar 指针主机变量
以下示例代码描述将不透明类型列的数据选择到 lvarchar 指针主机变量中。为了简
化示例。此代码不会检查错误的返回的值。
#include
exec sql include “polyvar.h” /* includes udt - polygon_type */
main()
{
exec sql begin declare section;
lvarchar ‘polygon_type’ *mypoly1
char *buffer;
int size, p_id, len;
exec sql end declare section;
ifx_var_flag(&mypoly1, 1); /* ESQL/C run time will do the allocation
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 267 -
*/
exec sql select poly into :mypoly1 from polygon_tab where p_id = 1;
if ( ifx_var_getlen(&mypoly1) > 0 ) { /* If select returns valid data
*/
buffer = (char *)ifx_var_getdata(&mypoly1); /*Access data in
* mypoly1*/
printf(“Length of data : %ld \n”, (int)ifx_var_getlen(&mypoly) );
printf("Data: %s \n", buffer);
ifx_var_dealloc(&mypoly1); /* Always users responsibility to free */
}
该示例代码执行以下步骤：
声明 lvarchar 指针主机变量 *mypoly1。
调用 ifx_var_flag() 函数指定它将让 GBase 8s ESQL/C 分配给数据缓冲区的内存
（flag 等于 1)）。如果为调用 ifx_var_flag() ，则GBase 8s ESQL/C 缺省分配内存。
将列 poly 选择到 *mypoly 主机变量中。
调用 ifx_var_getdata() 获取数据缓冲区的地址，将返回的值强制转型为 char * 并将
地址存储在 buffer 中。
调用 ifx_var_getlen() 显示如何获取检索到的数据的长度。
释放 GBase 8s ESQL/C 分配给 *mypoly1 的内存。