GBase8s SYSBldPrepare函数

GBase8s SYSBldPrepare函数
从连接到支持显式事务日志记录的 GBase 8s 数据库的会话中，可以通过发出调用内置 SYSBldPrepare( ) 的 SQL 函数注册或注销 DataBlade 模块。另一个内置函数，SYSBldRelease( )，返回本地数据库中 SYSBldPrepare( ) 函数的版本字符串。
通过 SQL 函数注册和注销 DataBlade 模块的替代方法是使用 BladeManager 实用程序。BladeManager 实用程序可以执行多种 DataBlade 模块任务，包括注册、注销和显示有关 DataBlade 模块的信息。此实用程序支持命令行界面和图形用户界面。
SYSBldPrepare函数是GBase 8s 在服务器实例的所有数据库中定义的函数签名。可以使用它注册或注销 DataBlade 模块，另一种方法是使用 BladeManager 实用程序。
SYSBldPrepare()函数具有以下定义：
CREATE FUNCTION gbasedbt.sysbldprepare(CHAR(64),CHAR(18))
RETURNS INTEGER
EXTERNAL NAME ‘$GBASEDBTDIR/extend/ifxmngr/ifxmngr.bld(SYSBldCustomPrepare)’
LANGUAGE C;
返回的整数表示此函数调用成功（0）或失败（非0）。
以下限制应用于您调用此内置函数的数据库：
GBase 8s 实例的配置文件中的最小 STACKSIZE 应该至少为 64 K 。（在某些系统中，缺省的 stack 大小为 32K，但是对使用 SYSBldPrepare( ) 函数的数据库推荐使用 64 K ）。
该函数调用不能引用远程数据库。您只能在当前连接的本地数据库中注册或注销 DataBlade 模块。
数据库必须支持显式事务。您不能在兼容 ANSI/ISO 的数据库中调用此函数，或者在不支持事务日志记录的数据库中调用此函数。
在 Enterprise Replication 集群环境中，支持数据库的 GBase 8s 实例不能是远程辅助服务器。因为这种服务器不能直接支持 DDL 操作，就像此函数支持的 DDL 操作。如果要在辅助服务器上注册或注销 DataBlade 模块，您必须在辅助服务器复制的主服务器上注册或注销此模块。 .
这是调用 SYSBldPrepare( ) 的语法:
SYSBldPrepare 函数

