API Reference Manual. EAServer 6.0

Transcription

1 API Reference Manual EAServer 6.0

2 DOCUMENT ID: DC LAST REVISED: July 2006 Copyright by Sybase, Inc. All rights reserved. This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement. To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) , fax (617) Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc. Sybase, SYBASE (logo), ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server, Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication, Adaptive Server Everywhere, Advantage Database Server, Afaria, Answers Anywhere, Applied Meta, Applied Metacomputing, AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-Translator, APT-Library, ASEP, Avaki, Avaki (Arrow Design), Avaki Data Grid, AvantGo, Backup Server, BayCam, Beyond Connected, Bit-Wise, BizTracker, Certified PowerBuilder Developer, Certified SYBASE Professional, Certified SYBASE Professional Logo, ClearConnect, Client-Library, Client Services, CodeBank, Column Design, ComponentPack, Connection Manager, Convoy/DM, Copernicus, CSP, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer, DataWindow, DataWindow.NET, DB-Library, dbqueue, Dejima, Dejima Direct, Developers Workbench, DirectConnect Anywhere, DirectConnect, Distribution Director, Dynamic Mobility Model, e-adk, E-Anywhere, e-biz Integrator, E-Whatever, EC Gateway, ECMAP, ECRTP, efulfillment Accelerator, EII Plus, Electronic Case Management, Embedded SQL, EMS, Enterprise Application Studio, Enterprise Client/ Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise Portal (logo), Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer, Enterprise Work Modeler, eprocurement Accelerator, eremote, Everything Works Better When Everything Works Together, EWA, ExtendedAssist, Extended Systems, ExtendedView, Financial Fusion, Financial Fusion (and design), Financial Fusion Server, Formula One, Fusion Powered e-finance, Fusion Powered Financial Destinations, Fusion Powered STP, Gateway Manager, GeoPoint, GlobalFIX, ianywhere, ianywhere Solutions, ImpactNow, Industry Warehouse Studio, InfoMaker, Information Anywhere, Information Everywhere, InformationConnect, InstaHelp, Intelligent Self-Care, InternetBuilder, iremote, irlite, iscript, Jaguar CTS, jconnect for JDBC, KnowledgeBase, Legion, Logical Memory Manager, M2M Anywhere, Mach Desktop, Mail Anywhere Studio, Mainframe Connect, Maintenance Express, Manage Anywhere Studio, MAP, M-Business Anywhere, M-Business Channel, M-Business Network, M-Business Suite, MDI Access Server, MDI Database Gateway, media.splash, Message Anywhere Server, MetaWorks, MethodSet, mfolio, Mirror Activator, ML Query, MobiCATS, MobileQ, MySupport, Net-Gateway, Net-Library, New Era of Networks, Next Generation Learning, Next Generation Learning Studio, O DEVICE, OASiS, OASiS logo, ObjectConnect, ObjectCycle, OmniConnect, OmniQ, OmniSQL Access Module, OmniSQL Toolkit, OneBridge, Open Biz, Open Business Interchange, Open Client, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, Partnerships that Work, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, Pharma Anywhere, PhysicalArchitect, Pocket PowerBuilder, PocketBuilder, Power++, Power Through Knowledge, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, Powering the New Economy, PowerScript, PowerSite, PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst, Pylon, Pylon Anywhere, Pylon Application Server, Pylon Conduit, Pylon PIM Server, Pylon Pro, QAnywhere, Rapport, Relational Beans, RemoteWare, RepConnector, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, Replication Toolkit, Resource Manager, RFID Anywhere, RW-DisplayLib, RW-Library, SAFE, SAFE/PRO, Sales Anywhere, Search Anywhere, SDF, Search Anywhere, Secure SQL Server, Secure SQL Toolset, Security Guardian, ShareSpool, ShareLink, SKILS, smart.partners, smart.parts, smart.script, SOA Anywhere Trademark,SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQL Server SNMP SubAgent, SQL Station, SQLJ, Stage III Engineering, Startup.Com, STEP, SupportNow, S.W.I.F.T. Message Format Libraries, Sybase Central, Sybase Client/Server Interfaces, Sybase Development Framework, Sybase Financial Server, Sybase Gateways, Sybase IQ, Sybase Learning Connection, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase Synergy Program, Sybase Virtual Server Architecture, Sybase User Workbench, SybaseWare, Syber Financial, SyberAssist, SybFlex, SybMD, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, The Enterprise Client/Server Company, The Extensible Software Platform, The Future Is Wide Open, The Learning Connection, The Model For Client/Server Solutions, The Online Information Center, The Power of One, TotalFix, TradeForce, Transact-SQL, Translation Toolkit, Turning Imagination Into Reality, UltraLite, UltraLite.NET, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viafone, Viewer, VisualWriter, VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server, XcelleNet, XP Server, XTNDAccess and XTNDConnect are trademarks of Sybase, Inc. or its subsidiaries. 05/06 Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. All other company and product names used herein may be trademarks or registered trademarks of their respective companies. Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS for the DOD and as set forth in FAR (a)-(d) for civilian agencies. Sybase, Inc., One Sybase Drive, Dublin, CA

