Application IntegratorSybase provides the following Application Integrator documentation: •...

Reference for Stored Procedures

Application IntegratorVersion 3.0

n new

29-9

the

erver, catio

s, n prise ork n ase,

upport, it,

erAMC, ipt, erWare

or, S SQL , SQL L

inancial orkbench, ream,

e roup

s.

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 i 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) 2845.

Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All or 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 SAdaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replin, 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, DataExpresDataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, DistributioDirector, E-Anywhere, E-Whatever, Embedded SQL, EMS, Enterprise Application Server, Enterprise Application Studio, EnterClient/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise WArchitecture, Enterprise Work Designer, Enterprise Work Modeler, EWA, Gateway Manager, ImpactNow, InfoMaker, InformatioAnywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBMainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MySNet-Gateway, Net-Library, NetImpact, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL ToolkOpen 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, PowPowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScrPowerSite, PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowDesktop, 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 Design-Designor, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script,Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL EverywhereModeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQServer SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase FServer, Sybase Gateways, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User WSybaseWare, Syber Financial, SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data StTransact-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, WarehousWORKS, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGSQL 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 companie

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 ................................... 11What Is AI for Stored Procedures? ................................................ 12

A Description of AI for Stored Procedures .............................. 12AI for Stored Procedures Architecture..................................... 13Supported Procedures ............................................................ 13

Why Use AI for Stored Procedures? .............................................. 15Problem ................................................................................... 15Solution ................................................................................... 15

Jaguar and AI for Stored Procedures Functionality........................ 16How Jaguar Works .................................................................. 16When Jaguar Uses AI for Stored Procedures Components.... 17

Basic Steps for Building a Component........................................... 18Step 1: Research the Target Stored Procedure ...................... 18Step 2: Create the Component................................................ 19Step 3: Deploy the Component ............................................... 19Step 4: Use the Component .................................................... 19

Using the AI for Stored Procedures Tutorials................................. 20

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

Starting the Component Builder .............................................. 22Working with Project Files ....................................................... 22

Understanding AI Connections ...................................................... 25Defining Connection Properties............................................... 25Registering JDBC Drivers ....................................................... 26Testing Connections................................................................ 27Connection Caching ................................................................ 27

Understanding AI Components ...................................................... 28Component Properties ............................................................ 28Creating Methods .................................................................... 29Method Properties ................................................................... 31

iii

Contents

Mapping Stored Procedures to Methods................................. 34Understanding AI Component Deployment.................................... 38

Understanding the Deployment Wizard................................... 38Understanding Deployed Components in Jaguar.................... 39Understanding Deployed Connections in Jaguar .................... 40

CHAPTER 3 Jaguar and Application Issues..................................................... 41AI Components in Jaguar............................................................... 42

Instance Creation .................................................................... 42Instance Activation .................................................................. 42Method Invocation ................................................................... 43Instance Deactivation .............................................................. 43Instance Destruction................................................................ 43

Connections and Connection Caching........................................... 44Component Properties: Connections and Security ................. 44Acquiring and Disposing of Connections................................. 45Defining Connection Caches in Jaguar Manager.................... 46AI Component Properties in Jaguar Components................... 47

Client Application Development ..................................................... 49

APPENDIX A Target Types .................................................................................. 51Sybase Targets .............................................................................. 52

Adaptive Server Anywhere...................................................... 52Adaptive Server Enterprise ..................................................... 53DirectConnect.......................................................................... 53

Oracle Targets ............................................................................... 55Oracle OCI .............................................................................. 55Oracle Thin.............................................................................. 56

JDBC-ODBC Bridge Targets.......................................................... 57Generic Targets ............................................................................. 58About JDBC URLs ......................................................................... 59

Glossary 61

iv

tor

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 Integraas “AI for Stored Procedures,” and to Jaguar Component TransactionServer (CTS) as “Jaguar.”

AudienceUse this document if you are responsible for using AI for Stored Procedures to create components from target stored procedures anddeploy them to Jaguar.

How to Use This BookUse this document to understand AI for Stored Procedures.

Table 1 describes the contents of this book.

v

About this book

0 als and

Table 1: Application Integrator for Stored Procedures Reference contents

DocumentationSybase 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.program group for Application Integrator samples, which include tutoridesigned to give you hands-on experience with each step of creatingdeploying components.

Related DocumentationThis 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.

Chapter Contents

Chapter 1, “Understanding AI for Stored Procedures”

Provides an overview of the functionality and features of AI for Stored Procedures.

Chapter 2, “Working with the AI Component Builder”

Describes how to work with the AI for Stored Procedures Component Builder to create and deploy components.

Chapter 3, “Jaguar and Application Issues”

Provides information about how to write applications that use components you create.

Appendix A, “Target Types”

Provides information about JDBC and ODBC drivers required when creating connections in the AI for Stored Procedures Component Builder.

Glossary Defines technical terms used in this book.

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.

ConventionsThis section describes the following:

• Style Conventions

• Syntax Conventions

Style ConventionsThe following table shows some of the style conventions used in the documentation for this product.

Table 2: Style conventions

Item Example

• Programs

• Utilities

• Procedures

• Commands

create connection

• File names

• Directory names

• Properties

install.cfg

Code examples input com.sybase.ai.utils

• User input

Command line input

shutdown

Variables (place-holder text that you replace with the appropriate value)

host_name

vii

About this book

Syntax ConventionsThe 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

Symbol Explanation Example

( ) Include parentheses as part of the command.

START DATABASE (database_name)

