Informix JDBC Driverict.udlap.mx/.../docsAndothers/doc/release/jdbc4pg.pdf6 Informix JDBC Driver Programmer’s Guide Typographical Conventions Typographical Conventions This manual

Informix JDBC Driver

Programmer’s Guide

Version 1.22August 1998Part No. 000-5237

ii Informix JDBC Driver

Published by INFORMIX Press Informix Software, Inc.4100 Bohannon DriveMenlo Park, CA 94025-1032

Copyright 1981-1998 by Informix Software, Inc., or its subsidiaries, provided that portions may becopyrighted by third parties, as set forth in documentation. All rights reserved.

The following are trademarks of Informix Corporation or its affliates: INFORMIX, the Informix logo,Dynamic Scalable Architecture, Informix Dynamic Server, Universal Data Option, Extended ParallelOption, Advanced Decision Support Option, MetaCube™ ROLAP Option, Web Integration Option,Workgroup Edition, OnLine Dynamic Server, Illustra, DataBlade, Data Director, and New Era.

All other marks or symbols are registered trademarks or trademarks of their respective owners.

ACKNOWLEDGMENTS

Documentation Team: Juliet Shackell, Kimberly Bostrom, Daniel Howard, Bob Nowacki, Scott Stark, KarinMoore

Contributors: Yeh-Heng Sheng, Elham Chandler, Vivian Li, Mary Remillard, Ling-Gee Kwok, JorgeNoa, Charly Litzell

RESTRICTED RIGHTS/SPECIAL LICENSE RIGHTS

Software and documentation acquired with US Government funds are provided with rights as follows: (1) iffor civilian agency use, with Restricted Rights as defined in FAR 52.227-19; (2) if for Dept. of Defense use, withrights as restricted by vendor's standard license, unless superseded by negotiated vendor license as prescribedin DFAR 227.7202. Any whole or partial reproduction of software or documentation marked with this legendmust reproduce the legend.

Programmer’s Guide

Table of Contents

Table ofContents

IntroductionIn This Introduction . . . . . . . . . . . . . . . . . 3About This Manual . . . . . . . . . . . . . . . . . . 3

Organization of This Manual . . . . . . . . . . . . . 3Material Not Covered . . . . . . . . . . . . . . . 4Types of Users . . . . . . . . . . . . . . . . . . 4Software Dependencies . . . . . . . . . . . . . . . 4

Documentation Conventions . . . . . . . . . . . . . . 5Typographical Conventions . . . . . . . . . . . . . 6Icon Conventions . . . . . . . . . . . . . . . . . 6

Additional Documentation . . . . . . . . . . . . . . . 8Printed Documentation . . . . . . . . . . . . . . . 8On-Line Release Notes and Documentation Notes . . . . . 9Vendor-Specific Documentation . . . . . . . . . . . . 9

Compliance with Industry Standards . . . . . . . . . . . 10Informix Welcomes Your Comments . . . . . . . . . . . . 10

Chapter 1 Getting StartedIn This Chapter . . . . . . . . . . . . . . . . . . . 1-3What Is JDBC? . . . . . . . . . . . . . . . . . . . 1-3What Is a JDBC Driver? . . . . . . . . . . . . . . . . 1-5Overview of Informix JDBC Driver . . . . . . . . . . . . 1-6Installing the Driver . . . . . . . . . . . . . . . . . 1-7

Interactive Installation . . . . . . . . . . . . . . . 1-7Silent Installation . . . . . . . . . . . . . . . . . 1-9

Uninstalling the Driver . . . . . . . . . . . . . . . . 1-11Using the Driver in an Application . . . . . . . . . . . . 1-12Using the Driver in an Applet . . . . . . . . . . . . . . 1-13

iv Inform

Chapter 2 Programming with Informix JDBC DriverIn This Chapter . . . . . . . . . . . . . . . . . . . 2-3Establishing a Connection . . . . . . . . . . . . . . . 2-3

Loading Informix JDBC Driver . . . . . . . . . . . . 2-4Creating a Connection . . . . . . . . . . . . . . . 2-4

Accessing Database Metadata . . . . . . . . . . . . . . 2-13Querying the Database . . . . . . . . . . . . . . . . 2-14

Manipulating Informix BYTE and TEXT Data Types . . . . 2-14Manipulating Informix INTERVAL Data Types . . . . . . 2-19Informix-Specific Information About Querying a Database . . 2-20Example of Sending a Query to an Informix Database . . . . 2-21

Mapping Data Types . . . . . . . . . . . . . . . . . 2-22Mapping Between Informix and JDBC Data Types . . . . . 2-22Supported ResultSet.getXXX() Methods . . . . . . . . . 2-23

Handling Errors . . . . . . . . . . . . . . . . . . 2-25Using the SQLException Class . . . . . . . . . . . . 2-26Retrieving Informix Error Message Text . . . . . . . . . 2-27

Handling Transactions . . . . . . . . . . . . . . . . 2-27Other Informix Extensions to the JDBC API . . . . . . . . . 2-28

Using the Informix SERIAL and SERIAL8 Data Types . . . . 2-28Obtaining Driver Version Information . . . . . . . . . 2-30

Informix JDBC Driver and Remote Method Invocation (RMI) . . . 2-31Restrictions and Limitations . . . . . . . . . . . . . . 2-31

Chapter 3 TroubleshootingIn This Chapter . . . . . . . . . . . . . . . . . . . 3-3Debugging Your JDBC API Program . . . . . . . . . . . 3-3

Using the Debug Version of the Driver . . . . . . . . . 3-3Turning on Tracing . . . . . . . . . . . . . . . . 3-4

Performance Issues . . . . . . . . . . . . . . . . . 3-6Using the FET_BUF_SIZE Environment Variable . . . . . . 3-6Memory Management of TEXT and BYTE Data Types . . . . 3-6Reducing Network Traffic. . . . . . . . . . . . . . 3-7

Browser Security Issues . . . . . . . . . . . . . . . . 3-8

Appendix A Sample Code

Glossary

Index

ix JDBC Driver Programmer’s Guide

Introduction

Introduction

In This Introduction . . . . . . . . . . . . . . . . . . 3

About This Manual . . . . . . . . . . . . . . . . . . . 3Organization of This Manual . . . . . . . . . . . . . . 3Material Not Covered . . . . . . . . . . . . . . . . 4Types of Users . . . . . . . . . . . . . . . . . . . 4Software Dependencies . . . . . . . . . . . . . . . . 4

Documentation Conventions . . . . . . . . . . . . . . . 5Typographical Conventions . . . . . . . . . . . . . . 6Icon Conventions . . . . . . . . . . . . . . . . . . 6

Comment Icons . . . . . . . . . . . . . . . . . 7Platform Icons . . . . . . . . . . . . . . . . . . 7

Additional Documentation . . . . . . . . . . . . . . . . 8Printed Documentation . . . . . . . . . . . . . . . . 8On-Line Release Notes and Documentation Notes. . . . . . . 9Vendor-Specific Documentation . . . . . . . . . . . . . 9

Compliance with Industry Standards . . . . . . . . . . . . 10

Informix Welcomes Your Comments . . . . . . . . . . . . . 10

2 Inform
ix JDBC Driver Programmer’s Guide

In This IntroductionThis chapter introduces the Informix JDBC Driver Programmer’s Guide. Readthis chapter for an overview of the information provided in this manual andfor an understanding of the conventions used throughout.

About This ManualThis guide describes how to install, load, and use Informix JDBC Driver toconnect to an Informix database from within a Java application or applet.

This section discusses the organization of the manual, the intended audience,and the associated software products you must have to use Informix JDBCDriver.

Organization of This ManualThis manual includes the following chapters:

■ This introduction provides an overview of the manual, describes thedocumentation conventions used, and explains the generic style ofthis documentation.

■ Chapter 1, “Getting Started,” describes Informix JDBC Driver and theJDBC API in general. It provides essential information forprogrammers to immediately start using the product, such asinstructions on how to install and load the driver.

Introduction 3

Material Not Covered

■ Chapter 2, “Programming with Informix JDBC Driver,” explains inmore detail the Informix-specific information needed to use InformixJDBC Driver to connect to an Informix database. This includes how tocreate a connection to an Informix database, query tables, map datatypes, and handle errors.

■ Chapter 3, “Troubleshooting,” provides troubleshooting tips on howto solve programming errors and problems with the driver. It alsodescribes browser security issues when you use Informix JDBCDriver in a Java applet.

■ Appendix A, “Sample Code,” provides the full text of the examplesreferred to in the guide.

■ A Glossary of relevant terms follows the chapters, and an Indexdirects you to areas of particular interest.

Material Not CoveredThis guide does not describe all the interfaces, classes, and methods of theJDBC application programming interface (API) and does not provide detaileddescriptions of how to use the JDBC API to write Java applications thatconnect to Informix databases. The examples in the guide provide enoughinformation to show how to use Informix JDBC Driver but do not provide anextensive description of the JDBC API.

For more information about the JDBC API, visit the JavaSoft Web site at:

http://www.javasoft.com/products/jdk/1.1/docs/guide/jdbc/index.html.

Types of UsersThis guide is for Java programmers who use the JDBC API to connect toInformix databases via the Informix JDBC Driver. To use this guide, youshould know how to program in Java and, in particular, understand theclasses and methods of the JDBC API.

Software DependenciesTo use Informix JDBC Driver to connect to an Informix database, you must useone of the following Informix database servers:

4 Informix JDBC Driver Programmer’s Guide

Documentation Conventions

■ Informix Dynamic Server, Version 7.x

■ Informix Dynamic Server, Workgroup and Developer Editions,Version 7.x

■ Informix Dynamic Server with Advanced Decision Support andExtended Parallel Options, Version 8.x

■ Informix Dynamic Server with Universal Data Option, Version 9.x

■ INFORMIX-OnLine, Version 5.x

You must also use the following JavaSoft software:

■ Java Development Kit (JDK), Version 1.1.5 or later

Documentation ConventionsThis section describes the conventions that this manual uses. These conven-tions make it easier to gather information from this and other volumes in thedocumentation set:

■ Typographical conventions

■ Icon conventions

Introduction 5

Typographical Conventions

Typographical ConventionsThis manual uses the following standard set of conventions to introduce newterms, describe command syntax, and so forth.

Tip: When you are instructed to “enter” characters or to “execute” a command,immediately press RETURN after the entry. When you are instructed to “type” thetext or to “press” other keys, no RETURN is required.

Tip: The text and many of the examples in this manual show routine and data typenames in mixed lettercasing (uppercase and lowercase). Because Informix DynamicServer is case insensitive, you do not need to enter routine names exactly as shown:you can use uppercase letters, lowercase letters, or any combination of the two.

Icon ConventionsThroughout the documentation, you will find text identified by differenttypes of icons. This section describes these icons.

Convention Meaning

KEYWORD All keywords appear in uppercase letters in a serif font.

italics Within text, new terms and emphasized words appear in italics.Within syntax diagrams, values that you are to specify appearin italics.

boldface Identifiers (names of classes, interfaces, methods, objects,constants, events, functions, program variables, forms, labels,and reports), environment variables, database names,filenames, table names, column names, icons, menu items,command names, and other similar terms appear in boldface.

monospace Information that the product displays and information that youenter appear in a monospace typeface.

KEYSTROKE Keys that you are to press appear in uppercase letters in a sansserif font.

♦ This symbol indicates the end of product- or platform-specificinformation.


Icon Conventions

Comment Icons

Comment icons identify warnings, important notes, or tips. This informationis always displayed in italics.

Platform Icons

Platform icons identify paragraphs that contain platform-specificinformation.

These icons can apply to a row in a table, one or more paragraphs, or an entiresection. A ♦ symbol indicates the end of the platform-specific information.

Icon Description

The warning icon identifies vital instructions, cautions, orcritical information.

The important icon identifies significant information aboutthe feature or operation that is being described.

The tip icon identifies additional details or shortcuts for thefunctionality that is being described.

Icon Description

Identifies information that is specific to the UNIXenvironment.

Identifies information that is specific to the Windowsenvironment.

UNIX

Windows

Introduction 7

Additional Documentation

Additional DocumentationThis section describes the following parts of the documentation set:

■ Printed documentation

■ On-Line release notes and documentation notes

■ Vendor-specific documentation

Printed DocumentationThe following related Informix documents complement the informationin this manual:

■ If you have never used Structured Query Language (SQL), read theInformix Guide to SQL: Tutorial. It provides a tutorial on SQL as it isimplemented by Informix products. It also describes the funda-mental ideas and terminology for planning and implementing arelational database.

■ A companion volume to the Tutorial, the Informix Guide to SQL:Reference, includes details of the Informix system catalog tables,describes Informix and common environment variables that youshould set, and describes the column data types that Informixdatabase servers support.

Informix Error Messages might also be useful if you do not want to look upyour error messages on-line.


On-Line Release Notes and Documentation Notes

On-Line Release Notes and Documentation NotesIn addition to the Informix set of manuals, the following on-line filessupplement the information in this manual.

On-line files are located in the following directory: $JDBCLO-CATION/doc/release, where $JDBCLOCATION refers to the directory whereyou installed Informix JDBC Driver.♦

On-line files are located in the following directory: %JDBCLO-CATION%\doc\release, where %JDBCLOCATION% refers to the directorywhere you installed Informix JDBC Driver. ♦

Please examine these files because they contain vital information aboutapplication and performance issues.

Vendor-Specific DocumentationFor more information about the JDBC API, visit the JavaSoft Web site at:


On-Line File Purpose

JDBCREL.TXT The release notes describe any special actions required toconfigure and use Informix JDBC Driver on your computer.Additionally, this file contains information about any knownproblems and their workarounds.

JDBCDOC.TXT The documentation notes describe features not covered in themanuals or modified since publication.

UNIX

Windows

Introduction 9

Compliance with Industry Standards

Compliance with Industry StandardsThe American National Standards Institute (ANSI) has established a set ofindustry standards for SQL. Informix SQL-based products are fully compliantwith SQL-92 Transitional Level (published as ANSI X3.135-1992), which isidentical to ISO 9075:1992. In addition, many features of Informix databaseservers comply with the SQL-92 Intermediate and Full Level and X/OpenSQL CAE (common applications environment) standards.

Informix Welcomes Your CommentsPlease tell us what you like or dislike about our manuals. To help us withfuture versions of our manuals, we want to know about any corrections orclarifications that you would find useful. Please include the followinginformation:

■ The name and version of the manual you are using

■ Any comments you have about the manual

■ Your name, address, and phone number

Write to us at the following address:

Informix Software, Inc.Technical Publications300 Lakeside Dr., Suite 2700Oakland, CA 94612

If you prefer to send electronic mail, our address is:

[email protected]

We appreciate your feedback.


1Chapter

Getting Started

In This Chapter . . . . . . . . . . . . . . . . . . . . 1-3

What Is JDBC? . . . . . . . . . . . . . . . . . . . . 1-3

What Is a JDBC Driver? . . . . . . . . . . . . . . . . . 1-5

Overview of Informix JDBC Driver . . . . . . . . . . . . . 1-6

Installing the Driver . . . . . . . . . . . . . . . . . . 1-7Interactive Installation . . . . . . . . . . . . . . . . 1-7Silent Installation . . . . . . . . . . . . . . . . . . 1-9

Uninstalling the Driver . . . . . . . . . . . . . . . . . 1-11

Using the Driver in an Application . . . . . . . . . . . . . 1-12

Using the Driver in an Applet . . . . . . . . . . . . . . . 1-13

1-2 Infor
mix JDBC Driver Programmer’s Guide

In This ChapterThis chapter provides an overview of Informix JDBC Driver and the JDBC API.It includes the following sections:

■ What Is JDBC?

■ What Is a JDBC Driver?

■ Overview of Informix JDBC Driver

■ Installing the Driver

■ Uninstalling the Driver

■ Using the Driver in an Application

■ Using the Driver in an Applet

What Is JDBC?JDBC is the JavaSoft specification of a standard application programminginterface (API) that allows Java programs to access database managementsystems. The JDBC API consists of a set of interfaces and classes written in theJava programming language.

Using these standard interfaces and classes, programmers can write applica-tions that connect to databases, send queries written in structured querylanguage (SQL), and process the results.

Getting Started 1-3

What Is JDBC?

