TIBCO Adapter™ for

ActiveDatabase
User’s Guide
Software Release 5.1.0
November 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
TIBCO Adapter for ActiveDatabase Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Publication and Subscription Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Message Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
TIBCO Rendezvous Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
TIBCO Enterprise for JMS Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Adapter Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Run-time Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
TIBCO Runtime Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Polling or Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Referencing External Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Loop Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Master-Master Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Multi-file Format Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
DAT File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Supported SQL Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Publication Service Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Publish by Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Publish by Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Update Feature for Parent-Child Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Changing 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Required Platform and Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Saving the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Testing the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Notes on Configuring an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Configuration Recommendations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Changing an Existing Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Using Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Design-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Using Connection Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Saving Connection Parameters for Reuse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Using 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

TIBCO Adapter for ActiveDatabase User’s Guide

 Contents v
|

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Quality of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Delivery Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Wire Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Publication Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Tables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Adding Child Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
DB2/OS390 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Publisher Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Subscription Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Table Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Child Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Subscriber Options for DB2 on OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Subscriber Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Request-Response Service Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Call Operation Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Advanced 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

TIBCO Adapter for ActiveDatabase User’s Guide

vi
| Contents
Start the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Monitor the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Adapter Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Properties File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Run-time Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Obfuscating or Encrypting a Password in the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Project Locator String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Server-based Project Locator String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Local Project Locator String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Installing the Adapter as a Service on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Creating Multiple Services for the Same Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

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

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Setting Up and Starting the Alerter on Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Oracle Alerter Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Oracle Alerter Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Setting Up and Starting the Alerter on Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Alerter Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Setting Up and Starting the Alerter on Sybase SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Alerter Setup on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Alerter Setup on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

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

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Request-Response Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
TIBCO ActiveEnterprise or XML Message Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
TIBCO Rendezvous Message Request Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
TIBCO ActiveEnterprise or XML Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
TIBCO Rendezvous Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
RPC Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Standard RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Custom RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Implementing Client RPC Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

TIBCO Adapter for ActiveDatabase User’s Guide

 Contents vii
|
Load Balancing in a Single Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Load Balancing Across Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Oracle REF Data Type Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

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

Publishing Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Removing Records from the Publication Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Stored Procedures and Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Publication Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Changing the Publication Trigger to Publish a Subset of Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Source Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Using an Exception Table as a Source Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Incremental Parent-child Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
DB2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Mapping to Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Subject Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Parameterized Subject Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Preregistering a Certified Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Changing the Location of the Ledger File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Sending Messages to an Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
adbDateTime Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Publishing by Reference Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Changing Repository Objects for Parent-Child Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Table to Record Sequence Numbers (DB2 on AS/400) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
User Callout Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Using the alterMsgPub and alterMsgSub Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Using the adbPreCommit Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Building 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Fine-Tuning Tracing Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Log File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