3 Contents About This Book... ix CHAPTER 1 Java Classes and Interfaces... 1 Package index... 1 com.sybase.corba.jdbc com.sybase.jaguar.jcm... 1 com.sybase.jaguar.server... 2 com.sybase.jaguar.sql... 2 com.sybase.jaguar.util... 2 com.sybase.corba.jdbc11.idl class... 2 IDL.getDate(java.sql.Date)... 3 IDL.getDecimal(java.math.BigDecimal)... 4 IDL.getMoney(java.math.BigDecimal)... 4 IDL.getResultSet(java.sql.ResultSet)... 4 IDL.getTime(java.sql.Time)... 5 IDL.getTimestamp(java.sql.Timestamp)... 5 com.sybase.corba.jdbc11.idlresultset... 6 com.sybase.corba.jdbc11.sql class... 7 SQL.getBigDecimal(BCD.Decimal)... 8 SQL.getBigDecimal(BCD.Money)... 8 SQL.getDate(MJD.Date)... 9 SQL.getResultSet(TabularResults.ResultSet)... 9 SQL.getTime(MJD.Time)... 9 SQL.getTimestamp(MJD.Timestamp) com.sybase.jaguar.jcm.jcm class JCM.byNameAllowed(String) JCM.getCache(String, String, String) JCM.getCacheByName(String) com.sybase.jaguar.jcm.jcmcache class JCMCache.byNameAllowed() JCMCache.dropConnection(Connection) JCMCache.getConlibName() JCMCache.getConnection(int) JCMCache.getPoolSizeMax() API Reference iii

4 Contents JCMCache.getPoolSizeMin() JCMCache.getProxyConnection(int, String) JCMCache.getName() JCMCache.getPassword() JCMCache.getRemoteServerName() JCMCache.getUserName() JCMCache.releaseConnection(Connection) com.sybase.jaguar.jcm.jconnectionnotfoundexception class com.sybase.jaguar.server.jaguar class Jaguar.getInstanceContext() Jaguar.getHostName() Jaguar.getPassword() Jaguar.getPeerAddress() Jaguar.getServerName() Jaguar.getUserName() Jaguar.inJaguar() Jaguar.writeLog(boolean, String) com.sybase.jaguar.server.jcontext class JContext.createServerResultSetMetaData() JContext.createServerResultSet(JServerResultSetMetaData) 27 JContext.forwardResultSet(ResultSet) JContext.getComponentName() JContext.getPackageName() com.sybase.jaguar.sql.jserverresultset interface JServerResultSet.done() JServerResultSet.findColumn(String) JServerResultSet.getMetaData() JServerResultSet.next() JServerResultSet.setBigDecimal(int, BigDecimal, int) JServerResultSet.setCurrency(int, long) JServerResultSet.setNull(int) JServerResultSet.set<Object>(int, <Object>) com.sybase.jaguar.sql.jserverresultsetmetadata interface JServerResultSetMetaData.setColumnCount(int) JServerResultSetMetaData.setColumnDisplaySize(int, int) JServerResultSetMetaData.setColumnLabel(int, String) JServerResultSetMetaData.setColumnName(int, String) JServerResultSetMetaData.setColumnType(int, int) JServerResultSetMetaData.setCurrency(int, boolean) JServerResultSetMetaData.setNullable(int, int) JServerResultSetMetaData.setPrecision(int, int) JServerResultSetMetaData.setScale(int, int) com.sybase.jaguar.util.jexception class iv EAServer

5 Contents CHAPTER 2 C Routines Reference Alphabetical list of all routines Routines for managing transaction flow Routines for managing cached connections Routines for handling errors in C or C++ components Routines for managing memory in C or C++ components Routines to obtain user login information Unsupported routines JagAlloc JagCmGetCachebyName JagCmGetCachebyUser JagCmGetConnection JagCmGetCtx JagCmGetProxyConnection JagCmReleaseConnection JagCompleteWork JagContinueWork JagDisallowCommit JagFree JagGetHostName JagGetPassword JagGetPeerAddress JagGetUserName JagInTransaction JagIsRollbackOnly JagLog JagRollbackWork JagSleep APPENDIX A Deprecated Java Classes and Interfaces Package Index com.sybase.jaguar.beans.enterprise com.sybase.jaguar.beans.enterprise.enterprisebeanexception class 76 com.sybase.jaguar.beans.enterprise.instancecontext interface InstanceContext.completeWork() InstanceContext.continueWork() InstanceContext.getSharedObjects() InstanceContext.inTransaction() InstanceContext.isRollbackOnly() InstanceContext.rollbackWork() com.sybase.jaguar.beans.enterprise.serverbean interface ServerBean.activate(InstanceContext, String) ServerBean.canReuse() API Reference v

6 Contents ServerBean.deactivate() ServerBean.destroy() com.sybase.jaguar.beans.enterprise.sharedobjectexception class 86 com.sybase.jaguar.beans.enterprise.sharedobjects interface SharedObjects.get(int) SharedObjects.lock(int) SharedObjects.lockNoWait(int) SharedObjects.set(int, Object) SharedObjects.unlock(int) Index vi EAServer

7 Contents API Reference vii

8 Contents viii EAServer

