GBase 8s ESQL/C 支持具有 ifx_lo_t 数据类型的 SQL 数据类型 CLOB 和 BLOB 。
由于智能大对象数据的潜在的巨大规模，GBase 8s ESQL/C 程序不会直接将数据存储在主
机变量中。相反，客户端应用程序以类似文件的结构访问数据。要在 GBase 8s ESQL/C 程
序中使用智能大对象，请采取以下操作：
使用 ifx_lo_t 数据类型声明主机变量。
使用以下三个数据结构的组合访问智能大对象：
LO 特定的结构 ifx_lo_create_spec_t
LO 指针结构 ifx_lo_t
整数 LO 文件描述符
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 187 -
重要：
ESQL/C 用于访问智能大对象的数据结构以 LO 前缀开头。
这个前缀是大对象
的缩写。目前，数据库服务器使用大对象来引用智能大对象和简单大对象。然而，为了遗
留目的，保留在访问智能大对象的 ESQL/C 结构中使用此前缀。
声明主机变量
声明用于具有 ifx_lo_t 结构
（名为 ifx_lo_t 数据类型）
的固定二进制主变量的类型为
CLOB 或 BLOB 的数据库列的 GBase 8s ESQL/C 主机变量，如下所示：
EXEC SQL include locator;
⋮
EXEC SQL BEGIN DECLARE SECTION;
fixed binary 'clob' ifx_lo_t clob_loptr;
fixed binary 'blob' ifx_lo_t blob_loptr;
EXEC SQL END DECLARE SECTION;
⋮
EXEC SQL select blobcol into :blob_loptr from tab1;
要访问智能大对象，您必须在您的 GBase 8s ESQL/C 程序中包含 locator.h 头文件。
该头文件包含数据结构的定义和程序需要使用智能大对象的常量。
LO 特定结构
在创建新的智能大对象之前，
必须使用 ifx_lo_def_create_spec() 函数分配 LO 特定结
构。
ifx_lo_def_create_spec() 函数执行以下任务：
它分配新的 LO 特定结构，它的指针作为参数提供。
它初始化 LO 特定结构的所有字段：磁盘存储选项和创建时间标志到适当的空值。
ifx_lo_create_spec_t 结构
LO 特定结构 ifx_lo_create_spec_t，
存储 GBase 8s ESQL/C 程序中智能大对象的存储
特征。
locator.h 头文件定义 LO 特定结构，因此您必须在访问此结构的 GBase 8s ESQL/C
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 188 -
程序中包含 locator.h 文件。
重要： LO 特定结构 ifx_lo_create_spec_t 对 GBase 8s ESQL/C 程序来说是不透明
数据类型。不要直接访问它的内容结构。ifx_lo_create_spec_t 的内部结构可能在之后的编
译过程中发生改变。因此，要创建便捷式代码，请始终使用 GBase 8s ESQL/C 访问函数来
获取和存储 LO 特定结构中的值。
LO 特定结构存储智能大对象的以下结构特征：
磁盘存储信息
创建时间标志
磁盘存储信息
LO 特定结构存储磁盘存储信息，它有助于数据库服务器确定如何在磁盘上最有效地
存储智能大对象。
下表显示了相应的 GBase 8s ESQL/C 访问函数的磁盘存储信息。
表 1. LO 特定结构中的磁盘存储信息
磁盘存储信息
描述
ESQL/C 访问程序函数
估计字节数
估计智能大对象的最终大小
（以字节
为单位）。数据库服务器使用此值来确定
要存储智能大对象的区域。
此值提供优化
信息，如果值严重不正确，则不会导致错
误的行为。但是，这意味着数据库服务器
可能不一定为智能大对象选择最佳扩展
大小。
ifx_lo_specget_estbyte
s()
ifx_lo_specset_estbytes
()
最大字节数
智能大对象的最大字节数
（以字节为
单位）。数据库服务器不允许智能大对象
超过此大小。
ifx_lo_specget_maxbyt
es()
ifx_lo_specset_maxbyt
es()
分配 extent 大小
分配的 extent 大小以千字节为单
位。最佳情况下，分配范围是容纳智能大
对象的所有数据的 chunk 中的单个
extent 。
数据库服务器以分配的 extent 大小
为增量为智能大对象执行存储分配。
它尝
ifx_lo_sepcget_extsz(),
ifx_lo_specset_extsz()
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 189 -
磁盘存储信息
描述
ESQL/C 访问程序函数
试将分配范围为一个 chunk 中的单个
extent。
但是，
如果单个 extent 不足够大，
则数据库服务器必须根据需要使用多个
extent 才能满足该请求。
sbspace 的名称
包含智能大对象的 sbspace 名称。
sbspace 名称最多可以为 18 字节长。该
名称必须以空终止。
ifx_lo_specget_sbspace
()
ifx_lo_specset_sbspace
()
对于大多数应用程序，建议您使用数据库服务器确定的磁盘存储信息。
创建时间标志
LO 特定结构存储创建时间标志，它告诉数据库服务器选择哪项分配给智能大对象。
下表显示了创建时间标志以及相应的 GBase 8s ESQL/C 存取函数。
表 2. LO 特定结构中的创建时间标志
指示符类型
创建时间标志
描述
日志记录
LO_LOG
告知数据库服务器将更改记录到系统
日志文件中的智能大对象。
仔细考虑是否使用 LO_LOG 标志
值。
数据库服务器使用相当大的开销来记录
智能大对象。
还必须确保系统日志文件足够
大以容纳智能大对象的值。
LO_NOLOG
告知数据库服务器关闭涉及智能大对
象的所有操作的日志记录。
最后一次
访问时间
LO_KEEP_LASTACCESS_
TIME
告知数据库服务器保存智能大对象的
最后访问时间。
此访问时间是上次读取或写
入操作的时间。
是否考虑使用
LO_KEEP_LASTACCESS_TIME 标志值。
数据库服务器使用相当大的开销来维护智
能大对象的最后访问时间。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 190 -
指示符类型
创建时间标志
描述
LO_NOKEEP_LASTACCES
S_TIME
告知数据库服务器不要维护智能大对
象的最后访问时间。
locator.h 头文件定义 LO_LOG 、
LO_NOLOG 、
LO_KEEP_LASTACCESS_TIME 和
LO_NOKEEP_LASTACCESS_TIME 创建时间常量。两组创建时间标志，记录指示符和最
后的访问时间指示符作为单个标志值存储在 LO 特定结构中。要设置每个组的标志，请使
用 C 语言 OR 运算符一起屏蔽两个标志值。但是屏蔽互斥标志会导致错误。
ifx_lo_specset_flags() 函数将创建时间标志为新值。ifx_lo_specget_flags() 函数检索创
建时间标志的当前值。
如果没有为其中一个标志组指定值，则数据库服务器将使用继承层次结构来确
定此信息。
使用 LO 特定结构的 ESQL/C 函数
下表显示访问 LO 特定结构的 GBase 8s ESQL/C 库函数。
ESQL/C 库函数
意义
请参阅
ifx_lo_col_info()
使用列级别存储特征更新
LO 特定结构
ifx_lo_col_info() 函
数
ifx_lo_create()
读取 LO 特定结构，以获
取其超级的新智能大对象的存
储特性
ifx_lo_create() 函数
ifx_lo_def_create_spec()
分配并初始化 LO 特定结
构
ifx_lo_def_create_spe
c() 函数
ifx_lo_spec_free()
释放 LO 特定结构的资源
ifx_lo_spec_free() 函
数
ifx_lo_specget_estbytes()
从 LO 特定结构获取估计
的字节数
ifx_lo_specget_estbyt
es() 函数
ifx_lo_specget_extsz()
从 LO 特定结构获取分配
extent 大小
ifx_lo_specget_extsz(
) 函数
ifx_lo_specget_flags()
从 LO 特定结构获取创建
时间标志
ifx_lo_specget_flags(
) 函数
ifx_lo_specget_maxbytes()
从 LO 特定结构获取最大
字节数
ifx_lo_specget_maxbyt
es() 函数
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 191 -
ESQL/C 库函数
意义
请参阅
ifx_lo_specget_sbspace()
从 LO 特定结构获取
sbspace 名称
ifx_lo_specget_sbspac
e() 函数
ifx_lo_specset_estbytes()
设置 LO 特定结构的字节
估计数
ifx_lo_specset_estbyt
es() 函数
ifx_lo_specset_extsz()
设置 LO 特定结构中的分
配 extent 大小
ifx_lo_specset_extsz(
) 函数
ifx_lo_specset_flags()
设置 LO 特定结构中的创
建时间标志
ifx_lo_specset_flags(
) 函数
ifx_lo_specset_maxbytes()
设置 LO 特定结构中的最
大字节数
ifx_lo_specset_maxbyt
es() 函数
ifx_lo_specset_sbspace()
设置 LO 特定结构中的
sbspace 名称
ifx_lo_specset_sbspac
e() 函数
ifx_lo_stat_cspec()
将存储特性返回给指定智
能大对象的 LO 特定结构
ifx_lo_stat_cspec()
函数
获得存储特征
在您使用 ifx_lo_def_create_spec() 函数分配 LO 特定结构后， 您必须保证在创建智
能大对象时此结构包含适当的存储特征。
GBase 8s 使用继承层次结构获取存储特征。
下图显示了智能大对象存储特征的继承层
次结构。
图 1. 存储特征的继承层次结构
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 192 -
系统指定的存储特征
GBase 8s 使用以下任一存储特征的设置作为系统指定的存储特征：
如果存储智能大对象的 sbspace 为特定存储特征指定了值，则数据库服务器使用
sbspace 值作为系统指定的特征。
数据库管理器（DBA）使用 onspaces 实用程序定义 sbspace 的存储特征。
如果存储智能大对象的 sbspace 没有为特定的存储特征指定值，则数据库服务器使用
系统缺省值作为系统指定的存储特征。
数据库服务器内部定义存储特征的系统缺省值。然而，您可以使用 onconfig 文件的
SBSPACENAME 配置参数指定缺省 sbspace 名。
并且，
应用程序可以调用 ifx_lo_col_info()
或 ifx_lo_specset_sbspace() 提供 LO 特定结构中的目标 sbspace。
重要： 如果您未指定 sbspacename 配置参数并且 LO 特定结构不包含目标 sbspace
的名称，则会发生错误。
建议您使用系统指定的磁盘存储信息的值。大多数应用程序不需要更改这些系统指定
的存储特征。
要对新的智能大对象使用系统指定的存储特征，请按以下步骤操作：
使用 ifx_lo_def_create_spec() 函数分配 LO 特定结构并初始化此结构为空值。
将 LO 特定结构传递给 ifx_lo_create_function 函数来创建智能大对象的实例。
ifx_lo_create() 函数创建一个智能大对象，其具有作为参数接收的 LO 特定结构中的
存储特征。因为之前对 ifx_lo_def_create_spec() 的调用在此结构中存储空值，所以数据库
服务器会将系统指定的特征分配给智能大对象的新实例。
列级别存储特征
数据库管理员（DBA）使用 CREATE TABLE 语句分配列级别的存储特征。CREATE
TABLE 的 PUT 子句为智能大对象列
（CLOB 或 BLOB）
指定存储特征。
syscolattribs 系
统目录表存储列级别存储特征。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 193 -
ifx_lo_col_info() 函数为智能大对象列获取列级别的存储特征。
要对新的智能大对象示
例使用列级别的存储特征，请按以下步骤操作：
使用 ifx_lo_def_create_spec() 函数分配 IO 特定结构并初始化此结构为空值。
将此 LO 特定结构传递给 ifx_lo_col_info() 函数并指定期望的列和表名作为参数。
该函数将列级别存储特征存储到指定的 LO 特定结构中。
将相同的 LO 特定结构传递给 ifx_lo_create() 函数来创建智能大对象的实例。
当 ifx_lo_create() 函数接收 LO 特定结构作为参数时，此结构包含之前调用
ifx_lo_col_info() 的列级存储特征。因此，数据库服务器将这些列级别特征分配给智能大对
象的新实例。
当您使用列级别存储特征时，通常不需要为智能大对象提供 sbspace 的名称。sbspace
名称在 CREATE TABLE 语句的 PUT 子句指定中或由 ONCONFIG 文件中的
SBSPACENAME 参数指定。
用户定义的存储特征
GBase 8s ESQL/C 应用程序可以为新的智能大对象定义一组独特的存储特征，如下所
示：
对于存储在列中的智能大对象，当创建智能大对象的实例时，可以覆盖列的某些存储
特征。
如果应用程序不覆盖某些或所有这些特征，则智能大对象使用列级别存储特征。
可以为每个智能大对象指定更广泛的特征集，因为智能大对象不受表列属性约束。
如果应用程序程序员不覆盖某些或所有的这些特征，则智能大对象继承系统指定的存
储特征。
要指定用户定义的存储特征，请为 LO 特定结构使用适当的 GBase 8s
ESQL/C 访问程序函数。
释放 LO 特定结构
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 194 -
完成 LO 特定结构指定后，使用 ifx_lo_spec_free() 函数释放分配给它的资源。当资
源被释放时，它们可以重新分配给您的程序所需的其它结构。
LO 指针结构
要对读取和写入操作打开智能大对象，GBase 8s ESQL/C 程序必须具有用于此智能大
对象的 LO 指针结构。此结构包含磁盘地址和智能大对象的一个唯一十六进制标识符。
要为新的智能大对象创建 LO 指针结构，请使用 ifx_lo_copy_to_file() 函数。
ifx_lo_copy_to_file() 函数执行以下操作：
它为新的智能大对象初始化 LO 指针结构，其指针作为参数。
新的智能大对象具有您提供的 LO 特定结构指定的存储特征。
它以指定的访问模式打开新的智能大对象，并返回在智能大对象上后续操作所需的
LO 文件描述符。
在调用 ifx_lo_create() 函数之前，必须调用 ifx_lo_def_create_spec() 创建新的智能大
对象。
存储智能大对象
GBase 8s ESQL/C 程序通过 LO 指针结构访问智能大对象。使用 LO 指针
结构的 ESQL/C 函数表中的 GBase 8s ESQL/C 库函数接受 LO 指针结构为参数。
通过 LO 指针结构，这些函数允许您创建并控制智能大对象，而不用将它绑定
到数据库行。
INSERT 或 UPDATE 语句不会执行智能大对象的实际输入。然而，它确实为应用程
序提供了识别要与列相关联的哪个智能大对象数据的方法。数据库表中的 CLOB 或
BLOB 列存储智能大对象的 LO 指针。因此。当您存储 CLOB 或 BLOB 列时，可以为
INSERT 或 UPDATE 语句的 ifx_lo_t 主机变量中的列提供 LO 指针结构。因此，您将
CLOB 和 BLOB 值的主变量声明为 LO 指针结构。
下图显示了 GBase 8s ESQL/C 客户端应用程序如果将智能大对象的数据传输给数据
库服务器。
图 2. 将来自客户端应用程序的智能大对象的数据传输到数据库服务器
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 195 -
只要 LO 指针结构存在， LO 指针结构标识的智能大对象就会存在。当您在数据库
中存储 LO 指针结构时，数据库服务器可以确保在适当时将智能大对象释放。
当您检索一行，然后更新该行包含的智能大对象时，数据库服务器将专门绑定该行以
更新智能大对象。此外，如果智能大对象需要很长时间才能更新或创建智能大对象（无论
日志记录是否启用，以及它们是否与表行相关联），都会为长事务创建长期更新。
ifx_lo_t 结构
LO 指针结构 ifx_lo_t 用作智能大对象的引用。它提供与安全相关的信息，并保存关
于智能大对象的实际磁盘位置的信息。
locator.h 头文件定义 LO 指针结构，因此您必须在访问此结构的 GBase 8s ESQL/C
程序中包含 locator.h 文件。
重要： LO 指针结构 ifx_lo_t 对 GBase 8s ESQL/C 程序来说是一个不透明结构。您
不能直接访问它的内部结构。ifx_lo_t 的内部结构可能会发生改变。
因此，
要创建便捷式代
码，使用正确的 GBase 8s ESQL/C 库函数来使用此结构。
LO 指针结构，并非 CLOB 或 BLOB 数据，存储在数据库的 CLOB 或 BLOB 列
中。因此，诸如 INSERT 和 SELECT 的 SQL 语句接受 LO 指针结构作为智能大对象列
的列值。声明 GBase 8s ESQL/C 主机变量保存智能大对象的值作为 ifx_lo_t 结构。
使用 LO 指针结构的 ESQL/C 函数
下表显示了访问 LO 指针结构的 GBase 8s ESQL/C 库函数，以及如何访问。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 196 -
ESQL/C 库函数
意义
请参阅
ifx_lo_copy_to_file()
将 LO 指针结构标识的智能大
对象复制到操作系统文件
ifx_lo_copy_to_file()
函数
ifx_lo_create()
为其创建的新智能大对象初始化
LO 指针结构，
并返回此智能大对象的
LO 文件描述符。
ifx_lo_create() 函数
ifx_lo_filename()
返回文件的名称，其中
ifx_lo_copy_to_file() 函数将存储 LO
指针标识的智能大对象
ifx_lo_filename() 函
数
ifx_lo_from_buffer()
将指定数量的字节从用户定义的
缓冲区复制到 LO 指针结构引用的智
能大对象中
ifx_lo_from_buffer()
函数
ifx_lo_release()
告知数据库服务器释放与 LO
指针结构引用的临时智能大对象相关
联的资源
ifx_lo_from_buffer()
函数
ifx_lo_to_buffer()
从 LO 指针结构引用的智能大
对象中将指定数量的字节复制到用户
定义的缓冲区中
ifx_lo_to_buffer() 函
数
LO 文件描述符
LO 文件描述符是一个整数值，以标识开放的智能大对象。
LO 文件描述符类似于操作系统文件的文件描述符。
它用于 I/O 处理服务器中的智能
大对象的数据。LO 文件描述符以搜索位置 0 开始。在接受 LO 文件描述符的 GBase 8s
ESQL/C 库函数中使用 LO 文件描述符。
使用 LO 文件描述符的 ESQL/C 库函数
下表显示了访问 LO 文件描述符的 GBase 8s ESQL/C 库函数。
ESQL/C 库函数
意义
请参阅
ifx_lo_close()
关闭 LO 文件描述符标识的
智能大对象，并释放 LO 文件描述
符
ifx_lo_close() 函数
ifx_lo_copy_to_lo()
将操作系统文件复制到 LO
文件描述符标识的打开智能大对象
中
ifx_lo_copy_to_lo()
函数
ifx_lo_create()
创建并打开新的智能大对象，
ifx_lo_create() 函数
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 197 -
ESQL/C 库函数
意义
请参阅
并返回 LO 文件描述符
ifx_lo_open()
打开智能大对象，并返回 LO
文件描述符
ifx_lo_open() 函数
ifx_lo_read()
读取来自 LO 文件描述符标
识的打开智能大对象的数据
ifx_lo_read() 函数
ifx_lo_readwithseek()
在 LO 文件描述符标识的打
开智能大对象中搜索指定的文件位
置，然后从此位置读取
ifx_lo_readwithseek()
函数
ifx_lo_seek()
移动 LO 文件描述符标识的
打开智能大对象的文件位置
ifx_lo_seek() 函数
ifx_lo_stat()
获取 LO 文件描述符标识的
打开智能大对象的状态信息
ifx_lo_stat() 函数
ifx_lo_tell()
确定 LO 文件描述符标识的
打开智能大对象中当前文件位置
ifx_lo_tell() 函数
ifx_lo_truncate()
以指定的偏移量截断 LO 文
件描述符标识的开放智能大对象
ifx_lo_truncate() 函
数
ifx_lo_write()
将数据写入到 LO 文件描述
符标识的打开智能大对象中
ifx_lo_write() 函数
ifx_lo_writewithseek()
在 LO 文件描述符标识的打
开智能大对象中搜索指定的文件位
置，让将数据写入到此位置
ifx_lo_writewithseek(
) 函数