TIBCO Adapter for ActiveDatabase User’s Guide

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Configuring the Adapter at Design-time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Special Configurations for Supporting a UTF-8 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Run-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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
activateTraceRole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
deactivateTraceRole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
getAdapterServiceInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
getComponents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
getConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
getConfigProperties(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
getHostInformation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
getRvConfig(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
getStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
getTraceSinks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
getVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
_onUnsolictedMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
preRegisterListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
reviewLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
setTraceSinks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
stopApplicationInstance(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
unRegisterListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
getEventQueueSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
setDebugLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
toggleVerboseFlag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
showConfiguration(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
terminateADBagent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

TIBCO Adapter for ActiveDatabase User’s Guide

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

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

General Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Request-Response Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

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

TIBCO Adapter for ActiveDatabase User’s Guide

x
| Contents

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

TIBCO Adapter for ActiveDatabase User’s Guide

xii
| Figures

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

TIBCO Adapter for ActiveDatabase User’s Guide

xiv
| Tables

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

TIBCO Adapter for ActiveDatabase User’s Guide

xvi
| Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Adapter for ActiveDatabase Documentation

The 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 Documentation

You 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

TIBCO Adapter for ActiveDatabase User’s Guide

 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

TIBCO Adapter for ActiveDatabase User’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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

xx
| How to Contact TIBCO Customer Support

TIBCO Adapter for ActiveDatabase User’s Guide

 |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

TIBCO Adapter for ActiveDatabase User’s Guide

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.

Capabilities
The 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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

4
| Chapter 1 Introduction

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 Services

The 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

Database Database
Application 1 Application 2

Adapter for Adapter for

ActiveDatabase ActiveDatabase
Publisher Subscriber

TIBCO Messaging

Other TIBCO
Applications

TIBCO Adapter for ActiveDatabase User’s Guide

 Adapter Services 5
|

Request-Response Service
The 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

TIBCO TIBCO
Application 1 Application 2

TIBCO Messaging

Adapter

Database

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 Adapter for ActiveDatabase User’s Guide

6
| Chapter 1 Introduction

Message Transports

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

TIBCO Rendezvous Transport

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Message Transports 7
|

TIBCO Enterprise for JMS Transport

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

TIBCO Adapter for ActiveDatabase User’s Guide

8
| Chapter 1 Introduction

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

Database

ODBC JDBC

TIBCO Adapter for TIBCO

Alerter
ActiveDatabase Designer

TIBCO Messaging

Application 1 Application 2

Run-time Adapter
A 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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

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

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 Agent

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

TIBCO Adapter for ActiveDatabase User’s Guide

10
| Chapter 1 Introduction

Polling or Alerter
An 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 Schemas

When 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 Table
You 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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Adapter Architecture 11
|

• 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 Detection
If 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 Replication
You 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.

TIBCO Adapter for ActiveDatabase User’s Guide

12
| Chapter 1 Introduction

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 Projects

This 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

TIBCO Adapter for ActiveDatabase User’s Guide

 Adapter Architecture 13
|

DAT File Format

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

TIBCO Adapter for ActiveDatabase User’s Guide

14
| Chapter 1 Introduction

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Value
When 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 Reference
The 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.

TIBCO Adapter for ActiveDatabase User’s Guide

16
| Chapter 1 Introduction

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 Publication

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

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.

Changing a Publication Subject Without Using TIBCO Designer

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

18
| Chapter 1 Introduction

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

20
| Chapter 1 Introduction

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

• Overview, page 22
• 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

TIBCO Adapter for ActiveDatabase User’s Guide

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 Software

This 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 Starting
Before 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.

Tables
The 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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Overview 23
|

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

Actions
When 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

Publishing Destination
Table Table
Insert
Trigger Exception
Table

Source
Table

Publisher Subscriber
Adapter Adapter

TIBCO Messaging

Tasks
This exercise consists of the following tasks:
• Create the Database Tables
• Configure the Properties File
• Start the Adapters

TIBCO Adapter for ActiveDatabase User’s Guide

24
| Chapter 2 Getting Started

• Change the Table Values and Receive Notification

• Exit the Query Tool and Adapters
• Clean Up

Exercise
This 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

TIBCO Rendezvous JMS Transport

Item Transport Value 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

TIBCO Adapter for ActiveDatabase User’s Guide

 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 - Production
JServer 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>

TIBCO Adapter for ActiveDatabase User’s Guide

26
| Chapter 2 Getting Started

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.

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.

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Configure the Properties File 27
|
# Change these settings for your login and dsn for Demo1
adb.user joanne
adb.password joanne
adb.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.

TIBCO Adapter for ActiveDatabase User’s Guide

28
| Chapter 2 Getting Started

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 --propFile
C:\TIBCO\adapter\adadb\5.1\demo\demo1\rvpub.tra

> adbagent --propFile

C:\TIBCO\adapter\adadb\5.1\demo\demo1\rvsub.tra

If using TIBCO Enterprise for JMS:

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

> adbagent --propFile

C:\TIBCO\adapter\adadb\5.1\demo\demo1\jmssub.tra

TIBCO Adapter for ActiveDatabase User’s Guide

 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.
If using TIBCO Rendezvous:
SQL> insert into ORDER_TABLE values(111,'Oak Table',499.95);

SQL> commit;

If using TIBCO Enterprise for JMS:

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.
If using TIBCO Rendezvous:
SQL> select * from SUB_ORDER;

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

ORDER_PRICE
-----------
111
Oak Table
499.95

If using TIBCO Enterprise for JMS:

SQL> select * from SUB_ORDER;

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

TIBCO Adapter for ActiveDatabase User’s Guide

30
| Chapter 2 Getting Started

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

ITEM_PRICE
-----------
111
Oak 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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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:
If using TIBCO Rendezvous:
tibrvsend _ADB.rvpub.TERMINATE now
tibrvsend _ADB.rvsub.TERMINATE now

If using TIBCO Enterprise for JMS:

tibrvsend _ADB.jmspub.TERMINATE now
tibrvsend _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.

TIBCO Adapter for ActiveDatabase User’s Guide

32
| Chapter 2 Getting Started

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

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

• Overview, page 34
• 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

TIBCO Adapter for ActiveDatabase User’s Guide

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 Tasks
Use 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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Project

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

TIBCO Adapter for ActiveDatabase User’s Guide

36
| Chapter 3 Adapter Instance Options

Testing the Adapter

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Recommendations
The 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 Configuration

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

TIBCO Adapter for ActiveDatabase User’s Guide

38
| Chapter 3 Adapter Instance Options

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

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

40
| Chapter 3 Adapter Instance Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

JmsSslProvider Tells applications where the JMS SSL daemon is located.

Url

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.

TIBCO Adapter for ActiveDatabase User’s Guide

42
| Chapter 3 Adapter Instance Options

Table 2 Predefined Global Variables (Cont’d)

Variable Description (Cont’d)

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.
See the TIBCO Hawk Installation and Configuration manual for details about this
parameter.

TIBCO Adapter for ActiveDatabase User’s Guide

 Overview 43
|
Table 2 Predefined Global Variables (Cont’d)

Variable Description (Cont’d)

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.
See the TIBCO Hawk Installation and Configuration manual for details about this
parameter.

TIBCO Adapter for ActiveDatabase User’s Guide

44
| Chapter 3 Adapter Instance Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

46
| Chapter 3 Adapter Instance Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Design-time Connection Tab 47
|

Table 3 JDBC Drivers and URLs (Cont’d)

Database Driver and URL (Cont’d)

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

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

TIBCO Adapter for ActiveDatabase User’s Guide

48
| Chapter 3 Adapter Instance Options

Use Design-time Connection For Run-time

This field is not active.

Using Connection Templates

TIBCO 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 Reuse

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Parameters

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

TIBCO Adapter for ActiveDatabase User’s Guide

50
| Chapter 3 Adapter Instance Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

52
| Chapter 3 Adapter Instance Options

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

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

54
| Chapter 3 Adapter Instance Options

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.

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.

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

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

56
| Chapter 3 Adapter Instance Options

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.

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.

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

58
| Chapter 3 Adapter Instance Options

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.

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

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

only as needed.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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: When this box is unchecked, you configure a standard log file. This is the default.
Standard Log File Fill out the remaining fields on this tab. You do not need to read the rest of this
field description.

Checked: Log When this box is checked, you can set two standard output destinations (sinks)
Sink 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.

TIBCO Adapter for ActiveDatabase User’s Guide

60
| Chapter 3 Adapter Instance Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

62
| Chapter 3 Adapter Instance Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

64
| Chapter 3 Adapter Instance Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

• Overview, page 66
• Adding Child Tables, page 73
• Publication Service Tabs, page 69
• Subscription Service Tabs, page 83
• Request-Response Service Tabs, page 91

TIBCO Adapter for ActiveDatabase User’s Guide

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 Service
This 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

TIBCO Adapter for ActiveDatabase User’s Guide

 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

The Transactional option is no longer supported. The option is included for

backward compatibility with version 5.0 and 4.x adapters.

(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 Formats
Services must use the same wire format to exchange data.
• Rendezvous Message (TIBCO Rendezvous Transport Type only)

TIBCO Adapter for ActiveDatabase User’s Guide

68
| Chapter 4 Adapter Service Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Tab
The 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.

TIBCO Adapter for ActiveDatabase User’s Guide

70
| Chapter 4 Adapter Service Options

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Publication Service Tabs 71
|

Tables Tab
You 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.

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

72
| Chapter 4 Adapter Service Options

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Publication Service Tabs 73
|

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_schema

grant 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 master
EXEC 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 Tables

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

TIBCO Adapter for ActiveDatabase User’s Guide

74
| Chapter 4 Adapter Service Options

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.

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Publication Service Tabs 75
|

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.

TIBCO Adapter for ActiveDatabase User’s Guide

76
| Chapter 4 Adapter Service Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Publication Service Tabs 77
|

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

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.

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_).

TIBCO Adapter for ActiveDatabase User’s Guide

78
| Chapter 4 Adapter Service Options

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 Tab

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Publication Service Tabs 79
|

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.

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

80
| Chapter 4 Adapter Service Options

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.

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Publication Service Tabs 81
|

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.

TIBCO Adapter for ActiveDatabase User’s Guide

82
| Chapter 4 Adapter Service Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.
You can configure parameters under the following tabs:
• Configuration Tab on page 83
• Table Tab on page 85
• Child Table Mappings Tab on page 87
• Subscriber Options Tab on page 89
• Advanced Tab on page 90

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

TIBCO Adapter for ActiveDatabase User’s Guide

84
| Chapter 4 Adapter Service Options

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

• Distributed Queue

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.
• Rendezvous Message (TIBCO Rendezvous only)
• XML Message (TIBCO Rendezvous or JMS)
• ActiveEnterprise Message (TIBCO Rendezvous only)

Connection Factory Type

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Subscription Service Tabs 85
|

Table Tab
You 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.

TIBCO Adapter for ActiveDatabase User’s Guide

86
| Chapter 4 Adapter Service Options

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Subscription Service Tabs 87
|

Join To — Joins two tables.

Child Table Mappings Tab

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

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

88
| Chapter 4 Adapter Service Options

Subscriber Options for DB2 on OS/390

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Subscription Service Tabs 89
|

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)

TIBCO Adapter for ActiveDatabase User’s Guide

90
| Chapter 4 Adapter Service Options

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.
You can configure parameters under the following tabs:
• Configuration Tab on page 91
• Call Operation Tab on page 94
• Advanced Tab on page 96

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.
• 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. Only the options that are available with the selected Transport
Type, Connection Factory Type, Mode or Wire Format are displayed.

TIBCO Adapter for ActiveDatabase User’s Guide

92
| Chapter 4 Adapter Service Options

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
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
• Distributed Queue

Connection Factory Type

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)

TIBCO Adapter for ActiveDatabase User’s Guide

 Request-Response Service Tabs 93
|

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

TIBCO Adapter for ActiveDatabase User’s Guide

94
| Chapter 4 Adapter Service Options

Call Operation Tab

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

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Request-Response Service Tabs 95
|

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.

TIBCO Adapter for ActiveDatabase User’s Guide

96
| Chapter 4 Adapter Service Options

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 | 97

Chapter 5 Deploying and Starting the Adapter Using

TIBCO Administrator Enterprise Edition

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.

Topics

• Overview, page 98
• 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

TIBCO Adapter for ActiveDatabase User’s Guide

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.

Table 4 TIBCO Administrator Features

Enterprise Repository
Feature
Edition 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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

• Overview, page 106

• 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

TIBCO Adapter for ActiveDatabase User’s Guide

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

tibco.repourl tibcr@ADBDemo1
tibco.configurl rvpub
application.args adbagent -system:propFile
C:/tibco/adapter/adadb/5.1/bin/adbagent.tra
application.start.dir C:/tibco/adapter/adadb/5.1/bin/

• 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 Adapter for ActiveDatabase User’s Guide

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Adapter

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

TIBCO Adapter for ActiveDatabase User’s Guide

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

Table 5 Run-time Adapter Options

Option Description
--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.
If propFile is not given, the properties file prefix must have
the same name as the adapter executable prefix.

--start --propFile fileName Microsoft Windows Only. Start the 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.

--stop --propFile fileName Microsoft Windows Only. Stops the 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.

-version Displays the version of TIBCO Adapter for ActiveDatabase.

Stop the Adapter

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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/config1
tibco.repourl=tibcr://TEST_PROJECT
tibco.username=admin
tibco.password=samplePassword
tibco.clientVar.service=7600
tibco.clientVar.daemon=tcp:7600

Properties defined in the properties file override the same properties defined in
the project.

Properties File Format

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

TIBCO Adapter for ActiveDatabase User’s Guide

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

Run-time Adapter Properties File Parameters

Properties 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 The location of the adapter service inside the project file. If a relative
relative_path path is specified, the adapter service is assumed to be under the
default area in the project file (/tibco/private/adapter/). For
or
example, the following value connects to an adapter service named
tibco.configurl adbpub in the /tibco/private/adapter/ directory:
absolute_path 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.p The password to connect to the targeted database. This can be

assword
obfuscated using the instructions in Obfuscating or Encrypting a
Password in the Properties File on page 123.

TIBCO Adapter for ActiveDatabase User’s Guide

 Adapter Properties File 117
|

Table 6 Required Run-Time Adapter Properties File Parameters (Cont’d)

Property (Cont’d) Description (Cont’d)

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/

Additional Properties
You can modify the following parameters as necessary. Properties that start with
ntservice are available only on Microsoft Windows platforms.

All paths inside a properties file, including Windows directory names, must use
forward slashes.

Table 7 Additional Run-Time Adapter Properties File Parameters

Description
Property

adb.addCustomHawkMethodsToClas The property is not set by default. Setting the property to

sMAgent <on/off>
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 When adb.PollingBatchSize is used, this optimizes

on|off -max_rows
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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

Table 7 Additional Run-Time Adapter Properties File Parameters (Cont’d)

Description
Property (Cont’d) (Cont’d)
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 Corresponding TIBCO Designer selection

(no value) ASCII (default)

ibm-1370 Big5

tibx-eucJP EUC-JP

ibm-1386 GBK

LATIN_1 ISO8859-1

ibm-949 KSC-5601

ibm-943 Shift_JIS (CP943)

tibx-943 Shift_JIS (TIBCO)

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Adapter Properties File 119
|
Table 7 Additional Run-Time Adapter Properties File Parameters (Cont’d)

Description
Property (Cont’d) (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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

Table 7 Additional Run-Time Adapter Properties File Parameters (Cont’d)

Description
Property (Cont’d) (Cont’d)
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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Adapter Properties File 121
|
Table 7 Additional Run-Time Adapter Properties File Parameters (Cont’d)

Description
Property (Cont’d) (Cont’d)
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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

Table 7 Additional Run-Time Adapter Properties File Parameters (Cont’d)

Description
Property (Cont’d) (Cont’d)
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".

TIBCO Adapter for ActiveDatabase User’s Guide

 Adapter Properties File 123
|

Table 7 Additional Run-Time Adapter Properties File Parameters (Cont’d)

Description
Property (Cont’d) (Cont’d)
tibco.username User name and password used by the repository server to
access the project. The password can be obfuscated using
tibco.password
the instructions in Obfuscating or Encrypting a Password in
the Properties File on page 123.

-version Displays a banner with version information, then exits. This

option is for troubleshooting purposes only.

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

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.

If you don’t want to obfuscate the password, remove the # at the beginning of the
password.

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:

TIBCO Adapter for ActiveDatabase User’s Guide

 Adapter Properties File 125
|
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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

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 String

TIBCO 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:// or tibcr@ tibcr@

Project name myInst

Optional parameters :service=5456
(separated by : )
:urlFile=/tibco/props/fredsProps.txt

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

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.
HTTP or HTTPS https://
Host name host
Port (optional) :8443
Repository locator string /administrator/repo
Required character ?
urlFile (required only for HTTPS) urlFile=httpsProps.ini

Optional parameters (separated by & ) &myInst

The following fields are required for HTTP or HTTPS.

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

Field Description
HTTP or Use HTTP// or HTTPS// as appropriate.
HTTPS

Host name Name of the host.

Repository Location of the repository.

locator string

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Project Locator String 129
|

Remote HTTP and HTTPS clients support the following optional parameters.
Each parameter must be separated by the character &.

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

Parameter Description
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.

Local Project Locator String

Example 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

TIBCO Adapter for ActiveDatabase User’s Guide

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

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.
Optional localrepo@
Instance name (required) c:/tibco/repository/instances/myInst

Optional .dat
Optional parameters (separated by : ) :userName=deborah

Clients support the following optional parameters separated by colons:

Table 11 Optional parameters for local repository locator string.

Parameter Description
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.
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.

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Adapter

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

TIBCO Adapter for ActiveDatabase User’s Guide

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

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

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

TIBCO Adapter for ActiveDatabase User’s Guide

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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

DBMS_PIPE

commit_and_notify Alerter
TIBCO Adapter for
ActiveDatabase
Source Table
Publishing Table

TIBCO Messaging

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.

TIBCO Adapter for ActiveDatabase User’s Guide

136
| Chapter 7 Using an Alerter

Before Starting
Make 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 Syntax

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

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.

Oracle Alerter Example

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Setting Up and Starting the Alerter on Oracle 137
|

1. Set the following properties in the properties file as shown:

tibco.repourl tibcr@ADB_demo
adb.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/demo
SQL> 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;

TIBCO Adapter for ActiveDatabase User’s Guide

138
| Chapter 7 Using an 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 Starting
A 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 Setup
Before 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 -Ppassword
1> sp_dropextendedproc notify
2> go
1> sp_dropextendedproc notifytable
2> go
1> DBCC adbalerter_mssql(FREE)
2> go
DBCC execution completed. If DBCC printed error messages,
contact your system administrator.

TIBCO Adapter for ActiveDatabase User’s Guide

 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> go
1> 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_account
2> go
1> grant execute on notifytable to database_account
2> go
1> exit

Using the Alerter

When 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 -dactivedb
1> insert into ORDER_TABLE values(406,'walnut table',9899.89)
2> go
1> execute itaska.master.dbo.notify @agentname='agentone'
2> go
Notifying: 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

TIBCO Adapter for ActiveDatabase User’s Guide

140
| Chapter 7 Using an Alerter

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 Starting
A 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 Solaris

Before 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

You may need to shut down and restart your XP SERVER after copying the
shared library to the sybase/lib directory.

2. Ensure that the procedures are not already defined in the master database:
isql -Usa -Ppassword
1> sp_dropextendedproc notify
2> go
1> sp_dropextendedproc notifytable
2> go
1> sp_freedll "adbalerter_sybase"
2> go

TIBCO Adapter for ActiveDatabase User’s Guide

 Setting Up and Starting the Alerter on Sybase SQL Server 141
|

3. Add the procedures to the master database:

1> sp_addextendedproc 'notify','adbalerter_sybase.so'
2> go
1> sp_addextendedproc 'notifytable','adbalerter_sybase.so'
2> go

This example shows how to add procedures on Solaris.

4. Set access permissions for the database account used by the adapter:
1> grant execute on notify to database_account
2> go
1> grant execute on notifytable to database_account
2> go
1> exit

Alerter Setup on Microsoft Windows

Before 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

You may need to shutdown and restart your XP SERVER after copying
adbalerter_sybase.dll to the \Sybase\dll directory.

2. Ensure that the procedures are not already defined in the master database:
isql -Usa -Ppassword
1> sp_dropextendedproc notify
2> go
1> sp_dropextendedproc notifytable
2> go
1> sp_freedll "adbalerter_sybase"
2> go

3. Add the procedures to the master database:

1> sp_addextendedproc 'notify','adbalerter_mssql.dll'
2> go
1> sp_addextendedproc 'notifytable','adbalerter_mssql.dll'
2> go

4. Set access permissions for the database account used by the adapter:
1> grant execute on notify to database_account
2> go
1> grant execute on notifytable to database_account
2> go
1> exit

TIBCO Adapter for ActiveDatabase User’s Guide

142
| Chapter 7 Using an Alerter

Using the Alerter

When 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 -dactivedb
1> insert into ORDER_TABLE values(406,'walnut table',9899.89)
2> go
1> execute itaska.master.dbo.notify @agentname='agentone'
2> go
Notifying: 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.

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

TIBCO Adapter for ActiveDatabase User’s Guide

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

146
| Chapter 8 Using the Request-Response Service

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

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.

Requests are described in the following sections:

• TIBCO ActiveEnterprise or XML Message Request Format, page 147
• TIBCO Rendezvous Message Request Format, page 147

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Format

In 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 Format

This 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 data
rv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statement
rv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statement
rv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statement
. . .
}

TIBCO Adapter for ActiveDatabase User’s Guide

148
| Chapter 8 Using the Request-Response Service

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_variables
rv_Name = “maxrows”, rvmsg_Type = RVMSG_INT, rvmsg_Data =
Optional_max_number_of_rows_to_fetch
rv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_data
rv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_data
rv_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_right
rv_Name = "column", rvmsg_Type = RVMSG_STRING, rvmsg_Data =
in_format_table-name.column-name_whose_column_type_matches_this_bound_variable
rv_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_argument
name = “stmt” value =
{
name = “sql” value = “INSERT INTO order_table (order_id,
order_description, order_price) values (1, ‘Order 1’, 1.10)”
}
}

TIBCO Adapter for ActiveDatabase User’s Guide

 Request-Response Mode 149
|

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_argument
name = “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.

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’));

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]}}}

TIBCO Adapter for ActiveDatabase User’s Guide

150
| Chapter 8 Using the Request-Response Service

TIBCO ActiveEnterprise or XML Message Response Format

In 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 Format

If 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 = 0
rv_Name = “results” rvmsg_Type = RVMSG_RVMSG rvmsg_Data = Result
rv_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_columns
name = “row” type = RVMSG_RVMSG value = List_of_columns
name = “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

TIBCO Adapter for ActiveDatabase User’s Guide

 Request-Response Mode 151
|
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_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_number
rv_Name = “sql” rvmsg_Type = RVMSG_STRING rvmsg_Data = SQL_statement_that_caused_error
rv_Name = “error” rvmsg_Type = RVMSG_STRING rvmsg_Data = error_text
rv_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 error
1: noMem // Out of Memory
2: notInitialized // Object never initialized
3: typeConversion // Type conversion error
4: dbNotFound // Database not registered
5: serverError // Error reported by server
6: serverMessage // Message from server
7: vendorLib // Error in vendor's library
8: notConnected // Lost connection
9: endOfFetch // End of fetch
10: invalidUsage // invalid usage of object
11: columnNotFound // Column does not exist
12: invalidPosition // invalid positioning within
object,i.e.bounds err
13: notSupported // Unsupported feature
14: nullReference // Null reference parameter
15: notFound // Database Object not found
16: missing // Required piece of information is missing
17: noMultiReaders // This object cannot support multiple readers
18: noDeleter // This object cannot support deletions
19: noInserter // This object cannot support insertions
20: noUpdater // This object cannot support updates
21: noReader // This object cannot support readers
22: noIndex // This object cannot support indices
23: noDrop // This object cannot be dropped
24: wrongConnection // Incorrect connection was supplied
25: noPrivilege // This object cannot support privileges
26: noCursor // This object cannot support cursors
27: cantOpen // Unable to open
28: applicationError // For errors produced at the application
level
29: notReady // For future use