9 About This Book Audience How to use this book This book, the EAServer API Reference Manual, contains reference pages for EAServer proprietary Java classes, C++ classes, ActiveX interfaces, and C routines. EAServer also supports many standard Java 2 Enterprise Edition (J2EE) and CORBA APIs. For information on these, see: The Enterprise JavaBeans User s Guide. The CORBA Components Guide. The relevant standards document for API reference information. For J2EE standards documents, please see the Sun Microsystems J2EE Web pages at For CORBA standards documentation, please see the Object Management Group (OMG) Web site at This book is written as a reference for developers of EAServer applications. Developers should know their development language and programming tools. Chapter 1, Java Classes and Interfaces, documents EAServer s Java classes and interfaces. You will need this information to implement Java components or Java clients. Chapter 2, C Routines Reference, documents EAServer s C library routines. You will need this information to implement C components. Appendix A, Deprecated Java Classes and Interfaces, documents Java classes and interfaces supported solely for backward compatibility. Related documents Core EAServer documentation The core EAServer documents are available in HTML and PDF format in your EAServer software installation and on the SyBooks CD. What s New in EAServer 6.0 summarizes new functionality in this version. The EAServer API Reference Manual (this book) contains reference pages for proprietary EAServer Java classes and C routines. The EAServer Automated Configuration Guide explains how to use Antbased configuration scripts to: API Reference ix

10 Define and configure entities, such as EJB modules, Web applications, data sources, and servers Perform administrative and deployment tasks The EAServer CORBA Components Guide explains how to: Create, deploy, and configure CORBA and PowerBuilder components and component-based applications Use the industry-standard CORBA and Java APIs supported by EAServer The EAServer Enterprise JavaBeans User s Guide describes how to: Configure and deploy EJB modules Develop EJB clients, and create and configure EJB providers Create and configure applications clients Run the EJB tutorial The EAServer Feature Guide explains application server concepts and architecture, such as supported component models, network protocols, servermanaged transactions, and Web applications. The EAServer Java Message Service User s Guide describes how to create Java Message Service (JMS) clients and components to send, publish, and receive JMS messages. The EAServer Migration Guide contains information about migrating EAServer 5.x resources and entities to an EAServer 6.0 installation. The EAServer Performance and Tuning Guide describes how to tune your server and application settings for best performance. The EAServer Security Administration and Programming Guide explains how to: Understand the EAServer security architecture Configure role-based security for components and Web applications Configure SSL certificate-based security for client connections Implement custom security services for authentication, authorization, and role membership evaluation Implement secure HTTP and IIOP client applications Deploy client applications that connect through Internet proxies and firewalls x EAServer

11 About This Book The EAServer System Administration Guide explains how to: Start the preconfigured server and manage it with the Sybase Management Console Create, configure, and start new application servers Define database types and data sources Create clusters of application servers to host load-balanced and highly available components and Web applications Monitor servers and application components Automate administration and monitoring tasks with command line tools The EAServer Web Application Programming Guide explains how to create, deploy, and configure Web applications, Java servlets, and JavaServer Pages. The EAServer Web Services Toolkit User s Guide describes Web services support in EAServer, including: Support for standard Web services protocols such as Simple Object Access Protocol (SOAP), Web Services Language (WSDL), and Uniform, Discovery, and Integration (UDDI) Administration tools for deployment and creation of new Web services, WSDL document creation, UDDI registration, and SOAP management The EAServer Troubleshooting Guide describes procedures for troubleshooting problems that EAServer users may encounter. This document is available only online; see the EAServer Troubleshooting Guide at tg/html/eastg/title.htm. jconnect for JDBC documents EAServer includes the jconnect for JDBC driver to allow JDBC access to Sybase database servers and gateways. The jconnect for JDBC Programmer s Reference is available on the Sybase Product Manuals Web site at 05.prjdbc/html/prjdbc/title.htm&toc=/com.sybase.help.jconnjdbc_6.05/toc.xml. Sybase Software Asset Management User s Guide EAServer includes the Sybase Software Asset Management license manager for managing and tracking your Sybase software license deployments. The Sybase Software Asset Management User s Guide is available on the Getting Started CD and in the EAServer 6.0 collection on the Sybase Product Manuals Web site at htm. API Reference xi

12 Conventions Formatting example commands and methods variable, package, or component File Save package 1 Other sources of information The formatting conventions used in this manual are: To indicate When used in descriptive text, this font indicates keywords such as: Command names used in descriptive text C++ and Java method or class names used in descriptive text Java package names used in descriptive text Property names in the raw format, as when using Ant or jagtool to configure applications rather than the Management Console Italic font indicates: Program variables, such as mycounter Parts of input text that must be substituted, for example: Server.log File names Names of components, EAServer packages, and other entities that are registered in the EAServer naming service Menu names and menu items are displayed in plain text. The vertical bar shows you how to navigate menu selections. For example, File Save indicates select Save from the File menu. Monospace font indicates: Information that you enter in the Management Console, a command line, or as program text Example program fragments Example output fragments Use the Sybase Getting Started CD, the SyBooks CD, and the Sybase Product Manuals Web site to learn more about your product: The Getting Started CD contains release bulletins and installation guides in PDF format, and may also contain other documents or updated information not included on the SyBooks CD. It is included with your software. To read or print documents on the Getting Started CD, you need Adobe Acrobat Reader, which you can download at no charge from the Adobe Web site using a link provided on the CD. The SyBooks CD contains product manuals and is included with your software. The Eclipse-based SyBooks browser allows you to access the manuals in an easy-to-use, HTML-based format. Some documentation may be provided in PDF format, which you can access through the PDF directory on the SyBooks CD. To read or print the PDF files, you need Adobe Acrobat Reader. xii EAServer