| A vertical bar indicates that you can select only one of the options shown. Do not type the bar in your command.

{yes|no}

, A comma indicates that you can choose one or more of the options shown. Separate each choice by using a comma as part of the command.

{long,short,none}

{ } Braces indicate that you must choose one or more of the enclosed options. Do not type the braces when you enter the option.

Select only one:

{datetime|datetime4}

Select at least one:

{char_iso,char_eur, char_jis}

[ ] Brackets indicate that you can choose one or more of the enclosed options, or none. Do not type the brackets when you enter the options.

[truncate]

... An ellipsis indicates that you can repeat the previous item as many times as necessary.

{datax,datay}...

viii

About this book

lps

If You Need HelpEach 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 ServicesSybase 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 BookIf you have questions, comments, or suggestions about this book, contact the Sybase documentation group directly by e-mail at:

[email protected]

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 heus provide more accurate, detailed, and easy-to-use documentation.

Note Please send comments about product features, functionality, orproblems to your systems engineer or Sybase Technical Support.

ix

x

tor

C H A P T E 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 Integraas “AI for Stored Procedures,” and to Jaguar Component TransactionServer (CTS) as “Jaguar.”

11

What Is AI for Stored Procedures?

vide ssible

use eate tored

ploy other

BC) te

sible nect where such

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 ProceduresAI for Stored Procedures allows you to create Jaguar components that proaccess to existing stored procedures, making the stored procedures acceto Web-based client applications.

The AI for Stored Procedures Component Builder is a design tool that youto create these components. The Component Builder makes it easy to crcomponents by simply browsing a database and selecting a collection of sprocedures. No manual coding is required.

After you create the components, you can use the Component Builder to dethem to Jaguar, where they can be used by Jaguar client applications or byJaguar components.

AI for Stored Procedures components use Java Database Connectivity (JDto access stored procedures. Using the Component Builder, you can creacomponents that invoke stored procedures in any database that is accesthrough a JDBC driver. AI for Stored Procedures includes the Sybase jConJDBC driver for access to Sybase databases such as Adaptive Server Any(ASA) and Adaptive Server Enterprise (ASE). For non-Sybase databases, as Oracle, you must provide additional JDBC drivers.

12

CHAPTER 1 Understanding AI for Stored Procedures

e to

s.

uar,

ries:

ugh

AI for Stored Procedures ArchitectureAI 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 usinvoke the target stored procedures from Jaguar

Figure 1-1 shows the design-time architecture of AI for Stored Procedure

Figure 1-1: AI for Stored Procedures design-time architecture

During design time, the Component Builder imports the stored proceduremetadata, 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 Jagwhich in turn accesses the target stored procedure.

Supported ProceduresAI for Stored Procedures supports the following stored procedures and que

• Database stored procedures (for any database that is accessible throJDBC)

• Database SQL commands (for example, select, insert, execute, update, delete)

13

What Is AI for Stored Procedures?

red

• DirectConnect Remote Stored Procedures (RSPs)

• Open ServerConnect language events and Remote Procedure Calls (RPCs)

Note This documentation refers to all supported procedures as “target stoprocedures.”

14


o

te

oad led”

hem easily

Why Use AI for Stored Procedures?To understand how AI for Stored Procedures can provide solutions for business problems, consider the following scenario.

ProblemA 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 tcustomers over the Internet.

• The company cannot afford to rewrite all the applications or consolidaall 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 brInternet accessibility), but none of the existing systems are “Web-enabtoday.

SolutionFor its solution, the company uses Sybase Enterprise Application Server (EAServer) as a platform to integrate their internal applications and make taccessible through the Internet. Using AI for Stored Procedures, they canaccess the business logic in their database stored procedures quickly andfrom the Jaguar middle tier for new application development.

15

Jaguar and AI for Stored Procedures Functionality

1- or

by that

the

rs as

est to

ent.

Jaguar and AI for Stored Procedures FunctionalityThe 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 WorksJaguar implements a “multi-tier” distributed computing architecture. Figure3 shows the typical Jaguar environment, in which three distinct elements,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 the middle-tier developer. They contain the executable business logichandles much of the application processing.

• The back-end database, which is the transaction target accessed by Jaguar component. It stores, manages, and processes data.

Figure 1-3: Typical Jaguar environment

In most cases, interaction between the client application and Jaguar occufollows:

1 When a client application needs to use a component, it issues a requthe Jaguar server.

2 The request from the client prompts Jaguar to instantiate the compon

3 The client invokes a method on a component.

16


ods r

the AI

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 ComponentsIn 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 meththat provide direct access to a target stored procedure. No middle-tiecoding 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 for Stored Procedures component in the middle tier.

Figure 1-4: AI for Stored Procedures environment

17

Basic Steps for Building a Component

task

with

Basic Steps for Building a ComponentThere 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 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 ProcedureYou must research the stored procedure you plan to use to become familiarhow it is defined and how it works.

18


uar, nent

ed r to

ar

Step 2: Create the ComponentIn 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 ComponentWhen you deploy the component, the Component Builder defines it in Jagand creates Java classes that implement the component. After the compois deployed, it is ready to run.

Step 4: Use the ComponentOnce a component is deployed, you can use it in applications. AI for StorProcedures components can be used to build Jaguar client applications obuild other Jaguar components.

Note For information on how to build your client application, see the Jagudocumentation.

19

Using the AI for Stored Procedures Tutorials

Using the AI for Stored Procedures TutorialsSybase 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

re.

nline p

