更新日期：2024年09月11日
可以创建您自己版本的 loc_open() 、
loc_read() 、
loc_write() 和 loc_close() 函数来为
简单大对象定义的位置。
用户定义IDE位置函数的典型用途是在应用程序使用数据之前需要以某种方式解释数
据。例如：如果数据被压缩，则在将数据发送到数据库之前，应用程序必须先解压缩。应
用程序甚至可以在运行时选择多种不同的解释函数，它只需将适当的函数指针设置为所需
的解释函数。
要使 GBase 8s ESQL/C 使用您子句的 C 函数定义 TEXT 或 BYTE 数据位置，
将定
位器结构的 loc_loctype 字段设置为 LOCUSER ，如下所示：
EXEC SQL BEGIN DECLARE SECTION;
ifx_loc_t my_simple_lo;
EXEC SQL END DECLARE SECTION;
⋮
my_simple_lo.loc_loctype = LOCUSER;
使用用户定义的简单大对象位置，定位器结构使用下表总结的字段。
表 5. 用于创建用户定义的位置函数的定位器结构中的字段
字段
数据类型
描述
loc_open
mint
(*)()
指向返回整数值的用户定义的打开函数的指针
loc_read
mint
(*)()
指向返回整数值的用户定义的读取函数的指针
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 160 -
字段
数据类型
描述
loc_write
mint
(*)()
指向返回整数值的用户定义的写入函数的指针
loc_close
mint
(*)()
指向返回整数值的用户定义的关闭函数的指针
loc_user_env
char *
保存用户定义的位置函数所需的数据的缓冲区的地址。
例
如：可以将 loc_user_env 设置为公共工作区的地址
loc_xfercount
4 字
节整数
传输简单大对象的最后一次传输操作的字节数
使用用户定义的简单大对象位置，定位器结构使用 lc_union 结构的 lc_mem
结构或 lc_file 结构。表 1和表 1介绍了 lc_union.lc_mem 结构和
lc_union.lc_file 结构的字段。
将简单大对象选择到用户定义的位置
当您的程序选择简单大对象值时，GBase 8s ESQL/C 库必须从数据库服务器接收数据
并将它传输给 GBase 8s ESQL/C 程序。要这样做，GBase 8s ESQL/C 执行以下步骤：
在传输之前，GBase 8s ESQL/C 调用用户定义的打开函数以指示用户定义的位置。此
打开函数的 oflags 参数设置为 LOC_WONLY。
GBase 8s ESQL/C 接收来自数据库服务器的简单大对象值，并将它们放入程序缓冲区。
GBase 8s ESQL/C 调用用户定义的写入函数将程序缓冲区的简单大对象数据传输到
用户定义的位置。
GBase 8s ESQL/C 多次重复步骤 2和 3以便将全部的简单大对象值传输到用户定义
的位置。
传输之后，GBase 8s ESQL/C 执行清除操作，清除用户定义的关闭函数指定的操作。
要将简单大对象选择到用户定义的位置，将 loc_loctype 设置为 LOCUSER 将
loc_open 、loc_write 和 loc_close 字段设置为包含用户定义的打开、写入和关闭函数的地
址。
将简单大对象插入到用户定义的位置
当您的程序插入一个简单大对象值时，GBase 8s ESQL/C 库必须将来自 GBase 8s
ESQL/C 程序的数据传输到数据库服务器。要做此，GBase 8s ESQL/C 执行以下步骤：
传输之前，GBase 8s ESQL/C 调用用户定义的打开函数初始化用户定义的位置。此打
开的函数的 oflags 参数设置为 LOC_RONLY。
GBase 8s ESQL/C 定义用户定义的读取函数将简单大对象从用户定义的位置传输到
程序缓冲区。
GBase 8s ESQL/C 将程序缓冲区中的值发送到数据库服务器。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 161 -
GBase 8s ESQL/C 根据需要重复步骤 2和 3，将整个简单大对象值从用户定义的位置
传输到数据库服务器。
传输后，GBase 8s ESQL/C 执行在用户定义关闭函数中指定的清除操作。
要插入存储在用户定义位置的简单大对象，
请将 loc_loctype 设置为 LOCUSER ，
并
设置 loc_open 、loc_read 和 loc_close 字段，以便它们包含适当的用户定义的打开、读取
和关闭函数的地址。如果要插入的简单大对象为空，请将 loc_indicator 字段设置为 -1。
将 loc_size 字段设置为插入的简单大对象数据的长度。
loc_size 值 -1 表示 GBase 8s
ESQL/C 在单个操作中发送整个用户定义的简单大对象数据。如果程序将 loc_size 设置为
-1，则数据库服务器将读取数据，直到读取函数返回文件结尾（EOF）信号。当计数不等于
请求的字节数时，数据库服务器假定为 EOF 信号。
用户定义的简单大对象函数
GBase 8s ESQL/C 提供四个传输函数，它们可以重新定义以处理用户定义的简单大对
象位置。
loc_open 、loc_read 、loc_write 和 loc_close 字段包含指向这些用户定义的位置函
数的指针。每个函数接收 ifx_loc_t 结构的地址作为第一个（或唯一）参数。可以使用
loc_user_env 字段保存用户定义的位置函数所需的数据。此外，loc_xfercount 以及
lc_union 子结构的字段都可用于这些函数。
用户定义的打开函数
要定义如何为传送操作（读或写）准备用户定义的位置，可以创建名为用户定义的打
开函数的 C 函数。
在从数据库服务器传送简单大对象数据或传输简单大对象数到数据库服务器之前，
GBase 8s ESQL/C 调用定位器结构的 loc_open 字段中的打开函数。
此用户定义的打开函数必须接收下列两个参数：
定位器结构的地址 ifx_loc_t *loc_struc，
其中 loc_struc 是您的用户定义的打开函数声
明的定位器结构的名称
打开模式标志 intoflags，其中 oflags 是包含打开模式标志的变量
如果 GBase 8s ESQL/C 调用打开函数将简单大对象发送给数据库，则该标志包含
LOC_RONLY。如果 GBase 8s ESQL/C 调用函数接受来自数据库的数据，则包含
LOC_WONLY 。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 162 -
用户定义的打开函数必须为打开操作返回成功代码，如下所示：
0
初始化成功。
-1
初始化失败。该返回码生成 loc_status （和 SQLCODE）-452 错误。
下图显示了用户定义的打开函数的骨架功能。
图 11. 用户定义的打开函数示例
open_simple_lo(adloc, oflags)
ifx_loc_t *adloc;
int oflags;
{
adloc->loc_status = 0;
adloc->loc_xfercount = 0L;
if (0 == (oflags & adloc->loc_oflags))
return(-1);
if (oflags & LOC_RONLY)
/*** prepare for store to db ***/
else
/*** prepare for fetch to program ***/
return(0);
}
用户定义的读取函数
要定义如何读取用户定义的位置，可以创建名为用户定义的读取函数的 C 函数。
当 GBase 8s ESQL/C 将数据发送给数据库服务器时，它从字符缓冲区读取该数据。
要将来自用户定位位置的数据传输到数据库服务器，它从字符缓冲区读取该数据。要将用
户定义位置的数据传输到缓冲区，
GBase 8s ESQL/C 调用用户定义的读取函数。
您的 GBase
8s ESQL/C 程序必须在定位器结构的 loc_read 字段中提供用户定义的读取函数的地址。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 163 -
该用户定义读取函数必须接收以下三个参数：
定位器结构的地址 ifx_loc_t *loc_struc，
其中 loc_struc 是您的用户定义的读取函数使
用的定位器结构
将数据发送到数据库服务器的缓冲区的地址 char *buffer，其中 buffer 是您程序分配
的缓冲区
要从用户定义位置读取的字节数 intnread，其中 nread 是包含字节数的变量
该函数必须将来自用户定义的位置的数据传输给 buffer 指示的字符缓冲区。
GBase 8s
ESQL/C 可能会多次调用该函数从用户定义的位置读取单个简单大对象值。每个调用接收
一段数据的地址和长度。跟踪用户定义的读取函数中用户定义位置的当前查找位置。您可
能需要使用 loc_position 或 loc_currdata_p 字段用于此目的。还可以使用 loc_xfercount
字段跟踪读取的数据量。
用户定义的读取函数必须返回读取操作的成功代码，如下所示：
>0
读取操作成功。返回值指示实际从定位器结构读取的字节数。
-1
读取操作失败。该返回码生成 -454 的 loc_status （和 SQLCODE）错误。
下图显示了用户定义的读取函数的骨架功能。
图 12. 用户定义的读取函数示例
read_simple_lo(adloc, bufp, ntoread)
ifx_loc_t *adloc;
char *bufp;
int ntoread;
{
int ntoxfer;
ntoxfer = ntoread;
if (adloc->loc_size != -1)
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 164 -
ntoxfer = min(ntoread,
adloc->loc_size - adloc->loc_xfercount);
/*** transfer "ntoread" bytes to *bufp ***/
adloc->loc_xfercount += ntoxfer;
return(ntoxfer);
}
用户定义的写入函数
要定义如何写入用户定义的位置，
您将创建一个名为用户定义的写入函数的 C 函数。
当 GBase 8s ESQL/C 接收来自数据库服务器的数据时，它将此数据存储在字符缓冲
区。要将来自缓冲区的数据传输到用户定义的位置，GBase 8s ESQL/C 调用用户定义的写
入函数。
您的 GBase 8s ESQL/C 程序必须在定位器结构的 loc_write 字段中提供用户定义
的写入函数的地址。
该用户定义写入函数必须接收以下三个参数：
定位器结构的地址 ifx_loc_t *loc_struc，
其中 loc_struc 是您的用户定义的写入函数使
用的定位器结构
接收来自数据库服务器的数据的缓冲区的地址 char *buffer，其中 buffer 是您的程序
分配的缓冲区
写入用户定义的位置的字节数 intnwrite，其中 nwrite 是包含字节数的变量
用户定义的写入函数必须传输来自字符缓冲区的数据，
buffer 指示到用户定义的位置。
GBase 8s ESQL/C 可能多次调用函数以将简单大对象值写入到用户定义的位置。每个调用
接收一段数据的地址和长度。跟踪用户定义的写入函数中用户定义位置的当前查找位置。
您可能需要使用 loc_position 或 loc_currdata_p 字段用于此目的。还可以使用
loc_xfercount 字段跟踪写入的数据量。
用户定义的写入函数必须返回写入操作的成功代码，如下所示：
>0
写入操作成功。返回值指示写入用户定义位置的字节数。
-1
写入操作失败。该返回码生成 -455 的 loc_status （和 SQLCODE）错误。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 165 -
下图显示了用户定义的写入函数的骨架功能。
图 13. 用户定义的写入函数的示例
write_simple_lo(adloc, bufp, ntowrite)
ifx_loc_t *adloc;
char *bufp;
int ntowrite;
{
int xtoxfer;
ntoxfer = ntowrite;
if (adloc->loc_size != -1)
ntoxfer = min(ntowrite,
(adloc->loc_size) - (adloc->loc_xfercount));
/*** transfer "ntowrite" bytes from *bufp ***/
adloc->loc_xfercount += ntoxfer;
return(ntoxfer);
}
用户定义的关闭函数
要定义如何执行清除用户定义的位置，您将创建一个名为用户定义的关闭函数的 C
函数。
当传输到数据库服务器或从数据库服务器传输完成时，GBase 8s ESQL/C 调用由定位
器结构的 loc_close 字段提供的关闭函数，
清除任务包括关闭文件或释放用户定义的位置使
用的内存。
该函数必须接收一个参数：
定位器结构的地址 ifx_loc_t *loc_struc ，
其中 loc_struc 是
您的用户定义的关闭函数使用的定位器结构。用户定义的关闭函数为此关闭操作返回成功
码如下所示：
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 166 -
0
清除操作成功。
-1
清除操作失败。该返回码生成 -455 的 loc_status （和 SQLCODE）错误。
下图显示了用户定义的关闭函数的骨架功能。
图 14. 用户定义的关闭函数示例
close_simple_lo (adloc)
ifx_loc_t *adloc;
{
adloc->loc_status = 0;
if (adloc->loc_oflags & LOC_WONLY) /* if fetching */
{
adloc->loc_indicator = 0; /* clear indicator */
adloc->loc_size = adloc->loc_xfercount;
}
return(0);
}