BEA WebLogic - · PDF fileTransaction boundaries ... Your feedback on the BEA WebLogic...

BEA WebLogicInstalling and Using

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

WebLogic jDriver for Oracle

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, jDriver, ObjectBroker, TOP END, and TUXEDO are registered trademarks of BEA Systems,Inc. BEA Builder, 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 jDriver for Oracle

Document Edition Part Number Date Software Version

1.0 April 2000 WebLogic jDriver for Oracle 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 OracleOverview ...............................................................................................................7

Important issues for release 5.1.............................................................................8

Other JDBC drivers...............................................................................................8

Installation steps....................................................................................................9

Editing an entry to the XML license file......................................................11

Setting your path and client libraries..................................................................12

JDBC 2.0......................................................................................................13

Platform considerations................................................................................13

Directory to put in your system PATH ........................................................13

Windows NT.........................................................................................13

Solaris ...................................................................................................14

IBM AIX...............................................................................................15

HP-UX 11 ............................................................................................15

SGI IRIX...............................................................................................16

Siemens MIPS.......................................................................................16

Compaq Tru64 UNIX ...........................................................................16

Note for Microsoft SDK for Java (Jview) users..................................................17

Checking connections to the Oracle database .....................................................17

Installing and Using WebLogic jDriver for Oracle v

Setting up a connection pool ........................................................................18

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

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

Using IDEs or debuggers with WebLogic jDrivers ............................................20

Next step..............................................................................................................20

2. Using WebLogic jDriver for OracleIntroduction .........................................................................................................21

What’s in this document...............................................................................21

Overview of BEA jDrivers...........................................................................22

Software requirements..................................................................................22

Installation....................................................................................................22

Implementing with WebLogic jDriver for Oracle...............................................23

Importing packages ......................................................................................23

Setting CLASSPATH ...........................................................................23

Oracle client library versions, URLs, and Driver class names.....................25

JDBC 1.x...............................................................................................25

JDBC 2.0...............................................................................................25

Connecting to an Oracle DBMS...................................................................25

Connection example..............................................................................27

Connecting using a DataSource object .................................................27

Setting properties for WebLogic JDBC use..........................................27

About the Connection object.................................................................27

Setting Autocommit ..............................................................................28

Making a simple SQL query ........................................................................28

Inserting, updating, and deleting records .....................................................29

Creating and using stored procedures and functions....................................30

Disconnecting and closing objects ...............................................................33

Code example...............................................................................................34

Working with ResultSets from stored procedures........................................37

Support for JDBC Extended SQL ................................................................38

Additional Oracle features...................................................................................39

Allowing mixed case metadata ....................................................................39

Data types .....................................................................................................40

WebLogic jDriver for Oracle and Oracle's NUMBER column ............41

vi Installing and Using WebLogic jDriver for Oracle

Using Oracle Long raw data types........................................................42

Waiting on Oracle resources ........................................................................42

Autocommit .................................................................................................43

Transaction isolation levels..........................................................................43

Codeset support............................................................................................44

Support for Oracle array fetches ..................................................................47

Using stored procedures...............................................................................48

Binding a parameter to an Oracle cursor ..............................................48

Notes on using CallableStatement ........................................................50

Notes on DatabaseMetaData methods .........................................................50

JDBC 2.0 for Oracle............................................................................................51

Overview......................................................................................................51

Configuration ...............................................................................................51

Driver class ...........................................................................................52

Driver URL ...........................................................................................52

Overview of BLOBs and CLOBs ................................................................52

Transaction boundaries .........................................................................52

BLOBs .........................................................................................................53

Connection properties ...........................................................................53

Import statements..................................................................................54

Initializing a BLOB field ......................................................................54

Writing binary data to a BLOB.............................................................55

Writing a BLOB object.........................................................................55

Reading BLOB data..............................................................................56

Other methods.......................................................................................57

CLOBs .........................................................................................................57

Codeset support.....................................................................................57

Initializing a CLOB field ......................................................................58

Writing ASCII data to a CLOB ............................................................59

Writing Unicode data to a CLOB .........................................................60

Writing CLOB objects ..........................................................................60

Reading CLOB data..............................................................................61

Other methods.......................................................................................61

Character and ASCII Streams ......................................................................62

Unicode character Streams ...................................................................62

Installing and Using WebLogic jDriver for Oracle vii

ASCII character streams .......................................................................62

Batch updates ...............................................................................................63

Using Batch updates..............................................................................63

Clearing the batch .................................................................................64

Update counts........................................................................................64

Using with JDBC 1 ...............................................................................64

New date methods ........................................................................................65

Resources.............................................................................................................66

Code Examples.............................................................................................66

3. Release Notes for WebLogic jDriver for OracleUpgrade ...............................................................................................................67

Changes ...............................................................................................................67

Issues ...................................................................................................................68

viii Installing and Using WebLogic jDriver for Oracle

PREFACE

About This Document

This document describes how to install and develop applications using jDriver forOracle, BEA’s type-2 Java Database Connectivity (JDBC) driver for the OracleDatabase management system.

This document covers the following topics:

� Chapter 1, “Installing WebLogic jDriver for Oracle”

� Chapter 2, “Using WebLogic jDriver for Oracle”

� Chapter 3, “Release Notes for WebLogic jDriver for Oracle”

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 Oracle 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 Oracle, is also available in HTML format on the BEA e-docs website. To accessthe online HTML version on the BEA web site, use the following links:

Installing WebLogic jDriver for Oracle:http://www.weblogic.com/docs51/install/install_jdbc.html

Using WebLogic jDriver for Oracle:http://www.weblogic.com/docs51/classdocs/API_joci.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 jDriver for Oracle documentation.

2 Installing and Using WebLogic jDriver for Oracle

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

http://www.weblogic.com/docs50/install/install_jdbc.html

Documentation Conventions

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

If you have any questions about this version of BEA jDriver for Oracle, or if you haveproblems installing and running BEA jDriver for Oracle, contact BEA CustomerSupport through BEA WebSupport at www.beasys.com. You can also contactCustomer Support by using the contact information provided on the Customer SupportCard, 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


CHAPTER

1 Installing WebLogic jDriver for Oracle

Overview

WebLogic jDriver for Oracle is a new name for the product formerly known asjdbcKona/Oracle.

WebLogic jDriver for Oracle, a Type-2 JDBC driver for the Oracle DBMS is includedwith WebLogic Server. For this driver to function, you must have a complete Oracleclient installed on the machine that will be the client to the Oracle DBMS. This Oracleclient installation contains vendor-supplied client libraries and associated files thatWebLogic jDriver for Oracle requires to operate.

The WebLogic Server distribution includes a choice of several BEA-supplied nativelibraries for WebLogic jDriver for Oracle. The library that you choose depends onwhich Oracle client version you have installed on your client machine and whichversion of the Oracle API you will use to access your Oracle server. Installing thisdriver requires that both the BEA-supplied native library and the Oracle-suppliedclient libraries be available by including them in your the client’s PATH (Windows NT)or shared library path (UNIX), as described below.

