bea weblogic - freie universität · 2000-04-03 · bea weblogic jdriver for informix. if you have...

BEA WebLogic Installing and Using WebLogic

D o c u m e n t 1 . 0A p r i l , 2 0 0 0

jDriver for Informix 5.1

Copyright

Copyright © 2000 BEA Systems, Inc. All Rights Reserved.

Restricted Rights Legend

This software and documentation is subject to and made available only pursuant to the terms of the BEA SystemsLicense Agreement and may be used or copied only in accordance with the terms of that agreement. It is againstthe law to copy the software except as specifically allowed in the agreement. This document may not, in whole orin part, be copied photocopied, reproduced, translated, or reduced to any electronic medium or machine readableform without prior consent, in writing, from BEA Systems, Inc.

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the BEA SystemsLicense Agreement and in subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights Clauseat FAR 52.227-19; subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause atDFARS 252.227-7013, subparagraph (d) of the Commercial Computer Software--Licensing clause at NASA FARsupplement 16-52.227-86; or their equivalent.

Information in this document is subject to change without notice and does not represent a commitment on the partof BEA Systems. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUTWARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OFMERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems DOESNOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THERESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS,ACCURACY, RELIABILITY, OR OTHERWISE.

Trademarks or Service Marks

BEA, WebLogic, ObjectBroker, TOP END, and TUXEDO are registered trademarks of BEA Systems, Inc. BEABuilder, BEA Connect, BEA Manager, BEA MessageQ, Jolt and M3 are trademarks of BEA Systems, Inc.

All other company names may be trademarks of the respective companies with which they are associated.

Installing and Using WebLogic jDriver for Informix

Document Edition Part Number Date Software Version

1.0 April 2000 WebLogic jDriver for Informix 5.1

Contents

About This DocumentWhat You Need to Know ......................................................................................1

e-docs Web Site.....................................................................................................1

How to Print the Document...................................................................................2

Related Information...............................................................................................2

Contact Us! ............................................................................................................2

Documentation Conventions .................................................................................3

1. Installing WebLogic jDriver for InformixOverview ...............................................................................................................7

Before you begin ...........................................................................................7Upgrade information ...............................................................................7

Evaluation licenses..................................................................................8

Installation steps .................................................................................................8Editing an entry to the XML license file......................................................10

Setting up a connection pool ........................................................................11

Configuring a connection pool with WebLogic Server ........................11

Using the connection pool in your application .....................................12

Verifying your connection to the Informix database ...................................13

Determining your database, hostname, and port ..........................................14

More resources ....................................................................................................15

Documentation .............................................................................................15

Applet programming ....................................................................................15

Code examples .............................................................................................15

2. Using WebLogic jDriver for InformixIntroduction .........................................................................................................17

Installing and Using WebLogic jDriver for Informix v

What’s in this document.............................................................................. 17

Mapping of types from Informix to WebLogic jDriver for Informix to Java18

Implementing with WebLogic jDriver for Informix .......................................... 20

Connecting to an Informix DBMS .............................................................. 20

Connection example............................................................................. 21

Other properties you can set for WebLogic jDriver for Informix ............... 22

Overview of data manipulation ................................................................... 23

Making a simple SQL query ................................................................ 23

Inserting, updating, and deleting records ............................................. 24

Creating and using stored procedures and functions............................ 25

Disconnecting and closing objects ....................................................... 27

Retrieving the SERIAL column after an insert ........................................... 28

Support for the Informix INTERVAL data type ......................................... 28

Using ResultSetMetaData methods............................................................. 30

Using autocommit mode.............................................................................. 30

Support for Informix-specific features ........................................................ 31

Retrieving VARCHAR/CHAR data as bytes....................................... 31

Codeset support ........................................................................................... 31

Using Unicode streams in a prepared statement.......................................... 32

What is currently supported in WebLogic jDriver for Informix ........................ 33

More Resources .................................................................................................. 37

Code examples............................................................................................. 37

3. Release Notes

vi Installing and Using WebLogic jDriver for Informix

What You Need to Know

About This Document

This document describes how to install and develop applications using WebLogicjDriver for Informix, BEA’s type-4 Java Database Connectivity (JDBC) driver for theInformix Database management system.

This document covers the following topics:

� Chapter 1, “Installing WebLogic jDriver for Informix.”.

� Chapter 2, “Using WebLogic jDriver for Informix.”

What You Need to Know

This document is intended mainly for application developers who are interested inbuilding applications requiring database access. It assumes a familiarity with SQL,general database concepts, and Java programming.

e-docs Web Site

BEA product documentation is available on the BEA corporate Web site. From theBEA Home page, click on Product Documentation or go directly to the “e-docs”Product Documentation page at http://e-docs.beasys.com.

Installing and Using WebLogic jDriver for Informix 1

How to Print the Document

You can print a copy of this document from Adobe Acrobat by using the File—>Printoption.

If you do not have the Adobe Acrobat Reader, you can download it for free from theAdobe Web site at http://www.adobe.com/.

Related Information

The most up-to-date version of this document, Installing and Using WebLogic jDriverfor Informix, is also available in HTML format on the BEA e-docs website.To accessthe online HTML version on the BEA website, use the following links:

Installing WebLogic jDriver for Informix:http://www.weblogic.com/docs51/techstart/install_jinf4.html

Using WebLogic jDriver for Informix:http://www.weblogic.com/docs51/classdocs/API_jinf4.html

You can view or print the PDF versions of these documents using Adobe Acrobat,version 3.0 or higher.

Complete documentation for WebLogic Server is available online athttp://www.weblogic.com/docs51/resources.html.

Contact Us!

Your feedback on the BEA WebLogic Enterprise documentation is important to us.Send us e-mail at [email protected] if you have questions or comments. Yourcomments will be reviewed directly by the BEA professionals who create and updatethe WebLogic jDriver for Informix documentation.

2 Installing and Using WebLogic jDriver for Informix

http://www.weblogic.com/docs51/classdocs/API_joci.html

http://www.weblogic.com/docs51/techstart/install_jinf4.html

Documentation Conventions

In your e-mail message, please indicate that you are using the documentation for theBEA WebLogic jDriver for Informix.