The JDBC API is consistent with the style of the core Java interfaces andclasses, such as java.lang and java.awt. The following table describes theinterfaces, classes, and exceptions that make up the JDBC API.

Name of Interface, Class, orException Description

java.sql.CallableStatement Interface used to execute stored procedures.

java.sql.Connection Interface used to establish a connection to a database.SQL statements run within the context of aconnection.

java.sql.DatabaseMetaData Interface used to return information about thedatabase.

java.sql.Driver Interface used to locate the driver for a particulardatabase management system.

java.sql.PreparedStatement Interface used to send precompiled SQL statementsto the database server and obtain results.

java.sql.ResultSet Interface used to process the results returned fromexecuting an SQL statement.

java.sql.ResultSetMetaData Interface used to return information about thecolumns in a ResultSet object.

java.sql.Statement Interface used to send static SQL statements to thedatabase server and obtain results.

java.sql.Date Subclass of java.util.Date used for the SQL DATEdata type.

java.sql.DriverManager Class used to manage a set of JDBC drivers.

java.sql.DriverPropertyInfo Class used to discover and supply properties to aconnection.

java.sql.Time Subclass of java.util.Date used for the SQL TIMEdata type.

java.sql.TimeStamp Subclass of java.util.Date used for the SQLTIMESTAMP data type.

(1 of 2)

1-4 Informix JDBC Driver Programmer’s Guide

What Is a JDBC Driver?

Since JDBC is a standard specification, one Java program that uses the JDBCAPI can connect to any database management system (DBMS), as long as adriver exists for that particular DBMS.

For more information about the JDBC API, visit the JavaSoft Web site at:


What Is a JDBC Driver?The JDBC API defines the Java interfaces and classes that programmers use toconnect to databases and send queries. A JDBC driver implements these inter-faces and classes for a particular DBMS vendor.

A Java program that uses the JDBC API loads the specified driver for aparticular DBMS before it actually connects to a database. The JDBC Driver-Manager class then sends all JDBC API calls to the loaded driver.

There are four types of JDBC drivers:

■ JDBC-ODBC bridge plus ODBC driver, also called Type 1.

Translates JDBC API calls into Microsoft ODBC calls that are thenpassed to the ODBC driver. The ODBC binary code must be loaded onevery client machine that uses this type of driver.

ODBC is an acronym for Open Database Connectivity.

java.sql.Types Class used to define constants that are used toidentify standard SQL data types, such asVARCHAR, INTEGER, and DECIMAL.

java.sql.DataTruncation Exception thrown or warning reported when datahas been truncated.

java.sql.SQLException Exception that provides information about adatabase error.

java.sql.SQLWarning Warning that provides information about a databasewarning.

Name of Interface, Class, orException Description

(2 of 2)

Getting Started 1-5

Overview of Informix JDBC Driver

■ Native-API partly Java driver, also called Type 2.

Converts JDBC API calls into DBMS-specific client API calls. Like thebridge driver, this type of driver requires that some binary code beloaded on each client machine.

■ JDBC-Net pure-Java driver, also called Type 3.

Sends JDBC API calls to a middle-tier net server that translates thecalls into DBMS-specific network protocol. The translated calls arethen sent to a particular DBMS.

■ Native-protocol pure-Java driver, also called Type 4.

Converts JDBC API calls directly into the DBMS-specific networkprotocol without a middle tier. This allows the client applications toconnect directly to the database server.

Overview of Informix JDBC DriverInformix JDBC Driver is a native-protocol, pure-Java driver (Type 4). Thismeans that when you use Informix JDBC Driver in a Java program that usesthe JDBC API to connect to an Informix database, your session connectsdirectly to the database or database server without a middle tier.

Informix JDBC Driver is based on Version 1.22 of the JDBC API.

Informix JDBC Driver is released as a Java class file called setup.class. Forinstructions on how to install the driver, refer to “Installing the Driver” onpage 1-7.

The product (after installation) consists of the following files, some of whichare Java archive (JAR) files:

■ lib/ifxjdbc.jar

JAR file that contains the optimized implementations of the JDBC APIinterfaces, classes, and methods.

The file is compiled with the -O option of the javac command.

■ lib/ifxjdbc-g.jar

Debug version of ifxjdbc.jar.

The file is compiled with the -g option of the javac command.


Installing the Driver