C H A P T E 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 softwaThese samples include tutorials designed to help you learn to use theComponent Builder to create components and connections. See the odocumentation in the Sybase\Application Integrator 3.0 program groufor information on running the tutorials.

21

Working with the Component Builder

e se

an

ts and

Working with the Component BuilderThe 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 BuilderTo 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 havinstalled. The AI Component Builders appear in the tree view in the SybaCentral window.

Working with Project FilesProject files provide a way to store component and connection definitionscreated with the Component Builder. Project files store information about logically related components. For example, you can group all componentscreated for a specific department into a single project file, such as a HumResources or Payroll file. Or, if you are creating components from stored procedures that reside on different databases, you can save all componenconnections 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

iew roject e +

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 NewProject.

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. Theseobjects are displayed hierarchically in the Sybase Central tree view. You vthe contents of a project by expanding the objects that appear beneath a pin the tree view. To expand an object in the tree, you can either left-click thbutton that appears next to the object, or double-click the object.

The following figure shows a project named asademo in the Component Builder.

23

Working with the Component Builder

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


tion more

ith with

ating ing ild in

in

der:

Understanding AI ConnectionsAn 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 ConnecCaches in Jaguar Manager” on page 46 and the Jaguar documentation forinformation.

You use the Component Builder to define connections, associate them wcomponents, and deploy them to Jaguar. Every component is associatedexactly one connection.

All connectivity in AI for Stored Procedures uses JDBC. The Component Builder uses JDBC to test connections and to browse databases when crecomponent methods. At run time, Application Integrator components runnin Jaguar use JDBC to invoke stored procedures. The connections you buthe Component Builder are JDBC connections.


• Defining Connection Properties

• Registering JDBC Drivers

• Testing Connections

• Connection Caching

Defining Connection PropertiesWhen you create a connection, you must supply the following informationthe Component Builder:

• The type of connection you want to create.

The following connection types are supported in the zComponent Buil

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

tored

and

and ers.

d

ct,

ers.

it to ns

ilder that the

• Properties needed to connect to the database containing the target sprocedure.

These properties differ for each target but often include a host name 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 does not require you to know the URL format for supported JDBC driv

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 storeprocedure.

Registering JDBC DriversApplication Integrator and Jaguar include the Sybase JDBC driver jConnewhich you can use to create connections to Sybase servers. For other connection types, such as Oracle, you must provide additional JDBC driv

You also must register each non-Sybase JDBC driver with the Component Builder before you create connections that use it. To register a driver, addthe JDBC Driver Class Path that appears in the Component Builder Optiodialog box.

The JDBC Driver Class Path is a Java class path that the Component Buuses to locate JDBC drivers. It can include jar files, zip files, or directories contain JDBC drivers you are using with the Component Builder. Entries inclass path are separated by semi-colons.

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

Connection type Description

26


ord,

ach

g use

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 ConnectionsThe 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 passwwere 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 econnection type.

Connection CachingApplication Integrator components do not use Jaguar’s connection cachinfeature at run time by default; however, components can be configured tothe connection caching feature in Jaguar. See Chapter 3, “Jaguar and Application Issues” for details.

27

Understanding AI Components

s can ingle

o

r ” on

u can t

in

Understanding AI ComponentsAI 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 methodinvoke. All stored procedures exposed in a component must reside on a sserver.

The Component Builder allows you to create components, add methods tcomponents, and deploy components to Jaguar.

You can add methods to components either manually or automatically. Fomore information, see the section in this chapter called “Creating Methodspage 29.

Once you have created a component and added one or more methods, yodeploy the component to Jaguar, where it is ready to used by Jaguar clienapplications 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 PropertiesWhen you create a component, you must supply the following informationthe 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


nent’s e

s to e and

rn ure.

Creating MethodsEach 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 andmanual method creation.

Creating Methods Automatically

When the Component Builder accesses the database through the compoconnection, it allows you to create a method automatically. You browse thdatabase and select a stored procedure that the method will invoke.

When you create methods automatically, the Component Builder attemptretrieve information about the stored procedure you select, such as its namits parameters. The Component Builder retrieves information for each parameter including the parameter mode, datatype, whether it has a retuvalue, and whether it can accept a NULL value. The Component Builder thenuses this information to create a method that will invoke the stored proced

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.

Property Description

29


st he

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 thefollowing:

• 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 targetstored procedure, so that you can enter this information correctly. The moaccurate source for this information is the source code (usually SQL) for tstored procedure.

30


Method PropertiesFor 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

Information about the method definition as it will appear in Jaguar.

Method name

Name of the method.

Description

Method description (optional).

Parameters:

Name Parameter name.

Mode Parameter mode. in, out, or inout.

Type Jaguar datatype for the parameter.

See “Mapping Stored Procedures to Methods” on page 34 for mappings between Jaguar types, IDL types, and JDBC types.

31


Target

Information about the target stored procedure

Catalog JDBC catalog. For Sybase, the procedure’s database.

Schema JDBC schema. For Sybase, the procedure’s owner.

Procedure

Procedure name.

Catalog Separator

Delimiter for portions of the fully qualified stored procedure name.

Default value is a period (.).

String Delimiter

Default value is a single quotation mark (‘).

Not used for callable or prepared statements.

Statement Type

Valid values are Statement, Prepared, and Callable.

See “Statement Templates” on page 33 for more information.

Result Sets

Indicates whether the procedure returns result sets.

Valid values are 0, 1, and Variable (0, 1, or many).

Parameters:

Name Parameter name.

