========================================= RELEASE NOTES INFORMIX JDBC DRIVER, VERSION 1.22.JC1 DATE: August 31, 1998 ========================================= TABLE OF CONTENTS I. OVERVIEW OF RELEASE NOTES II. PLATFORM INDEPENDENCE III. DATABASE SERVER AND PLATFORM COMPATIBILITY IV. COMPILER COMPATIBILITY V. JAVA VIRTUAL MACHINE COMPATIBILITY VI. SUPPORT POLICIES VII. USING INFORMIX-SE VERSION 5.x DATABASE SERVERS VIII. USING INFORMIX-SE VERSION 7.2x DATABASE SERVERS IX. USING INFORMIX-OnLine VERSION 5.x DATABASE SERVERS X. getCatalogs() AND getDbname() METHODS XI. FEATURES NOT SUPPORTED IN THIS RELEASE OF INFORMIX JDBC DRIVER XII. THIRD-PARTY PRODUCT INFORMATION XIII. CONCURRENT USE OF STATEMENT AND RESULTSET OBJECTS ACROSS THREADS XIV. FLOAT AND DOUBLE PRECISION DATA TYPES XV. INFORMIX DATETIME DATA TYPE XVI. USING INFORMIX INTERVAL DATA TYPES XVII. AUTOCOMMIT AND LOGGING XVIII. ON-LINE PROGRAMMER'S GUIDE XIX. INFORMATION FOR INFORMIX-OBJECT INTERFACE FOR JAVA CUSTOMERS XX. KNOWN PROBLEMS XXI. FIXED 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 Informix JDBC Driver on your computer. This file also contains information 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 "Informix JDBC Driver Programmer's Guide," which provides thorough information about product features and behavior. These release notes are written for the following audience: o System administrators who install Informix JDBC Driver o Database administrators who control access to Informix Dynamic Server databases o Developers who write applications using Informix JDBC Driver II. PLATFORM INDEPENDENCE ========================= The Informix JDBC Driver is a type 4 implementation of the standard Java database connectivity API, as defined by Sun Microsystems. Informix is a strong supporter of Java standards, and all the benefits that platform neutrality bring to application development and deployment. Therefore, Informix has developed one version of the JDBC Driver to be a platform independent product that will run on any standard Java platform. Version 1.22.JC1 of Informix JDBC Driver was compiled with Version 1.1.6 of the JavaSoft Java Development Kit (JDK) on Solaris 2.5.1. The optimized version of the driver was compiled with the -O option and the debug version was compiled with the -g option. Informix has tested and certified the driver with multiple Informix database servers, outlined in the next section. Although the driver has not been tested on every Informix server version, there are no known restrictions, other than described in this document, when using the JDBC driver with currently shipping server products. Informix has also tested and certified the JDBC driver across multiple platforms. While this does not guarantee complete portability on every Java platform due to slight variations in vendor's Java implementations, there are no known restrictions and the driver should work in any standard Java environment. III.DATABASE SERVER AND PLATFORM COMPATIBILITY =============================================== The Informix database server and platform combinations listed below have been tested and certified with the Informix JDBC Driver v.1.22.JC1. Server/platform combinations not listed below have not been tested and certified, and the driver may or may not work correctly. These tests have been completed using the latest available level of the JDK, either 1.1.5 or 1.1.6 in all cases except AIX 4.2.1, which uses JDK 1.1.4. The following servers have been tested and certified on Solaris 2.5.1, NT 4.0, HP-UX 10.20 & 11.0, AIX 4.2.1 & 4.3, SGI 6.2, and DEC 4.0: Informix Dynamic Server, Version 7.x Informix Dynamic Server, Workgroup and Developer Editions, Version 7.x Informix Dynamic Server with Universal Data Option, Version 9.x The following servers have been tested and certified on Solaris 2.5.1 only: Informix Dynamic Server with Advanced Decision Support and Extended Parallel Options, Version 8.x INFORMIX-OnLine, Version 5.08 INFORMIX-SE, Version 5.08 INFORMIX-SE, Version 7.23 IV.COMPILER COMPATIBILITY ========================== While Informix tested and certified the JDBC 1.22 driver with the following compilers, there are no known restrictions in the use of other Java compilers used to create an application or applet: JavaSoft's JDK 1.1.6 Java compiler Microsoft's visual J++ Java compiler Symantec's Cafe Java compiler V.JAVA VIRTUAL MACHINE COMPATIBILITY ===================================== Java Virtual Machine (JVM) to deploy application: While Informix has tested and certified the JDBC 1.22 driver with the following JVMs, there are no known restrictions on the use of other JVMs used to deploy an application: JavaSoft's JDK 1.1.6 JVM Microsoft's Visual J++ JVM Symantec's Cafe JVM Java Virtual Machine (JVM) to deploy applet: Informix has tested and certified the JDBC 1.22 driver with the following browser JVMs to deploy applets: Default JVM that is in Netscape Navigator 4.05 Default JVM that is in Microsoft Internet Explorer 4.72 Informix recommends you use one of these browsers (or later versions) to view applets that use Informix JDBC Driver. **Some older versions of these browsers might not automatically support the JDBC API. Refer to your browser documentation for more information on JDBC support. VI.SUPPORT POLICIES ==================== Technical Support through Informix is available for Informix JDBC Driver on all platforms for customers who purchase support contracts. Informix recognizes that the cross-platform nature of the JDBC driver will create situations where Informix has not tested and certified the platform configuration deployed by the customer. In this case, Informix will make every effort for customers purchasing maintenance to reproduce, isolate and resolve all reported issues within the standard JDBC specification and Informix's JDBC implementation. Given the open nature of this product, Informix may from time to time request access to the customer's environment to fully isolate and resolve an issue when the customer's exact platform configuration is not available in our labs. Issues found to be due to non-standard Java implementations will need to be handled by the associated vendor VII. USING INFORMIX-SE VERSION 5.x DATABASE SERVERS =================================================== This section describes how to use Informix JDBC Driver with INFORMIX-SE, Version 5.x. A. NETWORK INFORMATION ---------------------- Refer to the "INFORMIX-NET and INFORMIX-STAR Installation and Configuration Guide" for instructions on how to install INFORMIX-SE Version 5.x and start an SE daemon using the "tcp" protocol. Note that Version 5.x of INFORMIX-NET and INFORMIX-STAR have a different command line syntax for starting the daemons than that of INFORMIX-SE Version 7.x. For Version 5.x, you must specify a service name, not a database server name, when you start the daemon. For example, the following command starts a Version 5.x daemon: $INFORMIXDIR/lib/sqlexecd sqlexec -l /tmp/selog In the example, "sqlexec" is a service name, not a database server name. You must specify the "USERV5SERVER=1" environment variable in the database URL or property list when connecting to INFORMIX-SE Version 5.x. B. DATABASE DIRECTORIES ----------------------- INFORMIX-SE database servers can only read from or write to the local directories on the computer where the SE daemon was started. This means, for example, that you cannot create a database on an NFS-mounted directory on the computer where the SE daemon was started. By default, when you create a database through Informix JDBC Driver, the driver asks the SE database server to create the database in your home directory. This means that your home directory cannot be an NFS- mounted directory. If you do not want the database to be created in your home directory, you can specify another directory by using the following syntax after connecting to the SE database server: CREATE DATABASE '//server-name/path/database_name'; For example, the following statement creates the database called MYDB in the directory "/tmp/mydb.dbs" using the SE database server "myserver_tli": CREATE DATABASE '//myhost/tmp/mydb'; You can specify this database in a database URL, as shown in the following example: url = "jdbc:informix-sqli://myhost:1525//tmp/mydb:informixserver=myhost;user=rdtest;password=test"; VIII.USING INFORMIX-SE VERSION 7.2x DATABASE SERVERS ===================================================== This section describes how to use Informix JDBC Driver with INFORMIX-SE, Version 7.2x. A. NETWORK INFORMATION ---------------------- Informix JDBC Driver supports only the TCP/IP protocol, which means you can connect to SE database servers only through the "setlitcp" or "sesoctcp" network protocols. Some platforms, such as Solaris, only support "setlitcp"; other platforms only support "sesoctcp." Check your SE database server machine notes to verify the network protocol supported by your platform. To use the TCP/IP protocol, you must bring up an SE daemon. First define an SE database server name in the SQLHOSTS file, specifying either "setlitcp" or "sesoctcp," as shown in the following example: myserver_tli setlitcp myhost sqlexec Assume that in the example, "sqlexec" has a port number of 1525. This information will be used in a later example. To bring up the SE tlitcp daemon, execute the following command as the "root" user: $INFORMIXDIR/lib/sqlexecd myserver_tli -l /tmp/selog_tli Use the UNIX "ps" command to check whether the SE daemon has been successfully started. B. DATABASE DIRECTORIES ----------------------- INFORMIX-SE database servers can only read from or write to the local directories on the computer where the SE daemon was started. This means, for example, that you cannot create a database on an NFS-mounted directory on the computer where the SE daemon was started. By default, when you create a database through Informix JDBC Driver, the driver asks the SE database server to create the database in your home directory. This means that your home directory cannot be an NFS- mounted directory. If you do not want the database to be created in your home directory, you can specify another directory by using the following syntax after connecting to the SE database server: CREATE DATABASE '//server-name/path/database_name'; For example, the following statement creates the database called MYDB in the directory "/tmp/mydb.dbs" using the SE database server "myserver_tli": CREATE DATABASE '//myserver_tli/tmp/mydb'; You can specify this database in a database URL in your Java program, as shown in the following example: url = "jdbc:informix-sqli://myhost:1525//tmp/mydb:informixserver=myserver_tli;user=rdtest;password=test"; IX.USING INFORMIX-OnLine VERSION 5.x DATABASE SERVERS ====================================================== This section describes how to use Informix JDBC Driver with INFORMIX-OnLine, Version 5.x. Refer to the "INFORMIX-NET and INFORMIX-STAR Installation and Configuration Guide" for instructions on how to install INFORMIX-OnLine Version 5.x and start an INFORMIX-STAR daemon using the "tcp" protocol. Note that Version 5.x of INFORMIX-NET and INFORMIX-STAR have a different command line syntax for starting the daemons than that of INFORMIX-SE Version 7.x. For Version 5.x, you must specify a service name, not a database server name, when you start the daemon. For example, the following command starts a Version 5.x daemon: $INFORMIXDIR/lib/sqlexecd sqlexec -l /tmp/selog In the example, "sqlexec" is a service name, not a database server name. Finally, you must specify the "USERV5SERVER=1" environment variable in the database URL or property list when connecting to INFORMIX-OnLine Version 5.x. X. getCatalogs() AND getDbname() METHODS ======================================== The "getCatalogs()" method of the DatabaseMetaData interface and the "getDbname()" method of the Connection interface return a "Method not supported" SQLException when executed against any of the following database servers: INFORMIX-OnLine, Version 5.x INFORMIX-SE, Versions 5.x and 7.x This is because none of these database servers have a "sysmaster" database. XI.FEATURES NOT SUPPORTED IN THIS RELEASE OF INFORMIX JDBC DRIVER ================================================================== This section describes the features not supported in the 1.22.JC1 release of Informix JDBC Driver. A. GLS ------ The current version of the driver does not support the Global Language Support (GLS) feature. This means the driver cannot handle languages, cultural conventions, and code sets other than standard English. B. DATA TYPES ------------- The current version of the driver does not support the following Informix data types: * LVARCHAR * BOOLEAN * BLOB * CLOB * Opaque Data Types * Complex Data Types Future versions of Informix JDBC Driver will support these data types. XII.THIRD-PARTY PRODUCT INFORMATION ==================================== This section contains information about using Informix JDBC Driver with Java WorkShop and the HP port of the Java Development Kit (JDK), Version 1.1.3. A. JAVA WORKSHOP ---------------- The Java WorkShop debugger does not work with Informix JDBC Driver because the debugger cannot work with any product that has not been compiled by Java WorkShop. For more information about Java WorkShop, refer to the following Sun Web site: http://www.sun.com/workshop.workshopFAQ.html B. JDK 1.1.3 ON HP ------------------ Because of bugs in the JDK, Version 1.1.3, on the HP platform, you may get a Java Virtual Machine core dump when you run your applications with Informix JDBC Driver on this platform. XIII.CONCURRENT USE OF STATEMENT AND RESULTSET OBJECTS ACROSS THREADS ====================================================================== Version 1.22 of Informix JDBC Driver does not support concurrent use of Statement and ResultSet objects across threads. For example, suppose one thread executes the "Statement.executeQuery()" method on a Statement object, and another thread executes the method "Statement.executeUpdate()" on the same Statement object. The result of both methods is unexpected and depends on which method was executed last. Similarly, if one thread executes the method ResultSet.next() and another thread executes the same method on the same ResultSet object, the result of both methods is unexpected and depends on which method was executed last. You can share a Connection object between multiple threads. However, its DatabaseMetaData object, created with the Connection.getMetaData() method, cannot be accessed simultaneously between multiple threads. XIV.FLOAT AND DOUBLE PRECISION DATA TYPES ========================================== All FLOAT and DOUBLE PRECISION data types are transported in their native format when used in Java programs that run against Informix database servers on Motorola-based platforms, such as Solaris. If the data types are used in Java programs that run against Informix database servers on Intel-based platforms, such as Windows NT, the data types are transported as decimals. XV.INFORMIX DATETIME DATA TYPE =============================== The current version of Informix JDBC Driver maps the JDBC API data type java.sql.Timestamp to Informix DATETIME columns with "year to fraction(5)" qualifiers, the ANSI standard. If the DATETIME column in your table is defined with qualifiers that do not match year/month/day, such as "hours to seconds," then you must explicitly use the JDBC API data type java.sql.Time instead. If your Informix DATETIME columns are neither "year to fraction(5)" nor "hour to fraction(5)," and you are sending the data to the database server, you must call the database server's "extend()" function to convert the JDBC range to your Informix DATETIME range. For example, assume your Informix DATETIME column is defined as: datetime (minute to second) When you use the setTime() method to insert your JDBC data into the table column, you will need to modify the WHERE clause of your INSERT or UPDATE statement as follows: INSERT INTO tab VALUES (extend(?, minute to second)); The "extend()" function tells the database server to convert the time or timestamp range to the range that matches your Informix DATETIME column. If you do not use the "extend()" function in this way, you will receive a conversion error. If your DATETIME column matches the ANSI definition of time, the setTime() method will work correctly without modifying your SQL statement. The same is true if your Informix DATETIME column matches the timestamp range and if you are using the setTimestamp() method. XVI.USING INFORMIX INTERVAL DATA TYPES ======================================= You must use the "getString()" and "setString()" methods to fetch and bind columns of the Informix INTERVAL data type. When you use the "setString()" method, the Informix database server expects the format of the interval value to conform to the "Numeric Date" format described in the section "Literal INTERVAL" of the "Informix Guide to SQL: Syntax." For example, "9-12" is a valid year-month interval, and "5 10:30:20.12345" is a valid day-time interval. An example of using the Informix INTERVAL data type is provided in Chapter 2 of the "Informix JDBC Driver Programmer's Guide." XVII.AUTOCOMMIT AND LOGGING ============================ This information supplements the section "Handling Transactions" in Chapter 2 of the "Informix JDBC Driver Programmer's Guide." Each time autocommit mode is set to false, a user transaction is implicitly started, which requires that the database had been created with logging enabled. Therefore, if the database has not been created with logging enabled, the method "setAutoCommit()" returns an SQLException when set to false. XVIII.ON-LINE PROGRAMMER'S GUIDE ================================= PDF and HTML versions of the "Informix JDBC Driver Programmer's Guide" are included in the product distribution. The following two sections describe the location of the on-line files on UNIX and Windows NT. A. UNIX ------- The following file contains the PDF version of the programmer's guide: $JDBCLOCATION/doc/release/jdbc4pg.pdf To view the HTML version of the programmer's guide, point your browser to the following file: $JDBCLOCATION/doc/release/HTML_Guide/index.html $JDBCLOCATION refers to the directory where you installed Informix JDBC Driver. B. WINDOWS NT ------------- The following file contains the PDF version of the programmer's guide: %JDBCLOCATION%\doc\release\jdbc4pg.pdf To view the HTML version of the programmer's guide, point your browser to the following file: %JDBCLOCATION%\doc\release\HTML_Guide\index.html %JDBCLOCATION% refers to the directory where you installed Informix JDBC Driver. XIX.INFORMATION FOR INFORMIX-OBJECT INTERFACE FOR JAVA CUSTOMERS ================================================================= If you are an INFORMIX-Object Interface for Java (OIJ) customer and want to migrate your Java program that uses OIJ to one that uses Informix JDBC Driver, read the HTML file "oij_jdbc_migration.html," located in the same directory as these release notes. The file contains information and examples about migrating from OIJ to JDBC. XX.KNOWN PROBLEMS =================== This section describes the known problems with this release of Informix JDBC Driver. Bug 99333 The method DatabaseMetaData.getDatabaseProductVersion() returns an error instead of the product version. Bug 99323 If all the columns of a table have a particular table-level privilege, such as UPDATE, the DatabaseMetaData.getColumnPrivileges() method returns no rows when executed on the table. If, however, only some of the columns have a particular privilege, then those columns are returned by the method. This is true for all table-level privileges. Bug 99321 The method DatabaseMetaData.getTableTypes() does not return SYNONYM as a table type when the method is executed against Informix Dynamic Server with Universal Data Option 9.x. The method works correctly when executed against the other Informix database server options. Bug 99306 The ResultSet.close() method does not clean up and free all resources correctly. For example, after executing the method, it is still possible to access the result of the previously read row. Bug 99180 When an SQLException is thrown after a database access error, the SQLException object contains the error message and error code, but not the ISAM code. Bug 99110 Using a ResultSet object while the query is in progress, or executing a query on a Statement object while the Statement is already executing another query, produces an uncaught ArrayIndexOutOfBoundException exception. The same exception might also occur if you share ResultSet or Statement objects across threads. This is a limitation of Informix JDBC Driver, and is described in detail in Section X of these release notes. Bug 98905 The following Informix JDBC Driver error messages do not contain the name of the method that caused the error: -79700 Method not supported -79729 Method can not take argument -79750 Method only for queries Bug 95601 If an error occurs when you try to connect to an Informix database, Informix JDBC Driver does not substitue the "%s" variable in the returned error message with the database server name. For example, the following error message might be returned if a Java program failed to connect to an Informix database; the message contains the variable "%s" instead of the database server name: java.sql.SQLException: Attempt to connect to database server (%s) failed. Bug 93984 The Informix implementation of the JDBC API method ResultSetMetaData.getColumnTypeName() returns a Decimal value, instead of a String value, when it is executed on a column of data type SMALLFLOAT or FLOAT. This bug only occurs when the Informix database server is running on an Intel-based platform, such as Windows NT. Bug 93977 The Informix SQL data types FLOAT and SMALLFLOAT are incorrectly mapped to the Java BigDecimal data type instead of the Java Float data type. For example, if you use the method ResultSet.getObject() to return the value in a column of data type FLOAT or SMALLFLOAT, the returned object is of Java data type BigDecimal instead of Float. This bug only occurs when the Informix database server is running on an Intel-based platform, such as Windows NT. Bug 93763 Informix JDBC Driver maps the JDBC API data type LONGVARCHAR only to the Informix data type TEXT. According to the JDBC API specification, LONGVARCHAR can support many more data conversions. In particular, the driver does not currently support using the following methods to convert LONGVARCHAR to other Informix data types: getByte() getShort() getInt() getLong() getFloat() getDouble() getBigDecimal() getBoolean() getDate() getTime() getTimestamp() getObject() The driver incorrectly supports the following two methods for LONGVARCHAR conversion: getBytes() getBinaryStream() XXI.FIXED PROBLEMS ==================== This section describes the problems fixed since the 1.22.JC1B2 version of the product. Bug 97975 An internal error is no longer returned by Informix JDBC Driver when selecting a value of "00:00" from a column defined as an INTERVAL data type. Bug 97745 The following methods of the DatabaseMetaData interface no longer return the error "-254 : Cursor Not Open" when run against an Informix database created in ANSI mode: getTables() getColumns() getColumnPrivileges() getTablePrivileges() getBestRowIdentifier() getPrimaryKeys() getImportedKeys() getExportedKeys() getCrossReference() getIndexInfo()