adadb userguide

TIBCO Adapter™ for ActiveDatabase

User’s GuideSoftware Release 5.1.0November 2003

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THIS MANUAL). USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIB, TIBCO, Information Bus, The Power of Now, TIBCO ActiveEnterprise, TIBCO Adapter, TIBCO Administrator, TIBCO Designer, TIBCO Hawk, TIBCO IntegrationManager, TIBCO Rendezvous, and TIBCO Runtime Agent are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

EJB, J2EE, JMS and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

PORTIONS OF THIS SOFTWARE ARE COPYRIGHTED BY DATADIRECT TECHNOLOGIES, 1991-2002.

Copyright © 1999-2003 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

| iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviTIBCO Adapter for ActiveDatabase Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Publication and Subscription Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Message Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6TIBCO Rendezvous Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6TIBCO Enterprise for JMS Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Adapter Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Run-time Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8TIBCO Runtime Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Polling or Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Referencing External Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Loop Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Master-Master Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Multi-file Format Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12DAT File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Supported SQL Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Publication Service Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Publish by Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Publish by Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Update Feature for Parent-Child Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Changing a Publication Subject Without Using TIBCO Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

TIBCO Adapter for ActiveDatabase User’s Guide

iv | Contents

Checking for Duplicate Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Message Logging Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Timely Processing of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Required Platform and Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Create the Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Configure the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Start the Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Change the Table Values and Receive Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Exit the Query Tool and Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Clean Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 3 Adapter Instance Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Saving the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Testing the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Notes on Configuring an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Configuration Recommendations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Changing an Existing Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Using Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Design-time Connection Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Using Connection Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Saving Connection Parameters for Reuse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Using Saved Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Run-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Adapter Services Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Logging Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Startup Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Monitoring Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63


Contents | v

Chapter 4 Adapter Service Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Quality of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Delivery Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Wire Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Publication Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Tables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Adding Child Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73DB2/OS390 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Publisher Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Subscription Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Table Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Child Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Subscriber Options for DB2 on OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Subscriber Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Request-Response Service Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Call Operation Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator Enterprise Edition . 97

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Create an EAR File in TIBCO Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Deploy the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Monitor the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 6 Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition. 105

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Export the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Create a Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Set Properties in Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Assign Security Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111


vi | Contents

Start the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Monitor the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Adapter Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Properties File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Run-time Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Obfuscating or Encrypting a Password in the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Project Locator String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Server-based Project Locator String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Local Project Locator String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Installing the Adapter as a Service on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Creating Multiple Services for the Same Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Chapter 7 Using an Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Setting Up and Starting the Alerter on Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Oracle Alerter Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Oracle Alerter Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Setting Up and Starting the Alerter on Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Alerter Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Setting Up and Starting the Alerter on Sybase SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Alerter Setup on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Alerter Setup on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Chapter 8 Using the Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Request-Response Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146TIBCO ActiveEnterprise or XML Message Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147TIBCO Rendezvous Message Request Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147TIBCO ActiveEnterprise or XML Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150TIBCO Rendezvous Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

RPC Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Standard RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Custom RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Implementing Client RPC Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164


Contents | vii

Load Balancing in a Single Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Load Balancing Across Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Oracle REF Data Type Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Chapter 9 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Publishing Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Removing Records from the Publication Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Stored Procedures and Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Publication Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Changing the Publication Trigger to Publish a Subset of Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Source Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Using an Exception Table as a Source Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Incremental Parent-child Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182DB2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Mapping to Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Subject Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Parameterized Subject Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Preregistering a Certified Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Changing the Location of the Ledger File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Sending Messages to an Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190adbDateTime Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Publishing by Reference Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Changing Repository Objects for Parent-Child Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Table to Record Sequence Numbers (DB2 on AS/400) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

User Callout Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Using the alterMsgPub and alterMsgSub Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Using the adbPreCommit Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Building the Callout Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Unique Connection Identifier for Oracle Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Publishing in a Commitment Controlled Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Using the Adapter with a Revision Control System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Using a Log File for an Adapter Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Fine-Tuning Tracing Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Log File Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213


viii | Contents

Using Advanced Logging Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Using Database Cleanup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Change the SQL Statement Terminator (DB2/OS390 Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Chapter 10 Setting Encoding Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Setting TIBCO Messaging Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Configuring the Adapter to Communicate with the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Configuring the Adapter at Design-time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Special Configurations for Supporting a UTF-8 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Run-time Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Relevant Environment Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Chapter 11 Monitoring the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Starting TIBCO Hawk Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

The Auto-Discovery Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Invoking Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Available Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238activateTraceRole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242deactivateTraceRole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243getAdapterServiceInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244getComponents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getConfigProperties(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247getHostInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248getRvConfig(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249getStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250getTraceSinks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251getVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252_onUnsolictedMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253preRegisterListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254reviewLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255setTraceSinks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256stopApplicationInstance(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257unRegisterListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258getEventQueueSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259setDebugLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260toggleVerboseFlag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261showConfiguration(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262terminateADBagent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263


Contents | ix

getPollingInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264setPollingInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265getPollingBatchSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266setPollingBatchSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267getActivityStatistics(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268getActivityStatisticsByService. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269getActivityStatisticsByOperation(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270getThreadStatistics(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271getQueueStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272getConnectionStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273resetActivityStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274resetThreadStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275resetQueueStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276resetConnectionStatistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Appendix A Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

General Questions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Request-Response Questions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Appendix B Trace Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333


x | Contents


| xi

Figures

Figure 1 Typical Publication-Subscription Services Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Figure 2 Typical Request-Response Service Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Figure 3 The TIBCO Adapter for ActiveDatabase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Figure 4 Diagram of Publish-Subscribe Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Figure 5 Diagram of Alerter Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Figure 6 Request-Response Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Figure 7 Example of Unicode Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220


xii | Figures


| xiii

Tables

Table 1 Values to Use for TIBCO Rendezvous and JMS Transport Types . . . . . . . . . . . . . . . . . . . . . . . . 24

Table 2 Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Table 3 JDBC Drivers and URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Table 4 TIBCO Administrator Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Table 5 Run-time Adapter Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Table 6 Required Run-Time Adapter Properties File Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Table 7 Additional Run-Time Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Table 8 Optional parameters for server-based locator string (TIBCO Rendezvous). . . . . . . . . . . . . . . . . 127

Table 9 Required fields for server-based locator string (HTTP or HTTPS). . . . . . . . . . . . . . . . . . . . . . . . 128

Table 10 Optional parameters for server-based locator strings (HTTP or HTTPS) . . . . . . . . . . . . . . . . . . 129

Table 11 Optional parameters for local repository locator string. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Table 12 Alerter Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Table 13 REQUEST Schema Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Table 14 REPLY Schema Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Table 15 Publishing Table Additional Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Table 16 Mapping to Database Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Table 17 Wire Format Parameters and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Table 18 adbPreCommit Parameter Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Table 19 Compilers for Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Table 20 IANAAppCodePage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Table 21 TIBCO ActiveDatabase Adapter and Oracle NLS_Lang Values . . . . . . . . . . . . . . . . . . . . . . . . . 229

Table 22 Standard Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Table 23 Custom Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Table 24 Custom Microagent Methods with adb.perfMon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Table 25 Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289


xiv | Tables


| xv

Preface

TIBCO Adapter™ for ActiveDatabase software is a bidirectional gateway between databases and applications configured for the TIBCO environment. The software supports both publish-subscribe and request-response interactions.

Using a trigger-enabled ODBC or JDBC connection to a database, the adapter proactively notifies applications of changes that occur inside the database. Conversely, the adapter can be configured to subscribe to messages from other applications and capture the messages into target tables in the database. Triggers can be attached to these target tables to cause other actions to occur with the database.

Requests from applications are processed by the adapter and replies containing the processed request are sent back by the adapter to the requesting application.

Topics

• Related Documentation, page xvi

• How to Contact TIBCO Customer Support, page xix


xvi | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Adapter for ActiveDatabase DocumentationThe following documents form the TIBCO Adapter for ActiveDatabase documentation set:

• TIBCO Adapter for ActiveDatabase Installation Guide — Read this manual for instructions on how to install and uninstall the adapter on Windows and UNIX platforms.

• TIBCO Adapter for ActiveDatabase User’s Guide — Read this manual to gain an understanding of the product that you can apply to the various tasks you may undertake.

• TIBCO Adapter for ActiveDatabase Examples Guide — Complete the examples in this manual to get a hands-on introduction to the software.

• TIBCO Adapter for ActiveDatabase Release Notes — Read this manual for additional information about new features, closed and open issues.

• TIBCO Adapter for ActiveDatabase readme.txt — Read this document to check the current release number, supported platforms and required software.

• TIBCO Adapter Concepts — This manual introduces adapters by explaining what they are, and explains how to install, configure, deploy and manage adapters.

Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCO products. Note that only books that relate to adapters are listed. Each of the books is available from the doc directory in the product’s installation area.

• TIBCO ActiveEnterprise™ software:

— TIBCO ActiveEnterprise Concepts

• TIBCO Designer™ software:

— TIBCO Designer User’s Guide

— TIBCO Designer Palette Reference

— TIBCO Designer Release Notes


Preface | xvii

• TIBCO Administrator™ software:

— TIBCO Administrator User’s Guide

— TIBCO Administrator Server Configuration Guide

— TIBCO Administrator Release Notes

• TIBCO BusinessWorks software:

— TIBCO BusinessWorks Concepts

— TIBCO BusinessWorks QuickStart

— TIBCO BusinessWorks Process Design Guide

— TIBCO BusinessWorks Palette Reference

— TIBCO BusinessWorks Installation

— TIBCO BusinessWorks Release Notes

• TIBCO IntegrationManager™ software:

— TIBCO IntegrationManager Concepts

— TIBCO IntegrationManager Administrator’s Guide

— TIBCO IntegrationManager Process Design Guide

— TIBCO IntegrationManager Reference

— TIBCO IntegrationManager Release Notes

• TIBCO Rendezvous™ software:

— TIBCO Rendezvous Concepts

— TIBCO Rendezvous Administration

— TIBCO Rendezvous Configuration Tools

• TIBCO Enterprise™ for JMS software:

— TIBCO Enterprise for JMS User’s Guide

— TIBCO Enterprise for JMS Release Notes

• TIBCO Hawk™ software:

— TIBCO Hawk Installation and Configuration

— TIBCO Hawk Administrator’s Guide

• TIBCO Adapter SDK

— TIBCO Adapter SDK Concepts

— TIBCO Adapter SDK Programmer’s Guide


xviii | Related Documentation

• TIBCO Runtime Agent

— TIBCO Runtime Agent Release Notes

— TIBCO Runtime Agent Administrator’s Guide

— TIBCO Runtime Agent Installation

— TIBCO ActiveEnterprise Features, Migration and Compatibility


Preface | xix

How to Contact TIBCO Customer Support

For comments or problems with this manual or the software it addresses, please contact TIBCO Support Services as follows.

• For an overview of TIBCO Support Services, and information about getting started with TIBCO Product Support, visit this site:

http://www.tibco.com/services/support/default.jsp

• If you already have a valid maintenance or support contract, visit this site:

http://support.tibco.com

Entry to this site requires a username and password. If you do not have a username, you can request one.


xx | How to Contact TIBCO Customer Support


| 1

Chapter 1 Introduction

This chapter introduces the TIBCO Adapter for ActiveDatabase product by providing background information about its features, components and the applications that use it.

Topics

• Overview, page 2

• Adapter Services, page 4

• Message Transports, page 6

• Adapter Architecture, page 8

• Supported SQL Operations, page 14

• Publication Service Considerations, page 15

• Checking for Duplicate Configurations, page 17

• Message Logging Feature, page 18

• Timely Processing of Data, page 19


2 | Chapter 1 Introduction

Overview

TIBCO Adapter for ActiveDatabase software (the adapter) allows data changes in a database to be sent as they occur to other databases and applications. It extends publish-subscribe and request-response technology to databases, making multiple levels of delivery services available to applications that need access to these databases. ODBC and JDBC compliant databases such as Oracle, Sybase, and Microsoft SQL Server are supported. While the adapter does not run on OS/390 and AS/400 systems, it can remotely connect to a DB2 database running on these systems.

TIBCO Adapter for ActiveDatabase is written using the TIBCO Adapter SDK software, which allows the adapter to interoperate with other TIBCO products. The adapter can communicate with any application that is configured for the TIBCO environment.

CapabilitiesThe following capabilities are described in detail in this manual.

• Automatically publish data when rows in pre-specified database tables are inserted, updated or deleted:

— Publish data by creating a copy (by value). See Publish by Value on page 15.

— Publish by reference (publish data directly from the source database table without first copying the data from the source table to a publishing table). See Publish by Reference on page 15.

— Publish on parameterized subjects, which allows a subject to be created from the contents of one or more table columns. See Parameterized Subject Names on page 185.

— Preregister certified subscribers with a certified publisher. See Preregistering a Certified Subscriber on page 186.

— Update both parent and child tables within a publication. Both the parent row and all related child rows will be published if the user has set up to publish child data. See Adding Child Tables on page 73.

• Automatically subscribe to data and insert, update or delete the data in pre-specified tables in a database:

— Subscribe using wildcard subject names. See Subject Names on page 184 and Preregistering a Certified Subscriber on page 186.

— Perform batch commits based on message count or time out value. See Adapter Services Tab on page 52.


Overview | 3

• Use request-response semantics to publish SQL statements, stored procedures, or both on a specified subject:

— Execute stored procedures with IN parameters, OUT parameters, or both. (Binary OUT parameters are not supported. This is a limitation of the Oracle ODBC driver.) See Oracle REF Data Type Support on page 168.

• Support RPC (Remote Procedure Calls). The adapter can act as an operation server providing a simple means for a client to execute a single or batch of SQL statements. See Request-Response Mode on page 146 and RPC Mode on page 154.

• Change published messages for a publisher or subscriber adapter by customizing the supplied callout library. See User Callout Library on page 200.

• Customize adapter behavior to suit your needs:

— Specify relationships between tables, then publish related tables together. See Tables Tab on page 71.

— Monitor for database changes using periodic polling or notification by an alerting mechanism. See Adapter Services Tab on page 52.

• Rely on standards:

— Connect to multiple database vendors using ODBC or JDBC drivers. See Design-time Connection Tab on page 46 and Run-time Connection Tab on page 50.

— Interoperate with other TIBCO products through the use of TIBCO Adapter SDK software. See Sending Messages to an Adapter Instance on page 190.

— Monitor your adapter service using TIBCO Hawk software. See Monitoring Tab on page 63 and Chapter 11, Monitoring the Adapter, on page 231.

— Choose message transports: TIBCO Rendezvous or Java Messaging Service (JMS). See Message Transports on page 6.

• Configure the adapter easily using TIBCO Designer. See Chapter 3 on page 33.



Adapter Services

The adapter offers publication, subscription, and request-response services. Communication parameters, database connectivity parameters, and many other parameters can be configured for these adapter services using TIBCO Designer.

The following sections describe how these adapter services interact with the database environment to provide message connectivity with it.

Publication and Subscription ServicesThe following diagram illustrates publication and subscription. Database Application 1 updates a table in a database monitored by a TIBCO Adapter for ActiveDatabase publisher adapter. The adapter extracts data from the changed rows of the database tables and publishes it on the specified transport (TIBCO Rendezvous or TIBCO Enterprise for JMS). This data is then available to other applications listening on these transports.

One particular type of listening application could be another instance of a TIBCO Adapter for ActiveDatabase adapter, running a subscription service. Upon receiving a message, it updates the relevant tables in its associated database.

Figure 1 Typical Publication-Subscription Services Flow

DatabaseApplication 1

DatabaseApplication 2

Adapter forActiveDatabase

Publisher

Adapter forActiveDatabase

Subscriber

Other TIBCOApplications

TIBCO Messaging


Adapter Services | 5

Request-Response ServiceThe request-response feature in TIBCO Adapter for ActiveDatabase allows an application to submit one or more SQL statements, stored procedures, or both for the adapter to execute. After execution, the adapter returns one or more result sets and a result code. The request and responses are formulated using nested self-describing messages. This data flow is illustrated in the figure below.

Figure 2 Typical Request-Response Service Flow

The adapter can also be configured to manage requests using load balancing among a set of adapters that participate in the same named queue. Additionally, the adapter has been designed to allow multiple threads to process application requests.

For more information, see Chapter 8, Using the Request-Response Service, on page 143.

TIBCO Messaging

TIBCOApplication 2

TIBCOApplication 1

Adapter

Database



Message Transports

Two message transports are available: TIBCO Rendezvous and TIBCO Enterprise for JMS. These transports are described below.

TIBCO Rendezvous TransportThe TIBCO Rendezvous transport provides two qualities of services: Reliable and Certified. In addition, a subscription service can be configured to use distributed queues. These transports are described in more detail in the TIBCO Rendezvous Concepts manual.

Supported Wire Formats

Three wire formats are supported, as described below. For detailed information, see the TIBCO Adapter SDK Concepts manual.

• ActiveEnterprise Message This is the standard TIBCO ActiveEnterprise wire format, which provides class information and packing rules for the TIBCO Adapter SDK set of data types. This wire format allows TIBCO ActiveEnterprise components to perform extra validation on messages sent or received.

• Rendezvous Message This is the basic TIBCO Rendezvous wire format.

• XML Message This conforms to specifically constructed and fully compliant XML Schema (XSD) based on the existing definition of the TIBCO ActiveEnterprise schema.

The notion of parent-child relationships is supported with the TIBCO ActiveEnterprise Message wire format. A group of related rows from multiple tables can be encoded into a single message and published. As a subscriber, the adapter can decode a complex message and insert multiple rows into a set of target tables.

An adapter does not convert messages from the TIBCO ActiveEnterprise Message wire format to the TIBCO Rendezvous Message wire format or the reverse. The wire format specified for a publishing table (in the source database) must match the wire format specified for a destination table (in the destination database). A wire format is assigned to a publishing table and to a destination table when using TIBCO Designer to configure an adapter. If message conversion between the two formats is required, use TIBCO BusinessWorks software to perform the conversion.


Message Transports | 7

TIBCO Enterprise for JMS TransportAn adapter service that uses the Java Messaging Service (JMS) can communicate only with the TIBCO Enterprise for JMS server. Before configuring an adapter service for the TIBCO Enterprise for JMS transport, you should be familiar with JMS concepts, which are explained fully in the TIBCO Enterprise for JMS User’s Guide. The book is available from the machine on which the software is installed in the TIBCO_home/jms/doc directory.

The TIBCO Enterprise for JMS transport uses the XML message wire format only. The XML wire format conforms to specifically constructed and fully compliant XML Schema (XSD) based on the existing definition of the TIBCO ActiveEnterprise schema.



Adapter Architecture

TIBCO Adapter for ActiveDatabase software allows data stored in a database to be exchanged with applications configured for the TIBCO environment. An alerter executable can be used when the default method of polling for database changes is not appropriate.

TIBCO Designer software is used to configure an adapter service. The adapter can be monitored using TIBCO monitoring tools.

The following diagram shows the major components in a system that uses the adapter and other parts of the TIBCO environment. Configuration data is stored in projects that can be used by one or more adapters. The components are explained in this section and the following section.

Figure 3 The TIBCO Adapter for ActiveDatabase Environment

Run-time AdapterA run-time adapter service acts as a bi-directional bridge between your database and the TIBCO environment. A publisher adapter service monitors your database, extracting data from relevant database tables and sending it on an appropriate subject using the configured quality of service, reliable or certified. A subscriber adapter service listens for messages sent on configured subjects and inserts, deletes or updates rows in its associated database tables with the information.

JDBC

TIBCO Adapter forActiveDatabase

ODBC

Database

Alerter

Application 1 Application 2

TIBCO Messaging

TIBCODesigner


Adapter Architecture | 9

An adapter can be configured with both a publisher service and a subscriber service, sending messages and writing them to more than one table. An adapter can publish and subscribe to the same table provided the publish destination is different from the subscribe destination.

An adapter can also be configured to use request-response semantics, which allows the adapter to act on behalf of a TIBCO application, processing its requests and returning responses. A set of adapters can be configured to participate in a queue (TIBCO Rendezvous Distributed Queue or JMS Queue) that allows load balancing, so requests are handled promptly.

By default, an adapter has both publisher and subscriber roles. A publisher role is defined by a project, when the Number of Publication Service Threads value is 1. A configuration has a subscriber role when the Number of Subscription Service Threads value is 1. For more information on changing these values, see Adapter Services Tab on page 52.

Adapter services using TIBCO Rendezvous transport can use the TIBCO Rendezvous certified messaging service. Message parameters are stored in the project and can be modified for your environment. For an example, see Changing the Location of the Ledger File on page 188. Adapters using JMS can use the durable messaging service.

TIBCO Runtime AgentTIBCO Runtime Agent is required on any machine on which an adapter is installed. It provides basic connectivity between the other components and manages the components on each machine. TIBCO Runtime Agent provides connectivity to other applications configured for the TIBCO environment.

TIBCO Runtime Agent provides the run-time environment for TIBCO ActiveEnterprise components. TIBCO Runtime Agent carries out two primary functions by providing:

• The run-time environment; that is, all the shared libraries including third-party libraries

• An agent that runs in the background and starts and stops processes according to deployment information.

Each adapter should have a unique name within a project. For more information, see Configuration Tab on page 44.



Polling or AlerterAn adapter publication service can use periodic polling or an alerter process to monitor changes to a database table.

• The default method is polling. The adapter polls (checks) the publishing tables periodically for any new rows to be published. This method is most efficient when the publishing tables change frequently and a limited number of database operations is preferred.

• In the case where the publishing tables change infrequently, polling may result in many unnecessary database accesses. For this situation, a set of alerter executables is provided for a database, to asynchronously alert the adapter of changes in the database. This removes the need for the adapter to poll its publishing table for existence of new rows. It is recommended to use the alerter only when database changes are infrequent. When the adapter receives an alert, it publishes the new data. (Publishing on subjects is introduced in Subject Names on page 184 and explained fully in TIBCO Rendezvous Concepts.)

The alerter is not available on all databases and platforms. See Chapter 7 on page 133 for details.

Referencing External SchemasWhen configuring an adapter, you can specify database tables to use for each publisher and subscriber. The default schema for specified source and destination table names is associated with the database user account in the create_user.sql script. This script is normally executed as part of the post installation procedure.

You may need to access source and destination tables that are in another schema, and not in your default schema (the schema specified in create_user.sql). Source and destination tables in TIBCO Adapter for ActiveDatabase can be configured to reference tables in an external schema.

Exception TableYou can designate an exception table for a subscriber. If a subscriber adapter cannot write data to its destination table, it will write the data to the exception table.

To write to an exception table, an adapter must be started with the adb.useExceptTable option set to on in the supplied properties file and an exception table must have been specified when using the TIBCO Designer to add a subscription. If an error occurs when inserting data into the destination table, the adapter attempts to insert the data into the exception table.



• If the insertion into the exception table is successful and the RVCM quality of service is specified for the subscription, the transaction commits and confirmation for the message is sent back. In the publishing table, the value of the delivery status column is C, since the message was processed. If you are using a durable JMS subscriber, a JMS confirmation will be sent back.

• If the insertion into the exception table fails, an error message displays, a rollback occurs and a TIBCO Hawk alert is published. The adapter will then terminate. The user is advised to fix the problem with the message or the table and then to restart the adapter. The message will be delivered again after the adapter starts. (If the adapter did not terminate, after the next message was inserted successfully, its confirmation would also implicitly confirm the failed message.)

You can identify the operation that failed by checking the ADB_OPCODE column of the publishing table. The ADB_ERROR_TEXT column contains error information. For details, see Exception Table on page 177.

Loop DetectionIf a source table is used both as the source and destination table on the same subject, the loop detection feature should be enabled. The feature prevents the same changes from being published repeatedly.

If the loop detection feature is enabled, an additional column, ADB_SOURCE, is added to the source table. When an adapter receives a message, it inserts or updates the source table and enters a T in the ADB_SOURCE column to denote that this row was inserted or updated as a result of a message, rather than from user intervention.

Triggers created by the ActiveDatabase Adapter Configuration palette are defined to not copy rows with T in the ADB_SOURCE column into the publishing table, which effectively means that the row will not be published. If you must update a row that was received (that is, has a T in the ADB_SOURCE column) and want the updated row propagated, you must also change the ADB_SOURCE column to NULL. This causes the trigger to pick up the row and send it out.

Master-Master ReplicationYou can use the loop detection feature to implement a simple master-master replication scheme. Master-master replication allows multiple sites, acting as peers, to copy and maintain groups of replicated objects.



When loop detection is enabled, an adapter can be configured as both a publisher and a subscriber to the same table on the same subject. When the subscriber receives a message, it compares the adapter ID of the message to its own adapter ID. If adapter ID values match and source and destination tables are the same table in the database, the subscriber discards the message. Other subscriber adapters listening on the subject receive the message only once.

The adapter does not resolve any replication conflicts, such as when two applications each update the same row of their corresponding source table and both publish the change. For advanced replication scenarios, use the replication tools provided by your database vendor.

Multi-file Format ProjectsThis section introduces the multi-file format in which projects are stored during design-time. A detailed description of the multi-file format is in the TIBCO Designer User’s Guide.

The multi-file format creates one TIBCO ActiveEnterprise XML file for each logical object (such as an adapter instance, a set of related TIBCO ActiveEnterprise classes, or a TIBCO BusinessWorks process flow) that occurs in the repository instance. This kind of project is referred to as a multi-file project.

Multi-file projects can be checked into a version control system, and a project can contain more than one adapter configuration. This allows a number of people to work on the same project at the same time, with different people working on each adapter configuration: a developer can check out the specific file corresponding to an object that needs to be changed, updated the file, and check it back in. TIBCO Designer accesses the local synchronized copies of the files on the developer’s hard drive.

The multi-file format provides a hierarchical structure with directories taking the place of RepoDirectory nodes. In previous releases of TIBCO Adapter for ActiveDatabase, repository nodes contained references to other repository nodes (such as sessions and endpoints of that instance) using a format such as:

/tibco/public/endpoint/adapter/adb/test/instance1/publisher1

In the multi-file format, these references are replaced by URIs of the following form:

ProjectRoot/multi-file_project_name/#type.name

For example, the first reference above would map to the following URI in a multi-file project:

ProjectRoot/Adapters/adb/test/instance1/publisher1



DAT File FormatFor production and for testing with run-time adapters, developers export multi-file projects to .dat format using TIBCO Designer menu commands. A project can be exported as a local project for local testing or exported to be managed by a repository server.



Supported SQL Operations

The adapter supports the following SQL operations for publishing and subscribing:

• INSERT

• UPDATE

• DELETE

• UPDATE/INSERT (update if row exists, otherwise insert)

Whenever a supported SQL statement is executed against a table monitored by a publisher adapter, the adapter instance sends a message to its subscribers, which update their destination tables.


Publication Service Considerations | 15

Publication Service Considerations

When configuring and preparing to run an adapter instance that involves a publication service, keep in mind the information in this section.

Publish by ValueWhen a user modifies a row in a source table that has been set up for publication, the data in the modified row is copied into a publishing table by a stored procedure created by the adapter during configuration. The adapter then selects the data from the publishing table, packs it into a message, and sends it.

An advantage of publish by value is its speed. However, it does not support some data types, such as Oracle LONG and LONG RAW. Publishing these data types by value from a top-level table is unsupported due to database trigger limitations.

Publish by ReferenceThe publish by reference feature allows you to publish data directly from the source table without first copying the data to a publishing table. If a source table is set up to publish by reference, the publishing table does not contain a copy of the source table data. Instead, the adapter selects the data for publishing directly from the source table itself.

For example, to publish from ORDER_TABLE with a key field ORDER_ID, the publishing table is created with the necessary adapter fields and the ORDER_ID field. When a row in ORDER_TABLE is modified, the trigger fires, populating adapter fields and copying the ORDER_ID value to the publishing table. When the adapter polls the publishing table, it detects the new row and selects from the ORDER_TABLE using the ORDER_ID value found in the publishing table. Then the message is published.

The advantage of publishing by reference is that the data to be published is stored just once. Also, this method supports data types such as Oracle LONG and LONG RAW.

The disadvantage of publish by reference is that after a row in the source table is modified, a small amount of time passes before the adapter selects the row. During this short interval, the row could be modified again. If this happens, the adapter will get only the second set of modifications when it selects the row. However, this time lapse can be minimized by using the alerter.



When publishing by reference, a key column or substitute key column is required for populating the publishing table. If the source table has no primary key, it can only be set up to publish by reference if a key column is specified when adding the publication. For more information, see Publisher Options Tab on page 78.

Update Feature for Parent-Child PublicationIf an adapter is configured to publish child data, the parent row and all related child rows are published when a parent row is updated. Upon receipt of such a message, a subscriber adapter updates the parent row and then updates all the child rows with the data that was received in the message. The adapter updates the child rows by deleting all the related child rows, then inserting child rows again based on the data in the received message.

Changing a Publication Subject Without Using TIBCO DesignerThe subject on which a publisher adapter sends messages for a publication is defined in TIBCO Designer when the publication is added (see Advanced Tab on page 82). You can change the publication subject while the adapter is running (without using TIBCO Designer) by changing the subject value in the database trigger.

By default, the subject is passed as NULL in the trigger. If the NULL value is replaced with a valid subject, it will be used when publishing. See Stored Procedures and Triggers on page 171 for more information about triggers.

Any changes to the child tables without a change in the parent table will not be processed. The adapter monitors only the parent table for publishing. You can define a trigger on the child table that will update the parent row whenever a change to the child table occurs.


Checking for Duplicate Configurations | 17

Checking for Duplicate Configurations

While multiple adapter instances can run concurrently on the same machine to split the load of publications and subscriptions on the database, each configuration must have a unique name. During the configuration initialization cycle, a new adapter instance broadcasts a message with its name. If any running adapter has this name, it will reply to the broadcast message, causing the new adapter to abort its initialization phase and stop.

If there is running a configuration of the adapter with the same name, that configuration will respond to the broadcast message and the new configuration will not start.

To prevent same-named configurations starting on sites that have multiple TIBCO Rendezvous networks, you must allow the _ADB.DUPDECT.adapter_instance_name subject to pass through each network by configuring the rvrd daemon for each subnet. See TIBCO Rendezvous Administration for more information about using multiple TIBCO Rendezvous networks.



Message Logging Feature

You can configure an adapter instance to use the following transports and subscribe to messages in the wire formats shown below.

• TIBCO Rendezvous transport uses three wire formats:

— TIBCO ActiveEnterprise wire format

— TIBCO Rendezvous wire format

— XML wire format

• JMS transport uses the XML wire format to communicate with the TIBCO Enterprise for JMS Server.

• Opaque transport uses the TIBCO Rendezvous wire format.

Opaque Format

When the adapter receives a message in opaque format, it does not parse the message. Instead, the adapter logs the message by inserting it into a table created by TIBCO Designer. This table has two columns: a RAW column named LOG for storing the message, and a DATE column named TIMESTAMP which contains the date and time the message was inserted.

When using the TIBCO Rendezvous transport, messages can be retrieved by a database program that casts the message back into its original (uninterpreted) format. For an example of a program that selects the uninterpreted message and converts it from binary format to a TIBCO Rendezvous format, see the logtest.cpp file in your install-path\demo\logtest directory.


Timely Processing of Data | 19

Timely Processing of Data

If there is a large volume of messages to publish, set the adb.PollingInterval parameter in the adapter properties file to help process TIBCO Rendezvous events in an efficient manner. When the parameter is used, it limits the number of messages that are picked up per poll period. The adapter returns to the event loop when it is finished sending those messages.

If the parameter is not used, the adapter picks up all available messages and then tries to send all of them before returning to the event loop. This could affect adapter performance in a high volume environment.


| 21

Chapter 2 Getting Started

This chapter helps you get familiar with the adapter by running you through a basic exercise. Work through the exercise to get a hands-on understanding on how the adapter works.

Topics


• Create the Database Tables, page 25

• Configure the Properties File, page 26

• Start the Adapters, page 28

• Change the Table Values and Receive Notification, page 29

• Exit the Query Tool and Adapters, page 31

• Clean Up, page 32


22 | Chapter 2 Getting Started

Overview

In this exercise, you create tables in your database and configure a publisher adapter and a subscriber adapter. Then you modify a table and observe how the publisher adapter and subscriber adapter handle the change and update the subscription table.

Required Platform and SoftwareThis exercise can be performed on any supported operating system, using adapters provided with TIBCO Adapter for ActiveDatabase. The exercise can be run using the TIBCO Rendezvous transport method or the JMS transport method.

The exercise can be performed with an Oracle, Microsoft SQL or Sybase database.

A sample DAT file that can be used with an Oracle database, ADBDemo2-ora.dat, is included in the install-path\demo\demo2 directory.

Before StartingBefore performing this exercise, make sure that TIBCO Adapter for ActiveDatabase is installed according to the procedures in the TIBCO Adapter for ActiveDatabase Installation Guide. These procedures include creating a database account for the adapter and setting the ODBC data source, among other things.

You should be familiar with using TIBCO Designer to open and close projects and drag and drop resources; see the TIBCO Designer User’s Guide for more information. That document also describes the multi-file format used by TIBCO Designer, and converting to and from the .dat file format used by the run-time agent. The TIBCO Designer User’s Guide is available from TIBCO Designer by clicking the Help>Designer Help menu choice.

TablesThe tables are created by running a script specific to your database vendor. The script creates the following tables, all with a common set of columns:

• Source table to which you will add new data.

• Publishing table to which the new data from the source table is copied using the trigger set on the source table. This table has additional columns (prefixed by ADB_) that are used by the adapter.

• Destination table that TIBCO Adapter for ActiveDatabase will update with the new data.


Overview | 23

• Exception table to which TIBCO Adapter for ActiveDatabase will write any errors that occur during subscription.

ActionsWhen you add data to the source table, the following occurs:

1. The insert action fires a trigger and the inserted row is copied to the publishing table.

2. The publisher adapter polls the publishing table to check if any new rows have been inserted. Newly inserted rows are fetched using ODBC, packed into a message, and published.

3. The subscriber adapter listens for messages. When a message arrives, the subscriber adapter inserts it into the destination table using ODBC.

The following diagram illustrates the activity.

Figure 4 Diagram of Publish-Subscribe Steps

TasksThis exercise consists of the following tasks:

• Create the Database Tables

• Configure the Properties File

• Start the Adapters

PublisherAdapter

TIBCO Messaging

InsertTrigger

PublishingTable

DestinationTable

SourceTable

ExceptionTable

SubscriberAdapter



• Change the Table Values and Receive Notification

• Exit the Query Tool and Adapters

• Clean Up

ExerciseThis exercise uses the Oracle database. You can use the TIBCO Rendezvous or JMS transport. When performing this exercise, use the appropriate transport values for your configuration (as listed in Table 1) and follow the instructions that pertain to your particular database vendor.

You will need the following information, specific to your user environment:

• Database user ID

• Database password

• Database service

The values you will enter for the tables and the publisher and subscriber adapter instances are different, depending on which transport type you are using. (The kind of database you are using does not affect these names.)

Table 1 Values to Use for TIBCO Rendezvous and JMS Transport Types

Item TIBCO Rendezvous Transport Value

JMS Transport Value

Source Table ORDER_TABLE ITEM_TABLE

Publishing Table PUB_ORDER PUB_ITEM

Destination Table SUB_ORDER SUB_ITEM

Exception Table SUB_ORDER_EXCEP SUB_ITEM_EXCEP

Publisher Adapter rvpub jmspub

Subscriber Adapter rvsub jmssub


Create the Database Tables | 25

Create the Database Tables

The first task is to create the database tables.

1. Open a command window and change directory to the demo1 subdirectory. For example:

> cd c:\tibco\adapter\adadb\5.1\demo\demo1

2. Execute the demo1_databaseVendor.sql script in the subdirectory to create the tables for your database. Use your environment-specific user ID, password, and database service. For example:

> sqlplus userid/pswd@dbService @demo1_ora.sql

The script creates the items and displays the status. For example:

C:\TIBCO\adapter\adadb\5.1\demo\demo1>sqlplus joanne/joanne@ora817 @demo1_ora.sql

SQL*Plus: Release 8.1.7.0.0 - Production on Thu Feb 6 16:47:19 2003

(c) Copyright 2000 Oracle Corporation. All rights reserved.

Connected to:Oracle8i Enterprise Edition Release 8.1.7.0.0 - ProductionJServer Release 8.1.7.0.0 - Production

Table created.Table created.Table created.Index created.Index created.Index created.Sequence created.Trigger created.Table created.Table created.Table created.Table created.Index created.Index created.Sequence created.Trigger created.Table created.Commit complete.SQL>



Configure the Properties File

After creating the database tables, configure the adapter’s properties file.

1. In the demo1 subdirectory, locate the correct publisher adapter properties file for the transport type you are using. Refer to Table 1 on page 24.

2. Open the publisher adapter file and set the following values as appropriate for your environment.

For example:

C:\TIBCO\adapter\adadb\5.1\demo\demo1>write rvpub.tra## Sample ADB properties file# Optional properties file you can use in place of command line parameters# Usage: adbagent --propFile propFilename...

Property Value

adb.user userId Remove the comment-out character (#) from this line.

Use the database account name used by the adapter instance. This is the same username entered during TIBCO Adapter for ActiveDatabase installation when creating a database account for the adapter.

adb.password pswd Remove the comment-out character (#) from this line.

Use the database account password used by the adapter instance. This is the same password entered during TIBCO Adapter for ActiveDatabase installation when creating a database account for the adapter.

This password is not saved in the project. The global variable %%adb.password%% is saved instead.

adb.dsn dataSource Remove the comment-out character (#) from this line.

Use the name of the ODBC system data source for the adapter. The data source is configured as part of the TIBCO Adapter for ActiveDatabase post-installation procedure. See the TIBCO Adapter for ActiveDatabase Installation Guide for details.


Configure the Properties File | 27

# Change these settings for your login and dsn for Demo1adb.user joanneadb.password joanneadb.dsn datasource...

3. Save and close the publisher adapter file.

4. In the same subdirectory, locate the correct subscriber adapter file for the transport type you are using.

5. Open the subscriber adapter file and make the same changes that you did in step 2.

6. Save and close the subscriber adapter file.



Start the Adapters

You can use TIBCO Rendezvous or TIBCO Enterprise for JMS as the message transport.

1. If you are using TIBCO Rendezvous transport, skip this step.

If you are using JMS transport, open a command window and change directory to the TIBCO Enterprise for JMS bin directory and start the JMS server. For example:

cd c:\tibco\JMS\bin

> tibjmsd

2. Open a new command window and change directory to the adapter bin directory. For example:

> cd c:\tibco\adapter\adadb\5.1\bin

3. In separate command windows, start the publisher and subscriber adapters for your database.

If using TIBCO Rendezvous:

> adbagent --propFileC:\TIBCO\adapter\adadb\5.1\demo\demo1\rvpub.tra

> adbagent --propFileC:\TIBCO\adapter\adadb\5.1\demo\demo1\rvsub.tra

If using TIBCO Enterprise for JMS:

> adbagent --propFileC:\TIBCO\adapter\adadb\5.1\demo\demo1\jmspub.tra

> adbagent --propFileC:\TIBCO\adapter\adadb\5.1\demo\demo1\jmssub.tra


Change the Table Values and Receive Notification | 29

Change the Table Values and Receive Notification

You must change table setting in your database to trigger a notification.

1. Open a new command window and change directory to the demo1 subdirectory. For example:

> cd c:\tibco\adapter\adadb\5.1\demo\demo1

2. Invoke the query tool using the environment-specific user ID, password, and database service specified in Task .

> sqlplus userid/pswd@dbService

3. Insert three values into the source table, then commit the change.


SQL> insert into ORDER_TABLE values(111,'Oak Table',499.95);

SQL> commit;


SQL> insert into ITEM_TABLE values(111,'Oak Table',499.95);

SQL> commit;

You will see the message being sent in the publisher adapter window and, after a short delay, received in the subscriber adapter window.

4. Verify that the row in the source table has been inserted into the destination table.


SQL> select * from SUB_ORDER;

The following example result confirms that the data has been inserted:

ORDER_ID----------ORDER_DESCRIPTION---------------------------------------------------

ORDER_PRICE-----------

111Oak Table

499.95


SQL> select * from SUB_ORDER;

The following example result confirms that the data has been inserted:

ITEM_ID



----------ITEM_DESCRIPTION---------------------------------------------------

ITEM_PRICE-----------

111Oak Table

499.95

5. Insert additional rows of data, if you wish. If you do, be aware that the first column (containing the value 111 in the example) is a primary key and must contain a value that is unique within the table.


Exit the Query Tool and Adapters | 31

Exit the Query Tool and Adapters

After running the example, exit the query tool and adapters.

1. Exit the SQL query tool. For example:

SQL> exit

2. In a command window, use the tibrvsend application to send a message on the terminate subject to stop each adapter instance:


tibrvsend _ADB.rvpub.TERMINATE nowtibrvsend _ADB.rvsub.TERMINATE now


tibrvsend _ADB.jmspub.TERMINATE nowtibrvsend _ADB.jmssub.TERMINATE now

Note that the tibrvsend program is typically not used to terminate the adapter. Instead, a JMS program typically sends a JMS message to the JMS termination destination configured for the adapter.



Clean Up

This cleanup script removes the example tables that were created by the demo1_cleanup_databasevendor.sql script.

1. In a command window, change directory to the demo1 directory. For example:

> cd c:\tibco\adapter\adadb\5.1\demo\demo1\

2. Execute the appropriate demo_cleanup.sql script in the subdirectory.

> sqlplus userid/pswd@dbService @demo1_cleanup_databasevendor.sql

For example:

> sqlplus joanne/joanne@ora817 @demo1_cleanup_ora.sql


| 33

Chapter 3 Adapter Instance Options

This chapter explains how to create an adapter instance by configuring standard settings. All configuration tasks are performed in TIBCO Designer and the information is stored in a project that is later used by the run-time adapter.

Topics


• Configuration Tab, page 44

• Design-time Connection Tab, page 46

• Run-time Connection Tab, page 50

• Adapter Services Tab, page 52

• General Tab, page 56

• Logging Tab, page 58

• Startup Tab, page 62

• Monitoring Tab, page 63


34 | Chapter 3 Adapter Instance Options

Overview

The adapter instance tabs in TIBCO Designer allow you to create, design, and run an adapter. Adding services to an adapter is described in Chapter 4, Adapter Service Options.

Please read the following sections before starting to configure an adapter.

• Configuration Tasks, page 34

• Saving the Project, page 35

• Testing the Adapter, page 36

• Notes on Configuring an Adapter, page 36

• Configuration Recommendations, page 37

• Changing an Existing Configuration, page 37

The adapter instance tabs are described in the following sections.

• Configuration Tab, page 44

• Design-time Connection Tab, page 46

• Run-time Connection Tab, page 50

• Startup Tab, page 62

• Monitoring Tab, page 63

• Logging Tab, page 58

• General Tab, page 56

• Adapter Services Tab, page 52

Configuration TasksUse the following sequence to create and configure an adapter service.

1. Start TIBCO Designer and open a multi-file project. See the TIBCO Designer User’s Guide for details.

2. Drag the ActiveDatabase Adapter Configuration icon from the palettes panel to the design panel. This creates an adapter instance named, by default, ActiveDatabaseAdapterConfiguration.

3. Define the adapter instance by assigning a new name. See Configuration Tab on page 44.


Overview | 35

4. Define and test the design-time connection options for the instance. See Design-time Connection Tab on page 46.

5. Either now or when the instance is ready to deploy, define and test the run-time connection options for the instance. See Run-time Connection Tab on page 50.

6. As necessary, modify the following default values for the instance:

— Default startup state and session, metadata search URL: see Startup Tab on page 62

— Standard, class, and default MicroAgents: see Monitoring Tab on page 63

— Logging options: see Logging Tab on page 58

— Termination subject, encoding, and debugging options: see General Tab on page 56

— Threads, polling, publishing child data, bulk insert size, TIBCO Rendezvous queue size, exception table: see Adapter Services Tab on page 52

7. Add one or more services to the adapter instance by dragging a service icon from the palettes panel and dropping it in the design panel: see Chapter 4, Adapter Service Options.

8. Under the service’s Configuration tab, set the combination of options for each service. This is required.

9. As necessary, define tables, mappings, message and reply subjects, endpoints, and other service options.

10. Save the project as a server repository project.

After configuring the adapter, create the run-time adapter property file and add the project name and adapter instance name. See Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition on page 105 for details.

Also define and test the run-time connection options for the instance if you did not do it earlier. See Run-time Connection Tab on page 50.

Saving the ProjectConfiguration information for an adapter and all other parameter settings related to the adapter are saved as a project. At any time while configuring the adapter, you can save the associated project. Each time you save a project, any configuration information you have entered is saved as a project.

For detailed steps and more information about exporting or importing projects to different formats (such as .dat), see the TIBCO Designer User’s Guide.



Testing the AdapterYou can use the Adapter Tester to verify that an adapter instance is configured correctly. The tester is invoked from the TIBCO Designer Tools menu and is documented in TIBCO Designer Palette Reference.

Notes on Configuring an Adapter

Required and Optional Settings

• You must set the options in the Configuration Tab for all adapters.

• The Design-time Connection Tab options are required before you can start designing the adapter and adding services.

• The remaining tabs are optional, and are customized for your adapter or services only as needed.

You should be aware of the following before starting or configuring an adapter.

• A database account must have been created for running the adapter. For details, see the TIBCO Adapter for ActiveDatabase Installation Guide.

• The database server process, and the repository server process if you are using a remote repository, must be running to start an adapter instance.

• Each adapter must have configuration information defined in a project using TIBCO Designer. For instructions, see Chapter 3, Adapter Instance Options.

• Data source connection parameters for an adapter instance can be specified in the adapter properties file and in TIBCO Designer. Values given in the properties file override the same values specified in TIBCO Designer.

• An adapter instance name is defined in TIBCO Designer. Names must be alphanumeric, can contain underscores (_) and hyphens(-), and must be less then 80 characters.

• Multiple subscribers of the same instance should not be configured to listen on the same subject.

• Multiple subscribers in different instances can be configured to listen on the same subject but should not write to the same destination table.

• An adapter instance can be configured as a publisher, subscriber, or both. It can handle request-response operations if it is configured to do so.

• An adapter instance can publish or subscribe to a maximum of 1024 database columns per table. The maximum size of each record is restricted by the number of bytes per row supported by the database server, and the amount of contiguous space in memory available to build the message.


Overview | 37

• If an adapter instance cannot access the database at startup, the adapter will not start. If the connection fails after startup, you can configure the adapter to attempt automatic reconnections (see the Run-time Connection Tab on page 50). You can also build a TIBCO Hawk rule to restart the adapter instance after the database is restarted.

• An adapter instance can be stopped in several ways. See Start or Stop the Adapter on page 111.

• An adapter instance logs error, warning, debug and information messages to the console window by default. Some of the output can be directed to a log file that can be located anywhere on your file system.

• Do not use ADB_ to prefix columns in the database. The prefix is reserved for this product.

Configuration RecommendationsThe following recommendations and limitations apply when using TIBCO Adapter for ActiveDatabase:

• The wire format for both the publishing and destination tables must be the same, otherwise an error will occur.

• Publisher and subscriber information should be defined in the same project for all cases. When using parent-child tables or the XML wire format, define the publisher and subscriber in the same repository.

• The following limitations apply to TIBCO Rendezvous transport type parameterized subject names:

— Do not insert the * or > character as an attribute value (varchar, char) in a column that is part of a parameterized subject.

— Do not insert data of Float type as an attribute value in a column that is part of a parameterized subject.

— Do not use Date type columns as part of a parameterized subject. Dates generally contain characters such as dashes and spaces that do not work well as part of a subject.

Changing an Existing ConfigurationYou can change an existing adapter instance before or after it is deployed, but doing so may have unintended consequences to the database, the schema, and to other adapter instances associated with the same schema. When making changes, be aware of the following:



• It is recommended to back up your project before making major configuration changes. To back up a project, use TIBCO Designer to export the project. The export file can be imported into TIBCO Designer, if necessary. For more information, see TIBCO Designer Palette Reference.

• Legitimate changes to the database as a result of adapter instance changes may not be immediately successful, for example, if the database was not available at the time the change was made.

• If you want adapter instance changes to be reflected in the database, make sure the Deploy On Save checkbox is selected; otherwise, make sure this checkbox is cleared. This checkbox is on the Configuration tab of the configured adapter resource.

• If you delete an adapter instance or service that is already deployed, the related database will be cleaned up as soon as you confirm the deletion, and the changes will be irreversible.

• If you change an adapter instance or service that is already deployed, the related database will be cleaned up as soon as you re-save the project.

• Deleting an adapter instance deletes all the services included in that configuration.

• When deleting an adapter service, you have the opportunity to save the service’s schema. This is important when another adapter instance is also associated with the same schema.

• If an adapter instance is renamed, the schema associated with that configuration is also renamed, and if another configuration is associated with that same schema, the association will become invalid once the schema is renamed.

If legitimate changes to the database result in error messages while you are trying to save the changes, you may need to run the cleanup script that the adapter creates during the save operation. For more information about these error messages and using the script, see Using Database Cleanup Scripts on page 216.

Using Global VariablesThe variable substitution mechanism can override global variables predefined in the project in a restricted manner. Predefined variables can be viewed and set in TIBCO Designer. Variables are specified as %%VARNAME%% and cannot contain any white space.

Variable substitution allows you to accomplish the following.

• Substitute string variables specified in the project at startup time.


Overview | 39

• Locally define the value for a variable for a specific project. The local value takes precedence over any global value.

• Specify the value for a variable in a properties file. This overrides the project repository and values set in code, but not variables set on the command line.

• Enforce the pre-defined variables listed in Predefined Global Variables on page 41.

Variables can be used anywhere in the configuration and will be replaced by the locally-defined adapter instance.

Variable Specification

The adapter can specify variables:

• In the project during configuration using TIBCO Designer.

• In a properties file.

• In TIBCO Administrator Enterprise Edition when deploying the project.

The values in the properties file or Enterprise Edition take precedence over the values set in the project through TIBCO Designer.

Specifying Variables Using TIBCO Designer

Global variables provide an easy way to set defaults for use throughout your project.

For example, you could assign the value 7474 to the predefined global variable RvDaemon. You can then use the variable in different sessions in your adapter. If you wish to change the TIBCO Rendezvous daemon for your adapter, you can globally set it to a different value or override it from the command line.



To Specify Global Variables:

1. In the project panel, select the Global Variables tab.

The project panel displays all currently defined global variables. You have these choices for modifying global variables:

— To assign or change a variable value, triple-click the variable. The variable expands so you can change either the variable name or the variable value. Press Enter when done.

— To add a new global variable group, click the group icon (on the left below the project panel). Specify the name of the group, then press Enter.

— To add a global variable to the list, click the abc icon below the project panel. A new global variable item is added to the bottom of the list. Type the variable name and, optionally, the value. Press Enter when done.

— To add a global variable to a group, select the desired group icon and click the abc icon below the project panel.

The global variable is now displayed in the global variables list.

2. When you want to use the global variable in the fields of a resource, enter the variable name surrounded by %% on both sides.

When the project is deployed and the configured components are run, all occurrences of the global variable name are replaced with the global variable value (unless it was overridden in a way that had higher precedence). For example, RvServiceTest would be replaced with 7800.


Overview | 41

A number of global variables are predefined. See Predefined Global Variables in the next section for information. You may add definitions of any variables you need to the predefined variables.

Predefined Global Variables

The following table lists and explains the predefined global variables. Some global variables are automatically used within the system when an adapter instance is configured.

Table 2 Predefined Global Variables

Variable Description

Deployment Defaults to the TIBCO Designer project name. This value can be any string value. This global variable is used by the system to partially define the subject name defined for a service.

DirLedger Specifies the path name of the TIBCO Rendezvous certified messaging ledger file. The default is the root installation directory.

DirTrace Specifies the path name for log file used by the adapter. The default is the root installation directory.

Domain The default value for file-based local projects is Domain. The value for server-based projects is the domain to which the project was saved.

JmsProviderUrl Tells applications where the JMS daemon is located. Setting this value mostly makes sense in early stages of a project, when only one JMS daemon is used.

JmsSslProviderUrl

Tells applications where the JMS SSL daemon is located.

RemoteRvDaemon TIBCO Rendezvous routing daemon (rvrd) to be used. See TIBCO Administrator Server Configuration Guide for details about setting up a domain using rvrd.

RvDaemon TIBCO Rendezvous daemon. Sessions use this daemon to establish communication. The default value is 7500.

RvNetwork TIBCO Rendezvous network. This variable need only be set on computers with more than one network interface. If specified, the TIBCO Rendezvous daemon uses that network for all outbound messages.

In most cases, you can leave the default.



RvService TIBCO Rendezvous service. The TIBCO Rendezvous daemon divides the network into logical partitions. Each transport communicates on a single service. A transport can communicate only on the same service with other transports.

Unless you are using a non-default TIBCO Rendezvous configuration, you should leave the default (7500).

RvaHost Computer on which the TIBCO Rendezvous agent runs. This variable is only relevant if you are using the TIBCO Rendezvous Agent (rva) instead of the TIBCO Rendezvous daemon, and if you have configured a non-default setup. See TIBCO Rendezvous Administration for details about specifying the rva parameters.

RvaPort TCP port where the TIBCO Rendezvous agent (rva) listens for client connection requests. See TIBCO Rendezvous Administration for details about specifying the rva parameters. Defaults to 7501.

TIBHawkDaemon TIBCO Rendezvous daemon used in the TIBCO Hawk session. Specifies which Hawk daemon handles communication for the session. A local daemon is specified by the communications type (always tcp) and a socket number. The default configuration uses the local daemon with the TCP socket number 7474.

Specify a remote daemon by inserting its host name or IP address between the tcp entry and the port number of the daemon parameter, such as tcp:remote_computer:7800.

See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

TIBHawkNetwork TIBCO Rendezvous network used by the TIBCO Hawk session. Specifies which network to use for outbound session communications when a computer is connected to more than one network, and also specifies the multicast groups to use for communication.


Table 2 Predefined Global Variables (Cont’d)

Variable Description (Cont’d)


Overview | 43

TIBHawkService TIBCO Rendezvous service used by the TIBCO Hawk session. The Service parameter specifies which User Datagram Protocol (UDP) service group the TIBCO Rendezvous daemon should use for session communications. The default service port is 7474.


Table 2 Predefined Global Variables (Cont’d)

Variable Description (Cont’d)



Configuration Tab

You must define the options on this tab before other options can be configured. Click Apply to apply the changes before leaving this dialog.

Instance Name

Use the default name or replace it with a name of your choice.

• An instance name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name.

• An instance name cannot use global variables.

• An instance name must be unique with respect to other adapter instances for the same adapter in the project. The same instance name can be used to name an adapter instance for a different adapter in the same project. For example, a TIBCO Adapter for ActiveDatabase adapter instance named TEST and a TIBCO Adapter for Siebel adapter instance named TEST can coexist in the same project.

• Each instance name must be unique per adapter within a project even if each instance is defined in a different folder. That is, configuring same-named adapter instances in different folders will not make their names unique.

When you create an adapter instance, the palette automatically creates several resources for it. The names of these resources derive from the name of the instance they belong to. Changing the adapter instance name results in an automatic regeneration of the resources names. If you manually modify any resource name, that particular name will not be automatically regenerated next time your rename the adapter instance.

Description

(Optional) Provide additional information about the adapter instance.

Version

The version string indicates the TIBCO ActiveEnterprise (AE) configuration format in which the adapter instance is saved. An adapter instance can be saved in AE 4.0, AE 5.0 or AE 5.1 format.

When a new adapter instance is created in TIBCO Designer 5.x, the version string is set to AE Version 5.1. When a 4.x adapter instance is opened in Designer 5.x, the Version field is set to AE Version 4.0.


Configuration Tab | 45

• If a 4.x adapter instance is to be run against a 4.x run-time adapter, the instance must be saved with the Version field set to AE Version 4.0.

• If you are using TIBCO Designer 5.x to modify 4.x adapter instances, change only features supported by the 4.x. run-time adapter and use the validation utility to verify the instance before deploying the project. The validation utility scans the project and returns warnings if any 5.1 features are defined for 4.x adapter instances. Invoke the utility from the Project>Validate Project for Deployment menu command in Designer.

To change versions, click the Change Version button.

Message Filter

Specify a message filter, if you have configured a message filter resource for use with the adapter. The plugin allows you to manipulate incoming and outgoing data before sending it on the network or handing it to the target application. Plugins can be written using the TIBCO Adapter SDK. See the TIBCO Adapter SDK Programmer’s Guide for information about writing a message filter.

Show All Tabs

Check this box to display additional tabs for configuring advanced options.

Vendor

Select the database vendor to which the adapter connects. This populates the JDBC Driver and JDBC URL fields in the Design-time Connection Tab with the appropriate data.

DB2 AS400 Library

(Appears when DB2 AS400 is selected in the Vendor field) The default library in which all TIBCO Adapter for ActiveDatabase objects are created.

Write to Database on Save

Click to select it if you want to write configuration settings to the database when this project is saved. This is the default mode.



Design-time Connection Tab

You must define these JDBC information and database account options before you can design the adapter instance. I

After completing these fields, click Apply, then click Test Connection to establish a connection to the database. When the connection is successful message appears, click OK. You can now begin design-time configuration of the adapter.

Many of the following fields can use global variables. Click the Global Variables tab in the project panel to add or modify a global variable.

JDBC Driver and JDBC URL

The name and URL of the JDBC driver used during design-time configuration. The following table lists all the supported JDBC drivers and their URLs. For detailed parameter descriptions, see your JDBC driver documentation.

Instead of manually entering the following driver and URL values, you can populate these fields using a connection template or previously-stored connection parameters. For more information, see the text following this table.

Table 3 JDBC Drivers and URLs

Database Driver and URL

Oracle JDBC Driver: tibcosoftwareinc.jdbc.oracle.OracleDriver

JDBC URL: jdbc:tibcosoftwareinc:oracle://servername: 1521;SID=ORCL

SQL Server JDBC Driver: tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver

JDBC URL: jdbc:tibcosoftwareinc:sqlserver://servername:1433;databaseName=databaseName

Note: Default port number is 1433.


Design-time Connection Tab | 47

Username

Specify the database user that the design-time adapter uses to connect to the database.

Password

Specify the password for the database user.

Remember Password

If this field is checked, the password is obfuscated and saved in the project file. The next time you open this project, the Password field displays the masked password and the adapter will connect to the database without the user needing to know or enter the password.

If this field is not checked, the password must be entered here each time the project is opened. The password is saved in the project file as the global variable %%adb.password%%.

Sybase JDBC Driver: tibcosoftwareinc.jdbc.sybase.SybaseDriver

JDBC URL: jdbc:tibcosoftwareinc:sybase://servername:5000

Note: Specify a databaseName parameter (as shown in the SQL Server description above) if connecting to a database that is not the default database.

DB2 OS390 JDBC Driver: tibcosoftwareinc.jdbc.db2.DB2Driver

JDBC URL: jdbc:tibcosoftwareinc:db2://servername:port;locationName=DB2locationName;packageName=packageNamePrefix

DB2 AS400 JDBC Driver: com.ibm.as400.access.AS400JDBCDriver

JDBC URL: jdbc:as400://serverIP;libraries=lib

DB2 UDB JDBC Driver: tibcosoftwareinc.jdbc.db2.DB2Driver

JDBC URL: jdbc:tibcosoftwareinc:db2://servername:50000;databaseName=databaseName;packageName=DEF00

Table 3 JDBC Drivers and URLs (Cont’d)

Database Driver and URL (Cont’d)



Use Design-time Connection For Run-time

This field is not active.

Using Connection TemplatesTIBCO Adapter for ActiveDatabase provides connection templates with JDBC driver information for each supported database vendor. The templates populate the JDBC Driver and JDBC URL fields with the default settings as shown above. You then replace the variables with values appropriate for your configuration.

To populate the fields with default values, select ActiveDatabase>Connection templates, then select your database type from the submenu. The following screen sample shows Oracle being selected.

Saving Connection Parameters for ReuseAfter you have customized the connection parameters on this tab for your configuration, you can save them for use in another adapter. You can save as many sets of customized connection parameters as you need. The parameter sets can include the user name and password.

To save a set of connection parameters:

1. Fill in the connection parameters for the adapter.

2. Select ActiveDatabase>Save Connection Settings. The following dialog displays:


Design-time Connection Tab | 49

3. Type a name, then click OK. The following dialog displays:

4. Click either Yes or No:

— Yes saves the password in the parameter set. (If the Password field is empty, no password is saved.) When the user selects the parameter set, the Password field will be populated with the current password in clear text, even if the password is not saved in the project file or if it has been obfuscated in the project file.

— No does not save the current password in the parameter set. The user will have to enter it manually.

The connection parameters are saved.

Using Saved Connection ParametersTo use a saved set of connection parameters, select ActiveDatabase>User connections, then select a parameter set from the submenu.

The fields on the Configuration and Connection tabs are populated with the values stored in the parameter set.



Run-time Connection Tab

These settings must be configured before you start the run-time adapter.

After completing these fields, click Apply, then click Test Connection to establish a connection to the database. When the connection is successful message appears, click OK. The run-time adapter is now configured.

ODBC DSN

The name of an ODBC system data source for the database where the source or destination database table resides. The adapter uses this data source to send and receive information. If not specified, the data source name must be given in the adapter’s properties file or on the command line.

Username

This is the database user that the run-time adapter uses to connect to the database. This field is automatically populated when you select a template as described in Using Connection Templates on page 48. It cannot be changed here.

Password

This is the password for the database user. This field is automatically populated when you select a template as described in Using Connection Templates on page 48. It cannot be changed here.

Maximum Number of Reconnect Attempts

Specify the total number of reconnection attempts to make after the service has been suspended. When this number is reached, the run-time adapter or adapter service will be stopped. A value of -1 means reconnection attempts will continue indefinitely.

Number of Reconnect Attempts Before Suspending Impacted Service(s)

Specify the number of reconnection attempts to make before suspending the service. This value is 1 and cannot be changed.

Interval between Reconnect Attempts (milliseconds)

Specify the time interval (in milliseconds) to elapse between each reconnection attempt.


Run-time Connection Tab | 51

Adapter Termination Criteria (after max number of reconnect attempts)

The adapter and all of its services is stopped if any one of its services has been unable to re-establish connection after the Maximum Number of Reconnect Attempts has been made. This option cannot be changed.

Test Connection

This option is not enabled.



Adapter Services Tab

You are not required to change any settings in this tab. These settings affect all publishers, subscribers, and request-response services defined for the adapter, unless overridden by the individual service configurations as described in Chapter 4, Adapter Service Options.

Click Apply to apply the changes before leaving this tab.

All Publication Services

These settings apply to all publication services in the adapter.

Number of Publication Service Threads

A value of 1 designates the adapter as a publisher. A value of 0 (zero) indicates the attribute is not used (the adapter is not a publisher).

Use Polling Batch Size

Check this box to activate Polling Batch Size (Maximum Rows). If Polling Batch Size is not active, the adapter picks up all new rows and then tries to send all of them before returning to the event loop. This could affect adapter performance in a high volume environment.

Polling Interval

Type a specific polling interval in milliseconds. This is how often an adapter with a publication service checks the publishing table for new rows. The default is 5000, or once every five seconds.

Polling Batch Size (Maximum Rows)

(Only active when Use Polling Batch Size is checked) The maximum number of messages that are picked up per polling interval. The adapter returns to the event loop when it is finished sending those messages. Using this option helps process TIBCO Rendezvous events in an efficient manner.

By default, the adapter is designated as both a publisher and subscriber by having a value of 1 in both the Number of Publication Service Threads and Number of Subscription Service Threads fields.


Adapter Services Tab | 53

Batch Publish Status Updates

(Only active when Use Polling Batch Size is checked. Do not use this option when messages are published using a parameterized subject name.)

Check this box to optimize publishing performance by batching message status updates to the publishing table.

If an adapter stops before a batch update is performed, the status column is not updated. As a result, duplicate messages may be published when the adapter is restarted.

Publisher Batch Confirm Size

(Applies only to adapters with a publication service that uses certified message delivery. Do not use this option when messages are published using a parameterized subject name.)

The number of message status updates to include in a single batch.

Entering a value in this field optimizes performance. However, if an adapter stops before a batch update is performed, the status column is not updated. As a result, messages that were successfully published might still have a status of P (pending) in the publishing table when the adapter is restarted. In this case, the ledger file contains the correct status information. Smaller values in this field decrease this risk.

Publisher Batch Confirm Timeout

(Applies only to publisher adapters with publications that use certified message delivery. Do not use this option when messages are published using a parameterized subject name.)

The number of milliseconds to wait before updating the status column. After this interval, an update is performed even if the batch size value is not reached. The default value is 10000 (10 seconds). A value of 0 means that no timeout interval is used.

If an adapter instance stops before a batch update is performed, the status column is not updated. As a result, messages that were successfully published might still have a status of P (pending) in the publishing table when the adapter is restarted. In this case, the ledger file contains the correct status information. Smaller interval values decrease this risk.



Publish Child Data

This is checked by default. Check this box to publish the parent row and all related child rows when a parent row is updated. Upon receipt of such a message, a subscriber adapter updates the parent row and then updates all the child rows with the data that was received in the message.

The adapter updates the child rows by deleting all the related child rows, then inserting child rows again based on the data in the received message. For information on adding related tables for a publisher adapter, see Adding Child Tables on page 73. For information on adding related tables for a subscriber adapter, see Child Table Mappings Tab on page 87.

All Subscription Services

These settings apply to all subscription services in the adapter.

Number of Subscription Service Threads

A value of 1 designates the adapter as a subscriber. A value of 0 (zero) indicates the attribute is not used (the adapter is not a subscriber).

Subscriber Batch Commit Size

The number of messages to batch before invoking a commit operation. The default is 1.

Subscriber Batch Commit Timeout

Specify an interval (in milliseconds) that can expire before confirmation messages regarding successful insertion into the exception table are sent back to the publisher. The default is 1.

The batch commit feature does not commit all received messages if the adapter instance terminates before the batch commit value or time-out value is met.

Any changes to the child tables without a change in the parent table will not be processed. The adapter monitors only the parent table for publishing.

By default, the adapter is designated as both a publisher and subscriber by having a value of 1 in both the Number of Publication Service Threads and Number of Subscription Service Threads fields.


Adapter Services Tab | 55

Subscriber Bulk Insert Size

All incoming messages to insert are stored until this size is reached. Then, a bulk insert operation is performed on the destination table. This number must be less than or equal to the value in Subscriber Batch Commit Size. The default value is 1.

Note the following considerations:

• If any individual messages greater than 32K are published, bulk insert is automatically turned off.

• If an update statement is published while messages are being batched, the bulk insert is performed regardless of whether the size value has been reached. After records have been inserted, the update operation is performed.

Rendezvous Maximum Queue Size

Maximum number of messages to allow in the TIBCO Rendezvous event queue. The default value is 0, which means no limit is placed on event queue size. Use this option to prevent a subscriber’s memory from overflowing if the publisher is too fast.

Use Exception Table

Check this box to use an exception table. The exception table is defined when you create a subscription service.

All Request-Response Services

These settings apply to all request-response services in the adapter, unless the individual service is configured differently.

Number of Request-Response Service Threads

Indicate the number of database request-response threads to use. Valid values are from 1 through n. Each thread has a separate connection to the database. Specifying multiple threads allows you to load balance incoming RPC requests.

Do not use this option if LONG, LONG RAW, image, or variable-length BINARY type records are published. These records cannot be bulk inserted into a destination table.



General Tab

This tab allows you to set a termination subject or topic and specify the encoding type, debug level, and verbose mode. Note that the adapter should communicate only with other applications that support the same code pages or Unicode.

Click Apply to apply the changes before leaving this dialog.

Termination Subject or Topic

A message sent on this subject (if TIBCO Rendezvous is the transport) or topic (if JMS is the transport) stops the adapter.

The default termination subject or topic for a 5.1 project is:

%%Domain%%.%%Deployment%%.adb.%%InstanceId%%.exit

The termination subject for a 4.0 project is shown below. Do not change it.

_ADB.%%InstanceId%%.TERMINATE

See TIBCO Rendezvous Concepts for information about specifying subject names. See the TIBCO Enterprise for JMS User’s Guide for information about publishing on a topic.

Adapter Encoding

Select the encoding from the drop down menu. The adapter may support other encodings not shown. See Chapter 10, Setting Encoding Options, for a list of additional encodings that can be typed into this field.

Debug Level

This field is valid only when the Debug logging option is selected, as described in Logging Tab on page 58.

Select how much debugging output to provide at the console window or log file location specified in the Log File field. The options are:

• No debug information

• Only SQL commands executed against the database

• Only the ODBC data source for each SQL command

The palette does not validate encoding values that you type into the field. The run-time adapter will throw an error if the encoding value you type is not supported.


General Tab | 57

• All debug information

Generate Verbose Output

This field is valid only when the Information logging option is selected, as described in Logging Tab on page 58.

Check this box to include verbose output (all available information) at the console window or log file location specified in the Log File field.

Script File

Allows you to change the location where the SQL script file is written.



Logging Tab

Use these settings to configure a log file or log sinks, including which types of trace messages you want logged and where they are sent. Click Apply to apply the changes before leaving this dialog.

By default all error, warning, debug and information messages are printed in the console window in which the adapter was started. Alternatively, you can specify a log file and path to redirect trace output to a log file located anywhere on your file system. The default log file name is %%DirTrace%%/%%Deployment%%.%%InstanceId%%.log, and is saved in the same directory where your project (repository instance) is stored.

Logging trace messages is helpful for troubleshooting. There are four levels of trace messages that you can log: Information, Warning, Debug, and Error. Trace messages are described and listed in Appendix B, Trace Messages.

By default, the Use Advanced Logging option is not selected. In this mode, you configure a standard log file using the fields on this tab, as shown in the example below.

Most errors received by the adapter are logged. The only errors that might not be logged are any TIBCO Rendezvous or TIBCO Adapter SDK errors that appear at startup time before tracing can be initialized.

Logging affects system performance. It is recommended that you use logging only as needed.


Logging Tab | 59

When you select Use Advanced Logging, you configure log sinks using icons in the TIBCO Designer project panel. This gives you complete control on selecting the destinations and associating desired roles with each of the destinations.

Use Advanced Logging

Unchecked:Standard Log File

When this box is unchecked, you configure a standard log file. This is the default. Fill out the remaining fields on this tab. You do not need to read the rest of this field description.

Checked: LogSink

When this box is checked, you can set two standard output destinations (sinks) for trace messages and set the tracing level for the roles selected. The following sink types are available:

• File

• STDIO

• Hawk

• Network

To create log sinks:

1. Check the Use Advanced Logging box.

2. Click Apply.



3. In the TIBCO Designer project panel, select the Log Sinks folder under the Advanced folder.

4. Select an existing log sink or create a new one:

— Select the File or STDIO log sink icon.

— Create a new log sink by dragging and dropping the Generic log sink icon from the palette panel into the design panel, then assign a type to it from the dropdown menu in the configuration panel. Click Apply.

5. With the desired log sink icon selected in the design panel, fill in the fields in the configuration panel. You can also change the name and enter a description for each sink by right-clicking on the sink icon in the project panel.

— File sink logs the trace messages to a file. Specify the file limit, file count, and the option to append or overwrite. By default, the file limit is 30000 bytes, the file count is 3, and the mode is append.

— STDIO sink sends trace messages to stdout or stderr. By default, stdout is selected.

— Hawk sink sends each trace message to TIBCO Hawk Monitor or TIBCO Hawk Display using the Hawk session, which is created by the adapter for monitoring purposes. Specify the MicroAgent Name. (For details on Hawk sessions, see Using Global Variables on page 38.)

— Network sink publishes each trace message on TIBCO Rendezvous. Specify the session and the subject on which the trace messages needs to be published.


Logging Tab | 61

Log to Standard I/O

When selected, trace messages are displayed in the command prompt window where the adapter is started. This is the same as creating a STDIO sink. When not selected, trace messages do not display in the window.

Log File

Specify the name of the log file to which trace messages are written. This is the same as creating a file sink. Global variables can be used to specify the location of the log file. See Using Global Variables on page 38 for more information.

Type the name and file system path, or click Browse and select an existing log file. If no file name is specified, trace information is not written to a file.

Log Info/Debug/Warning/Error Messages

Select the types of trace messages you want logged.

Debug messages should not be logged unless requested by the TIBCO Product Support Group. This option writes a lot of information to the log file and significantly reduces the speed of the adapter.



Startup Tab

Changing these settings is not allowed. This tab displays the default startup behavior.

Show Startup Banner

The startup banner displays the run-time adapter version, the infrastructure version on which the adapter is built, and copyright information in the console window when the adapter is started.

Metadata Search URL

This field is predefined and cannot be changed. It specifies the location where the adapter searches for base schemas. All schemas that have been defined and saved at this location are loaded at startup.


Monitoring Tab | 63

Monitoring Tab

These settings do not need to be configured unless TIBCO Hawk is installed.

You can use microagents to supplement the monitoring information provided by the standard logging capability. Examples of supplemental information that you can obtain with microagents include the repository URL and the command line arguments used to start the adapter.

Click Apply to apply the changes before leaving this dialog.

See Chapter 11, Monitoring the Adapter, on page 231 for a list of all supported microagents.

Many of the following fields can use global variables. Click the Global Variables tab in the project panel to add or modify a global variable.

Enable Standard Microagent

Allows you to turn on or off the standard TIBCO Hawk Microagent. Clicking the globe icon changes the checkbox to a text field, allowing you to specify a global variable. When this is a text field, turn the microagent on and off by entering true or false.

Standard Microagent Name

This is the name for the standard microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used, COM.TIBCO.ADAPTER.adb.%%deployment%%.%%InstanceId%%.

The value for the %%deployment%% global variable can be set or modified by selecting the session icon and then clicking the Global Variables tab in the project panel.

The %%InstanceId%% variable does not need to be set because it is automatically set at run time by the run-time adapter.

Enable Class Microagent

Allows you to turn on or off the instance-specific or class-specific standard TIBCO Hawk Microagent. You can configure how the class microagent is turned on and off in this field: clicking the globe icon changes the checkbox to a a true/false text field.



Class Microagent Name

This is the name for the class microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used, COM.TIBCO.adb.%%deployment%%.%%InstanceId%%.

Default Microagent Session

This field is predefined and cannot be changed. The session is automatically generated by TIBCO Designer and will be used by the standard, class, and custom microagents.


| 65

Chapter 4 Adapter Service Options

After configuring an adapter instance, select one or more adapter services for the instance. All configuration tasks are performed in TIBCO Designer.

Topics


• Adding Child Tables, page 73

• Publication Service Tabs, page 69

• Subscription Service Tabs, page 83

• Request-Response Service Tabs, page 91


66 | Chapter 4 Adapter Service Options

Overview

The transport type (Rendezvous or JMS) you select for the run-time adapter determines which quality of service, delivery mode, and wire format the service can use. Only options that are compatible with a service’s transport type will be available for selection.

Quality of service, delivery mode, and wire formats are described below.

Quality of ServiceThis is the level of service that determines how messages are sent.

Possible values are:

• Reliable

(TIBCO Rendezvous Transport Type only) Reliable message delivery. Ensures that each multicast or broadcast message is received as long as the physical network and packet recipients are working, and that the loss of a message is detected. This choice can compensate for brief network failures because it can retransmit a message on request if the first attempt failed. This choice is appropriate when message delivery is expected but some loss can be tolerated. Messages are received without explicit confirmation.

• Certified

(TIBCO Rendezvous Transport Type only) Certified message delivery. Offers stronger assurances of message receipt, along with tighter control, greater flexibility and fine-grained reporting. Guarantees that every certified message reaches its intended recipient in the order sent. The message can be sent across network boundaries, and if a network fails, delivery attempts continue until delivery succeeds or until the message's time limit expires.

If certified message delivery is used, data is stored in a ledger file. The size of the ledger depends on several factors, the most important of which is the retention rate of stored data. That is, the ledger grows fastest in response to the cumulative length of undeliverable messages. You must ensure that sufficient disk space is available for the expected size of the ledger.

• Distributed Queue

(TIBCO Rendezvous Transport Type only) A distributed queue is a group of cooperating transport objects, each in a separate process. To obtain load balancing among servers, the adapter uses distributed queues for one-of-n delivery of messages to a group of servers. Each member of a distributed queue listens for the same subject using the TIBCO Rendezvous Distributed


Overview | 67

Queue listener objects. Even though many members listen for each inbound message (or task), only one member processes the message. For details on distributed queues, see TIBCO Rendezvous Concepts.

See Load Balancing Across Configurations on page 166 and TIBCO ActiveEnterprise Concepts for more information.

• Transactional

(Rendezvous and JMS Transport Types) Transactional message delivery provided by TIBCO Rendezvous TX includes store and forward message delivery. Messages arriving simultaneously are buffered, then moved through the network as fast as the hardware capacity allows, as soon as the output device is ready. See the TIBCO Adapter SDK Programmer’s Guide for more information.

Delivery Mode(JMS Transport Type only) The method of delivery for a JMS message. The semantics for these fields are somewhat more complex than the explanation given here. See the TIBCO Enterprise for JMS User’s Guide for more information.

• Persistent

In general, a message marked persistent will be available to a JMS client even if the JMS server goes down. Persistent messages are held in secondary storage in the JMS server and have guaranteed delivery when sent to a topic that has durable subscribers. (If a topic has no durable subscribers, there are no subscribers that need messages resent in the event of a server failure and therefore messages do not need to be saved.) Performance is improved because disk I/O is not required.

• Non-Persistent

(JMS Transport Type only) A message marked non persistent will not be available to a JMS client if the JMS server goes down. These messages are never written to persistent storage.

Wire FormatsServices must use the same wire format to exchange data.

• Rendezvous Message (TIBCO Rendezvous Transport Type only)

The Transactional option is no longer supported. The option is included for backward compatibility with version 5.0 and 4.x adapters.



A self-describing wire format used by TIBCO Rendezvous applications. Control information for validation is not sent in the message. If you use this format, the adapter is compatible with adapters not developed with TIBCO Adapter SDK.

• XML Message (TIBCO Rendezvous and JMS Transport Types)

The XML Message wire format conforms to specifically constructed and fully compliant XML Schema (XSD) based on the existing definition of the TIBCO ActiveEnterprise schema.

• ActiveEnterprise Message (TIBCO Rendezvous Transport Type only)

An externally-described XML wire format supported by the TIBCO Adapter SDK. Control information for validation is sent in the message. If no control information is included, an exception is returned to the subscriber. TIBCO ActiveEnterprise standard wire format provides class information and packing rules for the TIBCO Adapter SDK set of data types. This format allows TIBCO ActiveEnterprise components to perform extra validation on messages sent or received.

See the TIBCO Adapter SDK Programmer’s Guide for details about the control information generated and sent with TIBCO ActiveEnterprise messages.


Publication Service Tabs | 69

Publication Service Tabs

When running as a publisher, the adapter extracts data from the changed rows from database tables and publishes them on appropriate subject names.

You can configure parameters under the following tabs:

• Configuration Tab on page 69

• Tables Tab on page 71

• Publisher Options Tab on page 78

• Advanced Tab on page 82

Configuration TabThe wire format for the publication and subscription services must be the same, otherwise an error will occur.

Name

You can use the default name or replace it with a name of your choice. Note the following restrictions:

• A service name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name.

• A service name cannot use global variables.

Transport Type

Select the transport type (JMS or TIBCO Rendezvous) to be used by the run-time adapter. This selection determines which options appear in the rest of the Configuration tab.

The transport can be configured to use a trusted store and identity resource for use in SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field which uses a dialog to perform SSL configuration.

To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.



Quality of Service

(Only available when TIBCO Rendezvous is selected as the transport type) Select the level of service that determines how messages are sent. See Quality of Service on page 66 for a description of these options. • Reliable

• Certified

Wire Format

The wire format in which data will be sent. Note that the wire format for both the publisher and subscriber must be the same, otherwise an error will occur. See Wire Formats on page 67 for a description of these formats.

• ActiveEnterprise Message (TIBCO Rendezvous transport type only)

• Rendezvous Message (TIBCO Rendezvous transport type only)• XML Message

Connection Factory Type

(Only available when JMS is selected as the transport type) Connection Factory objects create JMS connections for sending and receiving messages. Available choices are:

• Topic

Publish-subscribe messaging. A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic.

• Queue

Point-to-point messaging. A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not.

Delivery Mode

(Only available when JMS is selected as the transport type) The delivery mode for each message sending operation. See Delivery Mode on page 67 for a description of each mode.• Persistent

• Non-Persistent



Tables TabYou must set publisher table options before configuring other publisher options.

Source table names can be qualified with a database user name. To access tables in other schemas, the database user specified in the Design-time Connection Tab on page 46 tab must have the proper set of permissions granted. This is described in Referencing an External Schema on page 73.

Icons

• Add Table — Click to display a dialog box that list tables available to the database user specified in the adapter Connection tab. Select the source table to publish from when data is inserted into it.

• Add Child Table — Displays a dialog box from which a secondary table can be added to the configuration.

• Add Table from Other Schema — Allows you to add a table from a different schema than the current database user schema. For instructions on granting access privileges to an external schema, see Referencing an External Schema on page 73.

• Remove Table — Deletes the selected table from the list.

• Re-find Tables from Database — Causes TIBCO Designer to refresh stored table schema information by retrieving new information from the database.

If a primary key is not defined for a table, the update and delete triggers will not be generated for the table. To define a primary key for the table, select the User Key column in a table row. The update and delete triggers will then be defined.



• Load Table Schema from Database — Allows you to load a database table schema, convert it into a TIBCO ActiveEnterprise schema, and store it in the schema folder of an instance.

Allow Key Columns Only

When this box is checked, child columns are joined only to a key column. When unchecked, child columns can be joined to any column.

Select/Deselect All Columns to Publish

When this box is checked, all of the boxes in the Use column are checked, so all columns in the tables are published. Unchecking this box unselects all of the columns. You can also individually check and uncheck the Use boxes.

Tables and Columns

The loaded tables and columns.

indicates a table or child table.

indicates a normal column.

indicates a User Key column.

Type

The primitive type.

AE Type

The primitive type mapped to an TIBCO ActiveEnterprise type.

User Key

Click to define the column as a user key.

Update Trigger?

Check the box to fire a trigger when an UPDATE statement changes a value in the column.

Use?

Click to publish this column when data is changed.



Join To

The name of a parent table column to join to for parent-child relationships.

Referencing an External Schema

To reference an external schema in TIBCO Designer, the default schema must have the proper access privileges. These are set in a command line. In the following syntax, adb_schema refers to the default schema in create_user.sql.

For Oracle, log in as system and grant create any trigger and drop any trigger permissions to the default schema. For example:

grant create any trigger to adb_schemagrant drop any trigger to adb_schema

In addition, Oracle and Sybase users must have permission to SELECT from a source table in an external schema. If table relationships are used, SELECT permission is required for both parent and child tables. SELECT, INSERT, UPDATE, and DELETE permissions are required for accessing a destination table in an external schema.

For Sybase, execute the following before creating catalog tables for the external schema:

sp_role "grant", sa_role, adb_schema

For SQL Server 7.0 and 2000, log in as sa and then execute the following before creating catalog tables for the external schema:

use masterEXEC sp_addsrvrolemember 'adb_schema', 'sysadmin'

For DB2 on AS400 you can avoid table access problems by changing the ActiveDatabase user authority to *ALLOBJ.

Adding Child TablesThis section describes how to add a related child table definition for publishing data.

Data models typically contain tables that share column data through a relationship. You can configure a publishing table to include related data from another table when it publishes. Data from the related table is not copied into the publishing table, but is fetched by reference.

When rows are inserted into the publishing table, a message that includes data from the source table and related (child) table is published. On the subscriber side, a corresponding table with the same columns as the child table associated with the publishing table must be specified.



Adding child tables requires two separate procedures, one for the publisher adapter and another for the subscriber. First, you add child tables for the source table, then you add child tables for the destination table.

The database schema must be the same for all tables, but the table names can be different. If the child table associated with the publishing table and the child table associated with the destination table have different names, you must set a mapping between the child tables.

The following restrictions apply to parent and child tables:

• The child table in the source database and child table in the destination database must have the same columns.

• Currently, child tables can be defined for publishing tables configured as follows:

— TIBCO Rendezvous Transport type using the TIBCO ActiveEnterprise wire format

— JMS Transport type using the XML wire format

• When parent-child relationships are defined, a subscriber adapter must use the same repository as the publisher adapter.

When you add a child table, TIBCO Designer creates a class object in the repository for the child table, and an association object for the relationship.

After adding child tables for a subscriber adapter, you create mappings between child tables on the publisher side and child tables on the subscriber side. For instructions, see Child Table Mappings Tab on page 87.

To add child tables for parent-child relationships, do the following in the Publication Service Tables Tab:

1. Click the name of the parent table to select it.

2. Click the Add Child Table icon. The Add Table dialog displays.

3. Select the related child table from the list and click OK.

4. Repeat the above steps to add more child tables.

When all of the child tables are added, you then designate a foreign key column as a key in each child table so that a relationship to the parent table can be defined.

5. Click the User Key checkbox for the foreign key column in the child table to select it. A key icon displays next to the column name.

To enable publishing child table related data, the publisher adapter properties file must have the adb.publishChildData option set to on.



You must also specify the relationship between the primary column in the parent table and the foreign key column in the child table.

6. Click in the Join To field for the child table column, and select the name of the parent table primary key column from the drop-down list.

7. Click Apply.

In the following example, a publication service that publishes newly inserted rows into the source table is created. Publisher Options Tab on page 78 explains how to configure the publisher adapter to publish data by value or by reference.



In the following example, a subscription is created such that received data will be inserted into the SUB_ORDER_DETAILS destination table. All three columns of the destination table are configured to receive data.

The following example shows a child table mapped. The left column (Subscriber Child Table Name) contains the subscriber child table and the right column (Publisher Child Table Name) contains the publisher child table.



DB2/OS390 OptionsThis tab appears when the Vendor field in the Adapter Instance Configuration Tab is set to DB2 OS390.

Database Name

Enter the name of the database that you want to put your publisher table in.

Table Space Name

Enter the name of the table space where the publisher table is located.

Storage Group

Optional. Enter the designator of the storage group that will hold the publisher table indexes.

Buffer Pool

Optional. Enter the name of the buffer pool to be used for indexes.

Index Suffix

Enter a suffix of your choice, up to 13 characters, that the adapter will append to each of the indexes (IDX1_, IDX2_, and IDX3_).

When the DB2 load utility loads rows to the source table, it does not activate the table’s INSERT triggers. Loaded data is not published.



Trigger Suffix

Enter a suffix of your choice, up to 5 characters, that adapter software will append to each of the triggers (T1, T2, and T3).

Publisher Options TabWhen you add a new publishing table, a new entry is inserted into the repository for the publisher adapter. The entry includes the name of a publishing table along with a sequence, stored procedure, and trigger. A class object for the publication is created in the repository.

For each publisher adapter, you must specify a storage option, Publish by Value or Publish by Reference. These options are described next.

Publish by Value

With Publish by Value, all specified columns in the source table are copied to the publishing table. Publishing by value is fast, but does not support some data types, for example Oracle LONG and LONG RAW.

Note the following restrictions on publishing tables when you publish by value:

• Publishing tables cannot contain columns with LONG data types. If you have a source table that contains a column with a LONG data type, that column cannot be specified for inclusion in the publishing table. This is because the trigger generated by the palette cannot refer to the LONG column via the :new construct.

This is an Oracle restriction documented in the Oracle SQL Reference manual. The problem is not detected by Oracle during trigger creation. However, when the trigger fires and it attempts to copy the LONG column value to the publishing table, the database connection will hang for some time and then eventually terminate.

• If you define parent-child relationships between tables, the publishing table that is created for a parent table should not contain a column with a LONG data type. However, a child table can contain a column with a LONG data type. This is because data on child table rows is not copied using the :new construct.

• LONG RAW data is not allowed in the publishing table.

These restrictions do not apply to publishing tables when you publish by reference and LONG or LONG RAW are non-key types.



Publish by Value Example

In the following example, the publishing table P_CUSTOMER is created for the source table, CUSTOMER. When CUSTOMER is updated, the new data will be copied to P_CUSTOMER. The adapter will poll P_CUSTOMER and publish the new data.

Publish by Reference

With Publish by Reference, only key column values are copied to the publishing table. The publish by reference feature allows you to publish data directly from the source table without first copying the data from the source table to a publishing table. A trigger, stored procedure, and publishing table are created, but the publishing table contains the necessary adapter fields and only the key fields of the source table. For more information, see Start or Stop the Adapter on page 111.

The advantage of publishing by reference is that the data to be published is stored just once. Also, data types such as Oracle LONG and LONG RAW are supported for publishing by reference.

In this example, loop detection is enabled. If a subscription exists that uses the same subject and CUSTOMER as the destination table, any changes to CUSTOMER will not be published repeatedly.



A key column or substitute key column is required when publishing by reference, since the publishing table contains only key values. If no column is specified, the publication is not added.

Example

In the following example, the publisher adapter is configured to publish from the P_CUSTOMER table with a key field CUST_ID. The publishing table is created with the necessary fields and the CUST_ID field. When a row in the P_CUSTOMER table is modified, the trigger fires, populating fields and copying the CUST_ID value to the publishing table. When the adapter polls the publishing table, it detects the new row and selects from the P_CUSTOMER table using the CUST_ID value found in the publishing table. Then the message is published.

Storage Mode

• Publish by Value copies all specified columns in the source table to the publishing table.

• Publish by Reference copies only key column values to the publishing table. If no key column is defined in the database, a substitute non-key column must be defined to publish by reference.

To use a view or other database object as the source table, you can configure the adapter to publish by reference object, where key columns are stored in the publishing table and data to publish is selected from the reference object. For details, see Publishing by Reference Object on page 192.



Publishing Table

Name of the database table used to store a copy of data to be published. The table name cannot be qualified by a schema name. The publishing table cannot contain any user-created columns where the column name starts with ADB_. These characters are reserved for use by the adapter.

A common practice is to use the publishing table name prefixed by P_. For example, if your source table is MY_ORDER, its publishing table should be named P_MY_ORDER.

A publishing table name must be less than 64 characters.

Update Mode

Select the method by which tables are updated.

• Update updates a row in the destination table only if the row exists.

• Upsert updates a row in the destination table if the row exists. If no such row exists, it performs an insert.

Enable Loop Detection

Click to enable loop detection and prevent an infinite loop from occurring when the publishing and destination table are the same table. Loop detection is disabled for DB2 on OS/390 because of DB2 on OS/390 feature limitations.

Do Not Generate Triggers

Click to prevent the generation of triggers. Although this option is not recommended, it lets you manually manage the insertion of data into the publishing table.



Advanced Tab

Destination

(Only available when JMS is selected as the transport type in the Adapter Instance Configuration Tab)

The publisher destination. A service uses a default destination generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default destination, make sure the values for Domain and Deployment are not empty.

Alternatively, you can manually enter a destination in this field. The destination does not have to be predefined in the JMS Server, and it can be static or dynamic.

See the TIBCO Enterprise for JMS User’s Guide for information about destinations.

Message Subject

(Only available when TIBCO Rendezvous is selected as the transport type in the Adapter Instance Configuration Tab)

Publisher subject. By default, a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field.

See TIBCO Rendezvous Concepts for information about specifying subject names.

Endpoint Reference

Displays the endpoint reference. Click the Browse icon to change the endpoint reference, the Go To icon to reconfigure the existing reference, or the Delete icon to delete the reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.

Class Reference

Click the Go To icon to reconfigure the existing reference. "Clear reference" can be used to remove the reference under Endpoint Reference. Class reference objects are explained in TIBCO Designer Palette Reference.


Subscription Service Tabs | 83

Subscription Service Tabs

When running as a subscriber, the adapter listens on a subject, receives messages and updates the relevant tables in its associated database. The data is then available to other applications that have access to the database.



• Table Tab on page 85

• Child Table Mappings Tab on page 87

• Subscriber Options Tab on page 89


Configuration Tab

Name

Type a name unique among all subscribers defined for this project. You can use the default name or replace it with a name of your choice.

• A service name must use alphanumeric characters, including underscore (_). You cannot use a blank space. The entire instance name must be less than 80 characters.


Transport Type

Select the transport type (JMS or TIBCO Rendezvous) to be used by the run-time adapter. This selection determines which options appear in the rest of the Configuration tab.





Quality of Service

(Only available when TIBCO Rendezvous is selected as the transport type) Select the level of service that determines how messages are sent. See Quality of Service on page 66 for a description of these options.

• Certified

• Reliable


Wire Format


• Rendezvous Message (TIBCO Rendezvous only)

• XML Message (TIBCO Rendezvous or JMS)

• ActiveEnterprise Message (TIBCO Rendezvous only)


Connection Factory objects create JMS connections for sending and receiving messages.

• Topic (JMS only)

A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe.

• Queue (JMS only)

A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point.

Delivery Mode

(Only available when JMS is the transport type and Topic is the connection factory type) The delivery mode for each message sending operation. See Delivery Mode on page 67 for a description of each mode.• Persistent

• Non-Persistent



Table TabYou must set subscriber table options before configuring other subscriber options.

An incoming message need not contain data for all the columns defined in the subscriber table. An adapter can be configured to expect only a subset of the columns. The adapter checks the repository for attributes defined in the subscriber table's class object definition. When a message arrives, the adapter iterates through the attributes in the subscriber table’s class object definition and looks for those same attributes in the incoming message.

Subscriber table names can be qualified with a schema name, such as SCOTT.EMP. To access tables in other schemas, the database user defined in the adapter Connection tab must have the proper set of permissions granted. For details, see page 10.

When configuring the destination table, subscribe only to columns that should be updated. If you subscribe to a column that should not be updated and a message arrives with no data for that column, a NULL will be written to that column. For example:

• If a source table is configured to send data for columns, c1, c2 and c3 and the destination table is configured to receive data for columns c1, c2, c3, c4, and c5:

— For the TIBCO Rendezvous message wire format, columns c1, c2, and c3 will get the data and columns c4 and c5 will get a NULL value.

— For the TIBCO ActiveEnterprise message and XML message wire format, columns c4 and c5 will be ignored and take on whatever default values they are supposed to have.

• If a source table is configured to send data for columns, c1, c2, and c3 and the destination table is configured to receive data for columns c1, c2, and c3 but not configured to receive data for columns c4 and c5, columns c4 and c5 will retain the defaults applicable to both tables.

When the publisher table is configured to use parent-child relationships, the subscriber adapter must use the same repository as the publisher adapter.



Add Table — Click to display a dialog box that list tables available to the database user specified in the adapter Connection tab. Select the table to be used as the subscription table where data is inserted when received.

Add Child Table — Displays a dialog box from which a secondary table can be added to the configuration.

Add Table from Other Schema — Allows you to enter a schema. For instructions on granting access privileges to an external schema, see Referencing an External Schema on page 73.

Remove Table — Deletes the selected table from the configuration.

Re-find Table from Database — Causes TIBCO Designer to refresh stored table schema information by retrieving new information from the database.

Allow Key Columns Only — If selected, child columns are joined only to a key colulmn. If unselected, child columns can be joined to any column.

Columns Tables and Columns — Lists the table and columns.

Type — Lists the primitive type.

AE Type — Lists the primitive type mapped to an TIBCO ActiveEnterprise type.

User Key — Click to define as a user key.

Use? — Click to enable the column to be updated when a message arrives. Subscribe only to columns that should be updated. Columns not configured to receive data will retain their default value. For columns that have been configured to receive data but do not get updated:

— In the TIBCO Rendezvous wire format, the columns get a NULL value.

— In the TIBCO ActiveEnterprise and XML wire formats, the columns are ignored in the statement.



Join To — Joins two tables.

Child Table Mappings TabChild tables between a publisher and subscriber must be mapped unless the tables have the same name.

The following example shows a child table mapped. The left column (Subscriber Child Table Name) contains the subscriber child table and the right column (Publisher Child Table Name) contains the publisher child table.

Subscriber Child Table Name

Displays the tables that can be mapped. Entries are automatically created when you add child tables for a subscriber adapter.

Publisher Child Table Name

Click in this column and type the name of a publisher child table. Prefix the table name with a database user if your database requires it.

These options are only active when child tables have been specified on the Table Tab.



Subscriber Options for DB2 on OS/390This tab appears when the Vendor field in the Adapter Instance Configuration Tab is set to DB2 OS390.

Database Name

Enter the name of the database that you want to put your exception table in.

Table Space Name

Enter the name of the table space where the exception table is located.



Subscriber Options Tab

Exceptions Table

Name of exception table where data is written, if the adapter cannot write to the subscriber table. This table will hold messages that caused an exception. If the table does not exist, the subscriber adapter creates it. For details, see Exception Table on page 177.

The exception table cannot contain any user-created columns where the column name starts with ADB_. These characters are reserved for use by the adapter.

Pre Commit Stored Procedure

The value entered here represents the name of a stored procedure the subscriber will call after the database insert, update, or delete and prior to commit. You can use this stored procedure as a hook to accomplish further processing inside the database and return the results to the adapter. No value means the adapter will not call a stored procedure.

Reply Sender Quality of Service

If the subscriber must send a reply to the sender, this value identifies the quality of service or delivery mode to use when sending the reply. See Quality of Service on page 66 and Delivery Mode on page 67 for a description of these fields.

• Reliable (TIBCO Rendezvous Transport Type only)

• Certified (TIBCO Rendezvous Transport Type only)

• Persistent (JMS Transport Type only)

• Non-Persistent (JMS Transport Type only)



Advanced Tab

Message Subject

(TIBCO Rendezvous Transport type only)

By default a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names.

Destination

(JMS Transport type only)

The subscriber destination. A service uses a default destination generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default destination, make sure the values for Domain and Deployment are not empty.



Endpoint Reference

Displays the endpoint reference. Click the Browse icon to change the endpoint reference or the Go To icon to reconfigure the existing reference. You can also click the Delete icon to remove the reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.

Class Reference

Click the Go To icon to reconfigure the existing reference. Class reference objects are explained in TIBCO Designer Palette Reference.


Request-Response Service Tabs | 91

Request-Response Service Tabs

This service is often called a Request Reply Server or RPC (Remote Procedural Call) Server. When running as a Request-Response Service, the adapter receives requests from other applications, parses them, calls the appropriate component interface API to set the input fields, then calls another set of component interface APIs to get the output fields. The output fields are wrapped in a schema and sent back to the caller.

A Request-Response Service is renamed ADBServer when you drag its icon into the design panel. Configuration involves specifying its name, quality of service and wire format. A server operation allows the adapter to process requests from client applications and return results in a response to the client.

When using the RPC server, you can configure custom operations. These are configured under the Call Operation Tab.



• Call Operation Tab on page 94


Configuration Tab

Name

Type a name unique among all request-response services defined for this project. You can use the default name or replace it with a name of your choice.

• A service name must use alphanumeric characters, including underscore (_). You cannot use a blank space. The entire instance name must be less than 80 characters.


Transport Type

Select the transport type (JMS or TIBCO Rendezvous) to be used by the run-time adapter. This selection determines which options appear in the rest of the Configuration tab. Only the options that are available with the selected Transport Type, Connection Factory Type, Mode or Wire Format are displayed.





Quality of Service

Select the level of service that determines how messages are sent. See Quality of Service on page 66 for a description of these options.• Certified

• Reliable



Connection Factory objects create JMS connections for sending and receiving messages.

• Topic

Publish and subscribe messaging. A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic.

• Queue

Point-to-point messaging. A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not.

Delivery Mode

(Only available when JMS is selected as the transport type) The delivery mode for each message sending operation. See Delivery Mode on page 67 for a description of Persistent and Non-Persistent.

• Durable (see Persistent)

• Non-Durable (see Non-Persistent)



Mode

The server mode.

• Request Reply is the basic request-reply mode. The server subscribes to the request and publishes the reply.

• RPC allows you to configure an adapter to act as an RPC (remote procedure call) server on behalf of a client.

Wire Format


• Rendezvous Message (TIBCO Rendezvous only)

• XML Message (TIBCO Rendezvous or JMS)

• ActiveEnterprise Message (TIBCO Rendezvous only)

Use Custom Operations

Selecting this checkbox and clicking Apply creates the Call Operation Tab.



Call Operation TabThis tab appears when the mode is set to RPC and the Use Custom Operations box is checked in the Request-Response Service Configuration tab.

Click New to enter data into the fields. After making changes, click Apply.

TIBCO Designer retrieves the signature of each stored procedure from the database.

Name

Enter a unique name for the call operation.

Catalog/Package

(Optional, only applicable to databases that have more than one catalog or package.) The catalog or package in which the procedure resides. This name is used to resolve naming conflicts if more than one catalog or package in the database has the selected procedure with the same name. See your database documentation for more information about catalogs and packages.

Schema

(Optional) The schema in which the procedure resides. This name is used to resolve naming conflicts if more than one schema in the database has the selected procedure with the same name.

Procedure Name

Name of the database procedure to call.

If you change the stored procedure or database connection while editing your project, you must return to this dialog and click Refresh to retrieve the changes from the database.



Select Procedure

Queries the database for available procedures for the Procedure Name field. Clicking this button displays a dialog showing the available procedures.

To select a procedure:

a. Select a call operation from the list on the left. Its input and output parameters, if any, are displayed in the fields on the right side of the dialog.

b. Click Select Procedure.

Maximum Rows

(Optional) The maximum number of rows to retrieve.

One way

(Optional) Check this box if you want to execute this procedure using one-way operation. If left unchecked, the procedure will execute using two-way operation.



Advanced Tab

Message Subject

(TIBCO Rendezvous Transport Type only)

By default a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names.

Destination

(JMS Transport type only)

The subscriber destination. A service uses a default destination generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default destination, make sure the values for Domain and Deployment are not empty.



Reply Subject

Type a TIBCO Rendezvous subject name that the adapter uses to response, if no response subject is specified in the request message.

Endpoint Reference

Displays the endpoint reference. Click the Browse icon to change the endpoint reference or the Go To icon to reconfigure the existing reference. You can also click the Delete icon to remove the reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.

Class Reference

Click the Go To icon to reconfigure the existing reference. Class reference objects are explained in TIBCO Designer Palette Reference.


| 97

Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator Enterprise Edition

Topics


• Create an EAR File in TIBCO Designer, page 99

• Deploy the Project, page 100

• Start or Stop the Adapter, page 102

• Monitor the Adapter, page 103

This chapter provides an overview about deploying, starting, stopping, and monitoring adapter services using the TIBCO Administrator Enterprise Edition web interface. See the TIBCO Administrator documentation set for details about using Enterprise Edition.


98 | Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator Enterprise Edition

Overview

An adapter service can be deployed, started and managed using TIBCO Administrator Enterprise Edition or TIBCO Administrator Repository Edition.

• Enterprise Edition must be used if your adapter is part of a TIBCO BusinessWorks process.

• Repository Edition is used for adapters that do not participate in TIBCO BusinessWorks processes. If you are using Repository Edition, see Chapter 6, Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition, on page 105 for details.

The following table summarizes the features available in each edition.

The modules are optional. That is, Repository Edition can be installed with or without the User Management module. The User Management module is required to set security options for adapter projects.

Table 4 TIBCO Administrator Features

Feature Enterprise Edition

Repository Edition

tomcat web server Yes Yes

TIBCO Administration Server Yes Yes

TIBCO Administration GUI Yes Yes

User Management module Yes Yes

Resource Management module Yes No

Application Management module Yes No


Create an EAR File in TIBCO Designer | 99

Create an EAR File in TIBCO Designer

Generate an Enterprise Archive file (EAR) that contains information about the adapter services to deploy.

The EAR file contains information on what you wish to deploy. This could be one or more adapter services, one or more TIBCO BusinessWorks process engines, or both.

In TIBCO Designer, follow these steps to create an EAR:

1. Configure the adapter services.

2. Drag and drop the Enterprise Archive resource from the palette panel to the design panel. If there are any configured adapter services in your project, an Adapter Archive resource becomes available in the palette panel.

3. Drag the Adapter Archive into the design panel and specify information in the Configuration tab, then click Apply.

4. Go to the Enterprise Archive and click Build Archive to create the archive file.

See Also

See the TIBCO Designer User’s Guide for more information about this procedure. The guide is available from the Designer Help menu.

Building an archive creates the EAR file, which you can then deploy from TIBCO Administrator. If you make changes to the business processes or adapter services included in the archive, you need to rebuild the archive. Saving the project does not affect the archive.



Deploy the Project

Before deploying a project, the machine on which the adapter is installed must be part of a TIBCO administration domain. After you have installed the TIBCO Administration Server, any machine on which you install TIBCO Runtime Agent (required by an adapter) can be added to the administration domain. The TIBCO software installed on the machine is then visible and accessible via the TIBCO Administrator GUI.

When you deploy a project, startup scripts and other information about the different components are sent to the machines to which the components were assigned. The project data store and TIBCO Administration Server are updated with the deployed components.

To deploy a project:

1. Import the EAR file into TIBCO Administrator Enterprise Edition.

2. Assign adapter archives in the EAR file to adapters installed in the administration domain and likewise assign process archives to process engines.

3. Specify startup options for each adapter service.

4. If desired, set up your deployment for fault tolerance by specifying more than one adapter service to run on different machines. The secondary services will run in standby mode until they are needed.

Password Handling

At design-time, the adapter uses a password to connect to the backend application and fetch metadata. At run-time, the adapter uses a password to connect to the back-end application and interoperate with it. If you create a 4.x configuration using TIBCO Designer 5.1, and use the configuration against a 4.x adapter version, some special considerations are required for security.

When deploying the adapter check the Service property of the global variable in the global variables section, then go to the Advanced tab of the adapter archive and set the password value under the Run-Time Variables section.

Do not set the password to type Password in the global variables section for adapter configurations that are set to AE Version 4.0 or AE Version 5.0 (in the Configuration tab Version field) or any intermediate version.


Deploy the Project | 101

See Also

See the TIBCO Administrator User’s Guide for an introduction to the TIBCO administration domain and detailed information about the above steps.

See the TIBCO Administrator Server Configuration Guide for fault tolerance information.



Start or Stop the Adapter

The TIBCO Administrator Application Management module allows you to start, and stop deployed applications.

To start an adapter service from the module:

1. In the Administrator GUI left pane, expand Application Management > Application-Name > Service Instances.

2. In the Service Instance panel, select the check box next to the adapter service.

3. Click the Start Selected button.

The status changes from Stopped to Starting up to Started.

4. To stop the adapter service, click the Stop Selected button.

See Also

See the TIBCO Administrator User’s Guide for more information.


Monitor the Adapter | 103

Monitor the Adapter

TIBCO Administrator offers a number of monitoring options. • Specify alerts and TIBCO Hawk rulebases for each machine in the domain.

• Specify alerts and Hawk rulebases for each adapter service.

• View the log for each adapter service.

See Also

See the TIBCO Administrator User’s Guide for information about configuring the above monitoring options.


| 105

Chapter 6 Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition

This chapter explains how deploy an adapter, then start and stop it on the command line. Repository Edition is used to manage adapter projects.

Topics


• Export the Project, page 107

• Create a Properties File, page 108

• Set Properties in Properties File, page 109

• Assign Security Options, page 110

• Start or Stop the Adapter, page 111

• Monitor the Adapter, page 114

• Adapter Properties File, page 115

• Project Locator String, page 126

• Installing the Adapter as a Service on Microsoft Windows, page 131


106 | Chapter 6 Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition

Overview

If your adapter is not used in a TIBCO BusinessWorks process, you can use TIBCO Administrator Repository Edition to manage adapter projects.

If your adapter is used in a TIBCO BusinessWorks project, you must use TIBCO Administrator Enterprise Edition to deploy and manage your projects. See Chapter 6, Deploying and Starting the Adapter Using TIBCO Administrator Repository Edition, on page 105 for details.

See Overview on page 98 for a description of features available in both Enterprise Edition and Repository Edition.


Export the Project | 107

Export the Project

In TIBCO Designer, after configuring, verifying and testing your project, export the project to a server repository.

1. Click Project>Export Full Project.

2. Click the Server Repository tab in Export Project.

3. Provide values for the required fields and click OK.

See Also

See the TIBCO Designer User’s Guide for details about the required fields. The guide is available from the Designer Help menu.



Create a Properties File

Before starting the adapter you must create a properties file or edit the default properties file. Each run-time adapter instance must have a unique properties file. The easiest way to deploy an adapter is to copy the default adadbagent.tra file to a unique name and edit the properties defined in the file.

To create a properties file:

1. Navigate to the adapter installation area:cd <install-path>\tibco\adapter\adadb\5.1\bin

2. Copy the default adadbagent.tra file to a unique name.

3. Edit the predefined properties in the copied file as explained in Set Properties in Properties File on page 109.


Set Properties in Properties File | 109

Set Properties in Properties File

The properties file contains a set of predefined properties. At a minimum, the following properties must be defined in the adapter property file. For a description of all predefined properties, see Adapter Properties File on page 115.

• The tibco.repourl property identifies the project in which the adapter configuration is defined.

• The tibco.configurl property identifies the adapter instance to start.

• The application.args property identifies the properties file to pass to the adapter.

• The application.start.dir property identifies the working directory for the adapter.

See Also

Adapter Properties File on page 115

tibco.repourl [email protected] rvpubapplication.args adbagent -system:propFile

C:/tibco/adapter/adadb/5.1/bin/adbagent.traapplication.start.dir C:/tibco/adapter/adadb/5.1/bin/



Assign Security Options

You must have installed TIBCO Administrator Repository Edition with the User Management module to assign security options. Setting security options is not required, but recommended.

The User Management module allows authorized users to specify security options for a TIBCO administration domain. Security has two components:

• Authentication. Specify users and passwords.

• Authorization. Give users access to individual components in the TIBCO administration domain.

By default, the administrative user for the administration domain has privileges to create users and assign privileges. That user can create additional users with the same full access privileges if appropriate.

Roles

TIBCO Administrator allows you to create a roles tree and assign users to one or more roles. You can then perform authorization on a per-role basis.

This capability is critical, for example, if a large number of users need read access to information about running projects but only a few users should be authorized to start and stop the project.

Authorization

TIBCO Administrator allows privileged users to authorize users for GUI Access or Data Access (or both).• GUI access is given on a per-tab basis. For each tab you can select in the

TIBCO Administrator GUI, you can specify which users are allowed read or write privileges.

• Data access is given on a per-data store basis. A repository data store is associated with each project. You can set various levels of access (read, write, variables) for data stores of each deployed project and for the system data store.

See Also

See the TIBCO Administrator User’s Guide for details about creating roles and authorizations.


Start or Stop the Adapter | 111

Start or Stop the Adapter

The run-time adapter can be run as a console application on all platforms. On Microsoft Windows platforms only, the adapter can also be installed and started as a Windows service.

Start the AdapterThe following command line starts the adapter as a console application using the default adbagent.tra properties file. The default file has been edited with the name of the TIBCO Designer project, the adapter instance, and properties file to pass to the application. Because the properties file has the same name prefix as the executable, it need not be specified on the command line.

adbagent --run

You can run the adapter as a console application using a custom properties file. For example, the next command line starts the adapter instance that is identified in the adbagentpub.tra properties file, which is located in the same directory as the executable. The absolute path name to the properties file must be given if it is located in a different directory than the executable. In other words, if the properties file is not in the default location with the default name, you must explicitly specify the absolute pathname of the properties file on the command line.

adbagent --run --propFile \opt\adapter\adadb\5.1\bin\adbagent.tra

See Adapter Properties File on page 115 for information about changing the properties file.

Adapter Command Line Options

The next table describes the options for the run-time adapter.

Table 5 Run-time Adapter Options

Option Description

--run --propFile fileName Launches the adapter using the specified properties file. This is the default option, if no options are specified on the command line.



Stop the AdapterUse one of the following methods to stop the adapter.

Recommended Methods

• (JMS or TIBCO Rendezvous transport) Using TIBCO Hawk Display, invoke the stopApplicationInstance() or terminateADBAgent() method.

• (JMS or TIBCO Rendezvous transports) From a command window that the adapter is not running in, send a message on the terminate subject.

• (JMS transport) Send a JMS message through a Topic session.

Changing the termination subject is described in General Tab on page 56.

--install --propFile fileName Microsoft Windows Only. Installs the application as a Windows Service using the specified properties file.

If propFile is not given, the properties file prefix must have the same name as the adapter executable prefix.

--uninstall --propFile fileName Microsoft Windows Only. Uninstalls the Windows Service associated with the adapter.


--start --propFile fileName Microsoft Windows Only. Start the Windows Service using the specified properties file.


--stop --propFile fileName Microsoft Windows Only. Stops the Windows Service using the specified properties file.


-version Displays the version of TIBCO Adapter for ActiveDatabase.

Table 5 Run-time Adapter Options

Option Description


Start or Stop the Adapter | 113

Alternative Methods

• (TIBCO Rendezvous transport on Windows only) Use the task manager to stop the adapter.

• (TIBCO Rendezvous transport on UNIX only) Use the command kill -9.



Monitor the Adapter

If you have installed TIBCO Hawk, you can use the methods defined in the adapter’s standard and custom microagents to monitor it.

See Also

For details about monitoring, see Chapter 11, Monitoring the Adapter, on page 231.


Adapter Properties File | 115

Adapter Properties File

The run-time adapter parses a properties file at startup. The default run-time adapter properties file is named adbagent.tra.

The default properties file is located in the install-path\bin subdirectory.

Each line in a properties file is a single property. Each property consists of a key and a value. The key starts with the first non-whitespace character and ends at the first "=", ":", or whitespace character. The value starts at the first character after the equal sign (=). For example:

tibco.configurl=/tibco/private/adapter/test/config/config1tibco.repourl=tibcr://TEST_PROJECTtibco.username=admintibco.password=samplePasswordtibco.clientVar.service=7600tibco.clientVar.daemon=tcp:7600

Properties defined in the properties file override the same properties defined in the project.

Properties File FormatThe following restrictions apply to properties:

• The "!" character may not be used as a comment line indicator. Only the "#" character is recognized.

• The line continuation character is ignored (a value must fit on a line).

• The key may not contain any of the termination characters. Java allows termination characters by escaping the value with a preceding "\" character. TIBCO Adapter for ActiveDatabase does not support this syntax.

Tagging Values for Obfuscation

The presence of a "#" character as the first character in a value (not the key) indicates that the value has been obfuscated or is to be obfuscated. The obfuscation command-line tool prompts for values to be obfuscated when it encounters a value with "#" as the first character in the properties file.

When the obfuscate tool is run, it rewrites the properties file with the obfuscated value in place. See Obfuscating or Encrypting a Password in the Properties File on page 123 for more information.



Run-time Adapter Properties File ParametersProperties are in two categories: Required Properties and Additional Properties. These are listed and described below.

Required Properties

In order for a properties file to be used with a run-time adapter, the following properties must be correct for the adapter’s configuration.

All paths inside a properties file, including Windows directory names, must use forward slashes.

Table 6 Required Run-Time Adapter Properties File Parameters

Property Description

tibco.repourl repourl The absolute pathname to the local repository where the adapter instance is defined. For example: C:/TIBCO/LocalRepositories/repo.dat

For a remote project, the repourl value should use the form tibco.repourl tibcr@name where name is the repository name. For example:tibco.repourl tibcr@ADBRepoDefault

For Unix systems, the path separator should include a single slash, "/". For example: /local/tibco/repo/repo.dat

See Project Locator String on page 126 for more information.

tibco.configurl

relative_path

or

tibco.configurl

absolute_path

The location of the adapter service inside the project file. If a relative path is specified, the adapter service is assumed to be under the default area in the project file (/tibco/private/adapter/). For example, the following value connects to an adapter service named adbpub in the /tibco/private/adapter/ directory:

tibco.configurl adbpub

If an absolute path is specified, the adapter instance is looked up in the repository as defined by the argument. For example:

tibco:configurl /tibco/private/adapter/adbpub

tibco.clientVar.adb.password

The password to connect to the targeted database. This can be obfuscated using the instructions in Obfuscating or Encrypting a Password in the Properties File on page 123.



Additional Properties

You can modify the following parameters as necessary. Properties that start with ntservice are available only on Microsoft Windows platforms.

application.args The properties (.tra) file to pass to TIBCO Adapter for ActiveDatabase. For example:

application.args adbagent --propFile C:/tibco/adapter/adadb/5.1/bin/adbsub.tra

application.start.dir The pathname of the adapter to start. For example:

application.start.dir C:/tibco/adapter/adadb/5.1/bin/

Table 6 Required Run-Time Adapter Properties File Parameters (Cont’d)

Property (Cont’d) Description (Cont’d)

All paths inside a properties file, including Windows directory names, must use forward slashes.

Table 7 Additional Run-Time Adapter Properties File Parameters

Property Description

adb.addCustomHawkMethodsToClassMAgent <on/off>

The property is not set by default. Setting the property to off disallows adding custom methods to the adapter’s standard microagent. Setting to on allows custom methods to be added to the adapter’s standard microagent.

adb.batchPubStatusUpdates on|off -max_rows

When adb.PollingBatchSize is used, this optimizes publishing performance by batching message status updates to the publishing table. Do not use this option when messages are published using a parameterized subject name.

If an adapter instance stops before a batch update is performed, the status column is not updated. As a result, duplicate messages are published when the instance is restarted.



adb.debug The debug printing level. If not specified, the default, 0, is used. Possible values are:

0 - No debug information displayed.

1 - SQL commands executed against the database display.

2 - In addition to 1, the ODBC data source for each SQL command displays.

3 - Displays values for all ODBC placeholders.

adb.dsn ODBC system data source name. If not specified, the system data source name is read from the repository.

adb.EnableReconn Either on or off.

adb.encoding The encoding to use. Required when using a non-ASCII character set, as in globalization. See Overview, page 220, and Relevant Environment Settings, page 229, for more information. Valid values are:

Value

(no value)

ibm-1370

tibx-eucJP

ibm-1386

LATIN_1

ibm-949

ibm-943

tibx-943

UTF8

Corresponding TIBCO Designer selection

ASCII (default)

Big5

EUC-JP

GBK

ISO8859-1

KSC-5601

Shift_JIS (CP943)

Shift_JIS (TIBCO)

UTF8

adb.password Password for the user account used to access your database. If not specified, the password stored in the repository is used.

adb.perfMon Either on or off. The default is off.

Table 7 Additional Run-Time Adapter Properties File Parameters (Cont’d)




adb.PollingBatchSize Applies only to publisher instances. Limits the amount of messages to be picked up. The value indicates the number of parent rows to fetch for a poll interval. The default value, 0, indicates that all new rows should be fetched.

adb.PollingInterval Specific polling period. Applies only to publisher instances. If not specified the default, 10 seconds, is used.

adb.pubBatchConfirmSize Applies only to publisher instances with publications that use certified message delivery. Optimizes performance by batching message status advisories to the publishing table. The value indicates the number of advisory messages to include in a single batch.

Do not use this option when messages are published using a parameterized subject name.

Note: If an adapter instance stops before a batch update is performed, the status column is not updated. As a result, messages that were successfully published might still have a status of P (pending) in the publishing table when the adapter instance is restarted. In this case, the ledger file contains the correct status information. A smaller value for this property decreases this risk.

adb.pubBatchConfirmTimeout Applies only to publisher instances with publications that use certified message delivery. This property specifies the number of milliseconds to wait before updating the status column. After this interval, an update is performed even if the batch size value is not reached. The default value is 10,000 (10 seconds). A value of 0 means that no timeout interval is used.

Do not use this option when messages are published using a parameterized subject name.

Note: If an adapter instance stops before a batch update is performed, the status column is not updated. As a result, messages that were successfully published might still have a status of P (pending) in the publishing table when the adapter instance is restarted. In this case, the ledger file contains the correct status information. A smaller value for this property decreases this risk.





adb.publishChildData Either on or off. Applies only to publisher instances. Enables publishing of table rows related to the source publishing table. By default, related table rows are not published.

adb.RetryTotal Total number of reconnection attempts.

adb.rvMaxQueueSize Applies only to subscriber instances. Maximum number of messages to allow in the TIBCO Rendezvous event queue. The default value is 0, which means no limit is placed on event queue size.

adb.SleepBetweenRetries Seconds of sleep between two reconnection attempts.

adb.subBatchCommitSize Applies only to subscriber instances. The number of messages to batch before invoking a commit operation. The default is 1 (one).

Note: if messages greater than 32K are published, batching is automatically turned off.

adb.subBatchCommitTimeout Applies only to subscriber instances. The amount of time that can expire after which a batch commit operation is invoked. If not specified the default value of 10 seconds is used.

adb.subBulkInsertSize Applies only to subscriber instances. All incoming messages to insert are stored until this size is reached. Then a bulk insert operation is performed on the destination table. This value must be less than or equal to the value specified for adb.subBatchCommitSize, if used. The default value is 1.

If an update statement is published while messages are being batched, the bulk insert is performed regardless of whether the size value has been reached. After records have been inserted, the update operation is performed.

Note: Do not use this option if LONG, LONG RAW, image, or varbinary records are published.

adb.traceOldMessages Either on or off.





adb.useExceptTable on|off Enables the use of the exception table. The exception table is defined when a subscription is created.

adb.user Database account name used by the adapter to access your database. If not specified, the database username stored in the repository is used.

adb.verbose on|off Verbose mode. Print all available information to the console window or log file location. By default the verbose mode is off.

adb.wchar Default is SQL_C_BINARY. Required when using UTF-8 encoding with an adapter that uses a DataDirect driver to retrieve UTF-8 data from the database.

ntservice.account Username under which to run the Windows Service.

You can use this property to initially set the account for the service, but once the service is installed, use the Services control to change the user account of services.

ntservice.binary.path.absolute Absolute path to the executable that is run when the service is started. For example:

ntservice.binary.path.absolute C:/tibco/adapter/adadb/5.1/bin/adbagent.exe

ntservice.dependencies The number of dependencies.

ntservice.displayname Name to display in the Services control for this Windows Service.

This property is useful if you wish to have multiple Windows Services for the same executable. That is, you may wish to have two adapter running on the same machine. By specifying different service names and display names for the adapters, you can accomplish this.

ntservice.interactive Either true or false. Specifies whether the Windows Service is interactive. Set to false if you are not using a system account.





ntservice.name Name for this Windows Service.

This property is useful if you wish to have multiple Windows Services for the same executable. That is, you may wish to have two adapters running on the same machine. By specifying different service names and display names for the adapters, you can accomplish this.

For example:

ntservice.name adapter_instance_name

ntservice.password Password for the username in the ntservice.account property.

You can use this property to initially set the password for the user account, but once the service is installed, use the Services control to change the password.

ntservice.starttype Start type for this Windows Service. Either manual or automatic. For example:

ntservice.starttype automatic

You can use this property to initially set the start type for the service, but once the service is installed, use the Windows Services control to change the start type of services.

tibco.clientVar Run-time values for global variables defined inside the repository. This value takes precedence over any global value set in the repository. Substitution takes place at run-time.

You append the global variable to tibco.clientVar, then give its value. For example, a global variable named DirLedger is specified as follows: tibco.clientVar.DirLedger

C:/tibco/adapter/adadb/5.1/myledger

Do not include the % character of substitution variables. For example, to set %%RvDaemon%%="tcp:7500", use tibco.clientVar.RvDaemon "tcp:7500".





Obfuscating or Encrypting a Password in the Properties File

Password Handling

At design-time, the adapter uses a password to connect to the backend application and fetch metadata. At run-time, the adapter uses a password to connect to the back-end application and interoperate with it. If you create a 4.x configuration using TIBCO Designer 5.1, and use the configuration against a 4.x adapter version, some special considerations are required for security.

If you plan to run the adapter locally, define the run-time password value to be a global variable. Before starting the adapter, include the run-time password as client variable in the adapter's .tra file and obfuscate it using obfuscate tool. For example, if the password value is defined as %%myPassword%%, create a global variable named myPassword in the global variables section with no value and include the following entry in the adapter's .tra file:

tibco.clientVar.myPassword

tibco.username User name and password used by the repository server to access the project. The password can be obfuscated using the instructions in Obfuscating or Encrypting a Password in the Properties File on page 123.

tibco.password

-version Displays a banner with version information, then exits. This option is for troubleshooting purposes only.



Do not set the password to type Password in the global variables section for adapter configurations that are set to AE Version 4.0 or AE Version 5.0 (in the Configuration tab Version field) or any intermediate version.



Obfuscating a Password

The run-time adapter needs a password to access the backend database. If you have unchecked the Remember Password checkbox in the Design-time Connection tab, the global variable %%adb.password%% is saved in the project. For run-time, you open the .tra file and add the password in clear text in the tibco.clientVar.adb.password=#password property. You can use the obfuscate tool to hide this password so it cannot be viewed by unauthorized users.

To obfuscate the password:

1. Using TIBCO Designer, open the adapter configuration and display the Design-time Connection tab.

2. Uncheck the Remember Password checkbox.

3. Apply the changes and save the project. This saves the global variable %%adb.password%% as the value of the password property in the project.

4. In the run-time adapter properties file, verify that the tibco.clientVar.adb.password=#password property is defined in clear text.

5. Run the obfuscation tool supplied with the adapter against the properties file. This tool is named obfuscate.exe and resides in the TIBCO_home\tra\5.1\bin directory.

The command syntax is:

obfuscate tra_file_pathName

where tra_file_pathName is the absolute pathname of the adapter properties file that contains the tibco.clientVar.adb.password=#password property.

For example, on Windows:

C:\tibco\tra\5.1\bin>obfuscate C:\tibco\adapter\adadb\5.1\bin\adbagent.tra

The password is now obfuscated and you can start the adapter with the changed properties file.

Encrypting a Password

Encryption is only supported for version 5 adapters and higher. If you have a property in a properties file the needs to be encrypted, follow these steps:

1. In the property file, add the #! characters in front of the value you wish to encrypt. For example:

If you don’t want to obfuscate the password, remove the # at the beginning of the password.



Repo.serverPassword = #!mysecret

2. Invoke the obfuscate utility from the command line:

<install-path>/tibco/tra/5.1/bin/obfuscate.exe --propertyfile=<property-file-name>

The next time you open the property file, mysecret will have been replaced with a random sequence of characters.



Project Locator String

This section explains the project locator string that is given as a value to the tibco.repourl, which is specified in the TIBCO Adapter for ActiveDatabase properties file.

There are two types of project locator strings: Server-based Project Locator String and Local Project Locator String. These are described in the next sections.

Server-based Project Locator StringTIBCO Adapter for ActiveDatabase uses a project resource locator string to specify the server-based project location and parameters.

The parameters differ depending on the protocol with which the adapter and server communicate. The two protocols are:

• TIBCO Rendezvous Protocol

• HTTP or HTTPS Protocol

These are described below.

TIBCO Rendezvous Protocol

Examples of TIBCO Rendezvous locator strings are:

tibcr://myInst:service=5456:userName=ann:timeout=4000

tibcr@myInst:service=5456:urlFile=/tibco/props/fredsProps.txt

tibcr://myInst:urlFile=/tibco/props/fredsProps.txt

The fields in an example string are described below. Only the first two fields shown below are required.

tibcr@

myInst

:service=5456

:urlFile=/tibco/props/fredsProps.txt

tibcr:// or tibcr@

Project name

Optional parameters(separated by : )


Project Locator String | 127

The following optional parameters are supported. Each parameter is separated by a colon ( : ).

Table 8 Optional parameters for server-based locator string (TIBCO Rendezvous)

Parameter Description

daemon TIBCO Rendezvous rvd daemon value

service TIBCO Rendezvous rvd service value

network TIBCO Rendezvous rvd network value

rva TIBCO Rendezvous rva host and port

subject Instance discovery subject

discoveryTime Timeout value in seconds for instance discovery

timeout Timeout value in seconds for server requests

operationRetry Number of retries when timeout occurs

userName Any identifier (null or empty implies read only with guest privileges)

password user password for security

regionalSubject TIBCO Rendezvous subject prefix used for regional read-operation in the load balancing mode. For additional information see the chapter on load balancing in the TIBCO Administrator Server Configuration Guide.

typeAccess Type of client connection. Valid values are:

• CLIENT_USAGE_DONT_CARE The default. Client reads until update, then switches to write.

• CLIENT_USAGE_READ_ONLY Client is not allowed to do updates.

• CLIENT_USAGE_READ_WRITE Client can do both reads and updates.

urlFile This can either be a fully qualified path or a relative path. The file can contain any of the optional parameters listed in this table. Property values starting with # are considered obfuscated.

The properties in this file are appended to the repository locator string. If the same property appears in both the locator string and the properties file, the properties in the locator string take precedence.



HTTP or HTTPS Protocol

Examples of HTTP and HTTPS locator strings are:

http://host:8080/administrator/repo?myInst&userName=ann&timeout=4000

https://host:8443/administrator/repo?urlFile=httpsProps.ini&myInst

https://host:8443/administrator/repo?urlFile=httpsProps.ini

The fields in an example string are described below. Note that the port and the &myInst parameters are optional, and the urlFile field is required only for HTTPS.

The following fields are required for HTTP or HTTPS.

https://

host

:8443

/administrator/repo

?

urlFile=httpsProps.ini

&myInst

HTTP or HTTPS

Host name

Port (optional)

Repository locator string

Required character

urlFile (required only for HTTPS)

Optional parameters (separated by & )

Table 9 Required fields for server-based locator string (HTTP or HTTPS)

Field Description

HTTP or HTTPS

Use HTTP// or HTTPS// as appropriate.

Host name Name of the host.

Repository locator string

Location of the repository.

? Required character.

urlFile Required for HTTPS, optional for HTTP. This can either be a fully qualified path or a relative path. The file can contain any of the optional parameters listed below. Property values starting with # are considered obfuscated.



Project Locator String | 129

Remote HTTP and HTTPS clients support the following optional parameters. Each parameter must be separated by the character &.

Local Project Locator StringExample local project locator strings are shown below. Each line shows a separate and valid local project locator string value.

localrepo@c:/tibco/repository/instances/myInst.dat:userName=deborah

./instances/myInst.dat:userName=deborah

c:/tibco/repository/instances/myInst.dat:urlFile=c:/tibco/repository/props/deborah

myProj.dat

myProj

myProj/myrepo.dat

Table 10 Optional parameters for server-based locator strings (HTTP or HTTPS)


port If a port is not specified, a default value is used. This is 8080 for HTTP and 8443 for HTTPS.

timeout Timeout value in seconds for server requests.

operationRetry Number of retries if a timeout occurs.

userName Any identifier (null or empty implies read only with guest privileges)

password User password for security

typeAccess Whether it is read only or read-write. Valid values are:

• CLIENT_USAGE_DONT_CARE—DEFAULT. Client reads until update, then switches to write.

• CLIENT_USAGE_READ_ONLY—Client is not allowed to do updates.

• CLIENT_USAGE_READ_WRITE—Client can do both reads and updates.



The fields in an example local repository string are described below. Note that only the instance name is required; this can be a fully qualified path or a relative path. The localrepo@ and .dat entries are optional, as are any parameters listed in Table 11.

Clients support the following optional parameters separated by colons:

localrepo@

c:/tibco/repository/instances/myInst

.dat

:userName=deborah

Optional

Instance name (required)

Optional

Optional parameters (separated by : )

Table 11 Optional parameters for local repository locator string.


userName Any identifier (if not present or empty makes a read-only client)

urlFile This can either be a fully qualified path or a relative path. The file can contain any of the optional parameters listed in this table. Property values starting with # are considered obfuscated.


typeAccess Type of client connection. Valid values are:

• CLIENT_USAGE_DONT_CARE (default): Client reads until update, then switches to write.

• CLIENT_USAGE_READ_ONLY: Client is not allowed to do updates.

• CLIENT_USAGE_READ_WRITE: Client can do both reads and updates.

• CLIENT_USAGE_REACQUIRE_INSTANCE_LOCK: Client is allowed to write and steal lock if same user

• CLIENT_USAGE_FORCE_INSTANCE_LOCK: Client is allowed to write and steal lock if same user


Installing the Adapter as a Service on Microsoft Windows | 131

Installing the Adapter as a Service on Microsoft Windows

The following command lines show how to install the adapter adbagent as a service, start the service, stop the service, and uninstall the service. Because no properties file is specified, the default properties file, adbagent.tra, is used. In this file, the default service name and service display name are the same: TIBCO Adapter for ActiveDatabase.

• Install the adapter as a service using the service name and service display name specified in the default properties file:adbagent --install

• Start the adapter service:adbagent --start

• Stop the adapter service:adbagent --stop

• Uninstall the adapter service:adbagent --uninstall

Creating Multiple Services for the Same AdapterYou can create multiple services for the same adapter instance by following these guidelines:

1. Create a separate properties file for each service, with a unique name.

2. Define each property in the properties file as described in Adapter Properties File on page 115.

3. In each properties file, provide a unique value for the following Service Name and Display Name properties. (This may be required for load balancing, if the subscriber quality of service is set to Distributed Queue.) The values specified in a file cannot match the values specified in any other properties file.— ntservice.name

— ntservice.displayname

4. Start the adapter instance, specifying the appropriate properties file on the command line. This starts an adapter service with the service name and display name defined in that selected properties file.

5. Run the start command again, specifying a different properties file. Another adapter service is started, using the different service name and display name.



The following example references a properties file named adbone.tra. The service started by this properties file uses the same adapter as in the first example, above, but the service name and display name of the adapter service are as defined in this properties file, not as in the default properties file.

• Install the adapter as a service using the service name and service display name specified in the adbone.tra properties file:adbagent --install --propFile adbone.tra

• Start the adapter service:adbagent --start --propFile adbone.tra

• Stop the adapter service:adbagent --stop --propFile adbone.tra

• Uninstall the adapter service:adbagent --uninstall --propFile adbone.tra


| 133

Chapter 7 Using an Alerter

This chapter explains how to configure and start an alerter for each supported database.

Topics

• Introduction, page 134

• Setting Up and Starting the Alerter on Oracle, page 135

• Setting Up and Starting the Alerter on Microsoft SQL Server, page 138

• Setting Up and Starting the Alerter on Sybase SQL Server, page 140


134 | Chapter 7 Using an Alerter

Introduction

Alerters are supported for TIBCO Rendezvous transport only.

The alerter process is used to asynchronously notify running publisher instances of database changes. The adapter does not need to poll its publishing table for existence of new rows. Use the alerter only when database changes are infrequent.

The procedures can be executed on the SQL command line or through any supported Application Programming Interfaces (the procedures cannot be invoked successfully from within a trigger). The procedures commit the inserts into the database table and notify the adapter of the commit.

Because the alerter process runs against a database instance, not user schema, an adapter instance cannot poll the publishing table name for just one user schema. For example, if the same publishing table exists for two user schemas and two instances are monitoring the same publication table, each instance with a different user, both instances will check the same publication table whenever the alerter checks for changes in the publication table.

Oracle

An alerter for Oracle is available on all operating systems supported by the adapter. The alerter is a separate program that can be used in the TIBCO Adapter for ActiveDatabase environment in cases where changes are infrequent and polling by the publisher adapter would result in unnecessary and expensive operations.

Microsoft SQL Server

An alerter function for Microsoft SQL Server is available on all operating systems supported by the adapter. The procedures are executed on the SQL command line itself, and there is no separate program. The alerter functionality is embedded in a dynamic linked library.

Sybase SQL Server

An alerter function for Sybase SQL Server is available on Microsoft Windows along with Solaris. The procedures are executed on the SQL command line itself, and there is no separate program. The alerter functionality is embedded in a dynamic linked library.

DB2

There is no alerter for DB2.


Setting Up and Starting the Alerter on Oracle | 135

Setting Up and Starting the Alerter on Oracle

The Oracle DBMS_PIPE package sends and receives information between sessions, asynchronously allowing two or more sessions in the same database instance to communicate. The Oracle DBMS_PIPE package must be installed before using the alerter process. See your Oracle documentation for information about installing the Oracle DBMS_PIPE package.

Two stored procedures are available for committing messages when the alerter is used:

• commit_and_notify. Forces a commit operation for all tables.

• commit_and_notify_table table_name. Forces a commit operation for a particular table.

As shown next, an adapter instance is started with polling disabled and the alerter is started using the database account that has access to the publishing table. When a source table is updated with data and the commit_and_notify procedure executed, a trigger copies the data to the publishing table and notifies the DBMS_PIPE that a publishing table has changed. The alerter gets the notification from the DBMS_PIPE and sends a notification message to the adapter that a publishing table has changed. The adapter then queries all its configured publishing tables for the new data and sends it on a subject to TIBCO Rendezvous. One or more instances can be notified.

Figure 5 Diagram of Alerter Operation

If there are multiple publishing tables under the same database account, you can use the commit_and_notify_table procedure to specify that only a particular table be checked by the adapter. This prevents the adapter from needlessly checking all its publishing tables for updates when only one table has been updated with new data. This notification can be sent to one or more instances.

commit_and_notify

Source Table

Publishing Table

DBMS_PIPE

AlerterTIBCO Adapter for

ActiveDatabase

TIBCO Messaging



Before StartingMake sure you have executed the alerter.sql file against the database account used by the adapter, as described in Post-Installation Tasks in the TIBCO Adapter for ActiveDatabase Installation Guide.

In addition, the database account must have execute permission set on the DBMS_PIPE package. To set this, type the following in sqlplus (while logged in under the system account):

SQL> grant execute on dbms_pipe to userid

Oracle Alerter SyntaxUse the following syntax to start the alerter:

adbalerter_ora.exe -dsn dsn -usr user -pwd password -id agent1 agent2 ...agentn

The alerter takes the command line options described below.

Oracle Alerter ExampleThis section describes how to start a publisher adapter with polling disabled, how to invoke the Oracle alerter, and how to execute the commit_and_notify_table stored procedure. It assumes the agentone.tra configuration has its data source name, user account name (demo) and password defined in the repository.

Table 12 Alerter Command Line Options

Option Description

-dsn dsn The ODBC DSN you are connecting to

-usr user Database account name that has access to the publishing table(s) to be monitored. If you need to monitor publishing tables that are under different database accounts, you must start an alerter for each account.

-pwd password Password for the given database account.

-id adapter_instance _name The name of the adapter instance to notify. One or more configuration names can be given, separated by a space character. This option must be last on the command line if more than one instance is to be notified.


Setting Up and Starting the Alerter on Oracle | 137

1. Set the following properties in the properties file as shown:tibco.repourl tibcr@ADB_demoadb.poll 0

2. Start the publisher adapter instance with polling disabled by typing:

adbagent --propFile agentone.tra

3. Start the alerter process for the publisher adapter.

adbalerter_ora.exe -dsn MyDSN -usr demo -pwd demo -id agentone

4. After inserting a message, execute the commit_and_notify_table stored procedure against the publishing table monitored by the publisher adapter. For example:

sqlplus demo/demoSQL> insert into ORDER_TABLE values(111,'Oak Table',499.95);SQL> execute commit_and_notify_table (’PUB_ORDER’);

The procedure puts a message on an Oracle DBMS pipe. The alerter captures this message, and publishes a TIBCO Rendezvous notification message to all publisher configurations that were included on the alerter command line. The publisher adapter then reads its publishing table and sends a message containing the changed data on its configured subject.

This example shows how to tell the adapter instance to poll a single table, PUB_ORDER, for changes. Use the commit_and_notify stored procedure to poll all publishing tables for changes.

5. Terminate the alerter process by executing the following stored procedure:

SQL> execute stop_alerter;



Setting Up and Starting the Alerter on Microsoft SQL Server

On Microsoft SQL Server the alerter mechanism is an extended stored procedure in a dynamic link library (provided with installation media) that is dynamically loaded into SQL Server.

Two stored procedures are available for sending messages when using the alerter:

• notify. Sends a TIBCO Rendezvous message to the given instance or instances that one or more publishing tables have been updated.

• notifytable table_name. Sends a TIBCO Rendezvous message to the given instance or instances that the given publishing table has been updated.

Before StartingA database account must have been created for running the adapter. This is typically done after installation. See the TIBCO Adapter for ActiveDatabase Installation Guide for details.

Alerter SetupBefore using the alerter you must copy the alerter dynamic link library adbalerter_mssql.dll to the Binn directory where SQL Server is installed, add the notify and notifytable external stored procedures to the master database and set execute permission on the procedures for the database account used by the adapter.

1. Open a command window and change directory to the install-path\bin directory.

2. Copy the alerter library to the Binn directory where SQL Server is installed, for example:

copy adbalerter_mssql.dll \Mssql7\Binn

3. Ensure the procedures are not already defined in the master database:

isql -Usa -Ppassword1> sp_dropextendedproc notify2> go1> sp_dropextendedproc notifytable2> go1> DBCC adbalerter_mssql(FREE)2> goDBCC execution completed. If DBCC printed error messages,

contact your system administrator.


Setting Up and Starting the Alerter on Microsoft SQL Server | 139

4. Add the procedures to the master database:

1> sp_addextendedproc 'notify','adbalerter_mssql.dll'2> go1> sp_addextendedproc 'notifytable','adbalerter_mssql.dll'2> go

5. Set access permissions for the database account used by the adapter:

1> grant execute on notify to database_account2> go1> grant execute on notifytable to database_account2> go1> exit

Using the AlerterWhen using the alerter, the adapter instance must be started with polling disabled. In this example, after adding a row in a table monitored by the adapter, the alerter procedure is invoked and the adapter checks for updates in its publishing table. The database server name is itaska and database name is activedb.

1. In a command window, start an adapter instance with polling disabled (set the adb.PollingInterval value to 0 in the properties file):

adbagent --propFile propFilename

2. In another command window, insert a row into the database table being monitored by the adapter, commit the transaction, then invoke the notify procedure:

isql -Uadb -Padb -dactivedb1> insert into ORDER_TABLE values(406,'walnut table',9899.89)2> go 1> execute itaska.master.dbo.notify @agentname='agentone'2> goNotifying: agentone

You can also execute the notify procedure for more then one adapter instance. Each configuration name must be separated using a space character. For example:

1> execute itaska.master.dbo.notify @agentname='agentone agenttwo agentthree'

2> go

The notifytable procedure can be invoked for one or more adapter instances and one publishing table. If the database used by the adapter and master database are on the same database server, the server prefix need not be given.

1> execute itaska.master.dbo.notifytable @agentname='agentone agenttwo',@tablename='P_ORDER_TABLE’

2> go



Setting Up and Starting the Alerter on Sybase SQL Server

On Sybase SQL Server the alerter mechanism is an extended stored procedure in a dynamic link library (provided with the installation media) that is dynamically loaded into Sybase SQL Server. Two stored procedures are available for sending messages when the alerter is used:

• notify. Sends a TIBCO Rendezvous message to the given configuration or configurations that one or more publishing tables have been updated.

• notifytable table_name. Sends a TIBCO Rendezvous message to the given configuration or configurations that the given publishing table has been updated.

Before StartingA database account must be created for running the adapter. This is typically done after installation. See the TIBCO Adapter for ActiveDatabase Installation Guide for details.

Alerter Setup on SolarisBefore using the alerter you must copy the alerter shared library to the Sybase/lib directory, add the notify and notifytable external stored procedures to the master database and set execute permission on the procedures for the database account used by the adapter. The name of the shared library file is adbalerter_sybase.so.

1. Open a command window and change directory to the install-path\bin directory. Copy the alerter library as follows:

cp adbalerter_sybase.so sybase/lib

2. Ensure that the procedures are not already defined in the master database:

isql -Usa -Ppassword1> sp_dropextendedproc notify2> go1> sp_dropextendedproc notifytable2> go1> sp_freedll "adbalerter_sybase"2> go

You may need to shut down and restart your XP SERVER after copying the shared library to the sybase/lib directory.


Setting Up and Starting the Alerter on Sybase SQL Server | 141


1> sp_addextendedproc 'notify','adbalerter_sybase.so'2> go1> sp_addextendedproc 'notifytable','adbalerter_sybase.so'2> go

This example shows how to add procedures on Solaris.



Alerter Setup on Microsoft WindowsBefore using the alerter you must copy the alerter dynamic link library, add the external stored procedures to the master database and set execute permission on the procedures for the database account used by the adapter.

1. Open a command window and change directory to the install-path\bin directory. Copy the alerter library as follows:

copy adbalerter_sybase.dll \Sybase\dll

2. Ensure that the procedures are not already defined in the master database:

isql -Usa -Ppassword1> sp_dropextendedproc notify2> go1> sp_dropextendedproc notifytable2> go1> sp_freedll "adbalerter_sybase"2> go


1> sp_addextendedproc 'notify','adbalerter_mssql.dll'2> go1> sp_addextendedproc 'notifytable','adbalerter_mssql.dll'2> go



You may need to shutdown and restart your XP SERVER after copying adbalerter_sybase.dll to the \Sybase\dll directory.



Using the AlerterWhen using the alerter, an adapter instance must be started with polling disabled. In this example, after adding a row in a table monitored by the adapter, the alerter procedure is invoked and the adapter checks for updates in its publishing table. The database server name is itaska and database name is activedb.

1. In a command window, start the adapter instance with polling disabled (set the adb.PollingInterval value to 0 in the properties file):adbagent --propFile propFilename

2. In another command window, insert a row into the database table being monitored by the adapter, commit the transaction, then invoke the notify procedure:

isql -Uadb -Padb -dactivedb1> insert into ORDER_TABLE values(406,'walnut table',9899.89)2> go1> execute itaska.master.dbo.notify @agentname='agentone'2> goNotifying: agentone

You can also execute the notify procedure for more than one adapter instance. Each configuration name must be separated using a space character. For example:

1> execute itaska.master.dbo.notify @agentname='agentone agenttwo agentthree'

2> go

The notifytable procedure can be invoked for one or more adapter instances and one publishing table. For example:

1> execute itaska.master.dbo.notifytable@agentname='agentone agenttwo',@tablename='P_ORDER_TABLE'

2> go

If the database used by the adapter and master database are on the same database server, the server prefix need not be given.


| 143

Chapter 8 Using the Request-Response Service

This chapter explains the request-response service, load balancing, and Oracle REF data type support features.

See the TIBCO Adapter for ActiveDatabase Examples guide for request-response exercises.

Topics

• Introduction, page 144

• Request-Response Mode, page 146

• RPC Mode, page 154

• Load Balancing, page 164

• Oracle REF Data Type Support, page 168


144 | Chapter 8 Using the Request-Response Service

Introduction

Request-response operations are set up using the Request-Response Service dialog. This dialog is described in Configuration Tab on page 91.

Using request-response semantics, client applications can send SQL statements, stored procedures, or both on a specified subject to an adapter instance. The adapter processes the request and returns the results in a response to the client.

1. A request may be a query to the database or any DDL or DML command to be performed on the database. Multiple statements, procedures or both can be sent in one message.

2. The adapter executes the statement, procedure or both. Requests within a message are processed as a single transaction.

3. The adapter sends back the response to the Inbox, subject or response subject that was set up by the client application. The response consists of a result code or one or more result sets, based on the request. A response can also be an error code or error description, if the request was not successful.


Introduction | 145

Multiple adapter instances can be configured so that any one of the configurations receives and processes the request:

• For a single configuration, the number of threads can be configured that will be responsible for processing application requests. See Load Balancing in a Single Configuration on page 164 for details.

• For multiple configurations, TIBCO Rendezvous Distributed Queuing can be used to balance the load across a number of configurations in a queue. The task will be assigned to the least loaded member of the queue. See Load Balancing Across Configurations on page 166 for details.

Use of Quotes in Microsoft SQL Server

When constructing a request in your application that will be processed by the adapter against a Microsoft SQL Server database, you must take care when using quotes.

For example, the following procedure is part of a request from an application. Double quotation marks are used, which is incorrect. An error will be returned.

select @qry = "Update " + @tablename + " set ORDER_DESCRIPTION = 'UPDATE TEST'" + ", ORDER_PRICE = 10109.25"

The following procedure is the same as above, but uses single quotes. It will be correctly processed.

select @qry = 'Update ' + @tablename + ' set ORDER_DESCRIPTION = ''UPDATE TEST'', ORDER_PRICE = 10109.25'

See Delimited Identifiers in your Microsoft SQL Server documentation for details.



Request-Response Mode

TIBCO Adapter for ActiveDatabase request-response mode supports the Rendezvous, ActiveEnterprise and XML message formats.

Requests

A request can contain one or more SQL statements, stored procedures, or both to be executed as a transaction. The text of the SQL statement follows the conventions for ODBC SQL syntax. All SQL statements supported by the DBMS are allowed and placeholders (represented by a question mark, ‘?’) are permitted in the SQL statement, conforming to the ODBC rules. For performance reasons, it is recommended to use a SQL statement. The ‘?’convention should only be used to bind binary data or call stored procedures.

An adapter instance is configured for request-response activity as described in Request-Response Service Tabs on page 91. In so doing, the adapter listens on the subject on which the application sends requests. The application uses TIBCO Rendezvous or the TIBCO Adapter SDK to send a self-describing message containing a request on the agreed subject to the adapter instance.

The following are supported:

• DDL and DML SQL statements

• Multiple statements or procedures in a single transaction that send a nested TIBCO Rendezvous message

• rv_Send(), rv_SendWithReply() and rv_Rpc() calls

• TIBCO Rendezvous C, C++, and Java APIs

Requests are described in the following sections:

• TIBCO ActiveEnterprise or XML Message Request Format, page 147

• TIBCO Rendezvous Message Request Format, page 147

If rv_SendWithReply() or rv_Rpc() calls are used, the adapter sends the response to the Inbox or subject that was set by the application for the response. Otherwise, the adapter sends the response on the response subject that was set at configuration time.


Request-Response Mode | 147

Responses

A response from the adapter to a client application has a result code and one or more result sets. Each result set contains nested self-describing messages, each of which encodes a result row, such as that returned from a query. A response can also return an error code and error description if the request was not successful.

Responses are described in the following sections:

• TIBCO ActiveEnterprise or XML Message Response Format, page 150

• TIBCO Rendezvous Message Response Format, page 150

TIBCO ActiveEnterprise or XML Message Request FormatIn these formats, the input class is SQL_REQUEST. The SQL_REQUEST class is described below. Also see SQL_STATEMENT Class on page 158.

<object name="SQL_REQUEST" lastModified="1036435805361" id="503"> <assoc name="attribute"> <string name="name" value="STATEMENTS"/> <ref name="attributeType"value="/tibco/public/sequence/ae/class/ae/ADB/adbmetadata/sequence[SQL_STATEMENT]"/> <string name="isKey" value="false"/> <string name="isReadable" value="true"/> <string name="isWriteable" value="true"/> </assoc> <assoc name="attribute"> <string name="name" value="CLOSURE"/> <ref name="attributeType" value="/tibco/public/scalar/ae/any"/> <string name="isKey" value="false"/> <string name="isReadable" value="true"/> <string name="isWriteable" value="true"/> </assoc> <string name="family" value="ae"/> <string name="objectType" value="class"/></object>

TIBCO Rendezvous Message Request FormatThis is an example structure of the nested self-describing request message sent by an application to the adapter.

Request{rv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional closure datarv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statementrv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statementrv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statement. . .}



The closure field is an optional field. If included in the request, the response returns the same closure argument untouched, so the client application can use this information as a means of matching requests with responses.

The value Statement is a TIBCO Rendezvous Message of the following structure:Statement{rv_Name = “sql”, rvmsg_Type = RVMSG_STRING, rvmsg_Data = SQL_statement_with_possible_bind_variablesrv_Name = “maxrows”, rvmsg_Type = RVMSG_INT, rvmsg_Data = Optional_max_number_of_rows_to_fetchrv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_datarv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_datarv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_data. . .}

The value Bind_data is a TIBCO Rendezvous Message with the following structure:Bind_data{rv_Name = "position", rvmsg_Type = RVMSG_INT, rvmsg_Data = position_of_placeholder_starting_with_1_from_left_to_rightrv_Name = "column", rvmsg_Type = RVMSG_STRING, rvmsg_Data = in_format_table-name.column-name_whose_column_type_matches_this_bound_variablerv_Name = "data", rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data}

If the position field is not specified, the order received is used.

Example TIBCO Rendezvous Message Requests

The section contains example requests that are based on SQL statements made by a client application and sent to an adapter instance for processing.

Simple SQL Request Statement

Given that a client application submits the following SQL statement:

INSERT INTO order_table (order_id, order_description,order_price) values (1, ‘Order 1’, 1.10)

The corresponding request could be formatted as a TIBCO Rendezvous Message similar to the following:

{name = “closure” value = optional_closure_argumentname = “stmt” value = { name = “sql” value = “INSERT INTO order_table (order_id, order_description, order_price) values (1, ‘Order 1’, 1.10)” }}



Bind Request Statement

Assume that a client application submits the following SQL statement, where ? is a placeholder for an adbDateTime value:

INSERT INTO order_table (order_id, order_date) values (2, ?)

The corresponding request could be formatted as a message in TIBCO Rendezvous Message format similar to the following:

{name = “closure” value = optional_closure_argumentname = “stmt” value = { name = “sql” value = “INSERT INTO order_table (order_id, order_date) values (2, ?)” name = “bind” value = { name = “order_table.order_date” type = RVMSG_STRING value = “1999-08-20 10:20:01” } }}

To create a bind parameter for binary data, the actual data would be sent as an RVMSG_OPAQUE.

Using Bind Entries

Bind entries are specific only to the stmt {} that contains them. For example, if you want to insert three rows into REPLYTEST, you need to have three stmt {} blocks (and thus, three sets of bind statements):

request: { stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-10-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[3 opaque bytes]}} stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-11-10 12:10:10"} bind={column="REPLYTEST.BINCOL" data=[4 opaque bytes]}} stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-12-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[5 opaque bytes]}}}

Not every data value sent to an SQL statement must be bound. The client can embed all these values into the actual text of the statement instead. Embedding the values directly into the SQL text results in better performance. However, binary values must be bound. Types such as adbDateTime can either be bound or included in the SQL text by using the native DBMS date conversion function.

For example, in ORACLE, you could use the TO-DATE function to enter a date:

INSERT INTO order_table (order_id, order_date) values (2,TO_DATE(’1999-08-20 10:20:01’, ’YYYY-MM-DD HH24:MI:SS’));



TIBCO ActiveEnterprise or XML Message Response FormatIn the TIBCO ActiveEnterprise Message or XML format, the input class is SQL_BATCHRETURN. This class is described in SQL_ BATCHRETURN Class on page 157.

TIBCO Rendezvous Message Response FormatIf rv_SendWithReply() or rv_Rpc() is used to send the request, the response is sent back on the subject or Inbox that was associated with the request.

If rv_Send() is used to send the request, because no response subject was specified with the request, the response subject set when the adapter was configured is used. To receive a response from the adapter, the client application must listen on the response subject.

The structure of a response message in TIBCO Rendezvous Message format is shown below.

Reply{rv_Name = “status” rvmsg_Type = RVMSG_INT rvmsg_Data = 0rv_Name = “results” rvmsg_Type = RVMSG_RVMSG rvmsg_Data = Resultrv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data}

where Result is a message in TIBCO Rendezvous Message format of the following structure:

Result{name = “row” type = RVMSG_RVMSG value = List_of_columnsname = “row” type = RVMSG_RVMSG value = List_of_columnsname = “row” type = RVMSG_RVMSG value = List_of_columns. . .}

where List_of_columns is a message in TIBCO Rendezvous Message format of the following structure:

List_of_columns{rv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data



rv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_datarv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data. . .}

If the request processing was not successful, the response could also return an error code and error description as shown next:

Reply{rv_Name = “status” rvmsg_Type = RVMSG_INT rvmsg_Data = nonzero_numberrv_Name = “sql” rvmsg_Type = RVMSG_STRING rvmsg_Data = SQL_statement_that_caused_errorrv_Name = “error” rvmsg_Type = RVMSG_STRING rvmsg_Data = error_textrv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data}

The status value is an integer specifying success or error. Possible values are:

0: ok // No error1: noMem // Out of Memory2: notInitialized // Object never initialized3: typeConversion // Type conversion error4: dbNotFound // Database not registered5: serverError // Error reported by server6: serverMessage // Message from server7: vendorLib // Error in vendor's library8: notConnected // Lost connection9: endOfFetch // End of fetch10: invalidUsage // invalid usage of object11: columnNotFound // Column does not exist12: invalidPosition // invalid positioning within object,i.e.bounds err13: notSupported // Unsupported feature14: nullReference // Null reference parameter15: notFound // Database Object not found16: missing // Required piece of information is missing17: noMultiReaders // This object cannot support multiple readers18: noDeleter // This object cannot support deletions19: noInserter // This object cannot support insertions20: noUpdater // This object cannot support updates21: noReader // This object cannot support readers22: noIndex // This object cannot support indices23: noDrop // This object cannot be dropped24: wrongConnection // Incorrect connection was supplied25: noPrivilege // This object cannot support privileges26: noCursor // This object cannot support cursors27: cantOpen // Unable to open28: applicationError // For errors produced at the application

level29: notReady // For future use



Example TIBCO Rendezvous Message Responses

This section has two examples. The first shows a successful query response and the second shows an unsuccessful query response.

Query Example

As an example, assume the SQL statement, SELECT * FROM ORDER_TABLE produces the following result:

SQL> SELECT * FROM ORDER_TABLE;

ORDER_ID ORDER_DESCRIPTION ORDER_PRICE 1 Order 1 1.00 2 Order 2 2.00

In this case, the self-describing message in TIBCO Rendezvous Message format produced by the adapter would have the following structure:

{name = “closure” value = optional_closure_argumentname = “status” value = 0name = “results” value = { name = “row” value = { name = “order_id” type = RVMSG_INT value = 1 name = “order_description” type = RVMSG_STRING value = “Order 1” name = “order_price” type = RVMSG_REAL value = 1.00 } name = “row” value = { name = “order_id” type = RVMSG_INT value = 2 name = “order_description” type = RVMSG_STRING value = “Order 2” name = “order_price” type = RVMSG_REAL value = 2.00 } }}

Error Example

If the request that was processed resulted in an error, the adapter returns a message containing an error code and description as shown below. In this example, assume the SQL statement SELECT * FROM ORDER_TABLE produced an error because there was no table named ORDER_TABLE defined in the database:

SQL> SELECT * FROM ORDER_TABLE;SELECT * FROM ORDER_TABLE *ERROR at line 1:ORA-00942: table or view does not exist



The self-describing message produced by the adapter would have the following structure:

{name = “closure” value = optional_closure_argumentname = “status” value = 5name = “sql” value = “SELECT * FROM ORDER_TABLE”name = "error" value = "[INTERSOLV][ODBC SequeLinkdriver][DB2/400]ORDER_TABLE in *LIBL type *FILE not found.}



RPC Mode

TIBCO Adapter for ActiveDatabase uses the TIBCO Adapter SDK Operations API for RPCServer.

In TIBCO Designer, you can configure an adapter to act as an RPC (remote procedure call) server on behalf of a client. Selecting RPC mode creates an object in the repository describing the RPC server that the adapter instance will start.

This section presents the structure of the TIBCO Repository class objects that provide MOperation support. Based on these class descriptions, you can create an RPC client to send requests to the adapter in the expected structure.

For convenience, class structure is shown in XML format.

Schema Types

Two schema types can be used for the server object created in the repository. For Standard RPC Operation, the standard request and reply object schema are pre-defined by TIBCO Adapter for ActiveDatabase. This schema can be used to describe the input and output of any database request, allowing a request/response service to process database operations on any tables or execute any stored procedures.

In some cases, using a standard schema can make the request/reply service difficult to integrate with third-party applications, as standard request and reply object schema do not describe the actual input and output values of a database operation or a stored procedure. The third-party application has to do its own parsing and mapping of the request and reply objects. The Custom RPC Operation, which allows you to define your operations, can be used in these situations. You can specify the stored procedure to be executed at design time. These operation definitions are stored in the repository in a way that allows easy integration with other applications.

One-way and Two-way Invocation

An RPC operation uses two-way invocation by default, in which it expects a reply from the server. You can make an RPC operation use one-way invocation, where no reply is expected by the server.


RPC Mode | 155

Standard RPC OperationThe repository contains descriptions of the classes and operations provided for MOperation support.

The SQL_OPS class describes the operations that the adapter instance, acting as an RPC server, can handle.

The structure of the server object is:

<servers> <rvCmRpcServer name = "agentNamereqreprvcmRPCServer" session = "agentNamepubreqreprvcmRvCmSession" subject = "ADB.SDK.OPERATION" classRef = "SQL_OPS" /></servers>

Two types of operations are supported, SQL_EXECUTE and SQL_BATCHEXECUTE. SQL_EXECUTE takes a single SQL statement and processes it. SQL_BATCHEXECUTE takes a sequence of SQL statements and processes them as one transaction. The other classes, such as SQL_STATEMENT, SQL_BIND, and SQL_RETURN, describe metadata for the input and output parameters to the operations.

SQL_OPS Class

The structure of the SQL_OPS class is:

<class name = "SQL_OPS"> <operation name = "SQL_EXECUTE" returnClass = "SQL_RETURN"> <parameter name = "STATEMENT" classRef = "SQL_STATEMENT"

direction = "in"> </parameter> </operation> <operation name = "SQL_BATCHEXECUTE" returnClass = "SQL_BATCHRETURN"> <parameter name = "STATEMENTS" classRef =

"sequence[SQL_STATEMENT]"direction = "in" />

</operation> </class>



SQL_RESULTSET Class

The structure of the SQL_RESULTSET class is:

<class name = "SQL_RESULTSET"> <attribute name = "HEADER" class = "sequence[string]"> </attribute> <attribute name = "ROWVALUES" class = "sequence[SQL_ROW]"> </attribute> <attribute name = "OUTBINDS" class = "sequence[SQL_BIND]"> </attribute></class>

SQL_ROW Class

The structure of the SQL_ROW class is:

<class name = "SQL_ROW"> <attribute name = "ROW" class = "sequence[any]"> </attribute> </class>

SQL_RETURN Class

The structure of the SQL_RETURN class is:

<object name="SQL_RETURN" lastModified="1046487158293" id="202"><assoc name="attribute">

<string name="name" value="STATUS"/><ref name="attributeType" value="/tibco/public/scalar/ae/string"/><string name="isKey" value="false"/><string name="isReadable" value="true"/><string name="isWriteable" value="true"/>

</assoc><assoc name="attribute">

<string name="name" value="SQL"/><ref name="attributeType" value="/tibco/public/scalar/ae/string"/><string name="isKey" value="false"/><string name="isReadable" value="true"/><string name="isWriteable" value="true"/>


<string name="name" value="ERROR_DESC"/><ref name="attributeType" value="/tibco/public/scalar/ae/string"/><string name="isKey" value="false"/><string name="isReadable" value="true"/><string name="isWriteable" value="true"/>


RPC Mode | 157


<string name="name" value="CLOSURE"/><ref name="attributeType" value="/tibco/public/scalar/ae/any"/><string name="isKey" value="false"/><string name="isReadable" value="true"/><string name="isWriteable" value="true"/>


<string name="name" value="RETURNVALUE"/><ref name="attributeType"

value="/tibco/public/class/ae/ADB/adbmetadata/SQL_RETURNVALUE"/><string name="isKey" value="false"/><string name="isReadable" value="true"/><string name="isWriteable" value="true"/>

</assoc><string name="family" value="ae"/><string name="objectType" value="class"/>

</object>

SQL_RETURNVALUE

<object name="SQL_RETURNVALUE" lastModified="1046487158293" id="204"><assoc name="attribute">

<string name="name" value="OUTBINDS"/><ref name="attributeType"

value="/tibco/public/sequence/ae/class/ae/ADB/adbmetadata/sequence[SQL_BIND]"/><string name="isKey" value="false"/><string name="isReadable" value="true"/><string name="isWriteable" value="true"/>


<string name="name" value="RESULTSETS"/><ref name="attributeType"

value="/tibco/public/sequence/ae/class/ae/ADB/adbmetadata/sequence[SQL_RESULTSET]"/>

<string name="isKey" value="false"/><string name="isReadable" value="true"/><string name="isWriteable" value="true"/>

</assoc><string name="family" value="ae"/><string name="objectType" value="class"/>

</object>

SQL_ BATCHRETURN Class

The structure of the SQL_BATCHRETURN class is:

<class name = "SQL_BATCHRETURN">



<attribute name = "STATUS" class = "string"> </attribute> <attribute name = "RESULTSETS" class = "sequence[SQL_RESULTSET]"> </attribute> <attribute name = "SQL" class = "string"> </attribute> <attribute name = "ERROR_DESC" class = "string"> </attribute> <attribute name = "CLOSURE" class = "any" </attribute></class>

SQL_BIND Class

The structure of the SQL_BIND class is:

<class name = "SQL_BIND"> <attribute name = "POSITION" class = "i4"> </attribute> <attribute name = "TYPE" class = "string"> </attribute> <attribute name = "DATA" class = "any"> </attribute> <attribute name = "NAME" class = "string"> </attribute></class>

SQL_STATEMENT Class

The structure of the SQL_STATEMENT class is:

<class name = "SQL_STATEMENT"> <attribute name = "SQL_STRING" class = "string"> </attribute> <attribute name = "BINDS" class = "sequence[SQL_BIND]"> </attribute> <attribute name = "CLOSURE" class = "any" </attribute> <attribute name = "MAXROWS" class = "i4"> </attribute></class>


RPC Mode | 159

Custom RPC OperationWhen you select Use Custom Operations in the Configuration tab of the Request-Response dialog, you can create custom schema for your operations. You can define the call operations to be executed by the RPC server in advance. The palette automatically generates the input and output schema for the call operation.

The operation takes one input class, REQUEST, which describes the input parameters and other input options for the stored procedure execution. The operation returns a class called REPLY, which describe the output schema of the stored procedure or any error message the agent returns.

Table 13 REQUEST Schema Description

Input Item

Data Type or Classname Description

INBINDS INPUT_BINDS The input parameters of the stored procedure.

OPTIONS INPUT_OPTIONS The input options:

Option Data Type Description

MAXROWS Integer The maximum number of rows to retrieve.

SQL String The SQL string use to execute the stored procedure. This string is automatically generated by the palette.

CACHE Boolean True if user want the agent to cache the statement for performance optimization

PACKAGE String read only, uses the call operation form to modify the package of the stored procedure.

SCHEMA String read only, uses the call operation form to modify the package of the stored procedure.

CLOSURE Any Closure argument. The reply returns this closure argument untouched.



Table 14 REPLY Schema Description

Output Item Data Type or Classname Description

OUTBINDS OUTPUT_BINDS The output parameters of the stored procedure

RESULTSET[1..n]/RESULTSETS

OUTPUT_ROWS/ SQL_RESULTSET

The result set(s) returned by the stored procedure, see section 'Result Set Support' for more description

STATUS String "SUCCESS" if the stored procedure is executed successfully."FAILURE" if there is an error. Error details are stored in the OPTIONS class

OPTIONS CUSTOM_OP_OUTPUT_OPTION

Contains the error description and the SQL statement if an error occurred.

CLOSURE Any Closure argument obtained from the request


RPC Mode | 161

Resultset Support

TIBCO Adapter for ActiveDatabase supports multiple resultsets returned for a stored procedure. The class generated for the resultset output depends on the schema information provided by the JDBC driver.

• For drivers that return valid information of a resultset schema, ADB creates an output class, named OUTPUT_ROW[1..n], for each result set. This is shown in the screen below.

• If a driver does not return valid information for the resultset schema, TIBCO Adapter for ActiveDatabase uses the generic class SQL_RESULTSETS as the output schema, as described in Standard RPC Operation on page 155.

DataDirect JDBC 3.3 drivers only provide valid resultset schema information for Oracle Server version 8.1.7 or higher.



Implementing Client RPC ProgramsTwo sample clients are provided in the install-path\demo\operation directory:

• a sample C++ client program that you can build and change

• a sample RPC client

Creating a Custom RPC Client

There are two tasks in creating a custom RPC client:

1. Write an RPC client program using the TIBCO Adapter SDK. This task is described in the TIBCO Adapter SDK Programmer’s Guide.

2. Create a new entry for the RPC client in the repository. This task is described below.

For more information on RPC server and client endpoint type fields, see TIBCO Designer Palette Reference.

To create a new RPC client entry in the repository:

Perform these steps after writing the client program and configuring the adapter, as described above. Detailed instructions for configuring a generic adapter are in the TIBCO Designer User’s Guide.

1. In TIBCO Designer, drag a Generic Adapter Configuration icon to the design panel.

2. Enter an Instance Name and an SDK AppName for the adapter.


RPC Mode | 163

3. Click Apply.

4. In the project tree panel, expand the GenericAdapterConfiguration icon and click the Adapter Services folder.

5. Drag a Request-Response Invocation Service icon to the designer panel.

6. In the Configuration tab, set the name of the service and transport type of your client service.

7. In the Transport tab, set the message subject, quality of service, and wire format of your client service.

If using the TIBCO Rendezvous message transport, you must use the TIBCO ActiveEnterprise wire format.

8. In the Schema tab, set the classReference to point to the correct class schema.

— For a standard RPC schema, use the following class schema:

AESchemas/ae/ADB/adbmetadata/Classes/SQL_OPS

— For custom RPC schema, use the class schema that corresponds to the server endpoint:

AESchemas/ae/ADB/serviceName/Classes/ADBServer_OPS

9. Click Apply.



Load Balancing

The adapter balances the load of requests coming in from applications in two ways, within a single adapter instance and across multiple adapter instances.

Load Balancing in a Single ConfigurationAn adapter instance performs load balancing within itself by allowing you to specify the number of threads that will be responsible for processing application requests. The number of threads to be spawned is specified in TIBCO Designer for an adapter instance.

To set load balancing parameters for a configuration:

1. In the project tree panel, click the corresponding ActiveDatabase Adapter resource to select it.

The TIBCO Designer window should look similar to the following:

2. Click Show All Tabs.


Load Balancing | 165

3. Display the Adapter Services tab.

4. Change the value of Number of Request-Response Service Threads as needed.

5. Click Apply.

Each request-response service thread is dedicated to listening on an agreed request subject.

1. When a request message is received by the request-response communication thread, it enqueues it into an in-memory queue. Each database request-response thread has a connection to the database using the user name-password combination that was provided to the adapter.

2. When an item is enqueued by the communication thread, one of the database request-response threads picks it up and executes the one or more SQL statements in the message as an atomic transaction.



3. It then composes a TIBCO Rendezvous self-describing response message and sends back a response on a response subject. If the original request was sending using rv_SendWithReply() or rv_Rpc(), the response is sent back on the subject that was specified by the requesting application. Otherwise, the response is sent back on the subject that was set up at configuration time.

Load Balancing Across ConfigurationsTo achieve load balancing across adapter instances, TIBCO Rendezvous Distributed Queueing can be used to assign each application request to exactly one configuration. For example, the following diagram shows three adapter instances each connected to a database server (not shown) that contains replicated data.

Figure 6 Request-Response Load Balancing

The configurations have been set up to use distributed queueing with one configuration acting as the scheduler. Only one of the three configurations will receive an incoming request from an application. The scheduler will assign certified requests to the least loaded member of the queue.

While the request message can be sent with either reliable or certified quality of service, the response message is always sent back using the reliable quality of service.

TIBCO Messaging

Application

Adapter 4

Adapter 3

Adapter 2

Adapter 1(Scheduler)

Request

Request

Request

RequestResponses

Distributed Queue


Load Balancing | 167

A queue member’s load is determined by the number of pending processes that are waiting to be processed by the member’s database request-response thread. After the request is processed, the processing configuration sends a response back to the requesting application. See TIBCO Rendezvous Concepts for information about configuring adapter instances to use distributed queues for one-of-n certified delivery.

Reliable requests in a certified environment use a simpler type of load balancing. In this example, the scheduler distributes the first reliable request to Adapter 2, the second to Adapter 3, and the third to Adapter 4 without evaluating a queue member’s load.



Oracle REF Data Type Support

The adapter supports the use of the REF data type as an OUT parameter in an Oracle stored procedure. The adapter returns a result in the same way as it does a result set from a SELECT query. The exact usage depends on the driver used (DataDirect Connect or Oracle ODBC), as described below.

For example, consider the following PL/SQL procedure:

-- Create a REF cursor procedureCREATE OR REPLACE PACKAGE ORDER_DEMO AS TYPE OrderCurTyp IS REF CURSOR RETURN SUB_ORDER%ROWTYPE; PROCEDURE FindOrders (price IN NUMBER, order_cv OUT OrderCurTyp);END ORDER_DEMO;

CREATE OR REPLACE PACKAGE BODY ORDER_DEMO AS PROCEDURE FindOrders (price IN NUMBER, order_cv OUT OrderCurTyp) IS BEGIN OPEN order_cv FOR SELECT * FROM SUB_ORDER where ORDER_PRICE > price; END FindOrders;END ORDER_DEMO;

Using DataDirect Connect Drivers

When using DataDirect Connect® (Merant) drivers, the procedure is called by leaving the REF cursor parameter out of the procedure's call list. For example, the procedure ORDER_DEMO.FindOrders with an input price of $1.00 can be called through the request program with the following request:

{stmt={sql="{call ORDER_DEMO.FindOrders(?)}" bind={position=1 type="IN" data=1}}}

The REF cursor's data will be returned in the results section of the reply.

Also, ProcedureRetResults=1 must be added to the data source entry in the odbc.ini file.

Using Oracle ODBC Drivers

When using the Oracle ODBC Driver, the procedure is called by including the REF cursor parameters in the call list but not binding them. For example, the procedure ORDER_DEMO.FindOrders with an input price of $1.00 can be called through the request program with the following request:

{stmt={sql="{call ORDER_DEMO.FindOrders(?, ?)}" bind={position=1 type="IN" data=1}}}

The REF cursor's data will be returned in the results section of the reply.


| 169

Chapter 9 Advanced Features

This chapter describes advanced features such as the format of a publishing table, stored procedures and the triggers used to populate publishing tables and adapter instance options.

Topics

• Publishing Table, page 170

• Source Table, page 176

• Exception Table, page 177

• Incremental Parent-child Operation, page 179

• Database Types, page 181

• Subject Names, page 184

• Preregistering a Certified Subscriber, page 186

• Changing the Location of the Ledger File, page 188

• Sending Messages to an Adapter Instance, page 190

• Publishing by Reference Object, page 192

• User Callout Library, page 200

• Publishing in a Commitment Controlled Environment, page 207

• Using a Log File for an Adapter Instance, page 211

• Using Database Cleanup Scripts, page 216

• Change the SQL Statement Terminator (DB2/OS390 Only), page 218


170 | Chapter 9 Advanced Features

Publishing Table

Publishing tables mirror tables that you have identified for monitoring. They contain additional columns, primarily a sequence number and delivery status, which are needed by the adapter to detect new rows. You create a publishing table for each table you want to activate using TIBCO Designer.

In addition to a copy of the source table’s columns, the publishing table has the following additional columns.

Table 15 Publishing Table Additional Columns

Column Name Type Description

ADB_SEQUENCE INTEGER Stores the monotonically increasing sequence number that represents new rows in the publishing table. If a column with this name exists, the number is generated automatically.

ADB_SET_SEQUENCE INTEGER Currently not used.

ADB_SUBJECT VARCHAR2 Used to specify the subject to publish the current row. Length is 255.

ADB_TIMESTAMP DATE Time of row insertion in publishing table that is used to calculate expiration of rows. The timestamp is generated automatically.

ADB_OPCODE INTEGER Operation code used by an adapter instance:

1 indicates INSERT.

2 indicates UPDATE.

3 indicates DELETE.

4 indicates UPSERT. UPDATE if row exists, otherwise INSERT.

10 indicates BYPASS (See Incremental Parent-child Operation on page 179)

If an incoming TIBCO Rendezvous message does not have an operation code, an INSERT occurs.

ADB_UPDATE_ALL INTEGER Currently not used.


Publishing Table | 171

The publication table cannot contain any user-created columns where the column name starts with ADB_. These characters are reserved for adapter use.

Removing Records from the Publication TableAn adapter instance does not remove the records from the publication table automatically, because often that information must be retained for auditing reasons. You can use the following command at the SQL prompt to manually remove records from the given publishing table. The command deletes all rows where ADB_L_DELIVERY_STATUS is C or F.

SQL> delete from publication_table_name where ADB_L_DELIVERY_STATUS = "C" or ADB_L_DELIVERY_STATUS = "F";

To automate the process, you could include this statement in a trigger.

Stored Procedures and Triggers A stored procedure is used to handle changes to data in the source table and send them to the publishing table. This procedure is invoked from a trigger placed on the source table. The trigger is set to fire after each insert, delete, or update. The triggers are generated by the palette.

• The generated stored procedure copies data from the source table to the publishing table, along with the extra columns (specified in the Publishing Table on page 170).

ADB_L_DELIVERY_STATUS CHAR Delivery status of a TIBCO Rendezvous message:

P indicates pending acknowledgement.

N indicates that a new message has arrived, but has not yet been published.

C indicates complete.

F indicates failed.

ADB_L_CMSEQUENCE NUMBER Certified messaging sequence number associated with this message.

ADB_REF_OBJECT VARCHAR When publish by reference object is used, contains the name of the reference object that provides source data.

Table 15 Publishing Table Additional Columns (Cont’d)

Column Name (Cont’d) Type Description (Cont’d)



• The generated trigger invokes the stored procedure for each row inserted into the source table.

If the trigger on a subscription table fails, the insert, delete or update will also fail and the transaction will be rolled back.

Publication ExampleThe following is a listing of the SQL commands used to create a publication. The listing can be found in the demo\demo1\demo_database.sql file. The file shows the stored procedure, and insert, update and delete triggers that are generated for a publication.

-- *******************************************-- TIBCO Adapter for ActiveDatabase-- Demo SQL script -- *******************************************

-- Spool the output of sql commands to a log file spool demo.log

-- *******************************************-- Create sample tables-- *******************************************

-- Publication source tableCREATE TABLE ORDER_TABLE ( ORDER_ID NUMBER PRIMARY KEY, ORDER_DESCRIPTION VARCHAR2(128), ORDER_PRICE NUMBER(10,3));

-- Create the destination tableCREATE TABLE SUB_ORDER ( ORDER_ID NUMBER PRIMARY KEY, ORDER_DESCRIPTION VARCHAR2(128), ORDER_PRICE NUMBER(10,3));

-- *******************************************-- Setup a publication -- *******************************************

INSERT INTO ADB_PUBINFO VALUES ('ADB.agentone.ORDER','agentone','ORDER_TABLE','PUB_ORDER','CERTIFIED','MINSTANCE', -1, -1, 'VALUE', 'YES', 10000, NULL, NULL, NULL, NULL);

CREATE TABLE PUB_ORDER (ORDER_ID NUMBER,ORDER_DESCRIPTION VARCHAR2(128),ORDER_PRICE NUMBER(10,3),ADB_SUBJECT VARCHAR2(255) NULL,ADB_SEQUENCE INTEGER NOT NULL,ADB_SET_SEQUENCE INTEGER NULL,



ADB_TIMESTAMP DATE NULL,ADB_OPCODE INTEGER NOT NULL,ADB_UPDATE_ALL INTEGER NULL,ADB_REF_OBJECT VARCHAR2(64) NULL,ADB_L_DELIVERY_STATUS CHAR NULL,ADB_L_CMSEQUENCE NUMBER(38, 0) NULL)/

CREATE UNIQUE INDEX IDX1_PUB_ORDER ON PUB_ORDER (ADB_SEQUENCE)/

CREATE UNIQUE INDEX IDX2_PUB_ORDER ON PUB_ORDER (ADB_L_DELIVERY_STATUS,

ADB_SEQUENCE)/

CREATE INDEX IDX3_PUB_ORDER ON PUB_ORDER (ADB_L_CMSEQUENCE)/

CREATE SEQUENCE PUB_ORDER_SEQSTART WITH 1INCREMENT BY 1NOMAXVALUENOCYCLECACHE 10/

CREATE OR REPLACE TRIGGER TRI_PUB_ORDER AFTER INSERT OR DELETE OR UPDATE ON

ORDER_TABLE FOR EACH ROW DECLAREupdating_key_fields EXCEPTION;BEGINIF INSERTING THENINSERT INTO PUB_ORDER VALUES (:NEW.ORDER_ID,:NEW.ORDER_DESCRIPTION,:NEW.ORDER_PRICE,NULL,PUB_ORDER_SEQ.NEXTVAL,0,SYSDATE,1,NULL,NULL,'N',-1);END IF;IF UPDATING THENIF UPDATING('ORDER_ID') THENRAISE updating_key_fields;END IF;



INSERT INTO PUB_ORDER VALUES (:OLD.ORDER_ID,:NEW.ORDER_DESCRIPTION,:NEW.ORDER_PRICE,NULL,PUB_ORDER_SEQ.NEXTVAL,0,SYSDATE,2,NULL,NULL,'N',-1);END IF;IF DELETING THENINSERT INTO PUB_ORDER VALUES (:OLD.ORDER_ID,:OLD.ORDER_DESCRIPTION,:OLD.ORDER_PRICE,NULL,PUB_ORDER_SEQ.NEXTVAL,0,SYSDATE,3,NULL,NULL,'N',-1);END IF;EXCEPTIONWHEN updating_key_fields THENraise_application_error(-20300, 'ActiveDB Error: cannot update key fields of source table.');END TRI_PUB_ORDER;/

-- *******************************************-- Setup a subscription-- *******************************************

INSERT INTO ADB_SUBINFO VALUES ('ADB.agentone.ORDER','agenttwo','SUB_ORDER','CERTIFIED','MINSTANCE',NULL,NULL, NULL, NULL, 'SUB_ORDER_EXCEP');

CREATE TABLE SUB_ORDER_EXCEP (ORDER_ID NUMBER,ORDER_DESCRIPTION VARCHAR2(128),ORDER_PRICE NUMBER(10,3),ADB_OPCODE INTEGER NULL,ADB_UPDATE_ALL INTEGER NULL,ADB_ERROR_TEXT VARCHAR(4000) NULL,ADB_ERROR_TIME DATE DEFAULT SYSDATE)/

-- *******************************************



-- Setup request/reply-- *******************************************

INSERT INTO ADB_REQREPINFO VALUES ('ADB.request.agentone', 'agentone', 'ADB.reply.agentone', NULL, 'RELIABLE', 'RVMSG', NULL, NULL, NULL, NULL);

INSERT INTO ADB_REQREPINFO VALUES ('ADB.request.agenttwo', 'agenttwo', 'ADB.reply.agenttwo', NULL, 'RELIABLE', 'RVMSG', NULL, NULL, NULL, NULL);

COMMIT;

Changing the Publication Trigger to Publish a Subset of RowsYou can set up a publication to publish only a subset of the rows within a table. That is, there may be scenarios where it is desirable to publish only if the inserted, deleted, or updated row satisfies certain conditions. While it is possible to use the callout library to do this additional filtering, it is simpler and more efficient to use a trigger that directly tests whether publishing conditions are met.

For Oracle, add a when clause to a row level trigger to test for the desired conditions. For Sybase and Microsoft SQL Server, use the if statement within a trigger body to test for the desired conditions.

For example, you could change the demo.sql trigger described in the previous section to fire only if the ORDER_PRICE value is $1.00 or greater:

CREATE OR REPLACE TRIGGER TRI_P_ORDER_TABLE AFTER INSERT OR UPDATE OR DELETE ON ORDER_TABLEFOR EACH ROW WHEN (new.ORDER_PRICE >= 1.00)



Source Table

If loop detection is enabled, the following column will be added to the source table. Loop detection is explained in Loop Detection on page 11.

The source table cannot contain any user-created columns where the column name starts with ADB_. These characters are reserved for adapter use.


ADB_SOURCE CHAR Used for loop detection. Denotes whether the row was inserted or updated as the result of a TIBCO Rendezvous message, rather than user intervention. See Loop Detection on page 11 for more information.

Valid values are T or NULL.

• T indicates the row is not to be published.

• NULL indicates the row can be published.


Exception Table | 177

Exception Table

If a database restriction or failure occurs, and a subscriber adapter is unable to access its destination table, an exception table can be configured to receive the message. If insertion into an exception table also fails, an error message will display and the adapter instance will terminate. You can build a TIBCO Hawk rulebase that detects when the configuration is down and automatically restarts it when the database is up. See the TIBCO Hawk Administrator’s Guide for details about creating a rulebase.

For bulk insert operations, the agent will insert the unsuccessful rows in the exception table only when an exception occurs. For example, if the agent attempts to perform a bulk insert of 500 rows to the destination table, and the first 300 rows are inserted successfully but the last 200 rows are unsuccessful, the agent will insert only the last 200 rows to the exception table. It will then commit the operation. (The bulk insert operation is described in Adapter Services Tab on page 52.)

In addition to destination table columns, the following columns are added to the exception table.

The exception table cannot contain any user-created columns where the column name starts with ADB_. These characters are reserved for adapter use.


ADB_OPCODE INTEGER Operation code used by the adapter:

1 indicates INSERT

2 indicates UPDATE

3 indicates DELETE

4 indicates UPDATE if row exists, otherwise INSERT.

If an incoming TIBCO Rendezvous message does not have an operation code, an INSERT occurs.

ADB_ERROR_TEXT VARCHAR2 (2000) Text of the error from the database server, ODBC driver, or other source that caused the exception.

ADB_ERROR_TIME DATE Timestamp of the inserted record.

ADB_UPDATE_ALL INTEGER Currently not used.



Using an Exception Table as a Source TableIf you want to publish from an exception table and also want to use that exception table as the source table, do not use the ADB_ERROR_TEXT or ADB_OPCODE column names. Instead, follow these guidelines:

• Create a database view that mirrors the exception table, but rename the ADB_ERROR_TEXT and ADB_OPCODE columns so that they do not begin with "ADB_."

• After renaming the columns, use Publish By Reference Object (see Publishing by Reference Object, page 192) and choose your view as the reference object.


Incremental Parent-child Operation | 179

Incremental Parent-child Operation

To support incremental parent-child operations, each child row has an opcode, that is, an extra ADB_OPCODE field that is added to the child schema. The opcode ADB_OPCODE_BYPASS is used to bypass the current table operation. The adapter determines if the operation is an incremental parent-child operation by checking the first level child opcode. If the first level child opcode is not set, the adapter treats it as a complete operation. For the subsequence child level, if the child opcode is not set, it will inherit the parent opcode.

Mixed parent-child operations are also supported. You can send a message to insert new child rows, update other child rows, and delete other child rows for an existing parent-child object. Following is an example of a mixed parent-child operation:

adb.key{ RVMSG_INT 2 ^type^ 1 RVMSG_INT 2 ^pfmt^ 10 RVMSG_INT 2 ^ver^ 30 RVMSG_INT 2 êncoding^ 1 RVMSG_RVMSG 110 ^prefixList^ { RVMSG_STRING 49 1 "/tibco/public/sequence/ae/class/ae/ADB/abc" RVMSG_STRING 37 default "/tibco/public/class/ae/ADB/abc" } RVMSG_RVMSG 77 ^tracking^ { RVMSG_STRING 30 îd^ "Gi2--4--DGMSk--s-064zzw8L-zzw" RVMSG_STRING 22 ^1^ "adb.key" } RVMSG_RVMSG 1200 ^data^ { RVMSG_STRING 8 ^class^ "S_KEYP1" RVMSG_INT 4 ADB_OPCODE 10 RVMSG_RVMSG 480 ADB_SEQUENCE_S_KEYP2 { RVMSG_STRING 18 ^class^ "sequence[S_KEYP2]" RVMSG_INT 4 îdx^ 1 RVMSG_RVMSG 210 ^1^ { RVMSG_STRING 8 ^class^ "S_KEYP2" RVMSG_INT 4 ADB_OPCODE 10 RVMSG_RVMSG 119 ADB_SEQUENCE_S_KEYP3 { RVMSG_STRING 18 ^class^ "sequence[S_KEYP3]" RVMSG_INT 4 îdx^ 1 RVMSG_RVMSG 58 ^1^ { RVMSG_STRING 8 ^class^ "S_KEYP3"



RVMSG_INT 4 ADB_OPCODE 4 RVMSG_REAL 8 A 1 RVMSG_STRING 2 B "a" RVMSG_REAL 8 C 4 } RVMSG_RVMSG 58 ^2^ { RVMSG_STRING 8 ^class^ "S_KEYP3" RVMSG_INT 4 ADB_OPCODE 3 RVMSG_REAL 8 A 1 RVMSG_STRING 2 B "a" RVMSG_REAL 8 C 4 } } } RVMSG_RVMSG 210 ^2^ { RVMSG_STRING 8 ^class^ "S_KEYP2" RVMSG_INT 4 ADB_OPCODE 1 RVMSG_REAL 8 A 2 RVMSG_STRING 2 B "a" RVMSG_REAL 8 C 4 RVMSG_RVMSG 119 ADB_SEQUENCE_S_KEYP3 { RVMSG_STRING 18 ^class^ "sequence[S_KEYP3]" RVMSG_INT 4 ^idx^ 1 RVMSG_RVMSG 58 ^1^ { RVMSG_STRING 8 ^class^ "S_KEYP3" RVMSG_REAL 8 A 2 RVMSG_STRING 2 B "a" RVMSG_REAL 8 C 4 } } } } }}

When the adapter receives this message, it performs the following database operations in sequence:

1. Bypass the parent table operation

2. Bypass first row operation on child table S_KEYP2

3. UPDATE S_KEYP3 set B = 'a', C = 4 where A = 1;

4. DELETE FROM S_KEYP3 where A = 1;

5. INSERT INTO S_KEYP2 (A, B, C) values (2, 'a', 4);

6. INSERT INTO S_KEYP3 (A, B, C) values (2, 'a', 4);


Database Types | 181

Database Types

The database data types listed in this section are supported.

OracleThe following Oracle data types are supported:

The following ANSI data types in Oracle are supported:

SQL ServerThe following SQL Server data types are supported:

• CHAR • TIMESTAMP

• DATE • RAW

• LONG • VARCHAR2

• LONG RAW • CLOB

• NUMBER • BLOB

• DOUBLE PRECISION • INTEGER

• FLOAT • SMALLINT

• INT • REAL

• BINARY

• BIT

• CHAR

• DATETIME

• DECIMAL

• FLOAT

• IMAGE (publish by reference only)

• INT

• MONEY

• NCHAR

• NTEXT

• NUMERIC

• NVARCHAR

• REAL

• SMALLDATETIME

• SMALLINT

• SMALLMONEY

• TEXT (publish by reference only)

• TIMESTAMP

• TINYINT

• UNIQUEIDENTIFIER

• VARBINARY

• VARCHAR



SybaseThe following Sybase data types are supported:

DB2The following DB2 AS400 data types are supported:

• BINARY • INT • TEXT

• BIT • MONEY • TIMESTAMP

• CHAR • NUMERIC • TINYINT

• DATETIME • REAL • UNIQUEIDENTIFIER

• DECIMAL • SMALLDATETIME • VARBINARY

• FLOAT • SMALLINT • VARCHAR

• IMAGE Publish by reference only)

• SMALLMONEY

• CHARACTER • NUMERIC

• DECIMAL • REAL

• DOUBLE PRECISION • SMALLINT

• FLOAT • TIMESTAMP

• INTEGER • VARCHAR

• LONG VARGRAPHIC


Database Types | 183

Mapping to Database TypesThe adapter converts values fetched from the database to types supported by the wire format. Similarly, data fields received in a message must be converted to meaningful database types before being stored.

The following table shows the mapping used by the adapter for such conversion.

Table 16 Mapping to Database Type

ODBC Type TIBCO ActiveEnterprise Type

TIBCO Rendezvous Message Type

SQL_CHAR

SQL_VARCHAR

SQL_LONGVARCHAR

string RVMSG_STRING

SQL_SMALLINT

SQL_INTEGER

i4 RVMSG_INT

SQL_REAL

SQL_DOUBLE

SQL_FLOAT

SQL_DECIMAL

SQL_NUMERIC

r8 RVMSG_REAL

SQL_BINARY

SQL_VARBINARY

SQL_LONGVARBINARY

binary RVMSG_OPAQUE

SQL_TIMESTAMP dateTime RVMSG_DATETIME



Subject Names

An adapter instance sends and receives messages using TIBCO Rendezvous subject names. Subject names are structured strings of alphanumeric characters. Each subject name is a string of characters divided into elements by the dot (.) character. For example, Tibco.Tsi and sales.accounting.order are valid subject names.

Default subject names are provided in TIBCO Designer. You can change these default values to specify a custom subject name. A default subject is created each time an adapter service is created.

The following are restrictions on subject names:

• Subject names are limited to a total length of 255 characters (including the dot delimiters). Even though TIBCO Rendezvous has a 255-character subject length limit, it is very unlikely that applications will need to use the full length. If you want to run an adapter instance against Microsoft SQL Server, you must design your subject space to conform to the length restrictions.

• There can be at most 100 elements in a subject name. The maximum element length is 255 characters.

• The asterisk (*) and greater than (>) are wildcard characters that can be used by subscriber configurations.

For example, if messages are published on the tsi.sales.sports and tsi.sales.clothing subjects and your subscriber adapter listens on the tsi.sales.* subject, the configuration will get messages sent on both subjects.

• The underscore (_) character is reserved. An underscore and any other unprintable character should not be used in your subject name elements. It is also recommended that you do not use tabs or spaces in subject names.

• It is illegal to incorporate the dot character into an element by using an escape sequence.

• Subject names are case sensitive.

See the TIBCO Rendezvous Concepts manual for a full explanation of subject names.


Subject Names | 185

Parameterized Subject NamesA TIBCO Rendezvous subject name can be created from one or more columns in a publishing table. A subject created this way is known as a parameterized subject. For example, you can use TIBCO Designer to define a publication subject to MYSUBJECT.$COLUMN1.$COLUMN2

where COLUMN1 and COLUMN2 are names of columns in the publishing table. For example:TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION

On publication, a subject is created from the contents of those columns. This allows receiving applications to filter publications based on value of certain fields. Parameterized subject names are supported with certified or reliable delivery.

Parameterized Subject Name Restrictions

• A TIBCO Rendezvous parameterized subject name can be at most 255 characters in length, with each component at most 127 characters. In the previous example, if the ORDER_DESCRIPTION column contains a description value that is longer than 127 characters, the parameter name $ORDER_DESCRIPTION is used as the subject in place of the description value.

• The asterisk (*) or greater than (>) characters or empty strings should not be used as attribute values (varchar, char) in a column that is part of a parameterized subject. Doing so makes the subject invalid.

For example, if the TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION parameterized subject name is defined and the following values are inserted into ORDER_TABLE:

insert into ORDER_TABLE values(111,'*',88.81);

and the following values are inserted into the ORDER_DESCRIPTION table:insert into ORDER_TABLE values(112,'>',99.91);

the publisher would return an error.

• Do not use columns that contain Date types as part of a parameterized subject. Date values are likely to contain characters such as dashes and spaces that can cause problems when used as part of a subject.

• Do not use columns that contain binary types as part of a parameterized subject.

• Do not insert data of Float type as an attribute value in a column that is part of a parameterized subject. Doing so makes the subject invalid.

• If a column should not be published, do not include the column name as part of the parameterized subject name.



Preregistering a Certified Subscriber

You can add one or more certified subscribers, or listeners, for a publisher adapter that sends messages on subjects using the RVCM quality of service. The name of the subscriber is added to the publisher adapter’s preregistered list. The subscriber can be a TIBCO Adapter for ActiveDatabase subscriber, or any other TIBCO Rendezvous subscriber.

A subscriber adapter on the preregister list is certified to receive all messages sent on the specified subject using the RVCM quality of service. If a subscriber is not preregistered, it may miss one or more of the initial messages sent by the publisher adapter.

To preregister a certified subscriber in TIBCO Designer:

1. In the project tree panel, under the publisher adapter, open the Advanced>Sessions>adbadapterInstanceNamervcmRvCmSession endpoint object.

Wildcard TIBCO Rendezvous subject names are not supported for preregistered listeners.


Preregistering a Certified Subscriber | 187

2. Click the publisher endpoint in the design panel.

The Configuration Tab for this endpoint is displayed, as shown below.

3. Verify the name of the certified subscriber in the Preregistered Listeners field: %%Domain%%.%%Deployment%%.adb.%%Adapter_name%%.CM. In this example, the preregistered listener is the subscriber adapter named rvsub.

4. Click Apply.



Changing the Location of the Ledger File

The ledger file provides temporary storage for published messages that are sent by a publisher adapter using the TIBCO Rendezvous certified messaging quality of service. Each message is held in the ledger until an acknowledgement is received from the subscriber that the message has been consumed. If there are many subscribers, the ledger file can grow to a substantial size. In this case, it might be preferable to store the ledger file in a directory other than the default directory (which is install-path/ledger).

To change the location of the ledger file in TIBCO Designer:

1. In the project tree panel, navigate to the open the Advanced>Sessions> adbadapterInstanceNamervcmRvCmSession object, as shown in the previous section, Preregistering a Certified Subscriber.

2. Edit the Ledger File value to point to the new ledger file location.

In the following example the name of the ledger file has been changed to adbdemo2pubrvcm.ldg, and it will be generated in the directory in which you run the adapter instance.


Changing the Location of the Ledger File | 189

When the adapter instance is restarted, it writes the ledger file to the new location. For more information on using TIBCO Designer, see the TIBCO Designer User’s Guide.



Sending Messages to an Adapter Instance

When TIBCO Adapter for ActiveDatabase publishes messages including datetime data, the wire format is handled implicitly since both publisher and subscriber use the same format.

In many scenarios, however, a separate product acts as the publisher, which means that you must explicitly specify the wire format. For example, an adapter instance might subscribe to messages published by another TIBCO ActiveEnterprise product, such as TIBCO BusinessWorks, after some transformation has been performed.

Messages containing datetime data sent to TIBCO Adapter for ActiveDatabase adapters must have that data in a string format. If it is in a different format, the TIBCO Adapter for ActiveDatabase adapter will not be able to process the date values. Formatting dates as strings allows the adapter to handle date values outside the range allowed by RVMSG_DATETIME, January 1, 1970 to January 1, 2034.

The format used by the adbDateTime metadata class is described below.

adbDateTime Object

To view the structure of the adbDateTime class:

1. In the project tree panel, navigate to AESchemas>ae>ADB>adbmetadata>Classes>adbDateTime>dateTime

Do not change any adbDateTime object information in this screen. Use this information to determine how to format the third-party subscriber date value.


Sending Messages to an Adapter Instance | 191


2. Click the adbDateTime entry.

3. Click the dateTime entry.

The format of the c lass is displayed. The input is a string value with one of the following formats:

yyyy-mm-ddyyyy-mm-dd hh:mm:ss.xxx

where xxx represents the millisecond value.



Publishing by Reference Object

When source data is stored in a view or other database object, you can publish this data using the publish by reference object feature. Publishing by reference object is an extension of the publish by reference feature. For a description of publishing by reference, see Publish by Reference on page 15.

In both cases, only key values from the source table are stored in the publishing table. The difference when publishing by reference object is when a row changes in the source table and the associated trigger fires, the adapter fetches data from the reference object, rather than the source table. The name of the reference object is stored in an ADB_REF_OBJECT column in the publishing table. For a description of this column, see Publishing Table on page 170. Publishing by reference object is recommended when a view provides the most efficient access to source data, for example when many levels of nesting exist between a parent and child table.

To configure a publisher adapter to publish data by reference object:

1. Drag the ActiveDatabase Adapter Configuration icon to the design panel or select the resource in the project panel.

2. Drag a Publication Service icon to the design panel.

3. To add a source table for a publisher adapter, do the following in the Tables tab:

a. Click the Add Table icon. The Add Table dialog displays.

b. Select a source table from the list and click OK.

If parent-child relationships are used, follow the steps under Adding Child Tables on page 73 to add child tables.

You must explicitly designate a key column or substitute key column for the reference object, since a reference object has no external designation of the key column.

4. Specify the following options in the Publisher Options tab:

Storage Mode — From the drop-down list, select Publish by Reference.

Publishing Table — Type the table name to use for storage. A common practice is to use the source table name prefixed by P_.

Referred Object — Type the name of the view or other database object to select source data from. To select from a list of tables in the current user schema, click Add. To select an object from a different schema, select Add From.


Publishing by Reference Object | 193

Update Mode — Select the method for updating tables from the drop-down list. Choose Update to update a row in the destination table only if the row exists. Choose Upsert to update a row in the destination table if the row exists and, if no such row exists, perform an insert.

5. Click Apply.

Designating the Key Column

To designate a column of the reference object as the key:

1. In the TIBCO Designer project tree panel, navigate to AESchemas\ae\ADB\adapter_instance\classes\ref_object\key_column. The TIBCO Designer window should look similar to the following:

2. In the Configuration tab, click the Key Field checkbox to select it.

3. Click Apply.

Changing Repository Objects for Parent-Child RelationshipsIf your publication service includes parent-child relationships, you must also add a sequence and association to the metadata stored in the repository. These tasks are described in the following sections.



Adding a Sequence

To add a sequence:

1. In the TIBCO Designer project tree panel, navigate to AESchemas\ae\Classes\ae\ADB\adapter_instance\Classes\reference_object.

2. Drag a Generic Sequence icon from the palette panel to the design panel to add it to the reference object class. The TIBCO Designer window should look similar to the following:

3. In the Name field, type ADB_SEQUENCE_childTableName.



4. In the Select Sequence field, click Browse. The Select Resource dialog displays:

5. Click the name of the sequence that represents the child table for the publication service, for example, sequence[ORDER_DETAILS].

6. Click OK.

7. In TIBCO Designer, click Apply. The sequence is added to the metadata for the reference object.

Adding an Association

To add an association:

1. In the TIBCO Designer project tree panel, navigate to AESchemas\ae\ADB\adapter_instance_name\Associations.

Several associations could display, at least one for the parent table to the child table on the publisher side, and another for the destination parent table to the child table on the subscriber side.



2. Click each of the resource icons that represent the parent-child relationship on the publisher side. For example:

3. In the Configuration tab, click in the Name field and replace the name of the publishing table with the name of the reference object. For example,P_CUSTOMER^ORDER_DETAILS becomes ORDER_VIEW^ORDER_DETAILS.

4. Click Apply.

5. In the project tree panel, double-click the new association name to expand it.



6. In the project tree panel, click Left Association to select it.

7. Enter a Role Name value that contains the reference object name. For example, roleORDER_TABLE.



8. In the Endpoint Class field, click Browse. Navigate to the class that represents the reference object, in this case ORDER_TABLE, and click OK.

9. In TIBCO Designer, click Apply.

ExampleIn the following example, the publisher adapter is configured to publish source data from the CUSTOMER table and its child table, EXTERNAL_ORDER_DETAILS. The relevant key columns are CUST_ID and ORDER_ID.

The publishing table is created with necessary adapter fields, as well as CUST_ID and ORDER_ID fields. When a row in CUSTOMER is modified, the trigger fires, populating fields and copying the CUST_ID and ORDER_ID values, as well as the name of the reference object, ORDER_VIEW, to the publishing table. When the



adapter polls the publishing table, it detects the new row. The adapter then selects the order and customer data from ORDER_VIEW, using the CUST_ID and ORDER_ID values along with the view name found in the publishing table. Then the message is published.

Table to Record Sequence Numbers (DB2 on AS/400)The palette will attempt to create the following table (if it does not exist) to record sequence numbers:

CREATE TABLE library.ADB_SEQTAB (PUB_TABLE VARCHAR(64) NOT NULL, ADB_SEQ NUMERIC(20), constraint ADB.ADB_SEQTAB_KEY primary key (PUB_TABLE))

The table must be journalled.

You can create this table or if journalling is automatically turned on, the palette will create the table automatically.



User Callout Library

The user callout shared library allows the transformation of a message that the adapter publishes into a structure that you want to be published. The shared library can be customized to apply limited transformations to outgoing and incoming messages.

To use the callout library, the TIBCO Adapter SDK must be installed because the callout library uses SDK include files and links with SDK libraries. Additionally, you must use the same TIBCO Adapter SDK version that your adapter instance is using.

If a message is modified before it is sent by a publisher adapter, all subscribers will receive the modified message. If a message is modified before it is received by a subscriber adapter, only that adapter will get the modified message.

For example, at the publisher adapter, a message can be modified to have a field added, or publish an empty message if a certain criteria is met. At the subscriber adapter a message can be modified to be written to the database or not, based on a filter, or have the subject name inserted into the table.

Before a message is sent or received, the adapter checks the callout library. If the callout library has not been modified, the message is passed back to the adapter unchanged. If the callout library has been modified, the message is passed back to the adapter with the modification. After receiving a modified message from the callout library, the adapter instance sends or consumes the message like any other message.

• The altermsg.cpp source file must be edited with your custom code.

• The callout library must be rebuilt for your platform.

The source code is included in your installation media in the install-path\demo\altermsg directory.

If you send or receive messages in the TIBCO Rendezvous Message wire format, the TIBCO Rendezvous Message APIs cannot be used to directly alter those messages. Instead, you will receive an MTree to which various functions can be applied to view or traverse the TIBCO Rendezvous message. If you must change the message, create a new message and pass it back to the adapter using the newmsg argument.


User Callout Library | 201

Using the alterMsgPub and alterMsgSub FunctionsTwo functions are available in the altermsg.cpp source file for creating callouts, alterMsgPub() to create a callout for a publisher and alterMsgSub() to create a callout for a subscriber. Two examples are included in the altermsg.cpp file. You can change the examples for your needs, or write new code in the file. The first example appends a new field to a message. The second example works in conjunction with the demo and returns an empty message if the message meets a certain criteria.

The alterMsgPub() and alterMsgSub() functions are the entry points into the callout library. These two function names and their signatures must not be changed.

The alterMsgPub and alterMsgSub functions allow you to alter messages in the TIBCO ActiveEnterprise Message, TIBCO Rendezvous Message, and XML wire formats. The function signatures are:

alterMsgPub(char * subj,const MTree *msg,MTree **newmsg,MInstance *pInst,MApp *pMapp,MMessageFormat dataformat);

alterMsgSub(char * subj,const MTree *msg,MTree **newmsg,MInstance *pInst,MApp *pMapp,MMessageFormat dataformat);

Both functions share the same set of parameters. However, several parameters are specific to a particular wire format. The following table contains parameter descriptions and a column for each format. If the R column contains an X, use the parameter for TIBCO Rendezvous Message wire format. If the M column contains an X, use the parameter for TIBCO ActiveEnterprise Message wire format. Otherwise, leave the value as NULL.

Table 17 Wire Format Parameters and Descriptions

Parameter R M Description

subj X X Subject on which the message is sent or received.

msg X MTree containing the message to send or receive.

newmsg X New MTree user creates if msg must be altered.



When sending or receiving messages in the TIBCO ActiveEnterprise Message wire format, you must use the pInst argument to change the message.

Using the adbPreCommit FunctionThe adbPreCommit function allows you to perform a custom operation, such as invoking a stored procedure or sending a TIBCO Rendezvous message, just before the transaction is committed. This function is called by the subscriber after all inserts, updates and delete operations have been performed on both parent and child tables.

The function signature is:

adbPreCommit(SQLHDBC connectHandle,MApp *pMapp,MInstance *pInst,MTree *pTree,MMessageFormat dataformat);

The following table contains parameter descriptions.

pInst X MInstance of the message. Alter directly if necessary.

pMapp X TIBCO Adapter SDK MApp structure for this MInstance.

dataformat X X The data format of the message.

Table 17 Wire Format Parameters and Descriptions (Cont’d)

Parameter R M Description

Table 18 adbPreCommit Parameter Descriptions

ParameterTIBCO Rendezvous Format

TIBCO ActiveEnterprise Format

Description

connectHandle X X The database connection handle.

pMapp X X TIBCO Adapter SDK MApp structure for this MInstance.

pInst X MInstance of the message.

pTree X MTree containing the message.

dataformat X X The data format of the message.



Building the Callout LibraryThis section explains how to build the callout library on each supported platform. The next table lists required compilers for each platform.

Building the Callout Library on Microsoft Windows

1. Using Visual C++, create a new workspace and insert a new project into the workspace.

2. In the new project, open the file:

install-path\demo\altermsg\altermsg.dsp

If an adapter is configured to use the adb.subBatchCommitTimeout or adb.subBatchCommitSize options, the custom operation is performed once for each message received. However, the entire transaction is not committed until the size or time-out values are reached. Adapter instances that use the bulk-insert-size option cannot use adbPreCommit. For more information on these options, see Adapter Properties File on page 115.

Table 19 Compilers for Platforms

Platform Compiler

Microsoft Windows

MSVC++ 6.0 with Service Pack 5, 7.0 or 7.1 (.NET)

Solaris 7, 8, 9 CC 5.0 (SPARCworks) or

Sun Forte Developer 6 Update 2 compiler

HP-UX 11, 11i aCC 3.13

AIX 5.1 XLC_r v5.1.0 (You must use the xlC_r compiler)

Linux GNU gcc v2.96.112



3. Select Project>Settings. In the Project Settings dialog box:

a. As shown next, select the C/C++ tab. In Category, select Preprocessor. In Additional include directories type the path to the TIBCO Rendezvous include directory.

b. As shown next, select the Link tab. In Category, select Input. In Additional library path type the path to the TIBCO Rendezvous library directory.

4. Select Build>Build adbaltermsg.dll to create the library.



5. After building the library, change to the install-path\bin directory.

a. Make a backup copy of the existing adbaltermsg.dll library.

b. Copy the new adbaltermsg.dll library into the bin directory.

Building the Callout Library on UNIX

1. Using a text editor open the MakeFile and set the RV_Home environment variable. For example, for Solaris 7:RV_HOME=/usr/tibco/tibrv

2. Using a text editor open the MakeFile and set the SDK_Home environment variable. For example:

SDK_HOME=/local/activedb/sdk50

3. Set the command to invoke your compiler. For example:CC= CC

4. Set the options to be passed to your compiler. For example:DEBUG=-gOPT=-O4

5. Save the MakeFile and execute:% make libadbaltermsg.so

6. After building the library, change to the install-path\lib directory.

a. Make a backup copy of the existing libadbaltermsg.so library.

b. Copy the new libadbaltermsg.so library into the lib directory.



Unique Connection Identifier for Oracle Databases

Within each adapter instance, the adapter typically creates multiple database connections or sessions. Each connection has a different responsibility (such as selecting from the publishing table or inserting into the destination table) and each is identified using a unique connection identifier.

The unique identifier added to each session allows a database administrator to monitor the adapter’s database activity from Oracle by being able to identify what each database connection is doing. The Oracle DBA can query the CLIENT_INFO column of V$SESSION to identify each Oracle connection the adapter is using. The identifiers for each service are:

• InstanceId.ADBPubPolling (publication service polling connection)

• InstanceId.ADBPubUpdate (publication service update connection)

• InstanceId.ADBPubConfirm (publication service confirm connection)

• InstanceId.ADBSubscriber (subscription service connection)

• InstanceId.ADBRequestReply.n (request-response service connection where n is the thread ID)


Publishing in a Commitment Controlled Environment | 207

Publishing in a Commitment Controlled Environment

If desired, you can enable the adapter to publish messages in a commitment controlled environment.

In its standard functionality the adapter generates and attaches database triggers to an application table that is the source for publishing data. A trigger program is activated on a database event on the source table (Insert, Update, Delete) and the trigger program uses the source table data to reflect the database event change on a publishing table.

Therefore, if the source table is being accessed by an application under commitment control, it is critical from a database integrity standpoint that the trigger program be part of the same commitment cycle.

To publish messages in a commitment controlled environment:

These steps assume that the trigger program is being generated by the palette in the RPG ILE language.

1. Once the adapter is configured and saved in TIBCO Designer, the trigger programs will be compiled and attached to the source table. Log on to the AS/400 using a profile that has *PGMR rights to the library and source file where the trigger program is created. The trigger program is always created in a source file called TIBCOSRC that is in a library representing the DB2 collection.

2. Edit the trigger program member in the TIBCOSRC file by adding the keyword 'Commit' on the F-Spec for the publishing table. An example is given below.

FP_EMPL O E Disk Rename(P_EMPL:Pub_Record)F UsrOpnF Commit

Make sure that the application program that is accessing the source table is running with commitment control enabled. Otherwise, the trigger program will encounter a runtime error with this keyword.

3. After editing the trigger program member, save and compile it with options DFTACTGRP(*NO) and ACTGRP(*CALLER). These options ensure that the trigger program runs as part of the calling application program's commitment cycle. The trigger program will run in the application program's activation group. Any database updates done by the trigger program will be done or undone by a Commit or Rollback issued by the application program, thus ensuring database integrity.

This feature applies only to DB2 on AS/400.



4. To have the trigger program run under commitment control, the publishing table (listed in the trigger program) must be journalized. This can be done by using the AS/400 command STRJRNPF. The journal that is being used to log changes to the source table can be used for the publishing table as well.


Using the Adapter with a Revision Control System | 209

Using the Adapter with a Revision Control System

TIBCO Designer supports revision control systems such as MicroSoft Visual SourceSafe and Perforce. If you are using a revision control system, you must manually add some configured resources to the revision control system and check in the resources when completing the instance configuration.

As part of service configuration, the adapter creates schema files in root/AESchemas/ae/adadb. For example, if you configure a service in an adapter configuration Instance1, the following files are created:

Project_root/AESchemas/ae/adb/Instance1.aeschemaProject_root/AESchemas/ae/adb/Instance1/businessObjects.aeschema

When the project is saved and a revision control system has been specified, the adapter displays a warning that additional files were created and should be added to the revision control system. This warning appears only when the files are created for the first time. The warning displays a Go To Resource button that helps in navigating to the resource. You should use the Multi-User>Add Resources to RCS menu command to add these files to the revision control system.

For information about how to use the Multi-User feature in TIBCO Designer, refer to the TIBCO Designer User’s Guide.

Copy, Cut, Paste and Move Operations

To successfully copy and paste a service from adapter Instance1 to Instance2, the adapter configuration and schema files for the Instance2 must be checked out.

To successfully cut and paste a service from adapter Instance1 to Instance2, the adapter configuration and schema files for both Instance1 and Instance2 must be checked out.

To successfully move a service from adapter Instance1 to Instance2, the adapter configuration and schema files for both Instance1 and Instance2 must be checked out.

Regeneration When Moving, Copying and Pasting

• Default subjects are not regenerated to reflect the new instance name when a service is moved.

• Manually changed certified messaging and certified messaging queue ledger file names are regenerated to defaults when a service is moved, or copied and pasted to a new instance.



• If a service associated with a custom session is moved, or copied and pasted, the custom session is not moved, or copied and pasted. The session is regenerated as a default session.


Using a Log File for an Adapter Instance | 211

Using a Log File for an Adapter Instance

By default all error, warning and information messages are printed in the console window in which the configuration was started and to a default log file. The log file can be located anywhere on your file system.

TIBCO Adapter for ActiveDatabase will trace to whatever sink is present in your TIBCO Adapter for ActiveDatabase configuration. If you have the default sinks of stdioSink and fileSink, TIBCO Adapter for ActiveDatabase will write to both the file and stdout.

Fine-Tuning Tracing AttributesThe tracing facility allows you to fine-tune where and what different types of information are sent.

To access tracing attributes for an adapter instance:

1. In the project tree panel, click the corresponding ActiveDatabase Adapter resource to select it.

Only errors that originate in the adapter instance itself are logged in the log file. Errors from other sources, for example TIBCO Rendezvous APIs or TIBCO Adapter SDK APIs, are not logged to a log file, but are printed to the console window where the configuration started.




2. Display the Logging Tab, as shown below.

The Log to Standard I/O checkbox is selected so that trace information can be written to the console window where the adapter instance was started. The log file is generated in the start directory unless specified otherwise in the properties file.

To disable file tracing for the adapter instance, delete this file name and click Apply.



The following checkboxes control the level of trace information that is captured:

• Log Info Messages—Capture error and warning information.

• Log Debug Messages—Capture all available information.

• Log Warning Messages—Capture warning information only.

• Log Error Messages—Capture error information only.

Log File SizeWhen a log file name is specified in the Logging tab, the adapter does the following:

1. Creates a file with no extension, using the file name specified in TIBCO Designer.

2. Redirects all trace statements generated by this configuration to that file until it reaches the default file size of 30 KB.

3. When this file size is reached (that is, as soon as the file is greater than or equal to the limit), renames the current file to file.1 and creates a new file with no extension.

Note that the log file can be slightly larger than the limit because the new file is only created after the limit has been reached.

4. Repeats this process of rolling log files and renaming files each time a new file is generated, until 3 log files exist.

Using Advanced Logging FeaturesThe example in this section shows how to change default log file attributes in TIBCO Designer.

To access advanced logging features in TIBCO Designer:

1. With the Logging tab selected in the Configuration panel, click the Use Advanced Logging checkbox.

With these default settings, the adapter instance overwrites the oldest file after 3 files have been created and the last file reaches 3 KB. For instructions on changing the default settings, see the next section.



2. Click Apply. The following information displays:

3. In the project tree panel, navigate to adapter_instance_name\Advanced\Log Sinks\fileSink.

The TIBCO Designer window looks similar to the following:

File Limit (bytes)

Sets the maximum size of a log file.



File Count

Specifies the maximum number of log files that are created for this adapter instance.

Append Mode

When this box is checked (the default), information is written to the log file in the Append mode, where trace information is appended to existing entries in the file.

Unchecking this box changes to Overwrite mode, where the adapter instance overwrites the current log file the next time the adapter starts.



Using Database Cleanup Scripts

Changing an existing adapter instance typically generates legitimate changes in the database. During this change process, the adapter creates a SQL script for changing the database objects and an associated cleanup script and stores them in the install-path\sql directory. If the legitimate database changes result in error messages, you may need to run these scripts. The messages and procedure for running the scripts are given in this section.

If the scripts created for legitimate database changes are not generated successfully, a message such as the following sample may display.


Using Database Cleanup Scripts | 217

If the scripts created for legitimate database changes are generated successfully but an error occurs while these changes are being saved to the database, a message such as the following sample may display.

To Run the Cleanup Scripts

1. Select each message in the top portion of the message window and read the explanation for it in the bottom portion of the message window.

2. In TIBCO Designer, close the project containing the adapter instance that you changed.

3. Fix the errors that caused the database changes to fail, as indicated by the messages.

4. If necessary, clean up the old database configuration by running the scripts created by the adapter. The scripts are in the sql directory and are named instanceId.sql or instanceId.undo.sql, where instanceId is the name of the adapter instance you changed.

5. Reopen the project in TIBCO Designer.

6. Select the adapter instance you were attempting to change when the errors occurred.

7. Save the project.



Change the SQL Statement Terminator (DB2/OS390 Only)

The SQL statement terminator by default is a semicolon ( ; ), but DB2 trigger statements use embedded semicolons as part of their syntax. Because of this, adapter SQL statements use a pound sign ( # ) as the SQL statement terminator.

When using the adapter in the default (real-time) mode, where repoOnly=false, the SQL statement terminator is not used and no changes are necessary.

However, when running the adapter in batch mode (repoOnly=true), you must change the SQL statement terminator from the default semicolon to the pound sign ( # ) in order to avoid conflicts with DB2 trigger statements.

Common methods of changing the SQL statement terminator are:

• Use SPUFI to set the terminator to # in the default panel.

• Include the following control statement at the beginning of the script file, or immediately before the DDL statement to be executed:

--#SET TERMINATOR #

• Use DSNTEP2 or DSNTIAD to code the RUN command as follows:

RUN PROGRAM(DSNTEP2) PLAN(DSNTEP61) PARMS(’SQLTERM(#)’)

Task A Change the Statement Terminator

The following steps change the statement terminator to a '#', then executes the SQL from the script file.

1. In a Windows command prompt, go to the directory where the script file resides.

2. Connect to DB2/OS390. For example:

C:\your-directoryDB2 Connect to S390LOC user logon_id using password

3. Execute your script file. For example:

C:\your-directoryDB2 -td# -f filename

4. In the Window's Command Center, go to the Script menu and select options.

5. Check the use statement termination character box and enter '#'.

6. Connect to DB2/OS390 from the Command Center GUI. For example:

Connect to S390LOC user logon_id using password

7. Cut the SQL statements from the script file and paste them into the Command Center GUI, then execute.


| 219

Chapter 10 Setting Encoding Options

This chapter describes how to use TIBCO Adapter for ActiveDatabase in an international environment using non-ASCII languages.

Topics


• Setting TIBCO Messaging Encoding, page 222

• Configuring the Adapter to Communicate with the Database, page 224

• Relevant Environment Settings, page 229


220 | Chapter 10 Setting Encoding Options

Overview

TIBCO Adapter for ActiveDatabase provides internationalization support by taking advantage of Unicode, which is supported by the TIBCO Adapter SDK. Currently the international data support is provided for text data only. Database name, database schema, metadata and error messages do not currently support international character sets, but these features will be available in a future release.

The following illustration shows an example of TIBCO Adapter for ActiveDatabase in a Japanese language environment serving databases of different encodings. The adapter converts the encoding between Unicode and the character sets of the databases.

Figure 7 Example of Unicode Conversion

In this example, Shift-JIS encoded Japanese data is retrieved from an Oracle database by the adapter’s publication service, which converts the data into UTF-8 and publishes the UTF-8 data to the TIBCO messaging environment. An adapter subscription service receives this message and converts it from UTF-8 to EUC-JP, and inserts the data into an Oracle EUC-JP database to which it is connected.

ActiveDatabase Publishing Service

ActiveDatabase Subscription Service

TIBCO Messaging

Shift-JIS

UTF-8 UTF-8

EUC-JP

Oracle DB in Shift-JIS

Oracle DB in EUC-JP

Driver Manager/ODBC Driver/Database Client


Overview | 221

By using UTF-8 as the TIBCO Messaging encoding between TIBCO ActiveEnterprise components, the two adapter services can serve databases of different encodings by exchanging data without data garbled. For detailed information about how TIBCO Adapter works in an international environment, please refer to TIBCO Adapter Concepts.

In circumstances where only ASCII and Latin-1 data (including English and Western European languages) are exchanged in the system, you can use Latin-1 encoding as the TIBCO Messaging encoding between TIBCO ActiveEnterprise components. It is not necessary to use UTF-8 as the TIBCO Messaging encoding in this case. UTF-8 is only required when the data to be exchanged is not included in the Latin-1 character set, as is the case with Asian languages and other European languages.

To configure the adapter to work correctly in transmitting non-ASCII data, you must set the TIBCO messaging encoding property. The following sections explain how to do this.

In certain cases, intermediate entities (such as an ODBC driver, ODBC driver manager, or the database vendor's proprietary database client) may also perform some encoding conversion. This is discussed later in this chapter.



Setting TIBCO Messaging Encoding

TIBCO ActiveEnterprise components (TIBCO applications and adapters) use TIBCO Messaging encoding when communicating with each other. In the case of TIBCO Adapter for ActiveDatabase, publication services use this encoding to publish data into TIBCO messaging system, and subscription services use it to receive data from the TIBCO messaging system.

There are currently two choices for TIBCO Messaging encoding: Latin-1 (ISO8859-1) for transmitting ASCII and Latin-1 data, and UTF-8 for transmitting data of other languages.

The encoding property is set on the project itself at design-time, and in the TIBCO administration server’s property file when creating a TIBCO administration domain.

Encoding in a Server-based Project

The TIBCO administration server setting is used when the project is exported to a server repository or deployed using TIBCO Administrator Enterprise Edition.

For a server based project, the TIBCO messaging encoding is set by the repo.encoding property in the server's tibcoadmin<domain-name>.tra configuration file (located in <install-path>/tibco/administrator/n.n/bin/).

The encoding is set when using the TIBCO Domain Utility to create the domain or by editing the repo.encoding property in the .tra configuration file.

Each adapter or TIBCO application that uses the same server for storing and retrieving configuration data uses this encoding setting when communicating to each other. This assures that all TIBCO components (including adapters and other TIBCO applications) that belong to the same project use the same encoding value to communicate.

Encoding in a Local Project File

If the project's configurations are saved in a local project file, which is the normal case when the project is in design stage before deployment, the TIBCO Messaging encoding is determined by the encoding property saved in the local project file.

The services do not use TIBCO Messaging encoding to connect to the backend database. See Configuring the Adapter to Communicate with the Database on page 224 for more information.


Setting TIBCO Messaging Encoding | 223

The encoding value is set on the root project folder in TIBCO Designer. By default, the value is set to ISO8859-1. You can change the value by selecting the folder and under the Project Settings tab, changing the value for the TIBCO Message Encoding field.

In order for different TIBCO components that each have their own local file repository to communicate with each other without data garbled, they must use the same TIBCO Messaging encoding, meaning that all these components must set their local project encoding to the same value.

After a project is deployed as a server-based project, the encoding property set at design-time is superseded by the encoding property set for the TIBCO administration server.

The encoding property of a local project file is only for determining the TIBCO Messaging encoding, not the encoding used for the persistent storage of the project files. The project files are always saved as UTF-8 encoded files.



Configuring the Adapter to Communicate with the Database

The TIBCO message encoding is a project setting used for data conversion among different components. However, the adapter uses a different encoding value for exchanging data with the database. Because there are many intermediate entities between the adapter and the database (such as the ODBC driver manager, ODBC driver, and possibly the database native client), and each of these entities may conduct encoding conversions to the data stream flow between the service and the database, the data encoding from the database might not be known, while the data encoding to the database must be compatible to that of the database.

To eliminate the complexity introduced by these intermediate entities, you can make some configuration changes that ensure the service’s encoding setting are compatible with the database instance's encoding. This also boosts the performance by eliminating unnecessary intermediate data conversions.

The configuration changes differ depending on the operating system that the service is running on, the database vendor, the ODBC driver used, and other factors. The following sections explain how to configure the adapter to communicate with the database.

Configuring the Adapter at Design-timeUse the following steps to set the adapter’s encoding.

1. Determine your database server encoding. This is the encoding you want to use for the adapter’s encoding. For example, for the Oracle database, the encoding can be found by querying the database with:

select * from nls_database_parameters;

2. Set the NLS_LANG environment variable for the client system.

Set the client machine's NLS_LANG environment variable to be consistent to the database instance's character set (NLS_CHARACTERSET) value. The client machine is where the adapter service is going to run. Consult your database administrator for the NLS_CHARACTERSET value of the database instance to connect to, and how to choose the right NLS_LANG value.

As an example, the system may use an Oracle database instance with the NLS_CHARACTERSET value set to JA16SJIS. In this case, the client machine's NLS_LANG environment variable must be set to JAPANESE_JAPAN.JA16SJIS.

The correct setting of the NLS_LANG environment variable eliminates the encoding conversion possibly conducted by the Oracle proprietary client.

3. Set the Adapter encoding in TIBCO Designer.


Configuring the Adapter to Communicate with the Database | 225

You must select or enter a valid encoding that the adapter understands. The adapter assumes the data coming from the database is in this encoding and ensures that data sent to the database is in this encoding. The encoding given here should match the encoding set for the database to which the adapter connects.

There are two ways to do this configuration:

— In TIBCO Designer, set this in the adapter resource. In the Configuration tab, click Show All Tabs. In the General tab, choose the encoding that is compatible with the encoding of the database instance to be connected to. Refer to Table 21, TIBCO ActiveDatabase Adapter and Oracle NLS_Lang Values.

The adapter may support more encoding values than those shown in TIBCO Designer. You can type in these encoding values. For more information about these, refer to Appendix B in TIBCO Adapter Concepts.

— You can modify the adapter encoding property, adb.encoding, in the adapter’s.tra file. This setting supersedes the encoding option chosen in TIBCO Designer.

4. Set the ODBC DSN in TIBCO Designer

This field is set under the adapter’s Run-time Connection tab. You must also define the ODBC DSN on the machine on which the adapter is running.

— On Unix systems, modify the odbc.ini file <install-path>/tibco/adapter/adadb/5.1/odbc. In addition, you must set the correct IANAAppCodePage to match the database encoding, if you are using a wire protocol driver. See IANAAppCodePage on page 225 for a list of IANAAppCodePage values. The complete list is available in <install-path>/tibco/adapter/adadb/5.1/odbc/books/odbcref/odbcref.pdf

— On Windows systems, use the Windows ODBC GUI to define a system DSN. Note that if you are using a TIBCO wire protocol driver, the machine on which the adapter is running must be on the locale that matches the database encoding.

Table 20 IANAAppCodePage

Value Encoding (Language)

3 ASCII (English)

4 ISO_8859-1 (Western European)

17 Shift_JIS (Japanese)



Using a non-Oracle Database

When using a database other than Oracle, contact the database vendor for information about whether the database's proprietary client performs any encoding conversion to the data flow, and how to configure the database client to eliminate the conversion possibly conducted by it. Several possibilities exist:

• The database client does not perform any conversion to the data flow in any cases. In this case, you only need to set the adapter encoding to be compatible with the database instance's encoding.

• The database client relies on a local setting, such as an environment variable, to determine whether or not a conversion should to be conducted. This is similar to the above Oracle example, where you need to set both this local setting and the adapter’s adapter encoding property to be compatible with the database server instance's encoding.

• The database client relies on the local system encoding to determine the conversion.

— When the local system encoding is compatible with the database instance encoding, no conversion will be conducted by the database client. You only need to set the adapter encoding to be compatible with the database server instance encoding;

— When the local system encoding is different from the database instance's encoding, the proprietary database client may do the encoding conversion between the two different encodings. This conversion cannot be avoided by any settings you can make. In this case, set the adapter encoding to be consistent with the local system encoding, because the data from the

18 EUC_JP (Japanese)

38 EUC_KR (Korean)

113 GBK (Simplified Chinese)

2026 BIG5 (Traditional Chinese)

Table 20 IANAAppCodePage

Value Encoding (Language)


Configuring the Adapter to Communicate with the Database | 227

database has been converted to local system encoding by the database client.

Special Configurations for Supporting a UTF-8 DatabaseThis section applies only to TIBCO ODBC drivers.

Companies doing business globally may require their database to be multilingual, that is, a single database instance supporting multiple languages so the data from the company's global business can be stored in it. Unicode is a natural choice for the encoding of this kind of database instance.

This requires the adapter to be able to use Unicode, or specifically, UTF-8 encoding, to communicate with the database. While this is already a supported feature, an exception exists when using TIBCO ODBC drivers.

TIBCO Adapter for ActiveDatabase contains a binary mode for use with an embedded TIBCO driver when UTF-8 is the encoding to communicate with the backend database instance. The configurations described below are applicable to both Windows and UNIX platforms, and both non-wire and wire protocol drivers.

1. Set the adapter’s encoding option to UTF-8.

2. In the adapter’s.tra file, uncomment the following line:

#ADB.WCHAR = SQL_C_BINARY

This forces the adapter to use binary mode to communicate with the database.

When using the DataDirect non-wire protocol ODBC driver and UTF-8 as the adapter encoding to support multilingual data exchange, the configuration is totally different. Please refer to the section Special Configurations for Supporting a UTF-8 Database.

These are for the internationalization configuration, which forces the adapter to use binary mode to communicate to the database instance. No further encoding related configurations are necessary. For example, on UNIX there is no need to set the AppCodePage attribute, and when using a non-wire driver there is no need to set the proprietary database client.



Run-time Environment VariablesIn general, after deploying the adapter, all information should be in the correct place, however you should verify the deployed .tra file and platform settings. The encoding conversion is dependent on the TIB_ICU_DATA environment variable. The deployed adapter .tra file should have a property called tibco.env.TIB_ICU_DATA. Make sure it points to the directory containing the tibicudata.dat file.

For the Oracle database, make sure the installed NLS_LANG attribute’s value matches the database character set. If not, set NLS_LANG to the correct value before starting the adapter. See TIBCO ActiveDatabase Adapter and Oracle NLS_Lang Values on page 229 for a list of values.


Relevant Environment Settings | 229

Relevant Environment Settings

In order to support international languages, the adapter uses the tibicudata.dat file to convert between the original database encoding and the TIBCO Messaging encoding (usually UTF-8). The environment variable TIB_ICU_DATA is already configured to point to the directory containing this file. Do not change this setting.

This environment variable setting is required on both Windows and Unix platforms.

The following table lists the TIBCO Adapter for ActiveDatabase encoding values as shown in TIBCO Designer.

Table 21 TIBCO ActiveDatabase Adapter and Oracle NLS_Lang Values

ActiveDatabase Adapter Encoding

Oracle NLS_LANG (containing NLS_CHARACTERSET) Description

ASCII US7ASCII 7-bit ASCII

ISO8859-1 language_territory.WE8ISO8859P1 ISO8859-1 (Latin-1), West European

Shift_JIS (CP943) JAPANESE_JAPAN.JA16SJIS Japanese Shift-JIS, CP943

Shift_JIS (TIBCO) JAPANESE_JAPAN.JA16SJIS Variant of IBM-943 (created by TIBCO for flavoring some MS-932 conversions)

KSC-5601 KOREAN_KOREA.KO16KSC5601 Korean KSC-5601

Big5 TRADITIONAL CHINESE_TAIWAN.ZHT16BIG5

Traditional Chinese Big5 with Euro

GBK SIMPLIFIED CHINESE_CHINA. ZHS16CGB231280

Simplified Chinese GBK (superset of GB2312-80)

EUC-JP JAPANESE_JAPAN.JA16EUC Japanese EUC

UTF8 AMERICAN_AMERICA.UTF8 Unicode Transformation Format-8


| 231

Chapter 11 Monitoring the Adapter

Read this appendix if you have installed TIBCO Hawk and want to use TIBCO Hawk microagents through the Monitoring tab of an adapter instance. TIBCO Hawk is an optional tool from TIBCO Software Inc. that can be used in addition to the standard trace message logging method described under Logging Tab on page 58).

Topics


• Starting TIBCO Hawk Software, page 233

• The Auto-Discovery Process, page 234

• Invoking Microagent Methods, page 235

• Available Microagents, page 238


232 | Chapter 11 Monitoring the Adapter

Overview

TIBCO Hawk is a sophisticated tool for enterprise-wide monitoring and managing of all distributed applications and systems. System administrators can use it to monitor adapters in a wide area network of any size. TIBCO Hawk can be configured to monitor system and adapter parameters and to take actions when predefined conditions occur. These actions include: sending alarms that are graphically displayed in the TIBCO Hawk display, sending email, paging, running executables, or modifying the behavior of a managed adapter.

Unlike other monitoring applications, TIBCO Hawk relies on a purely distributed intelligent agent architecture using publish or subscribe to distribute alerts. TIBCO Hawk uses TIBCO Rendezvous for all messaging and thus gains the benefits and scalability from the TIBCO Rendezvous features of publish/subscribe, subject name addressing, interest-based routing, and reliable multicast.

TIBCO Hawk is a purely event-based system that uses alerts. The agents are configured with rules that instruct them on everything from what and how to monitor to what actions to take when problems are discovered. Thus the workload is fully distributed throughout the enterprise. Every agent is autonomous in that it does not depend on other components to perform its functions.

The TIBCO Hawk Enterprise Monitor consists of these components:

• Display—GUI front end that displays alarms and provides editors to create rule bases, create tests, view messages, and invoke microagents to request information or initiate an action.

• Agents—Intelligent processes that perform monitoring and take actions as defined in rules.

• Rulebases—Rules that are loaded by agents to determine agent behavior.

• Application Management Interface (AMI)—Manages network applications via TIBCO Rendezvous and supports communication between a network application and monitoring TIBCO Hawk agents, including the ability to examine application variables, invoke methods, and monitor system performance.

• Microagents—Feed information back to TIBCO Hawk and expose action methods to rulebases.

For more information, see the TIBCO Hawk documentation.


Starting TIBCO Hawk Software | 233

Starting TIBCO Hawk Software

The TIBCO Hawk agent can be configured to start automatically during the system boot cycle. See the TIBCO Hawk Installation and Configuration guide for information about starting TIBCO Hawk.

The TIBCO Hawk Administrator’s Guide explains how to start the TIBCO Hawk Display.

The guides are included in your TIBCO Hawk software installation area.



The Auto-Discovery Process

After you start an instance of TIBCO Hawk Display, it continually discovers machines running TIBCO Hawk Agents on your network. Container icons are created for each agent, and arranged hierarchically in clusters. By default, agent icons are clustered according to subnets.

At first, the Agents container is empty. Its counter displays a value of zero and, on the right, the Discovered counter is also at zero. Both icons are initially green in color to show that no alerts, or warning messages, are in effect. As agents are discovered, the counters increment to reflect the current number of discovered agents:

Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a container in the left panel displays nested items on the right.

Icon colors change to reflect the highest level of alert found on discovered agents. For explanations of icon elements and characteristics, see your TIBCO Hawk Administrator’s Guide.


Invoking Microagent Methods | 235

Invoking Microagent Methods

A set of default microagents is loaded when a TIBCO Hawk Agent is started. When you install and start TIBCO Adapter for ActiveDatabase, its microagents are dynamically added to the local agent.

To invoke a microagent method:

1. In TIBCO Hawk Display, right-click on the agent icon and select Get Microagents.

If TIBCO Hawk security is implemented on your system and you do not have access to microagents on this agent, an error dialog displays. Select another agent, or contact your system administrator to obtain access.

The Microagents, Methods and Arguments dialog displays. The panel on the upper left lists microagents you can access on the current agent.

This dialog has two modes, Invoke and Subscribe. Invoking a method immediately returns a single set of current results. Subscribing provides updates of current results at regular intervals. Radio buttons at the bottom of the dialog control these modes.

2. Click a microagent name, such as Self, to display a list of associated methods and text descriptions in the panels below.



3. Click the name of the method to invoke, such as getComponentInfo.

If the method accepts arguments, fields for each argument display in the upper right panel. Detailed help text displays in the lower panel.

4. Specify any arguments for the method invocation.

5. Verify that the Invoke radio button is selected.


Invoking Microagent Methods | 237

6. Click Invoke to invoke the selected method.

The Invocation Results dialog displays the results returned by the method.

7. Click Done to close the dialog.

These steps describe how to interactively invoke a microagent method and receive a single set of results in TIBCO Hawk Display. You can also use a microagent method as the data source of a TIBCO Hawk rule. Rules automatically receive method results, apply tests to evaluate them, then take action if necessary. For more information on building TIBCO Hawk rules and rule bases, see your TIBCO Hawk Administrator’s Guide.



Available Microagents

Each adapter has two microagents, a standard TIBCO Hawk microagent named COM.TIBCO.ADAPTER.xyz (where xyz is the adapter configuration name) and a custom microagent. These microagents provide:

• Business level statistics—statistics that report the progress of the adapter as it interacts with the database. For example, in a database adapter such statistics might indicate whether objects were successfully or unsuccessfully inserted, updated, or deleted in the database.

• Queries that return information about the state of the adapter. This can be an important tool for seeing the internals of an adapter and debugging it if something appears wrong. For example, methods can return information about threads, internal queues, or connections to the target system. Using these methods, one might be able to identify certain bottlenecks or gauge how successfully an adapter is scaling with respect to the current environment.

• Updates of the adapter runtime parameters. This includes retrieving the current runtime parameters and setting new runtime parameters without restarting the adapter. An example of this is getting and setting the polling interval. Updating a runtime parameter through the Hawk microagent only affects the setting of the instance that is running. It does not make a permanent change of the setting in either the repository or the .tra file.

The following table lists each method available for the adapter and page on which the method is explained. Although the Microagents, Methods and Arguments dialog in TIBCO Hawk Display lists more methods than are documented here, only the following methods are supported.

Table 22 Standard Microagent Methods

Standard Method Description Page

activateTraceRole() Activates a mapping of a role to a sink at runtime.

242

deactivateTraceRole() Deactivates a mapping of a roles to sinks at runtime.

243

getAdapterServiceInformation()

Returns information about the services implemented by this adapter.

244

getComponents() Returns information about the publisher, subscriber and IODescriptor.

245


Available Microagents | 239

getConfig() Returns basic configuration information. More specific information is accessed by the more specific methods.

246

getConfigProperties() Returns a list of publishers and subscribers.

247

getHostInformation() Returns standard and extended application information.

248

getRvConfig() Returns information about all TIBCO Rendezvous sessions defined.

249

getStatus() Returns general status information, such as the number of TIBCO Rendezvous messages received and published, the number of errors since the last call, the PID of the application, and more.

250

getTraceSinks() Returns information about sinks to which traces currently go.

251

getVersion() Returns the configuration ID, application name, version, and date for this adapter instance.

252

_onUnsolictedMsg() Displays alert messages sent to the current adapter.

253

preRegisterListener() Preregisters an anticipated listener. 254

reviewLedger() Returns information retrieved from the ledger file of a certified messaging session for a publisher adapter.

255

setTraceSinks() Adds a role or changes the file limit of a previously specified sink.

256

stopApplicationInstance()

Stops the running adapter instance. 257

unRegisterListener() Unregisters a currently preregistered listener.

258

Table 22 Standard Microagent Methods (Cont’d)

Standard Method Description (Cont’d) Page



Table 23 Custom Microagent Methods

Custom Method Description Page

getEventQueueSize() Retrieves the size of the TIBCO Rendezvous event queue for the specified adapter instance.

259

setDebugLevel() Sets the debug level for the current adapter instance.

260

toggleVerboseFlag() Changes the value of the verbose flag from on to off, or the reverse.

261

showConfiguration() Shows the configuration defined for the current agent.

262

terminateADBagent() Stops the current TIBCO Adapter for ActiveDatabase agent.

263

getPollingInterval() Returns the current polling interval setting.

264

setPollingInterval() Set the polling interval for the publication service.

265

getPollingBatchSize() Get the polling batch size for the publication service.

266

setPollingBatchSize() Set the polling batch size for the publication service.

267

Table 24 Custom Microagent Methods with adb.perfMon

Custom Method Description Page

getActivityStatistics() Returns the total number of objects processed for all the schemas, based on the request type. Also, returns the number of success and error objects.

268


Available Microagents | 241

getActivityStatisticsByService

Returns the total number of objects processed for each of the schemas associated with the specified service.

269

getActivityStatisticsByOperation()

Returns the total number of objects processed for all the schemas by each service that is associated with a specified operation.

270

getThreadStatistics() Return the operation counts of the current threads.

271

getQueueStatistics() Return the current count of elements in any internal queue used by the adapter.

272

getConnectionStatistics() Returns the state and statistics for all the current connections used by the adapter.

273

resetActivityStatistics() Resets all the counts for the activity statistics.

274

resetThreadStatistics() Resets all the counts for the thread statistics.

275

resetQueueStatistics() Resets all the counts for the queue statistics.

276

resetConnectionStatistics() Resets all the counts for the connection statistics.

277

Table 24 Custom Microagent Methods with adb.perfMon (Cont’d)

Custom Method (Cont’d) Description (Cont’d) Page



activateTraceRole()

Purpose (Standard) Activates a mapping of a role to a sink at runtime. This replaces the now-deprecated setTraceSink() TIBCO Hawk method.

Parameters Parameters Type Description

roleName string Name of the role to activate.

sinkName string Name of a sink for which to activate the role.


deactivateTraceRole() | 243

deactivateTraceRole()

Purpose (Standard) Deactivates a mapping of a roles to sinks at runtime.

Parameters Parameters Type Description

roleName string Name of the role to activate.

sinkName string Name of a sink for which to activate the role.



getAdapterServiceInformation()

Purpose (Standard) Returns information about the services implemented by this adapter. The information is a summary of available adapter services.

Parameters

Returns

Parameter Type Description

serviceName string Name of the service from which to get information. Default is ALL.

Returns Type Description

Line Integer Sequential row number.

Name string Name of the Service.

Endpoint string Name of the endpoint used for this service.

Type string Type of the endpoint, for example, Publisher, Subscriber.

Quality of Service

string Quality of service for the endpoint, for example, RV, RVCM.

Adapter Name string Name of the application for this sink.

Session Name string Name of the TIBCO Rendezvous session.

Subject string Subject defined for this endpoint

Number of Messages

Integer Number of messages processed for this endpoint.


getComponents() | 245

getComponents()

Purpose (Standard) Returns information about the currently active TIBCO Hawk components such as publishers, subscribers, or timers.

Parameters

Returns

Parameters Type Description

Component Name string Name of the TIBCO Hawk component. Default is all components.

Component Type string Any of Publisher, Subscriber, Timer, or IODescriptor. The default value is All.


Component Name string Name of the TIBCO Hawk component.

Instance ID string Name of this adapter instance.

Adapter Name string Name of the adapter.

Session Name string Name of the TIBCO Rendezvous session.

Component Type string The name of the TIBCO Adapter SDK class for this TIBCO Hawk component, such as MPublisher, MSubscriber, or MIODescriptorSource. For more information, see your TIBCO Adapter SDK documentation.

Description string Information about this TIBCO Hawk component, for example, time interval, signal type, validating publisher (or subscriber) etc.



getConfig()

Purpose (Standard) Retrieves generic configuration information. More specific configuration information is accessed through separate methods.

Returns Returns Type Description

Instance ID string Configuration ID of this adapter.


Repository Connection

string URL of the repository used for adapter instance.

Configuration URL

string Location of the adapter project; either a file name or configuration URL.

Command string Command line arguments used to start the adapter.


getConfigProperties() | 247

getConfigProperties()

Purpose (Standard) Returns all attributes and elements for the given repository object.

Parameters

Returns


Property string Name of the property for which elements (tags) and attributes are desired. For example, agentone/startup.

If no value is given, all properties are returned.


Element Name string Repository directory for the property.

Attribute Name string Name of the repository object attribute.

Attribute Value string Value of the repository object attribute.

Line integer Line number in which this property is defined in the project file.



getHostInformation()

Purpose (Standard) Returns standard and extended application information.


Name string Name of the property.

Value string Value of the property.


getRvConfig() | 249

getRvConfig()

Purpose (Standard) Returns information about the TIBCO Rendezvous session defined by this adapter. Information about all currently defined sessions is returned if no sessionName is provided.

Parameters

Returns


Session Name string Name of the TIBCO Rendezvous session for which configuration is required (default is all).


Instance ID string The configuration ID of this adapter.


Session Name string Name of the session.

Service string Service parameter for this session.

Daemon string Daemon parameter for this session.

Network string Network parameter for this session.

Synchronous? boolean Returns 1 if this is a synchronous session, 0 otherwise.

Session Type string Type of session; one of M_RV, M_RVCM, or M_RVCMQ.

Certified Name string Name of this certified session.

Ledger File string Ledger file for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.

CM Timeout string Timeout for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.



getStatus()

Purpose (Standard) Retrieves basic status information about the adapter.

This information is fairly limited; for more detail, additional methods are provided: getConfig() on page 246 and getRvConfig() on page 249.


Instance ID string Configuration ID for this adapter instance.


Uptime integer Number of seconds since startup.

Messages Received integer Number of TIBCO Rendezvous messages received.

Messages Sent integer Number of TIBCO Rendezvous messages published.

New Errors integer Number of errors since the last call to this method.

Total Errors integer Total number of errors since startup.

Process ID integer Process ID of the application.

Host string Name of host machine on which this adapter is running.


getTraceSinks() | 251

getTraceSinks()

Purpose (Standard) Returns information about sinks to which traces currently go.

Parameters

Returns


Sink Name string Name of the sink for which you need information. If no name is specified, information about all sinks is returned. Default is all.

Role Name string Name of the role for which you need information for the specified sink or sinks. Default is all.


Instance ID string Name of this adapter instance as a string.

Adapter Name string Name of the application for this sink.

Sink Name string Name of the sink

Sink Type string Type of this sink. One of fileSink, rvSink, hawkSink, stderrSink.

Roles string Roles this sink supports, as a string. For example “warning, error, debug”.



getVersion()

Purpose (Standard) Retrieves version information for the current application. Two lines may be returned, one for the TIBCO Adapter SDK, one for the adapter.

Returns Returns Description

Instance ID The configuration ID as a string, for example SDK.

Adapter Name Name of the adapter as a string, for example agentone.

Version Version number as a string, for example 1.1.


_onUnsolictedMsg() | 253

_onUnsolictedMsg()

Purpose (Standard) Displays all alert messages sent from the adapter or an error if not successful.



preRegisterListener()

Purpose (Standard) Preregister an anticipated listener. Some sending applications can anticipate requests for certified delivery even before the listening applications start running. In such situations, the sender can preregister listeners, so TIBCO Rendezvous software begins storing outbound messages in the sender’s ledger. If the listening correspondent requires old messages, it receives the backlogged messages when it requests certified delivery.

Parameters

Returns OK if the listener was preregistered successfully, false otherwise.


Session Name string Name of the session that anticipates the listener.

Publisher Name string Name of the component for which the listener should be preregistered.

Listener Session Name

string Name of the listener to preregister.


reviewLedger() | 255

reviewLedger()

Purpose (Standard) Returns information retrieved from the ledger file of a TIBCO Rendezvous certified messaging session. Before invoking this method, ensure that the certified messaging publisher adapter has established a certified delivery agreement with its subscriber agents.

Parameters

Returns


Session Name string Name of the TIBCO Rendezvous session for which ledger information is desired (default is all).

Subject string Name of the subject for which ledger information is desired.


Session Name string Name of the TIBCO Rendezvous CM session to which this information applies.

Subject string Subject name for this session.

Last Sent Message integer Sequence number of the most recently sent message with this subject name.

Total Messages string Total number of pending messages with this subject name.

Total Size integer Total storage (in bytes) occupied by all pending messages with this subject name. If the ledger contains ten messages with this subject name, then this field sums the storage space over all of them.


string Within each listener submessage, the Listener Session Name field contains the name of the delivery-tracking listener session.

Last Confirmed string Within each listener submessage, the Last Confirmed field contains the sequence number of the last message for which this listener session confirmed delivery.

Line integer Row number in ledger file.

UnacknowledgedMessages

integer Number of RVCM messages pending for this listener. The value is computed by subtracting the last sent sequence number from the last acknowledged sequence number.



setTraceSinks()

Purpose (Standard) Adds a role or changes the file limit of a previously specified sink.

Parameters

Returns OK if successful or an error if not successful.


Sink Name string Name of the sink for which you want to add a role or change the file limit.

Role Name string Name of the role you want to add to this sink (warning, error, debug, or user defined). Default is all.

File Size integer Maximum file size for this sink.

This parameter is ignored if the sink specified by sinkName is not a file sink.


stopApplicationInstance() | 257

stopApplicationInstance()

Purpose (Standard) Stops the specified adapter by calling the internal stop() method.

Returns OK if successful or an error if not successful.



unRegisterListener()

Purpose (Standard) Unregisters a currently preregistered listener.

Parameters

Returns True if the listener was successfully unregistered, false otherwise.


Session Name string Name of the session that anticipates the listener.

Publisher Name string Name of the component for which the listener should be preregistered.


string Name of the listener to unregister.


getEventQueueSize() | 259

getEventQueueSize()

Purpose (Custom) Retrieves the size of the TIBCO Rendezvous event queue for the specified adapter instance. For more information on events and event queues, see TIBCO Rendezvous Concepts.

Parameters

Returns


Session string Type of listener for this adapter instance. Possible values are Subscriber or Request/Reply. The default value is Subscriber.

Return Type Description

QueueCount integer The number of events currently in the event queue.

QueueLimit integer The maximum number of events this adapter instance can have in the event queue. This value is set using the adb.rvMaxQueueSize option in the adapter’s properties file. The default value is 0, which means the event queue has unlimited size.



setDebugLevel()

Purpose (Custom) Sets the debug level for the current adapter instance.

Parameters

Returns Returns OK if successful or an error if not successful.


DebugLevel integer Sets the debug level to 0 (off), 1, 2, or 3.

0— No debug information displayed.

1—SQL commands executed against the database shown.

2—ODBC data source for each SQL command shown.

3—All debug information displayed.


toggleVerboseFlag() | 261

toggleVerboseFlag()

Purpose (Custom) Changes the value of the verbose flag from on to off, or the reverse.

Returns This method returns OK if successful or an error if not successful.



showConfiguration()

Purpose (Custom) Shows the configuration defined for the current agent.

Parameters Parameter Type Description

VerboseInfo string The current setting for the verbose mode, on or off.

DebugLevelInfo string The debug level setting:

0— No debug information displayed.

1—SQL commands executed against the database shown.

2—ODBC data source for each SQL command shown.

PollIntervalInfo string The poll interval in milliseconds.


terminateADBagent() | 263

terminateADBagent()

Purpose (Custom) Stops the current TIBCO Adapter for ActiveDatabase agent.

Remarks Invoking this method displays a warning message with the text MicroAgent returned error. AMI Method invocation timed out. The message can be ignored.

Returns This method returns OK if successful or an error if not successful.



getPollingInterval()

Purpose (Custom) Returns the current polling interval setting.


PollingInterval integer Polling interval in milliseconds.


setPollingInterval() | 265

setPollingInterval()

Purpose (Custom) Set the polling interval for the publication service.


PollingInterval integer Polling interval in milliseconds.

ServiceName string (Optional) Name of service where the polling interval is set.



getPollingBatchSize()

Purpose (Custom) Get the polling batch size for the publication service.


BatchSize integer The batch size for the publication service.


setPollingBatchSize() | 267

setPollingBatchSize()

Purpose (Custom) Set the polling batch size for the publication service.


BatchSize integer The new batch size for the publication service.



getActivityStatistics()

Purpose (Custom with adb.perfMon) Returns the total number of objects processed for all the schemas, based on the request type. Also, returns the number of success and error objects.

Parameters

Returns


Get Subtotal By integer Statistics categorized by service or by operation.


Name string Name of the service or operation.

Total integer Total number of objects processed for this schema for a publication service.

Total number of objects received for this schema for a subscription service.

Success integer The number of objects that were successfully identified for this schema which will be published or written to a file.

Failure integer The number of objects that were identified for this schema but were not published because the header of the schema failed validation for the publication service, or was written to a file because the schema was not associated with the subscriber for a subscription service.


getActivityStatisticsByService | 269

getActivityStatisticsByService

Purpose (Custom with adb.perfMon) Returns the total number of objects processed for each of the schemas associated with the specified service. Also, returns the number of success and error objects.

Parameters

Returns


Service Name string Name of the service.


Operation string Type of operation that the service performs.

Schema Name string Name of the schema that is associated with the service.

Total integer Number of objects processed for this schema for a publication service.

Number of objects received for this schema for a subscription service.





getActivityStatisticsByOperation()

Purpose (Custom with adb.perfMon) Returns the total number of objects processed for all the schemas by each service that is associated with a specified operation. Also, returns the number of success and error objects.

Parameters

Returns


Operation string Name of operation. Pick from list.


Service Name string Name of the service that is associated with the specified operation.

Total integer Total number of objects processed for this schema for a publication service.

Total number of objects received for this schema for a subscription service.




getThreadStatistics() | 271

getThreadStatistics()

Purpose (Custom with adb.perfMon) Return the operation counts of the current threads.


ThreadID string A unique identification of a particular thread.

ThreadType string A type or key that will match this thread to a queue or connection.

TaskType string Short description of the tasks this thread processes.

TaskCount integer Number of tasks processed by this thread.



getQueueStatistics()

Purpose (Custom with adb.perfMon) Return the current count of elements in any internal queue used by the adapter. This includes the TIBCO Rendezvous event queues automatically spawned by TIBCO Rendezvous for each adapter.


QueueID string A unique identification of a particular queue.

QueueType string A type or key that will match this queue to a thread or connection.

QueueCount integer Current number of elements in the queue.

MaxQueueSize integer Maximum number of elements in the queue.


getConnectionStatistics() | 273

getConnectionStatistics()

Purpose (Custom with adb.perfMon) Returns the state and statistics for all the current connections used by the adapter.


Connection ID string A unique identification of a particular connection.

Connection Type string A type or key that will match this connection to a thread or queue.

State string Current state: CONNECTED or DISCONNECTED

NumRetries integer Total number of times this connection had to be reestablished.

TotalNumOperations

integer Total number of operations processed by this connection since the adapter started.

CurrentNumOperations

integer Total number of operations processed by this connection since the last reconnection.



resetActivityStatistics()

Purpose (Custom with adb.perfMon) Resets all the counts for the activity statistics.


resetThreadStatistics() | 275

resetThreadStatistics()

Purpose (Custom with adb.perfMon) Resets all the counts for the thread statistics.



resetQueueStatistics()

Purpose (Custom with adb.perfMon) Resets all the counts for the queue statistics.


resetConnectionStatistics() | 277

resetConnectionStatistics()

Purpose (Custom with adb.perfMon) Resets all the counts for the connection statistics.


| 279

Appendix A Frequently Asked Questions

This appendix lists answers to frequently asked questions.

Topics

• General Questions, page 280

• Request-Response Questions, page 285


280 | Appendix A Frequently Asked Questions

General Questions

How can I determine the source of a problem or an error?

In some cases it is helpful to turn on ODBC tracing. Activate tracing in Control Panel>ODBC Data Sources on the Tracing tab. For details, see your Microsoft Windows documentation.

How can I find the version number of an adapter instance?

A banner displays when an adapter instance starts. The banner lists component versions for the adapter and for TIBCO Adapter SDK software. You can use this information to diagnose compatibility issues, or to report any problem details to Customer Support.

You can also display version information in TIBCO Designer by clicking the Help>Runtime Environment menu command.

Why is a database trigger error not logged in the exception table?

When using an adapter instance as a publisher, if an error occurs in the database trigger that is used to copy data from the source table to the publishing table, the database trigger error will not be logged in the exception table for the subscriber adapter.

How should the adapter react if the database connection is lost and the database is later restarted? Does it automatically try to reconnect?

If TIBCO Adapter for ActiveDatabase detects it has lost its database connection, it shuts down. You can configure the adapter for automatic reconnection (see Run-time Connection Tab on page 50). Alternatively, TIBCO Hawk rules can be written to detect this and restart the adapter whenever this occurs.

Must an incoming message contain all the columns that are defined for the destination table?

The incoming message need not contain all the columns defined in the destination database table. You can configure the adapter to expect only a subset of the columns, defined in the repository. The adapter is driven from the subscribing class description and will iterate through the attributes in the class definition for the subscribing table and specifically look for those attributes in the incoming messages. It inserts NULLs for the attributes that it is expecting but does not find in the message. If there are more columns in the subscribing table than are listed in the subscribing class (set when adding a subscription), those extra columns will get whatever default values were specified during the table creation.


General Questions | 281

Can an existing table be used as the publishing table?

No. TIBCO Adapter for ActiveDatabase requires additional columns in the publishing table. Even when every field in a table is published, a separate publishing table is required.

Does the TIBCO Rendezvous message that is published have to contain every field in the publishing table?

Yes. You can control which fields are copied to the publishing table by configuring the adapter and by changing the publication trigger to publish a subset of rows. You can also append additional fields to a message or drop a message based on some criteria using the user callout library. For more information on the user callout library, see User Callout Library on page 200.

If multiple updates occur between polling intervals, are updates published in multiple TIBCO Rendezvous messages or a single large message?

If you are using publish by value, a TIBCO Rendezvous message is created for each individual update. If you are using publish by reference, that operation will get the last update.

Is it possible to delete older entries in the publishing table?

Yes. When a row is published, the value of the ADB_L_DELIVERY_STATUS field in the publishing table changes to either C (complete) or F (failed). You can write a trigger in your publishing table that deletes the row when the delivery status changes to C or F.

You can also publish data directly from the source table by configuring the adapter instance to publish by reference. A publishing table is created, but it contains only required fields and key fields of the source table.

How does the exception table work?

Before starting an adapter instance, you must set the adb.useExceptTable option in the adapter’s properties file to on and specify an exception table when configuring the adapter instance. If an error occurs when inserting data into the destination table, it will be inserted into the exception table. The transaction will be committed and a confirmation sent back for the message (RVCM delivery). If the insertion into the exception table also fails, an error message will display and the adapter instance will terminate.



Can an adapter instance be used to replicate binary types, such as BLOB?

There is only limited support for binary large object (BLOB) data types. Oracle LONG and LONG RAW types are supported in top-level tables when the adapter is configured to publish by reference. Oracle BLOB and CLOB data types are supported.

Can an adapter instance write to tables that belong to a database account different from that used by the adapter?

Yes. A source table or destination table can belong to a different database user than the default account created in create_user.sql. For more information, see Referencing External Schemas on page 10.

Can a publisher adapter and a subscriber adapter use different projects?

Yes, unless the publisher adapter is configured to use parent-child relationships.

Can TIBCO Adapter for ActiveDatabase guarantee exactly once delivery of messages over RVCM?

Exactly once delivery of messages over RVCM is not currently guaranteed. The same quality of service that RVCM provides is supported, which is at least once. To get exactly once delivery requires combining the messaging operations and the database operations in a single atomic transaction, which is not supported in RVCM.

What guarantees does the adbagent make with regards to the order of database operations? For instance, is it guaranteed that for a given table, modifications are made in the same order that they were made to the source database? What guarantees are made for operations across different tables?

TIBCO Adapter for ActiveDatabase guarantees that for database operations that are published on the same subject, the order of the operations is preserved. Usually, this applies to database operations made to one table. It does not usually apply to database operations across different tables.

When using RVCM for delivery, at what point does the subscribing adapter acknowledge an incoming message?

A TIBCO Adapter for ActiveDatabase subscriber confirms the message only after the database operation is committed. If there is an error and no exception table is used, the database operation is rolled back and no confirmation is sent. If there is an error and an exception table is used, the insert to the exception table is committed and the message is then confirmed.


General Questions | 283

By maintaining the publishing tables, all changes to the source table can be captured. If, however, there is a failure between the point of publishing a message using RVCM and updating the publishing table, will the adapter republish the message that has already been sent?

Yes, the message will be republished and the subscriber would have to deal with the duplicate message.

For the subscriber adapter, if failure occurs after doing a database update and before sending an acknowledgement back to the publisher adapter, can the restarted configuration be prevented from redoing the update operation?

No. This would cause a duplicate insert.

For a certified subscriber adapter, if an insert exception occurs and no exception table is specified, what happens?

If the tibco.clientVar.DirTrace option is specified in the adapter’s properties file when the adapter is started, exception handling information is written to the log file and the configuration continues to run. Since the insert could not be performed, the ADB_L_DELIVERY_STATUS publishing table column has a value of P for the message.

How do I pre-register non-TIBCO Adapter for ActiveDatabase subscribers, like custom adapters, to ensure no messages are lost?

Specify the CM name of the listener’s RVCM session

The session names are automatically created. Can these be changed, without confusing TIBCO Adapter for ActiveDatabase, so that we can use a standard naming convention throughout the entire integration process?

No, the session names are fixed and used by TIBCO Adapter for ActiveDatabase internally. They cannot be altered.

What’s the proper way to permanently remove an adbagent subscriber when using CM? One way is to completely REMOVE the publisher’s ledger and to change all ’P’ records back to ’N’, then restart the publisher. Is there a better, more correct or automated method?

There is a TIBCO Hawk method, unRegisterListener(), which unregisters a CM subscription. This is the proper way to remove the adbagent subscriber as a CM listener.



Is it possible to run an adapter instance using a remote TIBCO Rendezvous daemon?

Yes. Change the default settings for network, service, and daemon parameters for the adapter using TIBCO Designer.

Is it possible to run two configurations of the adapter on the same machine?

It's possible to run multiple configurations of the adapter on the same machine if each adapter instance has a unique name. If both configurations use TIBCO Rendezvous certified messaging, each must use a different RVCM session.

Can an adapter instance collate information from several database tables to send as a single TIBCO Rendezvous message, or can it only publish data from a single table, in the format defined by that table?

There are two ways to publish related tables:

• Set the adb.publishChildData option to on when configuring the adapter’s properties file. When there are insertions into parent table, the adapter will publish parent rows and the corresponding child rows using TIBCO ActiveEnterprise or XML format.

Note that the adapter currently does not support publishing child data in the TIBCO Rendezvous Message format. Update and delete on parent-child relationship when publishing is also not supported. See Publisher Options Tab on page 78.

• Combine several tables into one table using a trigger and then publish from the combined table.

When publishing or subscribing, an adapter instance allows you to change the message using the callout library. See User Callout Library on page 200 for details.

Why does TIBCO Designer display a Java exception error while I’m trying to use TIBCO Designer through Exceed?

When using Exceed to simulate an X Windows environment, start the X Windows server in the Exceed Session Startup Application. In this application, make sure the Run X server checkbox is selected, then try TIBCO Designer again.

When my Sybase transaction log becomes full, the adapter hangs. How can I fix this problem?

When a Sybase transaction log becomes full, if the database setting abort trans on log full is set to false, your application will hang instead of printing a transaction log full error. Execute the following command:

sp_dboption dbname, "abort tran on log full", true


Request-Response Questions | 285

Request-Response Questions

When using request-response, can an INSERT statement with values only (without field names) be sent to the improve application's performance.?

Yes this is allowed. Your application can also send INSERT statements without the binds.

Can an application send UPDATE statements to a subscriber adapter with only those fields which are being updated? That is, if a table has ten records and only two should be updated, can an UPDATE statement be constructed and sent only for those fields?

Yes, this is supported.

Does an adapter instance send responses back as one large message with all rows in it or is the message sent in chunks?

The adapter sends results back to an application as one large message.

If a failure occurs when doing an insert or update, what is returned to the application?

If an error occurs while the adapter is processing a request, an error code and description is returned to the application. In the case of success, a result set and row count is returned to the application.


| 287

Appendix B Trace Messages

This appendix explains the trace messages in TIBCO Adapter for ActiveDatabase. These include status messages, informational messages, error messages, and other types of messages.

Topics


• Status Messages, page 297


288 | Appendix B Trace Messages

Overview

Trace messages provide information about adapter activities. The messages are logged to the console where the runtime adapter was started and to a log file in a location specified during configuration. Trace messages can also be redirected to the TIBCO Hawk Display application, or sent to other applications using the TIBCO Rendezvous transport.

Each trace message can include the following fields in the order shown:

Timestamp Adapter_Identifier Role Category Status_Code Tracking_Identifier Application_Information

The above fields are explained in Trace Message Fields on page 289. The following example shows a trace message containing some of these fields and then identifies the fields.

Example Trace Messages

The following trace messages were written during a session where TIBCO Adapter for Files received an object from TIBCO Adapter for R/3, then processed the object.

Example 1:Adapter Started

The following message indicates that TIBCO Adapter for Files has started. The timestamp indicates when the adapter started, and the role indicates that the trace message is informational, which means the activity is normal for the adapter. The category is identified, and the corresponding status code is displayed. The status code indicates that the adapter started successfully.

2003 Feb 22 20:14:51:718 GMT -8 FileAdapter.FileAdapterConfiguration Info [Configuration] AEFA-000058 TIBCO Adapter for Files successfully initialized

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000067 Message containing class /tibco/public/class/ae/Customer received on subject FROM.SAP tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

2003 Feb 22 20:15:12:937 GMT -8

FileAdapter.FileAdapterConfiguration

Info

[Adapter]

AEFA-000067 Message containing class /tibco/public/class/ae/Customer received on subject FROM.SAP

tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

Timestamp:

Adapter ID:

Role:

Category:

Status Code:

Tracking ID:


Overview | 289

Example 2:MessageReceived

The next set of trace messages indicates the adapter received an object that was sent on the TIBCO Rendezvous subject, FROM.SAP. The #MU3oTJ/WWCV1MU96J0zzwA9kzzw# tracking identifier included in the trace message uniquely identifies the message. The adapter (TIBCO Adapter for R/3) from which the message originated provided the identifier.

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000067 Message containing class /tibco/public/class/ae/Customer received on subject FROM.SAP tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000068 Message containing class /tibco/public/class/ae/Customer written to working file customers.txt in Working Directory F:\ca\integration\001\data_sets\files\wip tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

Example 3:Object Moved

The final trace message indicates the object has been moved to the output directory, which completes the adapter’s interaction with the object. Because the trace message is the termination point, the tracking identifier is not displayed.

2003 Feb 22 20:15:42:812 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000070 File customers.txt is moved to the Output Directory F:\ca\integration\001\data_sets\files\solutions\output

Trace Message FieldsEach trace message includes the following fields:

Table 25 Trace Message Fields

Field Name Description

Timestamp Timestamp of occurrence. For example, 2003 Feb 22 20:14:51:718 GMT -8.

Adapter Identifier

Name of the adapter that wrote the trace message. This is a combination of the adapter acronym and adapter configuration name. For example, the application identifier, ADB.publisher1 identifies a TIBCO Adapter for ActiveDatabase service named publisher1.



Role A role can be:

• Info. Indicates normal adapter operation. No action is necessary. A tracing message tagged with Info indicates that a significant processing step was reached and has been logged for tracking or auditing purposes. Only info messages preceding a tracking identifier are considered significant steps.

• Warn. An abnormal condition was found. Processing will continue, but special attention from an administrator is recommended.

• Error. An unrecoverable error occurred. Depending on the error severity, the adapter may continue with the next operation or may stop altogether.

• Debug. A developer-defined tracing message. In normal operating conditions, debug messages should not display.

When configuring the adapter you define what roles should or should not be logged. For example, you may decide not to log Info roles to increase performance.

Table 25 Trace Message Fields (Cont’d)

Field Name Description (Cont’d)


Overview | 291

Category One of the following:

• Adapter. The adapter is processing an event.

• Application. The adapter is interacting with the database.

• Configuration. The adapter is reading configuration information.

• Database. The adapter is interacting with a database.

• Metadata. The adapter is retrieving metadata from the database.

• Palette. The adapter is interacting with the palette.

• Publisher Service. The publication service is reporting this trace message.

• Request-Response Client Service. The request-response invocation service is reporting this trace message.

• Request-Response Server. The request-response service is reporting this trace message.

• Shutdown. The adapter is shutting down.

• Startup. The adapter is starting.

• Subscription Service. The subscription service is reporting this trace message.

• System. This category is not linked to a specific event process. The trace message may be related to a Windows service related messages, memory allocation, file system error, and so on.

• TibRvComm. The adapter is communicating with TIBCO Rendezvous.

• XML. The adapter is parsing XML documents.

Status Code Unique code for the message and description. Status codes are identified by a unique number and description. If a trace message includes an error or warn role, the status code documentation includes a resolution. See Status Messages on page 297 for details.





Role A role can be:









Overview | 293






















Role A role can be:









Overview | 295






















Tracking Identifier

A unique identifier that is "stamped" on each message by the originating adapter. The tracking identifier remains in effect from a message’s beginning to its completion as it is exchanged by TIBCO applications. If the adapter is the termination point of the message, the tracking identifier is not displayed in the trace message.

You cannot modify the tracking identifier format or configure what information is displayed.

Application Information

Application-specific information added to the tracking info to trace the message back to its source. Set initially by the originating adapter and carried forward. It is augmented by each intermediate component.




Status Messages | 297

Status Messages

Status Code Role Category Resolution

AEADB-100001 %1Database connection succeeded.

infoRole Database Normal operation; no action is necessary.

AEADB-100002 %1Database connection failed.

errorRole Database Check and test the ODBC configuration and restart the TIBCO Runtime Agent.

AEADB-100003 odbc connection as: DSN: %1, User: %2


AEADB-100004 Database driver code: %1Database vendor message: %2

errorRole Database Refer to an ODBC manual and to the manual of the native database by using the error code.

AEADB-100005 Unknown database system.

warnRole Database The adapter is unable to detect the DBMS type of the database it connects to. Make sure a supported DBMS is used. This condition sometimes occurs because a native character set is used. If you are using a supported DBMS, ignore this warning.

AEADB-100006 %1SQL statement preparation succeeded.


AEADB-100007 %1SQL statement preparation failed.

errorRole Database Preparation of a SQL statement failed. Check the configuration for this adapter service and restart the adapter.



AEADB-100008 Problem reading values for %1 from Database

errorRole Database The adapter cannot retrieve data from tables. In the adapter properties file, set the adb.verbose option to on and the adb.debug option to 3 to print the SQL statement to the log file then report this error to TIBCO support.

AEADB-100009 Database Connection Lost, Terminating....

errorRole Database Check the connection to the underlying database and restart the adapter.

AEADB-100010 jdbc connection as : Driver %1, URL %2, User %3


AEADB-100011 %1Database connection closed


AEADB-100012 %1Invalid statement

errorRole Database The adapter detected an invalid SQL statement. For request-response service, an invalid request is processed; otherwise, check your adapter service configuration and restart the adapter instance.

AEADB-100013 Attribute %1 (class %2): No column data ignoring


AEADB-100014 Inserted %1into database

infoRole Adapter Normal operation; no action is necessary.

AEADB-100015 Deleted from database


AEADB-100016 No rows deleted


Status Code Role Category Resolution (Cont’d)



AEADB-100017 Updated database


AEADB-100018 No rows updated


AEADB-100019 No columns specified for WHERE clause in %1

errorRole Adapter The adapter could not find key fields to construct the WHERE clause. Check the repository definition of this class and make sure there is at least one field with isKey=true.

AEADB-100020 Building %1 criteria


AEADB-200001 Foreign key attribute %1 not found in the publishing class.

errorRole Configuration Check your parent-child relationship in publisher configuration and make sure that the child table is joined with the parent table by a common key column, then restart the adapter.

AEADB-200002 %1Class registry not found: %2.

errorRole Configuration Check the configuration of that service to make sure that the class registry exists.

AEADB-200003 %1Class description not found: %2.

errorRole Configuration Check the configuration of that service to make sure that the class description exists. Sometimes, if the loadUrl is not set correctly, this problem occurs.

AEADB-200004 Problem encountered when reading from ADB_PREREGLISTENER

errorRole Configuration The adapter has problems reading from the ADB_PREREGLISTENER table. Check to see that access to that table is allowed and the table is not corrupted.




AEADB-200005 Could not register Hawk method %1

warnRole Configuration A description of a TIBCO Hawk method was not found in the repository. This can happen if the adapter instance is not the latest. Configure the adapter with the latest TIBCO Designer version.

AEADB-200006 Setting %1 = %2.

infoRole Configuration Normal operation; no action is necessary.

AEADB-200007 %1 cannot be used with %2

warnRole Configuration Incomplete options or conflicting options are used. Check the log file for the detailed information and restart the adapter with correct options.

AEADB-200008 Preregistering %1 on %2

infoRole Configuration Normal operation; no action is necessary.

AEADB-200009 %1 creation failed

errorRole Configuration There was an error initializing the publication. Check the ADB_PUBINFO table to see if it is valid. Re-configure the publication.

AEADB-200010 %1 cannot be larger than %2

errorRole Configuration Conflicting options are used. Check the log file and restart the adapter with the correct options.

AEADB-200011 Unsupported encoding type: %1, Use default ASCII Encoding.

errorRole Configuration An unknown character set is detected. Check the language configuration in the OS environment and restart the adapter.




AEADB-200012 AEADB-POLLINGINTERVAL-NOVALUE-ERR

errorRole Configuration Unable to retrieve polling interval value from Hawk method. Retaining original value of %1 milliseconds. Please make sure a value is specified before invoking the setPollingInterval method.

AEADB-200013 AEADB-POLLINGINTERVAL-NEGATIVE-ERR

errorRole Configuration Negative value of %1 for polling interval not allowed. Retaining original value of %2 milliseconds. Please make sure to specify a non-negative value for the polling interval.

AEADB-200014 AEADB-POLLINGINTERVAL-SAME-WARN

warnRole Configuration Polling interval already set to %1 milliseconds.

AEADB-200015 AEADB-POLLINGINTERVAL-CHANGED

infoRole Configuration Polling interval changed to %1 milliseconds.

AEADB-200016 AEADB-POLLINGBATCHSIZE-NOVALUE-ERR

errorRole Configuration Unable to retrieve polling batch size value from Hawk method. Retaining original value of %1. Please make sure a value is specified before invoking the setPollingBatchSize method.

AEADB-200017 AEADB-POLLINGBATCHSIZE-NEGATIVE-ERR

errorRole Configuration Negative value of %1 for polling batch size not allowed. Retaining original value of %2. Please make sure to specify a non-negative value for the polling batch size.

AEADB-200018 AEADB-POLLINGBATCHSIZE-SAME-WARN

warnRole Configuration Polling batch size already set to %1.

AEADB-200019 AEADB-POLLINGBATCHSIZE-CHANGED

infoRole Configuration Polling batch size changed to %1.




AEADB-200020 AEADB-POLLINGBATCHSIZE-CHANGED

warnRole Configuration The repository encoding should be set to UTF-8 if your agent encoding is not ASCII or LATIN-1. Set the repository encoding to UTF-8.

AEADB-300001 %1exception thrown in %2.

errorRole System An adapter internal error. Contact TIBCO Support.

AEADB-300002 Not enough memory available.

errorRole System Check the virtual memory of the system and restart the adapter. If it keeps happening, contact TIBCO Support.

AEADB-300003 MException throw in %1: %2.

errorRole System An Adapter SDK exception was thrown. Report the SDK error code and text to TIBCO Support.

AEADB-300004 %1 on connect socket in thread failed

errorRole System A TCP system call failed. Check your computer’s network ports and TCP libraries. Rebooting the computer may solve the problem.

AEADB-300005 Binding address to socket failed. Listenport = %1


AEADB-300006 Listen call on socket failed

errorRole System A TCP system call failed. Check your computer’s network ports and TCP libraries. Rebooting the machine may solve the problem.

AEADB-300007 Accept on socket failed





AEADB-300008 Socket creation in thread failed


AEADB-300009 Out of memory building the WHERE clause

errorRole Adapter An adapter process has run out of memory. Increase the amount of memory allowed to the adapter on your system.

AEADB-400001 %1Unknown column name %2

errorRole Metadata Request is missing a column field in the Bind data. Add a column, tableName.columnName field, to your bind data.

AEADB-400002 %1Unknown column type: %2 for field: %3.

errorRole Metadata The type %2 is an invalid AE class type. Check in the repository for attribute %3 and change the class type to a valid AE class type.

AEADB-400003 Unknown column type, %1, %2

infoRole Metadata Normal operation; no action is necessary.

AEADB-400004 %1schema %2, tables: %3

debugRole Metadata

AEADB-400005 %1table %2, columns: %3

debugRole Metadata

AEADB-400006 Ill-formatted table name %1

errorRole Metadata A table name of this format is not supported by the adapter. Use a different table name.




AEADB-600001 %1Failed to set limit policy for event queue %2 on session %3: %4

errorRole TibRvComm TIBCO Rendezvous failed to set the limit policy according to the -rv-max-queue-size specification. Please report this error text to TIBCO customer support.

AEADB-600002 %1Failed to get queue count for event queue %2 on session %3: %4

errorRole TibRvComm TIBCO Rendezvous failed to get the queue count for the given session. Please report this error text to TIBCO customer support.

AEADB-600003 %1Failed to get queue limit for event queue %2 on session %3: %4

errorRole TibRvComm TIBCO Rendezvous failed to get the limit policy for the given session. Report the this error text to TIBCO Support.

AEADB-600004 OnEvent: eventname %1

infoRole TibRvComm Normal operation; no action is necessary.

AEADB-700001 SQL: %1


AEADB-700002 %1Building SQL statement succeeded%2.


AEADB-700003 %1Binding data to placeholders: unknown column type, %1 for field %2. Ignoring

errorRole Adapter The type %1 is an invalid AE class type. Check in the repository for attribute %2 and change the class type to a valid AE class type.

AEADB-700004 %1database operation%2 succeeded





AEADB-700005 %1database operation%2 failed

errorRole Adapter The execution of this database statement failed. Use the error returned by the database to determine how to allow this SQL statement to succeed.

AEADB-700006 %1database transaction begin


AEADB-700007 %1database transaction commit


AEADB-700008 %1database transaction rollback.


AEADB-700009 %1Cannot bulk insert for variable binary type in column %2.%3.

warnRole Adapter The subscriber bulk insert option does not support a variable binary data type. Do not use bulk insert for tables with a variable binary data type.

AEADB-700010 %1Database transaction commit failed.

warnRole Adapter The database was unable to commit the transaction. Use the error returned by the database to determine how to allow this transaction to succeed.

AEADB-700011 Encoding error from %1 to %2.

errorRole Adapter An Adapter SDK error converting data to the specified encoding. Make sure the encoding is a supported one.

AEADB-700012 %1Cold start completed.





AEADB-700013 %1Cold start failed.

errorRole Adapter Run the adapter using debug 3 and verbose mode.

AEADB-700014 %1Confirming message.


AEADB-700015 %1 batch commit timeout.


AEADB-700016 %1Bulk insert begins.


AEADB-700017 %1Bulk insert ends.


AEADB-700018 Inserted %1into the corresponding exception table.


AEADB-700019 %1Exception table is not specified.

warnRole Adapter Reconfigure the subscriber by specifying an exception table, or turn off the adb.useExceptTable option (in the adapter properties file) when starting the adapter.

AEADB-700020 %1Cannot find bound data for %2.


AEADB-700021 %1 = %2

debugRole Adapter

AEADB-700022 %1 = NULL

debugRole Adapter




AEADB-700023 %1Bulk insert turning off.


AEADB-700024 Polling publishing table %1


AEADB-700025 Updating delivery status of publishing table %1.


AEADB-700026 %1 = %2

debugRole Adapter

AEADB-700027 %1Publishing by reference and selecting from reference object %2


AEADB-700029 %1


AEADB-700030 Received request %1.


AEADB-700031 Built reply %1.


AEADB-700032 %1sent to %2


AEADB-700033 %1


AEADB-700034 Bad date encountered: %1

errorRole Adapter Check your dateTime-related message data and make sure it is in the correct format.




AEADB-700035 Parameterized subject %1 exceeds TibRv maximum subject length of %2

errorRole Adapter Shorten a parameterized subject string length.

AEADB-700036 Unrecognized event

errorRole Adapter An unrecognized event received. Disable it if possible.

AEADB-700037 %1

errorRole Adapter An unexpected error happened internally. Contact TIBCO Support.

AEADB-700038 Poll for change failed

errorRole Adapter Run the adapter using debug 3 and verbose mode. Check printed database error code.

AEADB-700039 Update sequence Failed

errorRole Adapter Run the adapter using debug 3 and verbose mode. Check the update statement database error code.

AEADB-700041 %1, data = %2


AEADB-700042 Maximum of %1 thread allowed for %2 assuming %3

warnRole Adapter Maximum threads have been exceeded; however, the adapter runs by assuming the default thread count. Currently a publisher manager, subscriber manager and request-response communication can only have one thread each.

AEADB-700044 Main thread (name: %1, id: %2)


AEADB-700045 %1endpoints %2





AEADB-700046 Confirming request


AEADB-700048 %1Error creating reply message

errorRole Adapter Cannot create an Adapter SDK MTree object for a reply message. Contact TIBCO Support.

AEADB-700049 %1Request is being handled by thread %2


AEADB-700050 %1Could not start transaction

errorRole Adapter Cannot set autoCommit to false. Check the status of the database you are trying to connect to and try again. If it still fails, contact TIBCO Support.

AEADB-700051 Request Reply: Error retrieving %1

errorRole Adapter Missing required "sql" field when sending a request (rvMsg) to a request-response service for execution. Reconstruct the request message to include a "sql" field.

AEADB-700052 %1Error binding variables

errorRole Adapter Check the request message format. For a given field, make sure the data type in the message is the same as defined in the database.

AEADB-700053 %1Reply sent to %2


AEADB-700054 %1Error sending reply to %2 - %3

errorRole Adapter TIBCO Rendezvous failed to send a reply message to the request client. Report this error text to TIBCO Support.




AEADB-700055 %1Failed to create sender for reply

errorRole Adapter TIBCO Rendezvous failed to create a reply sender. Please report this error text to TIBCO customer support.

AEADB-700056 RequestReply: No reply name. Not sending reply

errorRole Adapter Specify a reply-subject when defining an adapter request-response service.

AEADB-700057 %1Error retrieving bind position

errorRole Adapter Check the request message format. For a given field in the message, make sure it is present in the database.

AEADB-700058 Stopped thread (%1)


AEADB-700059 Starting thread (name: %1, id: %2)


AEADB-700063 %1starts


AEADB-700064 %1Request: %2

debugRole Adapter

AEADB-700065 %1Reply: %2

debugRole Adapter

AEADB-700066 Load catalog table %1





AEADB-700071 Duplicate agent found %1

errorRole Adapter The adapter is terminated because a same-named configuration is started on the same TIBCO Rendezvous network. For more information, see to Notes on Configuring an Adapter on page 36.

AEADB-700072 %1MExceptionEvent - Not an RVMSG_RVMSG: %2

errorRole Adapter The adapter received an MExceptionEvent where an MDataEvent is expected. Check other running components’ configurations to determine the source of this message.

AEADB-700073 %1Unknown message format

errorRole Adapter The adapter received a TIBCO Rendezvous message of unknown format. Check other running components’ configurations to determine the source of this message.

AEADB-700074 %1Not processing message

errorRole Adapter The message is not being processed because an error has occurred. Check for related error messages to determine what the problem is.

AEADB-700075 %1Error converting event into an Mtree

errorRole Adapter A conversion error occurred in the Adapter SDK layer. The message may be corrupted or of a wrong format. Check the Adapter SDK error message if any to determine what the problem is.

AEADB-700076 %1CM sender: %2, CM sequence number: %3

debugRole Adapter

AEADB-700077 Received message altered:





AEADB-700078 Received message discarded by alterMsgSub()


AEADB-700079 %1Unable to create AE object from the message: %2

warnRole Adapter An unpacking error occurred in the Adapter SDK layer. The message may be corrupted or of a wrong format. Check the Adapter SDK error message if any to determine what the problem is.

AEADB-700080 Received its own message. Discarding.


AEADB-700081 Batch confirming %1 messages


AEADB-700082 RequestReply: Bind argument %1 must include a table name

errorRole Adapter The format of the Bind argument name should be tablename.columnname. This message will not be processed.

AEADB-700083 Published message on %1


AEADB-700084 ADB_SEQUENCE class %1 not supported

errorRole Adapter The class type of ADB_SEQUENCE can only be either string or i4. Make sure the class type of the ADB_SEQUENCE column of the publishing table is specified correctly in the repository.

AEADB-700085 Received ADVISORY %1


AEADB-700086 Publisher batch confirm timeout





AEADB-700087 %1 method invoked


AEADB-700088 Unknown driver %1

errorRole Adapter The adapter currently only supports ODBC drivers (including the IBM client access driver).

AEADB-700089 %1Request received from %2


AEADB-700090 Database error updating %1

errorRole Adapter An error occurred while updating the publishing table. This is a fatal error and the adapter will terminate. Use the error returned by the database to determine how to solve the problem.

AEADB-700091 Publishing ADBOPAQUE format not supported

errorRole Adapter The adapter currently does not support publishing in opaque format.

AEADB-700092 Keeping on original subject token %1


AEADB-700093 Binding data to insert placeholders


AEADB-700094 Polling for database change


AEADB-700095 Terminating agent





AEADB-700096 Unable to insert %1 into list

errorRole Adapter Wildcard TIBCO Rendezvous subject names are not currently supported for preregistered listeners.

AEADB-700097 Updating CM sequence failed

errorRole Adapter Currently not used.

AEADB-700098 %1Error binding parameter %2

errorRole Adapter There was a database error that occurred while binding parameters to a SQL statement. The message will not be processed. Use the database error if any to determine what the problem is.

AEADB-700099 RequestReply: Error retrieving value for parameter %1

errorRole Adapter A request has no value specified for input parameter %1. Add a (data, rvmsgData) field to the [Bind Data] of the request.

AEADB-700100 Received message:


AEADB-700101 Transaction rollback failed

errorRole Adapter The database was unable to rollback the transaction. Use the error returned by the database to determine how to allow this transaction to roll back.

AEADB-700102 Database object %1 not found

errorRole Adapter The database object was not found. Check to see if the object really exists (perhaps in another schema) and if you have permission to access it.




AEADB-700103 %1Unknown column type: %2 for field: %3. Ignoring

warnRole Adapter The type %2 is an invalid AE class type. For this particular situation, the adapter will skip this attribute and continue processing. Check in the repository for attribute %3 and change the class type to a valid AE class type.

AEADB-700104 Insert into the exception table failed

errorRole Adapter There was an error inserting into the exception table. This is a fatal error and the adapter will terminate. Use the error returned by the database to fix the inserts into the exception table.

AEADB-700105 %1%2 are not supported.

errorRole Adapter These AE/TIBCO Rendezvous data types are currently not supported by the adapter. Use only supported data types to represent this field instead; for example, a string or binary.

AEADB-700106 No data fetched for %1


AEADB-700107 New SQL: %1


AEADB-700108 Bulk insert of %1 rows executed for %2


AEADB-700109 Error executing bulk insert of %1 rows for %2

errorRole Adapter There was an error doing the bulk insert into the table. Use the error returned by the database to determine how to fix inserts into the table.

AEADB-700110 Statement changed, flush all previous bulk insert rows





AEADB-700111 Reassign data value to insert statement:


AEADB-700112 Cannot find publication entry. Not publishing message.

errorRole Adapter Internal error. Contact TIBCO Support.

AEADB-700113 Error retrieving column %1

errorRole Adapter The adapter could not retrieve this attribute from the message. Make sure the incoming message contains a value for this attribute.

AEADB-700114 %1

errorRole Adapter Internal error. Contact TIBCO Support.

AEADB-890001 AEADB-CONN-RETRY

infoRole Adapter Reconnect attempt %1 for service %2.

AEADB-890002 AEADB-CONN-RETRYSUCCESS

infoRole Adapter Reconnect succeeded on attempt %1 for service %2.

AEADB-890003 AEADB-CONN-RETRYFAIL

warnRole Adapter Reconnect failed on attempt %1 for service %2 -- will retry in %3 milliseconds. Make sure it is possible to establish an ODBC connection to the database.

AEADB-890004 AEADB-CONN-PUBDUP

warnRole Adapter Connection reestablished for the publisher - message may be a duplicate of a previously published message.

AEADB-890005 AEADB-CONN-REQERR

errorRole Adapter The request received could not be processed due to connection errors. Make sure it is possible to establish an ODBC connection to the database.




AEADB-890006 AEADB-CONN-STOP

errorRole Adapter Adapter stopping due to persistent connection errors. Please check your database and restart adapter. Make sure it is possible to establish an ODBC connection to the database.

AEADB-890007 AEADB-CONN-SVCSUSPEND

infoRole Adapter Adapter suspending service %1 due to persistent connection errors.

AEADB-910004 AEADB-STARTUP-4

errorRole Startup Startup Error. SDK Exception %1 occurred in the adapter initialization while creating the MAppProperties object. The Repository URL is %2 and the Configuration URL is %3. Please refer to SDK documentation for Repository URL and Configuration URL specification. Please cut and paste from SDK documentation for the above.


errorRole Startup Startup Error. SDK Exception %1 received on starting the adapter after initialization. The Repository URL is %2 and the Configuration URL is %3. Please verify your repository and environment settings. Refer to the User Guide documentation.


errorRole Startup Startup Error. Unable to create a connection with the target database using the dsn %1. The database error is: %2 Terminating adapter. Please verify your repository settings for the validity of connection parameters. Refer to the User Guide documentation.




AEADB-920001 AEADB-SUB-1

errorRole Subscriber Subscription error. Subscription service %1 listening on %2 received an unexpected event: %3. The Repository URL is %4 and the Configuration URL is %5. Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to User Guide for details on configuration of subscription service.


errorRole Subscriber Subscription error. Subscription service %1 failed to deserialize the event received on subject %2 and SDK exception thrown is %3. The event is: %4. The Repository URL is %5 and the Configuration URL is %6. Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to User Guide for details on configuration of subscription service.


errorRole Subscriber Subscription error. Subscription service %1 listening on subject %2 received error %3 in SDK message level UserExit %4. Make sure the UserExit parameters are valid and the user exit is invokable from SDK.





errorRole Subscriber Subscription error. Subscription service %1 listening on subject %2 could not get the class description of %3. The Repository URL is %4 and the Configuration URL is %5. Please check the repository configuration for this service. Please make sure the classes to be used by this service are accessible in the repository. Please refer to User Guide for details on how to configure, run and test the subscription service.


errorRole Subscriber Subscription error. Subscription service %1 listening on subject %2 failed due to database error: %3 Database is %4. The database commands and parameters are %5. Please look at the database error, note the database error code and consult with your database documentation.


errorRole Subscriber Subscription error. Subscription service %1 listening on %2 could not send response %3 on reply subject %4. The SDK error is %5. Please check your repository settings for the publish endpoint of this subscription service. Please refer to user guide on how to configure the subscription service.

AEADB-930002 AEADB-PUB-2

errorRole Publisher Publication error. Publication service %1 with publication subject %2 encountered database error: %3 while trying to create publish event with schema %4. Database is %5. The database command is %6. Make sure that the publication service is configured properly. Please look at the database error, note the database error code and consult with your database documentation.




AEADB-930003 AEADB-PUB-3

errorRole Publisher Publication error. Publication service %1 with publishing subject as %2 received event database %3. It failed while converting the event to "Minstance" as it could not get the class description for %4. Repository URL is %5 and the Configuration URL is %6. Please verify the configuration of the publication service and check that the schema/class definitions are present in the repository. Please refer to User Guide for details on how to configure a Publication service.

AEADB-940001 AEADB-REQRESP-1

errorRole Request_Response_Server

Request-Response error. Request-Response service %1 listening on %2 received unexpected null data in incoming request. Expects object %3. The Repository URL is %4 and the Configuration URL is %5. Please check the configuration of the application that is requesting the event and make sure that it matches the inbound event definition for the above RequestResponse service. Please refer to User Guide for details on configuration of RequestResponse service.



Request-Response error. Request-Response service %1 listening on subject %2 failed due to database error: %3Database is %4 and inbound event is %5. Please check the target application command and the parameters and make sure they are valid. Please look at the database error, note the database error code and consult with your database documentation.






Request-Response error. Request-Response service %1 listening on subject %2 failed to create Reply Business Object. Please check the database command and the parameters and make sure they are valid.



Request-Response error. Request-Response service %1 listening on subject %2 receive an error while sending Data on Reply Address %3. Error Message %4. Please check whether the request client is alive or message transport is functioning.

AEADB-990002 AEADB-SHUT-2

errorRole Shutdown Shutdown error. SDK cleanup exception = %1.



TIBCO Software Inc. End User License Agreement | 323

TIBCO Software Inc. End User License AgreementREAD THIS END USER LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING THE SOFTWARE, YOU AGREE TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE TO THESE TERMS, DO NOT DOWNLOAD OR INSTALL THE SOFTWARE AND RETURN IT TO THE VENDOR FROM WHICH IT WAS PURCHASED. RETURNS BY THE ORIGINAL PURCHASER WITHIN THIRTY (30) DAYS OF THE PURCHASE DATE WILL RECEIVE A FULL REFUND.

Upon your acceptance as indicated above, the following shall govern your use of the Software except to the extent all or any portion of the Software (a) is subject to a separate written agreement, (b) includes a separate "click-on" license agreement as part of the download or installation process, or (c) is provided by a third party under the terms set forth in an Addenda at the end of this Agreement, in which case the terms of such addenda shall control over inconsistent terms with regard to such portion(s).

License Grant. The Software is the property of TIBCO or its licensors and is protected by copyright and other laws. While TIBCO continues to own the Software, TIBCO hereby grants to Customer a limited, non-transferable, non-exclusive, license to use the number of Permitted Instances set forth in the Ordering Document, in machine-readable, object code form and solely for Customer's internal business use.

Restrictions. Customer agrees not to (a) make more copies than the number of Permitted Instances plus a reasonable number of backups; (b) provide access to the Software to anyone other than employees, contractors, or consultants of Customer; (c) sublicense, transfer, assign, distribute to any third party, pledge, lease, rent, or commercially share the Software or any of Customer's rights under this Agreement (for the purposes of the foregoing a change in control of Licensee is deemed to be an assignment); (d) use the Software for purposes of providing a service bureau, including, without limitation, providing third-party hosting, or third-party application integration or application service provider-type services, or any similar services; (e) use the Software in connection with ultrahazardous activities, or any activity for which failure of the Software might result in death or serious bodily injury to Customer or a third party; or (f) directly or indirectly, in whole or in part, modify, translate, reverse engineer, decrypt, decompile, disassemble, make error corrections to, create derivative works based on, or otherwise attempt to discover the source code or underlying ideas or algorithms of the Software.

Beta and Evaluation Licenses. Notwithstanding the foregoing, if the Software is being provided for demonstration, beta testing, or evaluation purposes, then Customer agrees (a) to use the Software solely for such purposes, (b) that the Software will not be used or deployed in a production environment, and (c) that such use shall automatically terminate upon the earlier of thirty days from the date Customer receives the right to install the Software, or Customer's receipt of notice of termination from TIBCO.

Technical Support. Provided Customer has paid applicable support fees (not included with Software fees unless separately listed), TIBCO shall provide support for generally available TIBCO Software on an annual basis commencing on the Purchase Date, as follows ("Support"): Customer shall designate at TIBCO's support website https://support.tibco.com/eSupport/newuser.html, the number of technical support contacts permitted under the level of Support purchased (contacts are changeable upon 48-hours prior written notice to TIBCO). Each contact may contact TIBCO for problem

resolution during TIBCO's published support hours corresponding to the level of Support fees paid.

Upon notice from a contact of a Software problem which can be reproduced at a TIBCO support facility or via remote access to Customer's facility, TIBCO shall use reasonable efforts to correct or circumvent the problem according to its published support objectives. TIBCO reserves the right to make changes only to the most currently available version. TIBCO will use reasonable efforts to support the previously released version of the Software for a maximum of six months.

TIBCO shall have no obligation to support the Software (i) for use on any computer system running other than the operating system software for which the Software is approved (as set forth in the Software documentation) and licensed hereunder, or (ii) if Customer has modified or authorized a third party to modify the Software. TIBCO shall have no obligation to modify any version of the Software to run with any new versions of any operating system, or any other third party software or hardware. If Customer purchases Support for any Software, Customer must purchase the same level of Support for all copies of the Software for which it is licensed.

Support may be extended for one-year periods on the anniversary of each Purchase Date at the standard amounts set forth in its price list, for as long as TIBCO offers Support. Customer may reinstate lapsed support for any then currently supported Software by paying all Support fees in arrears and any applicable reinstatement fee. Upgrades, patches, enhancements, bug fixes, new versions and/or new releases of the Software provided from time to time under Support shall be used only as replacements to existing Permitted Instances, and shall not be deemed to increase that number, and use thereof shall be governed by the terms of this Agreement, except for the first paragraph of the Limited Warranty and any right of return or refund.

Consulting Services. Customer may request additional services ("Services") either in an Ordering Document, or by a separate mutually executed work order, statement of work or other work-request document incorporating this Agreement (each, a "Work Order"). Unless otherwise expressly agreed to in a Work Order, all Services and any work product therefrom shall be (a) performed on a time and materials basis, plus meals, lodging, travel, and other expenses reasonably incurred in connection therewith, (b) deemed accepted upon delivery, and (c) exclusively owned by TIBCO (except for confidential information of Customer identified to TIBCO in the Ordering Document), including all right, title and intellectual property or other right or interest therein. Each Work Order is intended to constitute an independent and distinct agreement of the parties, notwithstanding that each shall be construed to incorporate all applicable provisions of this Agreement. Specific to TIBCO training services, additional information regarding courses, registration, restrictions or limitation can be found at TIBCO's website at http://www.tibco.com/services/education under Education Programs. Fees for Services shall be due and payable in United States dollars net 30 from the date of TIBCO's invoice.

Limited Warranty. If Customer obtained the Software directly from TIBCO, then TIBCO warrants that for a period of thirty (30) days from the Purchase Date: (i) the media on which the Software is furnished will be free of defects in materials and workmanship under normal use; and (ii) the Software will substantially conform to its published specifications. This limited warranty extends only to the original Customer hereunder. Customer's sole and exclusive remedy and the


324 | TIBCO Software Inc. End User License Agreement

entire liability of TIBCO and its suppliers under this limited warranty will be, at TIBCO's option, repair, replacement, or refund of the Software and applicable Support fees, in which event this Agreement shall terminate upon payment thereof.

This warranty does not apply to any Software which (a) is licensed for beta, evaluation, testing or demonstration purposes for which TIBCO does not receive a license fee, (b) has been altered or modified, except by TIBCO, (c) has not been installed, operated, repaired, or maintained in accordance with instructions supplied by TIBCO, (d) has been subjected to abnormal physical or electrical stress, misuse, negligence, or accident, or (e) is used in violation of any other term of this Agreement. Customer agrees to pay TIBCO for any Support or Services provided by TIBCO related to a breach of the foregoing on a time, materials, travel, lodging and other reasonable expenses basis. If Customer obtained the Software from a TIBCO reseller or distributor, the terms of any warranty shall be as provided by such reseller or distributor, and TIBCO provides Customer no warranty with respect to such Software.

EXCEPT AS SPECIFIED IN THIS LIMITED WARRANTY, THE SOFTWARE, SUPPORT AND SERVICES ARE PROVIDED "AS IS", ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS, AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, SATISFACTORY QUALITY OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE, ARE HEREBY EXCLUDED TO THE EXTENT ALLOWED BY APPLICABLE LAW. NO WARRANTY IS MADE REGARDING THE RESULTS OF ANY SOFTWARE, SUPPORT OR SERVICES OR THAT THE SOFTWARE WILL OPERATE WITHOUT ERRORS, PROBLEMS OR INTERRUPTIONS, OR THAT ERRORS OR BUGS IN THE SOFTWARE WILL BE CORRECTED, OR THAT THE SOFTWARE'S FUNCTIONALITY OR SERVICES WILL MEET CUSTOMER'S REQUIREMENTS. NO TIBCO DEALER, DISTRIBUTOR, AGENT OR EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS, EXTENSIONS OR ADDITIONS TO THIS WARRANTY.

Indemnity. If Customer obtained the Software from TIBCO directly, then TIBCO shall indemnify Licensee from and against any final judgment by a court of competent jurisdiction, including reasonable attorneys' fees, that the unmodified TIBCO Software infringes any patent issued by the United States, Canada, Australia, Japan, or any member of the European Union, or any copyright, or any trade secret of a third party; provided that TIBCO is promptly notified in writing of such claim, TIBCO has the exclusive right to control such defense and/or settlement, and Licensee shall provide reasonable assistance (at TIBCO's expense) in the defense thereof. In no event shall Licensee settle any claim, action or proceeding without TIBCO's prior written approval. In the event of any such claim, litigation or threat thereof, TIBCO, at its sole option and expense, shall (a) procure for Licensee the right to continue to use the TIBCO Software or (b) replace or modify the TIBCO Software with functionally equivalent software. If such settlement or modification is not commercially reasonable (in the reasonable opinion of TIBCO), TIBCO may cancel this Agreement upon sixty days prior written notice to Licensee, and refund to Licensee the unamortized portion of the license fees paid to TIBCO by Licensee based on a five-year straight-line depreciation. This Section states the entire liability of TIBCO with respect to the infringement of any Intellectual Property rights, and Licensee hereby expressly waives any other liabilities or obligations of TIBCO with respect thereto. The foregoing indemnity shall not apply to the extent any infringement could have been avoided by use of the then-current release.

Limitation of Liability. EXCEPT AS PROVIDED UNDER INDEMNITY OR RESULTING FROM A BREACH OF CONFIDENTIALITY (THE "EXCLUDED MATTERS"), IN NO EVENT WILL EITHER PARTY BE LIABLE FOR ANY LOST DATA, LOST REVENUE, LOST PROFITS, DAMAGE TO REPUTATION, BUSINESS INTERRUPTION, OR ANY OTHER INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, PUNITIVE, EXEMPLARY OR ANY SIMILAR TYPE DAMAGES ARISING OUT OF THIS AGREEMENT, THE USE OR THE INABILITY TO USE THE SOFTWARE, OR THE PROVISION OF ANY SUPPORT OR SERVICES, EVEN IF A PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. EXCEPT FOR THE EXCLUDED MATTERS, IN NO EVENT SHALL A PARTY BE LIABLE TO THE OTHER, WHETHER IN CONTRACT, TORT (INCLUDING ACTIVE OR PASSIVE NEGLIGENCE), BREACH OF WARRANTY, CLAIMS BY THIRD PARTIES OR OTHERWISE, EXCEED THE PRICE PAID BY CUSTOMER UNDER THE APPLICABLE ORDERING DOCUMENT.

THE FOREGOING LIMITATIONS SHALL APPLY EVEN IF THE ABOVE-STATED REMEDY OR LIMITED WARRANTY FAILS OF ITS ESSENTIAL PURPOSE. BECAUSE SOME STATES OR JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO CUSTOMER.

Confidentiality. "Confidential Information" means the terms of this Agreement; all information marked by the disclosing party as proprietary or confidential; any provided software, related documentation or related performance test results derived by Licensee; and any methods, concepts or processes utilized in provided software or related documentation. Confidential Information shall remain the sole property of the disclosing party and shall not be disclosed to any non-Authorized User without the prior written consent of the disclosing party. If Confidential Information is communicated orally, such communication shall be confirmed as "Confidential" in writing within thirty days of such disclosure. The parties agree to protect the Confidential Information of the other in the same manner it protects the confidentiality of similar information and data of its own (and at all times exercising at least a reasonable degree of care). Except with respect to the Software, items will not be deemed Confidential Information if (i) available to the public other than by a breach of an agreement with TIBCO, (ii) rightfully received from a third party not in breach of any obligation of confidentiality, (iii) independently developed by one party without use of the Confidential Information of the other; (iv) known to the recipient at the time of disclosure (other than under a separate confidentiality obligation); or (v) produced in compliance with applicable law or court order, provided the other party is given reasonable notice of the same. Both parties agree to indemnify the other for any damages the other may sustain resulting from their unauthorized use and/or disclosure of the other's Confidential Information. Such damages shall include reasonable expenses incurred in seeking both legal and equitable remedies. To the extent required by law, at Customer's request, TIBCO shall provide Customer with the interface information needed to achieve interoperability between the Software and another independently created program, on payment of TIBCO's applicable fee. Customer agrees to observe obligations of confidentiality with respect to such information.

Export. Software, including technical data, is subject to U.S. export control laws, including the U.S. Export Administration Act and its associated regulations, and may be subject to export or import regulations in other countries. Customer agrees to comply strictly with all such regulations and agrees to obtain all necessary licenses to export, re-export, or import Software.


TIBCO Software Inc. End User License Agreement | 325

Government Use. If the Customer is an agency, department, or other entity of the United States Government ("Government"), the use, duplication, reproduction, release, modification, disclosure or transfer of the Software, or any related documentation of any kind, including technical data or manuals, is restricted in accordance with Federal Acquisition Regulation ("FAR") 12.212 for civilian agencies and Defense Federal Acquisition Regulation Supplement ("DFARS") 227.7202 for military agencies. The Software is commercial computer software and commercial computer software documentation. Use of the Software and related documentation by the Government is further restricted in accordance with the terms of this Agreement, and any modification thereto.

Orders. An Ordering Document shall be deemed accepted only by issuance of a TIBCO invoice and solely for purposes of administrative convenience. None of the terms of the Ordering Document (other than the Software product name, number of Permitted Instances, level of Support, description of Services, and fees due in connection therewith) shall apply for any reason or purpose whatsoever, regardless of any statement on any Ordering Document to the contrary, unless countersigned by an officer of TIBCO. This Agreement constitutes the entire agreement between the parties with respect to the use of the Software, Support and Services, and supersedes all proposals, oral or written, and all other representations, statements, negotiations and undertakings relating to the subject matter hereof. All orders of Software, Support or Services by Customer from TIBCO shall be deemed to occur under the terms of this Agreement (with or without reference to this Agreement), unless expressly superseded by a signed written Agreement between the parties. Software shall be delivered electronically (unless physical shipment is specifically set forth in an Ordering Document), and such delivery shall occur upon e-mail of download information to Licensee at the email address set forth in the Ordering Document or as otherwise provided by Customer to TIBCO. Physical deliveries (if applicable) of Software and documentation which typically accompanies the Software on delivery shall be on CD-ROM, FOB TIBCO, and delivery shall occur by depositing the CD-ROM with TIBCO's overnight carrier (at no charge to Customer).

Term and Termination. Support or Services may be terminated: (a) by either party upon a default of the other, such default remaining uncured for fifteen days from written notice from the non-defaulting party; (b) upon the filing for bankruptcy or insolvency of the other party, (c) by either party upon prior written notice at least sixty days prior to the end of any annual Maintenance period; or (d) by Licensee (for Services), upon ten days prior written notice. Termination of Support or Services shall not terminate this Agreement. Customer may terminate this Agreement in its entirety at any time by destroying all copies of the Software. Upon termination of this Agreement in its entirety, for any reason, Customer must cease using and return or destroy all copies of the Software. Customer's obligation to pay accrued charges and any fees due as of the date of termination, as well as the sections entitled "Confidentiality", "Limited Warranty" and "Limitation of Liability" shall survive any such termination.

Authority. You hereby represent and warrant that you have full power and authority to accept the terms of this Agreement on behalf of Customer, and that Customer agrees to be bound by this Agreement.

General. Fees on the Ordering Document (all to be paid on the latter of thirty days from Invoice by TIBCO or the date set forth in the Ordering Document) do not include sales, use, withholding, value-added or similar taxes, and Customer agrees to pay the same, excluding therefrom taxes related to TIBCO's income and corporate franchise tax. Customer agrees to pay all reasonable costs incurred (including reasonable attorneys' fees) in collecting past due amounts under this Agreement. Except as set forth in the Section entitled

"Limited Warranty" all fees paid under or in connection with this Agreement are non-refundable and no right of set-off exists. All payments of fees due shall be made in U.S. dollars, net 30 from Purchase Date, or, for any other amounts coming due hereafter, net 30 from TIBCO's invoice. A service charge of one and one-half percent per month will be applied to all invoices that are not paid on time. Licensee agrees to pay all sales, use, value-added, withholding, excise and any other similar taxes or government charges, exclusive of TIBCO's income taxes. No delay in the performance of any obligation by either party, excepting all obligations to make payment, shall constitute a breach of this Agreement to the extent caused by force majeure. Customer hereby grants TIBCO and its independent auditors the right to audit Customer's compliance with this Agreement. If any portion of this Agreement is found to be void or unenforceable, the remaining provisions shall remain in full force and effect. This Agreement shall be governed by and construed in accordance with the laws of the State of California, United States of America, as if performed wholly within the state and without giving effect to the principles of conflict of law. The state and/or federal courts in San Francisco, California, USA, shall have exclusive jurisdiction of any action arising out of or relating to this Agreement. The United Nations Convention on Contracts for the International Sale of Goods is excluded from application hereto. If any portion hereof is found to be void or unenforceable, the remaining provisions of this Agreement shall remain in full force and effect.

Definitions. In connection with this Agreement, the following capitalized terms shall have the following meaning: "Agreement" means this End User License Agreement; "Connection" for the TIBCO Software product TIBCO Enterprise for JMS - Full Edition means a TIBCO Enterprise for JMS client connection to the TIBCO Enterprise for JMS server for the purpose of sending or receiving messages and for the purposes of the TIBCO Software products TIBCO SmartSockets and TIBCO SmartMQ software products, a Connection means any network protocol link established with such TIBCO Software (directly or indirectly) to any other entity, including but not limited to software, firmware or hardware; "Customer" means the original purchaser or licensee of the Software and any permitted successors and assigns; "Developer" means one user/developer of a TIBCO Software product for use in Development; "Development" means used for software development purposes only; "Enterprise" means an unlimited number of Permitted Instances for a period of one year from the Purchase Date (unless otherwise set forth in the Ordering Document), at which time existing licenses convert to perpetual and Customer may not thereafter deploy additional Permitted Instances, and in any event, shall (during the one-year unlimited deployment period) exclude any entity which acquires, is acquired by, merged into, or otherwise combined with Customer. Customer hereby agrees to provide TIBCO with notice of the number of Permitted Instances deployed at the end of such one-year period within thirty days thereafter; "Fab" means unlimited use for shop-floor manufacturing applications at a Site; "Workstation" shall mean a single end-user computer that is generally intended to be accessed by one person at a time; "Ordering Document" means any purchase order or similar document or agreement requesting Software, Support or Services; "Permitted Instance(s)" means the number of copies of Software running on a Server Instance, Workstation, User, or Development basis, on a designated Platform, as set forth in an Ordering Document, including, without limitation, Enterprise, Site and Fab licensing; "Platform" means the operating system set forth in an Ordering Document; "Purchase Date" means the date the Ordering Document is accepted by TIBCO; "Server Instance" means a computer with 1 CPU (unless otherwise set forth in the Ordering Document) performing common services for multiple machines; "Site" means an unlimited number of Permitted Instances at a specific physical address set forth in the Ordering Document (or, in the absence of any address, at Customer's corporate headquarters);


326 | TIBCO Software Inc. End User License Agreement

"Software" means the software products listed in an Ordering Document (except as provided in the second paragraph hereof), in whole and in part, along with their associated documentation; "TIBCO" means TIBCO Software Inc.; and "Named User" means the number of named users with access to the Software.

Special Product Provisions. TIBCO BusinessPartner: Customer may sublicense to third parties ("Partners") up to the total Number of Copies of TIBCO BusinessPartner, provided that for every such sublicense, the Number of Copies Customer is licensed to use shall be reduced by the same number, and provided further that prior to delivery of TIBCO BusinessPartner to a Partner, such Partner agrees in writing (a) to be bound by terms and conditions at least as protective of TIBCO as the terms of this Agreement, (b) that TIBCO BusinessPartner be used solely to communicate with Customer's implementation of TIBCO BusinessConnect, and (c) for such Partner to direct all technical support and Maintenance questions directly to Customer. Customer agrees to keep records of the Partners to which it distributes TIBCO BusinessPartner, and to provide TIBCO the names thereof (with an address and contact name) within sixty days of the end of each quarter. Third Party Software: Use of any other third-party software identified by its company and/or product name or otherwise designated in Licensee's Ordering Document (collectively "Third Party Software") is subject solely to the terms and conditions of the click-wrap or shrink-wrap license agreement included with the Third Party Software products, and for which TIBCO shall be an intended third-party beneficiary of same. TIBCO shall have no obligation whatsoever in connection with the Third Party Software (including, without limitation, any obligation to provide maintenance or support) and the provision of Third Party Software is accomplished solely as an accommodation and in lieu of Customer purchasing a license to Third Party Software directly from the third party vendor. Embedded/Bundled Products: Some TIBCO Software embeds or bundles other TIBCO Software (e.g., TIBCO InConcert bundles TIBCO Rendezvous). Use of such embedded or bundled TIBCO Software is solely to enable the functionality of the TIBCO Software licensed on the Cover Page, and may not be used or accessed by any other TIBCO Software, or for any other purpose. Open Source Software: If Licensee uses Open Source software in conjunction with the TIBCO Software, Licensee must ensure that its use does not (i) create, or purport to create, obligations of use with respect to the TIBCO Software, or (ii) grant, or purport to grant, to any third party any rights to or immunities under TIBCO's intellectual property or proprietary rights in the TIBCO Software. You also may not combine the TIBCO Software with programs licensed under the GNU General Public License ("GPL") in any manner that could cause, or could be interpreted or asserted to cause, the TIBCO Software or any modifications thereto to become subject to the terms of the GPL.

Copyright (c) 1994-2003 TIBCO Software Inc. ALL RIGHTS RESERVED.

ADDENDA: Third Party License Agreements


Third Party Software License Agreements | 327

Third Party Software License AgreementsThe following are the software licenses for the Third Party Software provided in connection with the software.

The Apache Software License, Version 1.1

Copyright (c) 1999 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. The names "Xerces", "Xalan" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected]. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

* This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, Lotus Development Corporation., http://www.lotus.com. For more information on the Apache Software Foundation, please see <http://www.apache.org/>./

The Apache Software License, Version 1.1

Copyright (c) 1999 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:

"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. The names "Xalan" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].

5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, Lotus Development Corporation., http://www.lotus.com. For more information on the Apache Software Foundation, please see <http://www.apache.org/>.

W3C IPR SOFTWARE NOTICE

Copyright 2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

The DOM bindings are published under the W3C Software Copyright Noticeand License. The software license requires "Notice of any changes ormodifications to the W3C files, including the date changes were made."

Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL


328 | Third Party Software License Agreements

binding, the pragma prefix can no longer be 'w3c.org'; in the case of the Java binding, the package names can no longer be in the 'org.w3c' package.

Note: The original version of the W3C Software Copyright Notice and License could be found at http://www.w3.org/Consortium/Legal/copyright-software-19980720

Copyright 1994-2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/

This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and modify this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications, that you make:

1.The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.

2.Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, a short notice of the following form (hypertext is preferred, text is permitted) should be used within the body of any redistributed or derivative code: "Copyright [$date-of-software] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/"

3.Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.

International Business Machines Corporation

This product includes software developed by International Business Machines Corporation. Copyright (c) International Business Machines. All rights reserved.

The terms of IBM Public License Version 1.0 apply to the TIBCO End User License Agreement. Any provisions in this License Agreement which differ from the terms of the IBM Public License Version 1.0 are offered by TIBCO Software Inc., alone, and not by any other party. In the event provisions of this License Agreement differ from the terms of the IBM Public License Version 1.0, you may obtain the ICU source code by sending email to [email protected].

"IBM Public License Version 1.0

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS IBM PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

1. DEFINITIONS

"Contribution" means: a) in the case of International Business Machines Corporation ("IBM"), the Original Program, and b) in the case of each Contributor, i) changes to the Program, and ii) additions to the Program; where such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution 'originates' from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program. "Contributor" means IBM and any other entity that distributes the Program.

"Licensed Patents " mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

"Original Program" means the original version of the software accompanying this Agreement as released by IBM, including source code, object code and documentation, if any.

"Program" means the Original Program and Contributions. "Recipient" means anyone who receives the Program under this Agreement, including all Contributors.

2. GRANT OF RIGHTS

a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form.

b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.

c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the



patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.

d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.

3. REQUIREMENTS A Contributor may choose to distribute the Program in object code form under its own license agreement, provided that: a) it complies with the terms and conditions of this Agreement; and b) its license agreement: i) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose; ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; iii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and iv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange. When the Program is made available in source code form: a) it must be made available under this Agreement; and b) a copy of this Agreement must be included with each copy of the Program.

Each Contributor must include the following in a conspicuous location in the Program: Copyright ? {date here}, International Business Machines Corporation and others. All Rights Reserved. In addition, each Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution.

4. COMMERCIAL DISTRIBUTION Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who include the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense. For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those

performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.

5. NO WARRANTY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

6. DISCLAIMER OF LIABILITY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. GENERAL

If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable. If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. In addition, If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed. All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive. IBM may publish new versions (including revisions) of this Agreement from time to time. Each new version of the Agreement will be given a distinguishing version number.



The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received.

In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. No one other than IBM has the right to modify this Agreement. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.

This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation."

Sun Microsystems, Inc. Binary Code License Agreement

READ THE TERMS OF THIS AGREEMENT AND ANY PROVIDED SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY "AGREEMENT") CAREFULLY BEFORE OPENING THE SOFTWARE MEDIA PACKAGE. BY OPENING THE SOFTWARE MEDIA PACKAGE, YOU AGREE TO THE TERMS OF THIS AGREEMENT. IF YOU ARE ACCESSING THE SOFTWARE ELECTRONICALLY, INDICATE YOUR ACCEPTANCE OF THESE TERMS BY SELECTING THE "ACCEPT" BUTTON AT THE END OF THIS AGREEMENT. IF YOU DO NOT AGREE TO ALL THESE TERMS, PROMPTLY RETURN THE UNUSED SOFTWARE TO YOUR PLACE OF PURCHASE FOR A REFUND OR, IF THE SOFTWARE IS ACCESSED ELECTRONICALLY, SELECT THE "DECLINE" BUTTON AT THE END OF THIS AGREEMENT.

1. LICENSE TO USE. Sun grants you a non-exclusive and non-transferable license for the internal use only of the accompanying software and documentation and any error corrections provided by Sun (collectively "Software"), by the number of users and the class of computer hardware for which the corresponding fee has been paid.

2. RESTRICTIONS. Software is confidential and copyrighted. Title to Software and all associated intellectual property rights is retained by Sun and/or its licensors. Except as specifically authorized in any Supplemental License Terms, you may not make copies of Software, other than a single copy of Software for archival purposes. Unless enforcement is prohibited by applicable law, you may not modify, decompile, or reverse engineer Software. You acknowledge that Software is not designed, licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility. Sun disclaims any express or implied warranty of fitness for such uses. No right, title or interest in or to any trademark, service mark, logo or trade name of Sun or its licensors is granted under this Agreement.

3. LIMITED WARRANTY. Sun warrants to you that for a period of ninety (90) days from the date of purchase, as evidenced by a copy of the receipt, the media on which Software is furnished (if any) will be free of defects in materials and workmanship under normal use. Except for the foregoing, Software is provided "AS IS". Your exclusive remedy and Sun's entire liability under this limited warranty will be at Sun's option to replace Software media or refund the fee paid for Software.

4. DISCLAIMER OF WARRANTY. UNLESS SPECIFIED IN THIS AGREEMENT, ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A

PARTICULAR PURPOSE OR NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

5. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event will Sun's liability to you, whether in contract, tort (including negligence), or otherwise, exceed the amount paid by you for Software under this Agreement. The foregoing limitations will apply even if the above stated warranty fails of its essential purpose.

6. Termination. This Agreement is effective until terminated. You may terminate this Agreement at any time by destroying all copies of Software. This Agreement will terminate immediately without notice from Sun if you fail to comply with any provision of this Agreement. Upon Termination, you must destroy all copies of Software.

7. Export Regulations. All Software and technical data delivered under this Agreement are subject to US export control laws and may be subject to export or import regulations in other countries. You agree to comply strictly with all such laws and regulations and acknowledge that you have the responsibility to obtain such licenses to export, re-export, or import as may be required after delivery to you.

8. U.S. Government Restricted Rights. If Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in Software and accompanying documentation will be only as set forth in this Agreement; this is in accordance with 48 CFR 227.7201 through 227.7202-4 (for Department of Defense (DOD) acquisitions) and with 48 CFR 2.101 and 12.212 (for non-DOD acquisitions).

9. Governing Law. Any action related to this Agreement will be governed by California law and controlling U.S. federal law. No choice of law rules of any jurisdiction will apply.

10. Severability. If any provision of this Agreement is held to be unenforceable, this Agreement will remain in effect with the provision omitted, unless omission would frustrate the intent of the parties, in which case this Agreement will immediately terminate.

11. Integration. This Agreement is the entire agreement between you and Sun relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification of this Agreement will be binding, unless in writing and signed by an authorized representative of each party.

JAVA(TM) INTERFACE CLASSES JAVA API FOR XML PROCESSING (JAXP), VERSION 1.1 SUPPLEMENTAL LICENSE TERMS

These supplemental license terms ("Supplemental Terms") add to or modify the terms of the Binary Code License Agreement (collectively, the "Agreement"). Capitalized terms not defined in these Supplemental Terms shall have the same meanings ascribed to them



in the Agreement. These Supplemental Terms shall supersede any inconsistent or conflicting terms in the Agreement, or in any license contained within the Software.

1. Software Internal Use and Development License Grant. Subject to the terms and conditions of this Agreement, including, but not limited to Section 3 (Java(TM) Technology Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive, non-transferable, limited license to reproduce internally and use internally the binary form of the Software, complete and unmodified, for the sole purpose of designing, developing and testing your Java applets and applications ("Programs").

2. License to Distribute Software. In addition to the license granted in Section 1 (Software Internal Use and Development License Grant) of these Supplemental Terms, subject to the terms and conditions of this Agreement, including but not limited to Section 3 (Java Technology Restrictions), Sun grants you a non-exclusive, non-transferable, limited license to reproduce and distribute the Software in binary form, provided that you (i) distribute the Software complete and unmodified and only bundled as part of your Programs, (ii) do not distribute additional software intended to replace any component(s) of the Software, (iii) do not remove or alter any proprietary legends or notices contained in the Software, (iv) only distribute the Software subject to a license agreement that protects Sun's interests consistent with the terms contained in this Agreement, and (v) agree to defend and indemnify Sun and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results from the use or distribution of any and all Programs and/or Software.

3. Java Technology Restrictions. You may not modify the Java Platform Interface ("JPI", identified as classes contained within the "java" package or any subpackages of the "java" package), by creating additional classes within the JPI or otherwise causing the addition to or modification of the classes in the JPI. In the event that you create an additional class and associated API(s) which (i) extends the functionality of the Java platform, and (ii) is exposed to third party software developers for the purpose of developing additional software which invokes such additional API, you must promptly publish broadly an accurate specification for such API for free use by all developers. You may not create, or authorize your licensees to create additional classes, interfaces, or subpackages that are in any way identified as "java", "javax", "sun" or similar convention as specified by Sun in any naming convention designation.

4. Trademarks and Logos. You acknowledge and agree as between you and Sun that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL and iPLANET trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL and iPLANET-related trademarks, service marks, logos and other brand designations ("Sun Marks"), and you agree to comply with the Sun Trademark and Logo Usage Requirements currently located at http://www.sun.com/policies/trademarks. Any use you make of the Sun Marks inures to Sun's benefit.

5. Source Code. Software may contain source code that is provided for reference purposes pursuant to the terms of this Agreement. Source code may not be redistributed unless expressly provided for in this Agreement. Portions of this download are governed by the Apache Source Code License and are identified in the Readme file. A copy of the Apache License is supplied with the Apache Source Code.

6. Termination for Infringement. Either party may terminate this Agreement immediately should any Software become, or in either

party's opinion be likely to become, the subject of a claim of infringement of any intellectual property right.

For inquiries please contact: Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303

Microstar Software.

Portions of this Software may include software provided by Microstar Software. Copyright (c) 1997, 1998 by Microstar Software. All rights reserved.

DataDirect Technologies (Merant) Software.

Portions of this software are copyrighted by DataDirect Technologies (MERANT), 1991-2002.


| 333

Index

Symbols

* 184. 184> 184_ 36, 184

A

access to DB2 AS/400 tables 73adapter

changing a configuration 37, 216checking for duplicate 17component (operation) information through TIBCO

Hawk 245error messages when changing a configuration 38naming restrictions 36size limitations 36starting as a Windows service 131stopping 37tracing 211

adapter configuration, changing 37, 216ADB_ERROR_TEXT 177ADB_ERROR_TIME 177ADB_L_CMSEQUENCE 171ADB_L_DELIVERY_STATUS 171ADB_OPCODE 170, 177ADB_REF_OBJECT column in the publishing

table 192ADB_SEQUENCE 170ADB_SET_SEQUENCE 170ADB_SOURCE 11, 176ADB_SUBJECT 170ADB_TIMESTAMP 170ADB_UPDATE_ALL 170, 177adbDateTime 190adbPreCommit() 202

addinglisteners 186

adding a sequence for parent-child 194adding an association for parent-child 195agents 232alerter

on Microsoft SQL Server 134on Sybase SQL Server 140

alerts 232auto-discovery process, TIBCO Hawk 234

B

binary type 185bind statements 149

C

callout library 200callout library, compilers 203certified message delivery

exception handling 283moving ledger files 188preregistering listeners 186

Class Microagent Name field, adapter 64closure field 148column names in an exception table 178column names, reserved prefix 37columns, maximum number 36command line arguments 246


334 | Index

commandsadbagent 28, 111, 131, 139, 142adbalerter_ora8 137Connect 46, 50copy 138, 141cp 140execute 137isql 138, 139, 140, 141, 142select 28, 29, 30, 31, 32sqlplus 25, 32, 137tibrvsend 31

commit_and_notify 135commit_and_notify_table 135compilers for callout libraries 203configuration properties, retrieving through TIBCO

Hawk 246conversion, messages 6custom RPC operation 159customer support xix

D

dat file format 22data format 6data source, ODBC

using 118database errors, capturing 177database type mapping 184Date types 185date/time values 190dateTime 183DB2 on OS/390 trigger statements syntax 218debug, adapter option 117delete trigger 71destination table

schema 10distributed queues 166dot character 184dsn, adapter option 118dsn, alerter option on Oracle 136duplicate adapters 17

E

error messages about database cleanup 38examples

commands for running an adapter as a service 131REF cursor procedure 168

Exceed FAQ 284exception table

defined 11structure of 177

exception table, column names in 178

F

fault tolerance 100file format

dat 22VC 22

Float data type 185format, messages 6

G

global variables 38setting for monitoring 63

I

id alerter option on Oracle 136

K

key columns, requirement for publish-by-reference 16


Index | 335

L

ledger fileslocation 188moving 188publication size status 119publication timeout status 119retrieving information through TIBCO Hawk 255

listeners, adding 186load balancing 101, 131

across adapters 166in an adapter 164

Log File field, adapter 61log file options 211log files location 59Log Info field, adapter 61Log to Standard field, adapter 61logtest, sample program 18LONG data type 78loop detection

column used for 176defined 11using for replication 11

M

mapping database types 184messages 6

conversion 6data format 6

microagent methods supported 238Microagent Session field, adapter 64MInstance

data format 74MInstance data format 74multiple file project 12

N

naming restrictionsadapters 36database columns 37publishing table 81subjects 184

notify procedureon Microsoft SQL Server 138on Sybase 140

notifytable procedureon Microsoft SQL Server 138on Sybase 140

NULL attributes 85

O

obfuscation 115opaque format, using to publish 18

P

parameterized subject 185binary type 185Date types 185Float type 185illegal characters 185


336 | Index

parametersAE Type 72, 86Batch Publish Status Updates 53Child Table Mapping 87Class Reference 82, 90, 96Debug Level 56Deploy On Save 38Do Not Generate Triggers 81Enable Loop Detection 81Endpoint Reference 82, 90, 96Generate Verbose Output 57Join To 73, 87Polling Batch Size (Maximum Rows) 52Polling Interval 52Publish Child Data 54Publisher Batch Confirm Timeout 53Publishing Table 81Reply Subject 96Storage Mode 80Subscriber Batch Commit Size 54Subscriber Batch Commit Timeout 54Subscriber Bulk Insert Size 55Table Name 87Tables and Columns 72, 86Type 72, 86Update Mode 81Update Trigger? 72Use Exception Table 55Use? 72, 86User Key 72, 86

parent/child publication 16parent-child association 195parent-child sequence 194password property 123PL/SQL procedure for REF cursor 168preregistering listeners 186Publication Service typical flow diagram 4publications

changing subject 16size limitations 36

publish-child-data, adapter option 119publishing

by reference 15, 78by value 15source data 192

publishing tablecolumns in 170name size 81restrictions for 78

pwdalerter option on Oracle 136

Q

quality of serviceand load balancing 166

queue member load 167

R

record size, limitations 36REF data type 168reference object location 192request

defined 146request/response

load balancing for 166using 144using multiple threads 164

response defined 147reviewLedger, TIBCO Hawk method 255RPC programs, client 162running the adapter as a Windows service 131rv_Rpc() 150rv_Send() 150rv_SendWithReply() 150RVMSG_DATETIME 183RVMSG_INT 183RVMSG_OPAQUE 183RVMSG_REAL 183RVMSG_STRING 183


Index | 337

S

same-named adapters 17sample programs

logtest 18schema changes affecting adapter configuration 38schemas

for related tables 74referencing external 10

sequence number 170source data publishing 192source data publishing example 198source table

loop detection column 176schema for 10

source table changes 171SQL statement terminator 218SQL_BATCHRETURN class, structure of 157SQL_BIND class, structure of 158SQL_OPS class, structure of 155SQL_RESULTSET class, structure of 156SQL_RETURN class, structure of 156SQL_ROW class, structure of 156SQL_STATEMENT class, structure of 158Standard Microagent Name field, adapter 63standard RPC operation 155starting an alerter on Oracle 135stopping an adapter 37sub-batch-commit-timeout, adapter option 120sub-bulk-insert-size, adapter option 120subjects

changing dynamically 16naming restrictions 184parameterized 185subscriber 36using wildcards 184, 186

subscriptionssize limitations 36wire format for 190

substitution 38support, contacting xix–system

configurl command-line argument 116

T

table access problems, overcoming 73technical support xixTIBCO Hawk

background information 232enterprise monitor components 232methods supported 238Monitoring tab use with 63

TIBCO Hawk methodsgetComponents 245getConfig 246getRvConfig 249getStatus 250reviewLedger 255

TIBCO Rendezvous, retrieving configuration through TIBCO Hawk 249

Tracing 288tracing features 211Tracing Levels and Fields 289tracking identifier 288, 296triggers

how they are generated 171no primary key 71purpose 171

U

underscore character 184update feature 16update trigger 71Use Advanced Logging field, adapter 59user authority 73user callout library 200user schema 134username property 123use-trace-file, adapter option 211usr

alerter option on Oracle 136


338 | Index

V

variable substitution 38variables 38version, adapter option 112, 123

W

wildcard subject names 184, 186


adadb userguide

Documents