If you have any questions about this version of BEA WebLogic jDriver for Informix,or if you have problems installing and running BEA WebLogic jDriver for Informix,contact BEA Customer Support through BEA WebSupport at www.beasys.com. Youcan also contact Customer Support by using the contact information provided on theCustomer Support Card, which is included in the product package.

When contacting Customer Support, be prepared to provide the following information:

� Your name, e-mail address, phone number, and fax number

� Your company name and company address

� Your machine type and authorization codes

� The name and version of the product you are using

� A description of the problem and the content of pertinent error messages


The following documentation conventions are used throughout this document.

Convention Item

boldface text Indicates terms defined in the glossary.

Ctrl+Tab Indicates that you must press two or more keys simultaneously.

italics Indicates emphasis or book titles.


monospacetext

Indicates code samples, commands and their options, data structures andtheir members, data types, directories, and file names and their extensions.Monospace text also indicates text that you must enter from the keyboard.

Examples:

#include <iostream.h> void main ( ) the pointer psz

chmod u+w *

\tux\data\ap

.doc

tux.doc

BITMAP

float

monospaceboldfacetext

Identifies significant words in code.

Example:

void commit ( )

monospaceitalictext

Identifies variables in code.

Example:

String expr

UPPERCASETEXT

Indicates device names, environment variables, and logical operators.

Examples:

LPT1

SIGNON

OR

{ } Indicates a set of choices in a syntax line. The braces themselves shouldnever be typed.

[ ] Indicates optional items in a syntax line. The brackets themselves shouldnever be typed.

Example:

buildobjclient [-v] [-o name ] [-f file-list]...[-l file-list]...

| Separates mutually exclusive choices in a syntax line. The symbol itselfshould never be typed.

Convention Item



... Indicates one of the following in a command line:

� That an argument can be repeated several times in a command line

� That the statement omits additional optional arguments

� That you can enter additional parameters, values, or other information

The ellipsis itself should never be typed.

Example:

buildobjclient [-v] [-o name ] [-f file-list]...[-l file-list]...

.

.

.

Indicates the omission of items from a code example or from a syntax line.The vertical ellipsis itself should never be typed.

Convention Item


Overview

1 Installing WebLogic jDriver for Informix

Overview

WebLogic jDriver for Informix is a new name for the product previously referred to asjdbcKona/Informix4.

This document tells you how to install WebLogic jDriver for Informix, BEA’spure-Java Type 4 JDBC driver for Informix. WebLogic jDriver for Informix is a 100%pure Java implementation of the Java Database Connectivity (JDBC) API, the industrystandard for relational database access from Java clients. It provides Java clients,including applets, with direct access to the Informix database management system(DBMS). If you are using the driver with applets, then you must install the package onyour web server host, which must also host your Informix database.

Before you begin

Upgrade information

Note: If you are using WebLogic jDriver for Informix with WebLogic Server 4.5 orlater, you must also upgrade the driver for use with WebLogic Server. You candownload the driver from the BEA website athttp://www.weblogic.com/download/downloadkona.html.


http://www.weblogic.com/download/downloadkona.html


Evaluation licenses

The WebLogic jDriver for Informix distribution you downloaded from WebLogic’swebsite includes an evaluation license that allows you to test the product with 2 usersfor 30 days. To purchase additional licenses, contact [email protected].

Installation steps

1. Unpack the distribution.

If you have not already done so, unpack the zip file containing the WebLogicjDriver for Informix into the root directory of your computer. You must use aprogram such as WinZip at http://www.winzip.com that preserves the directorystructure of the archive. The files unpack into the weblogic directory.

The instructions in this document assume that you are installing WebLogicjDriver for Informix on a Windows computer and that you unpacked the archivein the root directory of your C drive. If you are installing on a different operatingsystem or in a different location, check your system documentation for help inadjusting the commands shown in these instructions for your own environment.

2. Add the WebLogic jDriver for Informix classes directory to yourCLASSPATH variable.

To change your CLASSPATH temporarily at a Windows Command Prompt, usethis command:

$ set CLASSPATH=%CLASSPATH%;c:\weblogic\informix4\classes

To change your CLASSPATH permanently:

a. Double-click the System icon in the Control Panel.

b. Click the Environment tab.

c. In the lower panel, select the CLASSPATH variable. If no CLASSPATHvariable is defined, add it.

d. Add c:\weblogic\informix4\classes to the value of the CLASSPATHvariable. Use a semicolon (;) to separate the new path from the previous valueof the variable, if any.


http://www.winzip.com

mailto:[email protected]

Installation steps

Any program you launch after you update the CLASSPATH variable in theSystem control panel will have access to the new value.

For more help setting your CLASSPATH, read Setting classpath athttp://www.weblogic.com/docs51/admindocs/classpath.html. If you are usingWebLogic jDriver for Informix from within an IDE like Symantec Cafe orJBuilder, the procedure for adding classes to the CLASSPATH may be different.

3. Install WebLogic jDriver for Informix for use with browser applets.

If you are planning to use WebLogic jDriver for Informix to access databases viaapplets in a web browser, you must install the distribution on the computerexecuting the web server. Furthermore, the web server and the Informix databaseserver must be running on the same computer. This is a security restrictionenforced by most web browsers, including Netscape Navigator and InternetExplorer. For information about browser security and applets, readTroubleshooting Applet Security problems athttp://www.weblogic.com/docs51/techsupport/appletsecurity.html.

The web server must also be able to find the WebLogic jDriver for Informixclass files. To ensure that the web server can find the files, install the WebLogicjDriver for Informix distribution on your web server computer and then set theCLASSPATH on that computer as described in Step 2. Be sure to restart the webserver after you change the CLASSPATH so that the web server has access tothe revised CLASSPATH value.

4. Install a license file.

With the release of version 5.1 of WebLogic jDriver for Informix, a new type oflicense is shipped with the distribution. This license uses an XML file to storethe license keys.

There are several issues to consider regarding your license for WebLogic jDriverfor Informix:

� If you downloaded an evaluation version of the driver, your distributionincludes an evaluation license. Your driver is ready for evaluation use.

� If you have previously purchased a license for WebLogic jDriver forInformix, you must obtain an updated license file from your BEA contactperson and place that license in your WebLogic jDriver for Informixinstallation. The procedure required to use the XML license differsdepending on whether you are using WebLogic jDriver for Informix as astandalone driver (without WebLogic Server), or as a two-tier driver fromwithin WebLogic Server (using the t3, Pool, JTS, or RMI multitier drivers).


