Application Integrator: Reference For Stored Procedures

Reference for Stored Procedures
Application Integrator
Version 3.0
Document ID: 36602-01-0300-01
Last revised: February 1999
Copyright © 1989-1999 by Sybase, Inc. All rights reserved.
This publication pertains to Sybase database management software and to any subsequent release until otherwise indicated in new
editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished
under a license agreement, and it may be used or copied only in accordance with the terms of that agreement.
To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845.
Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other
international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled
software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic,
mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.
Sybase, the Sybase logo, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server,
Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication,
Adaptive Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, AnswerBase, Anywhere Studio, Application Manager,
AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Translator, APT-Library, Backup Server,
ClearConnect, Client-Library, Client Services, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress,
DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, Distribution
Director, E-Anywhere, E-Whatever, Embedded SQL, EMS, Enterprise Application Server, Enterprise Application Studio, Enterprise
Client/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work
Architecture, Enterprise Work Designer, Enterprise Work Modeler, EWA, Gateway Manager, ImpactNow, InfoMaker, Information
Anywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase,
MainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MySupport,
Net-Gateway, Net-Library, NetImpact, ObjectConnect, ObjectCycle, 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.stop, PowerAMC,
PowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScript,
PowerSite, PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare
Desktop, PowerWare Enterprise, ProcessAnalyst, Report Workbench, Report-Execute, Replication Agent, Replication Driver,
Replication Server, Replication Server Manager, Replication Toolkit, Resource Manager, RW-DisplayLib, RW-Library, S Designor, S-
Designor, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script, SQL
Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL
Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQL
Server SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial
Server, Sybase Gateways, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User Workbench,
SybaseWare, Syber Financial, SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream,
Transact-SQL, Translation Toolkit, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual
Components, VisualSpeller, VisualWriter, VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse
WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup
SQL Server, XA-Library, XA-Server and XP Server are trademarks of Sybase, Inc. 9/99
Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.
All other company and product names used herein may be trademarks or registered trademarks of their respective companies.
Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-
7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.
Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.

Contents
About This Book ............................................................................................................................ v
CHAPTER 1 Understanding AI for Stored Procedures ................................... 11

What Is AI for Stored Procedures? ................................................ 12
A Description of AI for Stored Procedures .............................. 12
AI for Stored Procedures Architecture..................................... 13
Supported Procedures ............................................................ 13
Why Use AI for Stored Procedures? .............................................. 15
Problem ................................................................................... 15
Solution ................................................................................... 15
Jaguar and AI for Stored Procedures Functionality........................ 16
How Jaguar Works .................................................................. 16
When Jaguar Uses AI for Stored Procedures Components .... 17
Basic Steps for Building a Component........................................... 18
Step 1: Research the Target Stored Procedure ...................... 18
Step 2: Create the Component................................................ 19
Step 3: Deploy the Component ............................................... 19
Step 4: Use the Component .................................................... 19
Using the AI for Stored Procedures Tutorials................................. 20
CHAPTER 2 Working with the AI Component Builder .................................... 21

Working with the Component Builder ............................................. 22
Starting the Component Builder .............................................. 22
Working with Project Files ....................................................... 22
Understanding AI Connections ...................................................... 25
Defining Connection Properties............................................... 25
Registering JDBC Drivers ....................................................... 26
Testing Connections................................................................ 27
Connection Caching ................................................................ 27
Understanding AI Components ...................................................... 28
Component Properties ............................................................ 28
Creating Methods .................................................................... 29
Method Properties ................................................................... 31
iii
Contents
Mapping Stored Procedures to Methods................................. 34

Understanding AI Component Deployment.................................... 38
Understanding the Deployment Wizard................................... 38
Understanding Deployed Components in Jaguar.................... 39
Understanding Deployed Connections in Jaguar .................... 40
CHAPTER 3 Jaguar and Application Issues..................................................... 41

AI Components in Jaguar............................................................... 42
Instance Creation .................................................................... 42
Instance Activation .................................................................. 42
Method Invocation ................................................................... 43
Instance Deactivation .............................................................. 43
Instance Destruction................................................................ 43
Connections and Connection Caching........................................... 44
Component Properties: Connections and Security ................. 44
Acquiring and Disposing of Connections................................. 45
Defining Connection Caches in Jaguar Manager.................... 46
AI Component Properties in Jaguar Components................... 47
Client Application Development ..................................................... 49
AP PE ND IX A Target Types .................................................................................. 51

Sybase Targets .............................................................................. 52
Adaptive Server Anywhere...................................................... 52
Adaptive Server Enterprise ..................................................... 53
DirectConnect.......................................................................... 53
Oracle Targets ............................................................................... 55
Oracle OCI .............................................................................. 55
Oracle Thin.............................................................................. 56
JDBC-ODBC Bridge Targets.......................................................... 57
Generic Targets ............................................................................. 58
About JDBC URLs ......................................................................... 59
Glossary 61
iv
About This Book
Application Integrator is a Jaguar component development and

deployment tool that allows application developers to quickly integrate
database stored procedures with Jaguar CTS.
This preface contains the following topics:
• Audience
• How to Use This Book
• Documentation
• Conventions
• If You Need Help
• If You Have Questions About This Book
Note The remaining chapters in this guide refer to Application Integrator

as “AI for Stored Procedures,” and to Jaguar Component Transaction
Server (CTS) as “Jaguar.”
Audience
Use this document if you are responsible for using AI for Stored
Procedures to create components from target stored procedures and
deploy them to Jaguar.
How to Use This Book

Use this document to understand AI for Stored Procedures.
Table 1 describes the contents of this book.
v
About this book
Table 1: Application Integrator for Stored Procedures Reference

contents
Chapter Contents
Chapter 1, “Understanding Provides an overview of the functionality and
AI for Stored Procedures” features of AI for Stored Procedures.
Chapter 2, “Working with Describes how to work with the AI for Stored
the AI Component Builder” Procedures Component Builder to create and
deploy components.
Chapter 3, “Jaguar and Provides information about how to write
Application Issues” applications that use components you create.
Appendix A, “Target Provides information about JDBC and ODBC
Types” drivers required when creating connections in
the AI for Stored Procedures Component
Builder.
Glossary Defines technical terms used in this book.
Documentation
Sybase provides the following Application Integrator documentation:
• Application Integrator for Stored Procedures Reference
• Application Integrator online help
See the online documentation in the Sybase\Application Integrator 3.0
program group for Application Integrator samples, which include tutorials
designed to give you hands-on experience with each step of creating and
deploying components.
Related Documentation
This section lists documentation for products that can be used in
conjunction with Application Integrator.
EAStudio
Building Internet and Enterprise Applications provides information about
using Application Integrator and other EAStudio applications.
vi
About this book
EAServer
Enterprise Application Server Version 3.5 Feature Guide provides
information about using Application Integrator and other EAServer
applications.
Jaguar CTS
The Jaguar CTS Programmer’s Guide is available with Jaguar CTS
version 3.0.
Conventions
This section describes the following:
• Style Conventions
• Syntax Conventions
Style Conventions
The following table shows some of the style conventions used in the
documentation for this product.
Table 2: Style conventions
Item Example
• Programs create connection
• Utilities
• Procedures
• Commands
• File names install.cfg
• Directory names
• Properties
Code examples input
com.sybase.ai.utils
• User input shutdown
Command line input
Variables (place-holder text that you host_name
replace with the appropriate value)
vii
About this book
Syntax Conventions
The following example illustrates some of the syntax conventions used in
this guide:
COMMAND [object_name, [ {TRUE | FALSE} ] ]
The following table explains the syntax conventions used in this guide.
Table 3: Syntax conventions
Symbo
l Explanation Example
() Include parentheses as part of the START DATABASE
command. (database_name)
| A vertical bar indicates that you can {yes|no}
select only one of the options
shown. Do not type the bar in your
command.
, A comma indicates that you can {long,short,none}
choose one or more of the options
shown. Separate each choice by
using a comma as part of the
command.
{} Braces indicate that you must Select only one:
choose one or more of the enclosed
options. Do not type the braces {datetime|datetime
when you enter the option. 4}
Select at least one:
{char_iso,char_eur
,
char_jis}
[] Brackets indicate that you can [truncate]
choose one or more of the enclosed
options, or none. Do not type the
brackets when you enter the
options.
... An ellipsis indicates that you can {datax,datay}...
repeat the previous item as many
times as necessary.
viii
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.
Sybase Professional Services

Sybase Professional Services offers on-site consulting and training
programs to help you maximize the benefits of our products. For more
information, call (800) 8SYBASE.
Note Outside the continental United States and Canada, obtain the correct
telephone numbers from your sales representative and record them for
future reference.
If You Have Questions About This Book

If you have questions, comments, or suggestions about this book, contact
the Sybase documentation group directly by e-mail at:
icd_doc@sybase.com
Feel free to forward any information, comments, or questions about the
following:
• Missing, incorrect, or unclear information
• Information you found particularly useful
• Organization or style
We will respond as promptly as possible by e-mail. Your feedback helps
us provide more accurate, detailed, and easy-to-use documentation.
Note Please send comments about product features, functionality, or

problems to your systems engineer or Sybase Technical Support.
ix
x
CH A PTE R 1 Understanding AI for Stored
Procedures
This chapter describes the functionality and architecture of Application

Integrator and includes the following topics:
• What Is AI for Stored Procedures?
• Why Use AI for Stored Procedures?
• Jaguar and AI for Stored Procedures Functionality
• Basic Steps for Building a Component
• Using the AI for Stored Procedures Tutorials
Note The remaining chapters in this guide refer to Application Integrator

as “AI for Stored Procedures,” and to Jaguar Component Transaction
Server (CTS) as “Jaguar.”
11
What Is AI for Stored Procedures?

AI for Stored Procedures is a Jaguar component development and deployment
tool that allows application developers to quickly integrate database stored
procedures with Jaguar.
AI for Stored Procedures is included in Sybase EAServer. EAServer is an
integrated set of application servers that you use to deploy Web applications
that support high-volume traffic, dynamic content, and intensive online
transaction processing. EAServer consists of PowerDynamo, Jaguar, AI for
CICS, AI for Stored Procedures, and Adaptive Server Anywhere (ASA).
This section covers the following topics:
• A Description of AI for Stored Procedures
• AI for Stored Procedures Architecture
• Supported Procedures
A Description of AI for Stored Procedures