For information on using WebLogic jDriver for Oracle see Using WebLogic jDriverfor Oracle (at http://www.weblogic.com/docs51/classdocs/API_joci.html).





Important issues for release 5.1

Please read the Release notes for details on the issues highlighted below.

Oracle Release Notes are also available on line athttp://www.weblogic.com/docs51/classdocs/release_notes_joci.html.

Platform Support:

Check the Release Notes or the WebLogic Platform Support page (athttp://www.weblogic.com/docs51/platforms/index.html) in the onlinedocumentation for details about which platforms, operating systems, DBMSversions, and Java versions are supported for WebLogic jDriver for Oracle.

Important issues include:

� WebLogic jDriver for Oracle is not supported when using the Oracle 8 API andconnecting to an version 7 Oracle DBMS.

� Using CallableStatement.getResultSet()

� Mixing different versions of the Oracle Client and Oracle Server

� Codeset conversion with CLOBs when using a different operating system on theclient and server.

Other JDBC drivers

BEA also has Type-4 JDBC drivers available for the Informix and Microsoft SQLServer DBMSs. These are pure-Java drivers and do not require vendor-supplied clientlibraries.

For more information on these drivers, please see: WebLogic JDBC Options, athttp://www.weblogic.com/docs51/classdocs/jdbcdrivers.html.


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

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

http://www.weblogic.com/docs51/platforms/index.html

Installation steps

Installation steps

1. Select the appropriate native library for your environment.

WebLogic jDriver for Oracle is shipped with dll, sl, or so files for variouscombinations of Oracle client versions, APIs, and platforms. You must place theappropriate file in your system’s path or shared library path for this driver tofunction. Unlike previous releases of WebLogic jDriver for Oracle, which hadonly one such file that was always present in the default path, you now mustspecify this path setting explicitly. For details and instructions on setting theseoptions, see Setting your path and client libraries on page 12.

2. Add the client libraries from your Oracle installation to your system PATH(Windows NT) or load library path (UNIX—the name of this variable differsamong UNIX systems). Check your Oracle documentation for the location ofthese libraries. On Windows NT the client libraries are usually located inc:\ORANT\bin.

3. Unpack the distribution.

If you have purchased WebLogic Server, WebLogic jDriver for Oracle isincluded with your distribution. No further steps are required to unpack thedistribution. The remainder of these installation steps are required only for usersof the stand-alone version of WebLogic jDriver for Oracle.

If you haven’t already, unpack the archive you downloaded in the root directoryof your computer. You must use a program such as WinZip athttp://www.winzip.com that preserves the directory structure of the archive. Thefiles unpack into the weblogic directory.

The instructions in this document assume that you are installing WebLogicjDriver for Oracle on a Windows computer and that you unpacked the archive inthe root directory of your C drive. If you’re 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.

4. Add the WebLogic jDriver for Oracle classes directory to your CLASSPATHvariable.

Note: If you are using the WebLogic jDriver for Oracle that is bundled withWebLogic Server, the classpath setting are the same as those required for


http://www.winzip.com


WebLogic Server. The standard start up scripts supplied with the WebLogicServer distribution will do this for you.

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.

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’re usingWebLogic jDriver for Oracle from within an IDE like Symantec Cafe orJBuilder, the procedure for adding classes to the CLASSPATH may be different.

5. Install WebLogic jDriver for Oracle for use with browser applets.

If you’re planning to use WebLogic jDriver for Oracle 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 Oracle classfiles. To ensure that the web server can find the files, install the WebLogicjDriver for Oracle distribution on your web server computer and then set theCLASSPATH on that computer as described in step 4. Be sure to restart the webserver after you change the CLASSPATH so that the web server has access tothe revised CLASSPATH value.


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

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

Installation steps

6. Install a license file.

With the release of version 5.1 of WebLogic jDriver for Oracle, 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 Oracle:

� 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 for Oracle,you must obtain an updated license file from your BEA contact person andplace that license in your WebLogic jDriver for Oracle installation.

Copy your license key into your WebLogicLicense.xml, file. This file islocated at weblogic/informix4/license/WebLogicLicense.xml (whereweblogic is the directory containing your WebLogic jDriver for Oracleinstallation). For instructions on editing a WebLogic XML license file, seeEditing an entry to the XML license file, below.

To purchase a permanent license for WebLogic jDriver for Oracle, [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 for Oracleor 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]


For example, if you have received a key, it'll look something like this:

<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 your path and client libraries

A native dll, so, or sl file containing your driver must be made available to yourWebLogic jDriver for Oracle client by including its directory in your system PATH

(Windows NT), LD_LIBRARY_PATH (most Unix systems), or SHLIB_PATH (HP-UX).The directory containing the correct file varies depending on several factors discussedbelow.

The vendor-supplied libraries from Oracle must also be included in your PATH, load

library path, or shared library path. The location of the directory containingyour Oracle client libraries will vary depending on your installation. On Windows NT,these libraries are normally placed into your machine’s path by the Oracle installer.

Version 5.1 of WebLogic jDriver for Oracle now uses the dll, so, or sl files built withthe Oracle 8 API as the native interface for accessing an Oracle DBMS. This APIallows for improved connectivity to a version 7 or version 8 Oracle Server and alsoprovides access to new features available only in Oracle 8 (some of these featuresrequire JDBC 2.0, which requires a Java 2 JVM).

An older version of these dll, so, or sl files that uses the Oracle 7 API, is alsoincluded with this release to assure backwards compatibility.



The tables below, under Directory to put in your system PATH, list the Oracle clientversion, the Oracle API version and the directory you must put in your system PATHto access that version of the driver.

JDBC 2.0

JDBC 2.0 features are only available when using a driver that uses the Oracle 8 API.You must also run your WebLogic jDriver for Oracle client under a Java 2 compatibleJDK. Using JDBC 2.0 also requires using a different driver class and URL in your Javacode. For more information, see JDBC 2.0 for Oracle in the document UsingWebLogic jDriver for Oracle athttp://www.weblogic.com/docs51/classdocs/API_joci.html#jdbc20.

Platform considerations

For information on supported platforms and JVM versions for WebLogic jDriver forOracle, see the WebLogic platform support page athttp://www.weblogic.com/docs51/platforms/index.html#jdbc.

The minimum supported client library is Oracle version 7.3.4.

Directory to put in your system PATH

Windows NT

Add weblogic\bin and the appropriate directory from the table below to your PATH,for example:

$ set PATH=%PATH%;c:\weblogic\bin\oci805_8

Where c:\weblogic is the home directory of your WebLogic Server or WebLogicjDriver for Oracle installation.


http://www.weblogic.com/docs51/platforms/index.html#jdbc

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


Directory to put in your PATH

Solaris

Add weblogic/lib/solaris and the appropriate directory from the table below toyour ld library path. (Where weblogic is the home directory of your WebLogicServer or WebLogic jDriver for Oracle installation)

Directory to put in your ld_library_path

OracleClientversion

Oracle APIversion

Directory Notes

7.3.4 7 oci734_7 Provided for backwards com-

patibility. No Oracle 8 or

JDBC 2.0 features.



JDBC 2.0 features.

8.0.5 8 oci805_8 Allows access to Oracle 8 and

JDBC 2.0 features.


JDBC 2.0 features.

OracleClientversion

Oracle APIversion

Directory Notes



JDBC 2.0 features.



JDBC 2.0 features.


JDBC 2.0 features.


JDBC 2.0 features.



You must also include the path to your vendor-supplied client libraries from Oracle inyour ld_library_path. The location of these libraries will depend on your Oracleclient installation.

IBM AIX

WebLogic jDriver for Oracle for IBM AIX is available only for the Oracle 7 API. Fora list of supported client versions, see Platform support for JDBC drivers athttp://www.weblogic.com/docs51/platforms/index.html#jdbc.

Add the directory weblogic/lib/aix to your LIBPATH.

Where weblogic is the home directory of your WebLogic Server or WebLogic jDriverfor Oracle installation.

HP-UX 11

Add weblogic/lib/hpux11 and the appropriate directory from the table below toyour SHLIB_PATH. (Where weblogic is the home directory of your WebLogic Serveror WebLogic jDriver for Oracle installation)


JDBC 2.0 features.

OracleClientversion

Oracle APIversion

Directory Notes



JDBC 2.0 features.


JDBC 2.0 features.

8.1.5 8 OCI815_8 Allows access to Oracle 8 and

JDBC 2.0 features.




SGI IRIX

WebLogic jDriver for Oracle for SGI IRIX is available only for the Oracle 7 API. Fora list of supported client versions, see Platform support for JDBC drivers athttp://www.weblogic.com/docs51/platforms/index.html#jdbc.

� Irix users must run Java in N32 mode.

� You must have the Oracle 8.0.5 N32 client installed on your computer.

Add the directory weblogic/lib/irixsh to your LD_LIBRARYN32_PATH.


Siemens MIPS

WebLogic jDriver for Oracle for Siemens MIPS is available only for the Oracle 7 API.For a list of supported client versions, see Platform support for JDBC drivers athttp://www.weblogic.com/docs51/platforms/index.html#jdbc.

Add the directory weblogic/lib/reliantunix to your LD_LIBRARY_PATH.


Compaq Tru64 UNIX

WebLogic jDriver for Oracle for Compaq Tru64 UNIX is available only for the Oracle7 API. For a list of supported client versions, see Platform support for JDBC drivers athttp://www.weblogic.com/docs51/platforms/index.html#jdbc.

Add the directory weblogic/lib/tru64unix to your LD_LIBRARY_PATH.






Note for Microsoft SDK for Java (Jview) users

Note for Microsoft SDK for Java (Jview) users

� Version 5.00, build 3186 or later of Jview is required for WebLogic jDriver forOracle.

� Jview does not support JDBC 2.0 features.

Checking connections to the Oracle database

Once you have installed WebLogic jDriver for Oracle you should check that you canuse it to connect to your database. A utility called dbping is included with WebLogicServer that you can use to test this connection.

To use this helper application, type the following at the command line (on one line):

$ java -classpathc:\java\lib\classes.zip;c:\weblogic\classes;c:\weblogic\license;utils.dbping ORACLE user password server

Where c:\weblogic is the directory containing your WebLogic Server or WebLogicjDriver for Oracle installation and c:\java is the path to your JDK.

Note: If you are using Java 2 (JDK 1.2), omit “c:\java\lib\classes.zip” fromthe above command.

For more detailed instructions on how to verify your connection to a DBMS, seeTesting connections.

If you have problems, check Troubleshooting problems with shared libraries on UNIX,at http://www.weblogic.com/docs51/techsupport/sharedlibs.html.


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

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


Setting up a connection pool

If you are using WebLogic jDriver for Oracle with either WebLogic Server orWebLogic Express, you can set up a pool of connections to your Oracle 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 Oracle and one of the existing connections from the pool toconnect to the Oracle database on behalf of your application.

Configuring a connection pool with WebLogic Server

1. Include the vendor-supplied native libraries and the WebLogic native libraries forWebLogic jDriver for Oracle in the PATH (Windows) or load library path

(UNIX) of the shell where you will start WebLogic Server (for details, see Settingyour path and client libraries on page 12). For more information on startingWebLogic Server, see Setting up and Starting WebLogic Server athttp://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.OraclePool=\url=jdbc:weblogic:oracle:myServer:myPort,\driver=weblogic.jdbc.oci.Driver,\loginDelaySecs=1,\initialCapacity=4,\maxCapacity=10,\capacityIncrement=2,\allowShrinking=true,\shrinkPeriodMins=15,\refreshMinutes=10,\testTable=dual,\props=user=myUserName;password=secret;server=myServer;\

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

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


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

Checking connections to the Oracle database

weblogic.allow.shrink.weblogic.jdbc.connectionPool.SQLPool=\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.

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


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

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

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

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

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


Using IDEs or debuggers with WebLogic jDrivers

If you are using Symantec Cafe, other IDEs, or debuggers, copy theWebLogic-supplied native library to a new file with a name that ends in _g (before thedot).

For example on a Unix machine, copy libweblogicoci36.so tolibweblogicoci36_g.so. For Windows NT, copy weblogicoci36.dll toweblogicoci36_g.dll

Next step

See Setting your development environment, athttp://www.weblogic.com/docs51/techstart/environment.html for information onsetting up a development environment for running JDBC clients.

Using WebLogic jDriver for Oracle (athttp://www.weblogic.com/docs51/classdocs/API_joci.html). Developers Guide forWebLogic jDriver for Oracle.


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


CHAPTER

2 Using WebLogic jDriver for Oracle

Introduction

WebLogic jDriver for Oracle is a new name for the product previously known asjdbcKona/Oracle.

What’s in this document

This document covers using the WebLogic jDriver for Oracle JDBC driver for theOracle Database management system (DBMS). This driver is a Type-2 JDBC driverand requires the installation of Oracle client libraries on the machine accessing theOracle Server.

This document also includes general notes and an implementation guide for usingJDBC, and information on using Oracle-specific features with WebLogic jDriver forOracle. The discussions and examples in this document assume that the reader isfamiliar with Java, general DBMS concepts, and Structured Query Language (SQL).

This document also covers recent updates to WebLogic jDriver for Oracle, as ofversion 5, that include new JDBC 2.0 for Oracle features such as Blob and Clobsupport and Batch updates.

If you are using WebLogic JDBC, BEA's multitier JDBC implementation, you shouldalso refer to the Developers Guide Using WebLogic JDBC athttp://www.weblogic.com/docs51/classdocs/API_jdbct3.html for more information.


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


Overview of BEA jDrivers

The BEA WebLogic jDrivers include a Type-2 native JDBC driver for Oracle andType 4 JDBC drivers for Informix and Microsoft SQL Server. The Type-2 driveremploys client libraries supplied by the database vendor while the Type-4 drivers are100% pure Java; they connect to the database server at the wire level withoutvendor-supplied client libraries.

For more information, see WebLogic JDBC Options athttp://www.weblogic.com/docs51/classdocs/jdbcdrivers.html.

Software requirements

For details on the platforms, operating systems, JVMs, DBMS versions, and clientlibraries supported by the WebLogic jDrivers see Platform support for WeblogicjDrivers at http://www.weblogic.com/docs51/platforms/index.html.

Installation

For installation instructions, see Installing WebLogic jDriver for Oracle athttp://www.weblogic.com/docs51/install/install_jdbc.html.


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




Implementing with WebLogic jDriver for Oracle


This example follows a simple application through the basic steps:

� Importing JDBC packages

� Connecting to an Oracle DBMS.

� Making a simple SQL query

� Inserting, updating, and deleting records

� Creating and using stored procedures and functions

� Disconnecting and closing objects

� Code example.

Importing packages

The classes that you import into your application should include:

import java.sql.*;import java.util.Properties; // required only if using a Properties

// object to set connection parametersimport weblogic.common.*;

The WebLogic jDriver for Oracle driver implements the java.sql interface. Youwrite your application using the java.sql classes. You do not need to import theJDBC driver class; instead, you load the driver inside the application. This allows youto select an appropriate driver at runtime. You can even decide what DBMS to connectto after the program is compiled.

Setting CLASSPATH

When running a WebLogic jDriver for Oracle client using the driver provided withWebLogic Server you must put the following directory in your CLASSPATH:



weblogic/classes

(where weblogic is the directory containing your WebLogic Server installation)

If you are running a stand-alone version of WebLogic jDriver for Oracle, place thefollowing directory in your classpath:

weblogic/oci/classes

(where weblogic is the directory containing your WebLogic jDriver for Oracleinstallation)

For more information on setting your CLASSPATH and other environment issues, seeSetting your development environment athttp://www.weblogic.com/docs51/techstart/environment.html.


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


Oracle client library versions, URLs, and Driver class names

Depending on your platform, which version of the Oracle client libraries you are using,and whether or not you require access to JDBC 2.0 features (Blobs, Clobs, Batchupdates), you need to use a different driver class name and URL.

You must also specify the correct driver version in your system’s path. For moreinformation, see Setting your path and client libraries athttp://www.weblogic.com/docs51/install/install_jdbc.html#client.

JDBC 1.x

Driver class: weblogic.jdbc.oci.Driver

URL: jdbc:weblogic:oracle

JDBC 2.0

Driver class: weblogic.jdbc20.oci.Driver

URL: jdbc20:weblogic:oracle

Connecting to an Oracle DBMS

These steps explain how to set up your application to connect to your Oracle DBMSusing WebLogic jDriver for Oracle. 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 Oracle JDBC driver class, and castingit to a java.sql.Driver object. This procedure properly loads and registers theJDBC driver. For example:

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


http://www.weblogic.com/docs51/install/install_jdbc.html#client


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("server", "DEMO");

The server name (“DEMO” in the example above) refers to an entry in thetnsnames.ora file, which is located in your Oracle client installation anddefines host names and other information about an Oracle database. If you donot supply a server name, the system will look for an environment variable(ORACLE_SID in the case of Oracle). You may also choose to add the servername to the URL, with this format:

"jdbc:weblogic:oracle:DEMO"

in which case you do not need to provide a “server” property.

You can also set properties in a single URL, for use with products likePowerSoft's PowerJ. For details, see Using URLs with WebLogic products athttp://www.weblogic.com/docs51/classdocs/urls.html.

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:oracle", 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:mssqlserver4, and may include other information, including the serverhost name and the database name.

Note: The examples in this document use the driver nameweblogic.jdbc.oci.Driver and the URL jdbc:weblogic:oracle.

These are intended for use where JDBC 2.0 features are not required. You mayalso use the driver name weblogic.jdbc20.oci.Driver and the URLjdbc20:weblogic:oracle if you need to use JDBC 2.0 features. For moreinformation on JDBC 2.0, see JDBC 2.0 for Oracle on page 51.


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


There are additional restrictions regarding the use of JDBC 2.0. For moreinformation, see Oracle client library versions, URLs, and Driver class nameson page 25.

Connection example

This example shows how to use a Properties object to connect to a database named“myDB.”

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



Connecting using a DataSource object

If you are using WebLogic jDriver for Oracle as a middle-tier driver with WebLogicServer, you can also obtain a connection by using a DataSource object. For moreinformation, see Using a DataSource object to get a connection athttp://www.weblogic.com/docs51/classdocs/DataSource.html.

Setting properties for WebLogic JDBC use

If you are using WebLogic JDBC in a multitier environment with the WebLogicjDriver for Oracle driver, you will set connection properties in a slightly different way.See Using WebLogic JDBC athttp://www.weblogic.com/docs51/classdocs/API_jdbct3.html for more information.

About the Connection object

The Connection object is an important part of the application. The Connection classhas constructors for many fundamental database objects that you will use throughoutthe application, and in the examples that follow, you will see the Connection objectconn used frequently. Connecting to the database completes the initial portion of theapplication.


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

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


You should call the close() method on the Connection object as soon as you finishworking with it, usually at the end of a class.

Setting Autocommit

The default transaction mode for JDBC assumes autocommit to be true. WithWebLogic jDriver for Oracle, setting autocommit to false will improve performance.

Making a simple SQL query

The most fundamental task in database access is to retrieve data. With WebLogicjDriver for Oracle, this is 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.

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 <= md.getColumnCount(); i++) {System.out.println("Column Name: " +md.getColumnName(i));

System.out.println("Nullable: " +md.isNullable(i));

System.out.println("Precision: " +md.getPrecision(i));



System.out.println("Scale: " +md.getScale(i));

System.out.println("Size: " +md.getColumnDisplaySize(i));

System.out.println("Column Type: " +md.getColumnType(i));

System.out.println("Column Type Name: "+md.getColumnTypeName(i));

System.out.println("");}

stmt.close();

JDBC ResultSets have a basic functionality for dealing with data on the record level.You may find managing data easier with BEA’s dbKona, which features a higher levelof abstraction. dbKona’s objects, like TableDataSet, QueryDataSet, and Record, aswell as other features like automatic SQL generation and client-side resultsmanagement, sit on top of JDBC. Check the Developers Guide Using dbKona, athttp://www.weblogic.com/docs51/classdocs/API_db.html for more information.

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 < 100; i++) {pstmt.setInt(1, i);pstmt.setString(2, "Person " + i);pstmt.setInt(3, i);pstmt.execute():

}pstmt.close();

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.


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


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

PreparedStatement pstmt2 = conn.prepareStatement(updsql);for (int i = 0; i < 100; i++) {pstmt2.setInt(1, i);pstmt2.setInt(2, i);pstmt2.execute();

}pstmt2.close();

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

String delsql = "delete from emp where empid = ?";PreparedStatement pstmt3 = conn.prepareStatement(delsql);for (int i = 0; i < 100; i++) {pstmt3.setInt(1, i);pstmt3.execute();

}pstmt3.close();

Creating and using stored procedures and functions

You can use WebLogic jDriver for Oracle 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) {//code to handle the exception goes here;}try {stmt.execute("drop procedure func_squareInt");}catch (SQLException e) {//code to handle the exception goes here;}try {stmt.execute("drop procedure proc_getresults");}catch (SQLException e) {//code to handle the exception goes here;}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.

Note that Oracle does not natively support binding to “?” values in a SQL statement.Instead it uses “:1”, “:2”, etc. You can use either syntax in your SQL with WebLogicjDriver for Oracle.



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 an Oracle stored procedure; thenwe execute 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();

// Native Oracle SQL is commented out here// String sql = "BEGIN proc_squareInt(?, ?); END;";

// This is the correct syntax as specified by JDBCString sql = "{call proc_squareInt(?, ?)}";CallableStatement cstmt1 = conn.prepareCall(sql);

// Register out parameterscstmt1.registerOutParameter(2, java.sql.Types.INTEGER);for (int i = 0; i < 5; i++) {cstmt1.setInt(1, i);cstmt1.execute();System.out.println(i + " " + cstmt1.getInt(1) + " "+ cstmt1.getInt(2));

} cstmt1.close();

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();