元素 描述 限制 语法
module 要注册或注销的 DataBlade 模块的名称 要 ‘CREATE’ module 必须安装在 $GBASEDBTDIR/extend 中。要 ‘DROP’ 它则必须在当前数据库中注册。 字符串字符
file 列出一个或多个 DataBlade 模块的文件的名称，每个模块引用格式 必须在 $GBASEDBTDIR/extend/ifxmngr 目录中存在 Character string with no suffix
major 整数指定主要的 GBase 8s 发布版本 必须与已安装或已注册的 DataBlade 模块或通配符的主要版本匹配 数字字符
minor 整数指定 GBase 8s 次要的发布版本 必须与已安装或已注册的 DataBlade 模块或通配符的次要版本匹配 数字字符
os_code 支持的操作系统的大写字母代码 有效选项为 F 、H 、T 或 U。这些代码在 DataBlade 模块安装与注册指南的第一章中有所描述。 文字字符
interim 整数指定 GBase 8s 临时的发布版本 必须与已安装或已注册的 DataBlade 模块或通配符的临时版本匹配 数字字符
可以使用 SQL 的 EXECUTE FUNCTION 语句或 SPL 的 CALL 语句调用此函数。
SYSBldPrepare( ) 的第一个参数指定要处理的 DataBlade 模块或文件。第二个参数是注册 （‘CREATE’）还是 注销（‘DROP’）第一个参数必须指定一个 DataBlade 模块，而不是一个文件。
指定 File 作为 First 参数
如果 ‘CREATE’ 是第二个参数，则第一个参数必须是单个模块引用或文本文件的名称，它指定一个或多个模块引用的列表，每个模块引用语法的格式如上面的语法图所示。（但是，此文本文件不能列出列出模块引用的另一个文本文件的名称。）。通过将有效文件指定为第一个参数，可以在单次调用 SYSBldPrepare( ) 函数注册一组 DataBlade模块。
该文件可以是您创建的文件，也可以是数据库服务器创建的 builtin 文件。builtin 文件包括 GBase 8s 分类为内置的 DataBlade 模块的列表。这些内置 DataBlade 您可与 GBase 8s 一起分布，并安装在 $GBASEDBTDIR/extend 文件系统中，但在它们注册到数据库之前无法访问。不支持用户对数据库服务器维护的此 builtin 文件的更新。
模块引用中的版本字符串和星号（）符号
当第一个参数以 DataBlade 模块的名称开头时，您还可以执行句号（ .）分隔符之后的结束版本字符串。 完整的版本字符串与 SQL 的 DBINFO(‘version full’) 函数或 oninit -V 实用程序的返回值的格式相同， 但是它基于 DataBlade 模块的发布版本。
DataBlade 模块名称或版本字符串可以用星号（）通配符截断。SYSBldPrepare( ) 如何解释星号符号取决于第二个参数：
如果 ‘CREATE’ 是第二个参数，则星号与指定模块的最高安装版本匹配。
如果 ‘DROP’ 是第二个参数，则星号与在本地数据库中注册的 DataBlade 模块中的模块的注册版本相匹配。在数据库中可以注册给定 DataBlade 模块的最多一个版本 ，因此替换版本字符串的星号指定已注册的版本。
模块引用中不是最后一个字符的任何星号符号都将解释为文字字符，而不是通配符。
其中 SYSBldPrepare( ) 搜索第一个参数指定的模块取决于第二个参数：
如果 ‘CREATE’ 是第二个参数，则该函数在安装 $GBASEDBTDIR/extend 目录中的模块之间进行搜索。.
如果 ‘DROP’ 是第二个参数，则该函数将在本地数据库中注册的 DataBlade 模块的指定版本。因为在数据库中不能注册多个版本的给定 DataBlade 模块，所以替换版本字符串的星号指定已注册的版本。
注册和注销 DataBlade 模块
此函数的第二个参数必须是 ‘CREATE’ 或 ‘DROP’：
使用 ‘CREATE’ 注册第一个参数指定的已安装的 DataBlade 模块（或者一组已安装的 DataBlade 模块）。
使用 ‘DROP’ 注销第一个参数指定的已安装的 DataBlade 模块。‘DROP’ 选项不能在对 SYSBldPrepare( ) 的单次调用中注销多个 DataBlade 模块。
使用 ‘CREATE’ 作为其第二个参数成功调用 SYSBldPrepare( ) 函数还会注册在第一个参数中指定的模块依赖的任何 DataBlade 模块。例如，下面的 SQL 语句注册 8.21.FC2 版本 的 Example DataBlade 模块 ，并在当前数据库中隐式注册了 R-tree DataBlade 模块的最新安装版本，其中 Example DataBlade 模块具有依赖性，如果 R-tree DataBlade 模块尚未在数据库中注册：
EXECUTE FUNCTION sysbldprepare (‘example.8.21.FC2’, ‘create’);
但是，如果已经在数据库中注册了相同的 DataBlade 模块的不同发行版本，则如果 ‘CREATE’ 是第二个参数，则mSYSBldPrepare( ) 会升级。例如，上面的函数调用把 Example DataBlade 模块的版本 8.20.FC1 升级到版本 8.21.FC2，如果版本 8.20.FC1 在调用 SYSBldPrepare( ) 时已经在同一个数据库中注册，但是 R-tree DataBlade 模块不会被隐式升级。
以下 SQL 语句使用星号表示法注销在数据库中注册的 Node 扩展的最高版本：
EXECUTE FUNCTION sysbldprepare (‘Node.*’, ‘drop’);
与注册操作不同，调用指定 ‘DROP’ 作为第二个参数的 SYSBldPrepare( ) 不会对第一个参数未指定的任何 DataBlade 模块自动生效。‘DROP’ 参数不会隐式注销与第一个参数指定的模块具有依赖关系的其它 DataBlade 模块。
在事务中使用 SYSBldPrepare( )
SYSBldPrepare( ) 函数在内部使用显式事务。如果发出 BEGIN WORK 以及开始调用 SYSBldPrepare( ) 的事务，则在同一事务中，但在调用 SYSBldPrepare( ) 之前，DML 或 DDL 语句对数据库所做的任何更改的状态是不可预测的。当提交 SYSBldPrepare( ) 的内部事务时，可能会提交来自 DML 或 DDL 操作的更改，从而使您无法通过 SQL 语句的词法顺序中函数调用之后的错误处理逻辑回滚这些更改。要避免此情况，请不要在显式开始的事务中调用 SYSBldPrepare( ) 。
调用 SYSBldPrepare( ) 中的异常
如果尝试使用 ‘DROP’ 选项注销在当前数据库中注册的另一个 DataBlade 模块所依赖的另一个 DataBlade 模块，则 SYSBldPrepare( ) 函数会发出错误。例如，当在注册 Example DataBlade 模块时您不能使用此函数注销 R-tree DataBlade 模块mod。
如果 SYSBldPrepare( ) 试图注销未注册在数据库中的 DataBlade 模块， GBase 8s 也会发出错误。
以下示例显示尝试注册未安装的 DataBlade 模块以及生成的错误消息：
EXECUTE FUNCTION sysbldprepare (‘node.2.33’, ‘create’);

(U0001) - registerBlade - Unable to register node.2.33
– DataBlade module not found

• check online log and sysblderrorlog table for more information
  如果 IFX_EXTEND_ROLE 配置参数设置为 ON，那么调用此例程的授权仅对数据库服务器管理员（DBSA）和 DBSA 授予的 EXTEND 角色的其它人可用。缺省情况下，DBSA 是用户 gbasedbt。
  此函数执行时发生的异常可能导致 SYSBldPrepare( ) 发出不是 GBase 8s 错误消息的诊断错误消息。