AI for Stored Procedures allows you to create Jaguar components that provide
access to existing stored procedures, making the stored procedures accessible
to Web-based client applications.
The AI for Stored Procedures Component Builder is a design tool that you use
to create these components. The Component Builder makes it easy to create
components by simply browsing a database and selecting a collection of stored
procedures. No manual coding is required.
After you create the components, you can use the Component Builder to deploy
them to Jaguar, where they can be used by Jaguar client applications or by other
Jaguar components.
AI for Stored Procedures components use Java Database Connectivity (JDBC)
to access stored procedures. Using the Component Builder, you can create
components that invoke stored procedures in any database that is accessible
through a JDBC driver. AI for Stored Procedures includes the Sybase jConnect
JDBC driver for access to Sybase databases such as Adaptive Server Anywhere
(ASA) and Adaptive Server Enterprise (ASE). For non-Sybase databases, such
as Oracle, you must provide additional JDBC drivers.
12
CHAPTER 1 Understanding AI for Stored Procedures
AI for Stored Procedures Architecture

AI for Stored Procedures consists of the following:
• A design tool called the Component Builder that allows you to create
Jaguar components that invoke stored procedures
• A library of Java classes that AI for Stored Procedures components use to
invoke the target stored procedures from Jaguar
Figure 1-1 shows the design-time architecture of AI for Stored Procedures.
Figure 1-1: AI for Stored Procedures design-time architecture
During design time, the Component Builder imports the stored procedure
metadata, then creates and deploys the component into Jaguar.
Figure 1-2 shows the run-time architecture of AI for Stored Procedures.
Figure 1-2: AI for Stored Procedures run-time architecture
During run time, a client application attempts to invoke a component in Jaguar,

which in turn accesses the target stored procedure.
Supported Procedures
AI for Stored Procedures supports the following stored procedures and queries:
• Database stored procedures (for any database that is accessible through
JDBC)
• Database SQL commands (for example, select, insert, execute, update,
delete)
13
• DirectConnect Remote Stored Procedures (RSPs)

• Open ServerConnect language events and Remote Procedure Calls
(RPCs)
Note This documentation refers to all supported procedures as “target stored

procedures.”
14
Why Use AI for Stored Procedures?

To understand how AI for Stored Procedures can provide solutions for business
problems, consider the following scenario.
Problem
A company needs to attract new prospects and keep them as customers, and at
the same time, lower the cost of sales.
The company would like to allow customers to self-service their accounts
through a new application over the Internet. By deploying the application over
the Internet, the customer would be able to easily renew an account, and the
company would expand its target market without increasing its direct sales
force.
However, the company faces the following constraints:
• Existing operational systems were not designed for direct exposure to
customers over the Internet.
• The company cannot afford to rewrite all the applications or consolidate
all the data on a common platform. The business logic and security
infrastructure is spread across LAN database stored procedures.
• The new application must be developed using HTML and Java (for broad
Internet accessibility), but none of the existing systems are “Web-enabled”
today.
Solution
For its solution, the company uses Sybase Enterprise Application Server
(EAServer) as a platform to integrate their internal applications and make them
accessible through the Internet. Using AI for Stored Procedures, they can
access the business logic in their database stored procedures quickly and easily
from the Jaguar middle tier for new application development.
15
Jaguar and AI for Stored Procedures Functionality
Jaguar and AI for Stored Procedures Functionality

The following sections are intended to familiarize you with how Jaguar
functions and how it relates to AI for Stored Procedures:
• How Jaguar Works
• When Jaguar Uses AI for Stored Procedures Components
How Jaguar Works

Jaguar implements a “multi-tier” distributed computing architecture. Figure 1-
3 shows the typical Jaguar environment, in which three distinct elements, or
tiers, work together to give users access to data:
• The client application code, which manages the presentation and
interaction with the end user.
• Middle-tier components, which run in Jaguar and are typically coded by
the middle-tier developer. They contain the executable business logic that
handles much of the application processing.
• The back-end database, which is the transaction target accessed by the
Jaguar component. It stores, manages, and processes data.
Figure 1-3: Typical Jaguar environment
In most cases, interaction between the client application and Jaguar occurs as
follows:
1 When a client application needs to use a component, it issues a request to
the Jaguar server.
2 The request from the client prompts Jaguar to instantiate the component.
3 The client invokes a method on a component.
16
4 The method invokes the target stored procedure and returns any results to
the client.
Note For detailed information about how Jaguar works, see the Jaguar
documentation.
When Jaguar Uses AI for Stored Procedures Components

In AI for Stored Procedures, the components in the middle-tier contain
methods that represent target stored procedures. Figure 1-4 shows the
following elements, or tiers, of the AI for Stored Procedures environment:
• The client, which contains the application code that manages the
presentation and interaction with the end user.
• Middle-tier AI for Stored Procedures components, which contain methods
that provide direct access to a target stored procedure. No middle-tier
coding is required.
• The target stored procedure, which contains business logic for an
application.
Figure 1-4 shows the Jaguar client accessing a stored procedure through the AI
for Stored Procedures component in the middle tier.
Figure 1-4: AI for Stored Procedures environment
17
Basic Steps for Building a Component
Basic Steps for Building a Component

There are four basic steps in the AI for Stored Procedures development
process:
• Step 1: Research the Target Stored Procedure
• Step 2: Create the Component
• Step 3: Deploy the Component
• Step 4: Use the Component
Figure 1-5 shows the process flow by task, the environment in which each task
is performed, and the skills needed to perform the tasks in each step.
Figure 1-5: Four-step process and required skills
The following sections describe each step.
Step 1: Research the Target Stored Procedure

You must research the stored procedure you plan to use to become familiar with
how it is defined and how it works.
18
Step 2: Create the Component

In this step, you use the Component Builder to create a connection and a
component. The connection provides access to a database that contains stored
procedures. The component contains a collection of methods, and each method
invokes a single stored procedure.
When you use the Component Builder to create a component, you can create
component methods automatically by connecting to the target database and
selecting a target stored procedure.
If the JDBC driver cannot access the stored procedure metadata on the
database, you must create component methods manually by entering detailed
information about the stored procedure properties.
For more information about creating components automatically or manually,
see Chapter 2, “Working with the AI Component Builder”
Step 3: Deploy the Component

When you deploy the component, the Component Builder defines it in Jaguar,
and creates Java classes that implement the component. After the component
is deployed, it is ready to run.
Step 4: Use the Component

Once a component is deployed, you can use it in applications. AI for Stored
Procedures components can be used to build Jaguar client applications or to
build other Jaguar components.
Note For information on how to build your client application, see the Jaguar
documentation.
19
Using the AI for Stored Procedures Tutorials
Using the AI for Stored Procedures Tutorials

Sybase provides tutorials to give you hands-on experience and guide you
through the process described in this chapter.
The tutorials are installed with AI for Stored Procedures. See the online
documentation in the Sybase\Application Integrator 3.0 program group for
information on running the tutorials.
20
CH A PTE R 2 Working with the AI Component
Builder
This chapter contains information about using the AI for Stored

Procedures Component Builder, including the following topics:
• Working with the Component Builder
• Understanding AI Connections
• Understanding AI Components
• Understanding AI Component Deployment
Note Sybase provides samples with the Application Integrator software.

These samples include tutorials designed to help you learn to use the
Component Builder to create components and connections. See the online
documentation in the Sybase\Application Integrator 3.0 program group
for information on running the tutorials.
21
Working with the Component Builder

The Stored Proc Component Builder lets you easily create Jaguar components
that invoke existing stored procedures. Like all AI Component Builders, the
Stored Proc Component Builder runs in Sybase Central, a system management
and design tool. Sybase Central is also used with Sybase servers such as Jaguar
and Adaptive Server Anywhere (ASA).
You use the Stored Proc Component Builder to perform the following tasks:
• Create, test, and edit connections
• Create and edit components
• Deploy components to Jaguar
• Starting the Component Builder
• Working with Project Files
Starting the Component Builder

To start the Component Builder, from the Windows Start menu, select AI
Component Builder from the Sybase Application Integrator 3.0 program
group.
This starts Sybase Central and loads any AI Component Builders you have
installed. The AI Component Builders appear in the tree view in the Sybase
Central window.
Working with Project Files

Project files provide a way to store component and connection definitions
created with the Component Builder. Project files store information about
logically related components. For example, you can group all components
created for a specific department into a single project file, such as a Human
Resources or Payroll file. Or, if you are creating components from stored
procedures that reside on different databases, you can save all components and
connections created for a specific database in a single project file.
Component Builder project files have the extension .aip. We recommend that
you continue to use the .aip extension for each project file you save.
22
CHAPTER 2 Working with the AI Component Builder
This section covers these topics:

• Creating, Opening, and Closing Projects
• Viewing Project Contents
• Saving Projects
Creating, Opening, and Closing Projects

To create a new project, right-click the Component Builder and click New
Project.
To open a project file, right-click the Component Builder and click Open
Project.
To close a project file, right-click the project and click Close.
Viewing Project Contents

Each project contains a collection of components and connections. These
objects are displayed hierarchically in the Sybase Central tree view. You view
the contents of a project by expanding the objects that appear beneath a project
in the tree view. To expand an object in the tree, you can either left-click the +
button that appears next to the object, or double-click the object.
The following figure shows a project named asademo in the Component
Builder.
23
Figure 2-1: Component Builder project file structure
In the asademo project, the component called ASADemo contains seven

methods. The connection associated with this component is Holograph.
The right-hand window in Sybase Central contains different views of the object
currently selected in the tree. The Details view displays children of the object
selected in the tree. Some objects include other views that provide additional
information. For example, when you select a component in the tree, you can
view both Details and Interface views for the component:
• The Details view displays the methods in the component.
• The Interface view displays the CORBA IDL (Interface Definition
Language) interface for the component.
Saving Projects
To save your project to a file, right-click it and click Save.
24
Understanding AI Connections
An Application Integrator connection is a named set of properties that specifies
how to connect to a target system (similar to an ODBC data source or a JDBC
URL). At design time, the AI connection definition tells the Component
Builder how to retrieve metadata about target stored procedures. At run time,
the AI connection can be used by the component to obtain a connection to the
target by default; alternatively, you can configure AI components to use the
Jaguar connection cache to acquire a connection. See “Defining Connection
Caches in Jaguar Manager” on page 46 and the Jaguar documentation for more
information.
You use the Component Builder to define connections, associate them with
components, and deploy them to Jaguar. Every component is associated with
exactly one connection.
All connectivity in AI for Stored Procedures uses JDBC. The Component
Builder uses JDBC to test connections and to browse databases when creating
component methods. At run time, Application Integrator components running
in Jaguar use JDBC to invoke stored procedures. The connections you build in
the Component Builder are JDBC connections.
• Defining Connection Properties
• Registering JDBC Drivers
• Testing Connections
• Connection Caching
Defining Connection Properties

