I. Overview of Release Notes

II. New Features

A. XML Support

B. Enhancements to the Java Runtime

C. C. Informix Object Translator Tutorial

III. Server Compatibility and System Requirements

A. Requirements for All Environments

B. Requirements for the Microsoft Visual Basic Development Environment

C. Requirements for the Visual Cafe Development Environment

D. Requirements for any Java Development Environment

IV. Limitations

A. Global Language Support (GLS)

B. XML Mapping Limitations

V. Known Problems

VI. Fixed Problems

VII. Acknowledgments

The purpose of these release notes is to make you aware of any special actions required to configure and use Informix Object Translator, Version 1.10, on your client computer. This file also contains information about product features not yet included in the product documentation, and about known bugs and their workarounds.

This release notes document is not intended to be all-inclusive; it should be used as an addendum to the Installation Notes for Informix Object Translator and the online help provided with Object Translator. These documents provide thorough information about system requirements, installation procedures, product features and concepts, and product usage.

These release notes are written for the following audience:

• System administrators who install Informix database servers and client products
• Developers who write applications using Object Translator

This section describes the XML support and Java support features that have been added to Informix Object Translator since the 1.0 and 1.10 Beta Refresh versions of the product. It also describes the tutorial that is now available for Object Translator.

For the Informix Object Translator, Version 1.10 release, XML functionality was added to the Java version of the product. This functionality allows you to map XML document elements and attributes to the map-object attributes of your Object Translator project, including multilevel XML elements to map-object attributes that are embedded or collection objects. The following additions were made to Object Translator to support this new functionality:

• Two pages were added to the Object Translator console:
• XML Document page. This page was added to the Document pane (formerly the Schema Viewer pane), and it allows you to display and view any well-formed XML document in a tree-like structure. You select XML elements from this page and map them to the attributes of the map object displayed in the Object Viewer pane.
• XML Links page. This page was added to the Workspace pane (formerly the Project Viewer pane), and it allows you to view the links you have created between one or more XML documents and the map objects of this Object Translator project.
• Two wizards were added to the Object Translator console:
• DTD-to-XML wizard. This wizard generates an XML document from a DTD file.
• HTML-to-XML wizard. This wizard converts an HTML document to a well-formed XML document.

The XML documents created by these wizards are displayed in the XML Document page of the Document page, allowing you to map them to the map objects of your Object Translator project.

• The following changes were made to the Code Generator:
• A servlet class that allows you to access the new XML functionality is generated.
• An HTML file to access the servlet over an HTTP connection is generated.
• A .settings file is generated.

The Object Translator-generated code and the Object Translator Java runtime use a text file, called ObjectName.settings, to dynamically load map-object information at runtime. For Object Translator, Version 1.10, the ObjectName.settings file contains the name and location of the XML document mapped to the map object named ObjectName. (A .settings file is not generated for an embedded object.) For information on how to change the information in this file, see How to Use the Informix Object Translator Java Runtime.

• A sample makefile is generated; for more information, see Generation of a Sample Makefile later in this document.

• Two methods have been added to the generated Java data object class:
• String getXML ( ). The getXML method allows you to retrieve the XML document populated with the data from the database as a Java string variable.
• boolean setXML (String XMLString). The setXML method allows you to pass an XML document to the Informix Object Translator-generated Java object.

Version 1.10 of Informix Object Translator includes the following enhancements to the Java runtime:

• Java Global Language Support (GLS)
• Enhanced exception handling
• Generation of a sample makefile
• JNDI support and connection pooling
• In addition to JDK 1.2.x, Object Translator supports 1.1.7 (or higher) as an interim solution to customers who do not yet have access to JDK 1.2.x

These features are described in more detail in the following sections.

Version 1.10 of the Object Translator Java runtime is certified for operation in internationalized (I18N) environments. This section describes the approach followed by Informix to provide this support. For an example of using the Java GLS support, see How to Use the Informix Object Translator Java Runtime.

Informix does not provide a Java GLS library; thus, Object Translator uses the standard Java I18N APIs, such as the ResourceBundle and the Locale classes in the java.util and java.text packages.

The Object Translator Java runtime does not have a GUI component and deals only with database data types. Thus, the I18N package handles only Messages, Dates/Times, and Numbers.

• Messages. Object Translator stores its exception and logging messages in the PropertyResourceBundle (a subclass of the JDK ResourceBundle). Other message data that is stored to and from a database is not formatted by the Object Translator Java runtime; thus, that data is not stored in a bundle.