■ demo/basic/*

demo/rmi/*

demo/stores7/*

Directories that contain the sample Java programs that use the JDBCAPI.

■ doc/release/*

Directory that contains the on-line release and documentation notes,as well as the HTML and PDF versions of this programmer’s guide.

Installing the DriverInformix JDBC Driver is released as a Java class file called setup.class.

There are two ways to install the driver: interactively with a Setup programor silently at the command line. The following sections describe the two waysfor both UNIX and Windows.

Interactive InstallationThis section describes how to interactively install Informix JDBC Driver withthe Setup program.

To interactively install Informix JDBC Driver on UNIX

1. If you are installing Informix JDBC Driver from a CD, load the discinto the CD-ROM drive.

If you are downloading the driver from the Web, download thesetup.class file into a temporary directory.

2. Be sure your CLASSPATH environment variable points to Version1.1.5 or later of the Java Development Kit (JDK).

3. At the UNIX shell prompt, create a directory to hold the contents ofthe driver.

For example, to create the directory /work/jdbcdriver_home,execute the following command:

mkdir /work/jdbcdriver_home

UNIX

Getting Started 1-7

Interactive Installation

4. Change directory to either the CD-ROM drive, if you are installingfrom a CD, or the temporary directory that contains the downloadedsetup.class file, if you are downloading the driver from the Web.

5. Launch the Setup program with the java command at the UNIX shellprompt:

java setup

6. The Setup program guides you through the installation of InformixJDBC Driver.

After the Welcome window, the program asks you for your serialnumber and key. It then asks you to accept a licensing agreement.The program then asks you for the name of the directory that willhold the contents of the driver. In our example, this directory is called/work/jdbcdriver_home and was created in Step 3 of theseinstructions.

The installation is complete when you get to the InstallationComplete window. ♦

To interactively install Informix JDBC Driver on Windows




3. Using Windows Explorer, create a directory to hold the contents ofthe driver.

Assume, for this example, that the new directory is calledc:\work\jdbcdriver_home.


5. Launch the Setup program with the java command at the Windowscommand prompt:

java setup

Windows


Silent Installation

6. The Setup program guides you through the installation of InformixJDBC Driver.

After the Welcome window, the program asks you for your serialnumber and key. It then asks you to accept a licensing agreement.The program then asks you for the name of the directory that willhold the contents of the driver. In our example, this directory is calledc:\work\dbcdriver_home and was created in Step 3 of theseinstructions.

The installation is complete when you get to the InstallationComplete window. ♦

Silent InstallationThis section describes how to silently install Informix JDBC Driver from theUNIX shell prompt or Windows command line.

To silently install Informix JDBC Driver on UNIX




3. At the UNIX shell prompt, create a directory to hold the contents ofthe driver.

For example, to create the directory /work/jdbcdriver_home,execute the following command:

mkdir /work/jdbcdriver_home


UNIX

Getting Started 1-9

Silent Installation

5. Execute the following command at the UNIX shell prompt:java setup -o <directory> serialNo=<serial_no> key=<key>

where directory refers to the directory that will hold the contents ofthe driver (created in Step 3 of these instructions) and serial_no andkey refer to the installation serial number and key.

The keywords serialNo and key are case sensitive. You can also usethe keywords SERIALNO, serialno, and KEY.

For example, to install Informix JDBC Driver in the directory/work/jdbcdriver_home using a serial number of INF#J123456 anda key of ABCDEF, execute the following command:java setup -o /work/jdbcdriver_home serialNo=INF#J123456 key=ABCDEF

If the specified directory already contains Informix JDBC Driver files,the command asks you if you want to overwrite them.

The installation is complete after the command has finishedexecuting.♦

To silently install Informix JDBC Driver on Windows




3. Using Windows Explorer, create a directory to hold the contents ofthe driver.

Assume, for this example, that the new directory is calledc:\work\jdbcdriver_home.


Windows


Uninstalling the Driver

5. Execute the following command at the Windows command prompt:java setup -o <directory> serialNo=<serial_no> key=<key>

where directory refers to the directory that will hold the contents ofthe driver (created in Step 3 of these instructions) and serial_no andkey refer to the installation serial number and key.

The keywords serialNo and key are case sensitive. You can also usethe keywords SERIALNO, serialno, and KEY.

For example, to install Informix JDBC Driver in the directoryc:\work\jdbcdriver_home using a serial number of INF#J123456and a key of ABCDEF, execute the following command:java setup -o c:\work\jdbcdriver_home serialNo=INF#J123456 key=ABCDEF

If the directory already contains Informix JDBC Driver files, thecommand asks you if you want to overwrite them.

The installation is complete once the command has finishedexecuting.♦

Uninstalling the DriverUninstalling Informix JDBC Driver completely removes the driver and all ofits components from your computer. The following sections describe how touninstall Informix JDBC Driver on UNIX and Windows.

To uninstall Informix JDBC Driver on UNIX

1. Change to the directory in which you installed Informix JDBC Driver.

For example, if you installed the driver in the directory/work/jdbcdriver_home, execute the following command at theUNIX shell prompt:

cd /work/jdbcdriver_home

2. Launch the Uninstall program with the java command:java uninstall

3. The Uninstall program guides you through the uninstallation ofInformix JDBC Driver. ♦

UNIX

Getting Started 1-11

Using the Driver in an Application

To uninstall Informix JDBC Driver on Windows

1. Change to the directory in which you installed Informix JDBC Driver.

For example, if you installed the driver in the directoryc:\work\jdbcdriver_home, execute the following command at thecommand prompt:

cd c:\work\jdbcdriver_home

2. Launch the Uninstall program with the java command:java uninstall

3. The Uninstall program guides you through the uninstallation ofInformix JDBC Driver. ♦

Important: When you uninstall Informix JDBC Driver, you always get a messagethat says the ifxjdbc.jar and ifxjdbc-g.jar files have changed, even if you have neverused the driver. This is because the files are automatically written to during theinstallation of the driver.

Using the Driver in an ApplicationTo use Informix JDBC Driver in an application, you must set your CLASSPATHenvironment variable to point to the driver files. The CLASSPATHenvironment variable tells the Java virtual machine (JVM) and other applica-tions where to find the Java class libraries used in a Java program.

There are two ways of setting your CLASSPATH environment variable:

■ Add the full pathname of the ifxjdbc.jar file to the CLASSPATHenvironment variable, as shown in the following example:setenv CLASSPATH /work/jdbcdriver_home/lib/ifxjdbc.jar:$CLASSPATH

To use the version of the driver that supports debugging, specify thefile ifxjdbc-g.jar instead of ifxjdbc.jar.

■ Unpack the ifxjdbc.jar file and add its directory to the CLASSPATHenvironment variable, as shown in the following example:

cd /work/jdbcdriver_home/libjar xvf ifxjdbc.jarsetenv CLASSPATH /work/jdbcdriver_home/lib:$CLASSPATH


Windows


Using the Driver in an Applet

For more information on the jar utility, refer to your JavaSoft documentationat the following Web site:

http://www.javasoft.com.

Using the Driver in an AppletYou can use Informix JDBC Driver in an applet to connect to an Informixdatabase from a browser such as Netscape Navigator or Microsoft InternetExplorer. The following steps show how to specify Informix JDBC Driver inthe applet and how to ensure that the driver is correctly downloaded fromthe Web server.

To use Informix JDBC Driver in an applet

1. Install the ifxjdbc.jar file in the same directory as your applet classfile.

To use the version of the driver that supports debugging, install thefile ifxjdbc-g.jar instead of ifxjdbc.jar.

2. Specify the ifxjdbc.jar file in the ARCHIVE attribute of the APPLETtag in your HTML file, as shown in the following example:

<APPLET ARCHIVE=ifxjdbc.jar CODE=my_applet.classCODEBASE=http://www.myhost.com WIDTH=460 HEIGHT=160></APPLET>


Important: A few browsers do not support the ARCHIVE attribute of the APPLETtag. If you think this is true of the browsers that are going to download your applet,you must unpack and install the ifxjdbc.jar file in the root directory of your Webserver.

If the browsers also do not support the JDBC API, you must install the class filesincluded in the java.sql package in the root directory of the Web server as well.

See your Web server documentation for information on installing files in the rootdirectory.

Getting Started 1-13

2Chapter

Programming with InformixJDBC Driver

In This Chapter . . . . . . . . . . . . . . . . . . . . 2-3

Establishing a Connection . . . . . . . . . . . . . . . . 2-3Loading Informix JDBC Driver . . . . . . . . . . . . . 2-4Creating a Connection . . . . . . . . . . . . . . . . 2-4

Format of Database URLs . . . . . . . . . . . . . . 2-5Database Versus Database Server Connections . . . . . . 2-7Specifying Environment Variables with the Properties Class . . 2-9Supported Informix Environment Variables . . . . . . . 2-10

Accessing Database Metadata . . . . . . . . . . . . . . . 2-13

Querying the Database . . . . . . . . . . . . . . . . . 2-14Manipulating Informix BYTE and TEXT Data Types . . . . . . 2-14

Inserting into or Updating BYTE and TEXT Columns . . . . 2-15Selecting from BYTE and TEXT Columns . . . . . . . . 2-17

Manipulating Informix INTERVAL Data Types . . . . . . . . 2-19Informix-Specific Information About Querying a Database. . . . 2-20Example of Sending a Query to an Informix Database . . . . . 2-21

Mapping Data Types . . . . . . . . . . . . . . . . . . 2-22Mapping Between Informix and JDBC Data Types. . . . . . . 2-22Supported ResultSet.getXXX() Methods . . . . . . . . . . 2-23

Handling Errors . . . . . . . . . . . . . . . . . . . . 2-25Using the SQLException Class . . . . . . . . . . . . . 2-26Retrieving Informix Error Message Text . . . . . . . . . . 2-27

Handling Transactions . . . . . . . . . . . . . . . . . 2-27

Other Informix Extensions to the JDBC API . . . . . . . . . . 2-28Using the Informix SERIAL and SERIAL8 Data Types . . . . . 2-28Obtaining Driver Version Information . . . . . . . . . . . 2-30

2-2 Infor

Informix JDBC Driver and Remote Method Invocation (RMI) . . . . 2-31

Restrictions and Limitations . . . . . . . . . . . . . . . . 2-31


In This ChapterThis chapter explains the Informix-specific information you need to useInformix JDBC Driver to connect to an Informix database. The chapterincludes the following sections:

■ Establishing a Connection

■ Accessing Database Metadata

■ Querying the Database

■ Mapping Data Types

■ Handling Errors

■ Handling Transactions

■ Other Informix Extensions to the JDBC API

■ Informix JDBC Driver and Remote Method Invocation (RMI)

■ Restrictions and Limitations

Establishing a ConnectionYou must first establish a connection to an Informix database server ordatabase before you can start sending queries and receiving results in yourJava program.

You establish a connection by completing two actions:

1. Load Informix JDBC Driver.

2. Create a connection to either a database server or a specific database.

Programming with Informix JDBC Driver 2-3

Loading Informix JDBC Driver

Loading Informix JDBC DriverTo load Informix JDBC Driver, use the Class.forName() method, passing it thevalue com.informix.jdbc.IfxDriver, as shown in the following codeexample from the CreateDB.java program:

try { Class.forName("com.informix.jdbc.IfxDriver"); }catch (Exception e) { System.out.println("ERROR: failed to load Informix JDBC driver."); e.printStackTrace(); return; }

The Class.forName() method loads the Informix implementation of theDriver class, IfxDriver. The IfxDriver class then creates an instance of thedriver and registers it with the DriverManager.

Once you have loaded Informix JDBC Driver, you are ready to connect to anInformix database or database server.

If you are writing an applet that will be viewed with Microsoft InternetExplorer, you might need to explicitly register Informix JDBC Driver to avoidplatform incompatibilities.

To explicitly register the driver, use the DriverManager.registerDriver()method, as shown in the following code example:

DriverManager.registerDriver((Driver)Class.forName("com.informix.jdbc.IfxDriver").newInstance());

This method might register Informix JDBC Driver twice, which will not causea problem. ♦

Creating a ConnectionTo create a connection to an Informix database or database server, use theDriverManager.getConnection() method. This method creates a Connectionobject, which is later used to create SQL statements, send them to an Informixdatabase, and process the results.

Windows


Creating a Connection

The DriverManager class keeps track of the available drivers and handlesconnection requests between appropriate drivers and databases or databaseservers. The url parameter of the getConnection() method is a database URLthat specifies the subprotocol (the database connectivity mechanism), thedatabase or database server identifier, and a list of properties. A secondparameter to the getConnection() method, property, is the property list. See“Specifying Environment Variables with the Properties Class” on page 2-9for an example of how to specify a property list.

The following example shows a database URL that connects to a databasecalled testDB:

jdbc:informix-sqli://123.45.67.89:1533/testDB:INFORMIXSERVER=myserver;user=rdtest;password-test

The details of the database URL syntax are described in the next section.

The following code example from the CreateDB.java program shows how toconnect to database testDB using Informix JDBC Driver. In the full example,the url variable, described in the preceding example, is passed in as aparameter when the program is run at the command line.

try { conn = DriverManager.getConnection(url); }catch (SQLException e) { System.out.println("ERROR: failed to connect!"); System.out.println("ERROR: " + e.getMessage()); e.printStackTrace(); return; }

Important: Not all methods of the Connection interface are supported by InformixJDBC Driver. For a list of unsupported methods, see “Restrictions and Limitations”on page 2-31.

Format of Database URLs

Informix JDBC Driver supports database URLs of the following format:

jdbc:informix-sqli://{<ip-address>|<host-name>}:<port-number>[/<dbname>]:INFORMIXSERVER=<server-name>;user=<username>;password=<password>[;<name>=<value>[;<name>=<value>]...]



In the preceding syntax:

■ curly brackets ( {} ) together with vertical lines ( | ) denote more thanone choice of variable.

■ angle brackets ( <> ) denote a variable value.

■ brackets ( [] ) denote an optional value.

■ words or symbols not enclosed in either angle brackets or bracketsare required (INFORMIXSERVER=, for example).

Important: Blank spaces are not allowed in the database URL.

The following table describes the variable parts of the database URL.

Database URL Variable Required? Description

ip-address

host-name

Yes The IP address or the host name of thecomputer running the Informix databaseserver.

An example of an IP address is 123.45.67.89.

An example of a host name is myhost.com ormyhost.informix.com.

port-number Yes The port number of the Informix databaseserver.

dbname No The name of the Informix database to whichyou want to connect. If you do not specify thename of a database, a connection is made to theInformix database server.

server-name Yes The name of the Informix server to which youwant to connect. This is the value of theINFORMIXSERVER environment variable.

The INFORMIXSERVER environmentvariable is required in the database URL,unless it is included in the property list.

(1 of 2)



Database Versus Database Server Connections

Using the DriveManager.getConnection() method, you can create aconnection to either an Informix database or an Informix database server.

To create a connection to an Informix database, specify the name of thedatabase in the <dbname> variable of the database URL. If you do not specifythe name of a database, a connection is made to the database server specifiedby the INFORMIXSERVER environment variable instead.

If you connect directly to an Informix database server, you can execute an SQLstatement that connects to a database later in your Java program.

All connections to both databases and database servers must include thename of an Informix database server via the INFORMIXSERVER environmentvariable.

user Yes The name of the user that wants to connect tothe Informix database or database server.

password Yes The password of the user specified by user.

name=value No A name-value pair that specifies a value for theInformix environment variable contained inthe name variable, recognized by eitherInformix JDBC Driver or Informix databaseservers. The name variable is case insensitive.

Informix JDBC Driver reads Informixenvironment variables from either thedatabase URL or from a connection propertylist, described in “Specifying EnvironmentVariables with the Properties Class” onpage 2-9. The user’s environment is notconsulted.

Refer to “Supported Informix EnvironmentVariables” on page 2-10 for a list of Informixenvironment variables supported by InformixJDBC Driver.

Database URL Variable Required? Description

(2 of 2)



Important: If you are connecting to an INFORMIX-OnLine 5.x database server, youmust specify the USEV5SERVER environment variable in the database URL orproperty list. Its value should be 1, such as “USERV5SERVER=1”.

The example given in “Creating a Connection” on page 2-4 shows how tocreate a connection directly to the Informix database called testDB with thedatabase URL.

The following example from the DBConnection.java program shows how tofirst create a connection to the Informix database server called myserver andthen connect to the database testDB later in the Java program using theStatement.executeUpdate() method.

The database URL that is passed in as a parameter to the program when theprogram is run at the command line is as follows; note that the URL does notinclude the name of a database:

jdbc:informix-sqli://123.45.67.89:1533:INFORMIXSERVER=myserver;user=rdtest;password-test



The code is as follows:

String cmd = null;int rc;

Connection conn = null;

try { Class.forName("com.informix.jdbc.IfxDriver"); }catch (Exception e) { System.out.println("ERROR: failed to load Informix JDBC driver."); }

try { conn = DriverManager.getConnection(url); }catch (SQLException e) { System.out.println("ERROR: failed to connect!"); }

try { Statement stmt = conn.createStatement(); cmd = "database testDB;"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

Specifying Environment Variables with the Properties Class

Informix JDBC Driver reads Informix environment variables only from thename-value pairs in the connection database URL or from a connectionproperty list. The driver does not consult the user’s environment for anyenvironment variables. Refer to “Supported Informix EnvironmentVariables” on page 2-10 for a list of supported Informix environmentvariables.

To specify Informix environment variables in the name-value pairs of theconnection database URL, refer to “Format of Database URLs” on page 2-5.



To specify Informix environment variables via a property list, use thejava.util.Properties class to build the list of properties. The list of propertiesmight include Informix environment variables, such as INFORMIXSERVER,as well as <user> and <password>. After you have built the property list,pass it to the DriverManager.getConnection() method as a secondparameter. You still need to include a database URL as the first parameter,although in this case you do not need to include the list of properties in theURL.

The following code from the optofc.java example shows how to use thejava.util.Properties class to set connection properties. It first uses theProperties.put() method to set the environment variable OPTOFC to 1; thenit connects to the database.

The DriverManager.getConnection() method in this example takes twoparameters: the database URL and the property list. The example creates aconnection similar to the example given in “Creating a Connection” onpage 2-4.


try { Properties pr = new Properties(); pr.put("OPTOFC","1"); conn = DriverManager.getConnection(newUrl, pr); }catch (SQLException e) { System.out.println("ERROR: failed to connect!"); }

Supported Informix Environment Variables

The following table lists the Informix environment variables supported byInformix JDBC Driver.



Important: The variable DBDATE is not supported. To be compatible with the JDBCAPI specification, the DBDATE format has been hard-coded as Y4MD-, such as 1998-05-01.

Supported InformixEnvironment Variables Description

DBANSIWARN Checks for Informix extensions to ANSI standardsyntax.

DBSPACETEMP Specifies the dbspaces in which temporary tables will bebuilt.

DBUPSPACE Specifies the amount of system disk space that theUPDATE STATISTICS statement can use when it simul-taneously constructs multiple-column distributions.

DELIMIDENT Specifies that strings set off by double quotes aredelimited identifiers.

FET_BUF_SIZE Overrides the default setting for the size of the fetchbuffer for all data except large objects.

IFX_AUTOFREE When set to 1, specifies that the Statement.close()method does not require a network round-trip to freethe server cursor resources if the cursor has alreadybeen closed in the database server.

The database server automatically frees the cursorresources after the cursor is closed, either explicitly bythe ResultSet.close() method or implicitly by theOPTOFC environment variable.

Once the cursor resources have been freed, the cursorcan no longer be referenced.

INFORMIXCONRETRY Specifies the maximum number of additionalconnection attempts that should be made to eachdatabase server by the client during the time limitspecified by the default value of the INFORMIX-CONTIME environment variable (15 seconds).

INFORMIXOPCACHE Specifies the size of the memory cache for the staging-area blobspace of the client application.

(1 of 3)



INFORMIXSERVER Specifies the default database server to which an explicitor implicit connection is made by a client application.

INFORMIXSTACKSIZE Specifies the stack size, in kilobytes, that the databaseserver uses for a particular client session.

NODEFDAC When set to YES, prevents default table and routineprivileges from being granted to the PUBLIC user whena new table or routine is created in a database that is notANSI compliant. Default is NO.

OPTCOMPIND Specifies the join method that the query optimizershould use.

OPTOFC When set to 1, the ResultSet.close() method does notrequire a network round-trip if all the qualifying rowshave already been retrieved in the client’s tuple buffer.The database server automatically closes the cursorafter all the rows have been retrieved.

Informix JDBC Driver might or might not haveadditional rows in the client’s tuple buffer before thenext ResultSet.next() method is called. Therefore,unless Informix JDBC Driver has received all the rowsfrom the database server, the ResultSet.close() methodmight still require a network round-trip when OPTOFCis set to 1.

PATH Specifies the directories that should be searched forexecutable programs.

PDQPRIORITY Determines the degree of parallelism used by thedatabase server.

PLCONFIG Specifies the name of the configuration file used by thehigh-performance loader.


(2 of 3)


Accessing Database Metadata

For a detailed description of a particular environment variable, refer toInformix Guide to SQL: Reference. You can find the on-line version of this guideat the following Web site:

http://www.informix.com/answers

Accessing Database MetadataTo access information about an Informix database, use the JDBC APIDatabaseMetaData interface.

Informix JDBC Driver is completely compatible with the JDBC API specifi-cation for accessing database metadata. The driver supports all the methodsof the DatabaseMetaData interface.

Informix JDBC Driver uses the sysmaster database to get database metadata.If you want to use the DatabaseMetaData interface in your Java program, thesysmaster database must exist in the Informix database server to which yourJava program is connected.

PSORT_DBTEMP Specifies one or more directories to which the databaseserver writes the temporary files it uses whenperforming a sort.

PSORT_NPROCS Enables the database server to improve the performanceof the parallel-process sorting package by allocatingmore threads for sorting.

USEV5SERVER When set to YES, specifies that the Java program isconnecting to an INFORMIX-OnLine 5.x databaseserver.

This environment variable is mandatory if you areconnecting to an INFORMIX-OnLine 5.x databaseserver.


(3 of 3)


Querying the Database

Informix JDBC Driver interprets the JDBC API term schemas to mean the namesof Informix users who own tables. The DatabaseMetaData.getSchemas()method returns all the user names found in the owner column of thesystables system catalog.

Similarly, Informix JDBC Driver interprets the JDBC API term catalogs to meanthe names of Informix databases. The method DatabaseMetaData.getCat-alogs() returns the names of all the databases that currently exist in theInformix database server to which your Java program is connected.

The example DBMetaData.java shows how to use the DatabaseMetaDataand ResultSetMetaData interfaces to gather information about a newprocedure. Refer to Appendix A, “Sample Code,” for the full text of thisexample.

Querying the DatabaseInformix JDBC Driver complies with the JDBC API specification for sendingqueries to a database and retrieving the results. The driver supports almostall the methods of the Statement, PreparedStatement, CallableStatement,ResultSet, and ResultSetMetaData interfaces.

Refer to “Restrictions and Limitations” on page 2-31 for a list of methods thatare not supported by Informix JDBC Driver and should not be used in yourJava program. This reference also includes a list of methods that behavedifferently than described in the JDBC API specification.

Manipulating Informix BYTE and TEXT Data TypesThe section describes the Informix BYTE and TEXT data types and how tomanipulate columns of these data types with the JDBC API.

The BYTE data type is a data type for a simple large object that stores any kindof data in an undifferentiated byte stream. Examples of binary data includespreadsheets, digitized voice patterns, and video clips. The TEXT data type isa data type for a simple large object that stores any kind of text data. It cancontain both single and multi-byte characters.


Manipulating Informix BYTE and TEXT Data Types

Both data types have no maximum size, and columns of either data type havea theoretical limit of 231 bytes and a practical limit determined by your diskcapacity.

For more detailed information about the Informix BYTE and TEXT data types,refer to Informix Guide to SQL: Reference and Informix Guide to SQL: Syntax. Youcan find the on-line version of both of these guides at the following Web site:


Inserting into or Updating BYTE and TEXT Columns

To insert into or update BYTE and TEXT columns, read a stream of data froma source, such as an operating system file, and transmit it to the database asa java.io.InputStream object. The PreparedStatement interface providesmethods for setting an input parameter to this Java input stream. When thestatement is executed, Informix JDBC Driver makes repeated calls to the inputstream, reading its contents and transmitting those contents as the actualparameter data to the database.

For BYTE data types, use the PreparedStatement.setBinaryStream() methodto set the input parameter to the InputStream object. For TEXT data types, usethe PreparedStatement.setAsciiStream() method.



The following example from the ByteType.java program shows how to insertthe contents of the operating system file data.dat into a column of data typeBYTE:

try{stmt = conn.createStatement();stmt.executeUpdate("create table tab1(col1 byte)");}

catch ( SQLException e) { System.out.println("Failed to create table ..." + e.getMessage());// e.printStackTrace(); }

System.out.println("Trying to insert data using Prepare Statement ...");try { pstmt = conn.prepareStatement("insert into tab1 values (?)"); }catch (SQLException e) { System.out.println("Failed to Insert into tab: " + e.toString());// e.printStackTrace(); }File file = new File("data.dat");int fileLength = (int) file.length();InputStream value = null;FileInputStream fileinp = null;int row = 0;String str = null;int rc = 0;ResultSet rs = null;

System.out.println("Inserting data ...\n");try{ fileinp = new FileInputStream(file); value = (InputStream)fileinp; }catch (Exception e) {}

try { pstmt.setBinaryStream(1,value,10); //set 1st column }catch (SQLException e) { System.out.println("Unable to set parameter"); }

try{pstmt.executeUpdate();}

catch (SQLException e)



{System.out.println("Failed to Insert into tab: " + e.toString());e.printStackTrace();}

The example first creates a java.io.File object that represents the operatingsystem file data.dat. The example then creates a FileInputStream object toread from the File object. The FileInputStream object is cast to its superclassInputStream, which is the expected data type of the second parameter to thePreparedStatement.setBinaryStream() method. The setBinaryStream()method is executed on the already prepared INSERT statement, which sets theinput stream parameter. Finally, the PreparedStatement.executeUpdate()method is executed, which actually inserts the contents of the data.datoperating system file into the BYTE column of the table.

The TextType.java program shows how to insert data into a TEXT column. Itis very similar to inserting into a BYTE column, except the methodsetAsciiStream() is used to set the input parameter instead ofsetBinaryStream().

Selecting from BYTE and TEXT Columns

After you select from a table into a ResultSet object, you can use theResultSet.getBinaryStream() and ResultSet.getAsciiStream() methods toretrieve a stream of binary or ASCII data from BYTE and TEXT columns,respectively. Both methods return an InputStream object, which can be usedto read the data in chunks.

All the data in the returned stream must be read before you get the value ofany other column in the table. The next call to a getXXX() method implicitlycloses the stream.



The following example from the ByteType.java program shows to how selectdata from a BYTE column and print out the data to the standard output:

try{stmt = conn.createStatement();rs = stmt.executeQuery("Select * from tab1");while( rs.next() ) { row++; value = rs.getBinaryStream(1);

System.out.println("\nResult of row #" + row + ", size = " +value.available() + “ from getAsciiStream(1) ..\n”);

} }catch (Exception e) { }dispValue(value);

public static void dispValue(InputStream in){

int size;byte buf;int count = 0;try

{size = in.available();byte ary[] = new byte[size];buf = (byte) in.read();while(buf!=-1)

{ary[count] = buf;count++;buf = (byte) in.read();}

System.out.println( new String(ary).trim());}

catch (Exception e){System.out.println("Error occur during reading stream ... \n");}

}

The example first puts the result of a SELECT statement into a ResultSetobject. It then executes the method ResultSet.getBinaryStream() to retrievethe BYTE data into a Java InputStream object.

The method dispValue(), whose Java code is also included in the example, isused to actually print out the contents of the column to standard output. ThedispValue() method uses byte arrays and the InputStream.read() method tosystematically read the contents of the BYTE column.


Manipulating Informix INTERVAL Data Types

The TextType.java program shows how to select data from a TEXT column. Itis very similar to selecting from a BYTE column, except the getAsciiStream()method is used instead of getBinaryStream().

Manipulating Informix INTERVAL Data TypesThe Informix INTERVAL data type stores a value that represents a span oftime. INTERVAL data types are divided into two types: year-month intervalsand day-time intervals. A year-month interval can represent a span of yearsand months, and a day-time interval can represent a span of days, hours,minutes, seconds, and fractions of a second.

The following example from the Interval.java program shows how to insertinto and select from the two types of INTERVAL data types:

/* * Create a table with two interval columns */System.out.println("");System.out.println("Create a table");try { cmd = "create table intrvl_tab " +

"(ym interval year to month, ds interval day to second)";

int rowcount = stmt.executeUpdate(cmd); System.out.println("Create table rowcount = " + rowcount); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); return; }