When you create a connection, you must supply the following information in
the Component Builder:
• The type of connection you want to create.
The following connection types are supported in the zComponent Builder:
Table 2-1: Connection types supported in the Component Builder
Connection type Description
Sybase ASA Connection to a Sybase Adaptive Server
Anywhere database
25
Understanding AI Connections
Connection type Description

Sybase ASE Connection to a Sybase Adaptive Server
Enterprise database
Sybase DirectConnect Connection to a Sybase DirectConnect gateway
Oracle OCI Connection to Oracle using the Oracle OCI
JDBC driver
Oracle Thin Connection to Oracle using the Oracle thin
JDBC driver
JDBC-ODBC Bridge Connection to any database accessible through
ODBC using the Sun JDBC-ODBC bridge
Generic Connection to a database accessible using JDBC
• Properties needed to connect to the database containing the target stored

procedure.
These properties differ for each target but often include a host name and
port number. When you create a connection, the Component Builder
derives a JDBC URL for the connection from these properties. The
Component Builder provides a simple interface for entering properties and
does not require you to know the URL format for supported JDBC drivers.
See Appendix A, “Target Types” for detailed information about the
properties required for each supported connection type.
• User name and password for the database containing the target stored
procedure.
Registering JDBC Drivers

Application Integrator and Jaguar include the Sybase JDBC driver jConnect,
which you can use to create connections to Sybase servers. For other
connection types, such as Oracle, you must provide additional JDBC drivers.
You also must register each non-Sybase JDBC driver with the Component
Builder before you create connections that use it. To register a driver, add it to
the JDBC Driver Class Path that appears in the Component Builder Options
dialog box.
The JDBC Driver Class Path is a Java class path that the Component Builder
uses to locate JDBC drivers. It can include jar files, zip files, or directories that
contain JDBC drivers you are using with the Component Builder. Entries in the
class path are separated by semi-colons.
26
After you register a driver, you can test connections in the Component Builder
and browse databases accessible through the driver to create component
methods.
You must also install each non-Sybase JDBC driver on the Jaguar server where
Application Integrator components are deployed. This must be done so that
components can use the JDBC driver at run time to invoke stored procedures.
Testing Connections
The Component Builder allows you to test a connection to the database where
the target stored procedure resides. This makes it easy to verify that the
database is running, and that you have defined the connection correctly.
Common reasons that connection tests fail are:
• The network or database is down.
• Invalid values, such as host name, port number, user name, or password,
were specified for the connection.
• The JDBC driver for the connection was not registered with the
Component Builder, or it is not installed correctly.
See Appendix A, “Target Types” for information on properties needed for each
connection type.
Connection Caching
Application Integrator components do not use Jaguar’s connection caching
feature at run time by default; however, components can be configured to use
the connection caching feature in Jaguar. See Chapter 3, “Jaguar and
Application Issues” for details.
27
Understanding AI Components
AI for Stored Procedures components are Jaguar components that provide
access to one or more stored procedures. A component contains one method for
each stored procedure it exposes, and each method invokes exactly one stored
procedure.
Every component is associated with a single connection. The choice of
connection determines which stored procedures the component’s methods can
invoke. All stored procedures exposed in a component must reside on a single
server.
The Component Builder allows you to create components, add methods to
components, and deploy components to Jaguar.
You can add methods to components either manually or automatically. For
more information, see the section in this chapter called “Creating Methods” on
page 29.
Once you have created a component and added one or more methods, you can
deploy the component to Jaguar, where it is ready to used by Jaguar client
applications or other Jaguar components.
The rest of this section covers the following topics:
• Component Properties
• Creating Methods
• Method Properties
• Mapping Stored Procedures to Methods
Component Properties
When you create a component, you must supply the following information in
the Component Builder:
Table 2-2: Component properties
Property Description
Component name Name that is used for the component when it is
deployed to Jaguar.
28
Property Description
Java package name Components are implemented as Java classes. Java
package names are used to organize Java classes
hierarchically. Typically, Java package names are in
reverse Internet domain name format (as in the
example com.xyzcorp.app_name, where app_name is
the name of the application you are building).
Note Java package names are not the same as Jaguar

package names.
Connection name Each component requires a connection. When

components are created in the Component Builder,
you can select an existing connection, or create a new
one. The choice of connection determines which
stored procedures can be exposed in the component.
Creating Methods
Each method in a component provides access to a stored procedure. You can
create methods automatically or manually, depending on whether the JDBC
driver you are using can access the stored procedure metadata.
See Appendix A, “Target Types” for information that affects automatic and
manual method creation.
Creating Methods Automatically

When the Component Builder accesses the database through the component’s
connection, it allows you to create a method automatically. You browse the
database and select a stored procedure that the method will invoke.
When you create methods automatically, the Component Builder attempts to
retrieve information about the stored procedure you select, such as its name and
its parameters. The Component Builder retrieves information for each
parameter including the parameter mode, datatype, whether it has a return
value, and whether it can accept a NULL value. The Component Builder then
uses this information to create a method that will invoke the stored procedure.
29
In some cases, JDBC drivers cannot retrieve complete information about a

stored procedure or its parameters. If the information that the JDBC driver
provides is incomplete, the Component Builder issues warning messages about
missing information when the method is created. The Component Builder
saves these messages; to view them, select the method in the Sybase Central
tree view and click the Details tab.
When warnings are issued for a method, you should obtain the source code for
the target stored procedure (usually SQL) and adjust the method definition in
the Component Builder as needed. After you have edited the method definition
to match the stored procedure, clear the warnings that appear in the Details
view.
Note We strongly recommend that you become familiar with the target stored
procedures that your components will access.
Creating Methods Manually

When the target cannot supply metadata about its stored procedures, you must
create methods manually. To do so, you enter specific information in the Target
tab of the Method Properties dialog box about the target stored procedure (see
Table 2-3 on page 31), such as:
• Target stored procedure name
• Whether the target stored procedure has a return value
• Whether it returns result sets
• Information for each parameter in the stored procedure, including the
following:
• Parameter name
• Mode (input, output, or input/output)
• JDBC datatype
• Scale (when the JDBC datatype is decimal or numeric)
• Whether it can accept NULL values
When you create methods manually, you must fully understand the target
stored procedure, so that you can enter this information correctly. The most
accurate source for this information is the source code (usually SQL) for the
stored procedure.
30
Method Properties
For each method, you can define properties in the Method Properties dialog
box. The General tab displays the method properties as they appear in Jaguar
and allows you to customize the method and parameter names. The Target tab
displays and allows you to set properties for the stored procedure as it appears
on the target.
Table 2-3: Method properties
Tab Field Description Comments
General Method Name of the
Information name method.
about the Descripti Method
method on description
definition as it (optional).
will appear in Paramete
Jaguar. rs:
Name Parameter name.
Mode Parameter mode. in, out, or inout.
Type Jaguar datatype See “Mapping Stored
for the parameter. Procedures to Methods” on
page 34 for mappings
between Jaguar types, IDL
types, and JDBC types.
31
Tab Field Description Comments

Target Catalog JDBC catalog. For Sybase, the procedure’s
Information database.
about the Schema JDBC schema. For Sybase, the procedure’s
target stored owner.
procedure Procedur Procedure name.
e
Catalog Delimiter for Default value is a period (.).
Separator portions of the
fully qualified
stored procedure
name.
String Default value is a single
Delimiter quotation mark (‘).
Not used for callable or
prepared statements.
Statement Valid values are Statement,
Type Prepared, and Callable.
See “Statement Templates”
on page 33 for more
information.
Result Indicates whether Valid values are 0, 1, and
Sets the procedure Variable (0, 1, or many).
returns result sets.
Paramete
rs:
Name Parameter name.
Mode Parameter input or Valid values are in, out, or
output mode. inout.
JDBC Parameter JDBC See Table 2-6 on page 36 for
Type datatype. details.
Precision For character See Table 2-6 on page 36 for
datatypes, details.
typically the
maximum number
of characters for
the parameter.
For other
datatypes,
typically the
number of bytes in
the parameter
value.
32
Statement Types
Methods can be defined to use any of the calling conventions supported by
JDBC. These statement types include Statement, Prepared Statement, and
Callable Statement. The calling conventions determine how the stored
procedure is invoked at run time in Jaguar.
Table 2-4: Method statement types and calling conventions
Statement type Calling convention
Statement The component invokes the procedure through a
java.sql.Statement.
Prepared Statement The component invokes the procedure through a
java.sql.PreparedStatement.
Callable Statement The component invokes the procedure through a
java.sql.CallableStatement
. This is the default statement type.
Note Callable statements yield the best performance

and should be used when supported by the target
database.
Statement Templates
When you choose the statement types Statement or Prepared Statement, you
must enter a template of the statement that should be sent to the server to
invoke a target stored procedure when the corresponding method is executed.
Click the “Compute” button to create a default statement template that is
derived from the catalog, schema, procedure name, catalog separator, and
defined parameters. You can edit the template in any way you prefer, provided
that the server can understand its syntax. Parameters defined to a method can
be substituted at run time by referring to them in the template as
{parameter_name}. {parameter_name} is the name of one of the parameters
defined in the Parameters field of the Method Properties dialog box.
Note The template you create should not contain the question mark (?)
character.
See Appendix A, “Target Types” for details on target support for various
statement types.
33
Mapping Stored Procedures to Methods

This section contains information about the relationships between target stored
procedures and corresponding components in AI for Stored Procedures and
Jaguar.
This section includes the following topics:
• Target Stored Procedures and Method Names
• Result Sets and Method Return Value
• Parameter Information
Target Stored Procedures and Method Names

When you add a method to a component, the Component Builder derives a
name for the method from the name of the target stored procedure, with the first
character in upper case and the subsequent characters in lower case.
Note If necessary, the Component Builder removes spaces and underscores

from the name to comply with Jaguar method name restrictions.
Result Sets and Method Return Value