TIBCO Adapter for ActiveDatabase User’s Guide

152
| Chapter 8 Using the Request-Response Service

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_argument
name = “status” value = 0
name = “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

TIBCO Adapter for ActiveDatabase User’s Guide

 Request-Response Mode 153
|

The self-describing message produced by the adapter would have the following
structure:

{
name = “closure” value = optional_closure_argument
name = “status” value = 5
name = “sql” value = “SELECT * FROM ORDER_TABLE”
name = "error" value = "[INTERSOLV][ODBC SequeLink
driver][DB2/400]ORDER_TABLE in *LIBL type *FILE not found.
}

TIBCO Adapter for ActiveDatabase User’s Guide

154
| Chapter 8 Using the Request-Response Service

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 RPC Mode 155
|

Standard RPC Operation

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

TIBCO Adapter for ActiveDatabase User’s Guide

156
| Chapter 8 Using the Request-Response Service

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"/>
</assoc>
<assoc name="attribute">
<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"/>

TIBCO Adapter for ActiveDatabase User’s Guide

 RPC Mode 157
|
</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>
<assoc name="attribute">
<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"/>
</assoc>
<assoc name="attribute">
<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">

TIBCO Adapter for ActiveDatabase User’s Guide

158
| Chapter 8 Using the Request-Response Service

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

TIBCO Adapter for ActiveDatabase User’s Guide

 RPC Mode 159
|

Custom RPC Operation

When 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 Data Type or Description

Item Classname
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.

TIBCO Adapter for ActiveDatabase User’s Guide

160
| Chapter 8 Using the Request-Response Service

Table 14 REPLY Schema Description

Data Type or
Output Item Classname Description

OUTBINDS OUTPUT_BINDS The output parameters of the stored procedure

RESULTSET[1..n]/ OUTPUT_ROWS/ The result set(s) returned by the stored procedure,

RESULTSETS SQL_RESULTSET
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_ Contains the error description and the SQL statement
OPTION
if an error occurred.

CLOSURE Any Closure argument obtained from the request

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

162
| Chapter 8 Using the Request-Response Service

Implementing Client RPC Programs

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

164
| Chapter 8 Using the Request-Response Service

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 Configuration

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

166
| Chapter 8 Using the Request-Response Service

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.

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.

Load Balancing Across Configurations

To 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

Distributed Queue

Request Adapter 4

Request Adapter 3

Request Adapter 2

Adapter 1
(Scheduler)
Responses
Request

TIBCO Messaging

Application

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

168
| Chapter 8 Using the Request-Response Service

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 procedure
CREATE 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.

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

TIBCO Adapter for ActiveDatabase User’s Guide

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Publishing Table 171
|
Table 15 Publishing Table Additional Columns (Cont’d)

Column Name (Cont’d) Type Description (Cont’d)

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.

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 Table

An 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).

TIBCO Adapter for ActiveDatabase User’s Guide

172
| Chapter 9 Advanced Features

• 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 Example
The 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 table

CREATE TABLE ORDER_TABLE (
ORDER_ID NUMBER PRIMARY KEY,
ORDER_DESCRIPTION VARCHAR2(128),
ORDER_PRICE NUMBER(10,3)
);

-- Create the destination table

CREATE 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,

TIBCO Adapter for ActiveDatabase User’s Guide

 Publishing Table 173
|
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_SEQ

START WITH 1
INCREMENT BY 1
NOMAXVALUE
NOCYCLE
CACHE 10
/

CREATE OR REPLACE TRIGGER TRI_PUB_ORDER AFTER INSERT OR DELETE OR

UPDATE ON

ORDER_TABLE FOR EACH ROW DECLARE

updating_key_fields EXCEPTION;
BEGIN
IF INSERTING THEN
INSERT 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 THEN
IF UPDATING('ORDER_ID') THEN
RAISE updating_key_fields;
END IF;

TIBCO Adapter for ActiveDatabase User’s Guide

174
| Chapter 9 Advanced Features

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 THEN
INSERT 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;
EXCEPTION
WHEN updating_key_fields THEN
raise_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
)
/

-- *******************************************

TIBCO Adapter for ActiveDatabase User’s Guide

 Publishing Table 175
|
-- 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 Rows

You 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_TABLE
FOR EACH ROW WHEN (new.ORDER_PRICE >= 1.00)

TIBCO Adapter for ActiveDatabase User’s Guide

176
| Chapter 9 Advanced Features

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.

Column Name Type Description

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.

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

Column Name Type Description

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.

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

TIBCO Adapter for ActiveDatabase User’s Guide

178
| Chapter 9 Advanced Features

Using an Exception Table as a Source Table

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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 ^encoding^ 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 ^id^ "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 ^idx^ 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 ^idx^ 1
RVMSG_RVMSG 58 ^1^
{
RVMSG_STRING 8 ^class^ "S_KEYP3"

TIBCO Adapter for ActiveDatabase User’s Guide

180
| Chapter 9 Advanced Features

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);

TIBCO Adapter for ActiveDatabase User’s Guide

 Database Types 181
|

Database Types

The database data types listed in this section are supported.

Oracle
The following Oracle data types are supported:

• CHAR • TIMESTAMP
• DATE • RAW
• LONG • VARCHAR2
• LONG RAW • CLOB
• NUMBER • BLOB

The following ANSI data types in Oracle are supported:

• DOUBLE PRECISION • INTEGER

• FLOAT • SMALLINT
• INT • REAL

SQL Server
The following SQL Server data types are supported:

• BINARY • INT • SMALLINT

• BIT • MONEY • SMALLMONEY
• CHAR • NCHAR • TEXT (publish by
reference only)
• DATETIME • NTEXT
• TIMESTAMP
• DECIMAL • NUMERIC
• TINYINT
• FLOAT • NVARCHAR
• UNIQUEIDENTIFIER
• IMAGE (publish by • REAL • VARBINARY
reference only)
• SMALLDATETIME • VARCHAR

TIBCO Adapter for ActiveDatabase User’s Guide

182
| Chapter 9 Advanced Features

Sybase
The following Sybase 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 • SMALLMONEY
reference only)

DB2
The following DB2 AS400 data types are supported:

• CHARACTER • NUMERIC
• DECIMAL • REAL
• DOUBLE PRECISION • SMALLINT
• FLOAT • TIMESTAMP
• INTEGER • VARCHAR
• LONG VARGRAPHIC

TIBCO Adapter for ActiveDatabase User’s Guide

 Database Types 183
|

Mapping to Database Types

The 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

TIBCO
ODBC Type ActiveEnterprise TIBCO Rendezvous
Message Type
Type
SQL_CHAR string RVMSG_STRING
SQL_VARCHAR
SQL_LONGVARCHAR

SQL_SMALLINT i4 RVMSG_INT
SQL_INTEGER

SQL_REAL r8 RVMSG_REAL
SQL_DOUBLE
SQL_FLOAT
SQL_DECIMAL
SQL_NUMERIC

SQL_BINARY binary RVMSG_OPAQUE

SQL_VARBINARY
SQL_LONGVARBINARY

SQL_TIMESTAMP dateTime RVMSG_DATETIME

TIBCO Adapter for ActiveDatabase User’s Guide

184
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Subject Names 185
|

Parameterized Subject Names

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

TIBCO Adapter for ActiveDatabase User’s Guide

186
| Chapter 9 Advanced Features

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.

Wildcard TIBCO Rendezvous subject names are not supported for preregistered
listeners.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

188
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

190
| Chapter 9 Advanced Features

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

Do not change any adbDateTime object information in this screen. Use this
information to determine how to format the third-party subscriber date value.

To view the structure of the adbDateTime class:

1. In the project tree panel, navigate to
AESchemas>ae>ADB>adbmetadata>Classes>adbDateTime>dateTime

TIBCO Adapter for ActiveDatabase User’s Guide

 Sending Messages to an Adapter Instance 191
|

The TIBCO Designer window should look similar to the following:

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-dd
yyyy-mm-dd hh:mm:ss.xxx

where xxx represents the millisecond value.

TIBCO Adapter for ActiveDatabase User’s Guide

192
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Relationships

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

TIBCO Adapter for ActiveDatabase User’s Guide

194
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Publishing by Reference Object 195
|

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.

TIBCO Adapter for ActiveDatabase User’s Guide

196
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Publishing by Reference Object 197
|

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.

TIBCO Adapter for ActiveDatabase User’s Guide

198
| Chapter 9 Advanced Features

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.

Example
In 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

TIBCO Adapter for ActiveDatabase User’s Guide

 Publishing by Reference Object 199
|

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.

TIBCO Adapter for ActiveDatabase User’s Guide

200
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 User Callout Library 201
|

Using the alterMsgPub and alterMsgSub Functions

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

TIBCO Adapter for ActiveDatabase User’s Guide

202
| Chapter 9 Advanced Features

Table 17 Wire Format Parameters and Descriptions (Cont’d)

Parameter R M Description
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.

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 Function

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

Table 18 adbPreCommit Parameter Descriptions

TIBCO TIBCO
Parameter Rendezvous ActiveEnterprise Description
Format Format
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.

TIBCO Adapter for ActiveDatabase User’s Guide

 User Callout Library 203
|

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.

Building the Callout Library

This section explains how to build the callout library on each supported platform.
The next table lists required compilers for each platform.

Table 19 Compilers for Platforms

Platform Compiler
Microsoft MSVC++ 6.0 with Service Pack 5, 7.0 or 7.1 (.NET)
Windows

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

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

TIBCO Adapter for ActiveDatabase User’s Guide

204
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 User Callout Library 205
|

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=-g
OPT=-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.

TIBCO Adapter for ActiveDatabase User’s Guide

206
| Chapter 9 Advanced Features

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)

TIBCO Adapter for ActiveDatabase User’s Guide

 Publishing in a Commitment Controlled Environment 207
|

Publishing in a Commitment Controlled Environment

This feature applies only to DB2 on AS/400.

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 UsrOpn
F 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.

TIBCO Adapter for ActiveDatabase User’s Guide

208
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.aeschema
Project_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.

TIBCO Adapter for ActiveDatabase User’s Guide

210
| Chapter 9 Advanced Features

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

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.

Fine-Tuning Tracing Attributes

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

TIBCO Adapter for ActiveDatabase User’s Guide

212
| Chapter 9 Advanced Features

The TIBCO Designer window should look similar to the following:

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Using a Log File for an Adapter Instance 213
|

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 Size

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

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.

Using Advanced Logging Features

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

TIBCO Adapter for ActiveDatabase User’s Guide

214
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Using a Log File for an Adapter Instance 215
|

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.

TIBCO Adapter for ActiveDatabase User’s Guide

216
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

218
| Chapter 9 Advanced Features

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

• Overview, page 220

• Setting TIBCO Messaging Encoding, page 222
• Configuring the Adapter to Communicate with the Database, page 224
• Relevant Environment Settings, page 229

TIBCO Adapter for ActiveDatabase User’s Guide

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

Oracle DB Oracle DB in
in Shift-JIS EUC-JP

Driver Manager/ODBC Driver/Database Client

Shift-JIS EUC-JP

ActiveDatabase ActiveDatabase
Publishing Service Subscription Service

UTF-8 UTF-8

TIBCO Messaging

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.

TIBCO Adapter for ActiveDatabase User’s Guide

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

222
| Chapter 10 Setting Encoding Options

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.

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

224
| Chapter 10 Setting Encoding Options

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

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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/odbcre
f.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)

TIBCO Adapter for ActiveDatabase User’s Guide

226
| Chapter 10 Setting Encoding Options

Table 20 IANAAppCodePage

Value Encoding (Language)

18 EUC_JP (Japanese)

38 EUC_KR (Korean)

113 GBK (Simplified Chinese)

2026 BIG5 (Traditional Chinese)

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Configuring the Adapter to Communicate with the Database 227
|

database has been converted to local system encoding by the database

client.

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.

Special Configurations for Supporting a UTF-8 Database

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

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.

TIBCO Adapter for ActiveDatabase User’s Guide

228
| Chapter 10 Setting Encoding Options

Run-time Environment Variables

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Oracle NLS_LANG (containing Description

Adapter Encoding NLS_CHARACTERSET)
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 Traditional Chinese Big5 with Euro

CHINESE_TAIWAN.ZHT16BIG5

GBK SIMPLIFIED CHINESE_CHINA. Simplified Chinese GBK (superset

ZHS16CGB231280 of GB2312-80)

EUC-JP JAPANESE_JAPAN.JA16EUC Japanese EUC

UTF8 AMERICAN_AMERICA.UTF8 Unicode Transformation Format-8

TIBCO Adapter for ActiveDatabase User’s Guide

230
| Chapter 10 Setting Encoding Options

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

• Overview, page 232

• Starting TIBCO Hawk Software, page 233
• The Auto-Discovery Process, page 234
• Invoking Microagent Methods, page 235
• Available Microagents, page 238

TIBCO Adapter for ActiveDatabase User’s Guide

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

234
| Chapter 11 Monitoring the Adapter

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.

TIBCO Adapter for ActiveDatabase User’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.

TIBCO Adapter for ActiveDatabase User’s Guide

236
| Chapter 11 Monitoring the Adapter

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

238
| Chapter 11 Monitoring the Adapter

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 242
runtime.

deactivateTraceRole() Deactivates a mapping of a roles to sinks 243

at runtime.

getAdapterServiceInfo Returns information about the services 244

rmation()
implemented by this adapter.

getComponents() Returns information about the publisher, 245

subscriber and IODescriptor.

TIBCO Adapter for ActiveDatabase User’s Guide

 Available Microagents 239
|
Table 22 Standard Microagent Methods (Cont’d)