13 About This Book Refer to the SyBooks Installation Guide on the Getting Started CD, or the README.txt file on the SyBooks CD for instructions on installing and starting SyBooks. The Sybase Product Manuals Web site is an online version of the SyBooks CD that you can access using a standard Web browser. In addition to product manuals, you will find links to EBFs/Maintenance, Technical Documents, Case Management, Solved Cases, newsgroups, and the Sybase Developer Network. Sybase certifications on the Web To access the Sybase Product Manuals Web site, go to Product Manuals at Technical documentation at the Sybase Web site is updated frequently. Finding the latest information on product certifications 1 Point your Web browser to Technical Documents at 2 Select Products from the navigation bar on the left. 3 Select a product name from the product list and click Go. 4 Select the Certification Report filter, specify a time frame, and click Go. 5 Click a Certification Report title to display the report. Creating a personalized view of the Sybase Web site (including support pages) Set up a MySybase profile. MySybase is a free service that allows you to create a personalized view of Sybase Web pages. Sybase EBFs and software maintenance 1 Point your Web browser to Technical Documents at 2 Click MySybase and create a MySybase profile. Finding the latest information on EBFs and software maintenance 1 Point your Web browser to the Sybase Support Page at 2 Select EBFs/Maintenance. If prompted, enter your MySybase user name and password. 3 Select a product. API Reference xiii

14 Accessibility features 4 Specify a time frame and click Go. A list of EBF/Maintenance releases is displayed. Padlock icons indicate that you do not have download authorization for certain EBF/Maintenance releases because you are not registered as a Technical Support Contact. If you have not registered, but have valid information provided by your Sybase representative or through your support contract, click Edit Roles to add the Technical Support Contact role to your MySybase profile. 5 Click the Info icon to display the EBF/Maintenance report, or click the product description to download the software. EAServer has been tested for compliance with U.S. government Section 508 Accessibility requirements. The online help for this product is also provided in Eclipse help formats, which you can navigate using a screen reader. The Web console supports working without a mouse. For more information, see Keyboard navigation in Chapter 2, Management Console Overview, in the EAServer System Administration Guide. The Web Services Toolkit plug-in for Eclipse supports accessibility features for those that cannot use a mouse, are visually impaired, or have other special needs. For information about these features see the Eclipse help: 1 Start Eclipse. 2 Select Help Help Contents. 3 Enter Accessibility in the Search dialog box. 4 Select Accessible User Interfaces or Accessibility Features for Eclipse. Note You may need to configure your accessibility tool for optimal use. Some screen readers pronounce text based on its case; for example, they pronounce ALL UPPERCASE TEXT as initials, and MixedCase Text as words. You might find it helpful to configure your tool to announce syntax conventions. Consult the documentation for your tool. For additional information about how Sybase supports accessibility, see Sybase Accessibility at The Sybase Accessibility site includes links to information on Section 508 and W3C standards. xiv EAServer

15 About This Book 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, please have the designated person contact Sybase Technical Support or the Sybase subsidiary in your area. API Reference xv

16 xvi EAServer

17 CHAPTER 1 Java Classes and Interfaces Package index com.sybase.corba.jdbc11 For use in classes that will be run in a JDK-1.1-compatible Java virtual machine. Provides classes for converting between EAServer s predefined IDL datatypes and the core Java language objects: IDL Provides methods to convert core Java datatypes to EAServer s predefined CORBA IDL datatypes. IdlResultSet Implements the JServerResultSet interface, allowing you to construct TabularResults.ResultSet instances for component methods that return row results. SQL Provides methods to convert EAServer s predefined CORBA IDL datatypes to core Java datatypes. Note Open source implementations of the TabularResults classes are available on the EAServer CodeXchange pages at com.sybase.jaguar.jcm Classes and interfaces for managing cached JDBC connections in serverside Java code: com.sybase.jaguar.jcm.jcm class Provides access to JDBC data sources. com.sybase.jaguar.jcm.jcmcache class Manages a pool of JDBC connections to a third-tier database server. com.sybase.jaguar.jcm.jconnectionnotfoundexception class Exception thrown when no connections are available. API Reference 1

18 com.sybase.corba.jdbc11.idl class com.sybase.jaguar.server Utility classes used in server-side Java code: com.sybase.jaguar.server.jaguar class Provides utility methods for use in server-side Java code. com.sybase.jaguar.server.jcontext class Instantiates objects that are used to send result sets from a Java component method and provides a method to retrieve rows from a java.sql.resultset and forward them to the client. com.sybase.jaguar.sql Interfaces for objects that construct and send row results from a Java server component to the client: com.sybase.jaguar.sql.jserverresultset interface Provides methods to return result rows to a client application. JServerResultSet is similar to the java.sql.resultset interface, which is used to retrieve result rows from a server. com.sybase.jaguar.sql.jserverresultsetmetadata interface Provides methods for describing the metadata of a result set. Metadata specifies the number of columns in each row as well as the datatype, format, nullability, and so forth for each column. com.sybase.jaguar.util Utility classes that are used in both server-side and client side Java code: com.sybase.jaguar.util.jexception class JException is the generic exception that is thrown by methods in the EAServer classes or in generated client stub classes. com.sybase.corba.jdbc11.idl class package com.sybase.corba.jdbc11; public abstract class IDL 2 EAServer