The default U.S. English bundle is named Messages.properties and is included in the Java runtime package (ormapper.jar). German and English versions of the bundle are also included in the package.

• Dates/Times and Numbers. Date, time, and number data that is stored to and from a database is not formatted by the Object Translator Java Runtime. By default, these data types are mapped to the closest Java wrapper classes; for example, BIGINT is mapped to Long and DATETIME is mapped to Timestamp. You must manipulate this data in your native data types and display the data appropriately for your application. For data types in the Java String class, the conversions of strings to local settings should be handled by the database server and the JDBC driver.

Object Translator supports Informix GLS variables indirectly through Informix JDBC Driver. For example, CLIENT_LOCALE and DB_LOCALE can be set in the connection URL or in JDBC connection properties. These settings affect the data and messages returned from the database server and the JDBC driver. However, the language of messages originating from Object Translator is determined by the Locale property of the OConnection class, which is set with the setLocale method. (For an example of how to use setLocale, see How to Use the Informix Object Translator Java Runtime.)

Informix GLS environment variables such as DBCENTURY, DBDATE, and GL_DATE affect the format of date and time data types. This format conversion is handled by the database server and the JDBC driver.

This section describes the changes to the Object Translator Java runtime to provide enhanced exception handling. For examples showing how to use the enhanced exception handling, see the Installation Notes for Informix Object Translator.

Version 1.0 of the Object Translator Java runtime provided a DatabaseException class to encapsulate all error conditions, including those returned from JDBC drivers. While this made it easy to catch all error conditions, it was hard to determine the exact causes of errors when several different error conditions could arise from a single method.

The Object Translator 1.10 Java runtime contains a new exception classes in the com.informix.ormapper package. They are in a hierarchy under the existing DatabaseException class:

• ChangeDetectedException. An optimistic concurrent change has been detected.
• NoDriverException. No suitable driver can be loaded for the URL.
• NoConnectionException. No connection has been established.
• NoResultSetException. No result set or the result set is empty.
• NoStatementException. No statement has been created.

For a list of some of the situations in which these exceptions will be raised, as well as some examples of testing for the exceptions, see the Installation Notes for Informix Object Translator.

In addition, exception chaining (also known as nesting exceptions) has been implemented in all exceptions to allow you to trace the error stack back to the JDBC and JDK code.

Because the new exception classes inherit directly from DatabaseException, you can continue to check error conditions by catching just DatabaseException. In other words, you do not need to rewrite your client code.

To take advantage of the new exception classes, however, you must modify your code to check for those exceptions and you must use the Code Generator component to regenerate your Object Translator project.

In addition, a small change has been made in the behavior of the Java runtime package since Version 1.0. In Version 1.0, when an object was restored and an empty result set was returned, no exceptions were raised. Now the NoResultSetException exception is raised.

Many of the exceptions raised from the Java runtime package methods are the SQLException exceptions originally raised by JDBC drivers. Thus, if you called printStackTrace in Version 1.0, you could trace the error only from your code to the Object Translator runtime package, not to the JDBC or JDK code.

In Object Translator, Version 1.10, all new exception classes implement exception chaining. This means that if you call printStackTrace, the Object Translator Java runtime stack trace is printed, followed by the stack trace of the original exception.

The Code Generator component of the Object Translator GUI now generates a sample makefile, project_name.mak, for Java projects. This file compiles the Object Translator-generated classes, and then packages these classes with the .settings file and XML document if appropriate (see the XML Support section earlier in this document) into a jar file with the name project_name.jar.

You can build this file on a UNIX computer using the following command:

make -f <project_name>.mak

You can also build this file on a Windows NT computer if it has either Microsoft Visual Studio or the MKS toolkit installed on it. For the MKS toolkit, the command is the same as it is for UNIX. For Visual Studio, the command is as follows:

nmake -f <project_name>.mak

The generated makefile is a sample only. Depending on the platforms on which you are deploying the applications you create with Object Translator, you may need to create your own makefile.

Java Naming and Directory Interface (JNDI) support, part of the Java Enterprise API set, is a standard extension to the Java platform. It provides Java applications with a unified interface to multiple naming and directory services in the enterprise by abstracting the database-specific connectivity information. As a result, connecting and accessing an enterprise data source becomes generic.

Connection pooling is a method for conserving scarce database resources by managing a pool of connections among concurrently active clients.