The number of result sets declared in the Component Builder affects the
method’s return type. The following table shows how the number of result sets
are mapped in Jaguar:
Table 2-5: Result sets and method return value
Number of result sets Jaguar IDL mapping
0 void
1 TabularResults::ResultSet
More than 1 TabularResults::ResultSets
Parameter Information
• Parameter Names
• Parameter Modes
• Stored Procedure Return Values
34
• Parameter Datatypes
• Parameters with NULL Values
Parameter Names
For each method in an AI for Stored Procedures component, each parameter is
either automatically derived from the server using JDBC metadata calls or is
manually defined in the Component Builder. If the names of the parameters are
not valid parameter names, the Component Builder alters the parameter names
to conform to Jaguar restrictions. You can also alter parameter names in the
Component Builder.
Parameter Modes
The parameter mode refers to whether the parameter is used for input, output,
or both input and output.
When you define the component automatically, for each method in a
component, each of the procedure’s input, output, or input/output parameters is
added as a parameter for that method. If you manually define a component, you
must manually define each parameter for each method.
Stored Procedure Return Values

A stored procedure may or may not have a return value. If it is defined to have
a return value, an output parameter should be added to the method. Check the
Return Value check box for that parameter.
Note The Component Builder may have already set the Return Value property
for the parameter correctly if you created the method automatically.
The return value for a stored procedure is mapped as an output parameter in the
method.
Parameter Datatypes
This section describes mapping that occurs from parameter types to Jaguar IDL
datatypes. The datatype for each field is either automatically derived using
JDBC metadata calls or is manually defined in the Component Builder.
35
Because each supported target DBMS has a different set of native datatypes,
each JDBC driver must map the native datatypes of the target to valid SQL
datatypes. In addition, JDBC specifies the default mapping of SQL datatypes
to Java datatypes.
The first two columns of the following table show the SQL-to-Java datatype
mapping recommended by the JDBC 1.20 specification.
AI for Stored Procedures uses this mapping to convert SQL datatypes in stored
procedures to Java datatypes. The third column shows the mapping between
the Java datatypes and the Jaguar IDL datatypes that ultimately get mapped
into the appropriate Jaguar client datatype.
Table 2-6: Mapping SQL datatypes to Java and Jaguar datatypes
Jaguar IDL
SQL Datatype Java Datatype Datatype
CHAR java.lang.String string
VARCHAR java.lang.String string
LONGVARCHAR java.lang.String string
NUMERIC java.math.BigDecimal decimal
DECIMAL java.math.BigDecimal decimal
BIT boolean boolean
TINYINT byte byte
SMALLINT short integer<16>
INTEGER int integer<32>
BIGINT long integer<64>
REAL float float
FLOAT double double
DOUBLE double double
BINARY byte[] binary
VARBINARY byte[] binary
LONGVARBINARY byte[] binary
DATE java.sql.Date date
TIME java.sql.Time time
TIMESTAMP java.sql.Timestamp timestamp
For more information about Java datatypes, see the discussion on datatype
mapping in the JavaSoft JDBC Specification, version 1.20.
For more information about datatype mappings from third-party DBMSs to
Java, see the documentation for that DBMS.
36
Parameters with NULL Values

Most DBMSs and Sybase Open ServerConnect allow parameters to accept
NULL values. However, many JDBC drivers cannot obtain this information
about parameters from the procedure metadata when you create a component
automatically. As a result, when the JDBC driver cannot return information
about whether a parameter can accept NULL values, the Component Builder
sets the default to not nullable. If it should be NULL, you can set this property
in the Methods Properties dialog box.
Parameter nullability affects the signature for a Jaguar method. You can view
the IDL interface for a method in the Interface view in the Sybase Central
window.
Each non-nullable parameter in a stored procedure corresponds to a single
parameter in the method’s signature.
Each nullable parameter in a stored procedure corresponds to two parameters
in the method’s signature:
• The first is the parameter value itself, if the value is not null.
• Because parameters in Jaguar components cannot have NULL values,
upon deployment, the Component Builder adds a second parameter called
a null indicator to the method. The null indicator is a boolean value
(true/false) that indicates whether the first parameter value is NULL. The
name of a parameter’s null indicator is <param_name>IsNull, where
<param_name> is the name of the corresponding nullable parameter.
An application using an AI for Stored Procedures component should set
the value of the null indicator correctly to communicate whether the
corresponding parameter is NULL. When a method executes, the client
application can check the null indicators or any nullable output parameters
to determine whether the output value is NULL. At run time, the client
application can set the null indicator to true to indicate that the parameter
has a NULL value.
37
Understanding AI Component Deployment

Once you have defined a component with one or more methods, you can
deploy it to Jaguar, where it can then be used in Jaguar client applications.
This section includes the following topics:
• Understanding the Deployment Wizard
• Understanding Deployed Components in Jaguar
• Understanding Deployed Connections in Jaguar
Understanding the Deployment Wizard

The Component Builder provides a wizard that makes it easy to deploy
components. The wizard performs the following functions:
• Defines the component in Jaguar
• Copies the connection and Java source code for the component to the
Jaguar java\classes directory
• Compiles the Java source code for the component on the Jaguar server
When you deploy a component into Jaguar, you must provide the information
described in the following table:
Table 2-7: Information needed by the Deploy Components wizard
Wizard
dialog box Field Description
Jaguar User Name Valid Jaguar user ID.
connection Password Valid password for Jaguar user ID.
information
Host Name Name of the machine on which Jaguar is
running.
Note Be sure that Jaguar is running.
Port Number Number of the IIOP port on which Jaguar is

listening.
38
Wizard
dialog box Field Description
Jaguar Package Name The package name currently selected for this
package component. Enter a new name, accept the
information selected name, or select a different name from
the Existing Packages field.
Existing The list of package names currently available.
Packages Click a package name to select the package.
Note Jaguar system packages (such as

CosNaming) are not displayed.
After you provide the information needed by the wizard, the Deployment
Progress window shows the status of component deployment. If deployment is
not successful, use the messages that appear in the Deployment Progress
window to troubleshoot errors.
Note For each Jaguar server you deploy components into, the first time you
deploy a component, a message indicates that the feature for deploying
components is not yet installed in the Jaguar server. Click OK to install this
feature.
Understanding Deployed Components in Jaguar

Each AI for Stored Procedures component built and deployed to Jaguar
consists of a set of Java classes that work with the AI for Stored Procedures
Adapter.
The Adapter is a library of classes that provide access to server stored
procedures and statements using JDBC drivers. The Adapter also provides
security, transaction control, datatype conversion, and error handling
integration.
For each component that is deployed, AI for Stored Procedures creates (or
modifies, if one already exists) the following items on the Jaguar server:
• A Jaguar package (if a package with the specified package name does not
already exist)
• A Jaguar component definition
• An IDL module (modified, if it already exists)
39
• An IDL interface
• Java source files for the component
• Java class files for the component
• A file that contains the component’s connection
When components are deployed into Jaguar, the following occurs:
1 The Jaguar package and IDL module are created only if they do not
already exist.
• If the package already exists, AI for Stored Procedures adds the new
component to the existing package.
• If the module already exists, the IDL interface is added to the existing
module.
2 The Application Integrator deployment feature creates implementation
files and stores them in the <jaguar_install_dir>\java\classes directory.
3 The component connection is created in a file named connection_name.ser
in the <jaguar_install_dir>\java\classes\SybAiConnections directory.
4 The Application Integrator component definition is added to the Jaguar
repository. Application Integrator components also include a collection of
user-defined Jaguar properties, which allow you to configure additional
properties for the component, such as debugging and connection caching.
If the properties need to be changed, you can edit them in Jaguar Manager.
See Chapter 3, “Jaguar and Application Issues” for details.
Understanding Deployed Connections in Jaguar

When you deploy a component into Jaguar, the Component Builder also
deploys the connection that is associated with the component.
When a component is deployed into Jaguar, the information for the
component’s connection is sent to Jaguar in the form of a serialized file, which
is located in the Jaguar installation directory structure (in the
<jaguar_install_dir>\ java\classes\SybAIConnections directory).
If you need to change connection information for a component, you must edit
the connection in the Component Builder, and then redeploy the component
and connection.
40
CH A PTE R 3 Jaguar and Application Issues
This chapter describes the characteristics of Application Integrator

components in Jaguar that affect programming client applications in
Jaguar. This chapter contains the following topics:
• AI Components in Jaguar
• Client Application Development
To help you understand this material, we recommend that you familiarize
yourself with the following Jaguar-related topics in the Jaguar CTS
Programmer’s Guide:
• Java components in Jaguar
• Transactions and component life cycles
• Connection management
41
AI Components in Jaguar
AI Components in Jaguar
When the Component Builder deploys a component into Jaguar, a new
component is created in the specified Jaguar package using the Jaguar Java
component model. The new component’s interface (its methods and their
arguments) is described using CORBA IDL.
Application Integrator components are designed to take advantage of the
Jaguar instance pooling feature. This section covers the following topics:
• Instance Creation
• Instance Activation
• Method Invocation
• Instance Deactivation
• Instance Destruction
Instance Creation
When a client executes methods on a proxy object for an Application Integrator
component, Jaguar creates a new instance of a component if the instance pool
does not contain any instances available for reuse. If an unused instance
already exists in the pool, Jaguar can initialize that instance by calling the
activate method and allowing a client application to call a method on the
component. During component instantiation, a one-time initialization routine
retrieves component property information.
Instance Activation
Jaguar activates an Application Integrator component instance as a result of a
client method invocation request. When activated, the component attempts to
connect to its target server using the connection properties that you deployed
along with the component. Depending on its configuration, the component can
obtain its connection from a connection cache defined in Jaguar, or it can open
a connection directly to the server.
42
CHAPTER 3 Jaguar and Application Issues
If an exception occurs during component activation, the exception information

is held and returned on the first method call to that instance. The most common
reasons for exceptions during component activation result from problems
connecting to the server, such as invalid security values, the server being
unavailable, and invalid connection properties.
Method Invocation
The method’s input parameters (parameters defined with the modes in or
inout) are passed to the target stored procedure. After the procedure executes,
any result sets are returned to the caller as the return value of the method call,
and any output parameters (parameters defined as inout or out) are returned to
the caller.
Instance Deactivation
Jaguar deactivates each Application Integrator component instance when it no
longer needs to keep that instance associated with the client that caused its
activation. During instance deactivation, the connection that was obtained
during instance activation is returned to the pool.
Instance Destruction
Jaguar destroys pooled component instances in any of the following
circumstances:
• A nonrecoverable error occurs during construction, activation, or
deactivation (these errors are recorded in the Jaguar server log).
• The Jaguar server shuts down.
• A component is refreshed.
• The component method completes its task, if the client invoked the
method using the Jaguar MASP feature.
43
Connections and Connection Caching