Standard Method Description (Cont’d) Page

getConfig() Returns basic configuration information. 246
More specific information is accessed by
the more specific methods.

getConfigProperties() Returns a list of publishers and 247

subscribers.

getHostInformation() Returns standard and extended 248

application information.

getRvConfig() Returns information about all TIBCO 249

Rendezvous sessions defined.

getStatus() Returns general status information, such 250

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.

getTraceSinks() Returns information about sinks to 251

which traces currently go.

getVersion() Returns the configuration ID, application 252

name, version, and date for this adapter
instance.

_onUnsolictedMsg() Displays alert messages sent to the 253

current adapter.

preRegisterListener() Preregisters an anticipated listener. 254

reviewLedger() Returns information retrieved from the 255

ledger file of a certified messaging
session for a publisher adapter.

setTraceSinks() Adds a role or changes the file limit of a 256

previously specified sink.

stopApplicationInstan Stops the running adapter instance. 257

ce()

unRegisterListener() Unregisters a currently preregistered 258

listener.

TIBCO Adapter for ActiveDatabase User’s Guide

240
| Chapter 11 Monitoring the Adapter

Table 23 Custom Microagent Methods

Custom Method Description Page
getEventQueueSize() Retrieves the size of the TIBCO 259
Rendezvous event queue for the
specified adapter instance.

setDebugLevel() Sets the debug level for the current 260

adapter instance.

toggleVerboseFlag() Changes the value of the verbose flag 261

from on to off, or the reverse.

showConfiguration() Shows the configuration defined for the 262

current agent.

terminateADBagent() Stops the current TIBCO Adapter for 263

ActiveDatabase agent.

getPollingInterval() Returns the current polling interval 264

setting.

setPollingInterval() Set the polling interval for the 265

publication service.

getPollingBatchSize() Get the polling batch size for the 266

publication service.

setPollingBatchSize() Set the polling batch size for the 267

publication service.

Table 24 Custom Microagent Methods with adb.perfMon

Custom Method Description Page

getActivityStatistics() Returns the total number of objects 268
processed for all the schemas, based on
the request type. Also, returns the
number of success and error objects.

TIBCO Adapter for ActiveDatabase User’s Guide

 Available Microagents 241
|
Table 24 Custom Microagent Methods with adb.perfMon (Cont’d)

Custom Method (Cont’d) Description (Cont’d) Page

getActivityStatisticsBySer Returns the total number of objects 269
vice processed for each of the schemas
associated with the specified service.

getActivityStatisticsByOp Returns the total number of objects 270

eration() processed for all the schemas by each
service that is associated with a specified
operation.

getThreadStatistics() Return the operation counts of the 271

current threads.

getQueueStatistics() Return the current count of elements in 272

any internal queue used by the adapter.

getConnectionStatistics() Returns the state and statistics for all the 273
current connections used by the adapter.

resetActivityStatistics() Resets all the counts for the activity 274

statistics.

resetThreadStatistics() Resets all the counts for the thread 275

statistics.

resetQueueStatistics() Resets all the counts for the queue 276

statistics.

resetConnectionStatistics() Resets all the counts for the connection 277

statistics.

TIBCO Adapter for ActiveDatabase User’s Guide

242
| Chapter 11 Monitoring the Adapter

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

244
| Chapter 11 Monitoring the Adapter

getAdapterServiceInformation()

Purpose (Standard) Returns information about the services implemented by this adapter.
The information is a summary of available adapter services.

Parameters Parameter Type Description

serviceName string Name of the service from which to get
information. Default is ALL.

Returns 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 string Quality of service for the endpoint, for example,

Service 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 Integer Number of messages processed for this endpoint.

Messages

TIBCO Adapter for ActiveDatabase User’s Guide

 getComponents() 245
|

getComponents()

Purpose (Standard) Returns information about the currently active TIBCO Hawk
components such as publishers, subscribers, or timers.

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

Returns Returns Type Description

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.

TIBCO Adapter for ActiveDatabase User’s Guide

246
| Chapter 11 Monitoring the Adapter

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.

Adapter Name string Name of the adapter.

Repository string URL of the repository used for adapter instance.

Connection

Configuration string Location of the adapter project; either a file name

URL or configuration URL.

Command string Command line arguments used to start the

adapter.

TIBCO Adapter for ActiveDatabase User’s Guide

 getConfigProperties() 247
|

getConfigProperties()

Purpose (Standard) Returns all attributes and elements for the given repository object.

Parameters Parameter Type Description

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.

Returns Returns Type Description

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.

TIBCO Adapter for ActiveDatabase User’s Guide

248
| Chapter 11 Monitoring the Adapter

getHostInformation()

Purpose (Standard) Returns standard and extended application information.

Returns Returns Type Description

Name string Name of the property.

Value string Value of the property.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Parameter Type Description

Session Name string Name of the TIBCO Rendezvous session for
which configuration is required (default is all).

Returns Returns Type Description

Instance ID string The configuration ID of this adapter.

Adapter Name string Name of the 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.

TIBCO Adapter for ActiveDatabase User’s Guide

250
| Chapter 11 Monitoring the Adapter

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.

Returns Returns Type Description

Instance ID string Configuration ID for this adapter instance.

Adapter Name string Name of the adapter.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 getTraceSinks() 251
|

getTraceSinks()

Purpose (Standard) Returns information about sinks to which traces currently go.

Parameters Parameters Type Description

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.

Returns Returns Type Description

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

TIBCO Adapter for ActiveDatabase User’s Guide

252
| Chapter 11 Monitoring the Adapter

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 _onUnsolictedMsg() 253
|

_onUnsolictedMsg()

Purpose (Standard) Displays all alert messages sent from the adapter or an error if not
successful.

TIBCO Adapter for ActiveDatabase User’s Guide

254
| Chapter 11 Monitoring the Adapter

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 Parameters Type Description

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 string Name of the listener to preregister.

Name

Returns OK if the listener was preregistered successfully, false otherwise.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Parameters Type Description

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.

Returns

Returns Type Description

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.

Listener Session string Within each listener submessage, the Listener Session Name field
Name 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.

Unacknowledged integer Number of RVCM messages pending for this listener. The value is
Messages computed by subtracting the last sent sequence number from the
last acknowledged sequence number.

TIBCO Adapter for ActiveDatabase User’s Guide

256
| Chapter 11 Monitoring the Adapter

setTraceSinks()

Purpose (Standard) Adds a role or changes the file limit of a previously specified sink.

Parameters Parameters Type Description

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.

Returns OK if successful or an error if not successful.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

258
| Chapter 11 Monitoring the Adapter

unRegisterListener()

Purpose (Standard) Unregisters a currently preregistered listener.

Parameters Parameters Type Description

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 string Name of the listener to unregister.

Name

Returns True if the listener was successfully unregistered, false otherwise.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Parameter Type Description

Session string Type of listener for this adapter instance. Possible
values are Subscriber or Request/Reply. The
default value is Subscriber.

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

TIBCO Adapter for ActiveDatabase User’s Guide

260
| Chapter 11 Monitoring the Adapter

setDebugLevel()

Purpose (Custom) Sets the debug level for the current adapter instance.

Parameters Parameter Type Description

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.

Returns Returns OK if successful or an error if not successful.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

262
| Chapter 11 Monitoring the Adapter

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

264
| Chapter 11 Monitoring the Adapter

getPollingInterval()

Purpose (Custom) Returns the current polling interval setting.

Returns Returns Type Description

PollingInterval integer Polling interval in milliseconds.

TIBCO Adapter for ActiveDatabase User’s Guide

 setPollingInterval() 265
|

setPollingInterval()

Purpose (Custom) Set the polling interval for the publication service.

Parameters Parameter Type Description

PollingInterval integer Polling interval in milliseconds.

ServiceName string (Optional) Name of service where the polling

interval is set.

TIBCO Adapter for ActiveDatabase User’s Guide

266
| Chapter 11 Monitoring the Adapter

getPollingBatchSize()

Purpose (Custom) Get the polling batch size for the publication service.

Returns Returns Type Description

BatchSize integer The batch size for the publication service.

TIBCO Adapter for ActiveDatabase User’s Guide

 setPollingBatchSize() 267
|

setPollingBatchSize()

Purpose (Custom) Set the polling batch size for the publication service.

Parameters Parameter Type Description

BatchSize integer The new batch size for the publication service.

TIBCO Adapter for ActiveDatabase User’s Guide

268
| Chapter 11 Monitoring the Adapter

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 Parameter Type Description

Get Subtotal By integer Statistics categorized by service or by operation.

Returns Returns Type Description

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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 Parameter Type Description

Service Name string Name of the service.

Returns Returns Type Description

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

270
| Chapter 11 Monitoring the Adapter

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 Parameter Type Description

Operation string Name of operation. Pick from list.

Returns Returns Type Description

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.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 getThreadStatistics() 271
|

getThreadStatistics()

Purpose (Custom with adb.perfMon) Return the operation counts of the current threads.

Returns Returns Type Description

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.

TIBCO Adapter for ActiveDatabase User’s Guide

272
| Chapter 11 Monitoring the Adapter

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.

Returns Returns Type Description

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 getConnectionStatistics() 273
|

getConnectionStatistics()

Purpose (Custom with adb.perfMon) Returns the state and statistics for all the current
connections used by the adapter.

Returns Returns Type Description

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.

TotalNumOperat integer Total number of operations processed by this

ions connection since the adapter started.

CurrentNumOpe integer Total number of operations processed by this

rations connection since the last reconnection.

TIBCO Adapter for ActiveDatabase User’s Guide

274
| Chapter 11 Monitoring the Adapter

resetActivityStatistics()

Purpose (Custom with adb.perfMon) Resets all the counts for the activity statistics.

TIBCO Adapter for ActiveDatabase User’s Guide

 resetThreadStatistics() 275
|

resetThreadStatistics()

Purpose (Custom with adb.perfMon) Resets all the counts for the thread statistics.

TIBCO Adapter for ActiveDatabase User’s Guide

276
| Chapter 11 Monitoring the Adapter

resetQueueStatistics()

Purpose (Custom with adb.perfMon) Resets all the counts for the queue statistics.

TIBCO Adapter for ActiveDatabase User’s Guide

 resetConnectionStatistics() 277
|

resetConnectionStatistics()

Purpose (Custom with adb.perfMon) Resets all the counts for the connection statistics.

TIBCO Adapter for ActiveDatabase User’s Guide

278
| Chapter 11 Monitoring the Adapter

TIBCO Adapter for ActiveDatabase User’s Guide

 | 279

Appendix A Frequently Asked Questions

This appendix lists answers to frequently asked questions.

Topics

• General Questions, page 280

• Request-Response Questions, page 285

TIBCO Adapter for ActiveDatabase User’s Guide

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

282
| Appendix A Frequently Asked Questions

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

284
| Appendix A Frequently Asked Questions

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

TIBCO Adapter for ActiveDatabase User’s Guide

 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.

TIBCO Adapter for ActiveDatabase User’s Guide

286
| Appendix A Frequently Asked Questions

TIBCO Adapter for ActiveDatabase User’s Guide

 | 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

• Overview, page 288

• Status Messages, page 297

TIBCO Adapter for ActiveDatabase User’s Guide

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.
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: 2003 Feb 22 20:15:12:937 GMT -8

Adapter ID: FileAdapter.FileAdapterConfiguration
Role: Info
Category: [Adapter]
Status Code: AEFA-000067 Message containing class
/tibco/public/class/ae/Customer
received on subject FROM.SAP

Tracking ID: tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

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: The following message indicates that TIBCO Adapter for Files has started. The
Adapter Started 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

TIBCO Adapter for ActiveDatabase User’s Guide

 Overview 289
|
Example 2: The next set of trace messages indicates the adapter received an object that was
Message sent on the TIBCO Rendezvous subject, FROM.SAP. The
Received #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: The final trace message indicates the object has been moved to the output
Object Moved 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 Fields

Each 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 Name of the adapter that wrote the trace message. This is a combination of the
Identifier adapter acronym and adapter configuration name. For example, the
application identifier, ADB.publisher1 identifies a TIBCO Adapter for
ActiveDatabase service named publisher1.

TIBCO Adapter for ActiveDatabase User’s Guide

290
| Appendix B Trace Messages

Table 25 Trace Message Fields (Cont’d)

Field Name Description (Cont’d)

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Overview 291
|
Table 25 Trace Message Fields (Cont’d)

Field Name Description (Cont’d)

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.

TIBCO Adapter for ActiveDatabase User’s Guide

292
| Appendix B Trace Messages

Table 25 Trace Message Fields (Cont’d)

Field Name Description (Cont’d)

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Overview 293
|
Table 25 Trace Message Fields (Cont’d)

Field Name Description (Cont’d)

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.

TIBCO Adapter for ActiveDatabase User’s Guide

294
| Appendix B Trace Messages

Table 25 Trace Message Fields (Cont’d)

Field Name Description (Cont’d)

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Overview 295
|
Table 25 Trace Message Fields (Cont’d)

Field Name Description (Cont’d)

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.

TIBCO Adapter for ActiveDatabase User’s Guide

296
| Appendix B Trace Messages

Table 25 Trace Message Fields (Cont’d)

Field Name Description (Cont’d)

Tracking A unique identifier that is "stamped" on each message by the originating
Identifier 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 Application-specific information added to the tracking info to trace the

Information message back to its source. Set initially by the originating adapter and carried
forward. It is augmented by each intermediate component.

TIBCO Adapter for ActiveDatabase User’s Guide

 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

infoRole Database Normal operation; no action is necessary.

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.