19 CHAPTER 1 Java Classes and Interfaces Constructors Provides methods to convert core Java datatypes to EAServer s predefined CORBA IDL datatypes. None. All methods are static. Methods getdate(java.sql.date) Converts a java.sql.date object to an equivalent MJD::Date CORBA IDL object. getdecimal(java.math.bigdecimal) Converts a BigDecimal object to an equivalent BCD::Decimal CORBA IDL object. getmoney(java.math.bigdecimal) Converts a BigDecimal object to an equivalent BCD::Money CORBA IDL object. getresultset(java.sql.resultset) Converts a java.sql.resultset object to an equivalent TabularResults::ResultSet CORBA IDL object. gettime(java.sql.time) Converts a java.sql.time object to an equivalent MJD::Time CORBA IDL object. gettimestamp(java.sql.timestamp) Converts a java.sql.timestamp object to an equivalent MJD::Timestamp CORBA IDL object. com.sybase.corba.jdbc11.sql class IDL.getDate(java.sql.Date) Converts a java.sql.date object to an equivalent MJD::Date CORBA IDL object. Package Class com.sybase.corba.jdbc11 IDL Parameters public static MJD.Date getdate(java.sql.date value) value A java.sql.date value to be converted. The value converted to an equivalent CORBA IDL MJD::Date value. gettime(java.sql.time), gettimestamp(java.sql.timestamp), SQL.getDate(MJD.Date) API Reference 3

20 com.sybase.corba.jdbc11.idl class IDL.getDecimal(java.math.BigDecimal) Converts a BigDecimal object to an equivalent BCD::Decimal CORBA IDL object. Package Class com.sybase.corba.jdbc11 IDL Parameters public static BCD.Decimal getdecimal(java.math.bigdecimal value) throws org.omg.corba.data_conversion value A java.math.bigdecimal value to be converted. The value converted to an equivalent CORBA IDL BCD::Decimal value. getmoney(java.math.bigdecimal), SQL.getBigDecimal(BCD.Decimal) IDL.getMoney(java.math.BigDecimal) Converts a BigDecimal object to an equivalent BCD::Money CORBA IDL object. Package Class com.sybase.corba.jdbc11 IDL Parameters public static BCD.Money getmoney( java.math.bigdecimal value) throws org.omg.corba.data_conversion value A java.math.bigdecimal value to be converted. The value converted to an equivalent CORBA IDL BCD::Money value. getdecimal(java.math.bigdecimal), SQL.getBigDecimal(BCD.Money) IDL.getResultSet(java.sql.ResultSet) Converts a java.sql.resultset object to an equivalent TabularResults::ResultSet CORBA IDL object. 4 EAServer

21 CHAPTER 1 Java Classes and Interfaces Package Class com.sybase.corba.jdbc11 IDL Parameters public static MJD.ResultSet getresultset( java.sql.resultset rs) rs A java.sql.resultset value to be converted. The value converted to an equivalent CORBA IDL TabularResults::ResultSet value. SQL.getResultSet(TabularResults.ResultSet) IDL.getTime(java.sql.Time) Converts a java.sql.time object to an equivalent MJD::Time CORBA IDL object. Package Class com.sybase.corba.jdbc11 IDL Parameters public static MJD.Time gettime(java.sql.time value) value A java.sql.time value to be converted. The value converted to an equivalent CORBA IDL MJD::Time value. getdate(java.sql.date), gettimestamp(java.sql.timestamp), SQL.getTime(MJD.Time) IDL.getTimestamp(java.sql.Timestamp) Converts a java.sql.timestamp object to an equivalent MJD::Timestamp CORBA IDL object. Package Class com.sybase.corba.jdbc11 IDL public static MJD.Timestamp gettimestamp( java.sql.timestamp value) API Reference 5

22 com.sybase.corba.jdbc11.idlresultset Parameters value A java.sql.timestamp value to be converted. The value converted to an equivalent CORBA IDL MJD::Timestamp value. getdate(java.sql.date), gettime(java.sql.time), SQL.getTimestamp(MJD.Timestamp) com.sybase.corba.jdbc11.idlresultset package com.sybase.corba.jdbc11; public class IdlResultSet extends java.lang.object implements jaguar.sql.jserverresultset; Implements the JServerResultSet interface, allowing you to construct TabularResults.ResultSet instances for component methods that return row results. Component methods that return row results to clients return TabularResults.ResultSet or TabularResults.ResultSet[]. IdlResultSet allows you to create instances of these types using the JDBC style JServerResultSet interfaces. For documentation of the TabularResults IDL types, see the generated Interface Repository documentation at../../ir/tabularresults.html. To return a single result set, initialize the rows and columns using the JServerResultSetMetaData and JServerResultSet methods, then convert to a TabularResults.ResultSet instance as shown in this code fragment: JServerResultSetMetaData jsrs;... define column formats... IdlResultSet irs = new IdlResultSet(jsrsmd);... define row data using JServerResultSet methods... return irs.getresultset(); To return multiple result sets, build an array of TabularResults.ResultSet instances, as follows: 1 Declare a java.util.vector instance: java.util.vector vector = new Vector(); 2 Initialize each IdlResultSet instance as described above, then add it to the vector: 6 EAServer