// Native Oracle SQL is commented out here



// sql = "BEGIN ? := func_squareInt(?); END;";

// This is the correct syntax specified by JDBCsql = "{ ? = call func_squareInt(?)}";CallableStatement cstmt2 = conn.prepareCall(sql);

cstmt2.registerOutParameter(1, Types.INTEGER);for (int i = 0; i < 5; i++) {cstmt2.setInt(2, i);cstmt2.execute();System.out.println(i + " " + cstmt2.getInt(1) +

" " + cstmt2.getInt(2));}cstmt2.close();

This next example uses a stored procedure named sp_getmessages (the code for thisstored procedure is not included with this example) This stored procedure takes amessage number as an input parameter, looks up the message number in a tablecontaining the message text and returns the message text in a ResultSet as an outputparameter. Note that you must process all ResultSets returned by a stored procedureusing the Statement.execute() and Statement.getResult() methods beforeOUT parameters and return status are available.

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 finish processing the ResultSet, the OUT parameters and return status areavailable.

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’ve 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();

Code example

Here are selected portions of the code used in these examples to give you an overallidea of structure for a JDBC application. The code example shown here includesretrieving data, displaying metadata, inserting, deleting, and updating data, and storedprocedures and functions. Note the explicit calls to close() for each JDBC-relatedobject, and note also that we close the Connection itself in a finally {} block, withthe call to close() wrapped in a try {} block.