infoRole Database Normal operation; no action is necessary.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

298
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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

infoRole Database Normal operation; no action is necessary.

AEADB-100011 %1Database connection closed

infoRole Database Normal operation; no action is necessary.

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

infoRole Database Normal operation; no action is necessary.

AEADB-100014 Inserted %1into database

infoRole Adapter Normal operation; no action is necessary.

AEADB-100015 Deleted from database

infoRole Adapter Normal operation; no action is necessary.

AEADB-100016 No rows deleted

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 299
|

Status Code Role Category Resolution (Cont’d)

AEADB-100017 Updated database

infoRole Adapter Normal operation; no action is necessary.

AEADB-100018 No rows updated

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

300
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 301
|

Status Code Role Category Resolution (Cont’d)

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.

TIBCO Adapter for ActiveDatabase User’s Guide

302
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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

errorRole System A TCP system call failed. Check your

computer’s network ports and TCP libraries.
Rebooting the computer may solve the problem.

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

errorRole System A TCP system call failed. Check your

computer’s network ports and TCP libraries.
Rebooting the computer may solve the problem.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 303
|

Status Code Role Category Resolution (Cont’d)

AEADB-300008 Socket creation 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-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.

TIBCO Adapter for ActiveDatabase User’s Guide

304
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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

infoRole Adapter Normal operation; no action is necessary.

AEADB-700002 %1Building SQL statement succeeded%2.

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 305
|

Status Code Role Category Resolution (Cont’d)

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

infoRole Adapter Normal operation; no action is necessary.

AEADB-700007 %1database transaction commit

infoRole Adapter Normal operation; no action is necessary.

AEADB-700008 %1database transaction rollback.

infoRole Adapter Normal operation; no action is necessary.

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.

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

306
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

AEADB-700013 %1Cold start failed.

errorRole Adapter Run the adapter using debug 3 and verbose

mode.

AEADB-700014 %1Confirming message.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700015 %1 batch commit timeout.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700016 %1Bulk insert begins.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700017 %1Bulk insert ends.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700018 Inserted %1into the corresponding exception table.

infoRole Adapter Normal operation; no action is necessary.

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.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700021 %1 = %2

debugRole Adapter

AEADB-700022 %1 = NULL

debugRole Adapter

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 307
|

Status Code Role Category Resolution (Cont’d)

AEADB-700023 %1Bulk insert turning off.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700024 Polling publishing table %1

infoRole Adapter Normal operation; no action is necessary.

AEADB-700025 Updating delivery status of publishing table %1.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700026 %1 = %2

debugRole Adapter

AEADB-700027 %1Publishing by reference and selecting from reference object %2

infoRole Adapter Normal operation; no action is necessary.

AEADB-700029 %1

infoRole Adapter Normal operation; no action is necessary.

AEADB-700030 Received request %1.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700031 Built reply %1.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700032 %1sent to %2

infoRole Adapter Normal operation; no action is necessary.

AEADB-700033 %1

infoRole Adapter Normal operation; no action is necessary.

AEADB-700034 Bad date encountered: %1

errorRole Adapter Check your dateTime-related message data and

make sure it is in the correct format.

TIBCO Adapter for ActiveDatabase User’s Guide

308
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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

infoRole Adapter Normal operation; no action is necessary.

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)

infoRole Adapter Normal operation; no action is necessary.

AEADB-700045 %1endpoints %2

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 309
|

Status Code Role Category Resolution (Cont’d)

AEADB-700046 Confirming request

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

310
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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)

infoRole Adapter Normal operation; no action is necessary.

AEADB-700059 Starting thread (name: %1, id: %2)

infoRole Adapter Normal operation; no action is necessary.

AEADB-700063 %1starts

infoRole Adapter Normal operation; no action is necessary.

AEADB-700064 %1Request: %2

debugRole Adapter

AEADB-700065 %1Reply: %2

debugRole Adapter

AEADB-700066 Load catalog table %1

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 311
|

Status Code Role Category Resolution (Cont’d)

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:

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

312
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

AEADB-700078 Received message discarded by alterMsgSub()

infoRole Adapter Normal operation; no action is necessary.

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.

infoRole Adapter Normal operation; no action is necessary.

AEADB-700081 Batch confirming %1 messages

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

AEADB-700086 Publisher batch confirm timeout

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 313
|

Status Code Role Category Resolution (Cont’d)

AEADB-700087 %1 method invoked

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

AEADB-700093 Binding data to insert placeholders

infoRole Adapter Normal operation; no action is necessary.

AEADB-700094 Polling for database change

infoRole Adapter Normal operation; no action is necessary.

AEADB-700095 Terminating agent

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

314
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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:

infoRole Adapter Normal operation; no action is necessary.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 315
|

Status Code Role Category Resolution (Cont’d)

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

infoRole Adapter Normal operation; no action is necessary.

AEADB-700107 New SQL: %1

infoRole Adapter Normal operation; no action is necessary.

AEADB-700108 Bulk insert of %1 rows executed for %2

infoRole Adapter Normal operation; no action is necessary.

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

infoRole Adapter Normal operation; no action is necessary.

TIBCO Adapter for ActiveDatabase User’s Guide

316
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

AEADB-700111 Reassign data value to insert statement:

infoRole Adapter Normal operation; no action is necessary.

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 317
|

Status Code Role Category Resolution (Cont’d)

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.

AEADB-910005 AEADB-STARTUP-5

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.

AEADB-910007 AEADB-STARTUP-7

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.

TIBCO Adapter for ActiveDatabase User’s Guide

318
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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.

AEADB-920002 AEADB-SUB-2

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.

AEADB-920006 AEADB-SUB-6

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.

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 319
|

Status Code Role Category Resolution (Cont’d)

AEADB-920007 AEADB-SUB-7

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.

AEADB-920015 AEADB-SUB-15

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.

AEADB-920017 AEADB-SUB-17

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.

TIBCO Adapter for ActiveDatabase User’s Guide

320
| Appendix B Trace Messages

Status Code Role Category Resolution (Cont’d)

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_Resp Request-Response error. Request-Response

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

AEADB-940009 AEADB-REQRESP-9

errorRole Request_Resp Request-Response error. Request-Response

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Status Messages 321
|

Status Code Role Category Resolution (Cont’d)

AEADB-940010 AEADB-REQRESP-10

errorRole Request_Resp Request-Response error. Request-Response

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

AEADB-940012 AEADB-REQRESP-12

errorRole Request_Resp Request-Response error. Request-Response

onse_Server 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 Adapter for ActiveDatabase User’s Guide

322
| Appendix B Trace Messages

TIBCO Adapter for ActiveDatabase User’s Guide

 TIBCO Software Inc. End User License Agreement 323
|

TIBCO Software Inc. End User License Agreement