JNDI support and connection pooling are provided by your JDBC driver, your application server, or both via the DataSource object. For information on JNDI support and connection pooling, refer to the documentation for your JDBC driver and application servers. For examples of how to make use of these features in your Object Translator project, see How to Use the Informix Object Translator Java Runtime.

In addition to JDK 1.2.x, Informix Object Translator supports JDK 1.1.7 (or higher) as an interim solution to customers who do not yet have access to JDK 1.2.x.

To use Object Translator with JDK 1.1.7, you must use Informix JDBC Driver, Version 1.5.x, and ormapper_jdk11.jar instead of ormapper.jar.

The Informix Object Translator Tutorial demonstrates how to use Object Translator to connect a Web site to a relational database management system. The tutorial currently contains these lessons:

• Setting Up for the Tutorial
• Lesson 1: Building a Simple Servlet

You can access the tutorial from the Windows Start menu. Click the Start button, and then choose Programs->Informix Object Translator 1.10->Object Translator Tutorial.

When more lessons are developed, a new version of the tutorial will be placed on the Object Translator Web site, which is available at the following URL:

http://www.informix.com/idn-secure/webtools/ot

This section lists the software and hardware you need to use Informix Object Translator in any development environment and the software you need for the three development environments supported by Version 1.10: Microsoft Visual Basic, Visual Cafe, and any Java development environment.

To use Informix Object Translator, one of the following database servers must be installed on your server computer:

• Informix Dynamic Server 2000, Version 9.2x
• Informix Internet Foundation 2000, Version 9.2x
• Informix Dynamic Server, Version 7.x
• Cloudscape Data Manager, Version 3.0.1 or higher

Your client computer requires the following hardware and software:

• A hard drive with at least 12 MB of available storage space, in addition to whatever is required by your development environment
• Microsoft Windows NT 4.0, with Service Pack 4 or higher, or Microsoft Windows 95, 98, or 2000
• Microsoft Internet Explorer, Version 4.72 or higher (no other Web browser fulfills this requirement)
• Informix Object Translator, Version 1.10

Version 1.10 was tested on these deployment environments, including environments on client computers: Java-supported platforms, Solaris, Linux, and HP.

To use Informix Object Translator with the Microsoft Visual Basic development environment, your client computer requires the following software:

• Microsoft Visual Basic 6.0 (Professional Edition or Enterprise Edition) with Visual Studio Service Pack 3
• Informix Client Software Developer's Kit, Version 2.4 or higher
• At least one of the following drivers:
• Informix ODBC Driver, Version 3.30 or higher
  (included in the Typical install of the Informix Client SDK)
• Informix OLEDB Provider, Version 2.0
  (available by specifying the Custom install of the Informix Client SDK)

To use Informix Object Translator with the Visual Cafe development environment, your client computer requires the following software:

• Visual Cafe 3.0 (Database Edition, Professional Edition, or Enterprise Suite) or WebGain Visual Cafe 4 (Standard Edition, Expert Edition, or Enterprise Suite)
• Sun Java 2 Platform Standard Edition (JDK 1.2.x)
• Informix JDBC Driver, Version 2.1x or higher, or the CloudScape Data Manager, Version 3.0.1 or higher

To use Informix Object Translator with any Java development environment, your client computer requires the following software:

• Sun Java 2 Platform Standard Edition (JDK 1.2.x)
• Informix JDBC Driver, Version 2.1x or higher, or the CloudScape Data Manager, Version 3.0.1 or higher

This section describes the limitations of Informix Object Translator, Version 1.10.

Informix Object Translator, Version 1.10, for Visual Basic, does not support GLS. For information on the Java GLS support, see the Java Global Language Support (GLS) section earlier in this document.

This version of Informix Object Translator contains the following limitations to its XML mapping features:

• The generated setXml method does not work correctly if an Object Translator condition is set for the main object on which XML mapping is performed.
• Suppose that an XML document to be mapped to an Object Translator object has the following structure:

	<A>
		<A1/
		<A2/>
		<C>
			<C1/>
			<C2/>
		</C>
		<C>
			<C3/>
			<C4/>
		</C>
	</A>

The type of map-object attributes to which the first and second C elements are mapped determines whether the XML mappings will work or not:

First C element mapped to:	Second C element mapped to:	XML mapping works?
embedded object	collection object	Yes
collection object	embedded object	No
collection object	collection object	No

To ensure that the XML mappings will work, use the LinkIndex property. For the XML link that includes the first C element, keep the LinkIndex property at its default value of 0. For the XML link that includes the second C element, set the LinkIndex property to 1. For each additional XML link that includes a C element, increment the LinkIndex property.

