Sybase Jconnect For JDBC PDF

Sybase® jConnect™ for JDBC™
Programmer’s Reference
jConnect for JDBC version 4.0

Last Revised: May 31, 1998
Principal author: David Gordon
Contributing authors: John Adams
This publication pertains to jConnect for JDBC version 4.0 of the Sybase database
management software and to any subsequent version 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.
Document Orders
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.
Copyright © 1989–1998 by Sybase, Inc. All rights reserved.
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 Trademarks
Sybase, the Sybase logo, APT-FORMS, Certified SYBASE Professional, Column
Design, Data Workbench, First Impression, InfoMaker, ObjectCycle, PowerBuilder,
PowerDesigner, Powersoft, Replication Server, S-Designor, SQL Advantage, SQL
Debug, SQL SMART, Transact-SQL, Visual Components, VisualWriter, and VQL
are registered trademarks of Sybase, Inc. Adaptable Windowing Environment,
Adaptive Component Architecture, Adaptive Server, Adaptive Server Anywhere,
Adaptive Server Enterprise Monitor, Adaptive Server IQ, Adaptive Warehouse,
ADA Workbench, AnswerBase, Application Manager, AppModeler, APT-Build,
APT-Edit, APT-Execute, APT-Library, APT-Translator, APT Workbench, Backup
Server, BayCam, Bit-Wise, ClearConnect, Client-Library, Client Services,
CodeBank, Connection Manager, DataArchitect, Database Analyzer, DataExpress,
Data Pipeline, DataWindow, DB-Library, dbQueue, Developers Workbench,
DirectConnect, Distribution Agent, Distribution Director, Embedded SQL, EMS,
Enterprise Client/Server, Enterprise Connect, Enterprise Manager, Enterprise SQL
Server Manager, Enterprise Work Architecture, Enterprise Work Designer,
Enterprise Work Modeler, EWA, Formula One, Gateway Manager, GeoPoint,
ImpactNow, InformationConnect, InstaHelp, InternetBuilder, iScript, Jaguar CTS,
jConnect for JDBC, KnowledgeBase, Logical Memory Manager,
MainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI
Database Gateway, media.splash, MetaBridge, MetaWorks, MethodSet, Net-
Gateway, NetImpact, Net-Library, Next Generation Learning, ObjectConnect,
OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, 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 DB-Net, PC Net Library, Power++, Power AMC, PowerBuilt,
PowerBuilt with PowerBuilder, Power Dynamo, Power J, PowerScript, PowerSite,
PowerSocket, Powersoft Portfolio, PowerStudio, Power Through Knowledge,
PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst, QuickStart
DataMart, QuickStart MediaMart, QuickStart ReportSmart, Replication Agent,
Replication Driver, Replication Server Manager, Report-Execute, Report
Workbench, Resource Manager, RW-DisplayLib, RW-Library, SAFE, SDF, Secure
SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners,
smart.parts, smart.script, SQL Code Checker, SQL Edit, SQL Edit/TPU, SQL
Modeler, SQL Remote, SQL Server, SQL Server/CFT, SQL Server/DBM, SQL
Server Manager, SQL Server SNMP SubAgent, SQL Station, SQL Toolset, Sybase
Central, Sybase Client/Server Interfaces, Sybase Development Framework,
Sybase Gateways, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase
SQL Workgroup, Sybase Synergy Program, Sybase Virtual Server Architecture,
Sybase User Workbench, SybaseWare, SyBooks, System 10, System 11, the System
XI logo, SystemTools, Tabular Data Stream, The Enterprise Client/Server
Company, The Future is Wide Open, The Learning Connection, The Model for
Client/Server Solutions, The Online Information Center, Translation Toolkit,
Turning Imagination Into Reality, UNIBOM, Unilib, Uninull, Unisep, Unistring,
URK Runtime Kit for UniCode, Viewer, VisualSpeller, WarehouseArchitect,
Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web.PB,
Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-
Server, and XP Server are trademarks of Sybase, Inc. 1/98
All other company and product names used herein may be trademarks or
registered trademarks of their respective companies.
Restricted Rights
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., 6475 Christie Avenue, Emeryville, CA 94608.
Table of Contents
1. Introduction
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Other Sources of Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Sybase Certifications on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Javadoc Documentation of jConnect Extensions to JDBC . . . . . . . . . . . . 1-3
If You Need Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
What is JDBC? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
What is jConnect? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
2. Programming Information
jConnect Installation Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
jConnect Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
JDK 1.1 Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Invoking the jConnect Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Setting Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Establishing a Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Connecting to Adaptive Server Enterprise . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Connecting to SQL Anywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Setting the jConnect Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
JCONNECT_VERSION Connection Property . . . . . . . . . . . . . . . . . . 2-15
Support for SSL Security Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
SSL_SOCKET_FACTORY Connection Property . . . . . . . . . . . . . . . . . . . 2-16
Creating and Configuring an SSL Socket . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Connecting to a Server Using JNDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Connection URL for Using JNDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Required Directory Service Information . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
CONNECTION_FAILOVER Connection Property . . . . . . . . . . . . . . . . . 2-20
Providing JNDI Context Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
jConnect Character-Set Converters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Selecting a Character-Set Converter . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Setting the CHARSET Connection Property . . . . . . . . . . . . . . . . . . . 2-24
Improving Character-Set Conversion Performance . . . . . . . . . . . . . 2-25
Supported Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25
Unsupported Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Accessing Database Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
jConnect for JDBC Programmer’s Reference v

CANCEL_ALL Connection Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28

