The SYSBldPrepare Function

SYSBldPrepare( ) is a function signature that HCL OneDB™ defines in all databases. You can use it to register or to unregister DataBlade® modules, as an alternative to using the BladeManager utility.

The SYSBldPrepare( ) function has this definition:
CREATE FUNCTION informix.sysbldprepare (CHAR(64), CHAR(18))
   RETURNS INTEGER
   EXTERNAL NAME '$ONEDB_HOME/extend/ifxmngr/ifxmngr.bld(SYSBldCustomPrepare)'
   LANGUAGE C;

The returned integer shows whether the function call succeeded ( 0 ) or failed ( nonzero ).

The following restrictions apply to the database in which you invoke this built-in function:
  • The minimum STACKSIZE in the configuration file of the HCL OneDB instance should be at least 64K. (On some systems, the default stack size is 32K, but 64K is recommended for databases that use the SYSBldPrepare( ) function.
  • The function call cannot reference a remote database. You can only register or unregister a DataBlade module in the local database to which you are currently connected.
  • The database must support explicit transactions. You cannot invoke this function in an ANSI/ISO-compliant database, or in a database that does not support transaction logging.
  • In an Enterprise Replication cluster environment, the HCL OneDB instance that supports the database cannot be a remote secondary server, because such servers cannot directly support DDL operations, like those that this function performs. If a DataBlade module needs to be registered or unregistered on a secondary server, you must register or unregister that module on the primary server that the secondary server replicates.
.

This is the calling syntax of SYSBldPrepare( ):

Figure 1: SYSBldPrepare Function

1  EXECUTE FUNCTION SYSBLDPREPARE (  '
1 
2.1 %Module Reference
2.1 file
2.1 builtin
1 '
1 ,
1 '
1 CREATE
1  %Module Reference ' , ' DROP
2  ' ) ;
Module Reference

1  module
2.1  . major . minor . os_code C interim
2.1  . major . minor . os_code C *
2.1  . major . minor . os_code *
2.1  . major . minor . *
2.1  . major . minor *
2.1  . major . *
2.1  . major *
2.1  . *
2.1 *
Element Description Restrictions Syntax
module Name of a DataBlade module to register or unregister For ‘CREATE' module must be installed in $ONEDB_HOME/extend. For ‘DROP' it must be registered in the current database. String literal
file Name of a file that lists one or more DataBlade modules, each in Module Reference format Must exist in directory $ONEDB_HOME/extend/ifxmngr Character string with no suffix
major Integer specifying a major HCL OneDB release version Must match the major version of an installed or registered DataBlade module or wildcard Literal number
minor Integer specifying a minor HCL OneDB release version Must match the minor version of an installed or registered DataBlade module or wildcard Literal number
os_code Uppercase letter code for a supported operating system Valid options are F, H, T, or U. These codes are described in Chapter 1 of DataBlade Module Installation and Registration Guide. Literal character
interim Integer specifying an interim HCL OneDB release version Must match the interim version of an installed or registered DataBlade module or wildcard Literal number

You can invoke this function with the EXECUTE FUNCTION statement of SQL, or with the CALL statement of SPL. .

The first argument to SYSBldPrepare( ) specifies what DataBlade module or file to process. The second argument specifies whether to register ('CREATE') or to unregister (‘DROP') what the first argument specifies. If ‘DROP' is the second argument, the first argument must specify a DataBlade module, not a file.

Specifying a File as the First Argument

If ‘CREATE' is the second argument, the first argument must be either a single module reference or the name of a text file that specifies a list of one or more module references, each in the format of the Module Reference syntax segment in the syntax diagram above. (The text file cannot, however, list the name of another text file that lists module references.) By specifying a valid file as the first argument, you can register a set of DataBlade modules by a single call to the SYSBldPrepare( ) function.

The file can be one that you created, or it can be the builtin file that the database server creates. The builtin file includes a list of DataBlade modules that HCL OneDB classifies as built-in. These built-in DataBlade modules are distributed with HCL OneDB and are installed in the $ONEDB_HOME/extend file system, but they cannot be accessed until they are registered in the database. Updates by users to this builtin file, which the database server maintains, are not supported.

Version Strings and Asterisk ( * ) Notation in Module References

When the first argument begins with the name of a DataBlade module, you can also specify the complete version string after a period ( . ) separator. A complete version string has in the same format as the return value of the DBINFO('version full') function of SQL or of the oninit -V utility, but is based on DataBlade module release versions.

The DataBlade module name or version string can be truncated with the asterisk ( * ) wildcard. How SYSBldPrepare( ) interprets the asterisk symbol depends on the second argument:
  • If 'CREATE' is the second argument, the asterisk matches the highest installed version of the specified module.
  • If 'DROP' is the second argument, the asterisk matches the registered version of the module among the DataBlade modules that are registered in the local database. No more than one version of a given DataBlade module can be registered in the database, so an asterisk that replaces the version string specifies the version that is registered.

Any asterisk symbol in a Module Reference that is not the last character is interpreted as a literal character, rather than as a wildcard.

Where SYSBldPrepare( ) searches for a module that the first argument specifies depends on the second argument:
  • If 'CREATE' is the second argument, the function searches among the modules that are installed in the $ONEDB_HOME/extend directory.
  • If 'DROP' is the second argument, the function searches for the specified version of the module among the DataBlade modules that are registered in the local database. Because no more than one version of a given DataBlade module can be registered in the database, an asterisk that replaces the version string specifies the version that is registered.

Registering and Unregistering DataBlade Modules

The second argument to this function must be either 'CREATE' or 'DROP':
  • Use 'CREATE' to register the installed DataBlade module (or the set of installed DataBlade modules listed in a file) that the first argument specifies.
  • Use 'DROP' to unregister the registered DataBlade module that the first argument specifies. The 'DROP' option cannot unregister more than one DataBlade module in a single call to SYSBldPrepare( ).

Successful invocation of the SYSBldPrepare( ) function with ‘CREATE' as its second argument also registers any DataBlade modules on which the module specified in the first argument is dependent.

For example, the following SQL statement registers the current of the BTS DataBlade module:
EXECUTE FUNCTION sysbldprepare ('bts.*', 'create');
The following SQL statement uses asterisk notation to unregister the highest version of the Node extension that is registered in the database:
EXECUTE FUNCTION sysbldprepare ('Node.*', 'drop');

Unlike registration operations, a call to SYSBldPrepare( ) that specifies 'DROP' as the second argument has no automatic effect on any DataBlade module that the first argument does not specify. The 'DROP' argument does not implicitly unregister other DataBlade modules that have dependency relationships with the module specified by the first argument.

Using SYSBldPrepare( ) in Transactions

The SYSBldPrepare( )function internally uses explicit transactions. If you issue the BEGIN WORK statement to begin a transaction in which you invoke SYSBldPrepare( ), the status of any changes to the database by DML or DDL statements in the same transaction, but before the call to SYSBldPrepare( ), is unpredictable. Changes from your DML or DDL operations might be committed when the internal transaction of SYSBldPrepare( ) is committed, thereby depriving you of any opportunity to roll back these changes by error-handling logic that follows the function call in the lexical order of SQL statements. To avoid this situation, do not invoke SYSBldPrepare( ) within transactions that you begin explicitly.

Exceptions in Calls to SYSBldPrepare( )

The SYSBldPrepare( ) function issues an error if you attempt to use the 'DROP' option to unregister a DataBlade module on which another DataBlade module that is currently registered in the database depends. For example, you cannot use this function to unregister the R-tree DataBlade module while the Spatial DataBlade module is still registered.For example, you cannot use this function to unregister the R-tree DataBlade module while the Example DataBlade module is still registered.

HCL OneDB also issues an error if SYSBldPrepare( ) attempts to unregister a DataBlade module that is not registered in the database.

The next example shows an attempt to register a DataBlade module that is not installed and the resulting error message:
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

If the IFX_EXTEND_ROLE configuration parameter is set to ON, authorization to invoke this routine is available only to the Database Server Administrator (DBSA), and others to whom the DBSA has granted the EXTEND role. By default, the DBSA is user informix.

Exceptions that occur while this function is executing can result in diagnostic error messages from SYSBldPrepare( ) that are not HCL OneDB error messages. Refer to the HCL OneDB DataBlade Module Installation and Registration Guide for information about error messages that SYSBldPrepare( ) can issue.