SYSBldPrepare 函数

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）。

以下限制应用于您调用此内置函数的数据库： .

这是调用 SYSBldPrepare( ) 的语法:

SYSBldPrepare 函数
Module Reference
元素 描述 限制 语法
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 错误消息的诊断错误消息。有关 SYSBldPrepare( ) 可用发出的错误消息的信息，请参阅 GBase 8s DataBlade 模块安装和注册指南 。

父主题： DataBlade 模块管理函数