This section discusses how Application Integrator components use connections
to target servers, including the following topics:
• Component Properties: Connections and Security
• Acquiring and Disposing of Connections
• Defining Connection Caches in Jaguar Manager
• AI Component Properties in Jaguar Components
Component Properties: Connections and Security

When the Component Builder deploys a component into Jaguar, it sets the
following properties for the component. These properties affect connection
handling and security:
com.sybase.ai.connec This property is referred to as connection_name. It specifies the name of the
tion.name connection associated with the component.
com.sybase.ai.use_cli This property is referred to as use_client_security. It affects the user ID and
ent_security password that are used to obtain connections. Valid values are:
• false
A value of false tells the Application Integrator component to use the user
ID and password that were supplied in the connection object from the
Component Builder. The default value is false.
• true
A value of true tells the component to use the user ID and password from
the client that invoked the component method. When the value is true, the
caller’s user ID and password are obtained from Jaguar and are
subsequently used to override the user ID and password from the
connection definition.
com.sybase.ai.use_co This property is referred to as use_connection_cache. It specifies how the
nnection_cache Application Integrator component acquires and disposes of connections. Valid
values are:
• false
A value of false tells the Application Integrator component to open and

close connections to a server directly. The default value is false.
44
• true
A value of true tells the component to get and release connections from a
Jaguar connection cache.
com.sybase.ai.connec This property controls the action that Jaguar takes if there are no connections
tion_cache_unavail_a available in the cache. The valid values correspond to the possible values for
ction
the flag parameter on the JCMCache.getConnection() method. (See the
section on using connection management in the Jaguar CTS Programmer’s
Guide for a more detailed discussion.) Valid values are:
• nowait
Indicates that if no connections are available, the request results in an
exception (error condition) that is then propagated back to the caller. The
default is nowait.
• force
Indicates that Jaguar should attempt to open a new connection (that will
not be placed back in the cache after use).
• wait
Indicates that the component waits indefinitely until a connection becomes

available. We do not recommend that you use this option because this
indefinite wait can cause component instances to tie up resources and can
cause the client application to wait indefinitely.
Acquiring and Disposing of Connections

The process of acquiring and disposing of connections differs depending on
whether the Application Integrator component is configured to use connection
caching.
When Not Using • Acquiring connections refers to the process of opening a new connection
Connection Caching directly to the target server. The values supplied to the JDBC driver for
connecting to the server are retrieved from the connection definition with
the name matching the connection_name property. These values include
such information as the JDBC driver class name, connection URL, user
ID, password, and JDBC driver-specific properties. When opening a new
connection to a server, the Application Integrator component passes these
values to the JDBC driver.
• Disposing of connections refers to closing connections.
45
When Using • Acquiring connections refers to the process of retrieving a connection

Connection Caching from the Jaguar connection cache. When the Application Integrator
component needs to get a connection to the target server, the
connection_name property is used to locate a Jaguar connection cache by
name.
• Disposing of connections refers to releasing a connection back to the
Jaguar connection cache for other components to use.
Defining Connection Caches in Jaguar Manager

Defining connection caches for Application Integrator components is similar
to defining them for other components that use JDBC connection caches. A
connection cache that is defined for an Application Integrator component can
be shared with other non-Application Integrator components.
You must set up connection cache definitions in Jaguar Manager using the
following procedure. In general, use the same information that was used to
create the connection in the Component Builder.
To define a connection cache:
1 On the Driver tab of the Connection Cache Properties dialog box, select
the JDBC 1.1 radio button.
2 Enter the JDBC driver class name in the DLL or Class Name field.
For example, when using jConnect as the JDBC driver, the class name is
com.sybase.jdbc.SybDriver.
3 On the Server tab:
a Set the Server Name property to match the URL string from the
Application Integrator Component Builder connection definition (see
“Understanding AI Connections” on page 25 for information).
b Enter a valid user name and password.
4 Click the Enable cache-by-name access checkbox to set this property to on
(it is off by default). This allows the Application Integrator component to
look up connection caches by name.
Note Setting the Jaguar Enable cache-by-name access property requires

Jaguar administrator authority.
5 Restart the Jaguar server to effect changes to connection cache definitions.
46
Make sure the connection cache is installed into a running Jaguar server
before you use it in a component to connect to a target.
Note Currently, Jaguar connection cache definitions for JDBC drivers do not
allow you to specify driver connection properties. If the JDBC driver is Sybase
jConnect, the JDBC connection properties can be specified by appending the
name-value pairs to the URL using the following syntax:
/optional_db_name&PROP1=VAL1&PROP2=VAL2. See the Sybase
jConnect for JDBC Programmer’s Reference for information about setting
connection properties.
AI Component Properties in Jaguar Components

In addition to the properties that all Java-style Jaguar components have,
Application Integrator adds some properties to the component in the Jaguar
component repository. Application Integrator-specific properties begin with
the com.sybase.ai prefix and are set to default values by the Component
Builder when the component is initially deployed. You must refresh the
component in Jaguar Manager for property changes to take effect.
To edit these properties in Jaguar Manager, use the All Properties tab on the
Component Properties dialog box. Click on the column heading once to sort the
properties alphabetically by name in ascending order; click on the column
heading again to sort the properties alphabetically in descending order.
Table 3-1: Component properties and where they are set
Component property name Where property is set
com.sybase.ai.connection.name During Application Integrator
Component Builder deployment
com.sybase.ai.use_connection_cache Jaguar Manager
com.sybase.ai.connection_cache_ Jaguar Manager
unavail_action
com.sybase.ai.use_client_security Jaguar Manager
com.sybase.ai.debug Jaguar Manager
Do not modify any of the following component properties unless instructed to

do so by Sybase Technical Support:
• com.sybase.jaguar.component.files
• com.sybase.jaguar.component.ids
47
• com.sybase.jaguar.component.java.classes
• com.sybase.jaguar.component.interfaces
• com.sybase.jaguar.component.java.class
• com.sybase.jaguar.component.type
• com.sybase.jaguar.component.name
• com.sybase.jaguar.component.bind.object
• com.sybase.jaguar.component.bind.thread
Component Execution Debugging

The com.sybase.ai.debug component property can be used to cause the
component to write detailed trace information to the Jaguar server log. The
property can have a value of true to indicate that the component should write
trace information to the Jaguar server log.
A value of false (the default) indicates that the component should not write
information to the log.
Warning! Turning on debugging can cause large amounts of data to be logged,

which can adversely affect performance.
In general, the information produced by this logging is intended for Sybase

Technical Support to aid in problem determination.
To turn on component debugging:
1 In Jaguar Manager:
a Set the com.sybase.ai.debug property to a value of true.
b Refresh the component.
2 Run the component using your Jaguar client application.
3 Check the Jaguar server log to view the debug output produced by
component execution.
48
Client Application Development

If you are familiar with Jaguar, writing client applications that use Application
Integrator components is a straightforward task. Because an Application
Integrator component is defined in Jaguar as are other Java components, the
process of writing client applications will be similar to writing applications for
non-Application Integrator components.
For example, building client applications in Jaguar primarily consists of the
following steps:
1 Generate the stub classes.
2 Write the application logic. To write the application logic, you must do the
following:
a Instantiate proxy instances.
b Execute component methods.
c Process results.
d Handle errors.
3 Deploy the application.
See the Jaguar CTS Programmer’s Guide for details on how to perform
these tasks.
Note All IDL modules for Application Integrator components are defined with
the module property com.sybase.jaguar.module.java.package set to the Java
package name that was specified for this component in the Component Builder.
Therefore, this will be the Java package name for Java stubs generated for
Application Integrator components.
When you write client applications in Jaguar, be sure you understand the
following characteristics of Application Integrator components:
• Components can contain one or more methods.
• Each method corresponds to a target stored procedure.
• The input and output parameters for each method are mapped to
parameters in the procedure. (Typically, only procedures can have output
parameters.)
49
Client Application Development
• The return type of the method is based on whether result sets are returned
from the procedure. The number of result sets maps to IDL statements as
follows:
Number of result sets IDL mapping
0 void
1 TabularResults::ResultSet
More than 1 TabularResults::ResultSets
• If the target stored procedure has a return value, it appears in the method
signature as an output parameter.
• Parameters declared as nullable cause Application Integrator to add a
parameter (with the same mode as the nullable parameter) to the method
to communicate whether the corresponding parameter contains a NULL
value.
• Exceptions caught by the component are propagated to the client stub as a
user-defined exception type of AIUserException. These exceptions
contain a single field called Message that contains the error message text
for the exception.
50
A P PE N DI X A Target Types
This appendix provides information about targets containing stored

procedures. A target is a database or server that contains stored procedures
that Application Integrator components can invoke. This appendix
includes the following information about each target:
• The JDBC driver used for the target.
• Whether the target can be accessed by drivers included with the
Component Builder or requires a third-party JDBC driver.
• The type of connection that should be created in the Component
Builder for the target.
• Parameters needed to create connections for the target.
• Whether methods can be created from the target and automatically
added to the component or must be created manually. This depends
on the level of procedure metadata supported by the JDBC driver and
target server.
• JDBC statement types the target supports.
• Additional known target idiosyncrasies.
This appendix covers the following topics:
• Sybase Targets
• Oracle Targets
• JDBC-ODBC Bridge Targets
• Generic Targets
• About JDBC URLs
51
Sybase Targets
Sybase Targets
All Sybase targets use the Sybase JDBC driver called jConnect. Because
Sybase jConnect is provided with Application Integrator and Jaguar, you do
not need to register it with the Component Builder.
This section contains information about the following Sybase targets that are
supported in the Component Builder:
• Adaptive Server Anywhere
• Adaptive Server Enterprise
• DirectConnect
Adaptive Server Anywhere

Components that invoke Sybase Adaptive Server Anywhere (ASA) stored
procedures use connections of the type Sybase ASA. You must provide the
following values to create a Sybase ASA connection
Table A-1: Sybase ASA connection information
Information required Valid values
Host Name Name of the machine running ASA.
Port Number Port number that ASA is listening on.
Database Database the connection accesses.
Note This database is optional. If you do not

specify a value, the connection will access the
default database for the specified user name.
User Name User name for ASA.

Password User password for ASA.
:
For Sybase ASA, methods can be created automatically and can use any of the
following statement types:
• Callable Statement
• Prepared Statement
• Statement
52
APPENDIX A Target Types
Sybase ASA does not return information about whether parameters can accept
null values when methods are created automatically. Method parameters for
ASA stored procedures are set to not nullable by default.
Adaptive Server Enterprise