23 CHAPTER 1 Java Classes and Interfaces vector.addelement(irs.getresultset()); 3 When done, convert the vector to an array to be returned by the method: TabularResults.ResultSet[] array = new TabularResults.ResultSet[vector.size()]; vector.copyinto(array); return array; Constructors IdlResultSet(java.sql.ResultSetMetaData) Construct an instance using the column formats specified by a JServerResultSetMetaData instance. You can add rows to the instance using the JServerResultSet methods. IdlResultSet(java.sql.ResultSet) Construct an instance by reading the rows from the supplied ResultSet. Methods getresultset() Translate the contents of this instance into TabularResults.ResultSet instance. com.sybase.jaguar.sql.jserverresultset interface, com.sybase.jaguar.sql.jserverresultsetmetadata interface com.sybase.corba.jdbc11.sql class Constructors package com.sybase.corba.jdbc11; public abstract class SQL Provides methods to convert EAServer s predefined CORBA IDL datatypes to core Java datatypes. None. All methods are static. Methods getbigdecimal(bcd.decimal) Converts a BCD::Decimal CORBA IDL object to an equivalent java.math.bigdecimal. getbigdecimal(bcd.money) Converts a BCD::Money CORBA IDL object to an equivalent java.math.bigdecimal. getdate(mjd.date) Converts an MJD::Date CORBA IDL object to an equivalent java.sql.date object. getresultset(tabularresults.resultset) Converts a TabularResults::ResultSet CORBA IDL object to an equivalent java.sql.resultset object. gettime(mjd.time) Converts an MJD::Time CORBA IDL object to an equivalent java.sql.time object. API Reference 7

24 com.sybase.corba.jdbc11.sql class gettimestamp(mjd.timestamp) Converts an MJD::Timestamp CORBA IDL object to an equivalent java.sql.timestamp object. com.sybase.corba.jdbc11.idl class SQL.getBigDecimal(BCD.Decimal) Converts a BCD::Decimal CORBA IDL object to an equivalent java.math.bigdecimal. Package Class com.sybase.corba.jdbc11 SQL Parameters public static java.math.bigdecimal getbigdecimal(bcd.decimal value) value A BCD.Decimal value to be converted. The value converted to an equivalent java.math.bigdecimal value. getbigdecimal(bcd.decimal), getbigdecimal(bcd.money), IDL.getDecimal(java.math.BigDecimal) SQL.getBigDecimal(BCD.Money) Converts a BCD::Money CORBA IDL object to an equivalent java.math.bigdecimal. Package Class com.sybase.corba.jdbc11 SQL Parameters public static java.math.bigdecimal getbigdecimal(bcd.money value) value A BCD.Money value to be converted. The value converted to an equivalent java.math.bigdecimal value. getbigdecimal(bcd.decimal), IDL.getMoney(java.math.BigDecimal) 8 EAServer

25 CHAPTER 1 Java Classes and Interfaces SQL.getDate(MJD.Date) Converts an MJD::Date CORBA IDL object to an equivalent java.sql.date object. Package Class com.sybase.corba.jdbc11 SQL Parameters public static java.sql.date getdate(mjd.date value) value An MJD::Date value to be converted. The value converted to an equivalent java.sql.date value. gettime(mjd.time), gettimestamp(mjd.timestamp), IDL.getDate(java.sql.Date) SQL.getResultSet(TabularResults.ResultSet) Converts a TabularResults::ResultSet CORBA IDL object to an equivalent java.sql.resultset object. Package Class com.sybase.corba.jdbc11 SQL Parameters public static java.sql.resultset getresultset(tabularresults.resultset rs) rs A TabularResults.ResultSet object to be converted. The value converted to an equivalent java.sql.resultset value. IDL.getResultSet(java.sql.ResultSet) SQL.getTime(MJD.Time) Converts an MJD::Time CORBA IDL object to an equivalent java.sql.time object. Package com.sybase.corba.jdbc11 API Reference 9

26 com.sybase.jaguar.jcm.jcm class Class SQL Parameters public static java.sql.time gettime(mjd.time value) value An MJD.Time value to be converted. The value converted to an equivalent java.sql.time value. getdate(mjd.date), gettimestamp(mjd.timestamp), IDL.getTime(java.sql.Time) SQL.getTimestamp(MJD.Timestamp) Converts an MJD::Timestamp CORBA IDL object to an equivalent java.sql.timestamp object. Package Class com.sybase.corba.jdbc11 SQL Parameters public static java.sql.timestamp gettimestamp(mjd.timestamp value) value An MJD.Timestamp value to be converted. The value converted to an equivalent java.sql.timestamp value. getdate(mjd.date), gettime(mjd.time), IDL.getTimestamp(java.sql.Timestamp) com.sybase.jaguar.jcm.jcm class Constructors package com.sybase.jaguar.jcm; public class JCM extends Object Provides access to JDBC data sources. None. All methods are static. Methods bynameallowed(string) Determines if a data source can be retrieved by calling getcachebyname(string). 10 EAServer

27 CHAPTER 1 Java Classes and Interfaces getcache(string, String, String) Returns a reference to a data source with matching values for the specified user name, password, and server name. getcachebyname(string) Returns a reference to the data source with the given name. JCM.byNameAllowed(String) Determines if a data source can be retrieved by calling getcachebyname(string). Note Beginning in EAServer 6.0, all data sources allow access by name. This method is provided for backward compatibility. Package Interface com.sybase.jaguar.jcm JCM Parameters public static boolean bynameallowed (String name) throws JException name The name of the data source of interest. true if a data source is installed with the specified name, and the data source can be retrieved with JCM.getCacheByName(String); false otherwise. The getcachebyname(string) method allows you to retrieve a data source by specifying only the data source name, rather than specifying values for the data source user name, password, and server name. You can call bynameallowed to determine whether by-name access is allowed for a specified data source. getcachebyname(string) JCM.getCache(String, String, String) Returns a reference to a data source with matching values for the specified user name, password, and server name. API Reference 11