You can also work around the problem by renaming the second C element (choosing any other name) in the XML file before completing the XML mapping.

For example, you could rename the second C element as follows:

	<A>
		<A1/
		<A2/>
		<C>
			<C1/>
			<C2/>
		</C>
		<SecondC>
			<C3/>
			<C4/>
		</SecondC>
	</A>

This section describes the known problems with Informix Object Translator, Version 1.10, and provides workarounds if they exist.

Bug 118103

The Visual Basic runtime component of Object Translator does not retrieve, insert, update, or delete BLOB data correctly when using the OLEDB driver.

Bug 119248

The Visual Basic runtime component of Object Translator does not insert or update DATE data correctly when using the OLEDB driver.

Bug 120443

The Visual Basic runtime component of Object Translator does not insert or update DATETIME data correctly when using the OLEDB driver.

Bug 120452

The Visual Basic runtime component of Object Translator does not retrieve, insert, or update INTERVAL data correctly when using the OLEDB driver.

Bug 127620

If you use the Model Viewer's Import Wizard and choose a JDBC database driver and then click Cancel, the next time you choose a JDBC driver, an error message is displayed. To work around this problem, exit from Object Translator and then re-launch it.

Bug 128828

If you create a map object with multiple levels of collection objects and want to map an XML document to that object, you must set the RestoreType property of each parent object in the collection to Deep.

Bug 131262

If you attempt to use the setXML method of the Java runtime component of Object Translator to update a child collection object in which the foreign key is also part of the child object's primary key and the structure of the XML document does not match the structure of the tables in the database, an error message appears saying data cannot be inserted due to a unique key constraint. The workaround is to re-structure the XML document mapped to the parent object so that the foreign key is explicitly repeated in the XML element corresponding to the child collection object. The following example illustrates this problem and its workaround.

Suppose you have an Order object with the following attributes:

Order_num
Details
Items (nested collection object)

Primary key: Order_num

And an Items object with these attributes:

Item_num
Order_num (foreign key)
Description

Primary key: Item_num + Order_num
Foreign key: Order_num

And you map the Order object to an XML document with the following structure:

<Order>
<order_num>12</order_num>
<details>Details of this order</details>
<Items>
	<item_num>32</item_num>
	<description>Nuts</description>
</Items>
<Items>
	<item_num>45</item_num>
	<description>Bolts</description>
</Items>
</Order>

You can use this XML document to update the Order object with the setXML method; however, If you use it to update the Items object, the update will fail. (Note that it would work if Order_num were not part of the Items object's primary key.)

As stated in the bug description, the workaround is to re-structure the XML document so that the foreign key is explicitly repeated in the Items element, as follows:

<Order>
<order_num>12</order_num>
<details>Details of this order</details>
<Items>
	<item_num>32</item_num>
	<order_num>12</order_num>
	<description>Nuts</description>
</Items>
<Items>
	<item_num>45</item_num>
	<order_num>12</order_num>
	<description>Bolts</description>
</Items>
</Order>

This section describes the problems fixed since Informix Object Translator, Version 1.0.

Bug 127538

If you were using Windows 98 and were using ODBC to import a data model (using Client SDK 2.40), you might have received an error message regarding CTL3D32.DLL. This no longer occurs.

Bug 128419

If you attempted to join tables in a map object but there was not a valid data path between the tables, you received multiple error messages (one for each column in the table you attempted to drag from the Schema Viewer pane to the Object Viewer pane). This no longer occurs.

Bug 128759

If a table in the database did not have a primary key and you did not assign one in the data model, you were allowed to map the table to a primary object even though the generated code was invalid. You are no longer allowed to do so.

Bug 128938

If you created a map object with no attributes and then set its Embedded property to True, and then you later added attributes to the object, the newly added fields did not inherit the properties of attributes in the embedded object. This no longer occurs.

This product includes software developed by the Apache Software Foundation (http://apache.org/) and the World Wide Web Consortium (http://www.w3.org/People/Raggett/tidy).

The Apache software includes xerces-c_1_1.dll and domutils.jar. The Apache copyright notice follows in its entirety.

The Apache Software License, Version 1.1

Copyright (c) 1999-2000 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistribution of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistribution in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. The names "Xerces" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.

5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED \Q\QAS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc., http://www.ibm.com. For more information on the Apache Software Foundation, please see <http://www.apache.org/>.