Mode Parameter input or output mode.

Valid values are in, out, or inout.

JDBC Type

Parameter JDBC datatype.

See Table 2-6 on page 36 for details.

Precision For character datatypes, typically the maximum number of characters for the parameter.

For other datatypes, typically the number of bytes in the parameter value.

See Table 2-6 on page 36 for details.

Tab Field Description Comments

32


d ided d can

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 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, andefined parameters. You can edit the template in any way you prefer, provthat the server can understand its syntax. Parameters defined to a methobe substituted at run time by referring to them in the template as {parameter_name}. {parameter_name} is the name of one of the parametersdefined 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.

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.

33


a first

res

sets

Mapping Stored Procedures to MethodsThis 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 derivesname for the method from the name of the target stored procedure, with thecharacter in upper case and the subsequent characters in lower case.

Note If necessary, the Component Builder removes spaces and underscofrom 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 are mapped in Jaguar:

Table 2-5: Result sets and method return value

Parameter Information


• Parameter Names

• Parameter Modes

• Stored Procedure Return Values

Number of result sets Jaguar IDL mapping

0 void

1 TabularResults::ResultSet

More than 1 TabularResults::ResultSets

34


ter is r is s are ames the

tput,

rs is , you

ave k the

erty

in the

r IDL g

• Parameter Datatypes

• Parameters with NULL Values

Parameter Names

For each method in an AI for Stored Procedures component, each parameeither automatically derived from the server using JDBC metadata calls omanually defined in the Component Builder. If the names of the parameternot valid parameter names, the Component Builder alters the parameter nto conform to Jaguar restrictions. You can also alter parameter names in Component Builder.

Parameter Modes

The parameter mode refers to whether the parameter is used for input, ouor 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 parameteadded as a parameter for that method. If you manually define a componentmust 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 ha return value, an output parameter should be added to the method. ChecReturn Value check box for that parameter.

Note The Component Builder may have already set the Return Value propfor the parameter correctly if you created the method automatically.

The return value for a stored procedure is mapped as an output parametermethod.

Parameter Datatypes

This section describes mapping that occurs from parameter types to Jaguadatatypes. The datatype for each field is either automatically derived usinJDBC 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

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.

SQL Datatype Java DatatypeJaguar IDL 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

36


ters

alled

set

ters

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 paramein 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 ca 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 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 parameto determine whether the output value is NULL. At run time, the client application can set the null indicator to true to indicate that the parameterhas a NULL value.

37

Understanding AI Component Deployment

e

er

tion

Understanding AI Component DeploymentOnce 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 WizardThe 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 thJaguar java\classes directory

• Compiles the Java source code for the component on the Jaguar serv

When you deploy a component into Jaguar, you must provide the informadescribed in the following table:

Table 2-7: Information needed by the Deploy Components wizard

Wizard dialog box Field Description

Jaguar connection information

User Name Valid Jaguar user ID.

Password Valid password for Jaguar user ID.

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


s not

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 JaguarEach 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 doealready exist)

• A Jaguar component definition

• An IDL module (modified, if it already exists)

Jaguar package information

Package Name The package name currently selected for this component. Enter a new name, accept the selected name, or select a different name from the Existing Packages field.

Existing Packages

The list of package names currently available. Click a package name to select the package.

Note Jaguar system packages (such as CosNaming) are not displayed.

Wizard dialog box Field Description

39

Understanding AI Component Deployment

new

ing

n

r of al hing.

ager.

hich

edit nt

• 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 component to the existing package.

• If the module already exists, the IDL interface is added to the existmodule.

2 The Application Integrator deployment feature creates implementatiofiles 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 Jaguarepository. Application Integrator components also include a collectionuser-defined Jaguar properties, which allow you to configure additionproperties for the component, such as debugging and connection cac

If the properties need to be changed, you can edit them in Jaguar ManSee Chapter 3, “Jaguar and Application Issues” for details.

Understanding Deployed Connections in JaguarWhen 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, wis 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 the connection in the Component Builder, and then redeploy the componeand connection.

40

rize

C H A P T E 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 familiayourself 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

ator pool

ne

t of a ts to yed

can open

AI Components in JaguarWhen 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 theirarguments) is described using CORBA IDL.

Application Integrator components are designed to take advantage of theJaguar instance pooling feature. This section covers the following topics:

• Instance Creation

• Instance Activation

• Method Invocation

• Instance Deactivation

• Instance Destruction

Instance CreationWhen a client executes methods on a proxy object for an Application Integrcomponent, Jaguar creates a new instance of a component if the instancedoes not contain any instances available for reuse. If an unused instancealready exists in the pool, Jaguar can initialize that instance by calling theactivate method and allowing a client application to call a method on the component. During component instantiation, a one-time initialization routiretrieves component property information.

Instance ActivationJaguar activates an Application Integrator component instance as a resulclient method invocation request. When activated, the component attempconnect to its target server using the connection properties that you deploalong with the component. Depending on its configuration, the componentobtain its connection from a connection cache defined in Jaguar, or it can a connection directly to the server.

42

CHAPTER 3 Jaguar and Application Issues

utes, call,

it no its

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 InvocationThe method’s input parameters (parameters defined with the modes in or inout) are passed to the target stored procedure. After the procedure execany result sets are returned to the caller as the return value of the methodand any output parameters (parameters defined as inout or out) are returned to the caller.

Instance DeactivationJaguar deactivates each Application Integrator component instance whenlonger needs to keep that instance associated with the client that causedactivation. During instance deactivation, the connection that was obtainedduring instance activation is returned to the pool.