Using Cursors with Result Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
Creating a Cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30
Positioned Updates and Deletes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32
JDBC 1.x Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32
JDBC 2.0 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-33
Using a Cursor with a Prepared Statement. . . . . . . . . . . . . . . . . . . . . . . . 2-35
Cursor Performance and the LANGUAGE_CURSOR Connection Property . . . . . . . . 2-36
LANGUAGE_CURSOR Connection Property . . . . . . . . . . . . . . . . . . . . . 2-36
Updating the Database from the Result Set of a Stored Procedure . . . . . . . . . . . . . 2-37
Performance Tuning for Prepared Statements in Dynamic SQL . . . . . . . . . . . . . . . . 2-38
Connection.prepareStatement(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38
DYNAMIC_PREPARE Connection Property . . . . . . . . . . . . . . . . . . . . . . 2-39
SybConnection.prepareStatement() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-40
Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-41
Prepared Statements in Portable Applications . . . . . . . . . . . . . . . . . 2-42
Prepared Statements in Applications with jConnect Extensions . . 2-42
Choosing Between Prepared Statements and Stored Procedures . . 2-43
Sending Image Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44
Public Methods in the TextPointer Class . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44
Updating an image Column with TextPointer.sendData() . . . . . . . . . . . . . 2-45
Getting a TextPointer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45
Executing the Update with TextPointer.sendData . . . . . . . . . . . . . . . . 2-47
Using Date and Time Datatypes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-47
Using Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48
Event Notification Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-49
Error-Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50
Retrieving Sybase-Specific Error Information . . . . . . . . . . . . . . . . . . . . . 2-51
Customizing Error Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52
Installing an Error-Message Handler . . . . . . . . . . . . . . . . . . . . . . . . . 2-53
Error Message Handler Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-53
Storing Java Objects as Column Data in a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-55
Prerequisites for Storing Java Objects As Column Data . . . . . . . . . . . . . 2-55
Sending a Java Object to a Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-56
Receiving Java Objects from the Database . . . . . . . . . . . . . . . . . . . . . . . . 2-57
Improving jConnect Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-59
BigDecimal Rescaling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-60
REPEAT_READ Connection Property. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-60
Restrictions and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61
Using setLong() with Large Parameter Values . . . . . . . . . . . . . . . . . . . . . 2-61
Compute Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61
vi Table of Contents
Executing Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61

Running IsqlApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62
jConnect Sample Programs and Sample Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-63
Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-63
Running the Sample Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-64
Running the Sample Programs with SQL Anywhere . . . . . . . . . . . . 2-64
Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-65
3. Troubleshooting
Debugging with jConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Importing the Debug Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Turning On Debugging in Your Application . . . . . . . . . . . . . . . . . . . . . . . 3-1
Turning Off Debugging in Your Application . . . . . . . . . . . . . . . . . . . . . . . 3-2
Setting the CLASSPATH for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Using the Debug Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Unsuccessful Connection Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
HTTP Server Address Already in Use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Gateway Connection Refused. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Unable to Connect to a 4.9.2 SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Stored Procedure Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
RPC Returns Fewer Output Parameters Than Registered . . . . . . . . . . . . 3-5
Fetch/State Error When Stored Procedure Returns Output Params . . . 3-6
Stored Procedure Executed in Unchained Transaction Mode . . . . . . . . . 3-6
Capturing TDS Communication Between Client and Server . . . . . . . . . . . . . . . . . . . . 3-6
PROTOCOL_CAPTURE Connection Property . . . . . . . . . . . . . . . . . . . . . 3-7
pause() and resume() Methods in the Capture Class . . . . . . . . . . . . . . . . . . 3-7
A. Web Server Gateways

About Web Server Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
TDS tunneling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
jConnect and Gateway Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
Web Server and SQL Server on One Host. . . . . . . . . . . . . . . . . . . . . . A-2
Dedicated JDBC Web Server and SQL Server on One Host. . . . . . . A-3
Web Server and SQL Server on Separate Hosts . . . . . . . . . . . . . . . . . A-5
Connecting to a Server Through a Firewall . . . . . . . . . . . . . . . . . . . . A-6
Using the TDS-tunneling Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
TDS-tunneling Servlet System Requirements . . . . . . . . . . . . . . . . . . . . . A-8
Installing the Servlet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Setting Servlet Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Invoking the Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9
jConnect for JDBC Programmer’s Reference vii

Tracking Active TDS Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

Terminating TDS Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Resuming a TDS Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Using the Cascade Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Installing the Cascade Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
Starting the Cascade Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
Windows NT and Windows 95 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
Testing the Cascade Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Read the index.html File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Running the Sample Isql Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14
Defining a Connection to the Cascade Gateway . . . . . . . . . . . . . . . . . . A-15
B. SQL Exception and Warning Messages
viii Table of Contents

1 Introduction 1.
The jConnect for JDBC Programmer’s Reference describes the

jConnect™ for JDBC™ product and explains how to use it to access
data stored in relational database management systems.
Audience
This manual is for database-application programmers who are
familiar with the Java programming language, JDBC, and Transact-
SQL®, the Sybase® version of Structured Query Language.
About This Book

The information in this book is organized as follows:
Chapter 1, “Introduction,” describes JDBC and jConnect.
Chapter 2, “Programming Information,” provides reference
information and examples that are specific to the jConnect driver.
Chapter 3, “Troubleshooting,” describes how to use jConnect’s
debugging feature, and provides solutions and workarounds for
problems you may encounter when using jConnect.
Appendix A, “Web Server Gateways.”
Appendix B, “SQL Exception and Warning Messages” lists the SQL
exception and warning messages that you may encounter while
using jConnect.
Other Sources of Information

Use the Sybase Technical Library CD and the Technical Library Web
site to learn more about your product:
• Technical Library CD contains product manuals and technical
documents and is included with your software. The DynaText
browser (included on the Technical Library CD) allows you to
access technical information about your product in an easy-to-
use format.
Refer to the Technical Library Installation Guide in your
documentation package for instructions on installing and
starting Technical Library.
jConnect for JDBC Programmer’s Reference 1-1

Other Sources of Information jConnect for JDBC version 4.0
• Technical Library Web site is an HTML version of the Technical

Library CD that you can access using a standard Web browser.
To use the Technical Library Web site, go to www.sybase.com
and choose Documentation, choose Technical Library, then
choose Product Manuals.
Sybase Certifications on the Web
Technical documentation at the Sybase Web site is updated

frequently.
For the latest information on product certifications and/or the EBF Rollups:
1. Point your Web browser to Technical Documents at the
following Web site:
techinfo.sybase.com
2. In the Browse section, click on the Hot entry.
3. Explore your area of interest: Hot Docs covering various topics,
or Hot Links to Technical News, Certification Reports, Partner
Certifications, and so on.
If you are a registered SupportPlus user:

following Web site:
techinfo.sybase.com
3. Click on the EBF Rollups entry.
You can research EBFs using Technical Documents, and you can
download EBFs using Electronic Software Distribution (ESD).
4. Follow the instructions associated with the SupportPlusSM
Online Services entries.
If you are not a registered SupportPlus user, and you want to become one:
You can register by following the instructions on the Web.
To use SupportPlus, you need:
• A Web browser that supports the Secure Sockets Layer (SSL),
such as Netscape Navigator 1.2 or later
1-2 Introduction
jConnect for JDBC version 4.0 If You Need Help
• An active support license

• A named technical support contact
• Your user ID and password
Whether or not you are a registered SupportPlus user:

You may use Sybase’s Technical Documents. Certification Reports
are among the features documented at this site.
following Web site:
techinfo.sybase.com
3. Click on the topic that interests you.
Javadoc Documentation of jConnect Extensions to JDBC
The Java Development Kit (JDK) from JavaSoft contains a javadoc

script for extracting comments from source-code files. This script has
been used to extract documentation of jConnect packages, classes,
and methods from jConnect source files. When you install jConnect,
the javadoc information is placed in the javadocs directory:
Installation_directory/docs/en/javadocs
If You Need Help

Each Sybase installation that has purchased a support contract has
one or more designated people who are authorized to contact Sybase
Technical Support. If you cannot resolve a problem using the
manuals or online help, ask a designated person at your site to
contact Sybase Technical Support.
What is JDBC?
JDBC from JavaSoft is a specification for an application program
interface (API) that allows Java applications to access multiple
database management systems using Structured Query Language
(SQL). The JDBC driver manager handles multiple drivers that
connect to different databases.

What is jConnect? jConnect for JDBC version 4.0
A set of interfaces is included in the standard JDBC API so you can

open connections to databases, execute SQL commands, and process
results. The interfaces are described in Table 1-1.
Table 1-1: JDBC interfaces
Interface Description
java.sql.Driver Locates the driver for a database URL
java.sql.Connection Connection to a specific database
java.sql.Statement Executes SQL statements
java.sql.PreparedStatement Handles parameterized SQL statements
java.sql.CallableStatement Handles database stored procedure calls
java.sql.ResultSet Gets the results of SQL statements
java.sql.DatabaseMetaData Used to access a variety of information
about a Connection’s DBMS and database
java.sql.ResultSetMetaData Used to access a variety of information
describing a ResultSet’s attributes
Each relational database management system requires a driver to

implement these interfaces. All JDBC calls are sent to the JDBC driver
manager, which passes the call to the specified driver.
There are four types of JDBC drivers:
• JDBC-ODBC bridge – Translates JDBC calls into ODBC calls and
passes them to an ODBC driver. Some ODBC software must be
resident on the client machine. Some client database code may
also reside on the client machine.
• Native-API/partly Java – Converts JDBC calls into database-
specific calls. This driver, which communicates directly with the
database server, also requires some binary code on the client
machine.
• Net-protocol/all Java – Communicates to a middle-tier server
using a DBMS-independent net protocol. A middle-tier gateway
then converts the request to a vendor-specific protocol.
• Native-protocol/all Java – Converts JDBC calls to the vendor-
specific DBMS protocol, allowing client applications direct
communication with the database server.
What is jConnect?
The Sybase jConnect driver is both a:
• Net-protocol/all-Java driver within a three-tier environment,
and
1-4 Introduction
jConnect for JDBC version 4.0 What is jConnect?
• Native-protocol/all-Java driver within a two-tier environment.

The protocol used by jConnect is TDS 5.0 (Tabular Data Stream™,
version 5), the native protocol for Adaptive Server™ and Open
Server™ applications. jConnect implements the JDBC standard to
provide optimal connectivity to the complete family of Sybase
products, allowing access to 25 enterprise and legacy systems,
including:
• Adaptive Server Enterprise
• SQL Anywhere™
• Adaptive Server IQ™ (formerly Sybase IQ™)
• Replication Server®
• OmniConnect™
➤ Note
Since changing the name of Sybase SQL Server™ to Adaptive Server
Enterprise, Sybase uses the names Adaptive Server and Adaptive Server
Enterprise to refer collectively to all supported versions of Sybase SQL
Server and Adaptive Server Enterprise.

What is jConnect? jConnect for JDBC version 4.0
1-6 Introduction
2 Programming Information 2.
This chapter describes the basic components, programming

requirements, and debugging utilities that comprise jConnect for
JDBC. It explains how to invoke the jConnect driver, set connection
properties, and connect to a database server. In addition, it contains
information about implementing jConnect features and tuning
jConnect performance. It includes a sample application that
demonstrates the basic requirements.
➤ Note
For information about JDBC programming, visit the JavaSoft Web site. To
access JavaSoft’s JDBC Guide: Getting Started manual, go to:
http://www.javasoft.com/products/jdk/1.1/docs/guide/jdbc/
The following topics are included in this chapter:

• jConnect Installation Contents (page 2-2)
• jConnect Packages (page 2-4)
• Invoking the jConnect Driver (page 2-5)
• Setting Driver Connection Properties (page 2-5)
• Establishing a Connection (page 2-10)
• Setting the jConnect Version (page 2-12)
• Support for SSL Security Protocol (page 2-15)
• Connecting to a Server Using JNDI (page 2-18)
• jConnect Character-Set Converters (page 2-23)
• Accessing Database Metadata (page 2-28)
• CANCEL_ALL Connection Property (page 2-28)
• Using Cursors with Result Sets (page 2-29)
• Cursor Performance and the LANGUAGE_CURSOR Connection
Property (page 2-36)
• Updating the Database from the Result Set of a Stored Procedure
(page 2-37)
• Performance Tuning for Prepared Statements in Dynamic SQL
(page 2-38)
• Sending Image Data (page 2-44)

jConnect Installation Contents jConnect for JDBC version 4.0
• Using Date and Time Datatypes (page 2-47)

• Using Event Notification (page 2-48)
• Error-Message Handling (page 2-50)
• Storing Java Objects as Column Data in a Table (page 2-55)
• Improving jConnect Performance (page 2-59)
• Restrictions and Limitations (page 2-61)
• Running IsqlApp (page 2-62)
• jConnect Sample Programs and Sample Code (page 2-63)
jConnect Installation Contents

Table 2-1 lists the files and directories included in a jConnect for
JDBC installation.
Table 2-1: jConnect installation contents
Name Type Description

classes Directory Contains:
• com subdirectory for jConnect classes.
• uk subdirectory with the compiled version
of the Cascade gateway.
• sample subdirectory with class files for
sample applets and applications,
including IsqlApp and IsqlUtility.
devclasses Directory Contains the same components as the classes
directory, but debug mode is turned on.
2-2 Programming Information

jConnect for JDBC version 4.0 jConnect Installation Contents

docs Directory Contains HTML and Adobe Acrobat versions
of the jConnect Programmer’s Reference and the
jConnect javadoc documentation. The
Programmer’s Reference is located in one of the
following subdirectories, based on the
language chosen for installation:
• The en subdirectory, which contains the
English version of the Programmer’s
Reference.
• The de subdirectory, which contains the
German version of the Programmer’s
Reference.
• The fr subdirectory, which contains the
French version of the Programmer’s
Reference.
• The ja subdirectory, which contains the
Japanese version of the Programmer’s
Reference.
The javadoc documentation is located in the
javadocs subdirectory under en. The javadoc
documentation is available in English only.
gateway Directory • Contains classes for the TDS-tunnelling
servlet.
httpd.bat Command file Starts the Cascade gateway on Windows NT
and Windows 95.
httpd.sh Command file Starts the Cascade gateway on UNIX
platforms.
Note: This file is not installed with execute
permission. You must either change the file
permission before you run httpd.sh or
execute the command sh httpd.sh.
index.html HTML file Contains links to jConnect documentation
and to sample applets that you can run in
your browser.
mime.types File Provides file extension mapping used by the
Cascade gateway.
props.dat Configuration Contains configuration information about the
file current jConnect installation. Used to
safeguard configuration information during
an upgrade. Do not move or modify this file.

jConnect Packages jConnect for JDBC version 4.0

sample Directory Contains source code for sample Java
applications.
sp Directory Contains isql scripts that install stored
procedures for function escapes and
DatabaseMetaData methods on a database
server. The scripts are:
• sql_anywhere.sql
• sql_server.sql
uk Directory Contains the source code for the Cascade
gateway. For more information, see:
http://uk/org/cascade/sybase/http/
README
www.dos File Cascade gateway configuration file for
Windows NT and Windows 95. You must
modify this file to point to the jConnect
installation directory if you did not use the
default installation directory.
www.template File Cascade gateway configuration file for UNIX
and other platforms.
jConnect Packages
jConnect consists of the following packages in the jConnect
installation directory:
com.sybase.jdbc
com.sybase.tds
com.sybase.timedio
com.sybase.utils
The jConnect driver is in the com.sybase.jdbc package:
com.sybase.jdbc.SybDriver

jConnect for JDBC version 4.0 Invoking the jConnect Driver
JDK 1.1 Samples
You can find JDK 1.1 code samples in the sample subdirectory under
the jConnect installation directory. See “jConnect Sample Programs
and Sample Code” on page 2-63.
Invoking the jConnect Driver

There are two suggested way to register and invoke the Sybase
jConnect driver:
• Add the jConnect driver to the jdbc.drivers system property. At
initialization, the DriverManager class attempts to load the drivers
listed in jdbc.drivers. You can list multiple drivers in this property,
separated with a colon (:). The following code sample shows how
to add a driver to jdbc.drivers within a program:
Properties sysProps = System.getProperties();
StringBuffer drivers = new
StringBuffer("com.sybase.jdbc.SybDriver");
String oldDrivers =
sysProps.getProperty("jdbc.drivers");
if (oldDrivers != null)
drivers.append(":" + oldDrivers);
sysProps.put("jdbc.drivers", drivers.toString());
➤ Note
System.getProperties() is not allowed for Java applets. Use the Class.forName()
method, described below.
• Use Class.forName().newInstance to create an instance of

com.sybase.jdbc.SybDriver. This is more efficient than the previous
approach.
The following example creates an instance of
com.sybase.jdbc.SybDriver. SybDriver contains initialization code that
registers an instance as a driver at the time it is created.
Class.forName("com.sybase.jdbc.SybDriver").newInstance();
Setting Driver Connection Properties

Table 2-2 lists the connection properties for jConnect and indicates
their default values. Set the connection properties before you make a
connection.

Setting Driver Connection Properties jConnect for JDBC version 4.0
There are two ways to set the driver connection properties:

• In your application using the DriverManager.getConnection() method.
• When you define the URL. See “Establishing a Connection” on
page 2-10.
➤ Note
Driver connection properties set in the URL do not override any
corresponding connection properties set in the application using the
DriverManager.getConnection() method.
To obtain a current list of properties for any driver, use the

Driver.getDriverProperties() method.
➤ Note
Driver connection property names are not case-sensitive. jConnect uses
the prop.equalsIgnoreCase() method to make property names case-
insensitive.
Table 2-2: Connection properties
Default
Property Description
Value
APPLICATIONNAME A user-defined property. The server side can be Null
programmed to interpret the value given to this
property.
CANCEL_ALL Determines the behavior of the Statement.cancel() Depends on
method. If CANCEL_ALL is “false,” Statement.cancel() version
cancels only the Statement object it is invoked on. If setting. (See
CANCEL_ALL is “true,” Statement.cancel() cancels not “Setting the
only the object it is invoked on, but also any other jConnect
Statement objects that have already begun to execute and Version” on
are waiting for results. See “CANCEL_ALL Connection page 2-12.)
Property” on page 2-28.
CHARSET Specifies the character set for strings passed through Null
TDS. If you specify a charset, it must match a charset
listed in syscharsets.
If null, jConnect uses the server’s default charset.

jConnect for JDBC version 4.0 Setting Driver Connection Properties
Default
Value
CHARSET_CONVERTER_ You can use this property to specify the character-set com.sybase.
CLASS converter class you want jConnect to use, either the utils.Pure-
TruncationConverter class or the PureConverter class. See Converter
“Selecting a Character-Set Converter” on page 2-23.
CONNECTION_FAILOVER For use with the Java Naming and Directory Interface true
(JNDI). When set to “true,” jConnect can make multiple
attempts to connect to a server. If one attempt to connect
to a host and port number associated with a server fails,
jConnect uses JNDI to get the next host and port
number associated with the server and attempts to
connect through them. See
“CONNECTION_FAILOVER Connection Property” on
page 2-20.
DYNAMIC_PREPARE Determines whether dynamic SQL prepared statements false
are precompiled in the database. If “true,” prepared
statements are precompiled, if “false,” they are sent to
the database and compiled with each use. See
“DYNAMIC_PREPARE Connection Property” on page
2-39.
EXPIRESTRING A read-only property that contains the license Never
expiration date. Expiration is “never” except for
evaluation copies of jConnect.
HOSTNAME The name of the current host. None
HOSTPROC Identifies the application’s process on the host machine. None
JCONNECT_VERSION Use this property to set version-specific characteristics. 2
See “JCONNECT_VERSION Connection Property” on
page 2-15.
LANGUAGE Set this property for error messages returned from the Depends on
server and for jConnect messages. It must match a version
language in syslanguages. setting. (See
“Setting the
jConnect
Version” on
page 2-12.)
LANGUAGE_CURSOR Set this property to true if you want jConnect to use false
“language cursors” instead of “protocol cursors.”
Protocol cursors are new in jConnect 4.0 and offer better
performance than language cursors. See “Cursor
Performance and the LANGUAGE_CURSOR
Connection Property” on page 36.

Setting Driver Connection Properties jConnect for JDBC version 4.0
Default
Value
LITERAL_PARAMS This property is for SQL Anywhere. false
When set to “true,” any parameters set by the setXXX
methods in the PreparedStatement interface are inserted
literally into the SQL statement when it is executed.
If set to “false,” parameter markers are left in the SQL
statement and the parameter values are sent to the
server separately.
PACKETSIZE Network packet size. 512
password Login password. None
Set automatically if using the getConnection(String, String,
String) method, or explicitly if using getConnection(String,
Props).
PROTOCOL_CAPTURE The PROTOCOL_CAPTURE connection property is Null
used to specify a file for capturing TDS communication
between an application and an Adaptive Server. You
can send the file, which contains binary data and is not
directly interpretable, to Sybase Technical Support for
analysis. See “Capturing TDS Communication Between
Client and Server” on page 3-6 in Chapter 3,
“Troubleshooting.”
PROXY Gateway address. For the HTTP protocol, the URL is: None
http://host:port.
To use the HTTPS protocol that supports encryption, the
URL is https://host:port/servlet_alias.
REMOTEPWD Remote server passwords for access via DirectConnect. None
REPEAT_READ When REPEAT_READ is set to “true,” the driver keeps true
copies of columns and output parameters so that
columns can be read out of order or repeatedly. If this is
not required, more efficient performance can be
obtained by setting REPEAT_READ to “false.” See
“REPEAT_READ Connection Property” on page 2-60
SERVICENAME The name of a back-end database server that a None
DirectConnect gateway serves.
SESSION_ID When this property is set, jConnect assumes that an Null
application is trying to resume communication on an
existing TDS session held open by the TDS-tunnelling
gateway. jConnect skips the login negotiations and
forwards all requests from the application to the
specified session ID.

jConnect for JDBC version 4.0 Setting Driver Connection Properties
Default
Value
SESSION_TIMEOUT Use this property to specify the amount of time (in Null
seconds) that a server connection can remain idle before
the connection is automatically closed.
SQLINITSTRING Use this property to define a set of commands to be Null
passed to the back-end database server. These must be
SQL commands that can be executed using the
Statement.executeUpdate() method.
SSL_SOCKET_FACTORY To use SSL with jConnect, set SSL_SOCKET_FACTORY Null
either to the name of a class that extends
javax.net.ssl.SSLSocketFactory and can create SSL sockets
or to “DEFAULT,” which allows you to use
javax.net.ssl.SSLSocketFactory.getDefault(). See “Support
for SSL Security Protocol” on page 2-15.
STREAM_CACHE_SIZE Maximum size used to cache statement response Null
streams. (unlimited
cache size)
USE_METADATA When set to “true” (the default setting) a true
DatabaseMetaData object will be created and initialized
when establishing a connection. The DatabaseMetaData
object is necessary for connecting to a database specified
If you do not need to connect to a database specified in
the URL or use DatabaseMetaData for application
purposes, you can set this property to “false,” which
will result in a faster connection time.
user Login ID. None
Set automatically if using the getConnection(String, String,
String) method, or explicitly if using getConnection(String,
Props).
VERSIONSTRING Read-only version information for the JDBC driver. jConnect
driver
version
The following code is an example of setting connection properties.

The sample programs provided with jConnect also contain examples
of setting these properties.

Establishing a Connection jConnect for JDBC version 4.0
Properties props = new Properties();

props.put("user", "userid");
props.put("password", "user_password");
/*
* If the program is an applet that wants to access
* a server that is not on the same host as the
* web server, then it uses a proxy gateway.
*/
props.put("proxy", "localhost:port");
/*
* Make sure you set connection properties before
* attempting to make a connection. You can also
* set the properties in the URL.
*/
Connection con = DriverManager.getConnection("jdbc:
sybase:Tds:host:port", props);
Establishing a Connection
This section describes how to establish a connection to an Adaptive
Server Enterprise or SQL Anywhere database using jConnect.
Connecting to Adaptive Server Enterprise
In your Java application, define a URL using the jConnect driver to

connect to an Adaptive Server. The basic format of the URL is:
jdbc:sybase:Tds:host:port
where:
jdbc:sybase – Identifies the driver.
Tds – The Sybase communication protocol for Adaptive Server.
host:port – The Adaptive Server host name and listening port.
See the interfaces file $SYBASE/interfaces (UNIX) or
%SYBASE%\ini\sql.ini (Windows) for the entry that your
database or Open Server application uses. Obtain the
hostname/port from the “query” entry.
You can connect to a specific database using this format:
jdbc:sybase:Tds:host:port/database
Example
The following code creates a connection to an Adaptive Server on
host “myserver” listening on port 3697:

jConnect for JDBC version 4.0 Establishing a Connection
SysProps.put("user","userid");
SysProps.put("password","user_password");
String url = "jdbc:sybase:Tds:myserver:3697";
Connection _con =
DriverManager.getConnection(url,SysProps);
URL Connection Property Parameters

You can specify the values for the jConnect driver connection
properties when you define a URL.
➤ Note
Driver connection properties set in the URL do not override any
corresponding connection properties set in the application using the
DriverManager.getConnection() method.
To set a connection property in the URL, append the property name

and its value to the URL definition. Use this syntax:
jdbc:sybase:Tds:host:port/database?
property_name=value
To set multiple connection properties, append each additional
connection property and value, preceded by “&”. For example:
jdbc:sybase:Tds:myserver:1234/mydatabase?
LITERAL_PARAMS=true&PACKETSIZE=512&HOSTNAME=myhost
If the value for one of the connection properties contains ‘&’, precede
the ‘&’ in the connection property value with a backslash (\). For
example, if your host name is ‘a&bhost’, use this syntax:
jdbc:sybase:Tds:myserver:1234/mydatabase?
LITERAL_PARAMS=true&PACKETSIZE=512&HOSTNAME=
a\&bhost
Do not use quotes for connection property values, even if they are
strings. For example, use:
HOSTNAME=myhost
not:
HOSTNAME="myhost"

Setting the jConnect Version jConnect for JDBC version 4.0
Connecting to SQL Anywhere
To connect to SQL Anywhere via jConnect, you must run the SQL
Anywhere Open Server Gateway dbos50, which is distributed with
SQL Anywhere.
➤ Note
The free download version of SQL Anywhere available from the Powersoft
Web site does not include this Open Server Gateway. Call Powersoft at
(800) 265-4555 to receive a CD that includes the Open Server Gateway
and the required Open Server DLLs. You will be charged for shipping and
handling.
1. Install Open Server Gateway 5.5.03 or later and the Open Server
DLLs. Use Open Server DLLs, version 11.1.
2. Add an entry for the gateway to your %SYBASE%\ini\sql.ini
file (for example, with sqledit).
3. Start the gateway to the demonstration database included with
SQL Anywhere by entering:
start dbos50 gateway-demo
where gateway-demo is the gateway name defined in step 2.
4. When the Open Server gateway is running, you can define a
connection as follows:
host is the host name where the SQL Anywhere and Open Server
gateway is running, and port is the port number defined in
sql.ini.
➤ Note
To support multiple SQL Anywhere databases, use sqledit to add an entry
with a different port for each database, then run the Open Server Gateway
for each database.
Setting the jConnect Version

jConnect uses a version setting to determine:
• The default value of the LANGUAGE connection property.

jConnect for JDBC version 4.0 Setting the jConnect Version
• The default character set, if no character set is specified through

the CHARSET connection property.
• The default value of the CHARSET_CONVERTER connection
property.
• The default value of the CANCEL_ALL connection property and
the behavior of Statement.cancel().
• The availability of JDBC 2.0 methods for storing and retrieving
Java objects as column data.
Table Table 2-3 lists the version settings available and their features.
Table 2-3: jConnect version settings and their features
Version Features Comments

VERSION_2 • The default value of the VERSION_2 is the default version setting.
LANGUAGE connection property
The LANGUAGE connection property
is us_english.
determines the language in which messages
• If the CHARSET connection from the jConnect driver and messages from
property does not specify a the server appear.
character set, the default character
For information on the CHARSET and
set is iso_1.
CHARSET_CONVERTER connection classes,
• The default value for see “jConnect Character-Set Converters” on
CHARSET_CONVERTER is the page 2-23.
TruncationConverter class, unless the
The VERSION_2 default behavior of
CHARSET connection property
Statement.cancel() is not JDBC-compliant. In
specifies a multibyte or 8-bit
jConnect 4.0, you can use the CANCEL_ALL
character set, in which case the
connection property to set the behavior of
default CHARSET_CONVERTER
Statement.cancel(). See “CANCEL_ALL
is the PureConverter class.
Connection Property” on page 2-28.
• By default, Statement.cancel()
cancels the object it is invoked on
and any other Statement objects that
have begun to execute and are
waiting for results.

Setting the jConnect Version jConnect for JDBC version 4.0
Table 2-3: jConnect version settings and their features
Version Features Comments

VERSION_3 • The default value of the See the comments for VERSION_2.
LANGUAGE connection property
is us_english.
• If the CHARSET connection
property does not specify a
character set, jConnect uses the
database’s default character set.
• The default value for
CHARSET_CONVERTER is the
PureConverter class.
• By default, Statement.cancel()
cancels the object it is invoked on
and any other Statement objects that
have begun to execute and are
waiting for results.
VERSION_4 • The default value of the Messages from the server are localized
LANGUAGE connection property according to the language setting in your
is null. local user environment. The languages
supported are: Chinese, US English, French,
• If the CHARSET connection
German, Japanese, Korean, Portuguese, and
property does not specify a
Spanish.
character set, jConnect uses the
database’s default character set.The The default behavior of Statement.cancel() is
default value for JDBC compliant.
CHARSET_CONVERTER is the
You can use the CANCEL_ALL connection
PureConverter class.
property to set the behavior of
• By default, Statement.cancel() Statement.cancel(). See “CANCEL_ALL
cancels only the Statement object it is Connection Property” on page 2-28.
invoked on.
For information on Java objects as column
• JDBC 2.0 methods can be used to data, see “Storing Java Objects as Column
store and retrieve Java objects as Data in a Table” on page 2-55.
column data.
The version values are constant values from the SybDriver class. When
referring to the version constant, use the following syntax:
com.sybase.jdbc.SybDriver.VERSION_2
Use SybDriver.setVersion() to set the jConnect version. The following
code sample shows how to load the jConnect driver and set the
version to VERSION_4.

jConnect for JDBC version 4.0 Support for SSL Security Protocol
import com.sybase.jdbc.SybDriver;
import java.sql.*;
...
SybDriver d = new SybDriver();
d.setVersion(SybDriver.VERSION_4);
DriverManager.registerDriver(d);
You can call setVersion() multiple times to change the version setting.
New connections inherit the behavior associated with the version
setting at the time the connection is made. Changing the version
setting during a session does not affect the current connection.
As described in the next section, you can use the
JCONNECT_VERSION connection property to override the SybDriver
version setting and specify a different version setting for an
individual connection.
JCONNECT_VERSION Connection Property
The JCONNECT_VERSION connection property allows you to

specify the jConnect version setting that is to be used for an
individual session.You can set JCONNECT_VERSION to an integer
value of “2,” “3,” or “4,” depending on the version characteristics
you want (see Table 2-3 on page 2-13).
Support for SSL Security Protocol

jConnect 4.0 provides support for the Secure Sockets Layer (SSL)
protocol. SSL is a security protocol for protecting TCP/IP
communication between a client and server. SSL provides three basic
security features:
• Encryption, to ensure the privacy of communication
• Authentication, to verify the identity of a client or server and
prevent impersonations or message forgeries
• Message verification, to make sure that a message has not been
tampered with
When jConnect is used with SSL, all TDS communication sent to the
server is encrypted.

Support for SSL Security Protocol jConnect for JDBC version 4.0
➤ Note
jConnect with SSL is for Java client applications that need to establish a
secure connection with a server. Currently, no Sybase servers support
SSL. Support is planned in future Sybase products.
An applet that needs a secure connection should use an HTTPS gateway.

See Appendix A, “Web Server Gateways.”
To use SSL with jConnect 4.0, you need to:

• Provide a Java class that extends javax.net.ssl.SSLSocketFactory and
implements SSL.
As discussed under “Creating and Configuring an SSL Socket”
on page 2-17, your extension to javax.net.ssl.SSLSocketFactory must
be able to create an instance of a socket and configure it for SSL
communication before it returns the instance to jConnect.
• Set the SSL_SOCKET_FACTORY connection property so that
jConnect can use your extension of SSLSocketFactory to create an
SSL socket.
The following sections describe how to use SSL with jConnect. They
discuss the following topics:
• SSL_SOCKET_FACTORY Connection Property
• Creating and Configuring an SSL Socket
SSL_SOCKET_FACTORY Connection Property
To use SSL with jConnect, you set the SSL_SOCKET_FACTORY

connection property to a string that is either:
• The name of a class that extends javax.net.ssl.SSLSocketFactory and
can create SSL sockets
or
• “DEFAULT”
In this case, SSLSocketFactory.getDefault() must be able to return an
instance of a default SSL factory class that extends
javax.net.ssl.SSLSocketFactory and can create SSL sockets.
jConnect 4.0 uses the value of the connection property to get an
instance of an SSL socket, as in the following example, which is based

jConnect for JDBC version 4.0 Support for SSL Security Protocol
on jConnect source code. In the example, factory is a String object

containing the value assigned to SSL_SOCKET_FACTORY.
...
if (factory.equals("DEFAULT"))
{
ssl_factory = SSLSocketFactory.getDefault();
}
else
{
ssl_factory =
(SocketFactory)Class.forName(factory).newInstance();
}
socket = (Socket) ssl_factory.createSocket(hostname, portnumber);
Creating and Configuring an SSL Socket
Once jConnect gets an SSL socket, as shown in the code example of

the preceding section, it uses the socket to connect to a database. Any
configuration of the socket for SSL communication must be
completed before the socket is returned to jConnect.
The following example shows how an implementation of SSL can
create an instance of an SSL socket, configure it, and then return it. In
the example, the class MySSLSocketFactory extends SSLSocketFactory and
implements SSL. It contains a createSocket() method that creates an SSL
socket, invokes SSLSocket.setEnabledCipherSuites() to specify the cipher
suites available for encryption, and returns the socket.
public class MySSLSocketFactory extends SSLSocketFactory
{
/**
* Create a socket, set the cipher suites it can use, return
* the socket.
*/
public Socket createSocket(String host, int port)
throws java.io.IOException, UnknownHostException
{
// Prepare an array containing the cipher suites that are to
// be enabled.
String enableThese[] =
{
"SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA",
"SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5",

Connecting to a Server Using JNDI jConnect for JDBC version 4.0
"SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA"
};
Socket s =
SSLSocketFactory.getDefault().createSocket(host,
port);
((SSLSocket)s).setEnabledCipherSuites(enableThese);
return s;
}
//Additional MySSLSocketFactory methods
...
}
Connecting to a Server Using JNDI

In jConnect 4.0, you can use the Java Naming and Directory Interface
(JNDI) to provide connection information, which offers these:
• Host names and ports for connecting to a server can be
maintained in a central location. You do not need to hard code a
specific host and port number in an application.
• In a centralized location, you can specify connection properties
and a default database for all applications to use.
• You can use the jConnect 4.0 CONNECTION_FAILOVER
property for handling unsuccessful connection attempts. When
CONNECTION_FAILOVER is set to “true,” if its initial
connection attempt fails, jConnect attempts to connect to a
sequence of host/port server addresses in the JNDI name space
until one succeeds.
To use jConnect with JNDI, you need to make sure that certain
information is available in any directory service that JNDI accesses
and that required information is set in the javax.naming.Context class.
This section covers the following topics:
• Connection URL for Using JNDI
• Required Directory Service Information
• CONNECTION_FAILOVER Connection Property
• Providing JNDI Context Information
Connection URL for Using JNDI
To specify that jConnect is to use JNDI for obtaining connection

information, place “jndi” as the URL’s subprotocol after “sybase”:

jConnect for JDBC version 4.0 Connecting to a Server Using JNDI
jdbc:sybase:jndi:protocol-information-for-use-with-JNDI
Anything that follows “jndi” in the URL is handled through JNDI.
For example, to use JNDI with the Lightweight Directory Access
Protocol (LDAP), you might enter:
jdbc:sybase:jndi:ldap://LDAP_hostname:port_number/servername=
Sybase11,o=MyCompany,c=US
This URL tells JNDI to obtain information from an LDAP server,
gives the host name and port number of the LDAP server to use, and
provides the name of a database server in an LDAP-specific form.
Required Directory Service Information
When JNDI is used with jConnect, it needs to return the following

information for the target database server:
• A host name and port number to connect to
• The name of the database to use
• Any connection properties that individual applications are not
allowed to set on their own
This information needs to be stored according to a fixed format in
any directory service used for providing connection information.
The required format consists of a numerical object identifier (OID),
which identifies the type of information being provided (for
example, the destination database), followed by the formatted
information. The table below shows the required formatting. It is
followed by an example.
Table 2-4: Directory service information required for JNDI
Type of
Object Identifier (OID) Format Comments
Information
Host and port 1.3.6.1.4.1.897.4.2.5 TCP#1#hostname portnumber Multiple hosts and
ports can be specified
as separate entries.
This allows use of the
CONNECTION-
_FAILOVER
connection property.

Table 2-4: Directory service information required for JNDI
Type of
Object Identifier (OID) Format Comments
Information
Connection 1.3.6.1.4.1.897.4.2.10 Prop1=value&Prop2=value&Prop3= Multiple connection
property value&... properties can be
specified by using a
separate entry for
each property or by
putting multiple
properties, separated
by ampersands, in a
single entry.
Database 1.3.6.1.4.1.897.4.2.11 databasename
Connection 1.3.6.1.4.1.897.4.2.9 Tds Optional. If a
protocol connection protocol
is specified, it must
always be “Tds”.
The following example shows connection information entered for

the database server SYBASE11 under an LDAP directory service:
dn: servername=SYBASE11,o=MyCompany,c=US
servername: SYBASE11
1.3.6.1.4.1.897.4.2.5:TCP#1#giotto 1266
1.3.6.1.4.1.897.4.2.5:TCP#1#giotto 1337
1.3.6.1.4.1.897.4.2.5:TCP#1#standby1 4444
1.3.6.1.4.1.897.4.2.10:REPEAT_READ=false&PACKETSIZE=1024
1.3.6.1.4.1.897.4.2.10:CONNECTION_FAILOVER=true
1.3.6.1.4.1.897.4.2.11:pubs2
1.3.6.1.4.1.897.4.2.9:Tds
In the preceding example, SYBASE11 can be accessed through either
port 1266 or port 1337 on host “giotto” and it can be accessed through
port 4444 on host “standby1.” Two connection properties,
REPEAT_READ and PACKETSIZE, are set within one entry. The
CONNECTION_FAILOVER connection property is set as a separate
entry. Applications connecting to SYBASE11 are initially connected
with the pubs2 database. A connection protocol does not need to be
specified, but if it is, it must be TDS.
CONNECTION_FAILOVER Connection Property
CONNECTION_FAILOVER is a Boolean-valued connection

property for use when jConnect uses JNDI to get connection
information.

jConnect for JDBC version 4.0 Connecting to a Server Using JNDI
When CONNECTION_FAILOVER is set to “true,” jConnect can

make multiple attempts to connect to a server. If one attempt to
connect to a host and port number associated with a server fails,
jConnect uses JNDI to get the next host and port number associated
with the server and attempts to connect through them. Connection
attempts proceed sequentially through all the hosts and ports
associated with a server.
For example, suppose CONNECTION_FAILOVER is set to “true,”
and a database server is associated with the following hosts and port
numbers, as in the earlier LDAP example:
1.3.6.1.4.1.897.4.2.5:TCP#1#giotto 1266
1.3.6.1.4.1.897.4.2.5:TCP#1#giotto 1337
1.3.6.1.4.1.897.4.2.5:TCP#1#standby1 4444
To get a connection to the server, jConnect tries to connect to the host
“giotto” at port 1266. If this fails, jConnect tries port 1337 on “giotto.”
If this fails, jConnect tries to connect to host “standby1” through port
4444.
The default for CONNECTION_FAILOVER is “true.”
If CONNECTION_FAILOVER is set to “false,” jConnect attempts to
connect to an initial host and port number. If the attempt fails,
jConnect throws a SQLException and does not try again.
Providing JNDI Context Information
To use jConnect with JNDI, a developer should be familiar with the

JNDI specification from Sun Microsystems, available from the Web:
http://java.sun.com/products/jndi
In particular, the developer needs to make sure that required
initialization properties are set in javax.naming.directory.DirContext when
JNDI and jConnect are used together. These properties can be set at
the system level or set at runtime.
Two key properties are:
• Context.INITIAL_CONTEXT_FACTORY
This property takes the fully qualified class name of the initial
context factory for JNDI to use. This determines the JNDI driver
that is used with the URL specified in the
Context.PROVIDER_URL property.
• Context.PROVIDER_URL

This property takes the URL of the directory service that the
driver (for example, the LDAP driver) is to access. The URL
should be a string, such as “ldap://ldaphost:427”.
The following example shows how to set context properties at
runtime and how to get a connection using JNDI and LDAP. In the
example, the INITIAL_CONTEXT_FACTORY context property is set
to invoke Sun Microsystem’s implementation of an LDAP service
provider. The PROVIDER_URL context property is set to the URL of
an LDAP directory service located on the host “ldap_server1” at port
983.
/* We want to use LDAP, so INITIAL_CONTEXT_FACTORY is set to the

* class name of an LDAP context factory. In this case, the
* context factory is provided by Sun’s implementation of a
* driver for LDAP directory service.
*/
props.put(Context.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.ldap.LdapCtxFactory");
/* Now, we set PROVIDER_URL to the URL of the LDAP server that

* is to provide directory information for the connection.
*/
props.put(Context.PROVIDER_URL, "ldap://ldap_server1:983");
/* Set up additional context properties, as needed. */

props.put("user", "xyz");
props.put("password", "123");
/* get the connection */

Connection con = DriverManager.getConnection("jdbc:sybase:jndi:
ldap://ldap_server1:983/servername=Sybase11,o=MyCompany,
c=US",props);
Note that the connection string passed to getConnection() contains
LDAP-specific information, which must be provided by the
developer.
When JNDI properties are set at runtime, as in the preceding
example, jConnect passes them to JNDI to be used in initializing a
server, as in the following jConnect code:
javax.naming.directory.DirContext ctx =
new javax.naming.directory.InitialDirContext(props);
jConnect then obtains the connection information it needs from JNDI
by invoking DirContext.getAtributes(), as in the following example, where
ctx is a DirContext object:

jConnect for JDBC version 4.0 jConnect Character-Set Converters
javax.naming.directory.Attributes attrs =
ctx.getAttributes(ldap://ldap_server1:983/servername=
Sybase11, SYBASE_SERVER_ATTRIBUTES);
In the example, SYBASE_SERVER_ATTRIBUTES is an array of
strings defined within jConnect. The array values are the OIDs for
the required directory information listed in Table 2-4.
jConnect Character-Set Converters

jConnect uses special classes for all character-set conversions. You
specify how jConnect should handle single-byte and multibyte
character-set conversions, and the performance impact the character-
set conversions will have on your applications, by choosing the
character-set converter class jConnect should use.
There are two character-set conversion classes. The conversion class
that jConnect uses is based on the version setting (for example,
VERSION_4), and the CHARSET and
CHARSET_CONVERTER_CLASS connection properties.
• The TruncationConverter class works only with single-byte character
sets such as iso_1 and cp850. It does not work with multibyte
character sets or single-byte character sets that use non-ASCII
characters.
Using the TruncationConverter class, jConnect 4.0 handles character
sets in the same manner as jConnect version 2.2. The
TruncationConverter class is the default converter when the version
setting is VERSION_2.
• The PureConverter class is a pure Java, multibyte character-set
converter. jConnect uses this converter class if the version setting
is VERSION_4. jConnect also uses this converter with
VERSION_2 if it detects a character set specified in the CHARSET
connection property that is not compatible with using the
TruncationConverter class.
Although it enables multibyte character-set conversions, the
PureConverter class may negatively impact jConnect driver
performance. If driver performance is a concern, see “Improving
Character-Set Conversion Performance” on page 2-25.
Selecting a Character-Set Converter
jConnect uses the version setting from SybDriver.setVersion() to

determine the default character-set converter class to use. For

jConnect Character-Set Converters jConnect for JDBC version 4.0
VERSION_2, the default is TruncationConverter. For VERSION_4, the

default is PureConverter.
You can also set the CHARSET_CONVERTER_CLASS connection
property to specify which character-set converter you want jConnect
to use. This is useful if you want to use a character-set converter
other than the default for your jConnect version.
For example, if you set jConnect to VERSION_4, but want to use the
TruncationConverter class rather than the multibyte PureConverter class,
you can set CHARSET_CONVERTER_CLASS as follows:
...
props.put("CHARSET_CONVERTER_CLASS",
"com.sybase.utils.TruncationConverter")
Setting the CHARSET Connection Property
You can specify the character set to use in your application by setting
the CHARSET driver property. If you do not set the CHARSET
property:
• For VERSION_2, jConnect uses iso_1 as the default character set.
• ForVERSION_3 and VERSION_4, jConnect uses the database’s
default character set, and adjusts automatically to perform any
necessary conversions on the client side.
You can also use the -J charset command line option for the IsqlApp
application to specify a character set.
To determine which character sets are installed on your Adaptive
Server, issue the following SQL query on your server to see a list of
installed character sets:
select name from syscharsets
go
For the PureConverter class, if the designated CHARSET does not work
with the client’s Java Virtual Machine (VM), the connection fails with
a SQLException, indicating that you must set CHARSET to a character
set that is supported by both Adaptive Server and the client.
When the TruncationConverter class is used, character truncation is
applied regardless of whether the designated CHARSET is 7-bit
ASCII or not.

Improving Character-Set Conversion Performance
If you are using multibyte character sets and need to improve driver
performance, you can use the SunIoConverter class provided with the
jConnect samples. This converter is based on the sun.io classes
provided by JavaSoft.
The SunIoConverter class is not a pure Java implementation of the
character-set converter feature, and therefore is not integrated with
the standard jConnect product. However, we have provided this
converter class for your reference, and you can use it with the
jConnect driver to improve character-set conversion performance.
➤ Note
Based on Sybase testing, the SunIoConverter class improved performance
on all VMs on which it was tested. However, JavaSoft reserves the right to
remove or change the sun.io classes with future releases of the JDK, and
therefore this SunIoConverter class may not be compatible with later JDK
releases.
To use the SunIoConverter class, you must install the jConnect sample
applications. Refer to Chapter 3, “Installing jConnect 4.0,” in the
Sybase jConnect for JDBC Installation Guide and Release Bulletin for
complete instructions on installing jConnect and its components,
including the sample applications. Once the samples are installed,
you can set the CHARSET_CONVERTER_CLASS connection
property to reference the SunIoConverter class in the sample
subdirectory under your jConnect installation directory.
Supported Character Sets
Table 2-5 lists the Sybase character sets that are supported by this
release of jConnect. The table also lists the corresponding JDK byte
converter for each supported character set.
Table 2-5: Supported Sybase character sets
SybCharset Name JDK Byte Converter

ascii_7 8859_1
big5 Big5
cp037 Cp037

jConnect Character-Set Converters jConnect for JDBC version 4.0

cp437 Cp437
cp500 Cp500
cp850 Cp850
cp852 Cp852
cp855 Cp855
cp857 Cp857
cp860 Cp860
cp863 Cp863
cp864 Cp864
cp866 Cp866
cp869 Cp869
cp874 Cp874
cp932 Cp932
cp936 Cp936
cp950 Cp950
cp1250 Cp1250
cp1251 Cp1251
cp1252 Cp1252
cp1253 Cp1253
cp1254 Cp1254
cp1255 Cp1255
cp1256 Cp1256
deckanji EUCJIS
eucgb GB2312
eucjis EUCJIS
eucksc Cp949
ibm420 Cp420
ibm918 Cp918
iso_1 8859_1
iso88592 8859-2


is088595 8859_5
iso88596 8859_6
iso88597 8859_7
iso88598 8859_8
iso88599 8859_9
koi8 KOI8_R
mac Macroman
mac_cyr MacCyrillic
mac_ee MacCentralEurope
macgreek MacGreek
macturk MacTurkish
sjis (see note) SJIS
tis620 MS874
utf8 UTF8
➤ Note
The Sybase sjis character set does not include the IBM or Microsoft
extensions to JIS, whereas the JDK SJIS bytecode converter includes
these extensions. As a result, conversions from Java strings to a Sybase
database using sjis may result in character values that are not supported by
the Sybase database. However, conversions from sjis on a Sybase
database to Java strings should not have this problem.
Unsupported Character Sets
The following Sybase character sets are not supported in jConnect 4.0
because no JDK byte converters are analogous to the Sybase
character sets:
• cp1047
• euccns
• greek8
• roman8

Accessing Database Metadata jConnect for JDBC version 4.0
• turkish8
• ucs2
Accessing Database Metadata

To support JDBC DatabaseMetaData methods, Sybase provides a set of
stored procedures that jConnect can call for metadata about a
database. These stored procedures must be installed on the server for
the JDBC metadata methods to work.
If the stored procedures for providing metadata are not already
installed in a Sybase server, you can install them using one of two
stored procedure scripts provided with jConnect:
• sql_server.sql installs stored procedures on an Adaptive Server
database.
• sql_anywhere.sql installs stored procedures on a SQL Anywhere
database.
Refer to the jConnect for JDBC Installation Guide and Release Notes for
complete instructions on installing stored procedures.
In addition, to use the metadata methods, the USE_METADATA
connection property must be set to “true” (its default value) when
you establish a connection.
➤ Note
You cannot get metadata about temporary tables in a database.
➤ Note
The DatabaseMetaData.getPrimaryKeys() method finds primary keys
declared in a table definition (CREATE TABLE) or with alter table
(ALTER TABLE ADD CONSTRAINT). It does not find keys defined
using sp_primarykey.
CANCEL_ALL Connection Property

CANCEL_ALL is a Boolean-valued connection property for
specifying the behavior of the Statement.cancel() method.

jConnect for JDBC version 4.0 Using Cursors with Result Sets
➤ Note
In pre-4.0 jConnect versions, the default setting for CANCEL_ALL is “true.”
In jConnect 4.0, to comply with the JDBC specification, the default setting
for CANCEL_ALL is “false,” if you set the connection property
JCONNECT_VERSION to “4.”
The following example sets CANCEL_ALL to “false.” In the

example, props is a Properties object for specifying connection
properties.
...
props.put("CANCEL_ALL", "false")
The settings for CANCEL_ALL have the following effect on
Statement.cancel():
• If CANCEL_ALL is “false,” invoking Statement.cancel() cancels
only the Statement object it is invoked on. Thus, if stmtA is a Statement
object, stmtA.cancel() will cancel the execution of the SQL statement
contained in stmtA in the database, but no other statements will be
affected. stmtA is canceled whether it is in cache waiting to execute
or has started to execute and is waiting for results.
• If CANCEL_ALL is “true,” invoking Statement.cancel() cancels not
only the object it is invoked on, but also any other Statement objects
that have execution and are waiting for results.
➤ Note
If you want to cancel the execution of all Statement objects on a connection,
regardless of whether or not they have begun execution on the server, you
can use the extension method SybConnection.cancel().
Using Cursors with Result Sets

jConnect 4.0 implements cursor and update methods in the Statement
and ResultSet interfaces of JDBC 1.x. In addition, it implements many
new cursor and update methods added in JDBC 2.0. These methods
make it easier to use cursors and to update rows in a table based on
values in a result set.

Using Cursors with Result Sets jConnect for JDBC version 4.0
➤ Note
jConnect implementations of JDBC 2.0 are based on the JDBC 2.0, version
0.8, draft specification. There should not be major differences between this
draft version and the final 2.0 specification, which was not available during
development of jConnect 4.0.
The current version of the JDBC 2.0 specification is available from the
JavaSoft Web site at www.JavaSoft.com.
The JDBC 2.0 features provided in jConnect 4.0 are implemented in

the jConnect extension classes SybStatement and SybCursorResultSet. This
allows you to incorporate JDBC 2.0 features in an application while
using jConnect with JDBC 1.0. Applications written strictly to JDBC
1.0 remain fully compatible with jConnect 4.0.
This section describes how to create and use cursors It discusses the
following topics:
• Creating a Cursor
• Positioned Updates and Deletes
• Using a Cursor with a Prepared Statement
Creating a Cursor
To create a cursor, you need to use either SybStatement.setCursorName()

or SybStatement.setFetchSize(). SybStatement.setCursorName() is available in
earlier versions of jConnect. It implements Statement.setCursorName(), as
specified in JDBC 1.0. SybStatement.setFetchSize() is new in jConnect 4.0.
It implements Statement.setFetchSize(), as specified JDBC 2.0.
When you use SybStatement.setCursorName(), you explicitly assign the
cursor a name. The signature for SybStatement.setCursorName() is:
void setCursorName(String name) throws SQLException;
You use SybStatement.setFetchSize() to create a cursor and specify the
number of rows returned from the database in each fetch. The
signature for SybStatement.setFetchSize() is:
void setFetchSize(int rows) throws SQLException;
When you use setFetchSize() to create a cursor, the jConnect driver
names the cursor. You can get the name of the cursor using
ResultSet.getCursorName().

➤ Note
jConnect 4.0 supports forward cursors only. This is also the only cursor type
supported in JDBC 1.x.
The basic steps for creating and using a cursor are:

1. Create the cursor using Statement.setCursorName() or
SybStatement.setFetchSize().
2. Invoke Statement.executeQuery() to open the cursor for a statement
and return a cursor result set.
3. Invoke ResultSet.next() to fetch rows and position the cursor in the
result set.
The following example uses each of the two methods for
creating cursors and returning a result set. It also uses
ResultSet.getCursorName() to get the name of the cursor created by
SybStatement.setFetchSize().
// With conn as a Connection object, create a
// Statement object and assign it a cursor using
// Statement.setCursorName().
Statement stmt = conn.createStatement();
stmt.setCursorName("author_cursor");
// Use the statement to execute a query and return

// a cursor result set.
ResultSet rs = stmt.executeQuery("SELECT au_id,
au_lname, au_fname FROM authors
WHERE city = 'Oakland'");
while(rs.next())
{
...
}
// Create a second statement object and use

// SybStatement.setFetchSize()to create a cursor
// that returns 10 rows at a time.
SybStatement syb_stmt = conn.createStatement();
syb_stmt.setFetchSize(10);
// Use the syb_stmt to execute a query and return

// a cursor result set.
SybCursorResultSet rs2 =
(SybCursorResultSet)syb_stmt.executeQuery("SELECT
au_id, au_lname, au_fname FROM authors

WHERE city = 'Pinole'");

while(rs2.next())
{
...
}
// Get the name of the cursor created through the

// setFetchSize() method.
String cursor_name = rs2.getCursorName();
...
Positioned Updates and Deletes
The next two sections show how to do positioned updates and

deletions using JDBC 1.x and 2.0 methods.
JDBC 1.x Methods
The following example shows how to use methods in JDBC 1.x to do

a positioned update. The example creates two Statement objects, one
for selecting rows into a cursor result set and the other for updating
the database from rows in the result set.
// Create two statement objects and create a cursor
// for the result set returned by the first
// statement, stmt1. Use stmt1 to execute a query
// and return a cursor result set.
Statement stmt1 = conn.createStatement();
Statement stmt2 = conn.createStatement();
stmt1.setCursorName("author_cursor");
ResultSet rs = stmt1.executeQuery("SELECT
au_id,au_lname, au_fname
FROM authors WHERE city = 'Oakland'
FOR UPDATE OF au_lname");
// Get the name of the cursor created for stmt1 so

// that it can be used with stmt2.
String cursor = rs.getCursorName();
// Use stmt2 to update the database from the

// result set returned by stmt1.

String last_name = new String("Smith");

while(rs.next())
{
if (rs.getString(1).equals("274-80-9391"))
{
stmt2.executeUpdate("UPDATE authors
SET au_lname = "+last_name + "
WHERE CURRENT OF " + cursor);
}
}
The following example uses Statement object stmt2, from the
preceding code, to perform a positioned delete:
stmt2.executeUpdate("DELETE FROM authors
WHERE CURRENT OF " + cursor);
JDBC 2.0 Methods
This section discusses JDBC 2.0 methods for updating columns in the
current cursor row and updating the database from the current
cursor row in a result set. They are followed by an example.
Updating Columns in a Result Set

JDBC 2.0 specifies a number of methods for updating column values
from a result set in memory, on the client. The updated values can
then be used to perform an update, insert, or delete operation on the
underlying database. All of these methods are implemented in the
SybCursorResultSet class.
Examples of some of the JDBC 2.0 update methods available in
jConnect 4.0 are:
void updateAsciiStream(String columnName, java.io.InputStream x,
int length) throws SQLException;
void updateBoolean(int columnIndex, boolean x) throws
SQLException;
void updateFloat(int columnIndex, float x) throws SQLException;
void updateInt(String columnName, int x) throws SQLException;
void updateInt(int columnIndex, int x) throws SQLException;
void updateObject(String columnName, Object x) throws
SQLException;

Methods for Updating the Database from a Result Set

JDBC 2.0 specifies two new methods for updating or deleting rows in
the database, based on the current values in a result set. These
methods are simpler in form than Statement.executeUpdate() in JDBC 1.x
and do not require a cursor name. They are implemented in
SybCursorResultSet:
void updateRow() throws SQLException;
void deleteRow() throws SQLException;
Example
The following example creates a single Statement object which is used
to return a cursor result set. For each row in the result set, column
values are updated in memory and then the database is updated
with the row’s new column values.
// Create a Statement object and set fetch size to
// 25. This creates a cursor for the Statement
// object Use the statement to return a cursor
// result set.
SybStatement syb_stmt =
(SybStatement)conn.createStatement();
syb_stmt.setFetchSize(25);
SybCursorResultSet syb_rs =
(SybCursorResultSet)syb_stmt.executeQuery(
"SELECT * from T1 WHERE ...")
// Update each row in the result set according to

// code in the following while loop. jConnect
// fetches 25 rows at a time, until fewer than 25
// rows are left. Its last fetch takes any
// remaining rows.
while(syb_rs.next())
{
// Update columns 2 and 3 of each row, where
// column 2 is a varchar in the database and
// column 3 is an integer.
syb_rs.updateString(2, "xyz");
syb_rs.updateInt(3,100);
//Now, update the row in the database.
syb_rs.updateRow();
}
To delete a row from a cursor result set, you can use
SybCursorResultSet.deleteRow() as follows:

while(syb_rs.next())
{
int col3 = getInt(3);
if (col3 >100)
{
syb_rs.deleteRow();
}
}
Using a Cursor with a Prepared Statement
Once a PreparedStatement object is created, it can be used multiple times

with the same or different values for its input parameters. If you use
a cursor with a PreparedStatement object, you need to close the cursor
after each use and then reopen the cursor to use it again. A cursor is
closed when you close its result set (ResultSet.close()). It is opened
when you execute its prepared statement
(PreparedStatement.executeQuery()).
The following example shows how to create a PreparedStatement object,
assign it a cursor, and execute the PreparedStatement object twice,
closing and then reopening the cursor.
// Create a prepared statement object with a
// parameterized query.
PreparedStatement prep_stmt =
conn.prepareStatement(
"SELECT au_id, au_lname, au_fname
FROM authors WHERE city = ?
FOR UPDATE OF au_lname");
//Create a cursor for the statement.

prep_stmt.setCursorName("author_cursor");
// Assign the parameter in the query a value.

// Execute the prepared statement to return a
// result set.
prep_stmt.setString(1,"Oakland");
ResultSet rs = prep_stmt.executeQuery();
//Do some processing on the result set.

while(rs.next())
{

Cursor Performance and the LANGUAGE_CURSOR Connection Property jConnect for JDBC version 4.0
...
}
// Close the result, which also closes the cursor.

rs.close();
// Execute the prepared statement again with a new

// parameter value.
prep_stmt.setString(1,"San Francisco");
rs = prep_stmt.executeQuery(); // reopens cursor
Cursor Performance and the LANGUAGE_CURSOR Connection Property

When you use the Statement.setCursorName() method or the setFetchSize()
method in the SybCursorResultSet class, jConnect creates a cursor in the
database. Other methods cause jConnect to open, fetch, and update a
cursor.
Pre-4.0 versions of jConnect are implemented to create and
manipulate cursors only by sending SQL statements with explicit
cursor commands to the database for parsing and compilation.
jConnect 4.0 is implemented to create and manipulate cursors either
by sending SQL statements to the database or by encoding cursor
commands as tokens within the Tabular Data Stream (TDS)
communication protocol. Cursors of the first type are “language
cursors;” cursors of the second type are “protocol cursors.”
Protocol cursors provide better performance than language cursors.
In addition, not all databases support language cursors. For
example, SQL Anywhere databases do not support language
cursors.
In jConnect 4.0, the default condition is for all cursors to be protocol
cursors. However, the LANGUAGE_CURSOR connection property
gives you the option of having cursors created and manipulated
through language commands in the database.
LANGUAGE_CURSOR Connection Property
LANGUAGE_CURSOR is a Boolean-valued connection property in

jConnect 4.0 that allows you to determine whether cursors are
created as protocol cursors or language cursors:
• If LANGUAGE_CURSOR is set to “true,” all cursors created
during a session are language cursors. jConnect creates and

jConnect for JDBC version 4.0 Updating the Database from the Result Set of a Stored Procedure
manipulates the cursors by sending SQL statements to the

database for parsing and compilation.
• If LANGUAGE_CURSOR is set to “false,” all cursors created
during a session are protocol cursors. jConnect creates and
manipulates the cursors by sending cursor commands as tokens
in the TDS protocol.
By default, LANGUAGE_CURSOR is set to “false.”
➤ Note
There is no known advantage to setting LANGUAGE_CURSOR to “true,”
but the option is provided in case an application displays unexpected
behavior when LANGUAGE_CURSOR is “false.”
Updating the Database from the Result Set of a Stored Procedure

jConnect 4.0 introduces update and delete methods that allow you to
get a cursor on the result set returned by a stored procedure. You can
then use the cursor’s position to update or delete rows in the
underlying table that provided the result set. The methods are in
SybCursorResultSet:
void updateRow(String tableName) throws SQLException;
void deleteRow(String tableName) throws SQLException;
The tableName parameter identifies the database table that provided
the result set.
To get a cursor on the result set returned by a stored procedure,
before executing the callable statement that contains the procedure,
you need to use either SybCallableStatement.setCursorName() or
SybCallableStatement.setFetchSize(). The following example shows how to
create a cursor on the result set of a stored procedure, update values
in the result set, and then update the underlying table using the
SybCursorResultSet.update() method:

Performance Tuning for Prepared Statements in Dynamic SQL jConnect for JDBC version 4.0
// Create a CalleableStatement object for executing the stored

// procedure.
CallableStatement sproc_stmt =
conn.prepareCall("{call update_titles}");
// Set the number of rows to be returned from the database with

// each fetch. This creates a cursor on the result set.
(SybCallableStatement)sproc_stmt.setFetchSize(10);
//Execute the stored procedure and get a result set from it.
SybCursorResultSet sproc_result = (SybCursorResultSet)
sproc_stmt.executeQuery();
// Move through the result set row by row, updating values in the
// cursor’s current row and updating the underlying titles table
// with the modified row values.
while(sproc_result.next())
{
sproc_result.updateString(...);
sproc_result.updateInt(...);
...
sproc_result.updateRow(titles);
}
Performance Tuning for Prepared Statements in Dynamic SQL

jConnect 4.0 provides performance tuning features for dynamic SQL
statements. This section includes these topics:
• Connection.prepareStatement()
• DYNAMIC_PREPARE Connection Property
• SybConnection.prepareStatement()
• Performance Tuning
Connection.prepareStatement()
In embedded SQL, dynamic statements are SQL statements that

need to be compiled at runtime, rather than statically. Typically,
dynamic statements contain input parameters, although this is not a
requirement. In SQL, the prepare command is used to precompile a
dynamic statement and save it so that it can be executed repeatedly
without being recompiled during a session.

jConnect for JDBC version 4.0 Performance Tuning for Prepared Statements in Dynamic SQL
If a statement is used multiple times in a session, precompiling it

provides better performance than sending it to the database and
compiling it for each use. The more complex the statement, the
greater the performance benefit.
If a statement is likely to be used only a few times, precompiling it
may be inefficient because of the overhead involved in precompiling,
saving, and later deallocating it in the database.
jConnect 4.0 implements Connection.prepareStatement() so that it can be
set to return either precompiled SQL statements or uncompiled SQL
statements in PreparedStatement objects. If Connection.prepareStatement() is
set to return precompiled SQL statements in PreparedStatement objects,
it sends dynamic SQL statements to the database to be precompiled
and saved exactly as they would be under direct execution of the
prepare command. If Connection.prepareStatement() is set to return
uncompiled SQL statements, it returns them in PreparedStatement
objects without sending them to the database.
The type of SQL statement that Connection.prepareStatement() returns is
determined by the connection property, DYNAMIC_PREPARE, and
applies throughout a session.
For Sybase-specific applications, jConnect 4.0 provides a
prepareStatement() method under the jConnect SybConnection class.
SybConnection.prepareStatement() allows you to specify whether an
individual dynamic SQL statement is to be precompiled,
independent of the session-level setting of the
DYNAMIC_PREPARE connection property.
DYNAMIC_PREPARE Connection Property
DYNAMIC_PREPARE is a Boolean-valued connection property for

enabling dynamic SQL prepared statements:
• If DYNAMIC_PREPARE is set to “true,” every invocation of
Connection.prepareStatement() during a session attempts to return a
precompiled statement in a PreparedStatement object.
In this case, when a PreparedStatement is executed, the statement it
contains is already precompiled in the database, with place
holders for dynamically assigned values, and the statement only
needs to be executed.
• If DYNAMIC_PREPARE is set to “false” for a connection, the
PreparedStatement object returned by Connection.prepareStatement()
does not contain a precompiled statement.

In this case, each time a PreparedStatement is executed, the dynamic

SQL statement it contains must be sent to the database to be both
compiled and executed.
The default value for DYNAMIC_PREPARE is “false.”
In the following example, DYNAMIC_PREPARE is set to “true” to
enable precompilation of dynamic SQL statements. In the example,
props is a Properties object for specifying connection properties.
...
props.put("DYNAMIC_PREPARE", "true")
Connection conn = DriverManager.getConnection(url, props);
When DYNAMIC_PREPARE is set to “true,” note that:
• Not all dynamic statements can be precompiled under the prepare
command. The SQL-92 standard places some restrictions on the
statements that can be used with the prepare command, and
individual database vendors may have their own constraints.
• If the database generates an error because it is unable to
precompile and save a statement sent to it through
Connection.prepareStatement(), jConnect traps the error and returns a
PreparedStatement object containing an uncompiled dynamic SQL
statement. Each time the PreparedStatement object is executed, the
statement is re-sent to the database to be compiled and executed.
• A precompiled statement resides in memory in the database and
persists either to the end of a session or until its PreparedStatement
object is explicitly closed. Garbage collection on a PreparedStatement
object does not remove the prepared statement from the
database. As a general rule, you should explicitly close
PreparedStatement objects after their last use, to prevent prepared
statements from accumulating in server memory during a session
and slowing performance.
SybConnection.prepareStatement()
If your application allows jConnect-specific extensions to JDBC, you

can use the SybConnection.prepareStatement() extension method to return
dynamic SQL statements in PreparedStatement objects:
PreparedStatement SybConnection.prepareStatement(String sql_stmt,
boolean dynamic) throws SQLException
SybConnection.prepareStatement() can return PreparedStatement objects
containing either precompiled or uncompiled SQL statements,
depending on the setting of the dynamic parameter. If dynamic is

“true,” SybConnection.prepareStatement() returns a PreparedStatement object

with a precompiled SQL statement. If dynamic is “false,” it returns a
PreparedStatement object with an uncompiled SQL statement.
The following example shows the use of
SybConnection.prepareStatement() to return a PreparedStatement object
containing a precompiled statement:
PreparedStatement precomp_stmt =
((SybConnection) conn).prepareStatement( "SELECT * FROM
authors WHERE au_fname LIKE ?", true);
In the example, the connection object conn is downcast to a
SybConnection object to allow the use of SybConnection.prepareStatement().
Note that the SQL string passed to SybConnection.prepareStatement() will
be precompiled in the database, even if the connection property
DYNAMIC_PREPARE is “false.”
If the database generates an error because it is unable to precompile
a statement sent to it through SybConnection.prepareStatement(), jConnect
throws a SQLException and the call fails to return a PreparedStatement
object. This is unlike Connection.prepareStatement(), which traps SQL
errors and, in the event of an error, returns a PreparedStatement object
containing an uncompiled statement.
Performance Tuning
Precompiling a dynamic SQL statement for execution and saving it

in memory uses time and resources. If a statement is not likely to be
used multiple times during a session, the costs of doing a database
prepare may outweigh its benefits. Another consideration is that once
a dynamic SQL statement is prepared in the database, it is very
similar to a stored procedure. In some cases, it may be preferable to
create stored procedures and have them reside on the server, rather
than defining prepared statements in the application. This is
discussed under “Choosing Between Prepared Statements and
Stored Procedures” on page 2-43.
You can use jConnect to optimize the performance of dynamic SQL
statements on a Sybase database as follows:
• Create PreparedStatement objects that contain precompiled
statements in cases where a statement is likely to be executed
several times in a session.
• Create PreparedStatement objects that contain uncompiled SQL
statements in cases where a statement will be used very few times
in a session.

As described in the following sections, the optimal way to set the

DYNAMIC_PREPARE connection property and create
PreparedStatement objects is likely to depend on whether your
application needs to be portable across JDBC drivers or whether you
are writing an application that allows jConnect-specific extensions to
JDBC.
Prepared Statements in Portable Applications
If your application is to run on databases from different vendors and

you want some PreparedStatement objects to contain precompiled
statements and others to contain uncompiled statements, proceed as
follows:
• When you access a Sybase database, make sure that the
DYNAMIC_PREPARE connection property is set to “true.”
• To return PreparedStatement objects containing precompiled
statements, use Connection.prepareStatement() in the standard way:
PreparedStatement ps_precomp =
Connection.prepareStatement(sql_string);
• To return PreparedStatement objects containing uncompiled
statements, use Connection.prepareCall().
Connection.prepareCall() returns a CallableStatement object, but since
CallableStatement is a subclass of PreparedStatement, you can upcast a
CallableStatement object to a PreparedStatement object, as in the
following example:
PreparedStatement ps_uncomp =
Connection.prepareCall(sql_string);
The PreparedStatement object ps_uncomp is guaranteed to contain
an uncompiled statement, since only Connection.prepareStatement() is
implemented to return PreparedStatement objects containing
precompiled statements.
Prepared Statements in Applications with jConnect Extensions
If you are not concerned about portability across drivers, you can
write code that uses SybConnection.prepareStatement() to specify whether
a PreparedStatement object contains precompiled or uncompiled
statements. In this case, how you code prepared statements is likely
to depend on whether most of the dynamic statements in an
application are likely to be executed many times or only a few times
during a session.

If Most Dynamic Statements Are Executed Very Few Times

For an application in which most dynamic SQL statements are likely
to be executed only once or twice in a session:
• Set the connection property DYNAMIC_PREPARE to “false.”
statements, use SybConnection.prepareStatement() with dynamic set to
“true:”
(SybConnection)conn.prepareStatement(sql_string, true);
If Most Dynamic Statements Are Executed Many Times in a Session

If most of the dynamic statements in an application are likely to be
executed many times in the course of a session, proceed as follows:
• Set the connection property DYNAMIC_PREPARE to “true.”
statements, you can use either Connection.prepareCall() (see the third
bullet under “Prepared Statements in Portable Applications”) or
SybConnection.prepareStatement(), with dynamic set to “false:”
(SybConnection)conn.prepareStatement(sql_string, false);
Connection.prepareCall(sql_string);
Choosing Between Prepared Statements and Stored Procedures
If you create a PreparedStatement object containing a precompiled

dynamic SQL statement, once the statement is compiled in the
database, it effectively becomes a stored procedure that is retained in
memory and attached to the data structure associated with your
session. In deciding whether to maintain stored procedures in the

Sending Image Data jConnect for JDBC version 4.0
database or to create PreparedStatement objects containing compiled

SQL statements in your application, resource demands and database
and application maintenance are important considerations:
• Once a stored procedure is compiled, it is globally available
across all connections. In contrast, a dynamic SQL statement in a
PreparedStatement object needs to be compiled and deallocated in
every session that uses it.
• If your application accesses multiple databases, using stored
procedures means that the same stored procedures need to be
available on all target databases. This can create a database
maintenance problem. If you use PreparedStatement objects for
dynamic SQL statements, you avoid this problem.
• If your application creates CallableStatement objects for invoking
stored procedures, you can encapsulate SQL code and table
references in the stored procedures. The underlying database or
SQL code can be modified without requiring changes in the
application.
Sending Image Data

jConnect 4.0 introduces a TextPointer class with sendData() methods for
updating an image column in an Adaptive Server or SQL Anywhere
database. In earlier versions of jConnect, image data had to be sent
using the setBinaryStream() method in java.sql.PreparedStatement. The
TextPointer.sendData() methods use java.io.InputStream and greatly
improve performance when image data is sent to an Adaptive Server
database.
To obtain instances of the TextPointer class, you can use either of two
getTextPtr() methods in SybResultSet:
public TextPointer getTextPtr(String columnName)
public TextPointer getTextPtr(int columnIndex)
Public Methods in the TextPointer Class
The TextPointer class is contained in the com.sybase.jdbc package. Its

public method interface is:
public void sendData(InputStream is, boolean log)
throws SQLException
public void sendData(InputStream is, int length,
boolean log) throws SQLException

jConnect for JDBC version 4.0 Sending Image Data
public void sendData(InputStream is, int offset,

int length, boolean log) throws SQLException
public void sendData(byte[] byteInput, int offset,
int length, boolean log) throws SQLEXception
sendData(InputStream is, boolean log) – Updates an image column with

data in the specified input stream.
sendData(InputStream is, int length, boolean log) – Updates an image column
with data in the specified input stream. length is the number of
bytes being sent.
sendData(InputStream is, int offset, int length, boolean log) – Updates an image
column with data in the specified input stream, starting at the
byte offset given in the offset parameter and continuing for the
number of bytes specified in the length parameter.
sendData(byte[ ] byteInput, int offset, int length, boolean log) – Updates a
column with image data contained in the byte array specified in
the byteInput parameter. The update starts at the byte offset given
in the offset parameter and continues for the number of bytes
specified in the length parameter.
Each method has a log parameter. The log parameter specifies
whether image data is to be fully logged in the database transaction
log. If the log parameter is set to “true,” the entire binary image is
written into the transaction log. If the log parameter is set to “false,”
the update is logged, but the image itself is not included in the log.
Updating an image Column with TextPointer.sendData()
To update a column with image data:

• Get a TextPointer object for the row and column that are to be
updated.
• Use TextPointer.sendData() to execute the update.
The next two sections illustrate these steps with an example. In the
example, image data from the file Anne_Ringer.gif is sent to update
the pic column of the au_pix table in the pubs2 database. The update
is for the row with author ID 899-46-2035.
Getting a TextPointer Object
text and image columns contain timestamp and page-location

information that is separate from their text and image data. When

Sending Image Data jConnect for JDBC version 4.0
data is selected from a text or image column, this extra information is

“hidden” as part of the result set.
A TextPointer object for updating an image column requires this hidden
information, but does not need the image portion of the column data.
To get this information, you need to select the column into a ResultSet
object and then use SybResultSet.getTextPtr() (see the example that
follows the next paragraph). SybResultSet.getTextPtr() extracts text-
pointer information, ignores image data, and creates a TextPointer
object.
In cases where a column contains a significant amount of image data,
selecting the column for one or more rows and waiting to get all the
data is likely to be inefficient, since the data is not used. You can
shortcut this process by using the set textsize command to minimize
the amount of data returned in a packet. The following code example
for getting a TextPointer object includes the use of set textsize for this
purpose.
/*
* Define a string for selecting pic column data for author ID
* 899-46-2035.
*/
String getColumnData = "select pic from au_pix where au_id =
'899-46-2035'";
/*
* Use set textsize to return only a single byte of column data
* to a Statement object. The packet with the column data will
* contain the "hidden" information necessary for creating a
* TextPointer object.
*/
Statement stmt= connection.createStatement();
stmt.executeUpdate("set textsize 1");
/*
* Select the column data into a ResultSet object--cast the
* ResultSet to SybResultSet because the getTextPtr method is
* in SybResultSet, which extends ResultSet.
*/
SybResultSet rs = (SybResultSet)stmt.executeQuery(getColumnData);
/*
* Position the result set cursor on the returned column data
* and create the desired TextPointer object.

jConnect for JDBC version 4.0 Using Date and Time Datatypes
*/
rs.next();
TextPointer tp = rs.getTextPtr("pic");
/*
* Now, assuming we are only updating one row, and won’t need
* the minimum textsize set for the next return from the server,
* we reset textsize to its default value.
*/
stmt.executeUpdate("set textsize 0");
Executing the Update with TextPointer.sendData
The following code uses the TextPointer object from the preceding
section to update the pic column with image data in the file
Anne_Ringer.gif.
/*
* First, define an input stream for the file.
*/
FileInputStream in = new FileInputStream("Anne_Ringer.gif");
/*
* Prepare to send the input stream without logging the image data
* in the transaction log.
*/
boolean log = false;
/*
* Send the image data in Anne_Ringer.gif to update the pic
* column for author ID 899-46-2035.
*/
tp.sendData(in, log);
Using Date and Time Datatypes

JDBC uses three temporal datatypes: Time, Date, and Timestamp.
Adaptive Servers use only one temporal datatype, datetime, which is
a date and a time, equivalent to the JDBC Timestamp datatype. The
Server datetime datatype supports second resolution to 1/300th of a
second.
All three JDBC datatypes are treated as datetime datatypes on the
server side. A JDBC Timestamp is essentially the same as a Server
datetime; therefore, no conversion is necessary. However, translating

Using Event Notification jConnect for JDBC version 4.0
a JDBC Time or Date datatype to or from a Server datetime datatype

requires a conversion.
➤ Note
Do not confuse JDBC’s Timestamp datatype with Adaptive Server’s
timestamp datatype. The Adaptive Server timestamp datatype is a unique
varbinary value for use when updates are made using an “optimistic
concurrency” strategy.
• To convert Time to datetime, the date 1 Jan 1970 is added.

• To convert Date to datetime, “00:00:00” is appended.
• To convert a datetime to a Date variable or a Time variable, the
unused information is stripped out.
➤ Note
When a value is inserted as a Time datatype, the date portion is essentially
meaningless, so the value should only be fetched back using a Time
datatype, never as a Date or Timestamp datatype.
Using Event Notification

You can use the jConnect event notification feature to have your
application notified when an Open Server procedure is executed.
To use this feature, you must use the SybConnection class, which
extends the Connection interface. SybConnection contains a regWatch()
method for turning event notification on and a regNoWatch() method
for turning event notification off.
Your application must also implement the SybEventHandler interface.
This interface contains one public method, event(), which is called
when the specified event occurs. The parameters of the event are
passed to event() and it tells the application how to respond.
To use event notification in your application, call
SybConnection.regWatch() to register your application in the notification
list of a registered procedure. Use this syntax:
SybConnection.regWatch(proc_name,eventHdlr,option)
• proc_name is a String that is the name of the registered procedure
that generates the notification.

jConnect for JDBC version 4.0 Using Event Notification
• eventHdler is an instance of the SybEventHandler class that you

implement.
• option is either NOTIFY_ONCE or NOTIFY_ALWAYS. Use
NOTIFY_ONCE if you only want the application to be notified
the first time a procedure executes. Use NOTIFY_ALWAYS if you
want the application to be notified every time the procedure
executes.
Whenever an event with the designated proc_name occurs on the
Open Server, jConnect calls eventHdlr.event() from a separate thread.
The event parameters are passed to eventHdlr.event() when it is
executed. Because it is a separate thread, event notification does not
block execution of the application.
If proc_name is not a registered procedure, or if Open Server is unable
to add the client to the notification list, the call to regWatch() throws a
SQL exception.
To turn off event notification, use this call:
SybConnection.regNoWatch(proc_name)
Event Notification Example
The following example shows how to implement an event handler

and then register an event with an instance of your event handler,
once you have a connection:
public class MyEventHandler implements SybEventHandler
{
// Declare fields and constructors, as needed.
...
public MyEventHandler(String eventname)
{
...
}
// Implement SybEventHandler.event.
public void event(String eventName, ResultSet params)
{
try
{
// Check for error messages received prior to event
// notification.
SQLWarning sqlw = params.getWarnings();
if sqlw != null
{
// process errors, if any

Error-Message Handling jConnect for JDBC version 4.0
...
}
// process params as you would any result set with
// one row.
ResultSetMetaData rsmd = params.getMetaData();
int numColumns = rsmd.getColumnCount();
while (params.next()) // optional
{
for (int i = 1; i <= numColumns; i++)
{
System.out.println(rsmd.getColumnName(i) + " =
" + params.getString(i));
}
// Take appropriate action on the event. For example,
// perhaps notify application thread.
...
}
}
catch (SQLException sqe)
{
// process errors, if any
...
}
}
}
public class MyProgram

{
...
// Get a connection and register an event with an instance
// of MyEventHandler.
Connection conn = DriverManager.getConnection(...);
MyEventHandler myHdlr = new MyEventHandler("MY_EVENT");
// Register your event handler.

((SybConnection)con).regWatch("MY_EVENT", myHdlr,
SybEventHandler.NOTIFY_ALWAYS);
...
}
Error-Message Handling
jConnect provides two classes for returning Sybase-specific error
information, SybSQLException and SybSQLWarning, as well as a
SybMessageHandler interface that allows you to customize the way
jConnect handles error messages received from the server.

jConnect for JDBC version 4.0 Error-Message Handling
Retrieving Sybase-Specific Error Information
jConnect provides an EedInfo interface that specifies methods for

obtaining Sybase-specific error information. The EedInfo interface is
implemented in SybSQLException and SybSQLWarning, which extend the
SQLException and SQLWarning classes.
SybSQLException and SybSQLWarning contain the following methods:
• public ResultSet getEedParams();
Returns a one-row result set containing any parameter values
that accompany the error message.
• public int getStatus();
Returns a “1” if there are parameter values, returns a “0” if there
are no parameter values in the message.
• public int getLineNumber();
Returns the line number of the stored procedure or query that
caused the error message.
• public String getProcedureName();
Returns the name of the procedure that caused the error
message.
• public String getServerName();
Returns the name of the server that generated the message.
• public int getSeverity();
Returns the severity of the error message.
• public int getState();
Returns information about the internal source of the error
message in the server. For use by Sybase Technical Support, only.
• public int getTranState();
Returns one of the following transaction states:
- 0 The connection is currently in an extended transaction.
- 1 The previous transaction committed successfully.
- 3 The previous transaction aborted.
Note that some error messages may be SQLException or SQLWarning
messages, without being SybSQLException or SybSQLWarning messages.
Your application should check the type of exception it is handling

before it invokes any of the EedInfo methods in SybSQLException or

SybSQLWarning.
Customizing Error Message Handling
You can use the SybMessageHandler interface to customize the way

jConnect handles error messages generated by the server.
Implementing SybMessageHandler in your own class for handling error
messages can provide the following benefits:
• “Universal” error handling
Error handling logic can be placed in your error-message
handler, instead of being repeated in catch clauses throughout
an application.
• “Universal” error logging
Your error-message handler can contain the logic for handling all
error logging.
• Remapping of error-message severity, based on application
requirements.
Your error-message handler can contain logic for recognizing
specific error messages and downgrading or upgrading their
severity based on application considerations rather than the
server’s severity rating. For example, the severity of a message
that a row does not exist may be downgraded during a cleanup
operation that deletes old rows; it may be upgraded in other
circumstances.
➤ Note
Error-message handlers implementing the SybMessageHandler interface only
receive server-generated messages. They do not handle messages
generated by jConnect.
When jConnect receives an error message, it checks to see if a

SybMessageHandler class has been registered for handling the message.
If so, jConnect invokes the messageHandler() method. The
messageHandler() method accepts a SQL exception as its argument, and
jConnect processes the message based on what value is returned
from messageHandler(). The error-message handler can:
• Return the SQL exception as is.
• Return a null. As a result, jConnect ignores the message.

jConnect for JDBC version 4.0 Error-Message Handling
• Create a SQL warning from a SQL exception, and return it. This
results in the warning being added to the warning-message
chain.
• If the originating message is a SQL warning, messageHandler() can
evaluate the SQL warning as urgent and create and return a SQL
exception to be thrown once control is returned to jConnect.
Installing an Error-Message Handler
You can install an error-message handler implementing

SybMessageHandler by calling the setMessageHandler() method from
SybDriver, SybConnection, or SybStatement. If you install an error -message
handler from SybDriver, all subsequent SybConnection objects inherit it.
If you install an error-message handler from a SybConnection object, it
is inherited by all SybStatement objects created by that SybConnection.
This hierarchy only applies from the time the error-message-handler
object is installed. For example, if you create a SybConnection object,
myConnection, and then call SybDriver.setMessageHandler() to install an
error-message-handler object, myConnection cannot use that object.
To return the current error-message-handler object, use
getMessageHandler().
Error Message Handler Example
import java.io.*;
import java.sql.*;
import com.sybase.jdbc.SybMessageHandler;
import com.sybase.jdbc.SybConnection;
import com.sybase.jdbc.SybStatement;
import java.util.*;
public class MyApp

{
static SybConnection conn = null;
static SybStatement stmt = null
static ResultSet rs = null;
static String user = "guest";
static String password = "sybase";
static String server = "jdbc:sybase:Tds:192.138.151.39:4444";
static final int AVOID_SQLE = 20001;
public MyApp()
{
try

{
Class.forName("com.sybase.jdbc.SybDriver").newInstance;
props.put("user", user);
props.put("password", password);
conn = (SybConnection)
DriverManager.getConnection(server, props);
conn.setMessageHandler(new NoResultSetHandler());
stmt =(SybStatement) conn.createStatement();
stmt.executeUpdate("raiserror 20001 'your error'");
for (SQLWarning sqw = _stmt.getWarnings();

sqw != null;
sqw = sqw.getNextWarning());
{
if (sqw.getErrorCode() == AVOID_SQLE);
{
System.out.println("Error" +sqw.getErrorCode()+
" was found in the Statement’s warning list.");
break;
}
}
stmt.close();
conn.close();
}
catch(Exception e)
{
System.out.println(e.getMessage());
e.printStackTrace();
}
}
class NoResultSetHandler implements SybMessageHandler

{
public SQLException messageHandler(SQLException sqe)
{
int code = sqe.getErrorCode();
if (code == AVOID_SQLE)
{
System.out.println("User " + _user + " downgrading " +
AVOID_SQLE + " to a warning");
sqe = new SQLWarning(sqe.getMessage(),

jConnect for JDBC version 4.0 Storing Java Objects as Column Data in a Table
sqe.getSQLState(),sqe.getErrorCode());
}
return sqe;
}
}
public static void main(String args[])

{
new MyApp();
}
Storing Java Objects as Column Data in a Table

Forthcoming database products will make it possible to directly store
Java objects as column data in a database. In such databases, Java
classes are treated as datatypes, and a column can be declared with a
Java class as its datatype.
jConnect 4.0 supports storing Java objects in a database by
implementing the setObject() methods defined in the PreparedStatement
interface and the getObject() methods defined in the CallableStatement
and ResultSet interfaces. This makes it possible to use jConnect with
an application that uses native JDBC classes and methods to directly
store and retrieve Java objects as column data.
➤ Note
To use the jConnect 4.0 getObject() and setObject() methods, you need to set
the jConnect version to VERSION_4. See “Setting the jConnect Version” on
page 2-12.
The following sections describe the requirements and procedures for

storing objects in a table and retrieving them using JDBC with
jConnect:
• Prerequisites for Storing Java Objects As Column Data
• Sending a Java Object to a Database
• Receiving Java Objects from the Database
Prerequisites for Storing Java Objects As Column Data
To store Java objects belonging to a user-defined Java class in a

column, three requirements must be met:

Storing Java Objects as Column Data in a Table jConnect for JDBC version 4.0
• The class must implement the java.io.Serializable interface. This is

because jConnect 4.0 uses native Java serialization and
deserialization to send objects to a database and receive them
back from the database.
• The class definition must be installed in the destination database.
• The client system must have the class definition in a .class file that
is accessible through the local CLASSPATH environment
variable.
Sending a Java Object to a Database
To send an instance of a user-defined class as column data, you need

to use one of the following setObject() methods, as specified in the
PreparedStatement interface:
void setObject(int parameterIndex, Object x, int targetSqlType,
int scale) throws SQLException;
void setObject(int parameterIndex, Object x, int targetSqlType)
throws SQLException;
void setObject(int parameterIndex, Object x) throws SQLException;
The following example defines an Address class, shows the definition
of a “Friends” table that has an Address column whose datatype is the
Address class, and inserts a row into the table.
public class Address implements Serializable
{
public String streetNumber;
public String street;
public String apartmentNumber;
public String city;
public int zipCode;
//Methods
...
}
Friends table:
varchar(30) firstname,
varchar(30) lastname,
Address address,
varchar(15) phone

jConnect for JDBC version 4.0 Storing Java Objects as Column Data in a Table
// Connect to the database containing the Friends table.

Connection conn =
DriverManager.getConnection("jdbc:sybase:Tds:localhost:5000",
"username", "password");
// Create a Prepared Statement object with an insert statement

//for updating the Friends table.
PreparedStatement ps = conn.prepareStatement("INSERT INTO
Friends values (?,?,?,?)");
// Now, set the values in the prepared statement object, ps.

// set firstname to "Joan."
ps.setString(1, "Joan");
// Set last name to "Smith."

ps.setString(2, "Smith");
// Assuming that we already have "Joan_address" as an instance

// of Address, use setObject(int parameterIndex, Object x) to
// set the address column to "Joan_address."
ps.setObject(3, Joan_address);
// Set the phone column to Joan’s phone number.

ps.setString(4, "123-456-7890");
// Perform the insert.

ps.executeUpdate();
Receiving Java Objects from the Database
A client JDBC application can receive a Java object from the database
in a result set or as the value of an output parameter returned from a
stored procedure.
• If a result set contains a Java object as column data, you need to
use one of the following getObject() methods in the ResultSet
interface to assign the object to a class variable:
Object getObject(int columnIndex) throws SQLException;
Object getObject(String columnName) throws SQLException;
• If an output parameter from a stored procedure contains a Java
object, you need to use the following getObject() method in the
CallableStatement interface to assign the object to a class variable:
Object getObject(int parameterIndex) throws SQLException;

Storing Java Objects as Column Data in a Table jConnect for JDBC version 4.0
The following example illustrates the use of

ResultSet.getObject(int parameterIndex) to assign an object received in a
result set to a class variable. The example uses the Address class and
Friends table of the previous section and presents a simple
application that prints a name and address on an envelope.
/*
** This application takes a first and last name, gets the
** specified person’s address from the Friends table in the
** database, and addresses an envelope using the name and
** retrieved address.
*/
public class Envelope
{
Connection conn = null;
String firstName = null;
String lastName = null;
String street = null;
String city = null;
String zip = null;
public static void main(String[] args)

{
if (args.length < 2)
{
System.out.println("Usage: Envelope <firstName>
<lastName>");
System.exit(1);
}
// create a 4" x 10" envelope
Envelope e = new Envelope(4, 10);
try
{
// connect to the database with the Friends table.
conn = DriverManager.getConnection(
"jdbc:sybase:Tds:localhost:5000", "username",
"password");
// look up the address of the specified person
firstName = args[0];
lastName = args[1];
PreparedStatement ps = conn.prepareStatement(
"SELECT address FROM friends WHERE " +
"firstname = ? AND lastname = ?");
ps.setString(1, firstName);
ps.setString(2, lastName);
ResultSet rs = ps.executeQuery();
if (rs.next())
{

jConnect for JDBC version 4.0 Improving jConnect Performance
Address a = (Address) rs.getObject(1);

// set the destination address on the envelope
e.setAddress(firstName, lastName, a);
}
conn.close();
}
{
sqe.printStackTrace();
System.exit(2);
}
// if everything was successful, print the envelope
e.print();
}
private void setAddress(String fname, String lname, Address a)
{
street = a.streetNumber + " " + a.street + " " +
a.apartmentNumber;
city = a.city;
zip = "" + a.zipCode;
}
private void print()
{
// Print the name and address on the envelope.
...
}
}
Improving jConnect Performance

There are a number of ways to optimize the performance of an
application using jConnect. Here are some suggestions:
• Use the TextPointer.sendData() methods to send text and image data
to an Adaptive Server database. See “Sending Image Data” on
page 2-44.
• Create precompiled PreparedStatement objects for dynamic SQL
statements that are used repeatedly during a session. See
“Performance Tuning for Prepared Statements in Dynamic SQL”
on page 2-38.
• For sessions that are likely to move image data, large row sets,
and lengthy text data, use the PACKETSIZE connection property
to set the maximum feasible packet size.
• For TDS-tunneled HTTP, set the maximum TDS packet size (see
“Setting Servlet Arguments” on page A-8 of Appendix A, “Web

Improving jConnect Performance jConnect for JDBC version 4.0
Server Gateways”) and configure your Web server to support the

HTTP1.1 Keep-Alive feature.
• Use protocol cursors, the default setting of the
LANGUAGE_CURSOR connection property.
Two additional considerations for improving performance are
described below.
BigDecimal Rescaling
The JDBC 1.0 specification requires a scale factor with getBigDecimal().

Then, when a BigDecimal object is returned from the server, it must be
rescaled using the original scale factor you used with getBigDecimal().
To eliminate the processing time required for rescaling, use the JDBC
2.0 getBigDecimal() method, which jConnect implements in the
SybResultSet class and does not require a scale value:
public BigDecimal getBigDecimal(int columnIndex)
throws SQLException
For example:
SybResultSet rs =
(SybResultSet)stmt.executeQuery("SELECT
numeric_column from T1");
while (rs.next())
{
BigDecimal bd rs.getBigDecimal(
"numeric_column");
...
}
REPEAT_READ Connection Property
You can improve performance on retrieving a result set from the

database if you set the REPEAT_READ connection property to
“false.” However, when REPEAT_READ is “false”:
• You must read column values in order, according to column
index. This is difficult if you want to access columns by name
rather than column number.
• You cannot read a column value in a row more than once.

jConnect for JDBC version 4.0 Restrictions and Limitations
Restrictions and Limitations

The following restrictions and limitations apply to this version of
jConnect.
Using setLong() with Large Parameter Values
Implementations of the PreparedStatement.setLong() method set a

parameter value to a SQL BIGINT datatype. Most Adaptive Server
databases do not have an 8-byte BIGINT datatype. If a parameter
value requires more than 4 bytes of a BIGINT, using setLong() may
result in an overflow exception.
Compute Statements
jConnect does not support computed rows. Results are automatically

canceled when a query contains a computed row. For example, the
following statement is rejected:
SELECT name FROM sysobjects
WHERE type="S" COMPUTE COUNT(name)
To avoid this problem, substitute the following code:
SELECT name from sysobjects WHERE type="S"
SELECT COUNT(name) from sysobjects WHERE type="S"
Executing Stored Procedures
• If you execute a stored procedure in a CallableStatement object that

represents parameter values as question marks, you get better
performance than if you use both question marks and literal
values for parameters. Further, if a you mix literals and question
marks, you cannot use output parameters with a stored
procedure.
The following example creates sp_stmt as a CallableStatement object
for executing the stored procedure MyProc:
CallableStatement sp_stmt = conn.prepareCall(
{"call MyProc(?,?)}");
The two parameters in MyProc are represented as question marks.
You can register one or both of them as output parameters using
the registerOutParameter() methods in the CallableStatement interface.

Running IsqlApp jConnect for JDBC version 4.0
In the following example, sp_stmt2 is a CallableStatement object for

executing the stored procedure MyProc2.
CallableStatement sp_stmt2 = conn.prepareCall(
{"call MyProc2(?,'javalin')}");
In sp_stmt2, one parameter value is given as a literal value and
the other as a question mark. You cannot register either
parameter as an output parameter.
• jConnect does not currently support execution of stored
procedures with RPC commands using name-binding for
parameters. However, you can execute stored procedures using
language commands, passing input parameters to them directly
from Java variables using the PreparedStatement class. This is
illustrated in the following code fragment:
// Prepare the statement
System.out.println("Preparing the statement...");
String stmtString = "exec " + procname + " @p3=?, @p1=?";
PreparedStatement pstmt = con.preparedStatement(stmtString);
// Set the values

pstmt.setString(1, "xyz");
pstmt.setInt(2, 123);
// Send the query

System.out.println("Executing the query...");
ResultSet rs = pstmt.executeQuery();
Running IsqlApp
IsqlApp allows you to issue isql commands from the command line.
The syntax for IsqlApp is:
IsqlApp [-U username] [-P password]
[-S servername][-G gateway]
[-p http|https]
[-D debug-class-list][-v]
[-I input-command-file]
[-c command_terminator]
[-C charset] [-L language]
[-T sessionID]
[-N] [-V <version {2,3,4}>]
In this command:
-v turns on verbose printing mode.

jConnect for JDBC version 4.0 jConnect Sample Programs and Sample Code
-I input-command-file causes IsqlApp to take commands from a

file instead of the keyboard.
-c command-terminator lets you specify a keyword (for example,
“go”) that, when entered on a line by itself, terminates the
command. This lets you to enter multiline commands before
using the terminator keyword. If you do not specify a command
terminator, each new line terminates a command.
-N stops an exit code from being returned.
➤ Note
You must enter a space after each option flag.
To obtain a full description of the command line options, enter:

java IsqlApp -help
The following example shows how to connect to a database on a host
named “myserver” through port “3756” and run an isql script named
“myscript”:
java IsqlApp -U sa -P sapassword
-S jdbc:sybase:Tds:myserver:3756
-I $JDBC_HOME/sp/myscript -c go
➤ Note
An applet providing GUI access to isql commands is available from
$JDBC_HOME/sample/gateway.html (UNIX) or
%JDBC_HOME%\sample\gateway.html (Windows).
jConnect Sample Programs and Sample Code

Several sample programs are provided with jConnect to illustrate
many of the topics covered in this chapter, and to help you
understand how jConnect works with various JDBC classes and
methods. In addition, this section includes a sample code fragment
for your reference.
Sample Applications
When you install jConnect, you can also the install sample programs.
These samples include the source code so that you can review how

jConnect Sample Programs and Sample Code jConnect for JDBC version 4.0
jConnect implements various JDBC classes and methods. Refer to the

jConnect for JDBC Installation Guide and Release Bulletin for complete
instructions for installing the sample programs.
➤ Note
The jConnect sample programs are intended for demonstration purposes
only.
After you install the sample programs, they are located in the sample
subdirectory under your jConnect installation directory. The file
index.html in the sample subdirectory contains a complete list of the
samples that are available with a description of each sample. In
addition, index.html lets you view and run the sample programs as
applets.
Running the Sample Applets
Using your Web browser, you can run the sample programs as
applets. This enables you to view the source code while viewing the
output results.
To run the samples as applets, you need to start the Cascade gateway.
See “Using the Cascade Gateway” on page A-10.
Use your Web browser to open index.html in the sample subdirectory.
http://localhost:8000/sample/index.html
Running the Sample Programs with SQL Anywhere
All of the sample programs are compatible with Adaptive Server, but
only a limited number are compatible with SQL Anywhere. Refer to
index.html in the sample subdirectory for a current list of the sample
programs that are compatible with SQL Anywhere.
In addition, to run the sample programs that are available for SQL
Anywhere, you must install the script pubs2_any.sql on your SQL
Anywhere server. This script is located in the sample subdirectory
under your jConnect installation directory.
For Windows, go to DOS and enter:
java IsqlApp -U dba -P password
-S jdbc:sybase:Tds:[hostname]:[port]
-I %JDBC_HOME%\sample\pubs2_any.sql -c go
For UNIX, enter:

jConnect for JDBC version 4.0 jConnect Sample Programs and Sample Code
java IsqlApp -U dba -P password

-S jdbc:sybase:Tds:[hostname]:[port]
-I $JDBC_HOME/sample/pubs2_any.sql -c go
Sample Code
The following sample code illustrates several topics covered earlier

in this chapter, including how to invoke the jConnect driver, make a
connection, issue a SQL statement, and process results.
import java.io.*;
import java.sql.*;
public class SampleCode

{
public static void main(String args[])
{
try
{
/*
* Open the connection. May throw a SQLException.
*/
Connection con = DriverManager.getConnection(
"jdbc:sybase:Tds:myserver:3767", "sa", "");
/*
* Create a statement object, the container for the SQL
* statement. May throw a SQLException.
*/
Statement stmt = con.createStatement();
/*
* Create a result set object by executing the query.
* May throw a SQLException.
*/
ResultSet rs = stmt.executeQuery("Select 1");
/*
* Process the result set.
*/
if (rs.next())
{
int value = rs.getInt(1);
System.out.println("Fetched value " + value);
}
}
/*
* Exception handling.
*/

jConnect Sample Programs and Sample Code jConnect for JDBC version 4.0

{
System.out.println("Unexpected exception : " +
sqe.toString() + ", sqlstate = " +
sqe.getSQLState());
System.exit(1);
}
System.exit(0);
}
}

3 Troubleshooting 3.
This chapter describes solutions and workarounds for problems you

might encounter when using jConnect.
This chapter includes these topics:
• Debugging with jConnect (page 3-1)
• Unsuccessful Connection Errors (page 3-4)
• Stored Procedure Errors (page 3-5)
• Capturing TDS Communication Between Client and Server
Debugging with jConnect

jConnect includes a Debug class that contains a set of debugging
functions. This class is never instantiated; other classes just use its
static methods for debugging. The Debug methods include a variety of
assert, trace, and timer functions that let you define the scope of the
debugging process, and the output destination for the debugging
results.
The jConnect installation also includes a complete set of debug-
enabled classes. These classes are located in the devclasses
subdirectory under your jConnect installation directory. For
debugging purposes, you must redirect your CLASSPATH
environment variable to reference devclasses, rather than the standard
jConnect classes directory. You can also do this by explicitly
providing a -classpath argument to the java command when you run a
Java program.
Importing the Debug Class
In order to use the jConnect debugging feature, your application

must import the Debug class. Add this statement:
import com.sybase.utils.Debug;
Turning On Debugging in Your Application
Use the Debug.debug() method to turn on debugging within your

application. Add this call:

Debugging with jConnect jConnect for JDBC version 4.0
Debug.debug(true,[classes],[printstream]);
The classes parameter is a string that lists the specific classes you
want to debug, separated by colons. For example:
Debug.debug(true,"MyClass")
If you include “STATIC” in the class string, it turns on debugging for
all static methods in jConnect in addition to the designated classes.
For example:
Debug.debug(true,"STATIC:MyClass")
You can specify “ALL” to turn on debugging for all classes. For
example:
Debug.debug(true,"ALL");
The printstream parameter is optional. If you do not specify a
printstream, the debug output goes to the output file you specified
with DriverManager.setLogStream().
Turning Off Debugging in Your Application
To turn off debugging, add this call:

Debug.debug(false);
Setting the CLASSPATH for Debugging
Before running your debug-enabled application, redefine the

CLASSPATH environment variable to reference the /devclasses
subdirectory under your jConnect installation directory.
• For UNIX, replace $JDBC_HOME/classes with
$JDBC_HOME/devclasses.
• For Windows, replace %JDBC_HOME%\classes with
%JDBC_HOME%\devclasses.
Using the Debug Methods
You can add calls to other Debug methods to customize the debugging
process.
In these methods, the first (object) parameter is usually “this” to
specify the calling object. If any of these methods are static, use null
for the object parameter.
3-2 Troubleshooting
jConnect for JDBC version 4.0 Debugging with jConnect
Debug.println()
Use this method to define the message to print in the output log
if debugging is enabled and the object is included in the list of
classes to debug. The debug output goes to the output file you
specified with Debug.debug().
The syntax is:
Debug.println(object,message string);
For example:
Debug.println(this,"Query: "+ query);
produces a message similar to this in the output log:
myApp(thread[x,y,z]): Query: select * from author
Debug.assert()
Use this method to assert a condition, and throw a runtime
exception when the condition is not met. You can also define the
message to print in the output log if the condition is not met. The
syntax is:
Debug.assert(object,boolean condition,message
string);
For example:
Debug.assert(this,amount<=buf.length,amount+" too
big!");
produces a message similar to this in the output log if “amount”
exceeds the value of buf.length:
java.lang.RuntimeException:myApp(thread[x,y,z]):
Assertion failed: 513 too big!
at jdbc.sybase.utils.Debug.assert(Debug.java:338)
at myApp.myCall(myApp.java:xxx)
at .... more stack:
Debug.startTimer()
Debug.stopTimer()
Use these methods to start and stop a timer that measures the
milliseconds that elapse during an event. The method keeps one
timer per object, and one for all static methods. The syntax to
start the timer is:
Debug.startTimer(object);
The syntax to stop the timer is:
Debug.stopTimer(object,message string);

Unsuccessful Connection Errors jConnect for JDBC version 4.0
For example:
Debug.startTimer(this);
stmt.executeQuery(query);
Debug.stopTimer(this,"executeQuery");
produces a message similar to this in the output log:
myApp(thread[x,y,z]):executeQuery elapsed time =
25ms
Unsuccessful Connection Errors

This section addresses problems that may arise when you are trying
to establish a connection.
HTTP Server Address Already in Use

HTTPServer:
IOException: getRequest() Address already in use
This error indicates that another process is running on the default
port 8000. You can:
• Stop the process that is currently running on port 8000. After
verifying that the process has terminated, try starting the
gateway.
• Change the port number in the www.dos (DOS) or www.template
(UNIX) file, located in JDBC_HOME, then modify the
gateway.html file, located in the sample subdirectory of
JDBC_HOME, by changing the PROXY parameter from
“localhost:8000” to “localhost:new_port”. If your host is not
“localhost” (if your Cascade HTTP server and browser are on
different hosts), make sure that the PROXY parameter uses the
remote host name rather than “localhost.”
Gateway Connection Refused

Gateway connection refused:
HTTP/1.0 502 Bad Gateway|Restart Connection
This error message indicates that something is wrong with the
hostname or port# used to connect to your Adaptive Server. Check the
[query] entry in $SYBASE/interfaces (UNIX) or in
%SYBASE%\ini\sql.ini (Windows).
3-4 Troubleshooting
jConnect for JDBC version 4.0 Stored Procedure Errors
If the problem persists after you have verified the hostname and port#,
you can learn more by starting the HTTP server with the “verbose”
system property enabled.
For Windows, go to a DOS prompt and enter:
httpd -Dverbose=1 > filename
For UNIX, enter:
sh httpd.sh -Dverbose=1 > filename &
where filename is the debug messages output file.
If you are not making a connection through the Cascade HTTP
gateway, your Web server probably does not support the connect
method. Applets can only connect to the host from which they were
downloaded, unless you use the Cascade HTTP gateway, which
provides a path to the database server as a proxy.
The Cascade HTTP gateway and your Web server must run on the
same host. In this scenario, your applet can connect to the same
machine/host through the port that is controlled by the Cascade
HTTP gateway, which routes the request to the appropriate database.
To see how this is accomplished, review the source of Isql.java and
gateway.html in the sample subdirectory under the jConnect
installation directory. Search for “proxy”.
Unable to Connect to a 4.9.2 SQL Server
jConnect uses TDS 5.0 (Sybase transfer protocol). SQL Server 4.9.x
uses TDS 4.6, which is not compatible with TDS 5.0.
SQL Server 10.0.2 or later is required for use with jConnect.
Stored Procedure Errors
RPC Returns Fewer Output Parameters Than Registered

SQLState: JZ0SG - An RPC did not return as many
output parameters as the application had
registered for it.
This error occurs if you call CallableStatement.registerOutParam() for more
parameters than you have declared as “OUTPUT” parameters in the
stored procedure. Make sure that you have declared all of the

Capturing TDS Communication Between Client and Server jConnect for JDBC version 4.0
appropriate parameters as “OUTPUT.” Look at the line of code that

reads:
create procedure yourproc (@p1 int OUTPUT, ...
➤ Note
If you receive this error while using SQL Anywhere, you should upgrade to
SQL Anywhere version 5.5.04.
Fetch/State Error When Stored Procedure Returns Output Params
If a query does not return row data, then it should use the
CallableStatement.executeUpdate() or execute() methods rather than the
executeQuery() method.
jConnect throws a SQL exception if an executeQuery() has no result sets,
as required by the JDBC standard.
Stored Procedure Executed in Unchained Transaction Mode

Sybase Error 7713 - Stored Procedure can only be
executed in unchained transaction mode.
JDBC attempts to put the connection in autocommit(true) mode. The
application can change the connection to chained mode using
Connection.setAutoCommit(false) or by using a “set chained on” language
command. If the stored procedure was not created in a compatible
mode, this error occurs.
Use this system procedure to fix the problem:
sp_procxmode procedure_name,"anymode"
Capturing TDS Communication Between Client and Server

Tabular Data Stream (TDS) is Sybase’s proprietary protocol for
handling communication between a client application and Adaptive
Server. jConnect 4.0 includes a PROTOCOL_CAPTURE connection
property that allows you to capture raw TDS packets in a file.
If you are having problems with an application that you cannot
resolve within either the application or the server, you can use
PROTOCOL_CAPTURE to capture the communication between the
client and the server in a file. You can then send the file, which
3-6 Troubleshooting
jConnect for JDBC version 4.0 Capturing TDS Communication Between Client and Server
contains binary data and is not directly interpretable, to Sybase

Technical Support for analysis.
A file containing all the TDS packets sent during a session can be
very large. To control the size of TDS capture files, jConnect provides
a Capture class with pause() and resume() methods for stopping and
restarting the flow of TDS packets into a file.
PROTOCOL_CAPTURE Connection Property
The PROTOCOL_CAPTURE connection property is used to specify

a file for receiving the TDS packets exchanged between an
application and an Adaptive Server. PROTOCOL_CAPTURE takes
effect immediately so that TDS packets exchanged during
connection establishment are written to the specified file. All packets
continue to be written to the file until Capture.pause() is executed or the
session is closed.
The following example shows the use of PROTOCOL_CAPTURE to
send TDS data to the file tds_data:
...
props.put("PROTOCOL_CAPTURE", "tds_data")
Connection conn = DriverManager.getConnection(url, props);
where url is the connection URL and props is a Properties object for
specifying connection properties.
pause() and resume() Methods in the Capture Class
The Capture class is contained in the com.sybase.jdbc package. It

contains two public methods:
• public void pause()
• public void resume()
Capture.pause() stops the capture of raw TDS packets into a file;
Capture.resume() restarts the capture.
The TDS capture file for an entire session can become very large. If
you know where in an application you want to capture TDS data and
you want to limit the size of the capture file, you can do the
following:

Capturing TDS Communication Between Client and Server jConnect for JDBC version 4.0
1. Immediately after you have established a connection, get the

Capture object for the connection and use the pause() method to
stop capturing TDS data:
Capture cap = ((SybConnection)conn).getCapture();
cap.pause();
2. Place cap.resume() just before the point where you want to start
capturing TDS data.
3. Place cap.pause() just after the point where you want to stop
capturing data.
3-8 Troubleshooting
A Web Server Gateways A.
This appendix contains information about setting up and using Web

server gateways with jConnect.
This appendix is divided into these sections:
• About Web Server Gateways (page A-1)
• Using the TDS-tunneling Servlet (page A-6)
• Using the Cascade Gateway (page A-10)
About Web Server Gateways

If your database server runs on a different host than your Web server,
or if you are developing Internet applications that must connect to a
secure database server through a firewall, you need a gateway to act
as a proxy, providing a path to the database server.
To connect to servers using the Secure Sockets Layer (SSL) protocol,
jConnect provides a Java servlet that you can install on any Web
server that supports the javax.servlet interfaces. This servlet enables
jConnect to support encryption using the Web server as the gateway.
➤ Note
jConnect 4.0 also contains support for SSL on the client system. For
information on jConnect’s client-side support of SSL, see “Support
for SSL Security Protocol” on page 2-15.
jConnect includes a Cascade gateway, a slightly modified version of

the Cascade Web server. The Cascade gateway supports the
CONNECT HTTP method, which allows HTTP-tunneling of Tabular
Data Stream (TDS) data. You can use the Cascade gateway to connect
to a database server that runs on a different host than the Web server,
but that does not need to pass through a firewall. See “Using the
Cascade Gateway” on page A-10.
TDS tunneling
jConnect uses the TDS-tunneled HTTP protocol to communicate

with database servers. Requests from a client to a back-end server
that go through the gateway contain TDS in the body of the request.
jConnect for JDBC Programmer’s Reference A-1

About Web Server Gateways jConnect for JDBC version 4.0
The request header indicates the length of the TDS included in the
request packet.
TDS is a connection-oriented protocol, whereas HTTP is not. In order
to support security features such as encryption for Internet
applications, jConnect uses a TDS-tunneling servlet to maintain a
logical connection across HTTP requests. The servlet generates a
session ID during the initial login request, and the session ID is
included in the header of every subsequent request. Using session
IDs lets you identify active sessions, and even resume a session as
long as the servlet has an open connection using that specific session
ID.
The logical connection provided by the TDS-tunneling servlet
enables jConnect to support encrypted communication between two
systems.
jConnect and Gateway Configuration
There are several options for setting up your Web servers and
Adaptive Servers. Four common configurations are described below.
These examples show where to install the jConnect driver and when
to use the Cascade gateway or a gateway with the TDS-tunneling
servlet.
Web Server and SQL Server on One Host
In this two-tier configuration, the Web server and Adaptive Server

are both installed on the same host.
• Install jConnect on the Web server host.
• No gateway required.
A-2 Web Server Gateways

jConnect for JDBC version 4.0 About Web Server Gateways
Client Host
Browser
URL
Downloaded
applets and
jConnect Download Web Server
driver applets and
jConnect
applets and
jConnect
TDS 5.0
Adap-
tive
Server
Dedicated JDBC Web Server and SQL Server on One Host
With this configuration, you have a separate host for your main Web
server. A second host is shared by a Web server specifically for
Adaptive Server access and the Adaptive Server. Links from the
main server direct requests requiring SQL access to the dedicated
Web server.
• Install jConnect on the second (Adaptive Server) host.
• No gateway required.

About Web Server Gateways jConnect for JDBC version 4.0
Client Host A
Browser
URL
Downloaded
applets and Main
jConnect Web Server
driver
non-SQL
applets
URL
Download
Host B
applets and
jConnect
TDS 5.0 Web Server
applets and
jConnect
Adap-
tive
Server

jConnect for JDBC version 4.0 About Web Server Gateways
Web Server and SQL Server on Separate Hosts
In this three-tier configuration, the Adaptive Server is on a separate

host from the Web server. jConnect requires a gateway to act as a
proxy to the Adaptive Server.
• Requires either a TDS-tunneling servlet (TDS-TS; recommended)
or the Cascade gateway.
Client Host A
Browser
URL
Downloaded
applets and Main
jConnect Download Web Server
driver applets and
jConnect
applets and
jConnect
HTTP
tunneled TDS-TS or
TDS Cascade
Gateway
Host B
TDS 5.0
Adap-
tive
Server

Using the TDS-tunneling Servlet jConnect for JDBC version 4.0
Connecting to a Server Through a Firewall
To connect to a server protected by a firewall, you must use a Web

server with the TDS-tunneling servlet to support transmission of
database request responses over the Internet.
• Requires a Web server that supports the javax.servlet interfaces.
Client Host A
Browser URL
Downloaded Download
applets and applets and
jConnect jConnect
driver Web Server
Supporting
HTTP/HTTPS javax.servlet
tunneled
TDS TDS servlet
applets and
jConnect
Host B
TDS 5.0
Adap-
tive
Server
Firewall
Using the TDS-tunneling Servlet

In order to use the TDS-tunneling servlet, you need a Web server that
supports the javax.servlet interfaces, such as JavaSoft’s Java Web
Server. When you install the Web server, include the jConnect TDS-
tunneling servlet in the list of active servlets. You can also set
parameters for the servlet to define connection timeouts and
maximum packet size.
With the TDS-tunneling servlet, requests from a client to the back-
end server that go through the gateway include a GET or POST
command, the TDS session ID (after the initial request), back-end

jConnect for JDBC version 4.0 Using the TDS-tunneling Servlet
address, and status of the request as query parameters for the

request.
TDS is contained in the body of the request. Two header fields
indicate the length of the TDS stream included in the request packet,
and the session ID assigned by the gateway.
When the client sends a request, the Content-Length header field
indicates the size of the TDS content, and the request command is
POST. If there is no TDS data in the request because the client is either
retrieving the next portion of the response data from the server, or
closing the connection, the request command is GET.
The following example illustrates how information is passed
between the client and an HTTPS gateway using the TDS-tunneled
HTTPS protocol. This example shows a connection to a back-end
server named DBSERVER with a port number “1234.”
Client to gateway login request. No session ID.
Query POST/tds?ServerHost=dbserver&ServerPort=1234&Operation=more
HTTP/1.0
Header Content-Length: 605
Content Login request
(TDS)
Gateway to client. Header contains session ID assigned by the TDS servlet.
Query 200 SUCCESS HTTP/1.0

TDS-Session: TDS00245817298274292
Content Login acknowledgment
(TDS) EED
Client to gateway. Headers for all subsequent requests contain the session ID.
Query POST/tds?TDS-Session=TDS00245817298274292&Operation=more HTTP/1.0

Content Query “SELECT * from authors”
(TDS)

Using the TDS-tunneling Servlet jConnect for JDBC version 4.0
Gateway to client. Headers for all subsequent responses contain the session ID.
Query 200 SUCCESS HTTP/1.0

TDS-Session: TDS00245817298274292
Content Row format and some rows from query response
(TDS)
TDS-tunneling Servlet System Requirements
To use the jConnect servlet for TDS-tunneled HTTP, you need the
following:
• A Web server that supports javax.servlet interfaces. To install the
server, follow the instructions that are provided with it.
• A Web browser that supports JDK 1.1, such as Netscape 4.0,
Internet Explorer 4.0, or HotJava.
Installing the Servlet
Your jConnect installation includes a gateway subdirectory under the

classes directory. The gateway subdirectory contains files required for
the TDS-tunneling servlet.
Copy the jConnect gateway package to a gateway subdirectory under
your Web server’s servlets directory. Once you have copied the
servlets, follow the instructions for your Web server to activate the
servlets.
Setting Servlet Arguments
When you add the servlet to your Web server, you can enter optional
arguments to customize performance. You can enter the following
arguments:
• TdsResponseSize–Use this parameter to set the maximum TDS
packet size for the tunneled HTTPS. A larger TdsResponseSize is
more efficient if you have only a few users with a large volume of
data. Use a smaller TdsResponseSize if you have many users
making smaller transactions.
• TdsSessionIdleTimeout–Use this parameter to define the amount of
time (in milliseconds) that the server connection can remain idle

jConnect for JDBC version 4.0 Using the TDS-tunneling Servlet
before the connection is automatically closed. The default

TdsSessionIdleTimeout is 600,000 (10 minutes).
If you have interactive client programs that may be idle for long
periods of time and you don’t want the connections broken,
increase the TDSSessionIdleTimeout.
You can also set the connection timeout value from the jConnect
client using the SESSION_TIMEOUT connection property. This
is useful if you have specific applications that may be idle for
longer periods. In this case, set a longer timeout for those
connections with the SESSION_TIMEOUT connection property,
rather than setting it for the servlet.
• Debug–Use this parameter to turn on debugging. See “Debugging
with jConnect” on page 3-1.
Enter the servlet arguments in a comma-delimited string. For
example:
TdsResponseSize=[size],TdsSessionIdleTimeout=[timeout],Debug=true
Refer to your Web server documentation for complete instructions
on entering servlet arguments.
Invoking the Servlet
jConnect determines when to use the gateway where the TDS-

tunneling servlet is installed based on the path extension of the
PROXY connection property. jConnect recognizes the servlet path
extension to the PROXY and invokes the servlet on the designated
gateway.
Define the connection URL using this format:
http://host:port/TDS-servlet-path
jConnect invokes the TDS-tunneling servlet on the Web server to
tunnel TDS through HTTP. The servlet path must be the path you
defined in your Web server’s servlet alias list.
Tracking Active TDS Sessions
You can view information about active TDS sessions, including the
server connections for each session. Use your Web browser to open
the administrative URL:
http://host:port/TDS-servlet-path?Operation=list

Using the Cascade Gateway jConnect for JDBC version 4.0
For example, if your server is MYSERVER and the TDS servlet path
is /tds, you would enter:
http://myserver:8080/tds?Operation=list
This shows you a list of active TDS sessions. You can click on a
session to see more information, including the server connection.
Terminating TDS Sessions
You can use the URL described above to terminate any active TDS
session. Click on an active session from the list of sessions on the first
page, then click Terminate This Session.
Resuming a TDS Session
You can set the SESSION_ID connection property so that, if

necessary, you can resume an existing open connection. When you
specify a SESSION_ID, jConnect skips the login phase of the protocol
and resumes the connection with the gateway using the designated
session ID. If the session ID you specified does not exist on the
servlet, jConnect throws a SQL exception the first time you attempt
to use the connection.
Using the Cascade Gateway

If your database server runs on a different host than the Web server,
even if there is no firewall, you need a gateway to act as a proxy,
providing a path to the database server.
The jConnect installation includes a Cascade gateway, a slightly
modified version of the Cascade Web server written in Java by David
Wilkerson (email: [email protected]; Web site:
http://www.cascade.org.uk/). The Cascade gateway receives and
forwards packets, switching from HTTP to TDS when sending a
request to the Adaptive Server, and from TDS to HTTP when
returning results.
➤ Note
The Cascade gateway does not support encryption, and therefore is not
suitable for Internet applications that connect to a back-end server through
a firewall.

jConnect for JDBC version 4.0 Using the Cascade Gateway
Usage Requirements
• If you did not install jConnect in the default installation directory,
you must edit www.dos (DOS) or www.template (UNIX) and
change all default installation directory references to point to the
literal path where you installed jConnect.
• The Cascade gateway and your Web server must run on the same
host machine. This way, applets connect to the same host as the
Web server, but to the port controlled by the Cascade gateway.
The gateway routes the request to the appropriate database. To
see how this is accomplished, review the code in Isql.java and
gateway.html in the sample subdirectory of the jConnect
installation directory. Search for “proxy”.
If your database server runs on the same host as your Web server,
you do not need the Cascade gateway.
Installing the Cascade Gateway
The Cascade gateway is installed when you perform a full jConnect

installation, either using the jConnect installer, or using the install.bat
or install.sh files. You can also use the jConnect installer to install only
the Cascade gateway files, if necessary. See the Sybase JConnect for
JDBC Installation Guide and Release Bulletin.
Starting the Cascade Gateway
Follow the platform-specific instructions below to install and test the

Cascade gateway.
Windows NT and Windows 95
1. At a DOS prompt, change to the jConnect installation directory.

Your JDBC_HOME environment variable should be set to this
directory.
2. If you did not install jConnect in the default directory,
C:\Program Files\Sybase\jConnect, modify the www.dos file in
your installation directory:
- Open www.dos using a text editor and change the directory
path following “DocumentRoot” to your jConnect installation
directory.

3. From your jConnect installation directory, start the Cascade

gateway. Enter:
httpd
If the command executes successfully, you see output from
httpd.bat, ending with:
HTTPDServer www.dos
UNIX
Change to the directory where you installed jConnect (the

JDBC_HOME directory). Type the following command:
sh httpd.sh &
Troubleshooting
• If you do not see a message after you enter the httpd command, the
server is not running. Retry the command in verbose mode.
For Windows, go to a DOS prompt and enter:
httpd -Dverbose=1 > filename
For UNIX, enter:
sh httpd.sh -Dverbose=1 > filename &
In these commands, filename is the output file for debug
messages.
• If you receive this error message:
HTTPServer: IOException: getRequest() Address
already in use
it means another process is running on the default port (8000).
You can:
- Stop the process that is currently running on port 8000. After
verifying that the process has terminated, try starting the
gateway.
- Change the port number in the www.dos (DOS) or www.template
(UNIX) file, located in JDBC_HOME, then modify the
gateway.html file, located in the sample subdirectory of
JDBC_HOME, by changing the PROXY parameter from
“localhost:8000” to “localhost:new_port”. If your host is not
“localhost” (which is true if your Cascade gateway and

browser are on different hosts), make sure that the PROXY

parameter uses the remote host name rather than “localhost.”
Testing the Cascade Gateway
To check your setup and test the Cascade gateway, you can run a
validation program that connects to the Sybase demonstration
database.
➤ Note
The Validate program is hardcoded to use “localhost:8000” for testing your
gateway.
From the DOS prompt for Windows NT or Windows 95, or at a UNIX

prompt, change to the JDBC_HOME directory. Type:
java sample.SybSample Validate
If the validation is successful, you see the jConnect version number
and the message “Connected successfully” in the Sample output
window.
Troubleshooting
If you receive a “Bad command or file name” error (Windows 95) or

a “Name specified is not recognized as an internal or external
command” error (Windows NT), make sure that your path includes
the \bin subdirectory of the JDK home directory.
Read the index.html File
Use your Web browser to view the index.html file in your jConnect
installation directory. index.html provides links to the jConnect
documentation and sample code.
➤ Note
If you use Netscape on the same machine on which you have installed
jConnect, you need to make sure that your browser does not have access
to your CLASSPATH environment variable. See “Restrictions on Setting
CLASSPATH When You Use Netscape” in Chapter 3 of the Sybase
jConnect for JDBC Installation Guide and Release Bulletin.

1. Open your Web browser.

2. Enter the URL that matches your setup. For example, if your
browser and the Cascade gateway are running on the same host,
enter:
http://localhost:8000/index.html
If the browser and the Cascade gateway are running on different
hosts, enter:
http://host:port/index.html
where host is the name of the host on which the Cascade gateway
is running, and port is the listening port.
Troubleshooting
If you entered the correct host, port, and file information, but the
browser cannot open this link, the Cascade gateway is not running.
See “Starting the Cascade Gateway” on page A-11.
Running the Sample Isql Applet
After loading the index.html file in your browser:

1. Click “Run Sample JDBC Applets.”
This takes you to the jConnect Sample Programs page.
2. Move down the Sample Programs page to find the table under
“Executable Samples.”
3. Locate “Isql.java” in the table and click on “Run” at the end of
the row.
The sample Isql.java applet prompts for a simple query on a sample
database and displays the results. The applet displays a default
Adaptive Server host name, port number, user name (guest),
password (sybase), database, and query. Using the default values, the
applet connects to the Sybase demonstration database. It returns
results after you click Go.
Troubleshooting
Under UNIX, if the applet does not appear as expected, you can
modify the applet screen dimensions:

1. Use a text editor to edit $JDBC_HOME/sample/gateway.html.

2. Change the height parameter in line 7 to 650. You can
experiment with different height settings.
3. Reload the Web page on your browser.
Defining a Connection to the Cascade Gateway
To define a connection in your application that uses the Cascade

gateway, put the name of the host on which the Cascade gateway is
running in the URL:
host:port
where host is the name of the host on which the Cascade gateway is
running, and port is the listening port.


B SQL Exception and Warning
Messages B.
The following table lists the SQL exception and warning messages
that you may encounter when using jConnect.
SQLState Message/Description/Action
010DP Duplicate connection property _____ ignored.
A connection property is defined twice. It may be defined twice in the driver
connection properties list with different capitalization, for example
“password” and “PASSWORD”. Connection property names are not case
sensitive, and therefore jConnect does not distinguish between property names
with the same name but different capitalization.
The connection property may also be defined both in the connection properties
list, as well as in the URL. In this case, the property value in the connection
property list takes precedence.
Action: Make sure your application only defines the connection property once.
However, you may want you application to take advantage of the precedence
of connection properties defined in the property list over those defined in the
URL. In this case, you can safely ignore this warning.
010MX Metadata accessor information was not found on this database. Error
encountered while attempting to retrieve metadata information: _____
The server may not have the necessary stored procedures for returning
metadata information.
Action: Make sure that stored procedures for providing metatdata are installed
on the server. See “Installing Stored Procedures” in Chapter 3 of the jConnect for
JDBC Installation Guide and Release Bulletin.
010P4 An output parameter was received and ignored.
The query you executed returned an output parameter but the application
result-processing code did not fetch it so it was ignored.
Action: If your application needs that output parameter data, you must rewrite
the application so it can get it. This may require using a CallableStatement to
execute the query, and adding calls to registerOutputParameter() and getXXX().
010SN Permission to write to file was denied. File: _____. Error message: _____
Permission to write to a file specified in the PROTOCOL_CAPTURE
connection property is denied because of a security violation in the VM. This
can occur if an applet attempts to write to the specified file.
Action: If you are attempting to write to the file from an applet, make sure that
the applet has access to the target file system.
010SP File could not be opened for writing. File: _____. Error message: _____
Action: Make sure that the file name is correct and that the file is writeable.
jConnect for JDBC Programmer’s Reference B-1

010UF Attempt to execute use database command failed. Error message:_____
jConnect was unable to connect to the database specified in the connection
URL. Two possibilities are:
• The name was entered incorrectly in the URL.
• USE_METADATA is “true” (the default condition), but the stored
procedures for returning metadata have not been installed. As a result,
jConnect tried to execute the use database command with the database in the
URL, but the command failed. This may be because you attempted to access
a SQL Anywhere database. SQL Anywhere databases do not support the use
database command.
Action: Make sure the database name in the URL is correct. Make sure that the
stored procedures for returning metadata are installed on the server (see
“Installing Stored Procedures” in Chapter 3 of the jConnect for JDBC Installation
Guide and Release Bulletin). If you are attempting to access a SQL Anywhere
database, either do not specify a database name in the URL or set
USE_METADATA to “false.”
010UP Unrecognized connection property _____ ignored.
You attempted to set a connection property in the URL that jConnect does not
currently recognize. jConnect ignores the unrecognized property.
Action: Check the URL definition in your application to make sure it references
only valid jConnect driver connection properties.
010SJ Metadata accessor information was not found on this database.
The metadata information is not configured on the server.
Action: If your application requires metadata, install the stored procedures for
returning metadata that come with jConnect (see “Installing Stored
Procedures” in Chapter 3 of the jConnect for JDBC Installation Guide and Release
Bulletin). If you do not need metadata, set the USE_METADATA property to
“false.”
010SK Database cannot set connection option _____.
Your application attempted an operation which the database you are connected
to does not support.
Action: You may need to upgrade your database or make sure that the latest
version of MetaData information is installed on it.
JW0I0 I/O layer: thread operation failed.
An internal error occurred with a timed I/O stream.
Action: Close and reopen the connection.
JZ001 User name property ‘_____’ too long. Maximum length is 30.
Action: Do not exceed the 30 byte maximum.
B-2 SQL Exception and Warning Messages

JZ002 Password property ‘_____’ too long. Maximum length is 30.
Action: Do not exceed the 30-byte maximum.
JZ003 Incorrect URL format. URL: _____
Action: These are the possible URL formats when you specify jdbc:sybase:Tds:
jdbc:sybase:Tds:host:port/
jdbc:sybase:Tds:host:port/database
jdbc:sybase:Tds:host:port/database&property=value
In these formats:
jdbc:sybase–identifies the driver
Tds–the Sybase transfer protocol for SQL Server
host–the SQL Server host name
port–the listening port
database–use named database (preceded by a slash ‘/’)
property–a valid jConnect driver connection property name
value–value for setting the specified connection property
If you are using the PROXY connection property, you may get a JZ003
exception while trying to connect if the format for the PROXY property is
incorrect.
The PROXY format for the Cascade proxy is:
ip_address:port_number
The PROXY format for the TDS Tunneling Servlet is:
http[s]://host:port/tunneling_servlet_alias
JZ004 User name property missing in DriverManager.getConnection(..., Properties)
Action: Provide the required user property.
JZ006 Caught IOException: _____
An unexpected I/O error was detected from a lower layer. When such I/O
exceptions are caught, they are re-thrown as SQL exceptions using the
ERR_IO_EXCEPTION sqlstate. These errors are often the result of network
communication problems.
Action: Try increasing the statement cache size.

JZ008 Invalid column index value _____.
You have requested a column index value of less than 1 or greater than the
highest available value.
Action: Check call to the getXXX() method and the text of the original query, or
be sure to call rs.next().
JZ009 Error encountered in conversion. Error message: _____
Some of the possibilities are:
• A conversion between two incompatible types was attempted, as in going
from a date to an int.
• There was an attempt to convert a string containing a non-numeric character
to a numeric type.
• There was a formatting error, such as an incorrectly formatted time/date
string.
Action: Make sure that the JDBC specification supports the attempted type
conversion. Make sure that strings are correctly formatted. If a string contains
non-numeric characters, do not attempt to convert it to a numeric type.
JZ00B Numeric overflow.
You tried to send a BigInteger as a TDS numeric, and the value was too large, or
you tried to send a Java long as an int and the value was too large.
Action: These values cannot be stored in Sybase. For long, consider using a
Sybase numeric. There is no solution for Bignum.
JZ00D getCursorName() called without a previous call to setCursorName().
You called rs.getCursorName without previously calling stmt.setCursorName.
Action: Call stmt.setCursorName before calling rs.getCursorName.
JZ00E Attempt to call execute() or executeUpdate() for a statement where
setCursorName() has been called.
Action: Don’t try to call execute or executeUpdate on a statement that has a
cursor name set. Use a separate statement to delete or update a cursor.
JZ00F Cursor name has already been set by setCursorName().
Action: Do not set the cursor name twice for a statement. Close the result set of
the current cursor statement.
JZ00G No column values were set for this row update.
Action: You attempted to update a row in which no column values were
changed. To change column values in a row, call updateXX() methods before
calling updateRow().

JZ00H The result set is not updatable. Use Statement.setResultSetConcurrencyType().
Action: To change a result set from read-only to updatable, use the
Statement.setResultSetConcurrencyType() method or add a for update clause to your
SQL select statement.
JZ00L Login failed. Examine the SQLWarnings chained to this exception for the
reason(s).
Action: See message text; proceed according to the reason(s) given for the login
failure.
JZ010 Unable to deserialize an Object value. Error text: _____
Action: Make sure that the Java object from the database implements the
Serializable interface and is in your local CLASSPATH variable.
JZ011 Number format exception encountered while parsing numeric connection
property _____.
A non-integer value was specified for a numeric connection property.
Action: Specify an integer value for the connection property.
JZ012 Internal Error. Please report it to Sybase technical support. Wrong access type
for connection property _____.
Action: Contact Sybase Technical Support.
JZ013 Error obtaining JNDI entry: _____
Action: Correct the JNDI URL or make a new entry in the directory service.
JZ0BD Out of range or invalid value used for method parameter.
Action: Check the parameter value in the method to make sure that it is correct.
JZ0C0 Connection is already closed.
The application has already called Connection.close() on this connection object; it
cannot be used any more.
Action: Fix the code so that Connection object references are nulled out
whenever a connection is closed.
JZ0D0 This jConnect installation has not been registered yet. You need to install the
appropriate SybDriverKey classes.
Action: Go to the jConnect Web site to register your jConnect software
(http://www.sybase.com/products/internet/jconnect/). Once you register,
you can download the SybDriverKey classes necessary to activate the jConnect
driver.

JZ0D1 Invalid SybDriverKey for this jConnect driver.
You tried accessing the jConnect driver with an activation key that does not
match the jConnect driver you are using.
Action: Go to the jConnect Web site to download a valid activation key for the
jConnect driver you are using:
http://www.sybase.com/products/internet/jconnect/.
JZ0D2 Your Sybase JDBC license expired on _____. Please obtain a new license.
Action: Contact Sybase to obtain a new license for your jConnect driver.
JZ0D3 Your Sybase JDBC license will expire soon. Please obtain a new license. It will
expire on _____.
Action: Contact Sybase to obtain a new license for your jConnect driver.
JZ0D4 Unrecognized protocol in Sybase JDBC URL:_____.
You specified a connection URL using a protocol other than TDS, which is the
only protocol currently supported by jConnect.
Action: Check the URL definition. If the URL specifies TDS as a subprotocol
make sure that the entry uses the following format and capitalization:
If the URL specifies JNDI as a subprotocol, make sure that it starts with:
jdbc:sybase:jndi:
JZ0D5 Error loading protocol _____.
Action: Check the settings for the CLASSPATH system variable.
JZ0D6 Unrecognized version number _____ specified in setVersion. Choose one of the
SybDriver.VERSION_* values, and make sure that the version of jConnect that
you are using is at or beyond the version you specify.
Action: See message text.
JZ0D7 Error loading url provider _____. Error message: _____
Action: Check the JNDI URL to make sure it is correct.
JZ0D8 Error initializing url provider: _____
Action: Check the JNDI URL to make sure it is correct.
JZ0EM End of data.
Action: Report this error to Sybase Technical Support.
JZ0H0 Unable to start thread for event handler; event name = _____.

JZ0H1 An event notification was received but the event handler was not found; event
name = _____.
JZ0HC Illegal character ‘_____’ encountered while parsing hexadecimal number.
A string that is supposed to represent a binary value contains a character that is
not in the range (0–9, a–f) that is required for a hexadecimal number.
Action: Check the character values in the string to make sure they are in the
required range.
JZ0I1 I/O Layer: Error reading stream.
The connection was unable to read the amount requested. Most likely, the
statement timeout period was exceeded and the connection timed out.
Action: Increase the statement timeout value.
JZ0I2 I/O layer: Error writing stream.
The connection was unable to write the output requested. Most likely, the
statement timeout period was exceeded and the connection timed out.
Action: Increase the statement timeout value.
JZ0I3 Unknown property. This message indicates an internal product problem.
Report this error to Sybase Technical support.
Action: Indicates an internal product problem. Report this error to Sybase
Technical Support.
JZ0I5 An unrecognized CHARSET property was specified: _____.
You specified a character set code for the CHARSET connection property that is
not supported.
Action: Enter a valid character set code for the connection property. See
“jConnect Character-Set Converters” on page 2-23.
JZ0I6 An error occurred converting UNICODE to the charset used by the server.
Error message: _____
Action: Choose a different charset code for the CHARSET connection property
on the jConnect client that can support all the characters you need to send to
the server. You may need to install a different character set on the server, too.
JZ0I7 No response from proxy gateway.
The Cascade or security gateway is not responding.
Action: Make sure the gateway is properly installed and running.

JZ0I8 Proxy gateway connection refused. Gateway response: _____
The Web server/gateway indicated by the PROXY connection property has
refused your connection request.
Action: Check the access and error logs on the proxy to determine why the
connection was refused. Make sure the proxy is a JDBC gateway.
JZ0I9 This InputStream was closed.
You tried to read an InputStream obtained from getAsciiStream(),
getUnicodeStream(), or getBinaryStream(), but the InputStream was already closed.
The stream may have been closed because you moved to another column or
cancelled the result set and there were not enough resources to cache the data.
Action: Increase the cache size or read columns in order.
JZ0IA Truncation error trying to send_____.
There was a truncation error on charset conversion prior to sending a string.
The converted string is longer than the size allocated for it.
Action: Choose a different charset code for the CHARSET connection property
on the jConnect client that can support all the characters you need to send to
the server. You may need to install a different character set on the server, too.
JZ0IS Reading this InputStream would disable the ability to use it to update the
database.
After updating a column in a result set, you attempted to read the updated
column value using one of the following SybResultSet methods: getAsciiStream(),
getUnicodeStream(), getBinaryStream(). jConnect does not support this usage.
Action: Do not attempt to fetch input streams from columns you are updating.
JZ0J0 Offset and/or length values exceed the actual text/image length.
Action: Check the offset and/or length values you used to make sure they are
correct.
JZ0NC wasNull called without a preceding call to get a column.
You can only call wasNull() after a call to get a column, such as getInt() or
getBinaryStream().
Action: Change the code to move the call to wasNull().
JZ0NE Incorrect URL format. URL: _____. Error message: _____
Action: Check the format of the URL. Make sure that the port number consists
only of numeric characters.
JZ0NF Unable to load SSLSocketFactory. Make sure that you have spelled the class
name correctly, that the package is fully specified, that the class is available in
your class path, and that it has a public zero-argument constructor.

JZ0P1 Unexpected result type.
The database has returned a result that the statement cannot return to the
application, or that the application is not expecting at this point. This generally
indicates that the application is using JDBC incorrectly to execute the query or
stored procedure. If the JDBC application is connected to an Open Server
application, it may indicate an error in the Open Server application that causes
the Open Server to send unexpected sequences of results.
Action: Use the com.sybase.utils.Debug(true, “ALL”) debugging tools to try to
figure out what unexpected result is seen, and to understand its causes.
JZ0P4 Protocol error. This message indicates an internal product problem. Reports
this error to Sybase technical support.
Action: Indicates an internal product problem. Report this error to Sybase
Technical Support.
JZ0P7 Column is not cached; use RE-READABLE_COLUMNS property.
With the REPEAT_READ connection property set to “false, ” an attempt was
made to reread a column or read a column in the wrong order.
When REPEAT_READ is “false.” You can only read the column value for a row
once, and you can only read columns in ascending column-index order. For
example, after reading Column 3 for a row, you cannot read its value a second
time and you cannot read Column 2 for the row.
Action: Either set REPEAT_READ to “true,” or do not attempt to reread a
column value and make sure that you read columns in ascending column-
index order.
JZ0P8 The RSMDA Column Type Name you requested is unknown.
jConnect was unable to determine the name of a column type in the
ResultSetMetaData.getColumnTypeName() method.
Action: Check to make sure that your database has the most recent stored
procedures for metadata.
JZ0P9 A COMPUTE BY query has been detected. That type of result is unsupported
and has been cancelled.
The query you executed returned COMPUTE results, which are not supported
by jConnect.
Action: Change your query or stored procedure so it does not use COMPUTE
BY.
JZ0PA The query has been cancelled and the same response discarded.
A cancel was probably issued by another statement on the connection.
Action: Check the chain of SQL exceptions and warnings on this and other
statements to determine the cause.

JZ0PB The server does not support a requested operation.
When jConnect creates a connection with a server, it informs the server of
capabilities it wants supported and the server informs jConnect of the
capabilites that it supports. This error message is sent when an application
requests an operation that was denied in the original capabilities negotiation.
For example, if the database does not support precompilation of dynamic SQL
statements, and your code invokes SybConnection.prepareStatement(sql_stmt,
dynamic), and dynamic is set to “true,” jConnect will generate this message.
Action: Modify your code so that it does not request an unsupported
capability.
JZ0R0 Result set has already been closed.
The ResultSet.close() method has already been called on the result set object; you
cannot use the result set for anything else.
Action: Fix the code so that ResultSet object references are nulled whenever a
result set is closed.
JZ0R1 Result set is IDLE as you are not currently accessing a row.
The application has called one of the ResultSet.getXXX column-data retrieval
methods, but there is no current row; the application has not called
ResultSet.next(), or ResultSet.next() returned “false” to indicate that there is no
data.
Action: Check that rs.next() is set to “true” before calling rs.getXXX.
JZ0R2 No result set for this query.
You used Statement.executeQuery(), but the statement returned no rows.
Action: Use executeUpdate for statements returning no rows.
JZ0R3 Column is DEAD. This is an internal error. Please report it to Sybase technical
support.
Action: This is an internal code error. Contact Sybase technical support.
JZ0R4 Column does not have a text pointer. It is not a text/image column or the
column is NULL.
You cannot update a text/image column if it is NULL. A NULL text/image
column does not contain a text pointer.
Action: Make sure that you are not trying to update or get a text pointer to a
column that does not support text/image data. Make sure that you are not
trying to update a text/image column that is NULL. Insert data first, then make
the update.

JZ0RM The last update or delete on this row was successful. The row cannot be
refreshed from the database.
After deleting a row from the database with SybCursorResult.deleteRow(), you
used SybCursorResult.getXXX() to read a column value belonging to the deleted
row in your current result set.
Action: Do not attempt to reread a column value in a result set after deleting its
row from the database.
JZ0S0 Statement state machine: Statement is BUSY.
The only time this error is raised is from the Statement.setCursorname() method,
if the application is trying to set the cursor name when the statement is already
in use and has non-cursor results that need to be read.
Action: Set the cursor name on a statement before you execute any queries on
it, or call Statement.cancel() before setting the cursor name, to make sure that the
statement isn't busy.
JZ0S1 Statement state machine: Trying to FETCH on IDLE statement.
An internal error occurred on the statement.
Action: Close the statement and open another one.
JZ0S2 Statement object has already been closed.
The Statement.close() method has already been called on the statement object;
you cannot use the statement for anything else.
Action: Fix the application so that statement object references are nulled out
whenever a statement is closed.
JZ0S3 The inherited method _____ cannot be used in this subclass.
PreparedStatement does not support executeQuery(String), executeUpdate(String), or
execute(String).
Action: If you want to pass a query string, use Statement, not PreparedStatement.
JZ0S4 Cannot execute an empty (zero-length) query.
Action: Do not execute an empty query (““).
JZ0S8 An escape sequence in a SQL Query was malformed: ‘_____’.
This error results from bad escape syntax.
Action: Check JDBC documentation for correct syntax.
JZ0S9 Cannot execute an empty (zero-length) query.
Action: Do not execute an empty query (““).
JZ0SA Prepared Statement: Input parameter not set, index: _____.
Action: Make sure that each input parameter has a value.

JZ0SB Parameter index out of range: _____.
You have attempted to get, set, or register a parameter that goes beyond the
maximum number of parameters.
Action: Check the number of parameters in your query.
JZ0SC Callable Statement: attempt to set the return status as an InParameter.
You have prepared a call to a stored procedure that returns a status, but you are
trying to set parameter 1, which is the return status.
Action: Parameters that you can set start at 2 with this type of call.
JZ0SD No registered parameter found for output parameter.
This indicates an application logic error. You attempted to call getXXX() or
wasNull() on a parameter, but you have not read any parameters yet, or there are
no output parameters.
Action: Check to make sure that the application has registered output
parameters on the CallableStatement, that the statement has been executed,
and that the output parameters were read.
JZ0SE Invalid object type specified for setObject().
Illegal type argument passed to PreparedStatement.setObject.
Action: Check the JDBC documentation. The argument must be a constant
from java.sql.Types.
JZ0SF No Parameters expected. Has query been sent?
You tried to set a parameter on a statement with no parameters.
Action: Make sure the query has been sent before you set the parameters.
JZ0SG A CallableStatement did not return as many output parameters as the
application had registered for it.
Action: Check your stored procedures and registerOutParameter calls.
JZ0SH A static function escape was used, but the metadata accessor information was
not found on this server.
Action: Install metadata accessor information before using static function
escapes.
JZ0SI A static function escape _____ was used which is not supported by this server.
Action: Do not use this escape.
JZ0SJ Metadata accessor information was not found on this database.
Action: Install metadata information before making metadata calls.
JZ0SM Unsupported SQL type _____.
Action: Do not use Types.NULL, Types.OTHER, or PreparedStatement.setObject(null)

JZ0SN setMaxFieldSize: field size cannot be negative.
Action: Use a positive value or zero (unlimited) when calling setMaxFieldSize.
JZ0T2 Listener thread read error.
Action: Check your network communications.
JZ0T3 Read operation timed out.
The time allotted to read the response to a query was exceeded.
Action: Increase the timeout period by calling Statement.setQueryTimeout().
JZ0T4 Write operation timed out. Timeout in milliseconds: _____.
The time allotted to send a request was exceeded.
Action: Increase the timeout period by calling Statement.setQueryTimeout().
JZ0T5 Cache used to store responses is full.
Action: Use default or larger value for the STREAM_CACHE_SIZE connection
property.
JZ0T6 Error reading tunneled TDS URL.
The tunneled protocol failed while reading the URL header.
Action: Check the URL you defined for the connection.
JZ0T7 Listener thread read error -- caught ThreadDeath. Check network connection.
Action: Check the network connections and try to run the application again. If
the threads continue to be aborted, contact Sybase Technical Support.
JZ0T9 Request to send not synchronized. Please report this error to Sybase Technical
Support.
Action: Report the error to Sybase Technical Support.
JZ0TC Attempted conversion between an illegal pair of types.
Conversion between a Java type and a SQL type failed.
Action: Check the requested type conversion to make sure it is supported in
the JDBC specification.
JZ0US The SSL_SOCKET_FACTORY connection property was set, and the PROXY
connection property was set to the URL of a servlet. The jConnect driver does
not support this combination. If you want to send secure HTTP from an applet
running within a browser, use a proxy URL beginning with “https://”.
S0022 Invalid column name ‘_____’.
You attempted to reference a column by name and there is no column with that
name.
Action: Check the spelling of the column name.

ZZ00A The method _____ has not been completed and should not be called.
You have attempted to use a method that is not implemented.
Action: Check the release bulletin that came with your version of jConnect for
further information. You can also check the jConnect Web page at
http://www.sybase.com to see whether a more recent version of jConnect
implements the method. If not, do not use the method.

Sybase Jconnect For JDBC PDF

Uploaded by

Document Informationclick to expand document information

Document Informationclick to expand document information

Copyright:

Available Formats

Sybase Jconnect For JDBC PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Sybase Jconnect For JDBC PDF

Uploaded by

Copyright:

Available Formats

Sybase® jConnect™ for JDBC™

jConnect for JDBC version 4.0

Contributing authors: John Adams

jConnect for JDBC Programmer’s Reference v

CANCEL_ALL Connection Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28

Executing Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61

A. Web Server Gateways

jConnect for JDBC Programmer’s Reference vii

Tracking Active TDS Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

B. SQL Exception and Warning Messages

viii Table of Contents

The jConnect for JDBC Programmer’s Reference describes the

About This Book

Other Sources of Information

jConnect for JDBC Programmer’s Reference 1-1

• Technical Library Web site is an HTML version of the Technical

Sybase Certifications on the Web

Technical documentation at the Sybase Web site is updated

If you are a registered SupportPlus user:

• An active support license

Whether or not you are a registered SupportPlus user:

Javadoc Documentation of jConnect Extensions to JDBC

The Java Development Kit (JDK) from JavaSoft contains a javadoc

If You Need Help

jConnect for JDBC Programmer’s Reference 1-3

A set of interfaces is included in the standard JDBC API so you can

Each relational database management system requires a driver to

• Native-protocol/all-Java driver within a two-tier environment.

jConnect for JDBC Programmer’s Reference 1-5

This chapter describes the basic components, programming

The following topics are included in this chapter:

jConnect for JDBC Programmer’s Reference 2-1

• Using Date and Time Datatypes (page 2-47)

jConnect Installation Contents

Table 2-1: jConnect installation contents

Name Type Description

2-2 Programming Information

Table 2-1: jConnect installation contents

Name Type Description

jConnect for JDBC Programmer’s Reference 2-3

Table 2-1: jConnect installation contents

Name Type Description

2-4 Programming Information

JDK 1.1 Samples

Invoking the jConnect Driver

• Use Class.forName().newInstance to create an instance of

Setting Driver Connection Properties

jConnect for JDBC Programmer’s Reference 2-5

There are two ways to set the driver connection properties:

To obtain a current list of properties for any driver, use the

Table 2-2: Connection properties

2-6 Programming Information

Table 2-2: Connection properties

jConnect for JDBC Programmer’s Reference 2-7

Table 2-2: Connection properties

2-8 Programming Information

Table 2-2: Connection properties