READ THIS END USER LICENSE AGREEMENT CAREFULLY. BY resolution during TIBCO's published support hours corresponding to
DOWNLOADING OR INSTALLING THE SOFTWARE, YOU AGREE the level of Support fees paid.
TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE TO
THESE TERMS, DO NOT DOWNLOAD OR INSTALL THE Upon notice from a contact of a Software problem which can be
SOFTWARE AND RETURN IT TO THE VENDOR FROM WHICH IT reproduced at a TIBCO support facility or via remote access to
WAS PURCHASED. RETURNS BY THE ORIGINAL PURCHASER Customer's facility, TIBCO shall use reasonable efforts to correct or
WITHIN THIRTY (30) DAYS OF THE PURCHASE DATE WILL circumvent the problem according to its published support objectives.
RECEIVE A FULL REFUND. TIBCO reserves the right to make changes only to the most currently
available version. TIBCO will use reasonable efforts to support the
Upon your acceptance as indicated above, the following shall govern previously released version of the Software for a maximum of six
your use of the Software except to the extent all or any portion of the months.
Software (a) is subject to a separate written agreement, (b) includes a
separate "click-on" license agreement as part of the download or TIBCO shall have no obligation to support the Software (i) for use on
installation process, or (c) is provided by a third party under the terms any computer system running other than the operating system
set forth in an Addenda at the end of this Agreement, in which case software for which the Software is approved (as set forth in the
the terms of such addenda shall control over inconsistent terms with Software documentation) and licensed hereunder, or (ii) if Customer
regard to such portion(s). has modified or authorized a third party to modify the Software.
TIBCO shall have no obligation to modify any version of the Software
License Grant. The Software is the property of TIBCO or its licensors to run with any new versions of any operating system, or any other
and is protected by copyright and other laws. While TIBCO continues third party software or hardware. If Customer purchases Support for
to own the Software, TIBCO hereby grants to Customer a limited, any Software, Customer must purchase the same level of Support for
non-transferable, non-exclusive, license to use the number of all copies of the Software for which it is licensed.
Permitted Instances set forth in the Ordering Document, in
machine-readable, object code form and solely for Customer's internal Support may be extended for one-year periods on the anniversary of
business use. each Purchase Date at the standard amounts set forth in its price list,
for as long as TIBCO offers Support. Customer may reinstate lapsed
Restrictions. Customer agrees not to (a) make more copies than the support for any then currently supported Software by paying all
number of Permitted Instances plus a reasonable number of backups; Support fees in arrears and any applicable reinstatement fee.
(b) provide access to the Software to anyone other than employees, Upgrades, patches, enhancements, bug fixes, new versions and/or
contractors, or consultants of Customer; (c) sublicense, transfer, new releases of the Software provided from time to time under
assign, distribute to any third party, pledge, lease, rent, or Support shall be used only as replacements to existing Permitted
commercially share the Software or any of Customer's rights under Instances, and shall not be deemed to increase that number, and use
this Agreement (for the purposes of the foregoing a change in control thereof shall be governed by the terms of this Agreement, except for
of Licensee is deemed to be an assignment); (d) use the Software for the first paragraph of the Limited Warranty and any right of return or
purposes of providing a service bureau, including, without limitation, refund.
providing third-party hosting, or third-party application integration or
application service provider-type services, or any similar services; (e) Consulting Services. Customer may request additional services
use the Software in connection with ultrahazardous activities, or any ("Services") either in an Ordering Document, or by a separate
activity for which failure of the Software might result in death or mutually executed work order, statement of work or other
serious bodily injury to Customer or a third party; or (f) directly or work-request document incorporating this Agreement (each, a "Work
indirectly, in whole or in part, modify, translate, reverse engineer, Order"). Unless otherwise expressly agreed to in a Work Order, all
decrypt, decompile, disassemble, make error corrections to, create Services and any work product therefrom shall be (a) performed on a
derivative works based on, or otherwise attempt to discover the time and materials basis, plus meals, lodging, travel, and other
source code or underlying ideas or algorithms of the Software. expenses reasonably incurred in connection therewith, (b) deemed
accepted upon delivery, and (c) exclusively owned by TIBCO (except
Beta and Evaluation Licenses. Notwithstanding the foregoing, if the for confidential information of Customer identified to TIBCO in the
Software is being provided for demonstration, beta testing, or Ordering Document), including all right, title and intellectual property
evaluation purposes, then Customer agrees (a) to use the Software or other right or interest therein. Each Work Order is intended to
solely for such purposes, (b) that the Software will not be used or constitute an independent and distinct agreement of the parties,
deployed in a production environment, and (c) that such use shall notwithstanding that each shall be construed to incorporate all
automatically terminate upon the earlier of thirty days from the date applicable provisions of this Agreement. Specific to TIBCO training
Customer receives the right to install the Software, or Customer's services, additional information regarding courses, registration,
receipt of notice of termination from TIBCO. restrictions or limitation can be found at TIBCO's website at
http://www.tibco.com/services/education under Education Programs.
Technical Support. Provided Customer has paid applicable support Fees for Services shall be due and payable in United States dollars
fees (not included with Software fees unless separately listed), TIBCO net 30 from the date of TIBCO's invoice.
shall provide support for generally available TIBCO Software on an
annual basis commencing on the Purchase Date, as follows Limited Warranty. If Customer obtained the Software directly from
("Support"): Customer shall designate at TIBCO's support website TIBCO, then TIBCO warrants that for a period of thirty (30) days from
https://support.tibco.com/eSupport/newuser.html, the number of the Purchase Date: (i) the media on which the Software is furnished
technical support contacts permitted under the level of Support will be free of defects in materials and workmanship under normal
purchased (contacts are changeable upon 48-hours prior written use; and (ii) the Software will substantially conform to its published
notice to TIBCO). Each contact may contact TIBCO for problem specifications. This limited warranty extends only to the original
Customer hereunder. Customer's sole and exclusive remedy and the

TIBCO Adapter for ActiveDatabase User’s Guide

324
| TIBCO Software Inc. End User License Agreement
entire liability of TIBCO and its suppliers under this limited warranty Limitation of Liability. EXCEPT AS PROVIDED UNDER
will be, at TIBCO's option, repair, replacement, or refund of the INDEMNITY OR RESULTING FROM A BREACH OF
Software and applicable Support fees, in which event this Agreement CONFIDENTIALITY (THE "EXCLUDED MATTERS"), IN NO EVENT
shall terminate upon payment thereof. WILL EITHER PARTY BE LIABLE FOR ANY LOST DATA, LOST
REVENUE, LOST PROFITS, DAMAGE TO REPUTATION,
This warranty does not apply to any Software which (a) is licensed for BUSINESS INTERRUPTION, OR ANY OTHER INDIRECT,
beta, evaluation, testing or demonstration purposes for which TIBCO INCIDENTAL, CONSEQUENTIAL, SPECIAL, PUNITIVE,
does not receive a license fee, (b) has been altered or modified, EXEMPLARY OR ANY SIMILAR TYPE DAMAGES ARISING OUT OF
except by TIBCO, (c) has not been installed, operated, repaired, or THIS AGREEMENT, THE USE OR THE INABILITY TO USE THE
maintained in accordance with instructions supplied by TIBCO, (d) has SOFTWARE, OR THE PROVISION OF ANY SUPPORT OR
been subjected to abnormal physical or electrical stress, misuse, SERVICES, EVEN IF A PARTY HAS BEEN ADVISED OF THE
negligence, or accident, or (e) is used in violation of any other term of POSSIBILITY OF SUCH DAMAGES. EXCEPT FOR THE EXCLUDED
this Agreement. Customer agrees to pay TIBCO for any Support or MATTERS, IN NO EVENT SHALL A PARTY BE LIABLE TO THE
Services provided by TIBCO related to a breach of the foregoing on a OTHER, WHETHER IN CONTRACT, TORT (INCLUDING ACTIVE
time, materials, travel, lodging and other reasonable expenses basis. OR PASSIVE NEGLIGENCE), BREACH OF WARRANTY, CLAIMS
If Customer obtained the Software from a TIBCO reseller or BY THIRD PARTIES OR OTHERWISE, EXCEED THE PRICE PAID
distributor, the terms of any warranty shall be as provided by such BY CUSTOMER UNDER THE APPLICABLE ORDERING
reseller or distributor, and TIBCO provides Customer no warranty with DOCUMENT.
respect to such Software.
THE FOREGOING LIMITATIONS SHALL APPLY EVEN IF THE
EXCEPT AS SPECIFIED IN THIS LIMITED WARRANTY, THE ABOVE-STATED REMEDY OR LIMITED WARRANTY FAILS OF ITS
SOFTWARE, SUPPORT AND SERVICES ARE PROVIDED "AS IS", ESSENTIAL PURPOSE. BECAUSE SOME STATES OR
ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS, JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION OF
AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE
IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, LIMITATION MAY NOT APPLY TO CUSTOMER.
FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT,
SATISFACTORY QUALITY OR ARISING FROM A COURSE OF Confidentiality. "Confidential Information" means the terms of this
DEALING, USAGE, OR TRADE PRACTICE, ARE HEREBY Agreement; all information marked by the disclosing party as
EXCLUDED TO THE EXTENT ALLOWED BY APPLICABLE LAW. proprietary or confidential; any provided software, related
NO WARRANTY IS MADE REGARDING THE RESULTS OF ANY documentation or related performance test results derived by
SOFTWARE, SUPPORT OR SERVICES OR THAT THE SOFTWARE Licensee; and any methods, concepts or processes utilized in
WILL OPERATE WITHOUT ERRORS, PROBLEMS OR provided software or related documentation. Confidential Information
INTERRUPTIONS, OR THAT ERRORS OR BUGS IN THE shall remain the sole property of the disclosing party and shall not be
SOFTWARE WILL BE CORRECTED, OR THAT THE SOFTWARE'S disclosed to any non-Authorized User without the prior written consent
FUNCTIONALITY OR SERVICES WILL MEET CUSTOMER'S of the disclosing party. If Confidential Information is communicated
REQUIREMENTS. NO TIBCO DEALER, DISTRIBUTOR, AGENT OR orally, such communication shall be confirmed as "Confidential" in
EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS, writing within thirty days of such disclosure. The parties agree to
EXTENSIONS OR ADDITIONS TO THIS WARRANTY. protect the Confidential Information of the other in the same manner it
protects the confidentiality of similar information and data of its own
Indemnity. If Customer obtained the Software from TIBCO directly, (and at all times exercising at least a reasonable degree of care).
then TIBCO shall indemnify Licensee from and against any final Except with respect to the Software, items will not be deemed
judgment by a court of competent jurisdiction, including reasonable Confidential Information if (i) available to the public other than by a
attorneys' fees, that the unmodified TIBCO Software infringes any breach of an agreement with TIBCO, (ii) rightfully received from a third
patent issued by the United States, Canada, Australia, Japan, or any party not in breach of any obligation of confidentiality, (iii)
member of the European Union, or any copyright, or any trade secret independently developed by one party without use of the Confidential
of a third party; provided that TIBCO is promptly notified in writing of Information of the other; (iv) known to the recipient at the time of
such claim, TIBCO has the exclusive right to control such defense disclosure (other than under a separate confidentiality obligation); or
and/or settlement, and Licensee shall provide reasonable assistance (v) produced in compliance with applicable law or court order,
(at TIBCO's expense) in the defense thereof. In no event shall provided the other party is given reasonable notice of the same. Both
Licensee settle any claim, action or proceeding without TIBCO's prior parties agree to indemnify the other for any damages the other may
written approval. In the event of any such claim, litigation or threat sustain resulting from their unauthorized use and/or disclosure of the
thereof, TIBCO, at its sole option and expense, shall (a) procure for other's Confidential Information. Such damages shall include
Licensee the right to continue to use the TIBCO Software or (b) reasonable expenses incurred in seeking both legal and equitable
replace or modify the TIBCO Software with functionally equivalent remedies. To the extent required by law, at Customer's request,
software. If such settlement or modification is not commercially TIBCO shall provide Customer with the interface information needed
reasonable (in the reasonable opinion of TIBCO), TIBCO may cancel to achieve interoperability between the Software and another
this Agreement upon sixty days prior written notice to Licensee, and independently created program, on payment of TIBCO's applicable
refund to Licensee the unamortized portion of the license fees paid to fee. Customer agrees to observe obligations of confidentiality with
TIBCO by Licensee based on a five-year straight-line depreciation. respect to such information.
This Section states the entire liability of TIBCO with respect to the
infringement of any Intellectual Property rights, and Licensee hereby Export. Software, including technical data, is subject to U.S. export
expressly waives any other liabilities or obligations of TIBCO with control laws, including the U.S. Export Administration Act and its
respect thereto. The foregoing indemnity shall not apply to the extent associated regulations, and may be subject to export or import
any infringement could have been avoided by use of the then-current regulations in other countries. Customer agrees to comply strictly with
release. all such regulations and agrees to obtain all necessary licenses to
export, re-export, or import Software.

TIBCO Adapter for ActiveDatabase User’s Guide

 TIBCO Software Inc. End User License Agreement 325
|
Government Use. If the Customer is an agency, department, or other "Limited Warranty" all fees paid under or in connection with this
entity of the United States Government ("Government"), the use, Agreement are non-refundable and no right of set-off exists. All
duplication, reproduction, release, modification, disclosure or transfer payments of fees due shall be made in U.S. dollars, net 30 from
of the Software, or any related documentation of any kind, including Purchase Date, or, for any other amounts coming due hereafter, net
technical data or manuals, is restricted in accordance with Federal 30 from TIBCO's invoice. A service charge of one and one-half
Acquisition Regulation ("FAR") 12.212 for civilian agencies and percent per month will be applied to all invoices that are not paid on
Defense Federal Acquisition Regulation Supplement ("DFARS") time. Licensee agrees to pay all sales, use, value-added, withholding,
227.7202 for military agencies. The Software is commercial computer excise and any other similar taxes or government charges, exclusive
software and commercial computer software documentation. Use of of TIBCO's income taxes. No delay in the performance of any
the Software and related documentation by the Government is further obligation by either party, excepting all obligations to make payment,
restricted in accordance with the terms of this Agreement, and any shall constitute a breach of this Agreement to the extent caused by
modification thereto. force majeure. Customer hereby grants TIBCO and its independent
auditors the right to audit Customer's compliance with this Agreement.
Orders. An Ordering Document shall be deemed accepted only by If any portion of this Agreement is found to be void or unenforceable,
issuance of a TIBCO invoice and solely for purposes of administrative the remaining provisions shall remain in full force and effect. This
convenience. None of the terms of the Ordering Document (other than Agreement shall be governed by and construed in accordance with
the Software product name, number of Permitted Instances, level of the laws of the State of California, United States of America, as if
Support, description of Services, and fees due in connection performed wholly within the state and without giving effect to the
therewith) shall apply for any reason or purpose whatsoever, principles of conflict of law. The state and/or federal courts in San
regardless of any statement on any Ordering Document to the Francisco, California, USA, shall have exclusive jurisdiction of any
contrary, unless countersigned by an officer of TIBCO. This action arising out of or relating to this Agreement. The United Nations
Agreement constitutes the entire agreement between the parties with Convention on Contracts for the International Sale of Goods is
respect to the use of the Software, Support and Services, and excluded from application hereto. If any portion hereof is found to be
supersedes all proposals, oral or written, and all other void or unenforceable, the remaining provisions of this Agreement
representations, statements, negotiations and undertakings relating to shall remain in full force and effect.
the subject matter hereof. All orders of Software, Support or Services
by Customer from TIBCO shall be deemed to occur under the terms of Definitions. In connection with this Agreement, the following
this Agreement (with or without reference to this Agreement), unless capitalized terms shall have the following meaning: "Agreement"
expressly superseded by a signed written Agreement between the means this End User License Agreement; "Connection" for the TIBCO
parties. Software shall be delivered electronically (unless physical Software product TIBCO Enterprise for JMS - Full Edition means a
shipment is specifically set forth in an Ordering Document), and such TIBCO Enterprise for JMS client connection to the TIBCO Enterprise
delivery shall occur upon e-mail of download information to Licensee for JMS server for the purpose of sending or receiving messages and
at the email address set forth in the Ordering Document or as for the purposes of the TIBCO Software products TIBCO
otherwise provided by Customer to TIBCO. Physical deliveries (if SmartSockets and TIBCO SmartMQ software products, a Connection
applicable) of Software and documentation which typically means any network protocol link established with such TIBCO
accompanies the Software on delivery shall be on CD-ROM, FOB Software (directly or indirectly) to any other entity, including but not
TIBCO, and delivery shall occur by depositing the CD-ROM with limited to software, firmware or hardware; "Customer" means the
TIBCO's overnight carrier (at no charge to Customer). original purchaser or licensee of the Software and any permitted
successors and assigns; "Developer" means one user/developer of a
Term and Termination. Support or Services may be terminated: (a) TIBCO Software product for use in Development; "Development"
by either party upon a default of the other, such default remaining means used for software development purposes only; "Enterprise"
uncured for fifteen days from written notice from the non-defaulting means an unlimited number of Permitted Instances for a period of one
party; (b) upon the filing for bankruptcy or insolvency of the other year from the Purchase Date (unless otherwise set forth in the
party, (c) by either party upon prior written notice at least sixty days Ordering Document), at which time existing licenses convert to
prior to the end of any annual Maintenance period; or (d) by Licensee perpetual and Customer may not thereafter deploy additional
(for Services), upon ten days prior written notice. Termination of Permitted Instances, and in any event, shall (during the one-year
Support or Services shall not terminate this Agreement. Customer unlimited deployment period) exclude any entity which acquires, is
may terminate this Agreement in its entirety at any time by destroying acquired by, merged into, or otherwise combined with Customer.
all copies of the Software. Upon termination of this Agreement in its Customer hereby agrees to provide TIBCO with notice of the number
entirety, for any reason, Customer must cease using and return or of Permitted Instances deployed at the end of such one-year period
destroy all copies of the Software. Customer's obligation to pay within thirty days thereafter; "Fab" means unlimited use for shop-floor
accrued charges and any fees due as of the date of termination, as manufacturing applications at a Site; "Workstation" shall mean a
well as the sections entitled "Confidentiality", "Limited Warranty" and single end-user computer that is generally intended to be accessed by
"Limitation of Liability" shall survive any such termination. one person at a time; "Ordering Document" means any purchase
order or similar document or agreement requesting Software, Support
Authority. You hereby represent and warrant that you have full power or Services; "Permitted Instance(s)" means the number of copies of
and authority to accept the terms of this Agreement on behalf of Software running on a Server Instance, Workstation, User, or
Customer, and that Customer agrees to be bound by this Agreement. Development basis, on a designated Platform, as set forth in an
Ordering Document, including, without limitation, Enterprise, Site and
General. Fees on the Ordering Document (all to be paid on the latter Fab licensing; "Platform" means the operating system set forth in an
of thirty days from Invoice by TIBCO or the date set forth in the Ordering Document; "Purchase Date" means the date the Ordering
Ordering Document) do not include sales, use, withholding, Document is accepted by TIBCO; "Server Instance" means a
value-added or similar taxes, and Customer agrees to pay the same, computer with 1 CPU (unless otherwise set forth in the Ordering
excluding therefrom taxes related to TIBCO's income and corporate Document) performing common services for multiple machines; "Site"
franchise tax. Customer agrees to pay all reasonable costs incurred means an unlimited number of Permitted Instances at a specific
(including reasonable attorneys' fees) in collecting past due amounts physical address set forth in the Ordering Document (or, in the
under this Agreement. Except as set forth in the Section entitled absence of any address, at Customer's corporate headquarters);

TIBCO Adapter for ActiveDatabase User’s Guide

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

TIBCO Adapter for ActiveDatabase User’s Guide

 Third Party Software License Agreements 327
|

Third Party Software License Agreements

The following are the software licenses for the Third Party Software Redistribution and use in source and binary forms, with or without
provided in connection with the software. modification, are permitted provided that the following conditions are
met:

The Apache Software License, Version 1.1 1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
Copyright (c) 1999 The Apache Software Foundation. All rights
reserved. 2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
Redistribution and use in source and binary forms, with or without documentation and/or other materials provided with the distribution.
modification, are permitted provided that the following conditions are
met: 3. The end-user documentation included with the redistribution, if any,
must include the following acknowledgment:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer. "This product includes software developed by the Apache Software
Foundation (http://www.apache.org/)." Alternately, this
2. Redistributions in binary form must reproduce the above copyright acknowledgment may appear in the software itself, if and wherever
notice, this list of conditions and the following disclaimer in the such third-party acknowledgments normally appear.
documentation and/or other materials provided with the distribution.
4. The names "Xalan" and "Apache Software Foundation" must not be
3. The end-user documentation included with the redistribution, if any, used to endorse or promote products derived from this software
must include the following acknowledgment: "This product includes without prior written permission. For written permission, please
software developed by the Apache Software Foundation contact [email protected].
(http://www.apache.org/)." Alternately, this acknowledgment may
appear in the software itself, if and wherever such third-party 5. Products derived from this software may not be called "Apache",
acknowledgments normally appear. nor may "Apache" appear in their name, without prior written
permission of the Apache Software Foundation.
4. The names "Xerces", "Xalan" and "Apache Software Foundation"
must not be used to endorse or promote products derived from this THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED
software without prior written permission. For written permission, OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
please contact [email protected]. Products derived from this THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
software may not be called "Apache", nor may "Apache" appear in FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
their name, without prior written permission of the Apache Software NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
Foundation. ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT POSSIBILITY OF SUCH DAMAGE.
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER This software consists of voluntary contributions made by many
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN individuals on behalf of the Apache Software Foundation and was
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING originally based on software copyright (c) 1999, Lotus Development
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF Corporation., http://www.lotus.com. For more information on the
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE Apache Software Foundation, please see <http://www.apache.org/>.
POSSIBILITY OF SUCH DAMAGE.

* This software consists of voluntary contributions made by many W3C IPR SOFTWARE NOTICE
individuals on behalf of the Apache Software Foundation and was
originally based on software copyright (c) 1999, Lotus Development Copyright 2000 World Wide Web Consortium, (Massachusetts
Corporation., http://www.lotus.com. For more information on the Institute of Technology, Institut National de Recherche en Informatique
Apache Software Foundation, please see <http://www.apache.org/>./ et en Automatique, Keio University). All Rights Reserved.

The DOM bindings are published under the W3C Software Copyright
The Apache Software License, Version 1.1 Noticeand License. The software license requires "Notice of any
changes ormodifications to the W3C files, including the date changes
Copyright (c) 1999 The Apache Software Foundation. All rights were made."
reserved.
Consequently, modified versions of the DOM bindings must document
that they do not conform to the W3C standard; in the case of the IDL

TIBCO Adapter for ActiveDatabase User’s Guide

328
| Third Party Software License Agreements
binding, the pragma prefix can no longer be 'w3c.org'; in the case of The terms of IBM Public License Version 1.0 apply to the TIBCO End
the Java binding, the package names can no longer be in the 'org.w3c' User License Agreement. Any provisions in this License Agreement
package. 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
Note: The original version of the W3C Software Copyright Notice and the event provisions of this License Agreement differ from the terms of
License could be found at the IBM Public License Version 1.0, you may obtain the ICU source
http://www.w3.org/Consortium/Legal/copyright-software-19980720 code by sending email to [email protected].

Copyright 1994-2000 World Wide Web Consortium, (Massachusetts "IBM Public License Version 1.0
Institute of Technology, Institut National de Recherche en Informatique
et en Automatique, Keio University). All Rights Reserved. THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE
http://www.w3.org/Consortium/Legal/ TERMS OF THIS IBM PUBLIC LICENSE ("AGREEMENT"). ANY
USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM
This W3C work (including software, documents, or other related CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS
items) is being provided by the copyright holders under the following AGREEMENT.
license. By obtaining, using and/or copying this work, you (the
licensee) agree that you have read, understood, and will comply with 1. DEFINITIONS
the following terms and conditions:
"Contribution" means: a) in the case of International Business
Permission to use, copy, and modify this software and its Machines Corporation ("IBM"), the Original Program, and b) in the
documentation, with or without modification, for any purpose and case of each Contributor, i) changes to the Program, and ii) additions
without fee or royalty is hereby granted, provided that you include the to the Program; where such changes and/or additions to the Program
following on ALL copies of the software and documentation or portions originate from and are distributed by that particular Contributor. A
thereof, including modifications, that you make: Contribution 'originates' from a Contributor if it was added to the
Program by such Contributor itself or anyone acting on such
1.The full text of this NOTICE in a location viewable to users of the Contributor's behalf. Contributions do not include additions to the
redistributed or derivative work. Program which: (i) are separate modules of software distributed in
conjunction with the Program under their own license agreement, and
2.Any pre-existing intellectual property disclaimers, notices, or terms (ii) are not derivative works of the Program. "Contributor" means IBM
and conditions. If none exist, a short notice of the following form and any other entity that distributes the Program.
(hypertext is preferred, text is permitted) should be used within the
body of any redistributed or derivative code: "Copyright "Licensed Patents " mean patent claims licensable by a Contributor
[$date-of-software] World Wide Web Consortium, (Massachusetts which are necessarily infringed by the use or sale of its Contribution
Institute of Technology, Institut National de Recherche en Informatique alone or when combined with the Program.
et en Automatique, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/" "Original Program" means the original version of the software
accompanying this Agreement as released by IBM, including source
3.Notice of any changes or modifications to the W3C files, including code, object code and documentation, if any.
the date changes were made. (We recommend you provide URIs to
the location from which the code is derived.) "Program" means the Original Program and Contributions. "Recipient"
means anyone who receives the Program under this Agreement,
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," including all Contributors.
AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 2. GRANT OF RIGHTS
LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE a) Subject to the terms of this Agreement, each Contributor hereby
SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY grants Recipient a non-exclusive, worldwide, royalty-free copyright
THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR license to reproduce, prepare derivative works of, publicly display,
OTHER RIGHTS. publicly perform, distribute and sublicense the Contribution of such
Contributor, if any, and such derivative works, in source code and
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, object code form.
INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION. b) Subject to the terms of this Agreement, each Contributor hereby
grants Recipient a non-exclusive, worldwide, royalty-free patent
The name and trademarks of copyright holders may NOT be used in license under Licensed Patents to make, use, sell, offer to sell, import
advertising or publicity pertaining to the software without specific, and otherwise transfer the Contribution of such Contributor, if any, in
written prior permission. Title to copyright in this software and any source code and object code form. This patent license shall apply to
associated documentation will at all times remain with copyright the combination of the Contribution and the Program if, at the time the
holders. 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
International Business Machines Corporation which include the Contribution. No hardware per se is licensed
hereunder.
This product includes software developed by International Business
Machines Corporation. Copyright (c) International Business Machines. c) Recipient understands that although each Contributor grants the
All rights reserved. licenses to its Contributions set forth herein, no assurances are
provided by any Contributor that the Program does not infringe the

TIBCO Adapter for ActiveDatabase User’s Guide

 Third Party Software License Agreements 329
|
patent or other intellectual property rights of any other entity. Each performance claims and warranties are such Commercial
Contributor disclaims any liability to Recipient for claims brought by Contributor's responsibility alone. Under this section, the Commercial
any other entity based on infringement of intellectual property rights or Contributor would have to defend claims against the other
otherwise. As a condition to exercising the rights and licenses granted Contributors related to those performance claims and warranties, and
hereunder, each Recipient hereby assumes sole responsibility to if a court requires any other Contributor to pay any damages as a
secure any other intellectual property rights needed, if any. For result, the Commercial Contributor must pay those damages.
example, if a third party patent license is required to allow Recipient to
distribute the Program, it is Recipient's responsibility to acquire that 5. NO WARRANTY
license before distributing the Program.
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE
d) Each Contributor represents that to its knowledge it has sufficient PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT
copyright rights in its Contribution, if any, to grant the copyright license WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS
set forth in this Agreement. OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY
WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT,
3. REQUIREMENTS A Contributor may choose to distribute the MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Program in object code form under its own license agreement, Each Recipient is solely responsible for determining the
provided that: a) it complies with the terms and conditions of this appropriateness of using and distributing the Program and assumes
Agreement; and b) its license agreement: i) effectively disclaims on all risks associated with its exercise of rights under this Agreement,
behalf of all Contributors all warranties and conditions, express and including but not limited to the risks and costs of program errors,
implied, including warranties or conditions of title and compliance with applicable laws, damage to or loss of data, programs
non-infringement, and implied warranties or conditions of or equipment, and unavailability or interruption of operations.
merchantability and fitness for a particular purpose; ii) effectively
excludes on behalf of all Contributors all liability for damages, 6. DISCLAIMER OF LIABILITY
including direct, indirect, special, incidental and consequential
damages, such as lost profits; iii) states that any provisions which EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT,
differ from this Agreement are offered by that Contributor alone and NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE
not by any other party; and iv) states that source code for the Program ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL,
is available from such Contributor, and informs licensees how to SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
obtain it in a reasonable manner on or through a medium customarily (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER
used for software exchange. When the Program is made available in CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
source code form: a) it must be made available under this Agreement; CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
and b) a copy of this Agreement must be included with each copy of NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
the Program. THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF
Each Contributor must include the following in a conspicuous location ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
in the Program: Copyright ? {date here}, International Business
Machines Corporation and others. All Rights Reserved. In addition, 7. GENERAL
each Contributor must identify itself as the originator of its
Contribution, if any, in a manner that reasonably allows subsequent If any provision of this Agreement is invalid or unenforceable under
Recipients to identify the originator of the Contribution. applicable law, it shall not affect the validity or enforceability of the
remainder of the terms of this Agreement, and without further action
4. COMMERCIAL DISTRIBUTION Commercial distributors of by the parties hereto, such provision shall be reformed to the minimum
software may accept certain responsibilities with respect to end users, extent necessary to make such provision valid and enforceable. If
business partners and the like. While this license is intended to Recipient institutes patent litigation against a Contributor with respect
facilitate the commercial use of the Program, the Contributor who to a patent applicable to software (including a cross-claim or
include the Program in a commercial product offering should do so in counterclaim in a lawsuit), then any patent licenses granted by that
a manner which does not create potential liability for other Contributor to such Recipient under this Agreement shall terminate as
Contributors. Therefore, if a Contributor includes the Program in a of the date such litigation is filed. In addition, If Recipient institutes
commercial product offering, such Contributor ("Commercial patent litigation against any entity (including a cross-claim or
Contributor") hereby agrees to defend and indemnify every other counterclaim in a lawsuit) alleging that the Program itself (excluding
Contributor ("Indemnified Contributor") against any losses, damages combinations of the Program with other software or hardware)
and costs (collectively "Losses") arising from claims, lawsuits and infringes such Recipient's patent(s), then such Recipient's rights
other legal actions brought by a third party against the Indemnified granted under Section 2(b) shall terminate as of the date such
Contributor to the extent caused by the acts or omissions of such litigation is filed. All Recipient's rights under this Agreement shall
Commercial Contributor in connection with its distribution of the terminate if it fails to comply with any of the material terms or
Program in a commercial product offering. The obligations in this conditions of this Agreement and does not cure such failure in a
section do not apply to any claims or Losses relating to any actual or reasonable period of time after becoming aware of such
alleged intellectual property infringement. In order to qualify, an noncompliance. If all Recipient's rights under this Agreement
Indemnified Contributor must: a) promptly notify the Commercial terminate, Recipient agrees to cease use and distribution of the
Contributor in writing of such claim, and b) allow the Commercial Program as soon as reasonably practicable. However, Recipient's
Contributor to control, and cooperate with the Commercial Contributor obligations under this Agreement and any licenses granted by
in, the defense and any related settlement negotiations. The Recipient relating to the Program shall continue and survive. IBM may
Indemnified Contributor may participate in any such claim at its own publish new versions (including revisions) of this Agreement from time
expense. For example, a Contributor might include the Program in a to time. Each new version of the Agreement will be given a
commercial product offering, Product X. That Contributor is then a distinguishing version number.
Commercial Contributor. If that Commercial Contributor then makes
performance claims, or offers warranties related to Product X, those

