更新日期：2024年09月11日
置参数（SQL 管理 API）
随同 admin() 或 task() 函数，使用 set onconfig memory 参数来动态地更新内存中配置参
数的值。
语法
元素
描述
关键考虑
configuration_parameter_name
配置参数的名称。 该配置参数必须是您可动态地更新
的。
您可动态地更新的配置参数列表与
onmode -wf 命令的相同。
new_value
该配置参数的一个
或多个新的值。
该配置参数的这个或这些新的值必
须是有效的。
新值的格式必须严格地遵循那个配
置参数的语法。
用法
GBase 8s 管理员参考
南大通用数据技术股份有限公司 - 791 -
使用这个函数来临时地更新可动态地更新的配置参数的值。新的值立即生效。新的值不写
到 onconfig 文件，当数据库服务器重启时，新的值丢失。
这个函数等同于 onmode -wm 命令。
示例
下列示例为当前会话设置 DYNAMIC_LOGS 配置参数的值为 2：
EXECUTE FUNCTION task("set onconfig memory","DYNAMIC_LOGS","2");
GBase 8s ESQL/C 在 UNIX™ 和 Windows™ 操作系统上提供共享的和静态线程安
全以及共享和静态的缺省版本的 GBase 8s 通用库。在 Windows 操作系统中，GBase 8s
ESQL/C 提供名为 isqlt09a.dll 的 DLL 以及名为 isqlt09s.lib 的静态线程安全库。
线程安全 GBase 8s ESQL/C 应用程序的每个线程可以有一个活动连接。每个应用程
序可以有多个线程。线程安全库包含线程安全（或可重入）函数。线程安全函数是当多个
线程同时调用它时正常运行的函数。
对于 UNIX™ 操作系统上的 GBase 8s ESQL/C，
线程安全 GBase 8s 通用库使用来自
分布式计算环境（DCE）线程包的函数。DCE 线程库（Open Software Foundation （OSF）
开发）为线程安全应用程序创建标准接口。
如果 DCE 线程库在您的操作系统上不可用，
则 ESQL/C 可以使用 POSIX 线程库或
Sun Solaris 线程库。
如果您的操作系统支持 DCE 、POSIX 或 Solaris 线程包，则必须将它们安装在与
ESQL/C 相同的客户端计算机上。
在 Windows 环境中， GBase 8s 通用库使用 Windows API 来确保它们是线程安全。
使用程序安全 GBase 8s 通用库，
可以开发线程安全 GBase 8s ESQL/C 应用程序。
线
程安全应用程序可以控制许多线程。它将一个进程分隔成多个可执行线程，每个线程独立
运行。当非线程的 GBase 8s ESQL/C 应用程序可以建立与一个或多个数据库的连接时，但
它一次只能有一个活动连接。
活动连接时准备好处理 SQL 请求的连接。
线程安全的 GBase
8s ESQL/C 应用程序灭个线程可以有一个连接，每个应用程序可以有多个线程。
当指定 -thread 命令行选项时，
esql 命令将此选项发送给 GBase 8s ESQL/C 预处理器
esqlc。使用 -thread 选项，GBase 8s ESQL/C 预处理器生成线程安全的代码， 不同的线
程可以并发执行。
线程安全 ESQL/C 代码的特征
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 390 -
线程安全 GBase 8s ESQL/C 代码具有不同于非线程按代码的以下特征：
线程安全代码无法定义任何静态数据结构。
例如：
GBase 8s ESQL/C 自动分配 sqlda 结构，
并在运行时将主机变量与这些 sqlda
结构绑定。
线程安全代码动态地声明游标块而不是静态地声明它们。
线程安全代码使用状态变量的宏定义（SQLCODE 、SQLSTATE 和 sqlca 结构）。
由于上述的不同，GBase 8s ESQL/C 预处理器生成的线程安全 C 源文件（.c） 与非
线程安全的 C 源文件不同。
因此，
不能将用 -thread 选项编译的 GBase 8s ESQL/C 应用
程序与用 -thread 选项编译的应用程序相链接。要链接这些应用程序，您必须使用
-thread 选项编译这两个应用程序。
编写线程安全 ESQL/C 应用程序
本节介绍如何创建线程安全 GBase 8s ESQL/C 应用程序。
并发活动连接
在线程安全 GBase 8s ESQL/C 应用程序中，数据库服务器连接可以是以下之一的状
态：
活动的数据库服务器连接已经准备好处理 SQL 请求。
线程安全 GBase 8s ESQL/C 应用程序的主要优点是每个线程都可以有一个到数据库
服务器的活动连接。
使用 CONNECT 语句建立连接并激活它。
使用 SET CONNECTION 语
句（没有 DORMANT 子句）来激活休眠的连接。
已建立休眠的数据库服务器连接 ，当前不与线程相关联。
当线程使活动连接处于休眠状态时，则该连接将可用于其它线程。相反，当线程使休
眠连接处于活动状态时，该连接将变得不可用于其它线程。使用 SET
CONNECTION...DORMANT 语句显式地将连接置于休眠状态。
当前连接是当前向数据库服务器发送 SQL 请求并可能从数据库服务器的活动数据库
服务器连接。
单线程应用程序一次只有一个当前
（或活动的）
连接。
在多线程应用程序中，
每个线程都可以具有当前连接。因此，多线程应用程序可以同时具有多个活动连接。
当您使用 SET CONNECTION 语句（没有 DORMANT 子句）语句切换连接时，SET
CONNECTION 隐式地将当前连接置于休眠状态。在休眠状态时，连接可用于其它线程。
任何线程可以访问任何休眠连接。但是，一个线程一次只能具有一个活动连接。
下图显示了线程安全 GBase 8s ESQL/C 应用程序建立了三个并发连接，每个连接处
于活动状态。
图: 线程安全 ESQL/C 应用程序中的并发连接
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 391 -
在上图中，GBase 8s ESQL/C 应用程序由以下三个线程构成：
主线程（主函数）启动连接 con1 到 Server_1 上的数据库 db1。
主线程创建线程 2。线程 2 建立到 Server_1 上的数据库 db1 的连接 con2。
主线程创建线程 3。线程 3 建立到 Server_2 上的数据库 db2 的连接 con3。
图 1中的连接都是并发活动的，都可以执行 SQL 语句。以下代码片段建立了图 1显
示的连接。它没有显示 DCE 相关的调用，以及 start_threads() 函数的代码。
main()
{
EXEC SQL connect to 'db1@Server_1' as 'con1';
start_threads(); /* start 2 threads */
EXEC SQL select a into :a from t1; /* table t1 resides in db1 */
⋮
}
thread_1()
{
EXEC SQL connect to 'db1@Server_1' as 'con2';
EXEC SQL insert into table t2 values (10); /* table t2 is in db1 */
EXEC SQL disconnect 'con2';
}
thread_2()
{
EXEC SQL connect to 'db2@Server_2' as 'con3';
EXEC SQL insert into table t1 values(10); /* table t1 resides in db2
*/
EXEC SQL disconnect 'con3';
}
可以使用 ifx_getcur_conn_name() 函数获得当前连接的名称。
跨线程连接
如果您的应用程序包含需要使用相同连接的线程，则一个线程可能在另一个线程需要
访问时使用该连接。违例避免这种争用，您的 GBase 8s ESQL/C 应用程序必须管理对连接
的访问。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 392 -
管理几个线程必须使用连接的最简单的方法是将 SET CONNECTION 语句放到循环
中。以下代码片段显示了 SET CONNECTION 循环示例。
/* wait for connection: error -1802 indicates that the connection
is in use
*/
do {
EXEC SQL set connection :con_name;
} while (SQLCODE == -1802);
上述算法等待主机变量 :con_name 名称变为可用的连接。
然而，
这种方法的缺点是
它消耗了处理器周期。
以下代码片段使用 CONNECT 语句创建连接，
使用 SET CONNECTION 语句激活线
程中的休眠的连接。它还使用 SET CONNECTION...DORMANT 激活休眠的连接。此代码
片段建立图 1中所示的连接。它无法显示 DCE 相关的调用，以及 start_threads() 函数的
代码。
main()
{ EXEC SQL BEGIN DECLARE SECTION;
int a;
EXEC SQL END DECLARE SECTION;
start_threads(); /* start 2 threads */
wait for the threads to finish work.
/* Use con1 to update table t1; Con1 is dormant at this point.*/
EXEC SQL set connection 'con1';
EXEC SQL update table t1 set a = 40 where a = 10;
/* disconnect all connections */
EXEC SQL disconnect all;
}
thread_1()
{
EXEC SQL connect to 'db1' as 'con1’;
EXEC SQL insert into table t1 values (10); /* table t1 is in db1*/
/* make con1 available to other threads */
EXEC SQL set connection 'con1' dormant;
/* Wait for con2 to become available and then update t2 */
do {
EXEC SQL set connection 'con2';
} while ((SQLCODE == -1802) );
if (SQLCODE != 0)
return;
EXEC SQL update t2 set a = 12 where a = 10; /* table t2 is in db1 */
EXEC SQL set connection 'con2' dormant;
}
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 393 -
thread_2()
{ /* Make con2 an active connection */
EXEC SQL connect to 'db2' as 'con2';
EXEC SQL insert into table t2 values(10); /* table t2 is in db2*/
/* Make con2 available to other threads */
EXEC SQL set connection'con2' dormant;
}
在此代码中，thread_1() 使用 SET CONNECTION 语句循环（参见图 1）来等待
con2 变成可用状态。当 thread_2() 使 con2 休眠，其它线程可以使用此连接。同时，
thread_1() 中的 SET CONNECTION 语句成功，
并且 thread_1() 可用使用 con2 连接
更新表 t2。
DISCONNECT ALL 语句
DISCONNECT ALL 语句按顺序断开应用程序中的所有连接。
在线程安全 GBase 8s ESQL/C 应用程序中，只有发出 DISCONNECT ALL 语句的线
程可以处理 SQL 语句（在这情况中，是 DISCONNECT ALL 语句）。如果任何其它语句
正在执行 SQL 语句，则当 DISCONNECT ALL 语句尝试断开此连接失败。此故障可能会
使应用程序处于不一致的状态。
例如，假设 DISCONNECT ALL 语句成功断开连接 A 和连接 B 但是无法断开连接
C ，
因为此连接正在处理一个 SQL 语句。
DISCONNECT ALL 语句失败，
连接 A 和 B 断
开但是连接 C 打开。建议您在所用的线程完成它们的工作后在应用程序的主函数中发出
DISCONNECT ALL 语句。
当 DISCONNECT ALL 语句按顺序断开应用程序连接时，GBase 8s ESQL/C 阻止其
它连接请求。如果别的线程在 DISCONNECT ALL 语句执行时请求连接，则此连接必须等
待直到 DISCONNECT ALL 语句完成，然后 GBase 8s ESQL/C 可以发送此新的连接请求
到数据库服务器。
跨线程的预备语句
PREPARE 语句的作用域在连接级别。即，它们与连接相关联。当线程激活连接，它
可以访问与此连接相关联的任何准备好的语句。
如果您的线程安全的 GBase 8s ESQL/C 应
用程序使用准备好的语句，则您可能需要隔离 PREPARE 语句的编译，以便在程序中仅编
译一次。
构建应用程序的一种可能方法是执行将连接上下文初始化为一组的语句。连接上下文
包括当前用户的名称和数据库环境与此名称相关联的信息（包括准备好的语句）。
对于每个连接，应用程序将执行以下步骤：
使用 CONNECT 语句建立线程所需的连接。
使用 PREPARE 语句编译与连接相关联的任何 SQL 语句。
使用 SET CONNECTION...DORMANT 语句将连接置于休眠状态。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 394 -
当连接是休眠的，任何线程可以通过 SET CONNECTION 语句访问休眠的连接。当
线程激活连接时，它可以发送对应的预备的语句到数据库服务器执行。
在下图中，代码片段在连接初始化时准备 SQL 语句，然后在程序中执行它们。
图: 跨线程使用准备好的 SQL 语句
图 1中的代码执行以下操作：
主线程调用 start_con_threads()，它调用 start_con_thread() 来启动两个线程：
对于线程 1，start_con_thread() 函数建立连接 con1，准备名为 s1 的语句，使连接
con1 休眠。
对于线程 2，start_con_thread() 函数建立连接 con2，准备名为 s2 的语句，使连接
con2 休眠。
主线程调用 start_execute_threads()，它调用 start_execute_thread() 来为每个线程执
行准备好的语句：
对于线程 1，
start_execute_thread() 函数激活连接 con1，
执行与 con1 相关联的 s1 准
备语句，并使 con1 休眠。
对于线程 2，
start_execute_thread() 函数激活连接 con2，
执行与 con2 相关联的 s2 准
备语句，并使 con2 休眠。
主线程断开所有连接。
跨线程游标
如同准备的语句一样，游标在连接级别被限定。也就是说，它们与连接相关联。当线
程使连接处于活动状态时，它可以访问此连接声明的任何数据库游标。如果线程安全的
GBase 8s ESQL/C 应用程序使用数据库游标，则可能需要以与隔离预备语句相同的方式隔
离游标声明。以下代码片段显示了 start_con_thread() 函数的修改版本（在图 1中）。本版
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 395 -
本准备 SQL 语句，并为此语句声明游标：
EXEC SQL connect to 'db1' as 'con1';
EXEC SQL prepare s1 ....
EXEC SQL declare cursor cursor1 for s1;
EXEC SQL set connection 'con1' dormant;
跨线程环境变量
在 GBase 8s ESQL/C线程安全应用程序中，环境变量不是线程作用域的。即，如果线
程更改特定环境变量的值，则此更改也可在所有其它线程中显示。
消息文件描述符
缺省情况下，
ESQL/C 会在关闭消息文件时释放消息文件的所有的文件描述符。
但是，
作为性能优化，您可以设置环境变量 IFX_FREE_FD ，以使如果正在关闭的消息文件对另
一线程打开，GBase 8s ESQL/C 不会释放文件描述符。如果将 IFX_FREE_FD 设置为 1，
则 GBase 8s ESQL/C 仅为关闭文件的线程释放消息文件描述符。
Decimal 函数
GBase 8s ESQL/C 库的 dececvt() 和 decfcvt() 函数返回一个字符串，
如果两个线程同
时调用这些函数则可以覆盖此字符串。出于此原因，请使用这些函数的线程安全版本
ifx_dececvt() 和 ifx_decfcvt()。
DCE 限制（UNIX™）
线程安全的 GBase 8s ESQL/C 代码也适用于 DCE 线程包实现的所有限制。DCE 要
求所有使用 DCE 线程库的的应用程序符合 ANSI 标准。本节列出了一些限制，当创建
GBase 8s ESQL/C 应用程序请记住这些限制。
操作系统调用
必须将线程安全的 GBase 8s ESQL/C 应用程序中的所有操作系统调用替换为 DCE
线程套件程序。线程套接字符采用系统调用的名称，但是在调用事件系统服务之前，它们
将调用 DCE pthread_lock_global_np() 函数来锁定全局互斥锁（mutex）。
（ Mutexes 通过
确保一次只有一个线程执行代码的关键部分来按顺序执行线程。DCE 包含文件 pthread.h
定义了系统调用的套接版本。
fork() 操作系统调用
在 DCE 环境中，限制使用 fork() 操作系统调用。一般来说，在调用 fork() 之前终
止所有线程。
此规则的一个例外是当 fork() 系统调用紧跟在 fork() 调用之后。
如果您的应
用程序使用 fork()，
则建议子进程在执行任何 GBase 8s ESQL/C 语句之前调用 sqldetach()。
资源分配
建议您将紧急循环中的 DCE pthread_yield() 调用包含在内，
以体现调度程序更具需要
分配资源。对 pthread_yield() 的调用指示 DCE 调用程序尝试统一分配资源。如果一个线
程陷入紧密循环，等待连接（从而阻止其他线程进行）。以下代码片段显示 pthread_yield()
例程的调用：
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 396 -
/* loop until the connection is available*/
do
{
EXEC SQL set connection :con_name;
pthread_yield();
} while (SQLCODE == -1802);
链接线程安全库
当指定 -thread 命令行选项时，esql 命令链接静态或共享的线程安全版本的 GBase
8s 通用库。
UNIX 系统上将线程安全 GBase 8s 通用库链接到 ESQL/C 模块
在 UNIX™ 操作系统上，
执行以下步骤来将线程安全 GBase 8s 通用库链接到 GBase
8s ESQL/C 模块：
将 DCE 线程包安装到 GBase 8s ESQL/C 产品的同一客户端的计算机上。
如果 DCE 不可用于您的平台，则 ESQL/C 可以使用 POSIX 线程库或 Sun Solaris
线程库。
设置 THREADLIB 环境变量以指示当编译程序时使用哪个线程包。
以下 C-shell 命令将 THREADLIB 设置为 DCE 线程包：
setenv THREADLIB DCE
SOL 和 POSIX 也是 THREADLIB 环境变量的有效选项。
重要： 此版本的 GBase 8s ESQL/C 仅支持 DCE 线程包。
使用 esql 命令编译您的程序，并指定 -thread 命令行选项。
-thread 命令行选项告诉 esql 生成线程安全代码并在线程安全库中链接。以下命令将
线程安全共享库与 file.exe 可执行文件相链接：
esql -thread file.ec -o file.exe
-thread 命令行选项说明 esql 命令以执行以下步骤：
将 -thread 选项发送给 GBase 8s ESQL/C 预处理器来生成线程安全代码。
使用 -DIFX_THREAD 命令行选项调用 C 编译器。
将合适的线程库（共享或静态）链接到可执行文件。
提示： 比较在使用带有 -thread 命令行选项的 esql 命令前设置 THREADLIB 环境
变量。
如果指定 -thread 选项但不设置 THREADLIB，
或者如果将 THREADLIB 设置为某
些不支持的线程包，则 esql 命令发出下列消息：
esql: When using -thread, the THREADLIB environment variable
must be set to a supported thread library. Currently
supporting: DCE, POSIX(Solaris 2.5 and higher only) and
SOL (Solaris Kernel Threads)
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 397 -
定义线程安全变量（UNIX™）
当指定 esql 的 -thread 命令行选项时，GBase 8s ESQL/C 预处理器将
IFX_THREAD 定义传递给 C 编译器。
IFX_THREAD 定义告诉 C 编译器为非线程安全的
GBase 8s ESQL/C 代码创建线程范围变量。
例如，当 C 编译器包含设置了 IFX_THREAD 的 sqlca.h 文件时，它为 GBase 8s
ESQL/C 状态变量定义线程范围变量：SQLCODE 、SQLSTATE 和 sqlca 结构。线程范
围版本的状态变量是将全局状态变量映射到线程安全函数调用的宏。可以获取特定于线程
的状态信息。
下图显示了具有 GBase 8s ESQL/C 状态变量的线程范围定义的 sqlca.h 文件的摘录。
图: 线程范围状态变量的声明
⋮
extern struct sqlca_s sqlca;
extern int4 SQLCODE;
extern char SQLSTATE[];
#else /* IFX_THREAD */
extern int4 * ifx_sqlcode();
extern struct sqlca_s * ifx_sqlca();
#define SQLCODE (*(ifx_sqlcode()))
#define SQLSTATE ((char *)(ifx_sqlstate()))
#define sqlca (*(ifx_sqlca()))
#endif /* IFX_THREAD */
链接共享或静态版本
要告诉 esql 命令将 GBase 8s 库的线程安全版本链接到应用程序中，请使用 esql 的
-thread 命令行选项。如下所示：
线程安全共享库仅需要 -thread 命令行选项。
线程安全静态库需要 -thread 和 -static 命令行选项。
将线程安全的 GBase 8s 通用库链接到 Windows 环境中的 ESQL/C 模块
要创建线程安全的 GBase 8s ESQL/C 应用程序，您必须执行以下步骤：
在您的 GBase 8s ESQL/C 源文件中，
包括适当的线程函数和 Windows™ API 的变量。
当编译 GBase 8s ESQL/C 源文件时，指定 esql 命令的 -thread 命令行选项。
-thread 选项告诉 GBase 8s ESQL/C 预处理器当它翻译 SQL 和 GBase 8s ESQL/C
语句时，
生成线程安全 C 代码。
此线程安全代码包含 GBase 8s DLL 中线程安全函数的调
用。
如果您没有创建具有线程的 GBase 8s ESQL/C 应用程序，则忽略 -thread 选项。尽
管 GBase 8s DLL 是线程安全的，但是当您忽略 -thread 时，您的非线程安全应用程序不
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 398 -
能使用线程安全功能。