http://www.weblogic.com/docs51/admindocs/classpath.html

http://www.weblogic.com/docs51/techsupport/appletsecurity.html


Standalone useCopy your license key into your WebLogicLicense.xml, file. Thisfile is located atweblogic/informix4/license/WebLogicLicense.xml (whereweblogic is the directory containing your WebLogic jDriver forInformix installation). For instructions on editing a WebLogic XMLlicense file, see Editing an entry to the XML license file, below.

Using with WebLogic ServerIf are using WebLogic jDriver for Informix as a middle tier JDBCdriver within WebLogic Server (via the Pool, JTS, t3, or RMImultitier drivers), copy your license key into the license file used byWebLogic Server. This file is located atweblogic/license/WebLogicLicense.xml (where weblogic isthe directory containing your WebLogic Server installation). Forinstructions on editing a WebLogic XML license file, see Editing anentry to the XML license file, below.

To purchase a permanent license for WebLogic jDriver for Informix, [email protected].

Editing an entry to the XML license file

1. Open the message containing the key(s) you received by email when youpurchased a license from BEA Systems, Inc.

2. Open the WebLogicLicense.xml file in a text editor. This file is located in oneof the following directories:

� standalone driver: weblogic/informix4/license

� using the driver with WebLogic Server: weblogic/license

(Where weblogic is the directory containing your WebLogic jDriver forInformix or WebLogic Server installation.)

Do not edit this file in Microsoft Word or any other word-processing programthat will save the file as a binary.

3. Copy the keys from the email and paste them at the top of the XML file.


mailto:[email protected]

Installation steps

For example, if you have received a key for clustering, it'll look something likethis:

<LICENSE PRODUCT="jdbcKona/Informix4"IP="000.000.900.900"UNITS="5"EXPIRATION="31-Mar-1999"KEY="w20f8s08480v0adpup43245paprtnp8ac"

/>

4. Save the WebLogicLicense.xml file into the same directory.

5. Save your license key information and a copy of your WebLogicLicense.xmlfile in a safe place outside the WebLogic distribution, preferably someplace youwill remember. Although no one else will be able to use your license keys, youshould probably save this information in a place protected from either maliciousor innocent tampering by others. Please note that when you upgrade yourWebLogic classes, you will want to keep your original WebLogicLicense.xmland add new keys to it for any new services you purchase.

Setting up a connection pool

If you are using WebLogic jDriver for Informix with either WebLogic Server orWebLogic Express, you can set up a pool of connections to your Informix DBMS thatwill be established when WebLogic Server is started. Since the connections are sharedamong users, these connection pools eliminate the overhead of opening a new databaseconnection for each user.

Your application then uses a multitier (Type-3) JDBC driver, such as the WebLogicPool, JTS or RMI driver to connect to WebLogic Server. WebLogic Server then usesWebLogic jDriver for Informix and one of the existing connections from the pool toconnect to the Informix database on behalf of your application.

Configuring a connection pool with WebLogic Server

1. Include the WebLogic jDriver for Informix classes in the WebLogic classpath usedto start WebLogic Server (specified with the weblogic.class.path property onthe command line). For more information on starting WebLogic Server, see Settingup and Starting WebLogic Server athttp://www.weblogic.com/docs51/install/startserver.html.


http://www.weblogic.com/docs51/install/startserver.html

http://www.weblogic.com/docs51/install/startserver.html


2. Add an entry to the weblogic.properties file specifying the connection poolproperties (driver name, url, server, password, ACLs, etc.). For example:

weblogic.jdbc.connectionPool.InfxPool=\url=jdbc:weblogic:informix4,\driver=weblogic.jdbc.informix4.Driver,\loginDelaySecs=1,\initialCapacity=4,\maxCapacity=10,\capacityIncrement=2,\allowShrinking=true,\shrinkPeriodMins=15,\refreshTestMinutes=10,\testTable=dual,\props=user=myUserName;password=secret;\

server=myDatabase@myDBServer:myPortNo

weblogic.allow.reserve.weblogic.jdbc.connectionPool.InfxPool=\guest,joe,jill

weblogic.allow.reset.weblogic.jdbc.connectionPool.InfxPool=\joe,jill

weblogic.allow.shrink.weblogic.jdbc.connectionPool.InfxPool=\joe,jill

For more information on setting properties for connection pools, see JDBCConnection Pools, athttp://www.weblogic.com/docs51/admindocs/properties.html#conpools, in theWebLogic Administrators guide Setting WebLogic Properties.

3. Start WebLogic Server.

Using the connection pool in your application

Client-side applications

To use a connection pool in a client-side application, establish the database connectionusing the WebLogic JDBC/RMI driver. For more information, see

� Using WebLogic JDBC/RMI and WebLogic Clustered JDBC athttp://www.weblogic.com/docs51/classdocs/JDBC_RMI.html.


http://www.weblogic.com/docs51/classdocs/JDBC_RMI.html

http://www.weblogic.com/docs51/admindocs/properties.html#conpools

http://www.weblogic.com/docs51/admindocs/properties.html#conpools

Installation steps

Server-side applications

To use a connection pool in a server-side application (such as a servlet), establish yourdatabase connection using the WebLogic pool or jts drivers. For more information,see:

� Using connection pools with server-side Java (in Using WebLogic HTTPServlets) at http://www.weblogic.com/docs51/classdocs/API_servlet.html#pools0

� Creating a startup connection pool athttp://www.weblogic.com/docs51/classdocs/API_jdbct3.html#startupconnpool

Verifying your connection to the Informix database

Check your connection to the Informix database. You need to have a username andpassword of a valid user, and you also need to know the database name, hostname, andport of your database (see Determining your database, hostname, and port on page 14).

Once you’ve collected that information, you can test your connection. The WebLogicdistribution includes a Java application to help you in setting up WebLogic jDriver forInformix. To use this helper app, make sure that thec:/weblogic/informix4/classes directory is in your CLASSPATH. At a commandline, type:

java utils.dbping INFORMIX4 user pass db@host:port

where:

user

The Informix username of a valid user for this database

pass

Password for the user

db@host:port

These three arguments together describe how to reach your Informixdatabase:


