Programmer’s Reference
jConnect™ for JDBC™
5.5
DOCUMENT ID: DC39001-01-0550-03
LAST REVISED: September 2003
Copyright © 1989-2003 by Sybase, Inc. All rights reserved.
This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions or technical notes.
Information in this document is subject to change without notice. The software described herein is furnished under a license agreement,
and it may be used or copied only in accordance with the terms of that agreement.
To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845.
Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other
international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled
software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic,
mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.
Sybase, the Sybase logo, AccelaTrade, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture,
Adaptive Server, Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server
Enterprise Replication, Adaptive Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, Anywhere Studio, Application
Manager, AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Translator, APT-Library, AvantGo,
AvantGo Application Alerts, AvantGo Mobile Delivery, AvantGo Mobile Document Viewer, AvantGo Mobile Inspection, AvantGo
Mobile Marketing Channel, AvantGo Mobile Pharma, AvantGo Mobile Sales, AvantGo Pylon, AvantGo Pylon Application Server,
AvantGo Pylon Conduit, AvantGo Pylon PIM Server, AvantGo Pylon Pro, Backup Server, BizTracker, ClearConnect, Client-Library,
Client Services, Convoy/DM, Copernicus, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer,
DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, Distribution Director, e-ADK,
E-Anywhere, e-Biz Integrator, E-Whatever, EC Gateway, ECMAP, ECRTP, eFulfillment Accelerator, Embedded SQL, EMS, Enterprise
Application Studio, Enterprise Client/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server
Manager, Enterprise Work Architecture, Enterprise Work Designer, Enterprise Work Modeler, eProcurement Accelerator, EWA,
Financial Fusion, Financial Fusion Server, Gateway Manager, GlobalFIX, ImpactNow, Industry Warehouse Studio, InfoMaker,
Information Anywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, Mail
Anywhere Studio, MainframeConnect, Maintenance Express, Manage Anywhere Studio, M-Business Channel, M-Business Network,
M-Business Server, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, My AvantGo, My AvantGo Media Channel,
My AvantGo Mobile Marketing, MySupport, Net-Gateway, Net-Library, New Era of Networks, ObjectConnect, ObjectCycle,
OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Biz, Open Client, Open ClientConnect, Open Client/Server, Open
Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, PB-Gen, PC APT Execute, PC
Net Library, PocketBuilder, Pocket PowerBuilder, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class
Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScript, PowerSite, PowerSocket, Powersoft, PowerStage,
PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst,
Rapport, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server, Replication Server Manager,
Replication Toolkit, Resource Manager, RW-DisplayLib, S-Designor, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian,
SKILS, smart.partners, smart.parts, smart.script, SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL
Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART,
SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQL Server SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, S.W.I.F.T.
Message Format Libraries, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server, Sybase Gateways, Sybase MPP,
Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User Workbench, SybaseWare, Syber Financial,
SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, TradeForce, Transact-SQL,
Translation Toolkit, UltraLite.NET, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual
Components, VisualSpeller, VisualWriter, VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse
WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup
SQL Server, XA-Library, XA-Server and XP Server are trademarks of Sybase, Inc. 03/03
Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.
All other company and product names used herein may be trademarks or registered trademarks of their respective companies.
Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-
7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.
Sybase, Inc., One Sybase Drive, Dublin, CA 94568.
Contents
Programmer’s Reference iii
About This Book.......................................................................................................................... vii
CHAPTER 1 Introduction ..................................................................................... 1
What is JDBC?................................................................................. 1
What is jConnect? ............................................................................ 2
CHAPTER 2 Programming Information.............................................................. 5
Setting up jConnect.......................................................................... 5
Setting the jConnect version ..................................................... 6
Invoking the jConnect driver.................................................... 11
Establishing a connection .............................................................. 11
Setting connection properties.................................................. 11
Connecting to Adaptive Server................................................ 20
Connecting to Adaptive Server Anywhere............................... 21
Connecting to a server using JNDI.......................................... 22
Implementing custom socket plug-ins ............................................ 28
SYBSOCKET_FACTORY connection property....................... 29
Creating and configuring a custom socket .............................. 29
Handling internationalization and localization ................................ 32
Using jConnect to pass Unicode data ..................................... 33
jConnect character-set converters .......................................... 34
Working with databases ................................................................. 39
Implementing high availability failover support........................ 40
Performing server-to-server remote procedure calls............... 45
Wide table support for Adaptive Server version 12.5 and later 46
Accessing database metadata ................................................ 47
Using cursors with result sets.................................................. 48
Support for batch updates ....................................................... 59
Updating a database from a result set of a stored procedure . 61
Working with datatypes ........................................................... 62
Implementing advanced features................................................... 68
Using event notification ........................................................... 69
Handling error messages ........................................................ 71
iv jConnect for JDBC
Storing Java objects as column data in a table ....................... 76
Dynamic class loading............................................................. 80
JDBC 2.0 optional package extensions support...................... 84
Restrictions on and interpretations of JDBC standards.................. 95
Connection.isClosed() and the IS_CLOSED_TEST connection
property............................................................................. 95
Statement.close() with unprocessed results............................ 96
Making adjustments for multithreading.................................... 97
Using ResultSet.getCursorName( ) ......................................... 98
Using setLong( ) with large parameter values ......................... 98
Using COMPUTE statements.................................................. 98
Executing stored procedures................................................... 99
CHAPTER 3 Troubleshooting.......................................................................... 101
Debugging with jConnect.............................................................. 101
Obtaining an instance of the Debug class ............................. 101
Turning on debugging in your application.............................. 102
Turning off debugging in your application.............................. 102
Setting the CLASSPATH for debugging ................................ 103
Using the Debug methods ..................................................... 103
Capturing TDS communication..................................................... 104
PROTOCOL_CAPTURE connection property....................... 105
pause( ) and resume( ) methods in the Capture class........... 105
Unsuccessful connection errors ................................................... 106
Gateway connection refused ................................................. 106
Unable to connect to a 4.9.2 SQL Server.............................. 107
Memory usage in jConnect applications....................................... 107
Stored procedure errors ............................................................... 108
RPC returns fewer output parameters than registered.......... 108
Fetch/state errors when output params returned................... 108
Stored procedure executed in unchained transaction mode . 109
Custom socket implementation error............................................ 109
CHAPTER 4 Performance and Tuning............................................................ 111
Improving jConnect performance ................................................. 111
BigDecimal rescaling ............................................................. 112
REPEAT_READ connection property.................................... 112
Character-set conversion....................................................... 113
Performance tuning for prepared statements in dynamic SQL..... 114
Choosing prepared statements and stored procedures......... 115
Prepared statements in portable applications........................ 115
Prepared statements with jConnect extensions..................... 116
Connection.prepareStatement( ) ........................................... 117
Contents
Programmer’s Reference v
DYNAMIC_PREPARE connection property.......................... 118
SybConnection.prepareStatement( ) .................................... 119
ESCAPE_PROCESSING_DEFAULT connection property... 120
Cursor performance ..................................................................... 120
LANGUAGE_CURSOR connection property ........................ 121
CHAPTER 5 Migrating jConnect Applications............................................... 123
Migrating jConnect applications ................................................... 123
Migrating applications to jConnect 4.5 and 5.5 ..................... 123
Sybase extensions....................................................................... 125
Change example ................................................................... 125
Method names....................................................................... 126
Debug class........................................................................... 126
CHAPTER 6 Web Server Gateways ................................................................ 127
About Web server gateways ........................................................ 127
TDS tunnelling....................................................................... 127
jConnect and gateway configuration ..................................... 128
Usage requirements..................................................................... 132
Reading the index.html file.................................................... 132
Running the sample Isql applet............................................. 133
Using the TDS-tunnelling servlet.................................................. 134
TDS-tunnelling servlet system requirements......................... 135
Installing the servlet............................................................... 136
Invoking the servlet ............................................................... 137
Tracking active TDS sessions............................................... 137
Resuming a TDS session...................................................... 138
TDS and Netscape Enterprise Server 3.5.1 on Solaris ......... 138
APPENDIX A SQL Exception and Warning Messages ................................... 141
APPENDIX B jConnect Sample Programs....................................................... 163
Running IsqlApp........................................................................... 163
Running jConnect sample programs and code ............................ 165
Sample applications .............................................................. 165
Sample code ......................................................................... 166