package examples.jdbc.oracle;

import java.sql.*;import java.util.Properties;import weblogic.common.*;

public class test {static int i;Statement stmt = null;

public static void main(String[] argv) {try {Properties props = new Properties();props.put("user", "scott");props.put("password", "tiger");props.put("server", "DEMO");

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


}catch (Exception e)e.printStackTrace();

}

try {// This will improve performance in Oracle// You'll need an explicit commit() call laterconn.setAutoCommit(false);



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 (i = 1; i <= md.getColumnCount(); i++) {System.out.println("Column Name: " +

md.getColumnName(i));System.out.println("Nullable: " +

md.isNullable(i));System.out.println("Precision: " +

md.getPrecision(i));System.out.println("Scale: " +

md.getScale(i));System.out.println("Size: " +

md.getColumnDisplaySize(i));System.out.println("Column Type: " +

md.getColumnType(i));System.out.println("Column Type Name: "+

md.getColumnTypeName(i));System.out.println("");

}rs.close();stmt.close();

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

// Create a stored procedureStatement 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();

CallableStatement cstmt1 =conn.prepareCall("BEGIN proc_squareInt(?, ?); END;");

cstmt1.registerOutParameter(2, Types.INTEGER);for (i = 0; i < 100; i++) {cstmt1.setInt(1, i);cstmt1.execute();System.out.println(i + " " + cstmt1.getInt(1) +


// Create a stored functionStatement 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();

CallableStatement cstmt2 =conn.prepareCall("BEGIN ? := func_squareInt(?); END;");

cstmt2.registerOutParameter(1, Types.INTEGER);for (i = 0; i < 100; i++) {cstmt2.setInt(2, i);cstmt2.execute();System.out.println(i + " " + cstmt2.getInt(1) +


// Insert 100 recordsSystem.out.println("Inserting 100 records...");String inssql ="insert into emp(empid, name, dept) values (?, ?, ?)";

PreparedStatement pstmt = conn.prepareStatement(inssql);

for (i = 0; i < 100; i++) {pstmt.setInt(1, i);pstmt.setString(2, "Person " + i);pstmt.setInt(3, i);pstmt.execute();

}pstmt.close();



// Update 100 recordsSystem.out.println("Updating 100 records...");String updsql ="update emp set dept = dept + ? where empid = ?";PreparedStatement pstmt2 = conn.prepareStatement(updsql);

for (i = 0; i < 100; i++) {pstmt2.setInt(1, i);pstmt2.setInt(2, i);pstmt2.execute();

}pstmt2.close();

// Delete 100 recordsSystem.out.println("Deleting 100 records...");String delsql = "delete from emp where empid = ?";PreparedStatement pstmt3 = conn.prepareStatement(delsql);

for (i = 0; i < 100; i++) {pstmt3.setInt(1, i);pstmt3.execute();

}pstmt3.close();

conn.commit();}catch (Exception e) {// Deal with failures appropriately

}finally {try {conn.close();}catch (Exception e) {// Catch and deal with exception

}}

}}

Working with ResultSets from stored procedures

Executing stored procedures may return multiple ResultSets. When you processResultSets returned by a stored procedure, using Statement.execute() andStatement.getResultSet() methods, you must process all ResultSets returnedbefore any of the OUT parameters or the return status codes are available.



Support for JDBC Extended SQL

The JavaSoft JDBC specification includes SQL Extensions, also called SQL EscapeSyntax. All WebLogic jDrivers support Extended SQL. Extended SQL provides accessto common SQL extensions in a way that is portable between DBMSs.

For example, the function to extract the day name from a date is not defined by the SQLstandards. For Oracle, the SQL is:

select to_char(date_column, 'DAY') from table_with_dates

The equivalent function for Sybase and Microsoft SQL Server is:

select datename(dw, date_column) from table_with_dates

Using Extended SQL, you can retrieve the day name for both DBMSs as follows:

select {fn dayname(date_column)} from table_with_dates

Here’s an example that demonstrates several features of Extended SQL:

String query ="-- This SQL includes comments and " +

"JDBC extended SQL syntax.\n" +"select into date_table values( \n" +" {fn now()}, -- current time \n" +" {d '1997-05-24'}, -- a date \n" +" {t '10:30:29' }, -- a time \n" +" {ts '1997-05-24 10:30:29.123'}, -- a timestamp\n" +" '{string data with { or } will not be altered}'\n" +"-- Also note that you can safely include" +

" { and } in comments or\n" +"-- string data.";Statement stmt = conn.createStatement();stmt.executeUpdate(query);

Extended SQL is delimited with curly braces (“{}”) to differentiate it from commonSQL. Comments are preceded by two hyphens, and are ended by a new line (“\n”).The entire Extended SQL sequence, including comments, SQL, and Extended SQL, isplaced within double quotes and passed to the execute() method of a Statementobject. Here is Extended SQL used as part of a CallableStatement:

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

This example shows that you can nest extended SQL expressions:


Additional Oracle features

select {fn dayname({fn now()})}

You can retrieve lists of supported Extended SQL functions from a DatabaseMetaDataobject. This example shows how to list all the functions a JDBC driver supports:

DatabaseMetaData md = conn.getMetaData();System.out.println("Numeric functions: " +

md.getNumericFunctions());System.out.println("\nString functions: " +

md.getStringFunctions());System.out.println("\nTime/date functions: " +

md.getTimeDateFunctions());System.out.println("\nSystem functions: " +

md.getSystemFunctions());conn.close();

Refer to chapter 11 of the JDBC 1.2 specification at JavaSoft athttp://splash.javasoft.com/jdbc for a description of Extended SQL.


Allowing mixed case metadata

WebLogic jDriver for Oracle also allows setting the propertyallowMixedCaseMetaData. When set to the boolean true, this property sets up theConnection to use mixed case in calls to DatabaseMetaData methods. If this propertyis set to false, Oracle defaults to UPPERCASE for database metadata. Here is anexample of setting up the properties to include this feature:

Properties props = new Properties();props.put("user", "scott");props.put("password", "tiger");props.put("server", "DEMO");props.put("allowMixedCaseMetaData", "true");

Driver myDriver = (Driver)Class.for.Name(weblogic.jdbc.oci.Driver).newInstance();



http://splash.javasoft.com/jdbc


If you do not set this property, WebLogic jDriver for Oracle defaults to the Oracledefault, which uses UPPERCASE for database metadata.

Data types

The table below shows the recommended mapping between Oracle data types and Javatypes. There are additional possibilities for representing Oracle data types in Java.Calling the getObject() method when processing result sets will return the defaultJava data type for the Oracle column being queried.

Figure 2-1 Mapping of types between Oracle and WebLogic jDriver for Oracle.

Oracle WebLogic jDriverfor Oracle

Varchar String

Number Tinyint

Number Smallint

Number Integer

Number Long

Number Float

Number Numeric

Number Double

Long Longvarchar

RowID String

Date Timestamp

Raw (var)Binary

Long raw Longvarbinary

Char (var)Char



*Note that when PreparedStatement.setBoolean() is called, it will convert aVARCHAR type to “1” or “0” (string), and it will convert a NUMBER type to 1 or 0(number).

WebLogic jDriver for Oracle and Oracle's NUMBER column

Oracle provides a column type called NUMBER, which can be optionally specified witha precision and a scale, in the forms NUMBER(P) and NUMBER(P,S). Even in the simpleunqualified NUMBER form, this column can hold all number types from small integervalues to very large floating point numbers, with high precision.

WebLogic jDriver for Oracle reliably converts the values in a column to the Java typerequested when a WebLogic jDriver for Oracle application asks for a value from sucha column. Of course, if a value of 123.456 is asked for with getInt(), the value willbe rounded.

The method getObject(), however, poses a little more complexity. WebLogicjDriver for Oracle guarantees to return a Java object which will represent any value ina NUMBER column with no loss in precision. This means that a value of 1 can be returnedin an Integer, but a value like 123434567890.123456789 can only be returned in aBigDecimal.

There is no metadata from Oracle to report the maximum precision of the values in thecolumn, so WebLogic jDriver for Oracle must decide what sort of object to returnbased on each value. This means that one ResultSet may return multiple Java typesfrom getObject() for a given NUMBER column. A table full of integer values mayall be returned as Integer from getObject(), whereas a table of floating pointmeasurements may be returned primarily as Double, with some Integer if any valuehappens to be something like “123.00”. Oracle does not provide any information todistinguish between a NUMBER value of “1” and a NUMBER of “1.0000000000”.

Boolean* Number ORVarchar

MLS label String

Blob Blob

Clob Clob



There is some more reliable behavior with qualified NUMBER columns, that is, thosedefined with a specific precision. Oracle's metadata provides these parameters to thedriver so WebLogic jDriver for Oracle will always return a Java object appropriate forthe given precision and scale, regardless of the values in the table.

Using Oracle Long raw data types

There are two properties available for use with WebLogic jDriver for Oracle in supportof Oracle's chunking of Blobs, Clobs, Long, and Long raw data types. Although Bloband Clob data types are only supported with Oracle Version 8 and JDBC 2.0, theseproperties also apply to Oracle’s Long raw datatype, which is available in OracleVersion 7 and JDBC 1.x. For more information on theses properties, see Connectionproperties in the JDBC 2.0 section, on page 53.

Waiting on Oracle resources

Note: The waitOnResources() method is not supported when using the Oracle 8API. (For more information on your Oracle client, server, and API versions,see Setting your path and client libraries athttp://www.weblogic.com/docs51/install/install_jdbc.html#client.)

The WebLogic jDriver for Oracle driver supports Oracle's oopt() C functionality,which allows a client to wait until resources become available. The Oracle C functionsets options in cases where requested resources are not available; for example, whetherto wait for locks.

Column definition Returned by getObject()

NUMBER(P <= 9) Integer

NUMBER(P <= 18) Long

NUMBER(P = 19) BigDecimal

NUMBER(P <=16, S 0) Double

NUMBER(P = 17, S 0) BigDecimal


http://www.weblogic.com/docs51/install/install_jdbc.html#client


The developer can set whether a client will wait for DBMS resources, or will receivean immediate exception. Here's an example from the exampleexamples/jdbc/oracle/waiton.java:

java.util.Properties props = new java.util.Properties();props.put("user", "scott");props.put("password", "tiger");props.put("server", "myserver");


// You must cast the Connection as a weblogic.jdbc.oci.Connection// to take advantage of this extension

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

// After constructing the Connection object, immediately call// the waitOnResources method

conn.waitOnResources(true);

Note that use of this method can cause several error return codes while waiting forinternal resources that are locked for short durations.

To take advantage of this feature, you must first cast your Connection object as aweblogic.jdbc.oci.Connection, and then call the waitOnResources() method.

This functionality is described in section 4-97 of The OCI Functions for C.

Autocommit

The default transaction mode for JDBC WebLogic jDriver for Oracle assumesautocommit to be true. You will improve the performance of your programs by settingautocommit to false after creating a Connection object with the statement:

Connection.setAutoCommit(false);

Transaction isolation levels

WebLogic jDriver for Oracle supports the following transaction isolation levels:



� SET TRANSACTION ISOLATION LEVEL READ COMMITTED

� SET TRANSACTION ISOLATION LEVEL SERIALIZABLE

The Oracle DBMS only supports these two isolation levels. Unlike other JDBCdrivers, WebLogic jDriver for Oracle throws an exception if you try to use an isolationlevel that is unsupported. Some drivers silently ignore attempts to set an unsupportedisolation level.

The READ_UNCOMMITTED transaction isolation level is not supported.

Codeset support

JDBC and your WebLogic jDriver for Oracle driver handle character strings in Java asUnicode strings. Since the Oracle DBMS uses a different codeset, the driver mustconvert character strings from Unicode to the codeset used by Oracle. The WebLogicjDriver for Oracle will examine the value stored in the Oracle environment variableNLS_LANG and select a codeset for the JDK to use for the conversion, using themapping shown in the table below. If the NLS_LANG variable is not set, or is set to acodeset not recognized by the JDK, the driver will not be able to determine the correctcodeset. (Consult your Oracle documentation for information on the correct syntax forsetting NLS_LANG.)

If you are converting codesets, you should pass the following property to theWebLogic jDriver for Oracle with the Driver.connect() method when youestablish the connection in your code:

props.put(“weblogic.oci.min_bind_size”, 660);

This property defines the minimum size of buffers to be bound. The default is 2000bytes, which is also the maximum value. If you are converting codesets, you shoulduse this property to reduce the bind size to a maximum of 660, one-third of themaximum 2000 bytes, since Oracle codeset conversion triples the buffer to allow forexpansion.

WebLogic jDriver for Oracle provides a way to set the codeset from within your Javacode. By setting a connection property, weblogic.codeset, you can override thevalue stored in the NLS_LANG environment variable. For example, to use the cp932codeset, create a Properties object and set the weblogic.codeset property before callingDriver.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:oracle";


Connection conn =myDriver.connect(connectUrl, props);

Note that codeset support can vary with different JVMs. Check the documentation forthe JDK you are using to determine if a particular codeset is supported. You can findthe List of supported encodings for JDK 1.1 at the JavaSoft website.

Table 2-1 Mapping of NLS_LANG settings to JDK codesets

NLS_LANG JDK codeset

us7ascii ASCII

ja16sjis SJIS

us8pc437 Cp437

we8ebcdic37 Cp1046

we8ebcdic500 Cp500

we8pc850 Cp850

we8iso8859p1 ISO8859_1

ee8iso8859p2 ISO8859_2

se8iso8859p3 ISO8859_3

nee8iso8859p4 ISO8859_4

cl8iso8859p5 ISO8859_5

ar8iso8859p6 ISO8859_6

el8iso8859p7 ISO8859_7

iw8iso8859p8 ISO8859_8

we8iso8859p9 ISO8859_9

ne8iso8859p10 ISO8859_10

ru8pc866 Cp866

ee8pc852 Cp852



ru8pc855 Cp855

tr8pc857 Cp857

cl8maccyrillic MacCyrillic

we8pc860 Cp860

is8pc861 Cp861

ee8mswin1250 Cp1250

cl8mswin1251 Cp1251

el8mswin1253 Cp1253

n8pc865 Cp865

ee8macce MacCentralEurope

ee8maccroatian MacCroatian

tr8macturkish MacTurkish

is8macicelandic MacIceland

el8macgreek MacGreek

we8macroman8 MacRoman

th8macthai MacThai

el8pc737 Cp737

lt8pc772 Cp772

lt8pc774 Cp774

cdn8pc863 Cp863

ja16euc EUC_JP

ko16ksc5601 EUC_KR

zht16big5 Big5

al24utffss UTF8

utf8 UTF8



Support for Oracle array fetches

WebLogic jDriver for Oracle supports Oracle array fetches. CallingResultSet.next() the first time will get an array of rows and store it in memory,rather than retrieving a single row. Each subsequent call to next() will read a rowfrom the rows in memory until they are exhausted, and only then will next() go backto the database.

You set a property (java.util.Property) to control the size of the array fetch. Theproperty is weblogic.oci.cacheRows; it is set by default to 100. Here's an exampleof setting this property to 300, which means that calls to next() only hit the databaseonce for each 300 rows retrieved by the client.

Properties props = new Properties();props.put("user", "scott");props.put("password", "tiger");props.put("server", "DEMO");props.put("weblogic.oci.cacheRows", "300");


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

You can improve client performance and lower the load on the database server bytaking advantage of this JDBC extension. Caching rows in the client, however,requires client resources. You should tune your application for the best balancebetween performance and client resources, depending upon your networkconfiguration and your application.

If any columns in a SELECT are of type LONG, the cache size will be temporarilyreset to one (1) for the ResultSet associated with that select statement.



Using stored procedures

Binding a parameter to an Oracle cursor

WebLogic has created an extension to JDBC(weblogic.jdbc.oci.CallableStatement) that allows you to bind a parameter fora stored procedure to an Oracle cursor. You can create a JDBC ResultSet object withthe results of the stored procedure. This allows you to return multiple ResultSets in anorganized way. The ResultSets are determined at run time in the stored procedure.

Here is an example. First define the stored procedures as follows:

create or replace packagecurs_types astype EmpCurType is REF CURSOR RETURN emp%ROWTYPE;end curs_types;/

create or replace proceduresingle_cursor(curs1 IN OUT curs_types.EmpCurType,ctype in number) AS BEGINif ctype = 1 then

OPEN curs1 FOR SELECT * FROM emp;elsif ctype = 2 then

OPEN curs1 FOR SELECT * FROM emp where sal 2000;elsif ctype = 3 then

OPEN curs1 FOR SELECT * FROM emp where deptno = 20;end if;

END single_cursor;/create or replace proceduremulti_cursor(curs1 IN OUT curs_types.EmpCurType,

curs2 IN OUT curs_types.EmpCurType,curs3 IN OUT curs_types.EmpCurType) AS

BEGINOPEN curs1 FOR SELECT * FROM emp;OPEN curs2 FOR SELECT * FROM emp where sal 2000;OPEN curs3 FOR SELECT * FROM emp where deptno = 20;

END multi_cursor;/

In your Java code, you'll construct CallableStatements with the stored proceduresand register the output parameter as data type java.sql.Types.OTHER. When youretrieve the data into a ResultSet, use the output parameter index as an argument forthe getResultSet() method.



weblogic.jdbc.oci.CallableStatement cstmt =(weblogic.jdbc.oci.CallableStatement)conn.prepareCall(

"BEGIN OPEN ? " +"FOR select * from emp; END;");

cstmt.registerOutParameter(1, java.sql.Types.OTHER);

cstmt.execute();ResultSet rs = cstmt.getResultSet(1);printResultSet(rs);rs.close();cstmt.close();

weblogic.jdbc.oci.CallableStatement cstmt2 =(weblogic.jdbc.oci.CallableStatement)conn.prepareCall(

"BEGIN single_cursor(?, ?); END;");cstmt2.registerOutParameter(1, java.sql.Types.OTHER);

cstmt2.setInt(2, 1);cstmt2.execute();rs = cstmt2.getResultSet(1);printResultSet(rs);

cstmt2.setInt(2, 2);cstmt2.execute();rs = cstmt2.getResultSet(1);}printResultSet(rs);

cstmt2.setInt(2, 3);cstmt2.execute();rs = cstmt2.getResultSet(1);printResultSet(rs);cstmt2.close();

weblogic.jdbc.oci.CallableStatement cstmt3 =(weblogic.jdbc.oci.CallableStatement)conn.prepareCall(

"BEGIN multi_cursor(?, ?, ?); END;");cstmt3.registerOutParameter(1, java.sql.Types.OTHER);cstmt3.registerOutParameter(2, java.sql.Types.OTHER);cstmt3.registerOutParameter(3, java.sql.Types.OTHER);

cstmt3.execute();

ResultSet rs1 = cstmt3.getResultSet(1);ResultSet rs2 = cstmt3.getResultSet(2);ResultSet rs3 = cstmt3.getResultSet(3);

For the full code for this example, including the printResultSet() method, see theexamples in the examples/jdbc/oracle/ directory.



Note that the default size of an Oracle stored procedure string is 256K.

Notes on using CallableStatement

The default length of a string bound to an OUTPUT parameter of a CallableStatementis 128 characters. If the value you assign to the bound parameter exceeds that length,you'll get the following error:

ORA-6502: value or numeric error

You can adjust the length of the value of the bound parameter by passing an explicitlength with the scale argument to theCallableStatement.registerOutputParameter() method. Here is a codeexample that binds a VARCHAR that will never be larger than 256 characters:

CallableStatement cstmt =conn.prepareCall("BEGIN testproc(?); END;");

cstmt.registerOutputParameter(1, Types.VARCHAR, 256);cstmt.execute();System.out.println(cstmt.getString());cstmt.close();

Notes on DatabaseMetaData methods

There are some variations in the implementation of DatabaseMetaData methods thatare specific to Oracle and are detailed here:

� As a general rule, the String catalog argument is ignored in allDatabaseMetaData methods.

� In the DatabaseMetaData.getProcedureColumns() method:

� The String catalog argument is ignored.

� The String schemaPattern argument accepts only exact matches (no patternmatching).

� The String procedureNamePattern argument accepts only exact matches (nopattern matching).

� The String columnNamePattern argument is ignored.


JDBC 2.0 for Oracle

JDBC 2.0 for Oracle

Overview

The JDBC 2.0 specification defines new functionality that was not available in earlierversions of JDBC, some of which is not yet supported by current DBMS products andtherefore has not been implemented in this driver.

New JDBC 2.0 features implemented in this driver:

� BLOBs (Binary Large Objects).WebLogic jDriver for Oracle can now handle this Oracle data type.

� CLOBs (Character Large Objects)WebLogic jDriver for Oracle can now handle this Oracle data type.

� Character Streams, for both ASCII and Unicode characters.A better way to handle characters streams—as streams of characters, not bytearrays.

� Batch UpdatesYou can now send multiple statements to the database as a single unit.

The above features are available in addition to all of the existing JDBC functionalitypreviously available in the WebLogic jDriver for Oracle. All of your existing code forprevious drivers will work with this new driver. athttp://www.weblogic.com/docs51/classdocs/API_joci.html.

Configuration

Since JDBC 2.0 is a Java 2 specification, you must run WebLogic jDriver for Oraclein a Java 2 environment. This means using one of the BEA supported Java VirtualMachines, such as JDK 1.2.x to run your JDBC clients. For a complete list of supportedconfigurations, see the WebLogic Platform support page athttp://www.weblogic.com/docs51/platforms/index.html.




If you will be using JDBC 2.0 features of WebLogic jDriver for Oracle in a multitierenvironment with the WebLogic RMI, T3, JTS, or pool drivers, then you must run yourWebLogic Server in a JDK 1.2.x JVM.

Driver class

The class name for the WebLogic jDriver for Oracle JDBC 2.0 driver is:

weblogic.jdbc20.oci.Driver

Driver URL

The URL for the WebLogic jDriver for Oracle JDBC 2.0 driver is:

jdbc20:weblogic:oracle

Overview of BLOBs and CLOBs

The BLOB (Binary Large Object) and CLOB (Character Large Object) data typeswere made available with the release of Oracle version 8. The JDBC 2.0 specificationand WebLogic jDriver for Oracle also support these data types. This section containsinformation on using these data types.

Transaction boundaries

BLOBs or CLOBs in Oracle behave differently than other data types in regards totransactional boundaries (statements issued before a SQL commit or rollbackstatement). in that a BLOB or CLOB will be come inactive as soon as a transaction iscommitted. If AutoCommit is set to TRUE, the transaction will be automaticallycommitted after each command issued on the connection, including SELECTstatements. For this reason you will need to set AutoCommit to false if you need tohave a BLOB or CLOB available across multiple SQL statements. You will then needto manually commit (or rollback) the transactions at the appropriate time. To setAutoCommit to false, issue the following command:

conn.setAutoCommit(false); // where conn is your connection object


JDBC 2.0 for Oracle

BLOBs

The BLOB data type, available with Oracle version 8, allows you to store and retrievelarge binary objects in an Oracle table. Although BLOBs are defined as part of theJDBC 2.0 specification, the specification does not provide methods to update BLOBcolumns in a table. The BEA WebLogic implementation of BLOBs, however, doesprovide this functionality by means of an extension to JDBC 2.0.

Connection properties

weblobic.oci.selectBlobChunkSize

This property sets the size of an internal buffer used for sending bytes orcharacters to an I/O stream. When the Chunk size is reached, the driver willperform an implicit flush() operation, which will cause the data to be sentto the DBMS.

Explicitly setting this value can be useful in controlling memory usage on theclient.

If the value of this property is not explicitly set, a default value of 65534 willbe used.

Set this property by passing it to the Connection object as a property. Forexample, this code fragment sets weblobic.oci.selectBlobChunkSize to1200:

Properties props = new Properties();props.put("user", "scott");props.put("password", "tiger");props.put("server", "DEMO");

props.put ("weblobic.oci.selectBlobChunkSize","1200");

Driver myDriver = (Driver)Class.forName("weblogic.jdbc20.oci.Driver").newInstance();

Connection conn =driver.connect("jdbc20:weblogic:oracle:myServer", props);

weblogic.oci.insertBlobChunkSize

This property specifies the buffer size (in bytes) of input streams usedinternally by the driver.



Set this property to a positive integer to insert Blobs into an Oracle DBMSwith the Blob chunking feature. By default, this property is set to zero (0),which means that BLOB chunking is turned off.

Import statements

To use the BLOB functionality described in this section, import the following classesin your client code:

import java.sql.*;import java.util.*;import java.io.*;import weblogic.jdbc20.common.*;

Initializing a BLOB field

When you first insert a row containing a BLOB data type, you must insert the row withan “empty” BLOB before the field can be updated with real data. You can insert anempty BLOB with the Oracle EMPTY_BLOB() function.

To initialize a BLOB field:

1. Create a table with one or more columns defined as a BLOB data type.

2. Insert a new row with an empty BLOB column, using the Oracle EMPTY_BLOB()function:

stmt.execute("INSERT into myTable values (1,EMPTY_BLOB()");

3. Obtain a “handle” to the BLOB column:

java.sql.Blob myBlob = null;Statement stmt2 = conn.createStatement();stmt2.execute("SELECT myBlobColumn from myTable");ResultSet rs = stmt2.getResultSet();rs.next() {myBlob = rs.getBlob("myBlobColumn");// do something with the BLOB

}

4. You can now write data to the BLOB. Continue with the next section, Writingbinary data to a BLOB.


JDBC 2.0 for Oracle

Writing binary data to a BLOB

To write binary data to a BLOB column:

1. Obtain a handle to the BLOB field as described above, in Initializing a BLOB field,step 3.

2. Create a InputStream object containing the binary data.

java.io.InputStream is = // create your input stream

3. Create an output stream to which you write your BLOB data. Note that you mustcast your BLOB object to weblogic.jdbc20.common.OracleBlob.

java.io.OutputStream os =((weblogic.jdbc20.common.OracleBlob)myBlob).getBinaryOutputStream();

4. Write the input stream containing your binary data to the output stream. Thewrite operation is finalized when you call the flush() method on theOutputStream object.

byte[] inBytes = new byte[65534]; // see note belowint numBytes = is.read(inBytes);while (numBytes > 0) {os.write(inBytes, 0, numBytes);numBytes = is.read(inBytes);

}os.flush();

Note: The value [65534] in the above code presumes that you have not set theweblogic.oci.select.BlobChunkSize property whose default is65534. If you have set this property, setting the byte[] value to match thevalue set in the weblogic.oci.select.BlobChunkSize property

will provide the most efficient handling of the data. For more informationon this property, see Connection properties on page 53.

5. Clean up:

os.close();pstmt.close();conn.close();

Writing a BLOB object

Writing a BLOB object to a table is performed with Prepared Statements. For example,to write the myBlob object to the table myOtherTable:



PreparedStatement pstmt = conn.preparedStatement("UPDATE myOtherTable SET myOtherBlobColumn = ? WHERE id = 12");

pstmt.setBlob(1, myBlob);

Reading BLOB data

When you retrieve a BLOB column with the getBlob() method and then use aResultSet from a SQL SELECT statement, only a pointer to the BLOB data isreturned; the binary data is not actually transferred to the client until thegetBinaryStream() method is called and the data is read into the stream object.

To read BLOB data from an Oracle table:

1. Execute a SELECT statement:

stmt2.execute("SELECT myBlobColumn from myTable");

2. Use the results from the SELECT statement.

int STREAM_SIZE = 10;byte[] r = new byte[STREAM_SIZE];

ResultSet rs = stmt2.getResultSet();java.sql.Blob myBlob = null;while (rs.next) {myBlob = rs.getBlob("myBlobColumn");

java.io.InputStream readis = myBlob.getBinaryStream();

for (int i=0 ; i < STREAM_SIZE ; i++) {r[i] = (byte) readis.read();System.out.println("output [" + i + "] = " + r[i]);

}

3. Clean up:

rs.close();stmt2.close();

Note: You can also use a CallableStatement to generate a ResultSet. ThisResultSet can then be used as shown above. See your JDK documentationunder java.sql.CallableStatment for details.


JDBC 2.0 for Oracle

Other methods

The following methods of the java.sql.Blob interface are also implemented in theWebLogic jDriver for Oracle JDBC 2.0 driver. For details, see your JDKdocumentation:

� getBinaryStream()

� getBytes()

� length()

The position() method is not implemented.

CLOBs

The CLOB data type, available with Oracle version 8, enables storage of largecharacter strings in an Oracle table. Since the JDBC 2.0 specification does not includefunctionality to directly update CLOB columns, BEA has implemented the methodsgetAsciiOutputStream() (for ASCII data) and getCharacterOutputStream()

(for Unicode data) to insert or update a CLOB.

Codeset support

Depending on which version of the Oracle Server and client you are using you mayneed to set one of the following properties by passing them to the Connection objectwhen you establish your connection the DBMS in your Java client code.

weblogic.codeset

This property allows you to set a codeset from within your Java code. Thiscodeset overrides the value of any codeset specified with the Oracleenvironment variable NLS_LANG.

weblogic.oci.ncodeset

This property sets the National codeset used by the Oracle server. Thiscodeset overrides the value of any codeset specified with the Oracleenvironment variable NLS_NCHAR.

weblogic.oci.codeset_width

This property tells the WebLogic jDriver for Oracle which type you are using.Note the following restrictions on codeset use:



Oracle Version 8.0.5: only fixed width character sets are supportedOracle Version 8.1.5 and later: character sets may be either fixed orvariable width.

Possible Values:0 (for variable-width codesets)1 (for fixed-width codesets; this is the default value)2 or 3 (the width, in bytes of the codeset)

weblogic.oci.ncodeset_width

If you are using one of Oracle’s National codesets, specify the width of thatcodeset with this property. Note the following restrictions on codeset use:

Oracle Version 8.0.5: only fixed width character sets are supportedOracle Version 8.1.5 and later: character sets may be either fixed orvariable width.

Possible Values:0 (for variable-width codesets)1 (for fixed-width codesets; this is the default value)2 or 3 (the width, in bytes, of the codeset)

weblogic.oci.use_clob_unicode_io

When using CLOBS in conjunction with a character set on the Oracle server(this applies to Client version 8.1.5 only), WebLogic jDriver for Oracleconverts the characters from Unicode to the character set in use by thedatabase. The Oracle server then converts this data back into Unicode. Thisobvious inefficiency can be avoided by setting this property to true, in whichcase all communication will be made in Unicode, preventing unnecessary andexpensive character set translations from occurring. The default value for thisproperty is false.

Initializing a CLOB field

When you first insert a row containing a CLOB data type, you must insert the row withan “empty” CLOB before the field can be updated with real data. You can insert anempty CLOB with the Oracle EMPTY_CLOB() function.

To initialize a CLOB column:

1. Create a table with one or more columns defined as a CLOB data type.

2. Insert a new row with an empty CLOB column, using the Oracle EMPTY_CLOB()function:

stmt.execute("INSERT into myTable VALUES (1,EMPTY_CLOB()");


JDBC 2.0 for Oracle

3. Obtain an object for the CLOB column:

java.sql.Clob myClob = null;Statement stmt2 = conn.createStatement();stmt2.execute("SELECT myClobColumn from myTable");ResultSet rs = stmt2.getResultSet();while (rs.next) {myClob = rs.getClob("myClobColumn");

}

4. You can now write character data to the CLOB. If your data is in the ASCIIformat, Continue with the next section, Writing ASCII data to a CLOB. If yourcharacter data is in Unicode format, see Writing Unicode data to a CLOB

Writing ASCII data to a CLOB

To write ASCII character data to a CLOB column:

1. Obtain a “handle” to the CLOB as described above, in Initializing a CLOB field,step 3.

2. Create an object containing the character data:

String s = // some ASCII data

3. Create an ASCII output stream to which you write your CLOB characters. Notethat you must cast your CLOB object toweblogic.jdbc20.common.OracleClob.

java.io.OutputStream os =((weblogic.jdbc20.common.OracleClob)myclob).getAsciiOutputStream();

4. Write the input stream containing your ASCII data to the output stream. Thewrite operation is finalized when you call the flush() method on theOutputStream object.

byte[] b = s.getBytes("ASCII");

os.write(b);os.flush();

5. Clean up:

os.close();pstmt.close();conn.close();



Writing Unicode data to a CLOB

To write Unicode character data to a CLOB column:

1. Obtain a “handle” to the CLOB as described above, in Initializing a CLOB field,step 3.

2. Create an object containing the character data:

String s = // some Unicode character data

3. Create a character output stream to which you write your CLOB characters. Notethat you must cast your CLOB object toweblogic.jdbc20.common.OracleClob.

java.io.Writer wr =((weblogic.jdbc20.common.OracleClob)myclob).getCharacterOutputStream();

4. Write the input stream containing your ASCII data to the output stream. Thewrite operation is finalized when you call the flush() method on theOutputStream object.

char[] b = s.toCharArray(); // converts ’s’ to a character array

wr.write(b);wr.flush();

5. Clean up:

wr.close();pstmt.close();conn.close();

Writing CLOB objects

Writing a CLOB object to a table is performed with Prepared Statements. For example,to write the myClob object to the table myOtherTable:

PreparedStatement pstmt = conn.preparedStatement("UPDATE myOtherTable SET myOtherClobColumn = ? WHERE id = 12");

pstmt.setClob(1, myClob);


JDBC 2.0 for Oracle

Reading CLOB data

When a CLOB column is retrieved using a result set from a SQL SELECT statement,only a pointer to the CLOB data is returned; the actual data is not transferred to theclient with the result set until the getAsciiStream() method is called and thecharacters are read in to the stream.

To read CLOB data from an Oracle table:

1. Execute a SELECT statement:

java.sql.Clob myClob = null;Statement stmt2 = conn.createStatement();stmt2.execute("SELECT myClobColumn from myTable");

2. Use the results from the SELECT statement:

ResultSet rs = stmt2.getResultSet();

while (rs.next) {myClob = rs.getClob("myClobColumn");java.io.InputStream readClobis =

myReadClob.getAsciiStream();char[] c = new char[26];for (int i=0 ; i < 26 ; i++) {

c[i] = (char) readClobis.read();System.out.println("output [" + i + "] = " + c[i]);

}}

3. Clean up:

rs.close();stmt2.close();

Note: You can also use a CallableStatement to generate a ResultSet. ThisResultSet can then be used as shown above. See your JDK documentationunder java.sql.CallableStatment for details.

Other methods

The following methods of the java.sql.Clob interface are also implemented in theWebLogic jDriver for Oracle JDBC 2.0 driver. For details, see your JDKdocumentation:



� getSubString()

� length()

The position() method is not implemented.

Character and ASCII Streams

Some new methods are included in the JDBC 2.0 specification that allow character andASCII streams to be manipulated as characters rather than as bytes, as wasimplemented in earlier versions. The following methods for handling character andASCII streams are implemented in WebLogic jDriver for Oracle.

Unicode character Streams

getCharacterStream()

The java.sql.ResultSet interface uses this method for reading Unicodestreams as the Java type java.io.Reader. This method replaces thedeprecated getUnicodeStream() method.

setCharacterStream()

The java.sql.PreparedStatement interface uses this method for writinga java.io.Reader object. This method replaces the deprecatedsetUnicodeStream() method.

ASCII character streams

getAsciiStream()

The java.sql.ResultSet interface uses this method for reading ASCIIstreams as the Java type java.io.InputStream.

setAsciiStream()

The java.sql.PreparedStatement interface uses this method for writinga java.io.InputStream object.

For details on using these methods, consult your JDK documentation.


JDBC 2.0 for Oracle

Batch updates

Batch updates are a new feature of JDBC 2.0 that allows you to send multiple SQLupdate statements to the DBMS as a single unit. Depending on the application, this canprovide improved performance over sending multiple update statements individually.The Batch update feature is available in the Statement interface and requires the useof SQL statements that return an update count and do not return a result set. UsingBatch updates with the callableStatement or preparedStatement is notsupported.

The following SQL statements can be used with Batch updates:

� INSERT INTO

� UPDATE

� DELETE

� CREATE TABLE

� DROP TABLE

� ALTER TABLE

Using Batch updates

This is the basic procedure for using Batch updates:

1. Get a connection using the WebLogic jDriver for Oracle JDBC 2.0 driver asdescribed in Connecting to an Oracle DBMS on page 25. For this example, theconnection object is called “conn”.

2. Create a statement object using the createStatement() method. For example:

Statement stmt = conn.createStatement();

3. Use the addBatch() method to add SQL statements to the batch. Thesestatements will not be sent to the DBMS until the executeBatch() method iscalled. For example:

stmt.addBatch("INSERT INTO batchTest VALUES ('JOE', 20,35)");stmt.addBatch("INSERT INTO batchTest VALUES ('Bob', 30,44)");stmt.addBatch("INSERT INTO batchTest VALUES ('Ed', 34,22)");

4. Use the executeBatch() method to send the batch to the DBMS for processing.For example:



stmt.executeBatch();

If any of the statements fail an exception will be thrown, and none of thestatements will be executed.

Clearing the batch

You may clear a batch of statements that was created using addBatch() method withthe clearBatch() method. For example:

stmt.clearBatch();

Update counts

According to the JDBC 2.0 specification, the executeBatch() method should returnan array of Integers containing the number of rows updated for each Statement. TheOracle DBMS, however, does not supply this information to the driver. The OracleDBMS will instead return -2 for all updates.

Using with JDBC 1

If you are running your client application (or WebLogic Server, if WebLogic jDriverfor Oracle is being used in the middle tier) under JDK 1.1, you may use Batch updatesby casting your Statement object to weblogic.jdbc.oci.Statement. For example:

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


JDBC 2.0 for Oracle

New date methods

The following methods have a new signature which takes a java.util.Calendarobject as a parameter. java.util.Calendar allows you to specify time zone andlocation information that is used to translate dates. Consult your JDK API guide fordetails on using the java.util.Calendar class.

java.sql.ResultSet.getDate(int columnIndex, Calendar cal)

(returns a java.sql.Date object)

java.sql.PreparedStatement.setDate(int parameterIndex, Date x, Calendar cal)

java.sql.CallableStatement.getDate(int parameterIndex, Calendar cal)

(returns a java.sql.Date object)



Resources

For more information about

� using BLOBS and CLOBS, see the article Using SQL3 Datatypes, from Sun’sJava Tutorial, available athttp://java.sun.com/docs/books/tutorial/jdbc/jdbc2dot0/sql3.html.

� WebLogic Server and JNDI, see Using WebLogic JNDI, athttp://www.weblogic.com/docs51/classdocs/API_jndi.html.

� installing WebLogic JDBC drivers, see Installing JDBC Drivers, athttp://www.weblogic.com/docs51/install/install_jdbc.html.

� the JDBC 2.0 specification, see New Features in the JDBC 2.0 API, athttp://java.sun.com/docs/books/tutorial/jdbc/jdbc2dot0/index.html.

Code Examples

Oracle examples

Examples using JDBC 2.0 featuresBatch UpdatesBlobs and Clobs


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

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


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

http://www.weblogic.com/docs51/examples/jdbc/oracle20/examples.jdbc.oracle20.batchUpdate.html

http://www.weblogic.com/docs51/examples/jdbc/oracle20/examples.jdbc.oracle20.OracleBlobClob.html

http://www.weblogic.com/docs51/examples/jdbc/oracle/index.html

Upgrade

3 Release Notes for WebLogic jDriver for Oracle

Upgrade

This driver is now called WebLogic jDriver for Oracle. Its former name wasjdbcKona/Oracle.

WebLogic jDriver for Oracle has been updated to incorporate some of the featuresavailable in Oracle 8, such as Blobs and Clobs, and also for new features available inthe JDBC 2.0 specification (using JDBC 2.0 requires that you run your driver with aJDK 1.2.x JVM).

These changes require a different setting for your system PATH orld_library_path. For details, see Setting your path and client libraries on page 12.

WebLogic jDriver for Oracle is not available on all platforms in this release. SeeSetting your path and client libraries on page 12 for details.

Changes

jDriver for Oracle available for the HP-UX 11 platform.



WebLogic jDriver for Oracle (formerly called jdbcKona/Oracle) is now available forthe HP-UX 11 platform for Oracle client versions 8.0.4, 8.0.5, and 8.1.5. There aresome restrictions on its use. For more information, see Issues on page 68 and InstallingWebLogic jDriver for Oracle athttp://www.weblogic.com/docs51/install/install_jdbc.html.

For information on using new Oracle 8 and JDBC 2.0 features, see the DeveloperGuides Using jdbcKona/Oracle athttp://www.weblogic.com/docs51/classdocs/API_joci.html.

WebLogic jDriver for Oracle: Blobs and Clobs

The procedure for using Oracle Blobs and Clobs requires that you cast the Blob or Clobobject to weblogic.jdbc20.common.OracleClob orweblogic.jdbc20.common.OracleBlob.

Issues

Issue 9431.

WebLogic jDriver for Oracle is not supported when using the Oracle 8 APIand connecting to an version 7 Oracle DBMS.

Issue 9283

CallableStatement.getResultSet()with a defined ResultSet Cursor doesnot work when using the Oracle 8.1.5 DBMS on the Solaris operating system.

When using Oracle client version 8.0.5 and executing a CallableStatementwith a defined ResultSet Cursor, you must re-register the cursor prior to eachCallableStatement.getResultSet() call. For example:

weblogic.jdbc.common.OracleCallableStatement cstmt2 =(weblogic.jdbc.common.OracleCallableStatement)conn.prepareCall("{CALL single_cursor(?, ?)}");

cstmt2.registerOutParameter(1, java.sql.Types.OTHER);

// You can also set input parameters, execute the statement,// retrieve the query into a ResultSet, and print it// for each set of input parameters.





Issues

System.out.println("FIRST sproc 'single_cursor' exec for INT==1\n\n\n\n");

cstmt2.setInt(2, 1);cstmt2.execute();rs = cstmt2.getResultSet(1);

System.out.println("FIRST sproc 'single_cursor' exec forINT==2\n\n\n\n");

// Add the following line to re-register the cursor:cstmt2.registerOutParameter(1, java.sql.Types.OTHER);

cstmt2.setInt(2, 2);cstmt2.execute();rs = cstmt2.getResultSet(1);

Cross-platform incompatibility when using Oracle 8.0.5 and 8.1.5 clients running onHP.

The following combinations are known to be incompatible:

� Oracle 8.0.5 Client running on HP connecting to an Oracle 8.1.5 DBMSrunning on Windows NT or Solaris.

� Oracle 8.1.5 client running on HP connecting to an Oracle 8.1.5 DBMSrunning on Solaris.

Issue 9708

Using the CLOB datatype and using codeset conversions while running theOracle client and Oracle server on different operating systems will fail.

Issue 10026

jDriver for Oracle is only supported on HP when the Oracle client and Oracleserver are the same version. For example, an Oracle 8.0.5 client is onlysupported when connecting to an Oracle 8.0.5 server.


BEA WebLogic - · PDF fileTransaction boundaries ... Your feedback on the BEA WebLogic...

Documents

Transcript of BEA WebLogic - · PDF fileTransaction boundaries ... Your feedback on the BEA WebLogic...