http://www.weblogic.com/docs51/classdocs/API_servlet.html#pools0

http://www.weblogic.com/docs51/classdocs/API_jdbct3.html#startupconnpool


db is the name of the database

host is the name of the computer on which the Informix server is running

port is the TCP/IP port number on which the Informix server is listening forconnection requests

Note the syntax of the command: the database name is followed by “@” (theat-sign), and the hostname and port are separated by a colon.

For more detailed instructions on how to verify your connection to a DBMS, seeTesting connections at http://www.weblogic.com/docs51/techstart/dbping.html.

Determining your database, hostname, and port

You need to know several details about your Informix server installation in order tomake a connection to it. These include:

� Name of the database you’ll be accessing

� Hostname of the computer on which the Informix server is running

� The TCP/IP port number on which the Informix server is listening forconnection requests

This may seem a little confusing because often people use the word “server” to meanboth the machine on which your database is running and the database instance itself.We’ll be clear in this document: the “hostname” is the name of the machine, and the“database name” is the name of the Informix instance.

To get information about the Informix server you want to connect to, look in$INFORMIXDIR/etc/sqlhosts and find the appropriate entry under the “SERVER”column. The entry in this file will tell you the hostname and servicename — located inthe far right column — for the connection. You only need to know the servicename tofind out the port number.

Then look in your /etc/services file (or, on Windows NT, in\Winnt\system32\drivers\etc\services) to find the port number associatedwith the servicename.


http://www.weblogic.com/docs51/techstart/dbping.html

More resources

More resources

Documentation