/* * Insert an interval using a String host variable. */System.out.println("");System.out.println("Insert an interval using a String host variable");try { String ym = new String("102-11"); // 102 years and 11 months String ds = new String("5 10:03:55"); // 5 days 10 hours 3 minutes

// and 55 seconds cmd = "insert into intrvl_tab values (?, ?)"; PreparedStatement pstmt = conn.prepareStatement(cmd);

pstmt.setString(1, ym);


Informix-Specific Information About Querying a Database

pstmt.setString(2, ds);

int rowcount = pstmt.executeUpdate(); System.out.println("Insert rowcount = " + rowcount); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); return; }

/* * Now fetch the row back */System.out.println("");System.out.println("Select from intrvl_tab");try { cmd = "select * from intrvl_tab"; ResultSet rs = stmt.executeQuery(cmd);

String ym; String ds; while(rs.next()) { ym = rs.getString(1); System.out.println(" Select: ym = " + ym);

ds = rs.getString(2); System.out.println(" Select: ds = " + ds); }

}catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); return; }

Informix-Specific Information About Querying a DatabaseThis section describes the Informix-specific information you need to know touse Informix JDBC Driver to query an Informix database and process theresults.


Example of Sending a Query to an Informix Database

The Informix JDBC Driver implementation of the Statement.execute()method returns a single ResultSet object. This differs from the JDBC APIspecification, which states that the method can return multiple ResultSetobjects.

Be sure to always explicitly close a Statement, PreparedStatement, andCallableStatement object by calling the appropriate close() method in yourJava program when you have finished processing the results of an SQLstatement. This immediately deallocates the resources that have beenallocated to execute your SQL statement. Although the ResultSet.close()method closes the ResultSet object, it does not deallocate the resourcesallocated to the Statement, PreparedStatement, or CallableStatementobjects.

Example of Sending a Query to an Informix DatabaseThe following example from the SimpleSelect.java program shows how touse the PreparedStatement interface to execute a SELECT statement that hasone input parameter:

try {

PreparedStatement pstmt = conn.prepareStatement("Select * from x where a = ?;"); pstmt.setInt(1, 11); ResultSet r = pstmt.executeQuery();

while(r.next()) { short i = r.getShort(1); System.out.println("Select: column a = " + i); } r.close(); pstmt.close(); }catch (SQLException e) { System.out.println("ERROR: Fetch statement failed: " + e.getMessage()); }

The program first uses the Connection.prepareStatement() method toprepare the SELECT statement with its single input parameter. It then assignsa value to the parameter using the PreparedStatement.setObject() methodand executes the query with the PreparedStatement.executeQuery()method.


Mapping Data Types

The program returns resulting rows in a ResultSet object, through which theprogram iterates with the ResultSet.next() method. The program retrievesindividual column values with the ResultSet.getShort() method, since thedata type of the selected column is SMALLINT.

Finally, both the ResultSet and PreparedStatement objects are explicitlyclosed with the appropriate close() method.

For more information on which getXXX() methods should be used to retrieveindividual column values, refer to “Mapping Data Types” on page 2-22.

Mapping Data TypesThis section discusses mapping issues between data types defined in a Javaprogram and the data types supported by the Informix database server. Inparticular it covers the following two topics:

■ Mapping between JDBC API data types and Informix data types

■ ResultSet.getXXX() methods supported by Informix JDBC Driver

Mapping Between Informix and JDBC Data TypesSince there are variations between the SQL data types supported by eachdatabase vendor, the JDBC API defines a set of generic SQL data types in theclass java.sql.Types. Use these JDBC API data types to reference generic SQLtypes in your Java programs that use the JDBC API to connect to Informixdatabases.

The following table shows the Informix data type to which each JDBC APIdata type maps.

JDBC API Data Typefrom java.sql.Types

Corresponding InformixData Type

BIGINT INT8

BINARY BYTE

BIT Not supported

(1 of 2)


Supported ResultSet.getXXX() Methods

Supported ResultSet.getXXX() MethodsUse the ResultSet.getXXX() methods to transfer data from an Informixdatabase to a Java program that uses the JDBC API to connect to an Informixdatabase. For example, use the ResultSet.getString() method to get the datastored in a column of data type LVARCHAR.

CHAR CHAR(n)

DATE DATE

DECIMAL DECIMAL

DOUBLE FLOAT

FLOAT SMALLFLOAT

INTEGER INTEGER

LONGVARBINARY BYTE

LONGVARCHAR TEXT

NUMERIC DECIMAL

REAL SMALLFLOAT

SMALLINT SMALLINT

TIME DATETIME

TIMESTAMP DATETIME

TINYINT SMALLINT

VARBINARY BYTE

VARCHAR VARCHAR(m,r)

JDBC API Data Typefrom java.sql.Types

Corresponding InformixData Type

(2 of 2)


Supported ResultSet.getXXX() Methods

The following table lists the ResultSet.getXXX() methods that Informix JDBCDriver supports. The top heading lists the standard JDBC API data typesdefined in the java.sql.Types class. These translate to specific Informix datatypes, as shown in the table on page 2-22. The left heading in the table liststhe getXXX() methods you can use to retrieve data of a particular JDBC APIdata type.

An uppercase and bold X indicates the getXXX() method Informix recom-mends you use; a lowercase x indicates other getXXX() methods supported byInformix JDBC Driver.

getXXX() Method

JDBC API Data Types from java.sql.Types

TINY

INT

SMAL

LINT

INTE

GER

BIGI

NT

REAL

FLOA

T

DOUB

LE

DECI

MAL

NUM

ERIC

BIT

CHAR

VARC

HAR

LONG

VARC

HAR

BINA

RY

VARB

INAR

Y

LONG

VARB

INAR

Y

DATE

TIM

E

TIM

ESTA

MP

getByte() X x x x x x x x x x1 x1

getShort() x X x x x x x x x x1 x1

getInt() x x X x x x x x x x1 x1

getLong() x x x X x x x x x x1 x1

getFloat() x x x x X x x x x x1 x1

getDouble() x x x x x X X x x x1 x1

getBigDecimal() x x x x x x x X X x x

getBoolean() x x x x x x x x x x x

getString() x x x x x x x x x X X x x x x x x x

getBytes() x X X x

getDate() x x X x

getTime() x x X x

getTimestamp() x x x X

(1 of 2)


Handling Errors

The getXXX() methods return a null value if the retrieved column value is anSQL null value.

Handling ErrorsUse the JDBC API SQLException class to handle errors in your Java program.The Informix-specific com.informix.jdbc.Message class can also be usedoutside a Java program to retrieve the Informix error text for a given errornumber.

getAsciiStream() X x x x

getUnicodeStream()

getBinaryStream() x x x X

getObject() x x x x x x x x x x x x2 x x x2 x x3 x

Notes:1 The column value must match the type of getXXX() exactly, or an SQLException is raised. If the columnvalue is not within the allowed value range, the getXXX() method raises an exception instead of convertingthe data type. For example, getByte(1) raises an SQLException if the column value is 1000.2 A byte array is returned.3 A Timestamp object is returned instead of a Time object.

getXXX() Method

JDBC API Data Types from java.sql.Types

TINY

INT

SMAL

LINT

INTE

GER

BIGI

NT

REAL

FLOA

T

DOUB

LE

DECI

MAL

NUM

ERIC

BIT

CHAR

VARC

HAR

LONG

VARC

HAR

BINA

RY

VARB

INAR

Y

LONG

VARB

INAR

Y

DATE

TIM

E

TIM

ESTA

MP

(2 of 2)


Using the SQLException Class

Using the SQLException ClassWhenever an error occurs from either Informix JDBC Driver or the databaseserver, an SQLException is raised. Use the following methods of the SQLEx-ception class to retrieve the text of the error message, the error code, and theSQLState:

■ getMessage()

Returns a description of the error. SQLException inherits this methodfrom the java.util.Throwable class.

■ getErrorCode()

Returns an integer value that corresponds to the Informix databaseserver or Informix JDBC Driver error code.

■ getSQLState()

Returns a string that describes the SQLState. The string follows theX/Open SQLState conventions.

All Informix JDBC Driver errors have error codes of the form -79XXX, such as-79708 Method can’t take null parameter.

For a list of Informix database server errors, refer to Informix Error Messages.You can find the on-line version of this guide at the following Web site:

http://www.informix.com/answers.


Retrieving Informix Error Message Text

The following example from the SimpleSelect.java program shows how touse the SQLException class to catch Informix JDBC Driver or database servererrors using a try-catch block:

try {

PreparedStatement pstmt = conn.prepareStatement("Select * from x where a = ?;"); pstmt.setInt(1, 11); ResultSet r = pstmt.executeQuery();

while(r.next()) { short i = r.getShort(1); System.out.println("Select: column a = " + i); } r.close(); pstmt.close(); }catch (SQLException e) { System.out.println("ERROR: Fetch statement failed: " + e.getMessage()); }

Retrieving Informix Error Message TextInformix provides the class com.informix.jdbc.Message for retrieving theInformix error message text based on the Informix error number. To use thisclass, call the Java interpreter java directly, passing it an Informix errornumber, as shown in the following example:

java com.informix.jdbc.Message 100

The example returns the message text for Informix error 100:

100: ISAM error: duplicate value for a record with unique key.

Handling TransactionsBy default, all new Connection objects are in autocommit mode. This meansthat a COMMIT statement is automatically executed after each statement thatis sent to the database server. To turn autocommit mode off for a connection,explicitly call the Connection.setAutoCommit(false) method.


Other Informix Extensions to the JDBC API

When autocommit mode is off, Informix JDBC Driver implicitly starts a newtransaction when the next statement is sent to the database server. This trans-action lasts until the user issues a COMMIT or ROLLBACK statement. If theuser has already started a transaction by executing setAutoCommit(false),and then calls setAutoCommit(false) again, the existing transction continuesunchanged. It is the responsibility of the Java program to explicitly terminatethe transaction by issuing either a COMMIT or a ROLLBACK statement beforeit drops the connection to the database or the database server.

If the Java program sets autocommit mode on while inside a transaction,Informix JDBC Driver rolls back the current transaction before it actually turnsautocommit mode on.

In a database that has been created with logging, if a COMMIT statement issent to the database server (either with the Connection.commit() method ordirectly with an SQL statement) and autocommit mode is on, the error -255: Not in transaction is returned by the database server because there iscurrently no user transaction started.

In a database created in ANSI mode, explicitly sending a COMMIT statementto the database server is a no-op. No error is returned because the databaseserver automatically starts a transaction before it executes the statement ifthere is no user transaction currently open. The COMMIT statement thereforejust commits an empty transaction.

Other Informix Extensions to the JDBC APIThis section describes the Informix-specific extensions to the JDBC API notalready covered in this guide. These extensions handle information that isspecific to Informix databases.

Another Informix extension, the com.informix.jdbc.Message class, is fullydescribed in “Handling Errors” on page 2-25.

Using the Informix SERIAL and SERIAL8 Data TypesInformix JDBC Driver provides support for the Informix SERIAL and SERIAL8data types via the methods getSerial() and getSerial8(), which are part of theimplementation of the java.sql.Statement interface.


Using the Informix SERIAL and SERIAL8 Data Types

Since the SERIAL and SERIAL8 data types do not have an obvious mapping toany JDBC API data types from the java.sql.Types class, you must importInformix-specific classes into your Java program to be able to handle SERIALand SERIAL8 table columns. To do this, add the following import line to yourJava program:

import com.informix.jdbc.*

Use the getSerial() and getSerial8() methods after an INSERT statement toreturn the serial value that was automatically inserted into the SERIAL orSERIAL8 column of a table, respectively. The methods return 0 if any of thefollowing conditions are true:

■ The last statement was not an INSERT statement.

■ The table being inserted into does not contain a SERIAL or SERIAL8column.

■ The INSERT statement has not executed yet.

If you execute the getSerial() or getSerial8() method after a CREATE TABLEstatement, the methods return 1 by default (assuming the new table includesa SERIAL or SERIAL8 column). If the table does not contain a SERIAL orSERIAL8 column, the methods return 0. If you assign a new serial startingnumber, the methods return that number.

You must cast the Statement or PreparedStatement object to IfxStatement,the Informix-specific implementation of the Statement interface, if you wantto use the getSerial() and getSerial8() methods. The following exampleshows how to perform the cast:

PreparedStatement pStmt = conn.prepareStatement ("INSERT INTO ... ");pStmt.executeUpdate()Integer serial_number = ((IfxStatement)pStmt).getSerial();

If you want to insert consecutive serial values into a column of data typeSERIAL or SERIAL8, specify a value of 0 for the SERIAL or SERIAL8 column inthe INSERT statement. When the column is set to 0, the database serverassigns the next highest value.

For more detailed information about the Informix SERIAL and SERIAL8 datatypes, refer to Informix Guide to SQL: Reference and Informix Guide to SQL:Syntax. You can find the on-line version of both of these guides at thefollowing Web site:



Obtaining Driver Version Information

Obtaining Driver Version InformationThere are two ways to obtain version information about Informix JDBCDriver: from your Java program or from the UNIX or Windows commandline. The command line method also allows you to obtain the serial numberyou provided when you installed the driver on your computer.

To get version information from your Java program

1. Import the Informix-specific package com.informix.jdbc.* into yourJava program by adding the following line to the import section:

import com.informix.jdbc.*;

2. Invoke the static method IfxDriver.getJDBCVersion(). This methodreturns a String object that contains the complete version of thecurrent Informix JDBC Driver.

An example of a version of Informix JDBC Driver is 1.22.JC1.

The IfxDriver.getJDBCVersion() method does not return the serialnumber you provided during installation of the driver.

Important: For Version 1.22 of Informix JDBC Driver, the JDBC API methodsDriver.getMajorVersion() and DatabaseMetaData.getDriverMajorVersion()always return the value 1. Similarly, the methods Driver.getMinorVersion() andDatabaseMetaData.getDriverMinorVersion() always return the value 22.

To get the version of Informix JDBC Driver from the command line, type thefollowing command at the UNIX shell prompt or the Windows commandprompt:

java com.informix.jdbc.Version

The command will also return the serial number you provided when youinstalled the driver. An example of a serial number is INF#J031093.


Informix JDBC Driver and Remote Method Invocation (RMI)

Informix JDBC Driver and Remote MethodInvocation (RMI)Informix JDBC Driver, like all JDBC drivers by definition, creates a directconnection to a database. Java applets, however, are commonly used on Webpages over the Internet, in which direct connections to a database cannot bemade. Firewalls and distributed databases also disallow direct connections.

Remote Method Invocation (RMI) allows you to create distributed Java-to-Java applications, in which methods of remote Java objects can be invokedfrom different hosts. Using RMI with JDBC solves the problem of not beingable to create direct database connections over the Internet and acrossfirewalls.

To use Informix JDBC Driver with RMI you must implement your own JDBCmethods. Typically you should implement at least the methods that open andclose connections to a remote database.

A detailed example that shows how to implement remote methods to openand close connections and send and receive database queries is provided inthe following Informix JDBC Driver example directory:

$JDBCLOCATION/demo/rmi ♦%JDBCLOCATION%\demo\rmi ♦

where JDBCLOCATION is the directory where you installed Informix JDBCDriver.

You can also use public-domain software, such as RmiJdbc, that providesremote implementations of all the java.sql.* interfaces.

For more detailed information on RMI, refer to the following Web site:

http://java.sun.com/products/jdk/1.1/docs/guide/rmi/index.html

Restrictions and LimitationsThe following JDBC API methods are not supported by Informix JDBC Driverand cannot be used in a Java program that connects to an Informix database:

UNIX

Windows


Restrictions and Limitations

■ Connection.setCatalog()

■ Connection.setReadOnly()

■ Connection.isReadOnly()

■ Statement.setMaxFieldSize()