TIBCO Adapter for ActiveDatabase User’s Guide

330
| Third Party Software License Agreements
The Program (including Contributions) may always be distributed PARTICULAR PURPOSE OR NON-INFRINGEMENT ARE
subject to the version of the Agreement under which it was received. DISCLAIMED, EXCEPT TO THE EXTENT THAT THESE
DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
In addition, after a new version of the Agreement is published,
Contributor may elect to distribute the Program (including its 5. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED
Contributions) under the new version. No one other than IBM has the BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE
right to modify this Agreement. Except as expressly stated in Sections FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR SPECIAL,
2(a) and 2(b) above, Recipient receives no rights or licenses to the INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
intellectual property of any Contributor under this Agreement, whether DAMAGES, HOWEVER CAUSED REGARDLESS OF THE THEORY
expressly, by implication, estoppel or otherwise. All rights in the OF LIABILITY, ARISING OUT OF OR RELATED TO THE USE OF OR
Program not expressly granted under this Agreement are reserved. INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event
This Agreement is governed by the laws of the State of New York and will Sun's liability to you, whether in contract, tort (including
the intellectual property laws of the United States of America. No party negligence), or otherwise, exceed the amount paid by you for
to this Agreement will bring a legal action under this Agreement more Software under this Agreement. The foregoing limitations will apply
than one year after the cause of action arose. Each party waives its even if the above stated warranty fails of its essential purpose.
rights to a jury trial in any resulting litigation."
6. Termination. This Agreement is effective until terminated. You may
terminate this Agreement at any time by destroying all copies of
Sun Microsystems, Inc. Binary Code License Agreement Software. This Agreement will terminate immediately without notice
from Sun if you fail to comply with any provision of this Agreement.
READ THE TERMS OF THIS AGREEMENT AND ANY PROVIDED Upon Termination, you must destroy all copies of Software.
SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY
"AGREEMENT") CAREFULLY BEFORE OPENING THE SOFTWARE 7. Export Regulations. All Software and technical data delivered under
MEDIA PACKAGE. BY OPENING THE SOFTWARE MEDIA this Agreement are subject to US export control laws and may be
PACKAGE, YOU AGREE TO THE TERMS OF THIS AGREEMENT. IF subject to export or import regulations in other countries. You agree to
YOU ARE ACCESSING THE SOFTWARE ELECTRONICALLY, comply strictly with all such laws and regulations and acknowledge
INDICATE YOUR ACCEPTANCE OF THESE TERMS BY that you have the responsibility to obtain such licenses to export,
SELECTING THE "ACCEPT" BUTTON AT THE END OF THIS re-export, or import as may be required after delivery to you.
AGREEMENT. IF YOU DO NOT AGREE TO ALL THESE TERMS,
PROMPTLY RETURN THE UNUSED SOFTWARE TO YOUR PLACE 8. U.S. Government Restricted Rights. If Software is being acquired
OF PURCHASE FOR A REFUND OR, IF THE SOFTWARE IS by or on behalf of the U.S. Government or by a U.S. Government
ACCESSED ELECTRONICALLY, SELECT THE "DECLINE" BUTTON prime contractor or subcontractor (at any tier), then the Government's
AT THE END OF THIS AGREEMENT. rights in Software and accompanying documentation will be only as
set forth in this Agreement; this is in accordance with 48 CFR
1. LICENSE TO USE. Sun grants you a non-exclusive and 227.7201 through 227.7202-4 (for Department of Defense (DOD)
non-transferable license for the internal use only of the accompanying acquisitions) and with 48 CFR 2.101 and 12.212 (for non-DOD
software and documentation and any error corrections provided by acquisitions).
Sun (collectively "Software"), by the number of users and the class of
computer hardware for which the corresponding fee has been paid. 9. Governing Law. Any action related to this Agreement will be
governed by California law and controlling U.S. federal law. No choice
2. RESTRICTIONS. Software is confidential and copyrighted. Title to of law rules of any jurisdiction will apply.
Software and all associated intellectual property rights is retained by
Sun and/or its licensors. Except as specifically authorized in any 10. Severability. If any provision of this Agreement is held to be
Supplemental License Terms, you may not make copies of Software, unenforceable, this Agreement will remain in effect with the provision
other than a single copy of Software for archival purposes. Unless omitted, unless omission would frustrate the intent of the parties, in
enforcement is prohibited by applicable law, you may not modify, which case this Agreement will immediately terminate.
decompile, or reverse engineer Software. You acknowledge that
Software is not designed, licensed or intended for use in the design, 11. Integration. This Agreement is the entire agreement between you
construction, operation or maintenance of any nuclear facility. Sun and Sun relating to its subject matter. It supersedes all prior or
disclaims any express or implied warranty of fitness for such uses. No contemporaneous oral or written communications, proposals,
right, title or interest in or to any trademark, service mark, logo or trade representations and warranties and prevails over any conflicting or
name of Sun or its licensors is granted under this Agreement. additional terms of any quote, order, acknowledgment, or other
communication between the parties relating to its subject matter
3. LIMITED WARRANTY. Sun warrants to you that for a period of during the term of this Agreement. No modification of this Agreement
ninety (90) days from the date of purchase, as evidenced by a copy of will be binding, unless in writing and signed by an authorized
the receipt, the media on which Software is furnished (if any) will be representative of each party.
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 JAVA(TM) INTERFACE CLASSES JAVA API FOR XML
Sun's option to replace Software media or refund the fee paid for PROCESSING (JAXP), VERSION 1.1 SUPPLEMENTAL LICENSE
Software. TERMS