Instance DestructionJaguar 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

e n

er

om

alid

Connections and Connection CachingThis 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 SecurityWhen the Component Builder deploys a component into Jaguar, it sets thfollowing properties for the component. These properties affect connectiohandling and security:

com.sybase.ai.connection.name

This property is referred to as connection_name. It specifies the name of the connection associated with the component.

com.sybase.ai.use_client_security

This property is referred to as use_client_security. It affects the user ID and password that are used to obtain connections. Valid values are:

• false

A value of false tells the Application Integrator component to use the usID and password that were supplied in the connection object from theComponent Builder. The default value is false.

• true

A value of true tells the component to use the user ID and password frthe 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_connection_cache

This property is referred to as use_connection_cache. It specifies how the Application Integrator component acquires and disposes of connections. Vvalues are:

• false

A value of false tells the Application Integrator component to open andclose connections to a server directly. The default value is false.

44


a

tions for

n The

will

es is d can

on tion

on r ith

er ew hese

• true

A value of true tells the component to get and release connections fromJaguar connection cache.

com.sybase.ai.connection_cache_unavail_action

This property controls the action that Jaguar takes if there are no connecavailable in the cache. The valid values correspond to the possible valuesthe 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 aexception (error condition) that is then propagated back to the caller. default is nowait.

• force

Indicates that Jaguar should attempt to open a new connection (that not be placed back in the cache after use).

• wait

Indicates that the component waits indefinitely until a connection becomavailable. We do not recommend that you use this option because thindefinite wait can cause component instances to tie up resources ancause the client application to wait indefinitely.

Acquiring and Disposing of ConnectionsThe process of acquiring and disposing of connections differs dependingwhether the Application Integrator component is configured to use conneccaching.

When Not Using Connection Caching

• Acquiring connections refers to the process of opening a new connectidirectly to the target server. The values supplied to the JDBC driver foconnecting to the server are retrieved from the connection definition wthe name matching the connection_name property. These values include such information as the JDBC driver class name, connection URL, usID, password, and JDBC driver-specific properties. When opening a nconnection to a server, the Application Integrator component passes tvalues to the JDBC driver.

• Disposing of connections refers to closing connections.

45


by

lar A can

e to

ect

e is

e

to on to

ires

itions.

When Using Connection Caching

• Acquiring connections refers to the process of retrieving a connectionfrom 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 cachename.

• Disposing of connections refers to releasing a connection back to the Jaguar connection cache for other components to use.

Defining Connection Caches in Jaguar ManagerDefining connection caches for Application Integrator components is simito defining them for other components that use JDBC connection caches.connection cache that is defined for an Application Integrator component be shared with other non-Application Integrator components.

You must set up connection cache definitions in Jaguar Manager using thfollowing procedure. In general, use the same information that was used create the connection in the Component Builder. To define a connection cache:

1 On the Driver tab of the Connection Cache Properties dialog box, selthe 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 namcom.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 (se“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 (it is off by default). This allows the Application Integrator component look up connection caches by name.

Note Setting the Jaguar Enable cache-by-name access property requJaguar administrator authority.

5 Restart the Jaguar server to effect changes to connection cache defin

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 ComponentsIn 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

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

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_ unavail_action

Jaguar Manager

com.sybase.ai.use_client_security Jaguar Manager

com.sybase.ai.debug Jaguar Manager

47


e

e

ged,

e

• 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. Thproperty can have a value of true to indicate that the component should writetrace information to the Jaguar server log. A value of false (the default) indicates that the component should not writinformation to the log.

Warning! Turning on debugging can cause large amounts of data to be logwhich can adversely affect performance.

In general, the information produced by this logging is intended for SybasTechnical 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


tput

Client Application DevelopmentIf 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 ouparameters.)

49

Client Application Development

rned ts as

thod

a thod

as a

text

• The return type of the method is based on whether result sets are retufrom the procedure. The number of result sets maps to IDL statemenfollows:

• If the target stored procedure has a return value, it appears in the mesignature as an output parameter.

• Parameters declared as nullable cause Application Integrator to add parameter (with the same mode as the nullable parameter) to the meto communicate whether the corresponding parameter contains a NULL value.

• Exceptions caught by the component are propagated to the client stubuser-defined exception type of AIUserException. These exceptions contain a single field called Message that contains the error messagefor the exception.

Number of result sets IDL mapping

0 void

1 TabularResults::ResultSet

More than 1 TabularResults::ResultSets

50

lly nds and

A P P E N D I 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 theComponent Builder or requires a third-party JDBC driver.

• The type of connection that should be created in the ComponentBuilder for the target.

• Parameters needed to create connections for the target.

• Whether methods can be created from the target and automaticaadded to the component or must be created manually. This depeon the level of procedure metadata supported by the JDBC drivertarget 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

of the

Sybase TargetsAll 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 AnywhereComponents that invoke Sybase Adaptive Server Anywhere (ASA) storedprocedures 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

:

For Sybase ASA, methods can be created automatically and can use any following statement types:

• Callable Statement

• Prepared Statement

• Statement

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.

52

APPENDIX A Target Types

ccept for

urces.

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 EnterpriseComponents 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

:

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 anull values when methods are created automatically. Method parametersASE stored procedures are set to not nullable by default.

DirectConnectSybase DirectConnect gateways provide access to heterogeneous data soThis section includes information on creating Application Integrator components that access procedures through DirectConnect.


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.

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

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.


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.

54


:

g

s, nent