28 com.sybase.jaguar.jcm.jcm class Package Interface com.sybase.jaguar.jcm JCM Parameters public static JCMCache getcache ( String user, String pwd, String server) throws JException user The database user name associated with the data source. pwd The database password associated with the data source. server The database server name associated with the data source. The value should be a JDBC connection URL in the appropriate format for calls to java.sql.drivermanager.getconnection(string). The URL format depends on which JDBC driver the data source uses. See your JDBC driver documentation for more information. A reference to a JCMCache instance with matching values for user, pwd, and server. A JException exception is thrown if no data source with matching values exists. The supplied values for user, pwd, and server must match the properties of an existing data source. Chapter 4, Database Access, in the EAServer System Administration Guide getcachebyname(string) JCM.getCacheByName(String) Returns a reference to the data source with the specified name. Package com.sybase.jaguar.jcm Interface JCM Parameters public static JCMCache getcachebyname ( String name) throws JException name The name of the data source to be retrieved. 12 EAServer

29 CHAPTER 1 Java Classes and Interfaces A reference to a JCMCache instance with a matching value for name. A JException exception is thrown if: No data source is installed with the specified name. A matching data source is installed, but the data source properties forbid retrieval with this method. Use getcache(string, String, String) instead. getcachebyname allows you to retrieve a data source by specifying only the data source name, rather than specifying values for the data source user name, password, and server name. Using this method rather than getcache(string, String, String) removes the need to code database user names and passwords into your component source code. This method also allows you to change the data source user name, password, or server in the data source properties without requiring corresponding changes to your component source code. Note Beginning in EAServer 6.0, all data sources allow access by name. Chapter 4, Database Access, in the EAServer System Administration Guide bynameallowed(), getcache(string, String, String) com.sybase.jaguar.jcm.jcmcache class Constructors Fields package com.sybase.jaguar.jcm; public class JCMCache extends Object Manages a pool of connections to a third-tier database server. None. Call JCM.getCache(String, String, String). JCM_FORCE public final static int JCM_FORCE A value for the getconnection flag parameter. JCM_NOWAIT public final static int JCM_NOWAIT A value for the getconnection flag parameter. JCM_WAIT API Reference 13

30 com.sybase.jaguar.jcm.jcmcache class public final static int JCM_WAIT A value for the getconnection flag parameter. Methods bynameallowed() Determines whether the data source can be retrieved by calling JCM.getCacheByName(String). dropconnection(connection) Drops a connection. The connection is closed and not released into the data source. getpoolsizemax() Retrieves the maximum number of connections that this data source can manage. getconlibname() Returns the connectivity library (or interface) name for the data source. getconnection(int) Obtains a connection handle from the data source. getproxyconnection(int, String) Obtains a connection handle from the data source, specifying an alternate login name to set-proxy to. getname() Retrieves the data source s name. getpassword() Retrieves the password used by connections in the data source. getremoteservername() Returns the remote server name used by connections in the data source. getusername() Retrieves the user name used by connections in the data source. releaseconnection(connection) Releases a connection to the data source for reuse. JCMCache.byNameAllowed() Determines whether the cache can be retrieved by calling JCM.getCacheByName(String). Note Beginning in EAServer 6.0, all data sources allow access by name. This method is provided for backward compatibility. Package Class com.sybase.jaguar.jcm JCMCache public boolean bynameallowed() 14 EAServer

31 CHAPTER 1 Java Classes and Interfaces true if the data source can be retrieved with JCM.getCacheByName(String), false otherwise. getname(), JCM.byNameAllowed(String), JCM.getCacheByName(String) See Chapter 4, Database Access, in the EAServer System Administration Guide JCMCache.dropConnection(Connection) Drops a connection. The connection is closed and not released into the cache. Package com.sybase.jaguar.jcm Class JCMCache Parameters public void dropconnection( Connection con) throws SQLException con The java.sql.connection instance to be dropped. Use dropconnection() to close a connection when you do not want the connection returned to the data source. If necessary, future getconnection(int) calls will allocate new connections to replace any that have been dropped. getconnection(int), releaseconnection(connection) JCMCache.getConlibName() Returns the connectivity library (or interface) name for the data source. Package com.sybase.jaguar.jcm Class JCMCache public String getconlibname() JDBC JCMCache.getConnection(int) Obtains a connection handle from the data source. API Reference 15

32 com.sybase.jaguar.jcm.jcmcache class Package Class com.sybase.jaguar.jcm JCMCache Parameters public Connection getconnection(int flag) throws SQLException, JException, JConnectionNotFoundException flag A symbolic value that specifies what should happen if the maximum number of connections have been allocated and are in use (that is, no connection is available in the data source). Allowable values are: Value JCM_NOWAIT JCM_WAIT JCM_FORCE Behavior when no connection is available Throws JConnectionNotFoundException. Does not return until a cached connection is available. Forces open a new, uncached connection. The data source s maximum size is ignored. A java.sql.connection instance from the data source. If the call specifies JCM_NOWAIT and no connections are available, the call throws a JConnectionNotFoundException instance. getconnection(int) attempts to return a connection from the data source. data sources are maintained statically; a data source is initially empty when the server starts. Subsequent getconnection(int) calls allocate connections when necessary. releaseconnection(connection) calls release control of a connection for later reuse. Each data source has a maximum number of connections determined by the data source properties. (See Chapter 4, Database Access, in the EAServer System Administration Guide for more information.) The flag parameter determines getconnection(int) behavior when the data source s maximum number of connections are in use. getpoolsizemax() returns the data source s maximum number of connections. For improved performance, connections should not be held any longer than necessary. As a general rule, methods that use a cached connection should release it with releaseconnection(connection) before returning. This strategy minimizes contention by multiple components for a data source s connections. dropconnection(connection), getpoolsizemax(), releaseconnection(connection) 16 EAServer