4. DISCLAIMER OF WARRANTY. UNLESS SPECIFIED IN THIS These supplemental license terms ("Supplemental Terms") add to or
AGREEMENT, ALL EXPRESS OR IMPLIED CONDITIONS, modify the terms of the Binary Code License Agreement (collectively,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY the "Agreement"). Capitalized terms not defined in these
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A Supplemental Terms shall have the same meanings ascribed to them

TIBCO Adapter for ActiveDatabase User’s Guide

 Third Party Software License Agreements 331
|
in the Agreement. These Supplemental Terms shall supersede any party's opinion be likely to become, the subject of a claim of
inconsistent or conflicting terms in the Agreement, or in any license infringement of any intellectual property right.
contained within the Software.
For inquiries please contact: Sun Microsystems, Inc. 901 San Antonio
1. Software Internal Use and Development License Grant. Subject to Road, Palo Alto, California 94303
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, Microstar Software.
non-transferable, limited license to reproduce internally and use
internally the binary form of the Software, complete and unmodified, Portions of this Software may include software provided by Microstar
for the sole purpose of designing, developing and testing your Java Software. Copyright (c) 1997, 1998 by Microstar Software. All rights
applets and applications ("Programs"). reserved.

2. License to Distribute Software. In addition to the license granted in

Section 1 (Software Internal Use and Development License Grant) of DataDirect Technologies (Merant) Software.
these Supplemental Terms, subject to the terms and conditions of this
Agreement, including but not limited to Section 3 (Java Technology Portions of this software are copyrighted by DataDirect Technologies
Restrictions), Sun grants you a non-exclusive, non-transferable, (MERANT), 1991-2002.
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

TIBCO Adapter for ActiveDatabase User’s Guide

332
| Third Party Software License Agreements

TIBCO Adapter for ActiveDatabase User’s Guide

 | 333

Index

Symbols adding
listeners 186
* 184 adding a sequence for parent-child 194
. 184 adding an association for parent-child 195
> 184 agents 232
_ 36, 184 alerter
on Microsoft SQL Server 134
on Sybase SQL Server 140
alerts 232
A auto-discovery process, TIBCO Hawk 234

access to DB2 AS/400 tables 73

adapter
changing a configuration 37, 216 B
checking for duplicate 17
component (operation) information through TIBCO binary type 185
Hawk 245 bind statements 149
error messages when changing a configuration 38
naming restrictions 36
size limitations 36
starting as a Windows service 131 C
stopping 37
tracing 211 callout library 200
adapter configuration, changing 37, 216 callout library, compilers 203
ADB_ERROR_TEXT 177 certified message delivery
ADB_ERROR_TIME 177 exception handling 283
ADB_L_CMSEQUENCE 171 moving ledger files 188
ADB_L_DELIVERY_STATUS 171 preregistering listeners 186
ADB_OPCODE 170, 177 Class Microagent Name field, adapter 64
ADB_REF_OBJECT column in the publishing closure field 148
table 192 column names in an exception table 178
ADB_SEQUENCE 170 column names, reserved prefix 37
ADB_SET_SEQUENCE 170 columns, maximum number 36
ADB_SOURCE 11, 176 command line arguments 246
ADB_SUBJECT 170
ADB_TIMESTAMP 170
ADB_UPDATE_ALL 170, 177
adbDateTime 190
adbPreCommit() 202

TIBCO Adapter for ActiveDatabase User’s Guide

334
| Index
commands E
adbagent 28, 111, 131, 139, 142
adbalerter_ora8 137 error messages about database cleanup 38
Connect 46, 50 examples
copy 138, 141 commands for running an adapter as a service 131
cp 140 REF cursor procedure 168
execute 137 Exceed FAQ 284
isql 138, 139, 140, 141, 142 exception table
select 28, 29, 30, 31, 32 defined 11
sqlplus 25, 32, 137 structure of 177
tibrvsend 31 exception table, column names in 178
commit_and_notify 135
commit_and_notify_table 135
compilers for callout libraries 203
configuration properties, retrieving through TIBCO F
Hawk 246
conversion, messages 6 fault tolerance 100
custom RPC operation 159 file format
customer support xix dat 22
VC 22
Float data type 185
format, messages 6
D
dat file format 22
data format 6 G
data source, ODBC
using 118 global variables 38
database errors, capturing 177 setting for monitoring 63
database type mapping 184
Date types 185
date/time values 190
dateTime 183 I
DB2 on OS/390 trigger statements syntax 218
debug, adapter option 117 id alerter option on Oracle 136
delete trigger 71
destination table
schema 10
distributed queues 166 K
dot character 184
dsn, adapter option 118 key columns, requirement for publish-by-reference 16
dsn, alerter option on Oracle 136
duplicate adapters 17

TIBCO Adapter for ActiveDatabase User’s Guide

 Index 335
|

L N
ledger files naming restrictions
location 188 adapters 36
moving 188 database columns 37
publication size status 119 publishing table 81
publication timeout status 119 subjects 184
retrieving information through TIBCO Hawk 255 notify procedure
listeners, adding 186 on Microsoft SQL Server 138
load balancing 101, 131 on Sybase 140
across adapters 166 notifytable procedure
in an adapter 164 on Microsoft SQL Server 138
Log File field, adapter 61 on Sybase 140
log file options 211 NULL attributes 85
log files location 59
Log Info field, adapter 61
Log to Standard field, adapter 61
logtest, sample program 18 O
LONG data type 78
loop detection obfuscation 115
column used for 176 opaque format, using to publish 18
defined 11
using for replication 11

M parameterized subject 185

binary type 185
mapping database types 184 Date types 185
messages 6 Float type 185
conversion 6 illegal characters 185
data format 6
microagent methods supported 238
Microagent Session field, adapter 64
MInstance
data format 74
MInstance data format 74
multiple file project 12

TIBCO Adapter for ActiveDatabase User’s Guide

336
| Index
parameters publishing table
AE Type 72, 86 columns in 170
Batch Publish Status Updates 53 name size 81
Child Table Mapping 87 restrictions for 78
Class Reference 82, 90, 96 pwd
Debug Level 56 alerter option on Oracle 136
Deploy On Save 38
Do Not Generate Triggers 81
Enable Loop Detection 81
Endpoint Reference 82, 90, 96 Q
Generate Verbose Output 57
Join To 73, 87 quality of service
Polling Batch Size (Maximum Rows) 52 and load balancing 166
Polling Interval 52 queue member load 167
Publish Child Data 54
Publisher Batch Confirm Timeout 53
Publishing Table 81
Reply Subject 96 R
Storage Mode 80
Subscriber Batch Commit Size 54 record size, limitations 36
Subscriber Batch Commit Timeout 54 REF data type 168
Subscriber Bulk Insert Size 55 reference object location 192
Table Name 87 request
Tables and Columns 72, 86 defined 146
Type 72, 86 request/response
Update Mode 81 load balancing for 166
Update Trigger? 72 using 144
Use Exception Table 55 using multiple threads 164
Use? 72, 86 response defined 147
User Key 72, 86 reviewLedger, TIBCO Hawk method 255
parent/child publication 16 RPC programs, client 162
parent-child association 195 running the adapter as a Windows service 131
parent-child sequence 194 rv_Rpc() 150
password property 123 rv_Send() 150
PL/SQL procedure for REF cursor 168 rv_SendWithReply() 150
preregistering listeners 186 RVMSG_DATETIME 183
Publication Service typical flow diagram 4 RVMSG_INT 183
publications RVMSG_OPAQUE 183
changing subject 16 RVMSG_REAL 183
size limitations 36 RVMSG_STRING 183
publish-child-data, adapter option 119
publishing
by reference 15, 78
by value 15
source data 192

TIBCO Adapter for ActiveDatabase User’s Guide

 Index 337
|

S T
same-named adapters 17 table access problems, overcoming 73
sample programs technical support xix
logtest 18 TIBCO Hawk
schema changes affecting adapter configuration 38 background information 232
schemas enterprise monitor components 232
for related tables 74 methods supported 238
referencing external 10 Monitoring tab use with 63
sequence number 170 TIBCO Hawk methods
source data publishing 192 getComponents 245
source data publishing example 198 getConfig 246
source table getRvConfig 249
loop detection column 176 getStatus 250
schema for 10 reviewLedger 255
source table changes 171 TIBCO Rendezvous, retrieving configuration through
SQL statement terminator 218 TIBCO Hawk 249
SQL_BATCHRETURN class, structure of 157 Tracing 288
SQL_BIND class, structure of 158 tracing features 211
SQL_OPS class, structure of 155 Tracing Levels and Fields 289
SQL_RESULTSET class, structure of 156 tracking identifier 288, 296
SQL_RETURN class, structure of 156 triggers
SQL_ROW class, structure of 156 how they are generated 171
SQL_STATEMENT class, structure of 158 no primary key 71
Standard Microagent Name field, adapter 63 purpose 171
standard RPC operation 155
starting an alerter on Oracle 135
stopping an adapter 37
sub-batch-commit-timeout, adapter option 120 U
sub-bulk-insert-size, adapter option 120
subjects underscore character 184
changing dynamically 16 update feature 16
naming restrictions 184 update trigger 71
parameterized 185 Use Advanced Logging field, adapter 59
subscriber 36 user authority 73
using wildcards 184, 186 user callout library 200
subscriptions user schema 134
size limitations 36 username property 123
wire format for 190 use-trace-file, adapter option 211
substitution 38 usr
support, contacting xix alerter option on Oracle 136
–system
configurl command-line argument 116

TIBCO Adapter for ActiveDatabase User’s Guide

338
| Index

V
variable substitution 38
variables 38
version, adapter option 112, 123

W
wildcard subject names 184, 186

TIBCO Adapter for ActiveDatabase User’s Guide