eate

CI acle

Oracle TargetsThis 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 drivercalled 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 ComponentBuilder is running

• Install the Oracle JDBC driver on the machine where Jaguar is runnin

• Register the JDBC driver with the Component Builder

To do this, right-click the Stored Proc Component Builder, click Optionand enter the class path for the Oracle driver in the Stored Proc CompoBuilder Options window.

After you have installed and registered the Oracle JDBC driver, you can crconnections for Oracle in the Component Builder.

Oracle OCIThe Oracle OCI connection type is used for connections to Oracle that use Onetworking. For these connections, the Oracle JDBC driver connects to Orusing 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

I. ava

any

For Oracle OCI, you can create methods automatically. Methods can use any of the following statement types:



• Statement

Oracle ThinThe Oracle Thin type is used for connections to Oracle that do not use OCFor Oracle Thin connections, the Oracle JDBC driver functions like a pure JType IV JDBC driver.

The following values are needed to create a connection

Table A-5: Oracle Thin connection information

:

For Oracle Thin, you can create methods automatically. Methods can useof the following statement types:



• Statement

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





Host Name Name of the machine where Oracle is running

Port Number Port number Oracle is listening on

SID Oracle system identifier



56


JDBC-ODBC Bridge TargetsThe 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

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.


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.

57

Generic Targets

is

s,

nds

o for ions

C

Generic TargetsThe 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 Builderrunning

• 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 Optionand 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

For generic connections, the ability to create methods automatically depeon whether the JDBC driver supports metadata calls. The best way to determine whether methods can be created automatically is to try doing sseveral stored procedures, and verify whether the resulting method definitare correct.

Support for different statement types also depends on the underlying JDBdriver and database. See the documentation for the JDBC driver for information about supported driver types.


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.

58


About JDBC URLsA 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

and r

jects tifier. nd

, e of

o all

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 appletcannot access the file system of the client upon which it is executing;the applet’s communication across the network is limited to the servefrom 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 obassociated with a particular schema name and user authorization idenThe objects include tables, views, domains, constraints, assertions, aprivileges.

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 thereforecommon properties, operations and behavior. An object is an instanca class.

code page An assignment of graphic characters and control function meanings tcode points.

code set The characters in a code page.

61

guar eturn

rom

er

and

COMMAREA Common communications area where mainframe application logic and presentation logic that are stored in separate regions can communicate with each other.

Common Object Request Broker Architecture (CORBA)

A specification produced by the Object Management Group (OMG) that presents standards for various types of object request brokers. Implementation 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. Jacomponents typically execute business logic, access data sources, and rresults 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 fcomponent and connection information.

connection A network between two systems:

• For SNA, the path connects an LU on one machine to an LU on anothmachine.

• 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 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 Language (IDL)

In CORBA, a declarative language that is used to describe object interfaces 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 Connectivity (JDBC)

An application programming interface that has the same characteristics as 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 (JVM)

An execution time environment for running Java programs. JVMs may be 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 broker (ORB)

In object-oriented programming, software that serves as an intermediary by transparently enabling objects to exchange requests and responses.

Open Database Connectivity (ODBC)

Standard application programming (API) interface for accessing data in both 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 reports

Sybase publications that certify third-party query and development tools to 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 procedure (RSP)

A customer-written CICS program that resides on the mainframe and 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 Architecture (SNA)

A network plan for transmitting information units through networks and 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 Control Protocol (TCP)

A communications protocol used in the Internet. TCP uses Internet Protocol (IP) as the underlying protocol.

Transaction Router Service (TRS)

DirectConnect program that accepts requests from workstation-based clients 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

AAccessing stored procedure metadata 19Acquiring connections

in Jaguar 45Activation

of instances 42Adapter 39Adaptive Server Anywhere

and Sybase Central 22EAServer component 12

Adaptive Server Anywhere. See ASA 12Adaptive Server Enterprise. See ASE 12Administrator

Jaguar authority required 46AI components. See Components 16AI for Stored Procedures

architecture 13description 12steps in development process 18

Application development process 18Application Integrator

deployment feature 40installing deployment feature 39

Applicationscode 17developing 49, 50

ASAaccess using JDBC driver 12connections 52

ASEaccess using JDBC driver 12connections 53

AuthorizationJaguar administrator 46

Automaticmethod creation 29, 58

Automatic method creation 19

Ccache_unavail_action

Jaguar property 45Caching

connection 27Callable Statement

statement type 33Calling conventions 33Catalog

method property 32Catalog separator

method property 32Changing connection information 40Characteristics of AI components in Jaguar 49Class name

JDBC driver 46Class path

JDBC driver 26Classes

Java 13Client applications 16, 17

developing 49, 50interaction with Jaguar 16

Closing project files 23com.sybase.ai

AI component properties in Jaguar 47Component Builder

description 12, 13Options dialog box 26starting 22tasks performed using 22using 22

Component propertiescomponent name 28connection name 29in Jaguar 47Java package name 29

Componentscharacteristics in Jaguar 49characteristics of deployed components in Jaguar

39contents 17defining properties in Component Builder 28definition 28deploying 38deploying in Jaguar 40description 12execution debugging 48in Jaguar 42middle tier in Jaguar 16name property 28properties in Jaguar 47

67

Index

refreshing in Jaguar Manager 43, 47relationship to connections 25, 28

Computecreating default statement template 33

Connection caches 40and acquiring and disposing of connections in Jaguar

45and AI components 27defining in Jaguar 46installed in running Jaguar server 47procedure for defining in Jaguar 46using Jaguar 25