33 CHAPTER 1 Java Classes and Interfaces JCMCache.getPoolSizeMax() Retrieves the maximum number of connections that can be pooled in the data source. Package Class com.sybase.jaguar.jcm JCMCache public int getpoolsizemax() The data source size. The size is specified the data source properties. See Chapter 4, Database Access, in the EAServer System Administration Guide for more information. getpoolsizemin() JCMCache.getPoolSizeMin() Retrieves the maximum number of connections that can be pooled in the data source. Package Class com.sybase.jaguar.jcm JCMCache public int getpoolsizemax() The data source size. The size is specified the data source properties. See Chapter 4, Database Access, in the EAServer System Administration Guide for more information. getpoolsizemax() JCMCache.getProxyConnection(int, String) Obtains a connection handle from the data source, specifying an alternate login name to set-proxy to. API Reference 17

34 com.sybase.jaguar.jcm.jcmcache class Not all data sources support set-proxy Set-proxy support must be enabled in the data source properties before you can use this feature. See Chapter 4, Database Access, in the EAServer System Administration Guide for more information. You must be connected to a database server, such as Adaptive Server Enterprise 11.5 or later, that supports the set session authorization command. Package Class com.sybase.jaguar.jcm JCMCache Parameters public Connection getproxyconnection(int flag, String proxy) throws SQLException, JException, JConnectionNotFoundException flag A symbolic value that specifies what should happen if the maximum number of connections have been allocated and are in use (that is, no connection is available in the data source). Allowable values are: Value JCM_NOWAIT JCM_WAIT JCM_FORCE Behavior when no connection is available Throws JConnectionNotFoundException. Does not return until a cached connection is available. Forces open a new, uncached connection. The data source s maximum size is ignored. proxy The user name to set-proxy to. A java.sql.connection instance from the data source. If the call specifies JCM_NOWAIT and no connections are available, the call throws a JConnectionNotFoundException instance. This method retrieves a cached connection, specifying an alternate login name to set-proxy to. Set-proxy support must be enabled in the data source properties. If support is enabled, connections retrieved from the data source with getconnection(int) set-proxy to the client user name. Call getproxyconnection(int, String) to specify a different user name to set-proxy to. Other than the set-proxy behavior, getproxyconnection(int, String) is identical to getconnection(int). See Chapter 4, Database Access, in the EAServer System Administration Guide for information on defining data sources and enabling set-proxy support. 18 EAServer

35 CHAPTER 1 Java Classes and Interfaces For improved performance, connections should not be held any longer than necessary. As a general rule, methods that use a cached connection should release it with releaseconnection(connection) before returning. This strategy minimizes contention by multiple components for a data source s connections. dropconnection(connection), getpoolsizemax(), getconnection(int), releaseconnection(connection) JCMCache.getName() Retrieves the data source s name. Package com.sybase.jaguar.jcm Class JCMCache public String getname() The data source s name. JCMCache.getPassword() Retrieves the password used by connections in the data source. Package Class com.sybase.jaguar.jcm JCMCache public String getpassword() The password. getremoteservername(), getusername() JCMCache.getRemoteServerName() Retrieves the remote server name used by connections in the data source. Package com.sybase.jaguar.jcm Class JCMCache public String getremoteservername() API Reference 19

36 com.sybase.jaguar.jcm.jcmcache class The remote server name. getpassword(), getusername() JCMCache.getUserName() Retrieves the user name used by connections in the data source. Package Class com.sybase.jaguar.jcm JCMCache public String getusername() The user name. getpassword(), getremoteservername() JCMCache.releaseConnection(Connection) Releases a connection to the data source for reuse. Package com.sybase.jaguar.jcm Class JCMCache Parameters public void releaseconnection( Connection con) throws SQLException con The connection to release. Released connections must be in a state that allows new queries to be issued. The connection will be dropped (and not returned to the data source) if the data source has exceeded its maximum number of connections. The maximum number of connections can be exceeded if calls to getconnection(int) are issued with flag as JCM_FORCE. In this case, releaseconnection drops the excess connections. 20 EAServer

37 CHAPTER 1 Java Classes and Interfaces Many JDBC programs do not explicitly clean up java.sql.statement objects. Instead, they rely on the JDBC driver to clean up Statement objects when the connection is closed. This strategy does not work with cached connections: you must explicitly clean up Statement objects before releasing a connection back into the data source. To clean up Statement objects, call Statement.close() and set the Statement reference to null. Warning! To prevent memory leaks, you must explicitly clean up a connection s Statement objects before releasing the connection back into the data source. Do not release a connection more than once. getconnection(int), dropconnection(connection) com.sybase.jaguar.jcm.jconnectionnotfoundexceptio n class Constructors Methods package com.sybase.jaguar.jcm; public class JConnectionNotFoundException extends JException; Exception thrown by JCMCache.getConnection(int) to indicate that no connections are available in the data source. You must specify JCM_NOWAIT in order for the exception to be thrown. Same as JException. Same as JException. com.sybase.jaguar.util.jexception class, java.sql.sqlexception class com.sybase.jaguar.server.jaguar class Constructors package com.sybase.jaguar.server; public class Jaguar extends Object Provides utility methods for use in server-side Java code. None. All methods are static. API Reference 21