■ Statement.setQueryTimeout()

■ Statement.cancel()

■ PreparedStatement.setUnicodeStream()

■ CallableStatement.registerOutParameter()

■ ResultSet.getUnicodeStream()

The following JDBC API methods behave differently than specified by theJavaSoft specification:

■ Statement.execute()

Method returns a single result set.

■ PreparedStatement.execute()


■ CallableStatement.execute()


■ ResultSetMetaData.getTableName()

Method always returns the value "".

■ ResultSetMetaData.getSchemaName()


■ ResultSetMetaData.getCatalogName()


■ ResultSetMetaData.isReadOnly()

Method always returns FALSE.

■ ResultSetMetaData.isWriteable()

Method always returns TRUE.

■ ResultSetMetaData.isDefinitelyWriteable()

Method always returns TRUE.


3Chapter

Troubleshooting

In This Chapter . . . . . . . . . . . . . . . . . . . . 3-3

Debugging Your JDBC API Program . . . . . . . . . . . . . 3-3Using the Debug Version of the Driver. . . . . . . . . . . 3-3Turning on Tracing . . . . . . . . . . . . . . . . . 3-4

Performance Issues . . . . . . . . . . . . . . . . . . . 3-6Using the FET_BUF_SIZE Environment Variable . . . . . . . 3-6Memory Management of TEXT and BYTE Data Types . . . . . 3-6Reducing Network Traffic . . . . . . . . . . . . . . . 3-7

Browser Security Issues . . . . . . . . . . . . . . . . . 3-8

3-2 Infor

In This ChapterThis chapter provides troubleshooting tips for Informix JDBC Driver. It coversthe following topics:

■ Debugging Your JDBC API Program

■ Performance Issues

■ Browser Security Issues

Debugging Your JDBC API ProgramIf your Java program contains JDBC API programming errors, you mightwant to use the debug version of Informix JDBC Driver, instead of theoptimized version, to try to find where the errors occur in your program.

Using the Debug Version of the DriverThe debug version of Informix JDBC Driver, called ifxjdbc-g.jar, is exactly thesame as the optimized version (called ifxjdbc.jar), except that it has beencompiled with the -g option instead of the -O option.

The difference in compilation options also means that the debug version ofInformix JDBC Driver has been embedded with tracing information. Whenyou use the debug version of the driver, you can turn on tracing and get abetter idea of what the JDBC API portion of your Java program is actuallydoing.

Troubleshooting 3-3

Turning on Tracing

For instructions on how to use the debug version of Informix JDBC Driver ina Java application or Java applet, refer to “Using the Driver in an Appli-cation” on page 1-12 or “Using the Driver in an Applet” on page 1-13,respectively.

Turning on TracingTrace output consists of the following two kinds of information:

■ General information from Informix JDBC Driver

■ Informix native SQLI protocol messages sent between your Javaprogram and the Informix database server

To turn on tracing, specify the environment variables TRACE, TRACEFILE,PROTOCOLTRACE, and PROTOCOLTRACEFILE in the database URL or theproperty list when you establish a connection to an Informix database ordatabase server.


Turning on Tracing

The following table describes the tracing environment variables.

The following example of a database URL specifies the highest level ofprotocol tracing and sets tracing output to the operating system file/tmp/trace.out:

String url = "jdbc:informix-sqli://123.45.67.89:1533:informixserver=myserver;user=rdtest;password=test;PROTOCOLTRACE=2;PROTOCOLTRACEFILE=/tmp/trace.out";

For more information on establishing a connection to an Informix databaseor database server using a database URL or a property list, refer to “Estab-lishing a Connection” on page 2-3.

Environment Variable Description

TRACE Traces general information from Informix JDBC Driver.

Can be set to one of the following levels:

■ 0. Tracing not enabled. This is the default value.

■ 1. Traces the entry and exit points of methods.

■ 2. Same as Level 1, plus generic error messages are alsotraced.

■ 3. Same as Level 2, plus data variables are also traced.

TRACEFILE Specifies the full pathname of the operating system file onthe client computer to which the TRACE messages arewritten.

PROTOCOLTRACE Traces the SQLI protocol messages sent between yourJava program and the Informix database server.

Can be set to the following levels:

■ 0. Protocol tracing not enabled. This is the defaultvalue.

■ 1. Traces message IDs.

■ 2. Same as Level 1, plus the data in the message packetsare also traced.

PROTOCOLTRACFILE Specifies the full pathname of the operating system file onthe client computer to which the PROTOCOLTRACEmessages are written.

Troubleshooting 3-5

Performance Issues

Performance IssuesThis section describes three issues that might affect the performance of yourqueries: the FET_BUF_SIZE environment variable, memory management ofthe Informix TEXT and BYTE data types, and reducing network traffic.

Using the FET_BUF_SIZE Environment VariableWhen a SELECT statement is sent from a Java program to an Informixdatabase, the returned rows, or tuples, are stored in a tuple buffer in InformixJDBC Driver. The default size of the tuple buffer is the larger of the returnedtuple size or 4096 bytes.

You can use the Informix FET_BUF_SIZE environment variable to override thedefault size of the tuple buffer. Increasing the size of the tuple buffer canreduce network traffic between your Java program and the database, oftenresulting in better performance of queries.

FET_BUF_SIZE can be set to any positive integer less than or equal to 32,767.If the FET_BUF_SIZE environment variable is set, and its value is larger thanthe default tuple buffer size, the tuple buffer size is set to the value ofFET_BUF_SIZE.

There are times, however, when increasing the size of the tuple buffer canactually degrade the performance of queries. This could happen if your Javaprogram has many active connections to a database or if the swap space onyour computer is limited. If this is true for your Java program or computer,you might not want to use the FET_BUF_SIZE environment variable toincrease the size of the tuple buffer.

For more information on setting Informix environment variables, see “Estab-lishing a Connection” on page 2-3.

Memory Management of TEXT and BYTE Data TypesInformix JDBC Driver fetches TEXT and BYTE data into two different locations,depending on the size of the data.


Reducing Network Traffic

If the TEXT or BYTE value is less than or equal to 1024 bytes, Informix JDBCDriver fetches the value into main memory. This improves the performanceof retrieving small simple large object data.

If, however, the TEXT or BYTE value is larger than 1024 bytes, Informix JDBCDriver first attempts to store the value in a file on the operating system. If thisattempt fails, the entire TEXT or BYTE value is fetched into main memory,regardless of its size. This ensures that values fetched from within a Javaapplet are retrieved correctly, even though browsers are usually unable towrite to the local operating system.

For programming information on how to use the TEXT and BYTE data typesin a Java program, refer to “Manipulating Informix BYTE and TEXT DataTypes” on page 2-14.

Reducing Network TrafficThe two environment variables OPTOFC and IFX_AUTOFREE can be used toreduce network traffic when you close Statement and ResultSet objects.

Set OPTOFC to 1 to specify that the ResultSet.close() method does not requirea network round-trip if all the qualifying rows have already been retrieved inthe client’s tuple buffer. The database server automatically closes the cursorafter all the rows have been retrieved.

Informix JDBC Driver might or might not have additional rows in the client’stuple buffer before the next ResultSet.next() method is called. Therefore,unless Informix JDBC Driver has received all rows from the database server,the ResultSet.close() method might still require a network round-trip whenOPTOFC is set to 1.

Set IFX_AUTOFREE to 1 to specify that the Statement.close() method does notrequire a network round-trip to free the server cursor resources if the cursorhas already been closed in the database server.

The database server automatically frees the cursor resources right after thecursor is closed, either explicitly by the ResultSet.close() method orimplicitly by the OPTOFC environment variable.

When the cursor resources have been freed, the cursor can no longer bereferenced.

Troubleshooting 3-7

Browser Security Issues

For examples of how to use the OPTOFC and IFX_AUTOFREE environmentvariables, see the autofree.java and optofc.java demo examples. In theseexamples, the variables are set with the Properties.put() method.

For more information on setting Informix environment variables, refer to“Establishing a Connection” on page 2-3.

Browser Security IssuesWhen you use the JDBC API in a Java applet, you can only connect to thecomputer that is running the Web server that originally delivered the applet.This limitation, along with other security limitations, is often referred to asJava’s sandbox.

The JDBC API code in the applet must reference the same computer as theWeb server in the URL passed to the DriverManager.getConnection()method. Any attempt to connect to an Informix database or database serveron a computer different from the computer that delivered the applet causes asecurity exception and results in an SQLException error similar to thefollowing message:

Attempt to connect to database server (production) failed.

This security limitation is imposed by the browser used to view the Javaapplet. The exception does not occur if you use the JavaSoft appletviewercommand to view the Java applet.

Informix recommends the following two strategies for handling thisbrowser-imposed security limitation; the best strategy depends on how youare planning to use your Java applet:

■ Put the Informix database server and the Web server on the samecomputer.

This is a good solution for intranet use, since putting the databaseserver and Web server on the same computer is not necessarily asecurity risk. This strategy, however, might be too risky for Internetuse.


Browser Security Issues

■ Use a multi-tier approach, such as RMI (Remote Method Invocation)or CORBA (Common Object Request Broker Architecture).

In this strategy, the middle-tier application server, instead of theclient computer running the browser, accesses the Informix databaseserver. The Informix database server does not need to run on themiddle-tier computer. The RMI server, however, must run on thesame computer that runs the Web server.

Other advantages of this strategy include:

❑ Client applications are smaller, resulting in faster download andpopup times.

❑ Network traffic might be reduced, depending on yourapplication.

❑ Business logic is centered in the middle-tier application server,which might be more secure for your business.

The disadvantages of this strategy include:

❑ Administration is more complex.

❑ Depending on your application, network traffic might increaseand performance might degrade.

For more information on RMI and CORBA, refer to the JavaSoft Website at:http://www.javasoft.com

Troubleshooting 3-9

AAppendix

Sample Code

This appendix contains the full text for most of the codeexamples provided or referred to in other chapters. The examplefiles are also included in the product.

The examples that do not use RMI are located in the directory$JDBCLOCATION/demo/basic, where JDBCLOCATION refers tothe directory where you installed Informix JDBC Driver.

The RMI example is located in the directory $JDBCLO-CATION/demo/rmi. There are many parts to this example, so thefull text is not provided in this appendix. A README file in thedemo directory explains how to execute the example.

Another set of examples are located in the directory $JDBCLO-CATION/demo/stores7. A README file in the demo directoryexplains the various demos and how to execute them.♦

The examples that do not use RMI are located in the directory%JDBCLOCATION%\demo\basic, where JDBCLOCATION refersto the directory where you installed Informix JDBC Driver.

The RMI example is located in the directory %JDBCLO-CATION%\demo\rmi. There are many parts to this example, sothe full text is not provided in this appendix. A README file inthe demo directory explains how to execute the example.

Another set of examples are located in the directory %JDBCLO-CATION%\demo\stores7. A README file in the demo directoryexplains the various demos and how to execute them. ♦

The following table displays the name of the Java program, abrief description of what the program does, and the page whereyou can find it.

UNIX

Windows

Demo Program Name Description Page

autofree.java Shows how to use the AUTOFREE environment variable. A-3

ByteType.java Shows how to insert into and select from a table thatcontains a column of data type BYTE.

A-7

CreateDB.java Creates a database called testDB. A-12

DBConnection.java Creates connections to both a database and a databaseserver.

A-14

DBMetaData.java Shows how to retrieve information about a database withthe DatabaseMetaData interface.

A-17

DropDB.java Drops a database called testDB. A-23

Interval.java Shows how to insert and select Informix interval data. A-25

MultiRowCall.java Shows how to return multiple rows in a stored procedurecall.

A-29

OptimizedSelect.java Shows how to use the FET_BUF_SIZE environmentvariable to adjust the Informix JDBC Driver tuple buffersize.

A-32

optofc.java Shows how to use the OPTOFC environment variable. A-36

PropertyConnection.java Shows how to specify connection environment variablesvia a property list.

A-40

RSMetaData.java Shows how to retrieve information about a result set withthe ResultSetMetaData interface.

A-43

SimpleCall.java Shows how to call a stored procedure. A-48

SimpleConnection.java Shows how to connect to a database or database server. A-52

SimpleSelect.java Shows how to send a simple SELECT query to thedatabase server.

A-54

TextType.java Shows how to insert into and select from a table thatcontains a column of data type TEXT.

A-58

A-2 Informix JDBC Driver Programmer’s Guide

autofree.java/*************************************************************************** * * Title: autofree.java * * Description: Show the differnce in the behavior when autofree is set * * Instructions to run the program * * 1. Use CreateDB to create the Database testdb if not already done. * java CreateDB 'jdbc:informix-sqli: * //emily:1533:informixserver=emily3;user=rdtest;password=test' * 2. Run the program with autofree set * java autofree * 'jdbc:informix-sqli://emily:1533:informixserver=emily3; * user=rdtest;password=test' * 3. Expected Result>>>With Autofree set no SQ_RELEASE is sent from the Client side test.URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test”Trying to insert data using Prepare Statement ...Retreaving records: age = 26 age = 27 age = 28 age = 29 age = 30 * If run against the debug build with the following appended * to the URL "protocoltrace=5;protocoltracefile=/tmp/sqli" * Then In the protocol trace file specified /tmp/sqli in * this case will show that SQ_RELEASE message * is not sent from the client side as part of the statement.close(). * Note: the protocol trace file is only generated with the debug build * *************************************************************************** */

import java.sql.*;import java.util.*;/* * OPTOFC is set. * AUTOFREE is set * Neither SQ_CLOSE nor SQ_RELEASE is sent */