Connection failuretypical causes 27

Connection typesgeneric 58, 59JDBC-ODBC Bridge 57Oracle 55, 56Oracle OCI 55Oracle Thin 56supported in Component Builder 25Sybase 52, 54Sybase ASA 52Sybase ASE 53Sybase DirectConnect 53

connection_nameJaguar property 44

Connectionsacquiring in Jaguar 45and JDBC URLs 26at design time 25at run time 25defining properties in Component Builder 25definition 25deployed in Jaguar 40deploying 40disposing of in Jaguar 45editing information 40Jaguar 38JDBC 25name property 29relationship to components 28serialized file in Jaguar 40specifying properties in URL 47testing 25testing in Component Builder 27

68

types supported in Component Builder 25CORBA IDL 42Creating

component methods 25components 18, 19connections 19Jaguar client applications 19Jaguar components 19new projects 23statement templates 33

Creating methods 29automatically 19, 29, 58manually 19, 30manually, importance of understanding stored

procedures when 30Creation

of instances 42

DDatabase

ASA access 12ASE access 12commands 13Oracle access 12stored procedures 13transaction target 16

Datatypesconversion 39Jaguar 31, 36Java 36JDBC 30parameter 29SQL 36third-party DBMS 36

Deactivationof instances 43

Debuggingcomponent execution 48

Decimal datatypesJDBC 30

Definingconnection caches in Jaguar 46connection properties in Component Builder 25Jaguar connection caches 46

Index

parameter modes 35Deployed components

in Jaguar 40Deploying

components 19, 38, 39connections 19, 40

Deploymentconnections in Jaguar 40feature 40feature installation 39

Deployment Progress window 39Deployment Wizard

understanding 38Description

method property 31Design time

AI for Stored Procedures architecture 13Component Builder process 13connections 25

Destructionof instances 43

Details viewin Sybase Central 24

Developing client applications 49, 50Development process 18DirectConnect

connections 53RSPs 13

Disposing of connectionsin Jaguar 45

DLLJDBC driver class name 46

Documentationreferences to supported procedures 14

Domain name formatand Java package names 29

DriversOracle 55registering JDBC with Component Builder 26,

55, 58specifying connection properties 47third-party JDBC 57, 58

EEAServer 15

components 12Editing

connection information 40method definitions 30parameter names 35

Enable cache-by-name access propertyauthority 46setting 46

Enterprise Application Server. See EAServer 15Errors

handling 39nonrecoverable 43troubleshooting using Deployment Progress window

contents 39troubleshooting using Details view in Sybase Central

30Exception handling 50

FFailure

typical causes of connection 27Files

implementation 40jar 26project 22serialized in Jaguar 40zip 26

GGeneric connection type 58, 59

IIDL

CORBA 42module 40viewing interface 37

IIOP port 38Implementation files

69

Index

location 40Installation

Jaguar directory 40third-party JDBC drivers 58

Instanceactivation in Jaguar 42creation in Jaguar 42deactivation in Jaguar 43destruction in Jaguar 43pooling in Jaguar 42

Instructiontutorials 20

Interfaceview in Sybase Central 24viewing IDL 37

Invocationof methods 43

JJaguar

and AI components 42and Sybase Central 22authority required for setting Enable cache-by-name

access property 46component definition and deployed component 39component properties 44component repository 47connection caching 25connection caching and AI components 27connection information in Deployment Wizard 38datatype property 31defining connection caches 46deployed components in 39deployed connections 40EAServer component 12functionality 16installation directory 40instance pooling 42Jaguar and Java package names 29mapping IDL datatypes to parameter types 35mapping Jaguar datatypes to SQL and Java datatypes

36MASP feature 43method name restrictions 34

70

package ame information in Deployment Wizard 39

packages 40packages and deployed component 39procedure for defining connection caches 46repository 40setting component properties 40

Jaguar Component Transaction Server (CTS). See Jaguar 11

Jaguar propertiescache_unavail_action 45connection_name 44use_client_security 44use_connection_cache 44

Jar files 26Java

classes 13mapping Java datatypes to Jaguar datatypes 36mapping Java datatypes to SQL datatypes 36package name component property 29package name for stubs generated for AI components

49package name format 29Type IV JDBC driver 56

Java Database Connectivity. See JDBC 12JCMCache.getConnection() method 45jConnect 12

class name 46JDBC

connections 25datatype method property 30decimal datatypes 30entering URLs 58numeric datatypes 30parameter datatypes 30statement type support 33URL and Generic connection type 59URL definition 59URL derived from connection properties 26

JDBC driversaccessing stored procedure metadata 19, 29class name 46class path 26Java Type IV 56mapping target datatypes to SQL datatypes 36metadata support 58

Index

Oracle 55registering with Component Builder 26, 55, 58specifying connection properties 47third-party 57, 58used to access stored procedures 12

JDBC typemethod property 30, 32

JDBC-ODBC Bridge connection type 57

LLanguage events

Open ServerConnect 14

MManual method creation 19, 30Mapping

parameter datatypes to Jaguar datatypes 35stored procedure return values to parameters 34stored procedures to methods 34

MASPJaguar feature 43

Messagesviewing in Sybase Central 30warning when creating methods 30

Metadataaccessing stored procedure 29stored procedure 19support in JDBC driver 58

Method nameproperty 31

Method ropertiesGeneral 31target 32

Methodscreating 25, 29creating automatically 19, 29, 58creating manually 19, 30editing definitions 30invoking 43JCMCache.getConnection() 45mapping parameters to stored procedure return