Components that invoke Sybase Adaptive Server Enterprise (ASE) stored
procedures use connections of the type Sybase ASE. You must provide the
following values to create a Sybase ASE connection
Table A-2: Sybase ASE connection information
Host Name Name of the machine running ASE.
Port Number Port number that ASE is listening on.
Database Database containing the target stored procedure.
Note This value is optional. If it is not specified,

the connection accesses the default database for
the specified user name.
User Name User name for ASE.

Password User password for ASE.
:
For Sybase ASE, methods can be created automatically and can use any of the
following statement types:
• Statement
Sybase ASE does not return information about whether parameters can accept
null values when methods are created automatically. Method parameters for
ASE stored procedures are set to not nullable by default.
DirectConnect
Sybase DirectConnect gateways provide access to heterogeneous data sources.
This section includes information on creating Application Integrator
components that access procedures through DirectConnect.
53
Sybase Targets
Components that access DirectConnect use connections of the type Sybase

DirectConnect. The following values are needed to create a connection:
Table A-3: Sybase DirectConnect connection information
Host Name Name of the host machine running
DirectConnect.
Port Number Port number DirectConnect is listening on.
Service Name Name of the DirectConnect service that the
connection accesses.
Note When the connection is created, the

Component Builder sets the jConnect
SERVICENAME property to the value you
specify.
User Name User name for DirectConnect.

Password User password for DirectConnect.
Currently, you must manually create methods for DirectConnect target stored
procedures. When you create methods manually, the best source of information
for defining the method correctly is the source code for the target stored
procedures.
54
Oracle Targets
This section contains information about the following Oracle targets that are
supported in the Component Builder:
• Oracle OCI
• Oracle Thin
The Oracle OCI and Oracle Thin targets both use the Oracle JDBC driver
called oracle.jdbc.driver.OracleDriver, which is not provided with
Application Integrator. To use Application Integrator with Oracle you must:
• Install the Oracle JDBC driver on the machine where the Component
Builder is running
• Install the Oracle JDBC driver on the machine where Jaguar is running
• Register the JDBC driver with the Component Builder
To do this, right-click the Stored Proc Component Builder, click Options,
and enter the class path for the Oracle driver in the Stored Proc Component
Builder Options window.
After you have installed and registered the Oracle JDBC driver, you can create
connections for Oracle in the Component Builder.
Oracle OCI
The Oracle OCI connection type is used for connections to Oracle that use OCI
networking. For these connections, the Oracle JDBC driver connects to Oracle
using OCI.
The following values are needed to create a connection:
Table A-4: Oracle OCI connection information
Version Valid values: 7 or 8
Address Type • TNSNAMES
• SQL*NET
For an address type of TNSNAMES, you must provide the following
information:
TNS Name An entry from the TNSNAMES file
User Name A valid Oracle user name
Password A valid Oracle user password
55
Oracle Targets

For an address type of SQL*NET, you must provide the following information:
Host Name Name of the machine where Oracle is running
Port Number Port number Oracle is listening on
SID Oracle system identifier
For Oracle OCI, you can create methods automatically. Methods can use any
of the following statement types:
• Statement
Oracle Thin
The Oracle Thin type is used for connections to Oracle that do not use OCI.
For Oracle Thin connections, the Oracle JDBC driver functions like a pure Java
Type IV JDBC driver.
The following values are needed to create a connection
Table A-5: Oracle Thin connection information
Host Name Name of the machine where Oracle is running
Port Number Port number Oracle is listening on
SID Oracle system identifier
:
For Oracle Thin, you can create methods automatically. Methods can use any
of the following statement types:
• Statement
56
JDBC-ODBC Bridge Targets

The JDBC-ODBC Bridge connection type allows you to create connections for
any ODBC driver. These connections use a JDBC driver called the Sun JDBC-
ODBC bridge (sun.jdbc.odbc.JdbcOdbcDriver). Because the JDBC-ODBC
bridge is provided with AI for Stored Procedures, you do not need to register it
in the Component Builder. You must install and configure ODBC drivers for
any connections that use the bridge on the machines where the Component
Builder and Jaguar are running.
The following values are needed to create connections:
Table A-6: JDBC-ODBC Bridge connection information
ODBC Data Source Name of an ODBC data source.
To obtain this value:
1 From the Start menu, point to Settings, then
click Control Panel.
2 Double-click the ODBC Icon.
3 Select the User DSN tab.
4 Enter the name for the driver shown in the
Name column of the User Data Sources field
in the ODBC Data Source field.
User Name User name for the target database.
Password Password for the target database.
For JDBC-ODBC bridge connections, your ability to create methods

automatically depends on the underlying ODBC driver and database. The best
way to determine whether methods can be created automatically is to try doing
so for several stored procedures, and then verify that the resulting method
definitions are correct.
Support for different statement types also depends on the underlying ODBC
driver and database. Most JDBC-ODBC bridge drivers support all statement
types, and all support the type Statement.
57
Generic Targets
Generic Targets
The Generic connection type allows you to create connections that use third-
party JDBC drivers. This type allows you to enter a JDBC driver class and
JDBC URL for a connection explicitly.
To use Application Integrator with a non-Sybase JDBC driver you must do the
following:
• Install the JDBC driver on the machine where the Component Builder is
running
• Install the JDBC driver on the machine where Jaguar is running
• Register the JDBC driver with the Component Builder
To do this, right-click the Stored Proc Component Builder, click Options,
and enter the class path for the driver in the Stored Proc Component
Builder Options window.
The following values are needed to create connections:
Table A-7: Generic connection information
JDBC Driver Java class name of the JDBC driver.
URL A valid JDBC URL for the JDBC driver
specified.
See “About JDBC URLs” on page 59 for
detailed information.
User Name User name for the database or machine that
contains the target stored procedure.
Password User password for the database or machine that
contains the target stored procedure.
For generic connections, the ability to create methods automatically depends

on whether the JDBC driver supports metadata calls. The best way to
determine whether methods can be created automatically is to try doing so for
several stored procedures, and verify whether the resulting method definitions
are correct.
Support for different statement types also depends on the underlying JDBC
driver and database. See the documentation for the JDBC driver for
information about supported driver types.
58
About JDBC URLs

A JDBC URL is an address used by JDBC drivers to connect to a database or
server. When you create connections in the Component Builder, you are
prompted for information needed to derive the URL. The Generic connection
type in the Component Builder allows you to enter an URL manually.
Different JDBC drivers have slightly different URL formats.
The following example shows the Sybase JDBC protocol and subprotocol
information contained in the URL:
Figure A-1: Sybase JDBC URL composition
The driver portion is always jdbc.