� API reference (http://www.weblogic.com/docs51/classdocs/packages.html)

� Using WebLogic jDriver for Informix(http://www.weblogic.com/docs51/classdocs/API_jinf4.html)

Applet programming

If you are planning to use WebLogic jDriver for Informix in an applet, you need toinstall the driver on your web server host. In addition, the web server and theInformix database must be located on the same machine. Because an applet mustcommunicate only with the host from which its classes were loaded, the Informixdatabase and the web server must be on the same IP host.

If you have questions about applet security issues, read Troubleshooting AppletSecurity problems athttp://www.weblogic.com/docs51/techsupport/appletsecurity.html.

For more information on applets, read Using WebLogic for applet programming athttp://www.weblogic.com/docs51/techdeploy/applets.html.

Code examples

We also ship a number of code examples in the distribution that will help you getstarted. Code examples are located in the weblogic/informix4/examples/directory in the distribution.


http://www.weblogic.com/docs51/classdocs/packages.html



http://www.weblogic.com/docs51/techdeploy/applets.html

http://www.weblogic.com/docs51/classdocs/API_jinf4.html

Introduction

2 Using WebLogic jDriver for Informix

Introduction

WebLogic jDriver for Informix is a new name for the product previously calledjdbcKona/Informix4.

What’s in this document

This document includes documentation on how to set up and use WebLogic jDriver forInformix (formerly known as FastForward from Connect Software, acquired in April1998). This database driver is a Type 4, pure-Java, two-tier driver. It requires noclient-side libraries since it connects to the database via the proprietary vendorprotocol at the wire-format level. Consequently, unlike Type 2, two-tier drivers, itmakes no “native” calls; it is written exclusively in Java.

A Type 4 driver is similar to a Type 2 driver in other ways, however. Both Type 2 andType 4 drivers are two-tier drivers; that means that each client requires an in-memorycopy of the driver to support its connection to the database.

WebLogic jDriver for Informix supports concurrent ResultSet execution; that is, youdon’t have to finish with and close one ResultSet on a Connection before you can openand work with another. However, the driver cannot support both concurrent ResultSetexecution and client-side caching.



WebLogic jDriver for Informix supports Informix OnLine versions 7.x and 9.x, with7.x data types plus the 9.x INT8 and SERIAL8 data types.

Before you begin working with WebLogic jDriver for Informix, make sure you haveinstalled the driver according to the installation instructions (athttp://www.weblogic.com/docs51/techstart/install_jinf4.html) and, in particular, thatyou know the port on which the database is listening for connection requests.

Mapping of types from Informix to WebLogic jDriver for Informix to Java

Informix WebLogic jDriverfor Informix

Java type

Byte Binary use java.io.InputStream

Char Char java.lang.String

Date Date java.sql.Date

Datetime Timestamp java.sql.Timestamp

Decimal Decimal java.math.BigDecimal

Float Decimal java.math.BigDecimal

Integer Integer java.lang.Integer

Integer8 Long java.lang.BigInt

Interval InformixInterval Literal string in Informix

Money Decimal java.math.BigDecimal

NChar Char java.lang.String

NVarchar Varchar java.lang.String

Serial Integer java.lang.Integer

Serial8 Long java.lang.BigInt

Smallfloat Decimal java.math.BigDecimal

Smallint Smallint java.lang.Integer


http://www.weblogic.com/docs51/techstart/install_jinf4.html

Introduction

Text Longvarchar use java.io.InputStream

Varchar Varchar java.lang.String

Informix WebLogic jDriverfor Informix

Java type



Implementing with WebLogic jDriver for Informix

Connecting to an Informix DBMS

The following steps tell you how to set up your application to connect to Informixusing WebLogic jDriver for Informix. In general, connecting happens in three steps:

1. Load the JDBC driver by calling Class.forName().newInstance() with thefull class name of the WebLogic jDriver for Informix JDBC driver class, andcasting it to a java.sql.Driver object. This procedure properly loads andregisters the JDBC driver. For example:

Driver myDriver = (Driver)Class.forName("weblogic.jdbc.informix4.Driver").newInstance();

2. Create a java.util.Properties object describing the connection. This objectcontains name-value pairs containing information such as user name, password,database name, server name, and port number. For example:

Properties props = new Properties();props.put("user", "scott");props.put("password", "secret");props.put("db", "myDB");props.put("server", "myHost");props.put("port", "8659");

3. Create a JDBC Connection object, which becomes an integral piece in yourJDBC operations, by calling the Driver.connect() method, which takes as itsparameters the URL of the driver and the java.util.Properties object youcreated in step 2. For example:

Connection conn =myDriver.connect("jdbc:weblogic:informix4", props);

In steps 1 and 3, you are describing the JDBC driver: in the first step, you use the fullpackage name of the driver. Note that it is dot-delimited. In the third step, you identifythe driver with its URL, which is colon-delimited. The URL must include at leastweblogic:jdbc:informix4, and may include other information, including the server hostname and the database name.



Connection example

This example shows how to use a Properties object to connect to a database named“myDB” on a server named “myHost”:

Properties props = new Properties();props.put("user", "scott");props.put("password", "secret");props.put("db", "myDB");props.put("server", "myHost");props.put("port", "8659");



You can combine the “db”, “server”, and “port” properties into one “server” property,as in this example:

Properties props = new Properties();props.put("user", "scott");props.put("password", "secret");props.put("server", "myDB@myHost:8659");



There are any number of variations on supplying information in the URL or in theProperties object. Whatever information you pass in the URL of the driver, you don’tneed to include in the Properties object. For more information, see Using URLs to setproperties for a JDBC connection athttp://www.weblogic.com/docs51/classdocs/urls.html.


http://www.weblogic.com/docs51/classdocs/urls.html




Other properties you can set for WebLogic jDriver for Informix

There are other Informix-specific properties that you can set in the connection URL orProperties object. These properties give you more control over an Informix-specificenvironment. For more information on these variables, please refer to your Informixdocumentation.

weblogic.informix4.login_timeout_secs=seconds_to_wait

When an attempt to log into an Informix server times out, WebLogic jDriverfor Informix returns an SQLException. By default, the driver waits 90seconds before it times out. You can modify the timeout period by setting thisproperty to the number of seconds you want to wait before returning anSQLException.

weblogic.informix4.delimited_identifiers=y

The Informix environment variable DELIMIDENT is used to enable and disableANSI SQL Delimited Identifiers. In older versions before the WebLogicacquisition, this feature was permanently set on (“y”). The default is now off(“n”).

weblogic.informix4.db_money=currency

The Informix environment variable DBMONEY is used to set the display of thecurrency symbol. In older versions before the WebLogic acquisition, “$.”was hard-coded as the value for this variable. The default value is now “$.”which can be overridden with this property.

weblogic.informix4.db_date=dateformat

The Informix environment variable DBDATE allows a user to specify the inputformat of dates. It sets the Informix DBDATE environment variable at login.The default value is “Y4MD”. Two-digit years (formats containing Y2) arenot supported by the driver. Note that this variable cannot be used to correctlyformat a date obtained from a ResultSet.getString() statement. Instead,use ResultSet.getDate() to obtain a java.util.Date object and thenformat the date in your code.

Here is an example of these properties used in a URL. Note that the URL is alwaysused as a single line but has been broken here for simplicity.

jdbc:weblogic:informix4:mydb@host:1493?weblogic.informix4.delimited_identifiers=y



&weblogic.informix4.db_money=DM&weblogic.informix4.db_date=Y4MD

Note the use of “?” and “&”, which are special characters for URLs. For more on usingURLs with WebLogic, read the Developers Guide, Using URLs to set properties for aJDBC Connection.

Here’s how these properties might be used with a Properties object:

Properties props = new Properties();props.put("user", "scott");props.put("password", "tiger");props.put("weblogic.informix4.delimited_identifiers", "y");props.put("weblogic.informix4.db_money", "DM");

Connection conn = myDriver.connect(jdbc:weblogic:informix4:myDB@myHost:8659",props);

Overview of data manipulation

This section provides an overview of the basic steps for executing SQL data queries,making inserts and updates, using stored procedures, and using callable statements.These steps follow basic JDBC methodology and are intended as a brief introductionto data manipulation with JDBC. For additional information, you should consult yourInformix documentation as well as Java-oriented texts discussing JDBC. You may alsowish to consult JavaSoft’s JDBC tutorial athttp://java.sun.com/docs/books/tutorial/jdbc/index.html.

Making a simple SQL query

The most fundamental task in database access is to retrieve data. With jdbcKona, thisis a three-step process:

1. Create a Statement to send a SQL query to the DBMS

2. Execute the Statement

3. Retrieve the results into a ResultSet. In this example, we execute a simple queryon the Employee table (alias “emp”) and display data from three of the columns.We also access and display metadata about the table from which the data wasretrieved. Note that we close the Statement at the end.




http://java.sun.com/docs/books/tutorial/jdbc/index.html


Statement stmt = conn.createStatement();stmt.execute("select * from emp");ResultSet rs = stmt.getResultSet();

while (rs.next()) {System.out.println(rs.getString("empid") + " - " +

rs.getString("name") + " - " +rs.getString("dept"));

}

ResultSetMetaData md = rs.getMetaData();

System.out.println("Number of columns: " +md.getColumnCount());

for (int i = 1; i

Inserting, updating, and deleting records

We illustrate three common database tasks in this step: inserting, updating, anddeleting records from a database table. We use a JDBC PreparedStatement for theseoperations; we create the PreparedStatement, then execute it and close it.

A PreparedStatement (subclassed from JDBC Statement) allows you to execute thesame SQL over and over again with different values. PreparedStatements use theJDBC “?” syntax.

String inssql ="insert into emp(empid, name, dept) values (?, ?, ?)";

PreparedStatement pstmt = conn.prepareStatement(inssql);

for (int i = 0; i

We also use a PreparedStatement to update records. In this example, we add the valueof the counter “i” to the current value of the “dept” field.

String updsql ="update emp set dept = dept + ? where empid = ?";

PreparedStatement pstmt2 = conn.prepareStatement(updsql);

for (int i = 0; i

Finally, we use a PreparedStatement to delete the records that we added and thenupdated.

String delsql = "delete from emp where empid = ?";PreparedStatement pstmt3 = conn.prepareStatement(delsql);



for (int i = 0; i

Creating and using stored procedures and functions

You can use WebLogic jDriver for Informix to create, use, and drop stored proceduresand functions. First, we execute a series of Statements to drop a set of storedprocedures and functions from the database.

Statement stmt = conn.createStatement();try {stmt.execute("drop procedure proc_squareInt");}catch (SQLException e) {;}try {stmt.execute("drop procedure func_squareInt");}catch (SQLException e) {;}try {stmt.execute("drop procedure proc_getresults");}catch (SQLException e) {;}stmt.close();

We use a JDBC Statement to create a stored procedure or function, and then we use aJDBC CallableStatement (subclassed from Statement) with the JDBC “?” syntax to setIN and OUT parameters.

Stored procedure input parameters are mapped to JDBC IN parameters, using theCallableStatement.setXXX() methods, like setInt(), and the JDBCPreparedStatement “?” syntax. Stored procedure output parameters are mapped toJDBC OUT parameters, using the CallableStatement.registerOutParameter()methods and JDBC PreparedStatement “?” syntax. A parameter may be both IN andOUT, which requires both a setXXX() and a registerOutParameter() call to bedone on the same parameter number.

In this example, we use a JDBC Statement to create a stored procedure, then weexecute the stored procedure with a CallableStatement. We use theregisterOutParameter() method to set an output parameter for the squared value.

Statement stmt1 = conn.createStatement();stmt1.execute

("CREATE OR REPLACE PROCEDURE proc_squareInt " +"(field1 IN OUT INTEGER, field2 OUT INTEGER) IS " +"BEGIN field2 := field1 * field1; field1 := " +"field1 * field1; END proc_squareInt;");

stmt1.close();

String sql = "{call proc_squareInt(?, ?)}";CallableStatement cstmt1 = conn.prepareCall(sql);



// Register out parameterscstmt1.registerOutParameter(2, java.sql.Types.INTEGER);for (int i = 0; i

In the next example, we use similar code to create and execute a stored function thatsquares an integer.

Statement stmt2 = conn.createStatement();stmt2.execute("CREATE OR REPLACE FUNCTION func_squareInt " +

"(field1 IN INTEGER) RETURN INTEGER IS " +"BEGIN return field1 * field1; " +

"END func_squareInt;");stmt2.close();

sql = "{ ? = call func_squareInt(?)}";CallableStatement cstmt2 = conn.prepareCall(sql);

cstmt2.registerOutParameter(1, Types.INTEGER);for (int i = 0; i

This next example uses a stored procedure named sp_getmessages (the code for thisstored procedure is not included with this example) named sp_getmessages, whichtakes a message number as an input parameter and returns the message text in aResultSet as an output parameter. Note that you must process all ResultSets returnedby a stored procedure using the Statement.execute() andStatement.getResult() methods before OUT parameters and return status areavailable.

First, we set up the three parameters to the CallableStatement:

1. Parameter 1 (output only) is the stored procedure return value

2. Parameter 2 (input only) is the msgno argument to sp_getmessage

3. Parameter 3 (output only) is the message text return for the message number

String sql = "{ ? = call sp_getmessage(?, ?)}";CallableStatement stmt = conn.prepareCall(sql);

stmt.registerOutParameter(1, java.sql.Types.INTEGER);stmt.setInt(2, 18000); // msgno 18000stmt.registerOutParameter(3, java.sql.Types.VARCHAR);

We execute the stored procedure and check the return value to see if the ResultSet isempty. If it is not, we use a loop to retrieve and display its contents.



boolean hasResultSet = stmt.execute();while (true){

ResultSet rs = stmt.getResultSet();int updateCount = stmt.getUpdateCount();if (rs == null && updateCount == -1) // no more resultsbreak;

if (rs != null) {// Process the ResultSet until it is emptywhile (rs.next()) {System.out.println("Get first col by id:" + rs.getString(1));

}} else {// we have an update countSystem.out.println("Update count = " +stmt.getUpdateCount());

}stmt.getMoreResults();

}

Once we have finished processing the ResultSet, the OUT parameters and returnstatus are available.

int retstat = stmt.getInt(1);String msg = stmt.getString(3);

System.out.println("sp_getmessage: status = " +retstat + " msg = " + msg);

stmt.close();

Disconnecting and closing objects

There are occasions on which you will want to call the commit() method to commitchanges you have made to the database before you close the connection.

When autocommit is set to true (the default JDBC transaction mode) each SQLstatement is its own transaction. After we created the Connection for these examples,however, we set autocommit to false; in this mode, the Connection always has animplicit transaction associated with it, and any call to the rollback() or commit()methods will end the current transaction and start a new one. Calling commit() beforeclose() ensures that all of the transactions are completed before closing theConnection.



Just as you close Statements, PreparedStatements, and CallableStatements when youhave finished working with them, you should always call the close() method on theconnection as final cleanup in your application, in a try {} block, and you shouldcatch exceptions and deal with them appropriately. The final two lines of this exampleinclude a call to commit and then a call to close the connection.

conn.commit();conn.close();

Retrieving the SERIAL column after an insert

weblogic.jdbc.informix4.Statement

You can obtain serial values after an insert by using theStatement.getSerialNumber() method, a WebLogic extension to JDBC inWebLogic jDriver for Informix. This allows you to track the index order of rows asyou add them to the table. Note that you must create the table with a SERIAL column.

To use this extension, you’ll need to explicitly cast your Statement object toweblogic.jdbc.informix4.Statement.

Here’s a simple code example that illustrates how to use the getSerialNumber()method.

weblogic.jdbc.informix4.Statement stmt =(weblogic.jdbc.informix4.Statement)conn.createStatement();

String sql = "CREATE TABLE test ( s SERIAL, count INT )";stmt.executeUpdate(sql);

for (int i = 100; i

Support for the Informix INTERVAL data type

To use the Informix INTERVAL data type, importweblogic.jdbc.common.InformixInterval and cast your objects toweblogic.jdbc.common.InformixInterval.



Use a literal string in the Informix INTERVAL format to enter an INTERVAL valuein a SQL statement. Use preparedStatement.setString() to set an INTERVALvalue parameter in a prepared statement. For retrieving INTERVAL data from anInformix server, WebLogic jDriver for Informix supports three standard API methodson a ResultSet:

� ResultSet.getString() returns a String representation of the interval in thestandard Informix format. Returns null if the interval is null.

� ResultSet.getBytes() returns the actual bytes the server returns to representthe interval.

� ResultSet.getObject() returns an object of typeweblogic.jdbc.common.InformixInterval. Returns null if the interval isnull.

The InformixInterval interface provides the following public methods:

String getString() throws SQLException

Identical to ResultSet.getString()

int getYear() throws SQLException

Returns the signed year of the INTERVAL, zero if YEAR is not defined

int getMonth() throws SQLException

Returns the signed year of the interval, zero if MONTH is not defined

int getDay() throws SQLException

Returns the signed day of the interval, zero if DAY is not defined

int getHour() throws SQLException

Returns the signed hour of the interval, zero if HOUR is not defined

int getMinute() throws SQLException

Returns the signed minute of the interval, zero if MINUTE is not defined

int getSecond() throws SQLException

Returns the signed second of the interval, zero if SECOND is not defined

int getFraction() throws SQLException

Returns the actual value of the FRACTION times 10**5



Using ResultSetMetaData methods

The metadata the Informix server returns with query results is available viaResultSetMetaData methods. However, the Informix server does not returninformation for the following:

getSchemaName(int)

getTableName(int)getCatalogName(int)

Using autocommit mode

Unlike other database system attributes, the autocommit mode of an Informix databasecannot be set dynamically. It is defined when the database is created. You cannotchange it with a call to the Connection.setAutoCommit method. Only non-ANSI,non-logged databases support changing autocommit.

The JDBC spec says that the autocommit mode should be true by default, but it is notpossible to do this with Informix. All that you can do is determine what the autocommitmode is. To change the autocommit state, you must rebuild your database (for moreinformation, see the information on “CREATE DATABASE” in the Informix docs).

This affects how transactions and locking work. A JDBC program could behave verydifferently depending on how the Informix database is created.

Before you depend on autocommit, you should know the setting of autocommit for thedatabase you’ll be using. You can check its state with theConnection.getAutoCommit() method, which returns true if autocommit isenabled. For Informix, this method returns false by default for ANSI databases; it mayreturn true or false, depending on how the database was created, for a non-ANSIdatabase.

Here is what is supported in WebLogic jDriver for Informix when you call theConnection.setAutoCommit() method:

� For ANSI databases, only autocommit=false is supported.

� For non-ANSI databases, autocommit can be set to either true or false.

� For non-ANSI databases without logging, only autocommit=true is supported.



Your program must then operate in accordance with the state of your Informixdatabase.

If you are using a non-ANSI database and you set autocommit to false, all transactionalSQL must be carried out using the Connection.commit() orConnection.rollback() methods. You should never execute the explicittransaction controls BEGIN WORK, COMMIT WORK, or ROLLBACK WORK callson a Statement, since WebLogic jDriver for Informix uses transaction commandsinternally to simulate an autocommit=false status. You should always control atransaction using commit() and rollback() methods in the Connection class.

For non-ANSI databases without logging, autocommit=false cannot be supported,since transactions are not supported. Consequently, only autocommit=true issupported for use with such databases.

Support for Informix-specific features

WebLogic jDriver for Informix includes support for other Informix-specific featuresthat may not be part of the JDBC specification, but that add power when writing aclient application for an Informix database.

Retrieving VARCHAR/CHAR data as bytes

WebLogic jDriver for Informix provides an extension to JDBC for Informix thatallows users to retrieve VARCHAR and CHAR columns using theResultSet.getBytes(String columnName) and ResultSet.getBytes(int

columnIndex)methods. Although this is outside the scope of the JDBC specification,this was implemented in response to customer requests. No cast of the ResultSet isrequired to take advantage of this feature.

Codeset support

As a Java application, WebLogic jDriver for Informix handles character strings asUnicode strings. To exchange character strings with a database that may operate witha different codeset, you must set the weblogic.codeset connection property to theproper JDK codeset. If there is no direct mapping between the codeset of your databaseand the character sets provided with the JDK, you can set the weblogic.codeset



connection property to the most appropriate Java character set. You can find the Listof supported encodings athttp://www.JavaSoft.com/products/jdk/1.1/docs/guide/intl/encoding.doc.html at theJavaSoft website.

For example, to use the cp932 codeset, create a Properties object and set theweblogic.codeset property before calling Driver.connect(), as in this example:

java.util.Properties props = new java.util.Properties();props.put("weblogic.codeset", "cp932");props.put("user", "scott");props.put("password", "tiger");

String connectUrl = "jdbc:weblogic:informix4:myDB@myHost:1493";

Driver myDriver = (Driver)Class.forName("weblogic.jdbc.informix4.Driver").newInstance();Connection conn =

myDriver.connect(connectUrl, props);

Using Unicode streams in a prepared statement

weblogic.jdbcbase.informix4.UnicodeInputStream()

If you are using the PreparedStatement.setUnicodeStream method, you caneither create your own InputStream object, or you can create aweblogic.jdbc.informix4.UnicodeInputStream object, using a String value inthe constructor. Here’s an example that shows how to input a Unicode stream into anInformix TEXT column, (using the connectUrl and props objects created above):

Driver myDriver = (Driver)Class.forName("weblogic.jdbc.informix4.Driver").newInstance();Connection c =

myDriver.connect(connectUrl, props);

PreparedStatement ps =c.prepareStatement("insert into dbTEST values (99,?)");

String s = new String("\u93e1\u68b0\u897f");weblogic.jdbcbase.informix4.UnicodeInputStream uis =

new weblogic.jdbcbase.informix4.UnicodeInputStream(s);

try {ps.setUnicodeStream(1,uis,uis.available());

}


http://www.JavaSoft.com/products/jdk/1.1/docs/guide/intl/encoding.doc.html

http://www.JavaSoft.com/products/jdk/1.1/docs/guide/intl/encoding.doc.html

What is currently supported in WebLogic jDriver for Informix

catch (java.io.IOException ioe) {System.out.println("-- IO Exception in setUnicodeStream");

}ps.executeUpdate();

To retrieve data from a UnicodeInputStream you can use java.io.InputStream. Forexample,

InputStream uisout = rs.getUnicodeStream(2);int i=0;while (true) {try {i = uisout.read(); // read 1 byte at a time from UnicodeStream

}catch (IOException e) {

System.out.println("-- IOException reading UnicodeStream");}

For more information, check the full example included in the distribution, in theexamples/jdbc/informix4 directory.


WebLogic jDriver for Informix is a complete and compliant implementation of theJDBC specification, except for those features described in JDBC that are eitherunsupported or unavailable in Informix. Since there is often confusion about theimplementation the DatabaseMetaData interface, we list all of its methods here. Mostare supported; some are planned for a future release, and some (because of Informixlimitations or implementations) will not be supported for this JDBC driver.

The following DatabaseMetaData methods are supported:allProceduresAreCallable()

allTablesAreSelectable()

dataDefinitionCausesTransactionCommit()

dataDefinitionIgnoredInTransactions()

doesMaxRowSizeIncludeBlobs()

getCatalogSeparator()



getCatalogTerm()

getColumns()

getDatabaseProductName()

getDatabaseProductVersion()

getDefaultTransactionIsolation()

getDriverMajorVersion()

getDriverMinorVersion()

getDriverName()

getDriverVersion()

getExportedKeys()

getExtraNameCharacters()

getIdentifierQuoteString()

getImportedKeys()

getMaxBinaryLiteralLength()

getMaxCatalogNameLength()

getMaxCharLiteralLength()

getMaxColumnNameLength()

getMaxColumnsInGroupBy()

getMaxColumnsInIndex()

getMaxColumnsInOrderBy()

getMaxColumnsInSelect()

getMaxColumnsInTable()

getMaxConnections()

getMaxCursorNameLength()

getMaxIndexLength()

getMaxProcedureNameLength()

getMaxRowSize()

getMaxSchemaNameLength()

getMaxStatementLength()

getMaxStatements()

getMaxTableNameLength()

getMaxTablesInSelect()

getMaxUserNameLength()

getNumericFunctions()

getPrimaryKeys()

getProcedures()

getProcedureTerm()

getSchemas()

getSchemaTerm()

getSearchStringEscape()

getSQLKeywords()



getStringFunctions()

getSystemFunctions()

getTables()

getTableTypes()

getTimeDateFunctions()

getTypeInfo()

getURL()

getUserName()

isCatalogAtStart()

isReadOnly()

nullPlusNonNullIsNull()

nullsAreSortedAtEnd()

nullsAreSortedAtStart()

nullsAreSortedHigh()

nullsAreSortedLow()

storesLowerCaseIdentifiers()

storesLowerCaseQuotedIdentifiers()

storesMixedCaseIdentifiers()

storesMixedCaseQuotedIdentifiers()

storesUpperCaseIdentifiers()

storesUpperCaseQuotedIdentifiers()

supportsAlterTableWithAddColumn()

supportsAlterTableWithDropColumn()

supportsANSI92EntryLevelSQL()

supportsANSI92FullSQL()

supportsANSI92IntermediateSQL()

supportsCatalogsInDataManipulation()

supportsCatalogsInIndexDefinitions()

supportsCatalogsInPrivilegeDefinitions()

supportsCatalogsInProcedureCalls()

supportsCatalogsInTableDefinitions()

supportsColumnAliasing()

supportsConvert()

supportsCoreSQLGrammar()

supportsCorrelatedSubqueries()

supportsDataDefinitionAndDataManipulationTransactions()

supportsDataManipulationTransactionsOnly()

supportsDifferentTableCorrelationNames()

supportsExpressionsInOrderBy()

supportsExtendedSQLGrammar()

supportsFullOuterJoins()



supportsGroupBy()

supportsGroupByBeyondSelect()

supportsGroupByUnrelated()

supportsIntegrityEnhancementFacility()

supportsLikeEscapeClause()

supportsLimitedOuterJoins()

supportsMinimumSQLGrammar()

supportsMixedCaseIdentifiers()

supportsMixedCaseQuotedIdentifiers()

supportsMultipleResultSets()

supportsMultipleTransactions()

supportsNonNullableColumns()

supportsOpenCursorsAcrossCommit()

supportsOpenCursorsAcrossRollback()

supportsOpenStatementsAcrossCommit()

supportsOpenStatementsAcrossRollback()

supportsOrderByUnrelated()

supportsOuterJoins()

supportsPositionedDelete()

supportsPositionedUpdate()

supportsSchemasInDataManipulation()

supportsSchemasInIndexDefinitions()

supportsSchemasInPrivilegeDefinitions()

supportsSchemasInProcedureCalls()

supportsSchemasInTableDefinitions()

supportsSelectForUpdate()

supportsStoredProcedures()

supportsSubqueriesInComparisons()

supportsSubqueriesInExists()

supportsSubqueriesInIns()

supportsSubqueriesInQuantifieds()

supportsTableCorrelationNames()

supportsTransactionIsolationLevel()

supportsTransactions()

supportsUnion()

supportsUnionAll()

usesLocalFilePerTable()

usesLocalFiles()

Support for the following methods is implemented and under testing:getBestRowIdentifier()


More Resources

getColumnPrivileges()

getTablePrivileges()

Support for the following methods is planned:getIndexInfo()

supportsConvert()

These methods will not be supported:getCatalogs()

getCrossReference()

getProcedureColumns()

getVersionColumns()

More Resources

� WebLogic JDBC Options(http://www.weblogic.com/docs51/classdocs/jdbcdrivers.html)

Contains information on other WebLogic JDBC drivers, additionaldocumentation, support resources, and more.

� Using connection pools with server-side Java (in Using WebLogic HTTPServlets) at http://www.weblogic.com/docs51/classdocs/API_servlet.html#pools0

� Creating and using connection pools athttp://www.weblogic.com/docs51/classdocs/conn_pools.html

� JavaSoft’s JDBC tutorial(http://java.sun.com/docs/books/tutorial/jdbc/index.html.)

Code examples

We also ship a number of code examples in the distribution that will help you getstarted. Code examples are located in the weblogic/informix4/examples/directory in the distribution.


http://www.weblogic.com/docs51/classdocs/jdbcdrivers.html

http://www.weblogic.com/docs51/classdocs/API_servlet.html#pools0

http://java.sun.com/docs/books/tutorial/jdbc/index.html

http://www.weblogic.com/docs51/classdocs/conn_pools.html

3 Release Notes

� Issue 9494

The class weblogic.jdbcbase.InformixInterval has been replaced with theinterface weblogic.jdbc.common.InformixInterval. To use thisinterface, import weblogic.jdbc.common.InformiInterval and cast yourobjects to weblogic.jdbc.common.InformixInterval.

� When establishing the database connection in your code, BEA nowrecommends, for performance reasons, that you not use theDriverManager.getConnection() method. In its place, construct a propertiesobject and pass the driver class and properties to thejava.sql.Driver.connect() method. This procedure is described in detail inthe section Connecting to an Informix DBMS on page 20.


bea weblogic - freie universität · 2000-04-03 · bea weblogic jdriver for informix. if you have...

Documents