analytics/informix/extend/ifxrltree.2.00/RLTREL.TXT

			  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