The protocol (in this case is sybase.Tds) specifies the JDBC driver and the
native database protocol.
The host name and port number identify the machine that contains the database
where the target stored procedures reside.
For Sybase, you can also specify a database name as part of the URL. For
example:
jdbc:sybase:Tds:localhost:5000/dbase1
where the database name (dbase1) is appended to the URL.
59
About JDBC URLs
60
Glossary
adapter A set of Application Integrator classes that are also referred to as the
Application Integrator run-time classes. Internally, the Adapter provides
access to server stored procedures and statements using JDBC drivers; it
also provides security, transaction control, datatype conversion, and error
handling integration.
applet An application program written in the Java programming language that
can be retrieved from a Web server and executed by a Web browser. A
reference to an applet appears in the markup for a Web page in the same
way that a reference to a graphics file appears: a browser retrieves an
applet in the same way that it retrieves a graphics file. For security
reasons, an applet’s access rights are limited in two ways: the applet
cannot access the file system of the client upon which it is executing; and
the applet’s communication across the network is limited to the server
from which it was downloaded.
builder See Component Builder.
byte code The output of a Java compiler. Byte code is suitable for interpretive
execution by a Java Virtual Machine.
catalog schema A persistent object in the database that consists of the collection of objects
associated with a particular schema name and user authorization identifier.
The objects include tables, views, domains, constraints, assertions, and
privileges.
catch Java code that begins error handling logic in exception handling. See also
throw.
class In object-oriented programming, a model or template that can be
instantiated to create objects with a common definition and therefore,
common properties, operations and behavior. An object is an instance of
a class.
code page An assignment of graphic characters and control function meanings to all
code points.
code set The characters in a code page.
61
COMMAREA Common communications area where mainframe application logic and
presentation logic that are stored in separate regions can communicate with
each other.
Common Object A specification produced by the Object Management Group (OMG) that
Request Broker presents standards for various types of object request brokers. Implementation
Architecture
(CORBA) of CORBA standards allows object request brokers from different software
vendors to interoperate.
component In Jaguar, an “application object” that consists of one or more methods. Jaguar
components typically execute business logic, access data sources, and return
results to the client. Clients (Java applications) create an instance of a
component and execute methods associated with that component.
Application Integrator creates a component that can contain one or more
methods for use in a client application.
Component Builder Application Integrator graphical design tool used to create a component from
component and connection information.
connection A network between two systems:
• For SNA, the path connects an LU on one machine to an LU on another
machine.
• For TCP/IP, the path connects TCP modules on separate machines.
In Application Integrator, the user creates a connection as part of the
component.
container A visual user-interface component that holds objects.
datatype The characteristics of stored information on a computer.
deploy Act of sending components to target container, such as Jaguar and
PowerDynamo.
deployment target The deployment container, such as Jaguar and PowerDynamo.
design time Environment in which the Component Builder is used to build connections and
components for deployment into Jaguar. Compare with run time.
exception An abnormal condition, such as an unknown communications error.
execution time See run time.
62
host The mainframe or other machine on which a database, an application, or a
program resides. In TCP/IP, this is any system that is associated with at least
one Internet address. See also Transmission Control Protocol.
hypertext A way of presenting information online with connections (hypertext links)
between one piece of information and another.
import The process of moving a stored procedure from its target data source into the
Application Integrator tool.
instance In object-oriented programming, an object created by instantiating a class.
instantiate In object-oriented programming, to represent a class abstraction with a
concrete instance of the class. A way to replicate a class file into several new
components.
Interface Definition In CORBA, a declarative language that is used to describe object interfaces
Language (IDL) without regard to object implementation.
Jaguar CTS Jaguar Component Transaction Server provides a framework for deploying
middle-tier logic of distributed component-based applications.
jar file A file composed of other files, such as class files and serialized files that acts
as a repository or library of classes.
Java An object-oriented programming language for portable interpretive code that
supports interaction among remote objects. Java was developed and specified
by Sun Microsystems, Inc.
JavaBeans The platform-independent component architecture for the Java programming
language. JavaBeans enables software developers to assemble pieces of Java
code in a drag-and-drop development environment.
Java Database An application programming interface that has the same characteristics as
Connectivity (JDBC) Open Database Connectivity (ODBC) but is specifically designed for use by
Java database applications. For databases that do not have a JDBC driver,
JDBC includes a JDBC-to-ODBC bridge.
JavaScript A scripting language that resemble Java and was developed by Netscape for
use with the Netscape browser.
Java Virtual Machine An execution time environment for running Java programs. JVMs may be
(JVM) stand alone or embedded in Web browsers, transaction servers, database
management systems, and so on.
jConnect The Sybase JDBC driver that is 100% Java and can be used by applets.
jConnect can also be used with Sun and Microsoft Java virtual machines.
63
marshal To copy data into a form suitable for use by another object. Stubs perform
marshalling.
method In object-oriented programming, software that implements the behavior
specified by an operation.
null indicator A boolean value (true/false) that indicates whether the first parameter value of
a method is NULL.
object In object-oriented programming, a concrete realization of a class that consists
of data and the operations associated with that data.
object request In object-oriented programming, software that serves as an intermediary by
broker (ORB) transparently enabling objects to exchange requests and responses.
Open Database Standard application programming (API) interface for accessing data in both
Connectivity (ODBC) relational and nonrelational database management systems. Using this API,
database applications can access data stored in database management systems
on a variety of computers even when each database management system uses
a different data storage format and programming interface. ODBC is based on
the Call Level Interface specification of the X/Open SQL Access Group and
was developed by DEC, Lotus, Microsoft and Sybase.
Open ServerConnect Sybase product that provides capability for programmatic access to mainframe
data. It allows workstation-based clients to execute customer-written
mainframe transactions remotely.
package In Jaguar, a collection of components that work together to provide a service
or some aspect of an application’s business logic. Each package acts as a unit
of distribution, grouping together application resources for ease of deployment
and management.
package name In Application Integrator, name used to provide unique identifiers for
components and associate them with a specific piece of an application
program. In the absence of a package name, AI for Stored Procedures assigns
a default name.
partner certification Sybase publications that certify third-party query and development tools to
reports work with Sybase products.
port number In the Internet suite of protocols, the identifier for a logical connector between
an application entity and the transport service.
project files Files that store definitions and information about logically-related components
and connections.
64
proxy A local representation of a remote user object in a distributed application.
remote stored A customer-written CICS program that resides on the mainframe and
procedure (RSP) communicates with MainframeConnect for DB2/MVS-CICS.
result set Rows of data retrieved from the database when a SQL SELECT statement is
executed. The return value for a method call.
run time Instant at which a particular computer program executes.
In Application Integrator, the environment in which a client application tries to
invoke a component in Jaguar CTS. Synonymous with execution time.
Compare with design time.
scalable Pertaining to the capability of a system to adapt readily to a greater or lesser
intensity of use, volume, or demand.
schema Set of statements, expressed in a data definition language, that completely
describe the structure of a database.
server A functional unit that provides shared services to one or more clients or
workstations over a network.
skeleton A skeleton acts as the interface between the Jaguar run-time environment and
the user code that implements the method. Skeletons are compiled and linked
with each of the components, and at run time they enable Jaguar to locate and
invoke an appropriate method.
stateful In code set conversion, the interpretation of a byte depends on the bytes before
it.
In Application Integrator, component instances that remain dedicated to a
single client application while the connection to the server remains open until
the component is deactivated. Compare with stateless.
stateless Application Integrator component instances that are removed from the instance
pool and dedicated to a client application only for the duration of the method
call. Compare with stateful.
stored procedure A collection of SQL statements and optional control-of-flow statements stored
under a name.
stub Small module called from an application that performs marshalling and
transfer of control to a larger body of related code.
65
In Jaguar, a stub is a Java class generated by Jaguar Manager and acts as a
proxy object for a Jaguar component. Compiled and linked with a Java client
application, a stub communicates with Jaguar to instantiate and invoke a
method on a component in the middle tier. Stubs make remote Jaguar
components appear local to the client.
Sybase Central A graphical user interface (GUI) that monitors, configures, and controls
databases and related products. Written in Java, it can run on any platform that
supports a Java Virtual Machine.
Systems Network A network plan for transmitting information units through networks and
Architecture (SNA) controlling network configuration and operation.
target Source that contains the stored procedure(s) used to create an Application
Integrator component.
throw Java code that deals with exception handling, specifically sending the
exception that triggers code for error handling. See also catch.
Transmission A communications protocol used in the Internet. TCP uses Internet Protocol
Control Protocol (IP) as the underlying protocol.
(TCP)
Transaction Router DirectConnect program that accepts requests from workstation-based clients
Service (TRS) and routes them to Open ServerConnect.
Web browser A client program that initiates requests to a Web server and displays the
information that the server returns.
Web server A server that is connected to the Internet and is capable of serving Web pages.
wizard A series of dialog boxes within an application that guide a user through the
completion of a task.
66
Index
A statement type 33
Calling conventions 33
Accessing stored procedure metadata 19
Catalog
Acquiring connections
method property 32
in Jaguar 45
Catalog separator
Activation
method property 32
of instances 42
Changing connection information 40
Adapter 39
Characteristics of AI components in Jaguar 49
Adaptive Server Anywhere
Class name
and Sybase Central 22
JDBC driver 46
EAServer component 12
Class path
Adaptive Server Anywhere. See ASA 12
JDBC driver 26
Adaptive Server Enterprise. See ASE 12
Classes
Administrator
Java 13
Jaguar authority required 46
Client applications 16, 17
AI components. See Components 16
developing 49, 50
AI for Stored Procedures
interaction with Jaguar 16
architecture 13
Closing project files 23
description 12
com.sybase.ai
steps in development process 18
AI component properties in Jaguar 47
Application development process 18
Component Builder
Application Integrator
description 12, 13
deployment feature 40
Options dialog box 26
installing deployment feature 39
starting 22
Applications
tasks performed using 22
code 17
using 22
developing 49, 50
Component properties
ASA
component name 28
access using JDBC driver 12
connection name 29
connections 52
in Jaguar 47
ASE
Java package name 29
access using JDBC driver 12
Components
connections 53
characteristics in Jaguar 49
Authorization
characteristics of deployed components in Jaguar
Jaguar administrator 46
39
Automatic
contents 17
method creation 29, 58
defining properties in Component Builder 28
Automatic method creation 19
definition 28
deploying 38
deploying in Jaguar 40
C description 12
execution debugging 48
cache_unavail_action in Jaguar 42
Jaguar property 45 middle tier in Jaguar 16
Caching name property 28
connection 27 properties in Jaguar 47
Callable Statement
67
Index
refreshing in Jaguar Manager 43, 47 types supported in Component Builder 25

relationship to connections 25, 28 CORBA IDL 42
Compute Creating
creating default statement template 33 component methods 25
Connection caches 40 components 18, 19
and acquiring and disposing of connections in Jaguar connections 19
45 Jaguar client applications 19
and AI components 27 Jaguar components 19
defining in Jaguar 46 new projects 23
installed in running Jaguar server 47 statement templates 33
procedure for defining in Jaguar 46 Creating methods 29
using Jaguar 25 automatically 19, 29, 58
Connection failure manually 19, 30
typical causes 27 manually, importance of understanding stored
Connection types procedures when 30
generic 58, 59 Creation
JDBC-ODBC Bridge 57 of instances 42
Oracle 55, 56
Oracle OCI 55
Oracle Thin 56
supported in Component Builder 25 D
Sybase 52, 54 Database
Sybase ASA 52 ASA access 12
Sybase ASE 53 ASE access 12
Sybase DirectConnect 53 commands 13
connection_name Oracle access 12
Jaguar property 44 stored procedures 13
Connections transaction target 16
acquiring in Jaguar 45 Datatypes
and JDBC URLs 26 conversion 39
at design time 25 Jaguar 31, 36
at run time 25 Java 36
defining properties in Component Builder 25 JDBC 30
definition 25 parameter 29
deployed in Jaguar 40 SQL 36
deploying 40 third-party DBMS 36
disposing of in Jaguar 45 Deactivation
editing information 40 of instances 43
Jaguar 38 Debugging
JDBC 25 component execution 48
name property 29 Decimal datatypes
relationship to components 28 JDBC 30
serialized file in Jaguar 40 Defining
specifying properties in URL 47 connection caches in Jaguar 46
testing 25 connection properties in Component Builder 25
testing in Component Builder 27 Jaguar connection caches 46
68
Index
parameter modes 35 E
Deployed components
EAServer 15
in Jaguar 40
components 12
Deploying
Editing
components 19, 38, 39
connection information 40
connections 19, 40
method definitions 30
Deployment
parameter names 35
connections in Jaguar 40
Enable cache-by-name access property
feature 40
authority 46
feature installation 39
setting 46
Deployment Progress window 39
Enterprise Application Server. See EAServer 15
Deployment Wizard
Errors
understanding 38
handling 39
Description
nonrecoverable 43
method property 31
troubleshooting using Deployment Progress window
Design time
contents 39
AI for Stored Procedures architecture 13
troubleshooting using Details view in Sybase Central
Component Builder process 13
30
connections 25
Exception handling 50
Destruction
of instances 43
Details view
in Sybase Central 24 F
Developing client applications 49, 50
Development process 18 Failure
DirectConnect typical causes of connection 27
connections 53 Files
RSPs 13 implementation 40
Disposing of connections jar 26
in Jaguar 45 project 22
DLL serialized in Jaguar 40
JDBC driver class name 46 zip 26
Documentation
references to supported procedures 14
Domain name format
and Java package names 29
G
Drivers Generic connection type 58, 59
Oracle 55
registering JDBC with Component Builder 26,
55, 58
specifying connection properties 47
I
third-party JDBC 57, 58 IDL
CORBA 42
module 40
viewing interface 37
IIOP port 38
Implementation files
69
Index
location 40 package ame information in Deployment Wizard

