IBM Informix RELEASE NOTES FOR IBM INFORMIX R-TREE DATABLADE MODULE 2.0, January 2004 ================================= TABLE OF CONTENTS I. OVERVIEW OF RELEASE NOTES II. IBM INFORMIX DATABASE SERVER COMPATIBILITY III. PRODUCT DESCRIPTION IV. GENERAL INFORMATION ON REGISTRATION V. REGISTERING IBM INFORMIX R-TREE DATABLADE VI. DEPENDENT DATABLADE MODULES VII. KNOWN PROBLEMS +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ I. OVERVIEW OF RELEASE NOTES ============================= The purpose of these release notes is to make you aware of any special actions required to configure and use the IBM Informix R-Tree DataBlade module. In addition, this document contains information about known bugs and their workarounds. The information in these release notes is not intended to be all- inclusive. For additional information on R-Tree features and behavior, consult the following IBM Informix manuals: o "IBM Informix R-Tree Index User's Guide" o "Extending IBM Informix Dynamic Server: Data Types" o "IBM Informix Dynamic Server Performance Guide" o "IBM Informix Guide to SQL: Reference" o "IBM Informix Guide to SQL: Tutorial" o "IBM Informix ESQL/C Programmer's Manual" o Various technical papers on the IBM Informix website (http://www.ibm.com/informix/) and the IBM Informix DeveloperWorks site (under http://www.ibm.com/developerworks/db2/zones/informix). These release notes are written for the following audience: o System administrators who install Informix database servers o Database administrators who control access to Informix databases o Developers who write DataBlade modules that support the R-Tree secondary access method or depend on the R-Tree DataBlade module II. IBM INFORMIX DATABASE SERVER COMPATIBILITY =============================================== Version 2.0 of the IBM Informix R-Tree DataBlade module is included with IBM Informix Dynamic Server, Version 9.20 and higher. III. PRODUCT DESCRIPTION ========================== The IBM Informix R-Tree DataBlade module consists of: o a list of error messages used by the R-Tree access method. o a BladeSmith interface object used by DataBlade modules that depend on the IBM Informix R-Tree DataBlade module. The R-Tree access method is built into the IBM Informix Dynamic Server, but the error messages used by this access method are only available if this DataBlade module is registered. See Section IV below for more information. The R-Tree error messages contained in this DataBlade module have error codes of the form RTRnn, where: o RTR is the three-character prefix for all current IBM Informix R-Tree DataBlade module error codes. o nn is a two-character identifier that uniquely identifies each error code. Some of the messages are not true error messages, but are reporting strings used by rtree code invoked by the oncheck utility. NOTE: Error messages with the RLT prefix are not used in the IBM IDS 9.20 and above. IV. GENERAL INFORMATION ON REGISTRATION ======================================== The IBM Informix R-Tree DataBlade module must be registered in each database in which you plan to use it. This registration normally occurs when you register a dependent DataBlade module, that is, one that can only be registered if the IBM Informix R-Tree DataBlade module has been previously registered. The dependent DataBlade module first signals to BladeManager that it depends on the IBM Informix R-Tree DataBlade module. BladeManager then registers the IBM Informix R-Tree DataBlade module before it registers the dependent DataBlade module. The dependent DataBlade module usually contains the definition of the user- defined data type that can be indexed by the R-Tree access method. The procedure for setting up this dependency is described in Section VI of these notes. V. REGISTERING IBM INFORMIX R-TREE DATABLADE ============================================ For IBM Informix Dynamic Server Version 9.30 and onward, the IBM Informix R-Tree DataBlade module Version 2.0 is automatically installed with the database server. You register the DataBlade module in new databases as needed. For database servers that are upgrading from IBM Informix Dynamic Server Version 9.1 to Version 9.30 and above VERSION 2.0 of the R-Tree DataBlade module is automatically installed as part of the standard upgrade procedure. The standard upgrade procedure also includes the conversion of the databases in the database server. When the upgrade process converts databases in which the R-Tree DataBlade module is registered, the conversion automatically upgrades the R-Tree DataBlade module from Version 1.0 to Version 2.0. If you subsequently revert the database back to the old database server version, you do not need to downgrade the R-Tree DataBlade module, since Version 2.0 of the R-Tree DataBlade module is compatible with Version 9.1 of IBM Informix Dynamic Server The following table summarizes which versions of the R-Tree DataBlade module are compatible with each relevant version of IBM Informix Dynamic Server: IBM IDS Version Compatible R-Tree Version ~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~ 9.1x 1.0, 2.0 9.20 GA 2.0 9.30 2.0 9.40 and above 2.0 VI. DEPENDENT DATABLADE MODULES ================================ Dependent DataBlade modules are those whose functionality depends on the functionality of the IBM Informix R-Tree DataBlade module. Dependent DataBlade modules signal their dependency to BladeManager by including a reference to the interface object ifxrltree1, provided by the IBM Informix R-Tree DataBlade module. NOTE: Both Versions 1.0 and 2.0 of the R-Tree DataBlade module name the interface object "ifxrltree1." A. REGISTERING DEPENDENT DATABLADE MODULES -------------------------------------------- When you register a DataBlade module that contains an imported reference to the ifxrltree1 interface, BladeManager searches for a DataBlade module that provides this interface and finds the IBM Informix R-Tree DataBlade Module, ifxrltree.2.00. If this module is already registered, for example through the prior registration of another dependent DataBlade module, the registration of the requested module proceeds without further interaction. If the R-Tree DataBlade module is not registered, BladeManager warns you of the dependency and gives you the option to register the R-Tree DataBlade module before proceeding with the registration of the dependent DataBlade module. If you decline, neither the dependent DataBlade module nor the IBM Informix R-Tree DataBlade module is registered. B. CREATING REGISTRATION SCRIPTS FOR DEPENDENT DATABLADE MODULES ------------------------------------------------------------------ Developers of dependent DataBlade modules can use the DataBlade Developer's Kit to create a registration script that signals to BladeManager a dependency on the IBM Informix R-Tree DataBlade module. Dependent DataBlade modules signal this dependency by importing an interface object provided by the IBM Informix R-Tree DataBlade module. During registration of the dependent DataBlade module, BladeManager checks interface dependencies and warns the customer if the IBM Informix R-Tree DataBlade module is not already registered in the database. In the BladeSmith tool, part of the DataBlade Developer's Kit, an interface object represents, by name, a set of functionality provided by the DataBlade module that defines the interface. The interface is named ifxrltree1. The functionality that it represents is the set of error objects defined in this module. To complete the BladeSmith project for a DataBlade module dependent on the R-Tree access method, you must import the interface object ifxrltree1 into your DataBlade module's project file. The ifxrltree1 interface object is located in the R-Tree DataBlade project file, ifxrltree.ibs, in the same directory as these release notes. The steps for importing the interface are: 1. If necessary, copy ifxrltree.ibs from its location under $INFORMIXDIR to a directory accessible from the Windows operating environment in which you run BladeSmith. 2. In BladeSmith, open ifxrltree.ibs in addition to your own project. 3. In the ifxrltree project, select the ifxrltree1 interface object and copy it to the clipboard. 4. In your own project, import the interface using the menu item Edit->Import->From Clipboard. See the "DataBlade Developer's Kit User's Guide" for details on the use of BladeSmith, and the R-Tree reference listing in "Overview of Release Notes" for sources of information about developing dependent DataBlade modules. VII. KNOWN PROBLEMS ==================== This section describes the known problems with this release of the IBM Informix R-Tree DataBlade module and shows, where possible, how to work around these problems. o R-Tree error messages are not mentioned in documentation chapters such as "Programming for a Multiuser Environment" in the "IBM Informix Guide to SQL: Tutorial." For example, when a query encounters a locked row in the presence of an R-Tree index, the system reports an error different from the one mentioned in that text. In other words, a client program should not limit its handling of locking errors to those suggested in the guides; in many cases, an R-Tree error message reporting failure merely represents a lock condition, which could be handled by retrying. Contact support: http://www.ibm.com/software/data/informix/ids/support/ (C) Copyright IBM Corp. 1996, 2012