public class autofree{

public static void main(String[] args) {

Sample Code A-3

if (args.length == 0) {

System.out.println("ERROR: connection URL must be provided in order torun the demo!”); return; }

String url = args[0]; Connection conn = null; Statement stmt = null;StringTokenizer st = new StringTokenizer(url, ":"); String token; String newUrl = "";

for (int i = 0; i < 4; ++i) { if (!st.hasMoreTokens()) { System.out.println("ERROR: incorrect URL format!"); return; } token = st.nextToken(); if (newUrl != "") newUrl += ":"; newUrl += token; }

newUrl += "/testDB";

while (st.hasMoreTokens()) { newUrl += ":" + st.nextToken(); }

String cmd=null;

String testName = "With Autofree set no SQ_RELEASE is sent from the Clientside”;

System.out.println(">>>" + testName + " test."); System.out.println("URL = \"" + newUrl + "\"");

try { Class.forName("com.informix.jdbc.IfxDriver"); } catch (Exception e) { System.out.println("ERROR: failed to load Informix JDBC driver."); }

try { Properties pr = new Properties(); pr.put("AUTOFREE","1");


conn = DriverManager.getConnection(newUrl, pr); } catch (SQLException e) { System.out.println("ERROR: failed to connect!"); } try { stmt = conn.createStatement(); stmt.executeUpdate("drop table tab1"); }catch (SQLException e){ }try { stmt = conn.createStatement(); stmt.executeUpdate("create table tab1(age int)"); } catch ( SQLException e) { System.out.println("Failed to create table ..." + e.getMessage());// e.printStackTrace(); }

System.out.println("Trying to insert data using Prepare Statement ..."); try { PreparedStatement pst = conn.prepareStatement("insert into tab1 values(?)”); int age = 25; for (int i = 0; i < 5 ; i++) { age = age + 1; pst.setInt (1, age); pst.executeUpdate(); } } catch (SQLException e) { System.out.println("Failed to Insert into tab: " + e.toString());// e.printStackTrace(); }

try { ResultSet r = stmt.executeQuery("select * from tab1"); int j;

System.out.println("Retreaving records: "); int n = 0; while(r.next()) { n++; int age1 = r.getInt(1); System.out.println(" age = " + age1); }

Sample Code A-5

r.close(); stmt.close(); } catch (SQLException e) { System.out.println("Select: Fetch statement failed: " + e.toString()); e.printStackTrace();

}

}

}


ByteType.java/*************************************************************************** * * Title: ByteType.java * * Description: Demo a byte dataType operation * * An example of running the program: * * java ByteType * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Simple text data type insert and fetch operation test. * URL = ":jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test” * Trying to insert data using Prepare Statement ... * Inserting data ... * * Reading data now ... * * * Result of row #1, size = 10 from getAsciiStream(1) .. * * 1234567890 * Trying to drop the table ... * * >>>End of Simple byte data type insert and fetch operation test. * *************************************************************************** */

import java.sql.*;import java.util.*;import java.math.BigDecimal ;import java.io.*;import java.lang.*;

public class ByteType { static Statement stmt; static PreparedStatement pstmt; static Connection conn = null;

public static void main(String[] args) { if (args.length == 0)

Sample Code A-7

{System.out.println("ERROR: connection URL must be provided in order to run

the demo!”); return; }

String url = args[0]; StringTokenizer st = new StringTokenizer(url, ":"); String token; String newUrl = "";

for (int i = 0; i < 4; ++i) {

if (!st.hasMoreTokens()) { System.out.println("ERROR: incorrect URL format!"); return; }

token = st.nextToken(); if (newUrl != "")

newUrl += ":"; newUrl += token; }


while (st.hasMoreTokens()) {

newUrl += ":" + st.nextToken(); }

String cmd=null;

String testName = "Simple byte data type insert and fetch operation";

System.out.println(">>>" + testName + " test.");System.out.println("URL = \"" + newUrl + "\"");


try { conn = DriverManager.getConnection(newUrl); }catch (SQLException e) { System.out.println("ERROR: failed to connect!"); }


try { stmt = conn.createStatement(); stmt.executeUpdate("drop table tab1"); } catch (SQLException e){ }

try{stmt = conn.createStatement();stmt.executeUpdate("create table tab1(col1 byte)");}

catch ( SQLException e) {

System.out.println("Failed to create table ..." + e.getMessage());// e.printStackTrace();

}

System.out.println("Trying to insert data using Prepare Statement ..."); try

{ pstmt = conn.prepareStatement("insert into tab1 values (?)");

} catch (SQLException e) { System.out.println("Failed to Insert into tab: " + e.toString());// e.printStackTrace(); }

File file = new File("data.dat"); int fileLength = (int) file.length();

InputStream value = null; FileInputStream fileinp = null;

int row = 0; String str = null; int rc = 0; ResultSet rs = null;

System.out.println("Inserting data ...\n"); try{ fileinp = new FileInputStream(file); value = (InputStream)fileinp; } catch (Exception e) {}

try { pstmt.setBinaryStream(1,value,10); //set 1st column } catch (SQLException e) { System.out.println("Unable to set parameter"); } set_execute();

System.out.println("Reading data now ...\n");

Sample Code A-9

try{stmt = conn.createStatement();rs = stmt.executeQuery("Select * from tab1");while( rs.next() ) { row++; value = rs.getBinaryStream(1);


} }

catch (Exception e) { }dispValue(value);

System.out.println("Trying to drop the table ...\n");try

{stmt = conn.createStatement();rc = stmt.executeUpdate("drop table tab1");}

catch ( SQLException e){ }

try{stmt.close();pstmt.close();conn.close();}

catch ( SQLException e){}

System.out.println(">>>End of " + testName + " test.");}

public static void set_execute(){

try { pstmt.executeUpdate();

} catch (SQLException e)

{System.out.println("Failed to Insert into tab: " + e.toString());

e.printStackTrace(); }

}public static void dispValue(InputStream in){

int size; byte buf; int count = 0; try {


size = in.available(); byte ary[] = new byte[size]; buf = (byte) in.read(); while(buf!=-1) { ary[count] = buf; count++; buf = (byte) in.read(); } System.out.println( new String(ary).trim()); } catch (Exception e) { System.out.println("Error occur during reading stream ... \n"); } }

}

Sample Code A-11

CreateDB.java/***************************************************************************** * Title: CreateDB.java * * Description: Demo how to create a database * * An example of running the program: * * java CreateDB * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Create Database test. * URL = "jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test” * >>>End of Create Database test. * *************************************************************************** */

import java.sql.*;import java.util.*;

public class CreateDB {




String url = args[0];Connection conn = null;

int rc;String cmd=null;

String testName = "Create Database";

System.out.println(">>>" + testName + " test.");System.out.println("URL = \"" + url + "\"");

try { Class.forName("com.informix.jdbc.IfxDriver"); }


catch (Exception e) { System.out.println("ERROR: failed to load Informix JDBC driver."); e.printStackTrace(); return; }

try { conn = DriverManager.getConnection(url); }catch (SQLException e) { System.out.println("ERROR: failed to connect!"); System.out.println("ERROR: " + e.getMessage()); e.printStackTrace(); return; }

try { Statement stmt = conn.createStatement(); cmd = "create database testDB;"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); e.printStackTrace(); return; }

try {

conn.close(); }catch (SQLException e) { System.out.println("ERROR: failed to close the connection!"); e.printStackTrace(); return; }

System.out.println(">>>End of " + testName + " test."); }}

Sample Code A-13

DBConnection.java/*************************************************************************** * * Title: DBConnection.java * * Description: Demo a connection to a database of a particular server * * An example of running the program: * * java DBConnection * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Database Connection Direct test. * URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test” * >>>End of Database Connection Direct test. * >>>Database Connection Indirect test. * URL = "jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test” * >>>End of Database Connection Indirect test. * *************************************************************************** */


public class DBConnection {





for (int i = 0; i < 4; ++i) {

if (!st.hasMoreTokens()) { System.out.println("ERROR: incorrect URL format!"); return;


} token = st.nextToken(); if (newUrl != "")






String testName = "Database Connection Direct";





try {

conn.close(); }catch (SQLException e) { System.out.println("ERROR: failed to close the connection!"); }

System.out.println(">>>End of " + testName + " test.");

Sample Code A-15

url = args[0];

testName = "Database Connection Indirect";

conn = null;




try { Statement stmt = conn.createStatement(); cmd = "database testDB;"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try {



}}


DBMetaData.java/*************************************************************************** * Title: DBMetaData.java * * Description: Demo a databasemetata operation * * An example of running the program: * * java DBMetaData * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * Expected result: * * >>>Simple databasemetadata operation test. * URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test” * number of columns 8 * procedure_catnull * procedure_schema, * procedure_name, * reserved1, * reserved2, * reserved3, * remarks, * procedure_type * * testDB, * <null>, * proc3, * <null>, * <null>, * <null>, * <null>, * 0 * * >>>End of Simple databasemetadata operation test. * *************************************************************************** */


public class DBMetaData {

public static void main(String[] args)

Sample Code A-17

{ if (args.length == 0)




for (int i = 0; i < 4; ++i) {







Connection conn = null; int rc;

String cmd=null;Statement stmt = null;

String testName = "Simple databasemetadata operation";



try { conn = DriverManager.getConnection(newUrl);


}catch (SQLException e) { System.out.println("ERROR: failed to connect!"); }

try {

ResultSet rs ; DatabaseMetaData dmd ;

stmt = conn.createStatement(); dmd = conn.getMetaData(); stmt.executeUpdate( "create procedure proc3( i integer ) " + "returning integer ; " + " define j integer ; " + " for j in ( 1 to 5 ) " + " let i = i + 1 ; " + " return i with resume ; " + " end for " + "end procedure" ) ; rs = dmd.getProcedures( null, null, "proc3" ) ; dispResult( rs ) ;

}catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try { stmt = conn.createStatement(); cmd = "drop procedure proc3"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try {


Sample Code A-19

System.out.println(">>>End of " + testName + " test."); }

public static void dispResult( ResultSet rs ) throws SQLException { int i ; int ncols ; ResultSetMetaData rsmd ; String s = null ; String comma = null ; byte [] blob ; int typ ; int blen ;

rsmd = rs.getMetaData() ; ncols = rsmd.getColumnCount() ;

System.out.println( "number of columns " + ncols ) ;

for( i=1; i<=ncols; ++i ) { if( i > 1 ) { if (i < ncols) comma = "," ; else comma = " "; } System.out.println((rsmd.getColumnLabel( i )).trim() + comma ) ; } System.out.println( "" ) ;

while( rs.next() ) { for( i=1; i<=ncols; ++i ) { // if( i > 1 ) System.out.println(", " ) ;

typ = rsmd.getColumnType( i ) ; //System.out.print( "typ " + typ + " " ) ;

switch( typ ) { case Types.CHAR: case Types.VARCHAR: case Types.LONGVARCHAR: s = rs.getString( i ) ; break ;

case Types.SMALLINT: short v = rs.getShort( i ) ; if( !rs.wasNull() ) s = "" + v ; break ;

case Types.INTEGER: int vi = rs.getInt( i ) ;


if( !rs.wasNull() ) s = "" + vi ; break ;

case Types.DOUBLE: double vd = rs.getDouble( i ) ; if( !rs.wasNull() ) s = "" + vd ; break ;

case Types.FLOAT: float vf = rs.getFloat( i ) ; if( !rs.wasNull() ) s = "" + vf ; break ;

case Types.DECIMAL: case Types.NUMERIC: BigDecimal vb = rs.getBigDecimal( i, 8 ) ; if( !rs.wasNull() ) s = vb.toString() ; break ;

case Types.DATE: java.sql.Date vt = rs.getDate( i ) ; if( !rs.wasNull() ) s = vt.toString() ; break ;

case Types.TIMESTAMP: Timestamp vs = rs.getTimestamp( i ) ; if( !rs.wasNull() ) s = vs.toString() ; break ;

case Types.LONGVARBINARY: //blen = ((VtiResultSet)rs).getBytesLength( i ) ; //System.out.print( blen + " " ) ; blob = rs.getBytes( i ) ; if( !rs.wasNull() ) s = "[blob length " + blob.length + "]" ; break ;

default: s = "" ;

} if( rs.wasNull() ) { if( i > 1 ) { if (i < ncols) comma = "," ; else comma = " "; } System.out.println("<null>" + comma ) ; } else {

Sample Code A-21

if (i < ncols) comma = "," ; else comma = " "; System.out.println(s.trim() + comma ) ; } } System.out.println( "" ) ; } }}


DropDB.java/*************************************************************************** * Title: DropDB.java * * Description: Demo how to drop a database * * An example of running the program: * * java DropDB * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * >>>Drop Database test. * URL = "jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test” * >>>End of Drop Database test. *************************************************************************** */


public class DropDB {




String url = args[0];Connection conn = null;String cmd=null;

int rc;

String testName = "Drop Database";



Sample Code A-23


try { Statement stmt = conn.createStatement(); cmd = "drop database testDB"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try {




Interval.java/*************************************************************************** * Title: Interval.java * * Description: Demo inserting and selecting Informix intervals * * An example of running the program: * * java Interval * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * Inserting and fetching Interval columns test. * * URL = "jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test” * * Create a table * Create table rowcount = 0 * * Insert an interval using a String host variable * Insert rowcount = 1 * * Select from intrvl_tab * Select: ym = 102-11 * Select: ds = 5 10:03:55 * * Test End * *************************************************************************** */

import java.sql.*;import java.util.*;import java.lang.*;

/* * Connect an existing database test db. Create a table and insert * and fetch an interval value. */public class Interval {


{ System.out.println("ERROR: connection URL must be provided in " +

"order to run the demo!"); return;

Sample Code A-25

}

String url = args[0]; StringTokenizer st = new StringTokenizer(url, ":"); String token; String newUrl = ""; String testName = "Inserting and fetching Interval columns";

for (int i = 0; i < 4; ++i) {







Connection conn = null;String cmd = null;Statement stmt = null;

System.out.println(testName + " test.");System.out.println("");System.out.println("URL = \"" + newUrl + "\"");

try { Class.forName("com.informix.jdbc.IfxDriver"); }catch (Exception e) { System.out.println("ERROR: failed to load Informix JDBC driver."); return; }

try { conn = DriverManager.getConnection(newUrl); }catch (SQLException e) { System.out.println("ERROR: failed to connect: " + e.toString()); return;

}

/* * Drop existing table (if any) */ try { stmt = conn.createStatement();

cmd = "drop table intrvl_tab"; stmt.executeUpdate(cmd); } catch (Exception e) { /* don't do anything if the table doesn't exist */ }

/* * Create a table with two interval columns */System.out.println("");System.out.println("Create a table");try { cmd = "create table intrvl_tab " +

"(ym interval year to month, ds interval day to second)";

int rowcount = stmt.executeUpdate(cmd); System.out.println("Create table rowcount = " + rowcount); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); return; }

/* * Insert an interval using a String host variable. */System.out.println("");System.out.println("Insert an interval using a String host variable");try { String ym = new String("102-11"); // 102 years and 11 months String ds = new String("5 10:03:55"); // 5 days 10 hours 3 minutes

// and 55 seconds cmd = "insert into intrvl_tab values (?, ?)"; PreparedStatement pstmt = conn.prepareStatement(cmd);

pstmt.setString(1, ym); pstmt.setString(2, ds);

int rowcount = pstmt.executeUpdate(); System.out.println("Insert rowcount = " + rowcount);

Sample Code A-27


/* * Now fetch the row back */System.out.println("");System.out.println("Select from intrvl_tab");try { cmd = "select * from intrvl_tab"; ResultSet rs = stmt.executeQuery(cmd);

String ym; String ds;

while(rs.next()) { ym = rs.getString(1); System.out.println(" Select: ym = " + ym);

ds = rs.getString(2); System.out.println(" Select: ds = " + ds); }


System.out.println("");System.out.println("Test End");

}

}


MultiRowCall.java/*************************************************************************** * * Title: MultiRowCall.java * * Description: Demo a procedure call with multiple return rows * * An example of running the program: * * java MultiRowCall * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * Expected result: * * >>>Multiple Return Row Procedure Call Statement test. * URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test” * Execute procedure proc2() returns: 1 * Execute procedure proc2() returns: 2 * Execute procedure proc2() returns: 3 * Execute procedure proc2() returns: 4 * Execute procedure proc2() returns: 5 * >>>End of Multiple Return Row Procedure Call Statement test. * *************************************************************************** */


public class MultiRowCall {





for (int i = 0; i < 4; ++i) {

if (!st.hasMoreTokens()) { System.out.println("ERROR: incorrect URL format!"); return;

Sample Code A-29

} token = st.nextToken(); if (newUrl != "")






String testName = "Multiple Return Row Procedure Call Statement";


String proc2 = "create procedure proc2( i integer ) " + "returning integer ; " + " define j integer ; " + " for j in ( 1 to 5 ) " + " let i = i + 1 ; " + " return i with resume ; " + " end for " + "end procedure";




try { Statement stmt = conn.createStatement();


rc = stmt.executeUpdate(proc2); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + proc2); System.out.println("ERROR: " + e.getMessage()); }

try { PreparedStatement pstmt = conn.prepareStatement("{call proc2(0)};"); ResultSet r = pstmt.executeQuery();

while (r.next()) { short i = r.getShort(1); System.out.println("Execute procedure proc2() returns: " + i); }

r.close(); pstmt.close();

} catch (SQLException e) { System.out.println("ERROR: Prepare \"call proc2\" failed: " +e.getErrorCode()); }

try { Statement stmt = conn.createStatement(); cmd = "drop procedure proc2"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try {



Sample Code A-31

OptimizedSelect.java/*************************************************************************** * Title: OptimizedSelect.java * * Description: Demo select statement with bigger fetch buffer * * An example of running the program: * * java OptimizedSelect * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Select statement with bigger (32k) fetch buffer test. * URL = "jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test;fet_buf_size=32000” * =============================== * Column 0: 0 * Column 0: TEST COL2 * Column 0: 1 * Column 0: TEST COL4 * Column 0: 2 * Column 0: TEST COL6 * =============================== * Column 1: 1 * Column 1: TEST COL2 * Column 1: 2 * Column 1: TEST COL4 * Column 1: 3 * Column 1: TEST COL6 * =============================== * Column 2: 2 * Column 2: TEST COL2 * Column 2: 3 * Column 2: TEST COL4 * Column 2: 4 * Column 2: TEST COL6 * =============================== * .... * =============================== * Column 998: 998 * Column 998: TEST COL2 * Column 998: 999 * Column 998: TEST COL4 * Column 998: 1000 * Column 998: TEST COL6 * =============================== * Column 999: 999 * Column 999: TEST COL2 * Column 999: 1000


* Column 999: TEST COL4 * Column 999: 1001 * Column 999: TEST COL6 * >>>End of Select statement with bigger (32k) fetch buffer test. * *************************************************************************** */

import java.sql.* ;import java.util.* ;

public class OptimizedSelect{ public static void main( String args[] ) { Connection conn =null; Statement sqlstmt =null; ResultSet rs =null; int i = 0;


if (args.length == 0) {

System.out.println("ERROR: connection URL must be provided in order to runthe demo!”);

return; }

String url = args[0]; url += ";fet_buf_size=32000";

String testName = "Select statement with bigger (32k) fetch buffer";




Sample Code A-33

try { Statement stmt = conn.createStatement(); cmd = "create database optdb;"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try { sqlstmt = conn.createStatement() ; sqlstmt.executeUpdate("create table t1(c1 integer, c2 char(100)," + " c3 integer, c4 char (100), c5 decimal, c6 char(500))");


{ System.out.println("ERROR: Create table t1 failed."); }

try { for (i=0; i < 1000; ++i) sqlstmt.executeUpdate("insert into t1 values(" + i +", \"TESTCOL2\”,” + (i+1) + ", \"TEST COL4\"," + (i+2) + ", \"TEST COL6\")");


{ System.out.println("ERROR: Insert failed at " + i); }

try { rs = sqlstmt.executeQuery( "select * from t1" ) ;

for (i = 0; rs.next(); ++i) { System.out.println("==============================="); System.out.println("Column " + i + ": " + rs.getInt(1)); System.out.println("Column " + i + ": " + rs.getString(2)); System.out.println("Column " + i + ": " + rs.getInt(3)); System.out.println("Column " + i + ": " + rs.getString(4));

System.out.println("Column " + i + ": " + rs.getBigDecimal(5, 0)); System.out.println("Column " + i + ": " + rs.getString(6));

} } catch( SQLException e ) {

System.out.println("ERROR: Select failed."); }


try { sqlstmt.executeUpdate("close database"); }

catch (SQLException e) { System.out.println("ERROR: Close datbase failed"); }

try { sqlstmt.executeUpdate("drop database optdb"); }

catch (SQLException e) { System.out.println("ERROR: Drop database failed"); }

try {



Sample Code A-35

optofc.java/*************************************************************************** * * Title: optofc.java * * Description: Show the differnce in the behavior when OPTOFC is set * * Instructions to run the program * * 1. Use CreateDB to create the Database testdb if not already done * java CreateDB 'jdbc:informix-sqli: * //emily:1533:informixserver=emily3;user=rdtest;password=test' * 2. Run the program * java optofc * 'jdbc:informix-sqli://emily:1533:informixserver=emily3; * user=rdtest;password=test' * 5. Expected Result * Data in the table>>>OPTOFC set close() followed by next() throws Exception no SQ_CLOSE sent fromthe client side test.URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test”Trying to insert data using Prepare Statement ...Retreaving records: Calling resultSet.next() = 26 Calling resultSet.next() = 27 Calling resultSet.next() = 28 Calling resultSet.next() = 29 Calling resultSet.next() = 30Calling resultSet.close()Calling resultSet.next()OPTOFC is set next after close throws SQLExceptionCursor not open. * *************************************************************************** */


/* * OPTOFC is set. * Calling rs.next() after calling rs.close() * should throw a SQL EXception */

public class optofc{

public static void main(String[] args)


{ if (args.length == 0) {

System.out.println("ERROR: connection URL must be provided in order torun the demo!”); return; }

String url = args[0]; Connection conn = null; Statement stmt = null; StringTokenizer st = new StringTokenizer(url, ":"); String token; String newUrl = "";

for (int i = 0; i < 4; ++i) { if (!st.hasMoreTokens()) { System.out.println("ERROR: incorrect URL format!"); return; } token = st.nextToken(); if (newUrl != "") newUrl += ":"; newUrl += token; }


while (st.hasMoreTokens()) { newUrl += ":" + st.nextToken(); }

String cmd=null;

String testName = "OPTOFC set close() followed by next() throws Exceptionno SQ_CLOSE sent from the client side”;

System.out.println(">>>" + testName + " test."); System.out.println("URL = \"" + newUrl + "\"");

try { Class.forName("com.informix.jdbc.IfxDriver"); } catch (Exception e) { System.out.println("ERROR: failed to load Informix JDBC driver."); }

try { Properties pr = new Properties();

Sample Code A-37

pr.put("OPTOFC","1"); conn = DriverManager.getConnection(newUrl, pr); } catch (SQLException e) { System.out.println("ERROR: failed to connect!"); } try { stmt = conn.createStatement(); stmt.executeUpdate("drop table tab1"); } catch (SQLException e){ }try { stmt = conn.createStatement(); stmt.executeUpdate("create table tab1(age int)"); } catch ( SQLException e) { System.out.println("Failed to create table ..." + e.getMessage());// e.printStackTrace(); }

System.out.println("Trying to insert data using Prepare Statement ..."); try { PreparedStatement pst = conn.prepareStatement("insert into tab1 values(?)”); int age = 25; for (int i = 0; i < 5 ; i++) { age = age + 1; pst.setInt (1, age); pst.executeUpdate(); } } catch (SQLException e) { System.out.println("Failed to Insert into tab: " + e.toString());// e.printStackTrace(); }

try { ResultSet r = stmt.executeQuery("select * from tab1"); int j;

System.out.println("Retreaving records: "); int n = 0; while(r.next()) { n++; int age1 = r.getInt(1); System.out.println(" Calling resultSet.next() = " + age1);


} System.out.println("Calling resultSet.close() ");

r.close(); System.out.println("Calling resultSet.next() "); boolean flag = r.next(); System.out.println ("This is the output if the OPTOFC is not set"); System.out.println ("next() after close() returns "+ flag); } catch (SQLException e) {

System.out.println ("OPTOFC is set next after close throws SQLException“); System.out.println(e.getMessage()); }

}

}

Sample Code A-39

PropertyConnection.java/*************************************************************************** * * Title: PropertyConnection.java * * Description: Demo a connection to a server using a property list * * java PropertyConnection * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Property Connection test. * URL = "jdbc:informix-sqli://emily:1533" * Properties = "{password=test, informixserver=emily3, user=rdtest}" * >>>End of Property Connection test. * *************************************************************************** */


public class PropertyConnection{ public static void main(String[] args) { if (args.length == 0)




for (int i = 0; i < 4; ++i) {





if (!st.hasMoreTokens()) {

System.out.println("ERROR: incorrect URL format!"); return; }

token = st.nextToken(); if (st.hasMoreTokens()) {


StringTokenizer st1 = new StringTokenizer(token, ";");

Properties prop = new Properties();

while (st1.hasMoreTokens()) {

int index; String t1 = st1.nextToken(); if ((index = t1.indexOf('=')) == -1 || (t1.indexOf('=') != t1.lastIndexOf('='))) {


prop.put(t1.substring(0, index), t1.substring(index+1)); }

String testName = "Property Connection";


System.out.println(">>>" + testName + " test.");System.out.println("URL = \"" + newUrl + "\"");System.out.println("Properties = \"" + prop.toString() + "\"");


try { conn = DriverManager.getConnection(newUrl,prop); }

Sample Code A-41

catch (SQLException e) { System.out.println("ERROR: failed to connect!"); }

try {



}}


RSMetaData.java/*************************************************************************** * * Title: RSMetaData.java * * Description: Demo a resultsetmetadata operation * * An example of running the program: * * java DBMetaData * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Simple resultsetmetadata operation test. * URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test” * table_cat * table_schem * table_name * column_name * data_type * type_name * column_size * buffer_length * decimal_digits * num_prec_radix * nullable * remarks * column_def * sql_data_type * sql_datetime_sub * char_octet_length * ordinal_position * testDB * * test1 * c1 * 4 * int * int * 0 * 0 * 0 * 0 * <null><null><null><null><null><null>testDB * * test1 * c2 * 8

Sample Code A-43

* double * double * 0 * 0 * 0 * 0 * <null><null><null><null><null><null>testDB * * test1 * c3 * 1 * char * char * 0 * 0 * 0 * 0 * <null><null><null><null><null><null>testDB * * test1 * c4 * 12 * varchar * varchar * 0 * 0 * 0 * 0 * <null><null><null><null><null><null> * >>>End of Simple resultsetmetadata operation test. * *************************************************************************** */


public class RSMetaData {




String url = args[0]; StringTokenizer st = new StringTokenizer(url, ":");


String token; String newUrl = "";

for (int i = 0; i < 4; ++i) {









String testName = "Simple resultsetmetadata operation";




try { Statement stmt1=conn.createStatement(); stmt1.executeUpdate("drop table test1");

Sample Code A-45

} catch (SQLException e){ }

try {

ResultSet rs ; DatabaseMetaData dmd ;

stmt = conn.createStatement(); dmd = conn.getMetaData(); stmt.executeUpdate ( "create table test1 (c1 integer, c2 float, c3 char(10), " + "c4 varchar(20) ) ") ; rs = dmd.getColumns( null, null, "test1" , "%" ) ; ResultSetMetaData rsmd = rs.getMetaData(); int ncols = rsmd.getColumnCount(); int i,type; String s = null; for (i = 1; i < ncols ; i++) { System.out.println(rsmd.getColumnLabel(i)); } while (rs.next()) { for (i = 1; i < ncols; i++) { type = rsmd.getColumnType(i); switch (type) { case Types.CHAR: case Types.VARCHAR: case Types.LONGVARCHAR: s = rs.getString(i); break; case Types.SMALLINT: short v1 = rs.getShort( i ) ; if( !rs.wasNull() ) s = "" + v1 ; break; case Types.FLOAT: float v2 = rs.getFloat( i ) ; if( !rs.wasNull() ) s = "" + v2 ; break; } if (rs.wasNull() ) { System.out.print( "<null>" ) ; } else { System.out.println( s.trim() ) ; } } }


}catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }System.out.println("\n>>>End of " + testName + " test.");

try { Statement stmt2 = conn.createStatement() ; stmt2.executeUpdate("drop table test1"); } catch (SQLException e){ } }

}

Sample Code A-47

SimpleCall.java/*************************************************************************** * Title: SimpleCall.java * * Description: Demo a simple procedure call statement * * An example of running the program: * * java SimpleCall * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Simple Procedure Call Statement test. * URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test” * Execute procedure proc1() returns: 3 * Escape call Procedure proc1() returns: 3 * >>>End of Simple Procedure Call Statement test. * *************************************************************************** */


public class SimpleCall {





for (int i = 0; i < 4; ++i) {








String testName = "Simple Procedure Call Statement";


String proc1 = "create procedure proc1() returning int;\n" +"define var1 int;\n" +"let var1 = 3;\n" + "return var1;\n" +"end procedure;";

int rc;String cmd=null;




try { Statement stmt = conn.createStatement(); rc = stmt.executeUpdate(proc1); stmt.close(); }catch (SQLException e) {

Sample Code A-49

System.out.println("ERROR: execution failed - statement: " + proc1); System.out.println("ERROR: " + e.getMessage()); }

try { PreparedStatement pstmt = conn.prepareStatement("execute procedureproc1();”); ResultSet r = pstmt.executeQuery();

if (r.next()) { short i = r.getShort(1); System.out.println("Execute procedure proc1() returns: " + i); }


} catch (SQLException e) { System.out.println("Prepare \"execute procedure\" failed: " +e.getErrorCode()); }

try { PreparedStatement pstmt = conn.prepareStatement("{call proc1()};"); ResultSet r = pstmt.executeQuery();

if (r.next()) { short i = r.getShort(1);

System.out.println("Escape call Procedure proc1() returns: " + i); }


} catch (SQLException e) { System.out.println("ERROR: Prepare \"escape call\" failed: " +e.getErrorCode()); }

try { Statement stmt = conn.createStatement(); cmd = "drop procedure proc1"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }


try {



Sample Code A-51

SimpleConnection.java/*************************************************************************** * * Title: SimpleConnection.java * * Description: Demo a connection to a server (no database specified) * * An example of running the program: * * java SimpleConnection * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Simple Connection test. * URL = "jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test” * >>>End of Simple Connection test. * *************************************************************************** */


public class SimpleConnection {




String url = args[0];

String testName = "Simple Connection";



try { Class.forName("com.informix.jdbc.IfxDriver"); }


catch (Exception e) { System.out.println("ERROR: failed to load Informix JDBC driver."); }


try {



Sample Code A-53

SimpleSelect.java/*************************************************************************** * Title: SimpleSelect.java * * Description: Demo a simple select operation * * An example of running the program: * * java SimpleSelect * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Simple Select Statement test. * URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test” * Select: column a = 11 * >>>End of Simple Select Statement test. * *************************************************************************** */


public class SimpleSelect {





for (int i = 0; i < 4; ++i) {


token = st.nextToken();


if (newUrl != "") newUrl += ":";

newUrl += token; }






String testName = "Simple Select Statement";




try { stmt = conn.createStatement(); cmd = "create table x (a smallint);"; rc = stmt.executeUpdate(cmd); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try {

Sample Code A-55

cmd = "insert into x values (11);"; rc = stmt.executeUpdate(cmd); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try { cmd = "insert into x values (22);"; rc = stmt.executeUpdate(cmd); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try {

PreparedStatement pstmt = conn.prepareStatement("Select * from x wherea = ?;”); pstmt.setInt(1, 11); ResultSet r = pstmt.executeQuery();

while(r.next()) { short i = r.getShort(1); System.out.println("Select: column a = " + i); }


} catch (SQLException e) {

System.out.println("ERROR: Fetch statement failed: " + e.getMessage()); }

try { cmd = "drop table x"; rc = stmt.executeUpdate(cmd); stmt.close(); }catch (SQLException e) { System.out.println("ERROR: execution failed - statement: " + cmd); System.out.println("ERROR: " + e.getMessage()); }

try {




Sample Code A-57

TextType.java/*************************************************************************** * * Title: TextType.java * * Description: Demo a textDataType operation * * An example of running the program: * * java TextType * 'jdbc:informix-sqli://emily:1533:informixserver=emily3;user=rdtest;password=test’ * * Expected result: * * >>>Simple text data type insert and fetch operation test. * URL = "jdbc:informix-sqli://emily:1533/testDB:informixserver=emily3;user=rdtest;password=test” * Trying to insert data using Prepare Statement ... * Inserting data ... * * Entering 1024 bytes of data to text/byte at column-1 * * Reading data now ... * * * Result of row #1, size = 1024 from getAsciiStream(1) .. * *123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 101-56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 201-56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 301-56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 401-56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 501-56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 601-56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 701-56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 801-


56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 901-56789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 * 1001-6789012345678901234 * Trying to drop the table ... * * >>>End of Simple text data type insert and fetch operation test. * *************************************************************************** */


public class TextType { static Statement stmt; static PreparedStatement pstmt; static Connection conn = null;





for (int i = 0; i < 4; ++i) {





Sample Code A-59



String cmd=null;

String testName = "Simple text data type insert and fetch operation";




try { stmt = conn.createStatement(); stmt.executeUpdate("drop table tab1"); } catch (SQLException e){ }

try{stmt = conn.createStatement();stmt.executeUpdate("create table tab1(col1 text)");}

catch ( SQLException e) {

System.out.println("Failed to create table ..." + e.getMessage());// e.printStackTrace();

}

System.out.println("Trying to insert data using Prepare Statement ..."); try

{ pstmt = conn.prepareStatement("insert into tab1 values (?)");

} catch (SQLException e) {


System.out.println("Failed to Insert into tab: " + e.toString());// e.printStackTrace(); }

File file = new File("data.dat"); int fileLength = (int) file.length();

InputStream value = null; int row = 0;

String str = null; int rc = 0; ResultSet rs = null;

System.out.println("Inserting data ...\n");

set_AsciiStream(1, file,1024); // set 1st column with 1024 byte Ascii set_execute();

System.out.println("Reading data now ...\n");try

{stmt = conn.createStatement();rs = stmt.executeQuery("Select * from tab1");while( rs.next() ) { row++; value = rs.getAsciiStream(1);


} }

catch (Exception e) { }dumpValue(value);

System.out.println("Trying to drop the table ...\n");try

{stmt = conn.createStatement();rc = stmt.executeUpdate("drop table tab1");}

catch ( SQLException e){ }

try{stmt.close();pstmt.close();conn.close();}

catch ( SQLException e){}

System.out.println(">>>End of " + testName + " test.");}

Sample Code A-61

public static void set_AsciiStream(int index, File file, int length){FileInputStream fin;System.out.println("Entering " + length + " bytes of data to text/byte at

column-”+index+” \n”);try { fin = new FileInputStream(file); pstmt.setAsciiStream(index , fin, length); }catch ( Exception e) { System.out.println("Failed to perform setAsciiStream: " + e.toString()); }

}public static void set_execute(){

try { pstmt.executeUpdate();


{System.out.println("Failed to Insert into tab: " + e.toString());

e.printStackTrace(); }

}public static void dumpValue(InputStream in){int size;byte buf;int count = 0;try

{size = in.available();byte ary[] = new byte[size];buf = (byte) in.read();while(buf!=-1)

{ary[count] = buf;count++;buf = (byte) in.read();}

System.out.println( new String(ary).trim());}

catch (Exception e){System.out.println("Error occur during reading stream ... \n");}

}}


Glossary

Glossary

applet A Java program that adheres to certain conventions that allow itto run within a Java-enabled browser.

appletviewer A JavaSoft command that allows you to run applets outside ofthe context of a Web browser.

autocommit Mode in which a COMMIT statement is automatically executedafter each statement sent to the database server.

blobspace A logical collection of chunks that is used to store TEXT and BYTEdata.

BYTE A built-in data type for a simple large object that stores any typeof binary data and can be as large as 231 bytes.

catalogs In Informix JDBC Driver, a list of all the Informix databaseswithin a particular database server.

class An encapsulated collection of data, and the methods that operateon the data. Classes are instantiated to produce objects.

CLASSPATH An environment variable that tells the Java virtual machine(JVM) and other applications where to find the Java class librariesused in a Java program.

commit An action that makes the changes to a database permanent andends a transaction.

connection An association between an application and a database environ-ment, created by a CONNECT or DATABASE statement. Databaseservers can also have connections to one another.

CORBA (Common Object Request Broker Architecture) The CORBA 2.0 specificationdescribes a convention called Object Request Broker (ORB), the infrastructurefor distributed-object computing. CORBA enables client applications to com-municate with remote objects and invoke operations statically or dynami-cally.

database URL URL passed to the DriverManager.getConnection() method that specifies thesubprotocol (the database connectivity mechanism), the database or databaseserver identifier, and a list of properties that can include Informix environ-ment variables.

dbspace A logical collection of one or more chunks of contiguous disk space withinwhich you store databases and tables. Because chunks represent specificregions of disk space, the creators of databases and tables can control wheretheir data is physically located by placing databases or tables in specificdbspaces. Large objects are stored in sbspaces.

debug version ofdriver

A version of Informix JDBC Driver that has been compiled with the -g optionused for debugging and tracing. The JAR file that contains the debug versionis named ifxjdbc-g.jar.

digital signature A string of bits that is computed from some data (the data being “signed”)and the private key of an entity. The signature can be used to verify that thedata came from the entity.

domain name The unique name that identifies an internet site, such as mysite.com.

exception A signal that some unexpected condition has occurred in a program.

interface A named collection of method definitions (without implementations). Aninterface can also include constant declarations.

IP address Unique ID of every computer on the Internet. The format consists of fournumerical strings separated by dots, such as 123.45.67.89.

jar JavaSoft utility to create Java archive files.

JDBC The JavaSoft specification of a standard application programming interface(API) that allows Java programs to access database management systems. TheJDBC API consists of a set of interfaces and classes written in the Javaprogramming language.

JDBC Driver An implementation of the JDBC API interfaces and classes for a particulardatabase vendor.


JDBC API The public and protected methods of all the public classes in the java.sqlpackage.

metadata Data about data. Metadata provides information about data in the databaseor used in the application. Metadata can be data attributes, such as name,size, and data type, or descriptive information about data.

method The object-oriented programming term for a function or a procedure.

optimizedversionof the driver

A version of Informix JDBC Driver that has been compiled with the -O optionfor optimal performance. The JAR file that contains the optimized version isnamed ifxjdbc.jar.

package A collection of related classes and interfaces that provides access protectionand name space management.

port number The port that a database server or Web server is listening on. In a database orWeb URL, the port number is listed right after the IP address or domain name.

RMI (Remote Method Invocation) A method for creating distributed Java-to-Javaapplications, in which the methods of remote Java objects can be invokedfrom other Java virtual machines, possibly on different hosts.

rollback An action that cancels the changes made to a database since the last COMMITstatement and ends the current transaction.

schema In Informix JDBC Driver, a list of all the Informix users who own tables.

SERIAL, SERIAL8 Informix data types that store sequential integers assigned automatically bythe database server when a row is inserted. A column of data type SERIALrequires four bytes of storage; a column of data type SERIAL8 requires eightbytes of storage.

signed applet An applet that contains a digital signature.

simple largeobject

A large object that is stored in a blobspace, is not recoverable, and does notobey transaction isolation modes. Simple large objects include TEXT andBYTE data types.

SLQState A variable set by the database server after it executes each SQL statement.

TEXT A built-in data type for a simple large object that stores text data and can beas large as 231 bytes.

Glossary 3

tuple buffer The section of Informix JDBC Driver memory that stores the retrieved rowsfrom a SELECT statement.

user name A user ID that must be valid on all computers involved in the client’s data-base access. Often referred to as the client’s user ID or login.

user password A user ID password that must be valid on all computers involved in the cli-ent’s database access. When the client specifies an explicit user ID, most com-puter systems require the user password to validate the user ID.


@

Index

O QCA B D E F G H I J K L M N P R S T U V W X Y Z

Index

AANSI compliance

level Intro-10APPLET tag 1-13Application server 3-9ARCHIVE attribute of APPLET

tag 1-13Autocommit 2-27AUTOFREE environment

variable A-2autofree.java example

program 3-8, A-2

BBrowsers 1-13, 3-8BYTE data type 2-14, 3-6ByteType.java example

program 2-16, 2-18, A-2

CCallableStatement interface 2-14cancel() method 2-32catalogs, Informix JDBC Driver

interpretation 2-14Classes

IfxDriver 2-4Message 2-27Properties 2-10SQLException 2-25, 2-27, 3-8Version 2-30

CLASSPATH environmentvariable 1-12

Class.forName() method 2-4

close() method 2-21Common Object Request Broker

Architecture (CORBA) 3-9Compliance with industry

standards Intro-10Connection interface 2-21, 2-27Connections

creating 2-4, 2-7establishing 2-3

Contents of Informix JDBCDriver 1-6

CreateDB.java exampleprogram A-2

Creating a connection 2-4, 2-7

DData types

BYTE 2-14, 3-6INTERVAL 2-19mapping between Informix and

JDBC API 2-22SERIAL 2-28SERIAL8 2-28TEXT 2-14, 3-6

DatabaseURL 2-5

Database server name, setting indatabase URLs 2-6

DatabaseMetaData interface 2-13,2-30

Databasesnames of, setting in database

URLs 2-6querying 2-14URL 2-5

@O QCA B D E F G H I J K L M N P R S T U V W X Y Z

DBANSIWARN environmentvariable 2-11

DBConnection.java exampleprogram 2-8, A-2

DBDATE environmentvariable 2-11

DBMetaData.java exampleprogram A-2

DBSPACETEMP environmentvariable 2-11

DBUPSPACE environmentvariable 2-11

Deallocating resources 2-21Debugging 3-3DELIMIDENT environment

variable 2-11Driver interface 2-30DriverManager interface 1-5, 2-4,

2-7, 2-10DropDB.java example

program A-2

EEnvironment variables

AUTOFREE A-2CLASSPATH 1-12DBANSIWARN 2-11DBDATE 2-11DBSPACETEMP 2-11DBUPSPACE 2-11DELIMIDENT 2-11FET_BUF_SIZE 2-11, 3-6, A-2IFX_AUTOFREE 2-11, 3-7INFORMIXCONRETRY 2-11INFORMIXOPCACHE 2-11INFORMIXSERVER 2-6, 2-7, 2-12INFORMIXSTACKSIZE 2-12NODEFDAC 2-12OPTCOMPIND 2-12OPTOFC 2-12, 3-7, A-2PATH 2-12PDQPRIORITY 2-12PLCONFIG 2-12PROTOCOLTRACE 3-4PROTOCOLTRACEFILE 3-4PSORT_DBTEMP 2-13PSORT_NPROCS 2-13

specifying 2-7, 2-9supported 2-10TRACE 3-4TRACEFILE 3-4USEV5SERVER 2-13

Errors 2-25, 2-26, 2-27Establishing a connection 2-3Examples

autofree.java 3-8, A-2ByteType.java 2-16, 2-18, A-2CreateDB.java A-2DBConnection.java 2-8, A-2DBMetaData.java A-2DropDB.java A-2Interval.java 2-19, A-2MultiRowCall.java A-2OptimizedSelect.java A-2optofc.java 2-10, 3-8, A-2PropertyConnection.java A-2RSMetaData.java A-2SimpleCall.java A-2SimpleConnection.java A-2SimpleSelect.java A-2TextType.java 2-17, 2-19, A-2

executeQuery() method 2-21executeUpdate() method 2-8, 2-17execute() method 2-21, 2-32

FFET_BUF_SIZE environment

variable 2-11, 3-6, A-2File interface 2-17FileInputStream interface 2-17

GgetCatalogName() method 2-32getCatalogs() method 2-14getConnection() method 2-4, 2-7,

2-10getErrorCode() method 2-26getJDBCVersion() method 2-30getMajorVersion() method 2-30getMessage() method 2-26getMinorVersion() method 2-30getSchemaName() method 2-32getSchemas() method 2-14

getSerial8() method 2-28getSerial() method 2-28getTableName() method 2-32getUnicodeStream() method 2-32getXXX() method 2-17, 2-22, 2-23

HHost names, setting in database

URLs 2-6

IIfxDriver class 2-4ifxjdbc-g.jar 1-6, 1-13, 3-3ifxjdbc.jar 1-6, 1-13IFX_AUTOFREE environment

variable 2-11, 3-7Industry standards, compliance

with Intro-10Informix JDBC Driver

contents of 1-6installing interactively 1-7installing silently 1-9loading 2-4overview of 1-6registering 2-4tracing 3-4uninstalling 1-11using debug version of 3-3using in an applet 1-13, 2-4using in an application 1-12

INFORMIXCONRETRYenvironment variable 2-11

INFORMIXOPCACHEenvironment variable 2-11

INFORMIXSERVER environmentvariable 2-6, 2-7, 2-12

INFORMIXSTACKSIZEenvironment variable 2-12

InputStream interface 2-15Installing Informix JDBC

Driver 1-7, 1-9Interfaces

CallableStatement 2-14Connection 2-21, 2-27DatabaseMetaData 2-13, 2-30Driver 2-30


O QCA B D E F G H I J K L M N P R S T U V W X Y Z @

DriverManager 1-5, 2-4, 2-7, 2-10File 2-17FileInputStream 2-17InputStream 2-15PreparedStatement 2-14, 2-15,

2-21ResultSet 2-14, 2-17, 2-21, 2-22,

2-23, 3-7ResultSetMetaData 2-14Statement 2-8, 2-14, 3-7Types 2-22, 2-29

INTERVAL data type 2-19Interval.java example

program 2-19, A-2IP address, setting in database

URL 2-6isDefinitelyWriteable()

method 2-32isReadOnly() method 2-32isWriteable() method 2-32

JJAR files

ifxjdbc-g.jar 1-6, 1-13, 3-3ifxjdbc.jar 1-6, 1-13

jar utility 1-13Java virtual machine (JVM) 1-12javac, Java compiler 1-6JavaSoft 1-3, 1-13JDBC API 1-3, 1-4JDBC driver, general 1-5

LLimitations and restrictions of

Informix JDBC Driver 2-31Loading Informix JDBC Driver 2-4

MMapping between Informix and

JDBC API data types 2-22Message class 2-27Metadata, accessing database 2-13Methods

cancel() 2-32

Class.forName() 2-4close() 2-21executeQuery() 2-21executeUpdate() 2-8, 2-17execute() 2-21, 2-32getCatalogName() 2-32getCatalogs() 2-14getConnection() 2-4, 2-7, 2-10getErrorCode() 2-26getJDBCVersion() 2-30getMajorVersion() 2-30getMessage() 2-26getMinorVersion() 2-30getSchemaName() 2-32getSchemas() 2-14getSerial8() 2-28getSerial() 2-28getTableName() 2-32getUnicodeStream() 2-32getXXX() 2-17, 2-22, 2-23isDefinitelyWriteable() 2-32isReadOnly() 2-32isWriteable() 2-32next() 2-22prepareStatement() 2-21put() 2-10registerDriver() 2-4registerOutParameter() 2-32setAsciiStream() 2-15setAutoCommit() 2-27setBinaryStream() 2-15setCatalog() 2-32setMaxFieldSize() 2-32setObject() 2-21setQueryTimeout() 2-32setReadOnly() 2-32setUnicodeStream() 2-32

MultiRowCall.java exampleprogram A-2

NName-value pairs of database

URL 2-7next() method 2-22NODEFDAC environment

variable 2-12

OODBC 1-5OPTCOMPIND environment

variable 2-12OptimizedSelect.java example

program A-2OPTOFC environment

variable 2-12, 3-7, A-2optofc.java example program 2-10,

3-8, A-2

PPasswords, setting in database

URL 2-7PATH environment variable 2-12PDQPRIORITY environment

variable 2-12Performance 3-6PLCONFIG environment

variable 2-12Port numbers, setting in database

URL 2-6PreparedStatement interface 2-14,

2-15, 2-21prepareStatement() method 2-21Properties class 2-10Property lists 2-10PropertyConnection.java example

program A-2PROTOCOLTRACE environment

variable 3-4PROTOCOLTRACEFILE

environment variable 3-4PSORT_DBTEMP environment

variable 2-13PSORT_NPROCS environment

variable 2-13put() method 2-10

QQuerying the database 2-14

Index 3

@O QCA B D E F G H I J K L M N P R S T U V W X Y Z

RregisterDriver() method 2-4Registering Informix JDBC

Driver 2-4registerOutParameter()

method 2-32Remote Method Invocation

(RMI) 2-31, 3-9Restrictions and limitations of

Informix JDBC Driver 2-31ResultSet interface 2-14, 2-17, 2-21,

2-22, 2-23, 3-7ResultSetMetaData interface 2-14Retrieving

database names 2-14Informix error message text 2-27user names 2-14version information 2-30

RMI 2-31RSMetaData.java example

program A-2

SSchemas, Informix JDBC Driver

interpretation 2-14Security issues 3-8SERIAL data type 2-28SERIAL8 data type 2-28setAsciiStream() method 2-15setAutoCommit() method 2-27setBinaryStream() method 2-15setCatalog() method 2-32setMaxFieldSize() method 2-32setObject() method 2-21setQueryTimeout() method 2-32setReadOnly() method 2-32Setting autocommit 2-27Setting properties 2-10Setting the CLASSPATH

environment variable 1-12setUnicodeStream() method 2-32setup.class class file 1-6, 1-7, 1-9,

1-10SimpleCall.java example

program A-2

SimpleConnection.java exampleprogram A-2

SimpleSelect.java exampleprogram A-2

Specifying environmentvariables 2-7, 2-9

SQLException class 2-25, 2-27, 3-8Statement interface 2-8, 2-14, 3-7Supported environment

variables 2-10Supported getXXX() methods 2-23Syntax of Database URL 2-5sysmaster database 2-13systables system table 2-14

TTEXT data type 2-14, 3-6TextType.java example

program 2-17, 2-19, A-2TRACE environment variable 3-4TRACEFILE environment

variable 3-4Tracing 3-4Transactions, handling 2-27Tuple buffer 2-11, 3-6Types interface 2-22, 2-29

UUninstalling Informix JDBC

Driver 1-11URLs, database 2-5User names, setting in database

URLs 2-7USEV5SERVER environment

variable 2-13Using debug version of Informix

JDBC Driver 3-3Using Informix JDBC Driver

in an applet 1-13, 2-4in an application 1-12

Using INFORMIX-OnLine 5.xdatabase servers 2-13

Using the Informix serial datatypes 2-28

Utilitiesjar 1-13

VVersion class 2-30Version, of Informix JDBC

Driver 2-30

XX/Open compliance level Intro-10


Documents

Informix JDBC Driverict.udlap.mx/.../docsAndothers/doc/release/jdbc4pg.pdf6 Informix JDBC Driver Programmer’s Guide Typographical Conventions Typographical Conventions This manual