Installation 39
Jaguar directory 40 packages 40
third-party JDBC drivers 58 packages and deployed component 39
Instance procedure for defining connection caches 46
activation in Jaguar 42 repository 40
creation in Jaguar 42 setting component properties 40
deactivation in Jaguar 43 Jaguar Component Transaction Server (CTS). See Jaguar
destruction in Jaguar 43 11
pooling in Jaguar 42 Jaguar properties
Instruction cache_unavail_action 45
tutorials 20 connection_name 44
Interface use_client_security 44
view in Sybase Central 24 use_connection_cache 44
viewing IDL 37 Jar files 26
Invocation Java
of methods 43 classes 13
mapping Java datatypes to Jaguar datatypes 36
mapping Java datatypes to SQL datatypes 36
package name component property 29
J package name for stubs generated for AI components
Jaguar 49
and AI components 42 package name format 29
and Sybase Central 22 Type IV JDBC driver 56
authority required for setting Enable cache-by-name Java Database Connectivity. See JDBC 12
access property 46 JCMCache.getConnection() method 45
component definition and deployed component 39 jConnect 12
component properties 44 class name 46
component repository 47 JDBC
connection caching 25 connections 25
connection caching and AI components 27 datatype method property 30
connection information in Deployment Wizard 38 decimal datatypes 30
datatype property 31 entering URLs 58
defining connection caches 46 numeric datatypes 30
deployed components in 39 parameter datatypes 30
deployed connections 40 statement type support 33
EAServer component 12 URL and Generic connection type 59
functionality 16 URL definition 59
installation directory 40 URL derived from connection properties 26
instance pooling 42 JDBC drivers
Jaguar and Java package names 29 accessing stored procedure metadata 19, 29
mapping IDL datatypes to parameter types 35 class name 46
mapping Jaguar datatypes to SQL and Java datatypes class path 26
36 Java Type IV 56
MASP feature 43 mapping target datatypes to SQL datatypes 36
method name restrictions 34 metadata support 58
70
Index
Oracle 55 mapping to stored procedures 34

registering with Component Builder 26, 55, 58 name restrictions 34
specifying connection properties 47 names 31
third-party 57, 58 names, mapping to stored procedure names 34
used to access stored procedures 12 null values in parameters 37
JDBC type parameter information 29
method property 30, 32 parameter names 30
JDBC-ODBC Bridge connection type 57 properties 31
relationship to stored procedures 28
return value relationship to result sets 34
warning messages when creating 30
L Middle-tier components
Language events in Jaguar 16
Open ServerConnect 14 Modes
parameter 30, 35
Modules
IDL 40
M Multi-tier computing environment
Manual method creation 19, 30 Jaguar architecture 16
Mapping
parameter datatypes to Jaguar datatypes 35
stored procedure return values to parameters 34
stored procedures to methods 34 N
MASP Names
Jaguar feature 43 parameter 35
Messages target stored procedure 30
viewing in Sybase Central 30 Nonrecoverable errors 43
warning when creating methods 30 Non-Sybase database access 12
Metadata Non-Sybase JDBC drivers
accessing stored procedure 29 registering with Component Builder 26
stored procedure 19 requirement for installing on Jaguar server 27
support in JDBC driver 58 Null indicator parameter 37
Method name Null values
property 31 in method parameters 37
Method roperties in parameters 29
General 31 parameters 30
target 32 Numeric datatypes
Methods JDBC 30
creating 25, 29
creating automatically 19, 29, 58
creating manually 19, 30
editing definitions 30 O
invoking 43 OCI networking
JCMCache.getConnection() 45 connections to Oracle 55
mapping parameters to stored procedure return Online documentation
values 34 location 20
71
Index
Open ServerConnect Process flow

language events 14 AI for Stored Procedures component development
Opening project files 23 18
Oracle Project files
connection types 55, 56 closing 23
JDBC driver 55 creating 23
Oracle OCI connection type 55 extension 22
Oracle Thin connection type 56 opening 23
Output parameters saving 24
and return values 35 viewing 23, 24
Projects
creating new 23
Properties
P component 28
Package name Jaguar component 40, 47
Jaguar 39 method 31
Java 29, 49 Protocol
relationship of Java to Jaguar 29 in JDBC URL 59
Packages
Jaguar 40
Java 49
Parameter mode 29, 30, 35 R
method property 31, 32 Refreshing components
Parameter names 35 in Jaguar Manager 43, 47
method property 31, 32 Registering JDBC drivers with Component Builder
Parameter type 26, 55, 58
method property 31 Relationship of methods and components 29
Parameters Remote Procedure Calls. See RPCs 14
and null values 37 Remote Stored Procedures. See RSPs 13
in statement templates 33 Repository
information for methods 29 Jaguar 40
mapping datatypes to Jaguar IDL datatypes 35 Jaguar component 47
mapping to stored procedures 34 Research
Performance stored procedure contents 18
and callable statement type 33 Restrictions
Ports method names in Jaguar 34
IIOP 38 on content of statement template 33
PowerDynamo stored procedures in components 28
EAServer component 12 Result sets
Precision method property 32
method property 32 relationship to method return value 34
Prepared Statement returned by target stored procedure 30
statement type 33 Return values 29
Procedures relationship to result sets 34
name property 32 stored procedure 35
supported types 13 target stored procedure 30
72
Index
RPCs Statement templates

support for Open ServerConnect 14 and statement types 33
RSPs computing 33
support for DirectConnect 13 creating 33
Run time parameters in 33
AI for Stored Procedures architecture 13 restrictions on content 33
and instance destruction 43 Statement types 33
and Jaguar security 44 Callable Statement 33
and scale parameter property 32 method property 32
and setting null indicators in client applications Prepared Statement 33
37 Statement 33
and statement types 33 support in JDBC drivers and databases 58
clients invoking components in Jaguar 13 Stored procedures
components and Jaguar connection caching 27 accessing metadata 19, 29
connections 25 mapping to methods 34
requirements for installing non-Sybase JDBC names, mapping to method names 34
drivers 27 references in documentation 14
substituting method parameters in statement relationship to methods 28
templates 33 supported types 13
using JDBC to invoke stored procedures 25 understanding 18
Stored Procedures Adapter
definition 39
Stored Procedures Component Builder
S using 22
Samples String Delimiter
online location 20 method property 32
Saving project files 24 Subprotocol
Scale in JDBC URL 59
method property 32 Sun JDBC-ODBC bridge driver 57
parameters 30 Supported connection types 25
Schema generic 58
method property 32 JDBC-ODBC bridge 57
Security 39 Oracle 55
Jaguar component properties 44 Sybase 52
Serialized file 40 Supported procedure types 13
Server name Sybase
Jaguar property and URL 46 ASA connections 52
Skills ASE connections 53
required in AI development process 18 connection types 52, 54
Specifying driver connection properties 47 DirectConnect connections 53
SQL jConnect driver class name 46
commands 13 Sybase Central 22
mapping SQL datatypes to Java datatypes 36
Starting the Component Builder 22
Statement
statement type 33
73
Index
T User scenario 15
Using AI components
Target stored procedures
in applications 19
accessed by AI components 17
setting the null indicator value 37
name 30
Using Jaguar connection caching 25
references in documentation 14
Using the Component Builder 22
supported procedure types 13
Targets
definition 51
generic 58 V
JDBC-ODBC Bridge 57
Viewing
Oracle 55, 56
IDL interface 37
Oracle OCI 55
messages in Sybase Central 30
Oracle Thin 56
project files 23, 24
Sybase 52, 54
Sybase ASA 52
Sybase ASE 53
Sybase DirectConnect 53 W
Templates
creating 33 Warning messages
statements and statement types 33 when creating methods 30
Testing connections 25 Working with project files 22
after registering drivers with Component Builder 27
in Component Builder 27
Third-party
DBMS datatypes 36
Z
JDBC drivers 57, 58 Zip files 26
Transaction control 39
Troubleshooting
debugging 48
using Deployment Progress window contents 39
using Details view in Sybase Central 30
Tutorials
online location 20
U
Understanding stored procedure functionality when creating
methods manually 30
URLs
connection properties in 47
JDBC 26, 59
use_client_security
Jaguar property 44
use_connection_cache
Jaguar property 44
74

Application Integrator: Reference For Stored Procedures

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

Application Integrator: Reference For Stored Procedures

Uploaded by

Copyright:

Available Formats

Reference for Stored Procedures

Copyright © 1989-1999 by Sybase, Inc. All rights reserved.

Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.

About This Book ............................................................................................................................ v

CHAPTER 1 Understanding AI for Stored Procedures ................................... 11

CHAPTER 2 Working with the AI Component Builder .................................... 21

Mapping Stored Procedures to Methods................................. 34

CHAPTER 3 Jaguar and Application Issues..................................................... 41

AP PE ND IX A Target Types .................................................................................. 51

Application Integrator is a Jaguar component development and

Note The remaining chapters in this guide refer to Application Integrator

How to Use This Book

Table 1: Application Integrator for Stored Procedures Reference

If You Need Help

Sybase Professional Services

If You Have Questions About This Book

Note Please send comments about product features, functionality, or

This chapter describes the functionality and architecture of Application

Note The remaining chapters in this guide refer to Application Integrator

What Is AI for Stored Procedures?

A Description of AI for Stored Procedures

AI for Stored Procedures Architecture

During run time, a client application attempts to invoke a component in Jaguar,

• DirectConnect Remote Stored Procedures (RSPs)

Note This documentation refers to all supported procedures as “target stored

Why Use AI for Stored Procedures?

Jaguar and AI for Stored Procedures Functionality

How Jaguar Works

When Jaguar Uses AI for Stored Procedures Components

Basic Steps for Building a Component

The following sections describe each step.

Step 1: Research the Target Stored Procedure

Step 2: Create the Component

Step 3: Deploy the Component

Step 4: Use the Component

Using the AI for Stored Procedures Tutorials

This chapter contains information about using the AI for Stored

Note Sybase provides samples with the Application Integrator software.

Working with the Component Builder

Starting the Component Builder

Working with Project Files

This section covers these topics:

Creating, Opening, and Closing Projects

Viewing Project Contents

Figure 2-1: Component Builder project file structure

In the asademo project, the component called ASADemo contains seven

Defining Connection Properties

Connection type Description

• Properties needed to connect to the database containing the target stored

Registering JDBC Drivers

Note Java package names are not the same as Jaguar

Connection name Each component requires a connection. When

Creating Methods Automatically

In some cases, JDBC drivers cannot retrieve complete information about a

Creating Methods Manually

Tab Field Description Comments

Note Callable statements yield the best performance

Mapping Stored Procedures to Methods

Target Stored Procedures and Method Names

Note If necessary, the Component Builder removes spaces and underscores

Result Sets and Method Return Value

Stored Procedure Return Values

Parameters with NULL Values