values 34

mapping to stored procedures 34name restrictions 34names 31names, mapping to stored procedure names 34null values in parameters 37parameter information 29parameter names 30properties 31relationship to stored procedures 28return value relationship to result sets 34warning messages when creating 30

Middle-tier componentsin Jaguar 16

Modesparameter 30, 35

ModulesIDL 40

Multi-tier computing environmentJaguar architecture 16

NNames

parameter 35target stored procedure 30

Nonrecoverable errors 43Non-Sybase database access 12Non-Sybase JDBC drivers

registering with Component Builder 26requirement for installing on Jaguar server 27

Null indicator parameter 37Null values

in method parameters 37in parameters 29parameters 30

Numeric datatypesJDBC 30

OOCI networking

connections to Oracle 55Online documentation

location 20

71

Index

Open ServerConnectlanguage events 14

Opening project files 23Oracle

connection types 55, 56JDBC driver 55Oracle OCI connection type 55Oracle Thin connection type 56

Output parametersand return values 35

PPackage name

Jaguar 39Java 29, 49relationship of Java to Jaguar 29

PackagesJaguar 40Java 49

Parameter mode 29, 30, 35method property 31, 32

Parameter names 35method property 31, 32

Parameter typemethod property 31

Parametersand null values 37in statement templates 33information for methods 29mapping datatypes to Jaguar IDL datatypes 35mapping to stored procedures 34

Performanceand callable statement type 33

PortsIIOP 38

PowerDynamoEAServer component 12

Precisionmethod property 32

Prepared Statementstatement type 33

Proceduresname property 32supported types 13

72

Process flowAI for Stored Procedures component development

18Project files

closing 23creating 23extension 22opening 23saving 24viewing 23, 24

Projectscreating new 23

Propertiescomponent 28Jaguar component 40, 47method 31

Protocolin JDBC URL 59

RRefreshing components

in Jaguar Manager 43, 47Registering JDBC drivers with Component Builder

26, 55, 58Relationship of methods and components 29Remote Procedure Calls. See RPCs 14Remote Stored Procedures. See RSPs 13Repository

Jaguar 40Jaguar component 47

Researchstored procedure contents 18

Restrictionsmethod names in Jaguar 34on content of statement template 33stored procedures in components 28

Result setsmethod property 32relationship to method return value 34returned by target stored procedure 30

Return values 29relationship to result sets 34stored procedure 35target stored procedure 30

Index

RPCssupport for Open ServerConnect 14

RSPssupport for DirectConnect 13

Run timeAI for Stored Procedures architecture 13and instance destruction 43and Jaguar security 44and scale parameter property 32and setting null indicators in client applications

37and statement types 33clients invoking components in Jaguar 13components and Jaguar connection caching 27connections 25requirements for installing non-Sybase JDBC

drivers 27substituting method parameters in statement

templates 33using JDBC to invoke stored procedures 25

SSamples

online location 20Saving project files 24Scale

method property 32parameters 30

Schemamethod property 32

Security 39Jaguar component properties 44

Serialized file 40Server name

Jaguar property and URL 46Skills

required in AI development process 18Specifying driver connection properties 47SQL

commands 13mapping SQL datatypes to Java datatypes 36

Starting the Component Builder 22Statement

statement type 33

Statement templatesand statement types 33computing 33creating 33parameters in 33restrictions on content 33

Statement types 33Callable Statement 33method property 32Prepared Statement 33Statement 33support in JDBC drivers and databases 58

Stored proceduresaccessing metadata 19, 29mapping to methods 34names, mapping to method names 34references in documentation 14relationship to methods 28supported types 13understanding 18

Stored Procedures Adapterdefinition 39

Stored Procedures Component Builderusing 22

String Delimitermethod property 32

Subprotocolin JDBC URL 59

Sun JDBC-ODBC bridge driver 57Supported connection types 25

generic 58JDBC-ODBC bridge 57Oracle 55Sybase 52

Supported procedure types 13Sybase

ASA connections 52ASE connections 53connection types 52, 54DirectConnect connections 53jConnect driver class name 46

Sybase Central 22

73

Index

TTarget stored procedures

accessed by AI components 17name 30references in documentation 14supported procedure types 13

Targetsdefinition 51generic 58JDBC-ODBC Bridge 57Oracle 55, 56Oracle OCI 55Oracle Thin 56Sybase 52, 54Sybase ASA 52Sybase ASE 53Sybase DirectConnect 53

Templatescreating 33statements and statement types 33

Testing connections 25after registering drivers with Component Builder 27in Component Builder 27

Third-partyDBMS datatypes 36JDBC drivers 57, 58

Transaction control 39Troubleshooting

debugging 48using Deployment Progress window contents 39using Details view in Sybase Central 30

Tutorialsonline location 20

UUnderstanding stored procedure functionality when creating

methods manually 30URLs

connection properties in 47JDBC 26, 59

use_client_securityJaguar property 44

use_connection_cacheJaguar property 44

74

User scenario 15Using AI components

in applications 19setting the null indicator value 37

Using Jaguar connection caching 25Using the Component Builder 22

VViewing

IDL interface 37messages in Sybase Central 30project files 23, 24

WWarning messages

when creating methods 30Working with project files 22

ZZip files 26

Date post:	22-Apr-2020
Category:	Documents
Upload:	others
View:	11 times
Download:	0 times

Application IntegratorSybase provides the following Application Integrator documentation: •...

Documents