TIBCO ActiveMatrix® Adapter for
Database
Configuration and Deployment
Software Release 6.2
January 2012
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 THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. 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.
TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Adapter SDK, TIBCO Administrator, TIBCO Database Drivers Supplement, TIBCO Designer, TIBCO Enterprise Message Service, TIBCO Hawk, TIBCO Rendezvous, and TIBCO Runtime Agent are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or 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. SEE THE README 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.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
Copyright © 1999-2012 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| iii
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv
Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
TIBCO ActiveMatrix Adapter for Database Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
TIBCO Administration Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
TIBCO Administration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
TIBCO Administrator GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Adapter Project Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Chapter 2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Required Platform and Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
iv | Contents
Create the Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Configure the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Start the Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Change the Table Values and Receive Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Exit the Query Tool and Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Clean Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Chapter 3 Adapter Instance Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Configuration Task Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Saving the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Testing the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Notes on Configuring an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Configuration Recommendations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Changing an Existing Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Using Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Adapter Instance Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Design-time Connection Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Using Connection Settings Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Saving Connection Settings for Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Using Saved Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Runtime Connection Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Adapter Services Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
All Publication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
All Subscription Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
All Request-response Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Logging Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Startup Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Monitoring Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Chapter 4 Adapter Service Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Quality of Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Delivery Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Wire Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Publication Service Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Tables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Contents | v
DB2/OS390 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
DB2/AS400 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Sybase Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Child Table Order By Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Publisher Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Subscription Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Table Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Child Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Child Exception Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Subscriber Options for DB2 on OS/390 (z/OS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Subscriber Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Request-response Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Call Operation Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator . . . . . . . . . . . . . . .95
Create an EAR File in TIBCO Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Deploy the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Monitor the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 6 Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and Above . . . . . . . . . . . . . . . . . . 103
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Configuring and Starting the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Oracle Alerter Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
SQL Server Alerter Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Setting Up and Starting the Alerter on Microsoft SQL Server 2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Alerter Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Setting Up and Starting the Alerter on Sybase SQL Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Alerter Setup on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Alerter Setup on Microsoft Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
vi | Contents
Chapter 7 Using the Request-response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Request-response Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
TIBCO ActiveEnterprise or XML Message Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
TIBCO Rendezvous Message Request Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
TIBCO ActiveEnterprise or XML Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
TIBCO Rendezvous Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
RPC Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Standard RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Custom RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Implementing Client RPC Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Load Balancing in a Single Instance Using Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Load Balancing Across Adapter Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Oracle REF Data Type Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Chapter 8 Working With Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Publishing Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Removing Records from the Publication Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Publication Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Changing the Publication Trigger to Publish a Subset of Rows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Optimizing the Publication Sequence for Oracle RAC System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Source Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Exception Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Child Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Using an Exception Table as a Source Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Opaque Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Incremental Parent-child Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Sybase and Sybase Adaptive Server Anywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
MySQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Teradata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Mapping to Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Chapter 9 Advanced Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Subject and Destination Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Parameterized Subject or Destination Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Preregistering a Certified Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Contents | vii
Changing the Location of the Ledger File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Sending Messages to an Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
adbDateTime Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Publishing by Reference Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Changing Repository Objects for Parent-child Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Table to Record Sequence Numbers (DB2 on iSeries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
User Callout Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Using the alterMsgPub and alterMsgSub Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Using the adbPreCommit Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Building the Callout Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Unique Connection Identifier for Oracle Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Publishing in a Commitment Controlled Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Using the Adapter with a Revision Control System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Using a Log File for an Adapter Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Fine-tuning Tracing Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Log File Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Using Advanced Logging Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Using Database Deployment and Cleanup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Changing the SQL Statement Terminator (DB2 for z/OS Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
SSL Data Encryption using DataDirect ODBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
OS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Query Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Working with Multi-File Format Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Subscriber Reply Sender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Subscriber Pre-commit Stored Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
JMS Durable Subscriber Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Runtime Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Runtime Table Schema Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Group Message Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Load Balancing and Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Improving Performance Using Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Load Balancing Across Adapter Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Compressing JMS Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Configuring RVCMQ Backlog Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
viii | Contents
Chapter 10 Setting Encoding Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Setting TIBCO Messaging Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Configuring the Adapter to Communicate with the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Configuring the Adapter at Design Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Special Configurations for Supporting a UTF-8 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Special Configurations for Retrieving Unicode Data from Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Runtime Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Relevant Environment Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Chapter 11 Monitoring the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Starting TIBCO Hawk Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
The Auto-Discovery Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Invoking Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Available Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Appendix A Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
General Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Request-response Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Appendix B Trace Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Status Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Appendix C Adapter Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Properties File Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Tagging Values for Obfuscation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Runtime Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Required Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Additional Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Obfuscating or Encrypting a Password in the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Password Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Obfuscating a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Encrypting a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Using Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Contents | ix
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Figures | xi
Figures
Figure 1 TIBCO Designer Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Figure 2 TIBCO Administrator GUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Figure 3 Diagram of Publish-Subscribe Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Figure 4 Alerter Operation (Oracle and MSSQLServer). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Figure 5 Request-Response Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Figure 6 Request-response Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Figure 7 Example of Unicode Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Tables | xiii
Tables
Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Table 2 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Table 3 Values to Use for TIBCO Rendezvous and JMS Transport Types . . . . . . . . . . . . . . . . . . . . . . . . 18
Table 4 Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Table 5 Adapter Instance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Table 6 Design-time Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Table 7 JDBC Drivers and URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Table 8 Runtime Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Table 9 Publication Service Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Table 10 Subscription Service Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Table 11 Request-response Service Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Table 12 General Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Table 13 Logging Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Table 14 Startup Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Table 15 Monitoring Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Table 16 Publication Service: Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Table 17 Publication Service Tables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Table 18 Publication Service DB2/OS390 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Table 19 Publication Service DB2/AS400 Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Table 20 Publication Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Table 21 Subscription Service Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Table 22 Subscription Service Child Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Table 23 Subscription Service Child Exception Table Mappings Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Table 24 Subsciption Service DB2/390 Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Table 25 Subscription Service Subscriber Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Table 26 Subscription Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Table 27 Request-response Service Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Table 28 Request-response Call Operation Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
xiv | Tables
Table 29 Request-response Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Table 30 Request Schema Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Table 31 Reply Schema Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Table 32 Publishing Table Additional Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Table 33 Source Table Additional Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Table 34 Exception Table Additional Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Table 35 Child Exception Table Additional Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Table 36 Opaque Exception Table Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Table 37 Mapping to Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Table 38 Wire Format Parameters and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Table 39 adbPreCommit Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Table 40 Description of ADB_SUBSCRIBER_STATUS Class Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Table 41 Description of the Pre-commit Stored Procedure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Table 42 IANAAppCodePage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Table 43 TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang Values . . . . . . . . . . . . . . . . . . 237
Table 44 Standard Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Table 45 Custom Microagent Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Table 46 Custom Microagent Methods with adb.perfMon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Table 47 Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Table 48 Required Runtime Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Table 49 Additional Runtime Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| xv
Preface
TIBCO ActiveMatrix Adapter for Database software is a bidirectional gateway between
databases and applications configured for the TIBCO environment. The software supports
both publish-subscribe and request-response interactions.
Topics
• Changes from the Previous Release of this Guide, page xvi
• Related Documentation, page xvii
• Typographical Conventions, page xviii
• Connecting with TIBCO Resources, page xxi
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
xvi | Changes from the Previous Release of this Guide
Changes from the Previous Release of this Guide
This section itemizes the major changes from the previous release of this guide.
Support for Teradata Database
Adapter instance configuration and supported data types for the Teradata database have
been added. See JDBC Drivers and URLs on page 42, Runtime Connection Tab on
page 45, and Database Types on page 161 for more information.
Support for JMS Message Compression
JMS message compression is an instance-level option that ensures messages will take less
memory space in storage and be handled faster by the TIBCO Enterprise Message Service
server. See Compressing JMS Messages on page 224 for more information.
Support for RVCMQ Backlog Size Configuration
The RVCMQ scheduler receives inbound messages and assigns them to the worker. The
scheduler stores tasks in a message queue. You can limit the maximum size of that queue
by either number of bytes or number of messages, or both. See Configuring RVCMQ
Backlog Size on page 225 for more information.
Parameterized Destination Name Information
Publishing on parameterized subjects or destinations allows a subject or destination to be
created from the contents of one or more table columns. See Parameterized Subject or
Destination Names on page 168 for more information.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Preface | xvii
Related Documentation
This section lists documentation resources you may find useful.
TIBCO ActiveMatrix Adapter for Database Documentation
The following documents form the TIBCO ActiveMatrix Adapter for Database
documentation set:
• TIBCO ActiveMatrix Adapter for Database Concepts Read this manual to gain an
understanding of adapters in general that you can apply to the various tasks you may
undertake.
• TIBCO ActiveMatrix Adapter for Database Installation Read this manual to learn
how to install TIBCO ActiveMatrix Adapter for Database.
• TIBCO ActiveMatrix Adapter for Database Configuration and Deployment This
manual explains how to create and configure adapter projects. Information on
deploying adapter projects is also included.
• TIBCO ActiveMatrix Adapter for Database Examples Read this manual to work
through the examples provided with the adapter.
• TIBCO ActiveMatrix Adapter for Database Release Notes Read the release notes for
a list of new and changed features. This document also contains lists of known issues
and closed issues for this release.
Other TIBCO Product Documentation
You may find it useful to read the documentation for the following TIBCO products:
• TIBCO® Adapter SDK
• TIBCO Administrator™
• TIBCO ActiveMatrix BusinessWorks™
• TIBCO® Database Drivers Supplement
• TIBCO Designer™
• TIBCO Enterprise Message Service™
• TIBCO Hawk®
• TIBCO Rendezvous®
• TIBCO Runtime Agent™
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
xviii | Typographical Conventions
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions
Convention Use
TIBCO_HOME
TIB_ADADB_HOME
ENV_NAME
CONFIG_HOME
Many TIBCO products must be installed within the same home directory. This
directory is referenced in documentation as TIBCO_HOME. The default value of
TIBCO_HOME depends on the operating system. For example, on Windows systems,
the default value is C:\tibco.
Other TIBCO products are installed into an installation environment. Products
installed into different installation environments do not share components.
Incompatible products and multiple instances of the same product must be installed
into different installation environments. An installation environment consists of the
following properties:
• Name Identifies the installation environment. The name is appended to the
name of Windows services created by the installer and is a component of the
path to the product in the Windows Start > All Programs menu. This directory is
referenced in documentation as ENV_HOME.
• Path The directory into which the product is installed. This directory is
referenced in documentation as TIBCO_HOME. TIBCO ActiveMatrix Adapter
for Database installs into a directory within TIBCO_HOME. This directory is
referenced in documentation as TIB_ADADB_HOME. The default value of
TIB_ADADB_HOME depends on the operating system. For example, on Unix
systems, the default value is TIBCO_HOME/adapter/adadb/version.
A TIBCO configuration folder stores configuration data generated by TIBCO
products. Configuration data can include sample scripts, session data, configured
binaries, logs, and so on. This folder is referenced in documentation as
CONFIG_HOME. The default location of the folder is
USER_HOME/ENV_NAME/tibco/cfgmgmt/product_name. For example, on Windows, the
default location is C:\Documents and Settings\user_name\Application
Data\ENV_NAME\tibco\cfgmgmt\product_name.
code font Code font identifies commands, code examples, filenames, pathnames, and output
displayed in a command window. For example:
Use MyCommand to start the foo process.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Preface | xix
bold code font Bold code font is used in the following ways:
• In procedures, to indicate what a user types. For example: Type admin.
• In large code samples, to indicate the parts of the sample that are of particular
interest.
• In command syntax, to indicate the default parameter for a command. For
example, if no parameter is specified, MyCommand is enabled:
MyCommand [enable | disable]
italic font Italic font is used in the following ways:
• To indicate a document title. For example: See TIBCO ActiveMatrix
BusinessWorks Concepts.
• To introduce new terms For example: A portal page may contain several
portlets. Portlets are mini-applications that run in a portal.
• To indicate a variable in a command or code syntax that you must replace. For
example: MyCommand PathName
Key combinations Key name separated by a plus sign indicate keys pressed simultaneously. For
example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the
other. For example: Esc, Ctrl+Q.
The note icon indicates information that is of special interest or importance, for
example, an additional action required only in certain circumstances.
The tip icon indicates an idea that could be useful, for example, a way to apply the
information provided in the current section to achieve a specific result.
The warning icon indicates the potential for a damaging situation, for example, data
loss or corruption if certain steps are taken or not taken.
Table 1 General Typographical Conventions (Cont’d)
Convention Use
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
xx | Typographical Conventions
Table 2 Syntax Typographical Conventions
Convention Use
[ ] An optional item in a command or code syntax.
For example:
MyCommand [optional_parameter] required_parameter
| A logical OR that separates multiple items of which only one may be chosen.
For example, you can select only one of the following parameters:
MyCommand para1 | param2 | param3
{ } A logical group of items in a command. Other syntax notations may appear within
each logical group.
For example, the following command requires two parameters, which can be either
the pair param1 and param2, or the pair param3 and param4.
MyCommand {param1 param2} | {param3 param4}
In the next example, the command requires two parameters. The first parameter can
be either param1 or param2 and the second can be either param3 or param4:
MyCommand {param1 | param2} {param3 | param4}
In the next example, the command can accept either two or three parameters. The
first parameter must be param1. You can optionally include param2 as the second
parameter. And the last parameter is either param3 or param4.
MyCommand param1 [param2] {param3 | param4}
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Preface | xxi
Connecting with TIBCO Resources
How to Join TIBCOmmunity
TIBCOmmunity is an online destination for TIBCO customers, partners, and resident
experts. It is a place to share and access the collective experience of the TIBCO
community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To
register, go to http://www.tibcommunity.com.
How to Access TIBCO Documentation
You can access TIBCO documentation here:
http://docs.tibco.com
How to Contact TIBCO Support
For comments or problems with this manual or the software it addresses, contact TIBCO
Support as follows.
• For an overview of TIBCO Support, and information about getting started with
TIBCO Support, visit this site:
http://www.tibco.com/services/support
• If you already have a valid maintenance or support contract, visit this site:
https://support.tibco.com
Entry to this site requires a user name and password. If you do not have a user name,
you can request one.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
xxii | Connecting with TIBCO Resources
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 1
271
Chapter 1 Introduction
This book provides information on configuring an adapter instance, using adapter
features, and deploying the adapter to the runtime environment.
Topics
• Overview, page 2
• Configuration, page 4
• Deployment, page 9
• Adapter Project Lifecycle, page 11
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
2 | Chapter 1 Introduction
Overview
TIBCO ActiveMatrix Adapter for Database 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, Microsoft SQL Server, MySQL,
and Teradata are supported. While the adapter does not run on z/OS and iSeries systems, it
can remotely connect to a DB2 database running on these systems.
Features
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 73.
— 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 74.
— Publish on parameterized subjects or destinations, which allows a subject or
destination to be created from the contents of one or more table columns. See
Parameterized Subject or Destination Names on page 164.
— Preregister certified subscribers with a certified publisher. See Preregistering a
Certified Subscriber on page 167.
— 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 65.
— Specify that a group of rows fetched from the publishing table is sent in a single
message.
The subject names mentioned in this document are referred to as subject names when
using the TIBCO Rendezvous transport type, but are referred to as destination names
when using the JMS (Java Messaging Service) transport type.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 3
• Automatically subscribe to data and insert, update or delete the data in pre-specified
tables in a database:
— Subscribe using wildcard subject names. See Preregistering a Certified Subscriber
on page 167.
— Perform batch commits based on message count or time out value. See Adapter
Instance Tabs on page 34.
— Subscribe a group of rows set in a single message. You can configure the adapter
to update all rows in a single database transaction by turning on the Enable Group
Message Transaction Support option. See Subscriber Options Tab on page 82.
• 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 139.
• 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 114 and RPC Mode on page 122.
• Change published messages for a publication or subscription service by customizing
the supplied callout library. See User Callout Library on page 179.
• Customize adapter behavior to suit your needs:
— Specify relationships between tables, then publish related tables together. See
Tables Tab on page 62.
— Monitor for database changes using periodic polling or notification by an alerting
mechanism. See Adapter Services Tab on page 43.
• Rely on standards:
— Connect to multiple database vendors using ODBC or JDBC drivers. See
Design-time Connection Tab on page 37 and Table 8, Runtime Connection Tab, on
page 41.
— Interoperate with other TIBCO products through the use of TIBCO Adapter SDK
software. See Sending Messages to an Adapter Instance on page 170.
— Monitor your adapter service using TIBCO Hawk software. See Monitoring Tab on
page 55 and Chapter 11, Monitoring the Adapter, on page 233.
— Choose message transports: TIBCO Rendezvous or JMS (Java Messaging
Service).
• Configure the adapter easily using TIBCO Designer. See Chapter 3 on page 25.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
4 | Chapter 1 Introduction
Configuration
TIBCO Designer, the design-time component, is an easy-to-use graphic user interface.
The TIBCO ActiveMatrix Adapter for Database palette in TIBCO Designer is used to
create adapter instances, configure adapter services, download schemas, and save the
resulting configuration in a project.
Before using TIBCO Designer, make sure you read the TIBCO Designer product
documentation.
The following figure shows the TIBCO Designer interface.
Figure 1 TIBCO Designer Main Window
Project Panel
Each TIBCO Designer window contains one and only one project, which is represented as
the root folder in the panel.
Design
Configurationpanel
Menu bar
Projectpanel
panelPalette
panel
Tool bar
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Configuration | 5
Projects are the key organizational principle for the configuration information you specify.
A project is a collection of all configured resources. Resources are the components of a
project. For example, an adapter publication service is a resource. Resources can be
complex and contain other resources, much like a folder can contain other folders on your
computer file system. Together, these resources make up your integration project. The
top-level (root) folder in the project tree panel represents a project. The top-level folder is
initially named Untitled and is renamed to the name of the project when you save the project
for the first time.
Most adapter resources have context-sensitive help available for the configuration of that
resource. Right-click on the resource and choose What Is This? from the popup menu for
more information on configuring the resource.
An adapter project contains the following folders:
• AESchemas Folder
The AESchemas folder is the default location for all TIBCO ActiveEnterprise schema
files. Each schema file contains a collection of classes, scalars, associations, unions,
and sequences.
• Adapter Services Folder
The Adapter Services folder contains services available to the adapter. Most adapters
include publication, subscription, request-response, and request-response invocation
services.
• Advanced Folder
The Advanced folder contains resources created by TIBCO Designer while the adapter
is configured. For example, each time you add a service to an adapter, a session and
endpoint are created and stored in the Advanced folder. Other resources such as
advanced logging resources are accessed directly from the folder. Adapter developers
typically do not access resources in this folder. Most of the adapter configuration is
done by changing resources that are available from the Adapter Services folder.
Palette Panel
Palettes organize resources and allow you to add them into your project. Palettes are
available from the palette panel in TIBCO Designer. Resources are visible components in
a palette. You select resources in the palette panel and drag-and-drop them into the design
panel to add them to your project.
Each adapter you install adds one or more palettes during installation. Which palette is
displayed depends on the resource selected in the project tree and on your preferences. In
the default view, the current selection in the project tree determines which palettes are
displayed in the palette panel.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
6 | Chapter 1 Introduction
Design Panel
The design panel displays the current resource selected in the project tree panel. For
resources that contain other resources, the contents of the selected resource are shown in
the design panel. For example, if you select a folder, its contents are displayed.
Configuration Panel
The configuration panel allows you to specify configuration options for the selected
resource. The type and the purpose of the resource determine the contents of the
configuration panel. There are usually one or more tabs in the configuration panel that
allow you to access the various configuration options. The tabs provide an organization to
the options for the resource.
You can click the question mark icon (?) in the top right corner of the configuration panel
for online help on the current selection.
For each tab, you must click the Apply button after you have specified configuration
information before you can select another tab. If you decide you do not want to add the
configuration information, click the Reset button before you apply any changes to return
to the previous values for each field in the tab.
Projects
A project is a named collection of data, usually schema data, and configuration data that is
persistently stored. Each project is opened and saved in multi-file format, which allows
the project to be used with a version control system. It allows different developers to
collaborate on a project and merge changes as needed.
When a project is ready to be deployed, it can be created or exported in the following
formats:
• Enterprise Archive File
• Local Repository
• Server Repository
• ZIP Archive
Enterprise Archive File
An Enterprise Archive file contains information about the adapter instances and processes
you wish to deploy. The format is used by TIBCO Administrator. The EAR file is
imported into Administrator where you can deploy, start, and manage the adapter instance
on the machines of your choice.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Configuration | 7
Local Repository
A project exported to a local repository is saved in .dat format. Projects saved in .dat format
should only be used for development and testing. The format can be used where data is not
shared by more than one adapter. It is possible to have a few local adapters accessing a
local project in read-only mode. It is, however, not possible to have more than one local
adapter accessing a local project in read and write mode.
Data are loaded at startup for local projects, so a local project has higher memory
requirements.
Server Repository
A project exported to a server repository is managed by a TIBCO Administration Server
running in a separate process, typically elsewhere on the network. One or more adapters
can communicate with a project managed by an Administration Server. Each can support
multiple projects.
An Administration Server is identified by a name that must be unique among all
administration servers on a network. The server-based mode of operation is scalable and
generally recommended for production situations. Server repositories allow multiple
simultaneous write operations with locking, automatic updates of clients, and notification.
Data are loaded on demand for server-based projects.
ZIP Archive
A project exported to a ZIP archive is written to the location you specify as a read-only
ZIP file. A project exported as a ZIP archive can be imported into TIBCO Designer.
Version Control
TIBCO Designer allows multiple developers to work on the same project and to use file
sharing (locking) or a version control system so that the same resource is not changed by
two developers at the same time. Different users can then add resources to the project and
lock the parts of the project they are working on.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
8 | Chapter 1 Introduction
TIBCO Designer creates a file that can be shared and locked for each top-level resource,
such as an adapter configuration. It does not create a file for each resource. As a result, for
example, you can lock an adapter configuration but cannot lock individual adapter
services.
When an adapter service is configured, the adapter creates a corresponding set of schema
files. A warning is displayed when the files are created advising you to add the files to
your version control system. You must add the files to your version control system and
ensure they are checked-in, otherwise your project will not be managed correctly by the
version control system.
TIBCO Designer also creates folders for folders you create in your project. You can lock
each folder as needed.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Deployment | 9
Deployment
After an integration project has been developed and tested, it is necessary to deploy the
runtime components to the machines on which they will ultimately run in a production
environment. An adapter instance can be deployed, started and managed using TIBCO
Administrator from the Administrator web browser.
Using TIBCO Administrator, you can upload the EAR, deploy the adapter on the
machine(s) of your choice, and set runtime options before deployment. Additionally you
can start and stop the adapter using TIBCO Administrator.
TIBCO Administrator also provides built-in tools to monitor and manage the adapter.
TIBCO Administrator provides user, resource, and application management modules for
adapters.
• User Management. This module allows you to set permissions for adapter users. You
define authentication, users and groups, and assign access control lists to users. This
includes security for server-based projects at design time and for deployed
applications at runtime.
• Resource Management. This module allows you to monitor machines and all
running applications in a TIBCO administration domain. Alerts can be created, for
example, to notify an administrator if the number of processes or disk usage exceed a
certain number.
• Application Management. This module allows you to upload Enterprise Archive
(EAR) files, and create, configure, and deploy adapters. This console is also used to
start and stop adapters.
TIBCO Administration Domain
A TIBCO administration domain is installed only if you have also installed the User
Management module.
A TIBCO administration domain is a collection of users, machines, and components that
an administration server manages. There is only one Administration Server for each
administration domain. Components within an administration domain can communicate
with systems outside of the domain, but the domain is the administrative boundary of your
enterprise integration project.
.See the TIBCO Administrator product documentation for more information.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
10 | Chapter 1 Introduction
TIBCO Administration Server
The TIBCO Administrator Server provides a central storage and distribution point for
configuration data and schema data needed by an adapter. The server is included in both
Administrator editions.
Each administration domain has one and only one TIBCO Administration Server. The
TIBCO Administration Server is the machine process that handles the stored project and
requests to manage the TIBCO administration domain.
The TIBCO Administrator Server contains its own web server (Apache Tomcat) that can
be accessed via the TIBCO Administrator GUI for configuration and monitoring
information.
TIBCO Administrator GUI
You can access the TIBCO Administration Server using the web-based TIBCO
Administrator GUI. The GUI allows you to create users and assign access to projects
managed by the Administration Server. You can invoke the GUI from any machine in a
TIBCO administration domain. The next diagram shows the GUI.
Figure 2 TIBCO Administrator GUI
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Adapter Project Lifecycle | 11
Adapter Project Lifecycle
This section describes the high-level steps required to configure and deploy an adapter.
Each of these steps are described in details in subsequent chapters. Adapter projects are
configured using TIBCO Designer.
Configuration
Task A Configure the Vendor Application to work with the Adapter
This task is completed as part of installing the adapter and before configuring an adapter
instance for the first time.
Task B Define an Adapter Project
When starting TIBCO Designer, you create or select a project. A project contains adapter
configuration information, such as the service and messaging transport to use, logging
options, and other specific settings. A project is opened and saved in multi-file format,
which allows a version control system to manage the files associated with the project.
See Adapter Instance Tabs on page 34 for more information.
Task C Set Global Variables
By default each project you create in TIBCO Designer includes several global variables.
Global variables provide an easy way to set defaults for use throughout your project.
Default values are predefined for some of the variables. You can define additional
variables and, optionally, set their values when configuring your adapter.
When the project is deployed and the configured adapters are run, all occurrences of the
global variable name are replaced with the global variable value.
A global variable value set in TIBCO Designer can be overridden at runtime by redefining
the value in TIBCO Administrator.
See Using Global Variables on page 30 for more information.
Task D Configure an Adapter Service
The adapter supports the following services: publication, subscription, request-response,
and request-response invocation.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
12 | Chapter 1 Introduction
Task E Test the Adapter Configuration
The adapter tester can be used to verify an adapter service after it has been configured.
When invoked, all adapter services configured in the project are displayed. You select the
adapter service to test, and start and stop the adapter from the tester. The tester window
displays adapter output within the tool so you can easily view results.
Deployment
During development, you save your design to a project. When you are ready to deploy
your project to a machine, you generate an Enterprise archive file (EAR file) from TIBCO
Designer. The EAR file contains information on what you wish to deploy
Task F Generate and Import an Enterprise Archive File
An Enterprise Archive file contains adapter instance configuration information, which is
used by a runtime adapter. An Enterprise Archive file is generated using TIBCO Designer
and imported into TIBCO Administrator.
See Create an EAR File in TIBCO Designer on page 92 for more information.
Task G Specify Deployment Information
After importing an Enterprise Archive file, the adapter can be deployed. This involves:
• Assigning adapter services to the machines in the administration domain.
• Specifying startup options for each process engine and adapter service.
See Deploy the Project on page 93 for more information.
Task H Specify Monitoring Options
Before starting the adapter you can optionally specify monitoring options, including:
• Specifying alerts or TIBCO Hawk rulebases for each machine.
• Specifying alerts and TIBCO Hawk rulebases for an adapter service.
• Setting log file properties for an adapter service instance.
Task I Start the Adapter
The adapter is started and stopped using the TIBCO Administrator GUI.
See Start or Stop the Adapter on page 94 for more information.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 13
Chapter 2 Getting Started
This chapter helps you get familiar with the adapter by walking you through a basic
exercise. Work through the exercise to get a hands-on understanding on how the adapter
works.
Topics
• Overview, page 14
• Create the Database Tables, page 17
• Configure the Properties File, page 18
• Start the Adapter Services, page 20
• Change the Table Values and Receive Notification, page 21
• Exit the Query Tool and Adapters, page 23
• Clean Up, page 24
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
14 | 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 ActiveMatrix Adapter for Database. 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 TIB_ADADB_HOME\demo\demo2 directory.
Before Starting
Before performing this exercise, make sure that TIBCO ActiveMatrix Adapter for
Database is installed according to the procedures in the TIBCO ActiveMatrix Adapter for
Database Installation.
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 runtime adapter. The TIBCO Designer User’s
Guide is available from TIBCO Designer by selecting Help > Designer Help.
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 ActiveMatrix Adapter for Database will update with
the new data.
• Exception table to which TIBCO ActiveMatrix Adapter for Database will write any
errors that occur during subscription.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 15
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 3 Diagram of Publish-Subscribe Steps
Tasks
This exercise consists of the following tasks:
• Create the Database Tables, page 17
• Configure the Properties File, page 18
• Start the Adapter Services, page 20
• Change the Table Values and Receive Notification, page 21
Source
Table
TIBCO Messaging
Adapter
PublisherAdapter
Subscriber
Publishing
Table
Destination
Table
Exception
Table
Insert Trigger
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
16 | Chapter 2 Getting Started
• Exit the Query Tool and Adapters, page 23
• Clean Up, page 24
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 3 on page 16) 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 service7
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 3 Values to Use for TIBCO Rendezvous and JMS Transport Types
ItemTIBCO Rendezvous Transport Value
JMS Transport Value
Source Table ORDER_TABLE ITEM_TABLE
Publishing Table PUB_ORDER PUB_ITEM
Destination Table SUB_ORDER SUB_ITEM
Exception Table SUB_ORDER_EXCEP SUB_ITEM_EXCEP
Publisher Adapter rvpub jmspub
Subscriber Adapter rvsub jmssub
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Create the Database Tables | 17
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 TIB_ADADB_HOME\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/password@dbService @demo1_ora.sql
The script creates the items and displays the status. For example:
TIB_ADADB_HOME\demo\demo1>sqlplus karlh/karlh@ORCL @demo1_ora.sql
SQL*Plus: Release 8.1.7.0.0 - Production on Tue Aug 10 13:10:48 2004
(c) Copyright 2000 Oracle Corporation. All rights reserved.
Connected to:
Personal Oracle8i Release 8.1.7.0.0 - Production
With the Partitioning option
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 ActiveMatrix Adapter for Database Configuration and Deployment
18 | 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. See Table 3 on page 16.
2. Open the publisher adapter file and set the following values for your environment.
For example:
TIB_ADADB_HOME\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.
.
.
# Change these settings for your login and dsn for Demo1
adb.user karlh
adb.password karlh
adb.dsn Oracle001
.
.
.
Property Value
adb.user username Use the database account name used by the adapter instance.
This is the same username entered during TIBCO
ActiveMatrix Adapter for Database post installation
procedure when creating a database account for the adapter.
adb.password pwd Use the database account password used by the adapter
instance. This is the same password entered during TIBCO
ActiveMatrix Adapter for Database post installation
procedure 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 data source Use the name of the ODBC system data source for the adapter.
The data source is configured as a post installation procedure.
See the TIBCO ActiveMatrix Adapter for Database
Installation for more information.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Configure the Properties File | 19
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 repeat the changes you made in step 2.
6. Save and close the subscriber adapter file.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
20 | Chapter 2 Getting Started
Start the Adapter Services
You can use TIBCO Rendezvous or TIBCO Enterprise Message Service as the message
transport.
1. If you are using TIBCO Rendezvous transport, skip this step and proceed to step 2.
If you are using JMS transport, open a command window and change directory to the
TIBCO Enterprise Message Service bin directory and start the server. Note that this
step is not required if the server is running as a service on Microsoft Windows. For
example:
cd TIBCO_HOME\ems\bin
> tibemsd
2. Open a new command window and change directory to the adapter bin directory. For
example:
> cd TIB_ADADB_HOME\bin
3. In separate command windows, start the publisher and subscriber adapters for your
database.
If using TIBCO Rendezvous:
> adbagent --propFile
TIB_ADADB_HOME\demo\demo1\rvpub.tra
> adbagent --propFile
TIB_ADADB_HOME\demo\demo1\rvsub.tra
If using TIBCO Enterprise Message Service:
> adbagent --propFile
TIB_ADADB_HOME\demo\demo1\jmspub.tra
> adbagent --propFile
TIB_ADADB_HOME\demo\demo1\jmssub.tra
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Change the Table Values and Receive Notification | 21
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 TIB_ADADB_HOME\demo\demo1
2. Invoke the query tool using the environment-specific user ID, password, and database
service specified in Create the Database Tables, page 17.
> sqlplus userid/password@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 Message Service:
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 ORDER_TABLE;
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 Message Service:
SQL> select * from ITEM_TABLE;
The following example result confirms that the data has been inserted:
ITEM_ID
----------
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
22 | 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 ActiveMatrix Adapter for Database Configuration and Deployment
Exit the Query Tool and Adapters | 23
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 Message Service:
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 ActiveMatrix Adapter for Database Configuration and Deployment
24 | 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 TIB_ADADB_HOME\demo\demo1\
2. Execute the appropriate demo_cleanup.sql script in the subdirectory.
> sqlplus userid/password@dbService @demo1_cleanup_databasevendor.sql
For example:
> sqlplus karlh/karlh@ORCL @demo1_cleanup_ora.sql
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 25
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 runtime adapter.
Topics
• Overview, page 26
• Adapter Instance Tabs, page 34
• Configuration Tab, page 35
• Design-time Connection Tab, page 37
• Runtime Connection Tab, page 41
• Adapter Services Tab, page 43
• General Tab, page 47
• Logging Tab, page 49
• Startup Tab, page 54
• Monitoring Tab, page 55
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
26 | 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 Task Sequence, page 26
• Saving the Project, page 27
• Testing the Adapter, page 27
• Notes on Configuring an Adapter, page 27
• Configuration Recommendations, page 28
• Changing an Existing Configuration, page 29
Configuration Task Sequence
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
documentation 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 35.
4. Define and test the design-time connection options for the instance. See Design-time
Connection Tab on page 37.
5. Either now or when the instance is ready to deploy, define and test the runtime
connection options for the instance. See Runtime Connection Tab on page 41.
6. As necessary, modify the following default values for the instance:
— Default startup state and session, metadata search URL: see Startup Tab on page 54
— Standard, class, and default MicroAgents: see Monitoring Tab on page 55
— Logging options: see Logging Tab on page 49
— Termination subject, encoding, and debugging options: see General Tab on page 47
— Threads, polling, publishing child data, bulk insert size, TIBCO Rendezvous queue
size, exception table: see Adapter Services Tab on page 43
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 27
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 runtime adapter property file and add the project
name and adapter instance name.
Also define and test the runtime connection options for the instance if you did not do it
earlier. See Runtime Connection Tab on page 41.
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.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
28 | Chapter 3 Adapter Instance Options
• A database account must have been created for running the adapter. For details, see
the TIBCO ActiveMatrix Adapter for Database Installation.
• 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.
• 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 Runtime Connection Tab on page 41). You can also build a
TIBCO Hawk rule to restart the adapter instance after the database is restarted.
• To start or stop an adapter instance see Start or Stop the Adapter on page 94.
• 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 ActiveMatrix
Adapter for Database:
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 29
• 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.
• For the limitations that apply to parameterized subject names and destination names,
see Parameterized Subject and Destination Name Restrictions on page 164.
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:
• 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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
30 | Chapter 3 Adapter Instance Options
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 Deployment and Cleanup Scripts on page 194.
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.
• 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 32.
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 ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 31
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.
— Click the pencil icon to open the advanced editor where you can add more
information to a global variable.
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
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
32 | Chapter 3 Adapter Instance Options
overridden in a way that had higher precedence). For example, RvServiceTest would be
replaced with 7800.
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 4 Predefined Global Variables (Sheet 1 of 2)
Variable Description
Deployment Defaults to the TIBCO Designer project name. This value can be
any string value. This global variable is used by the system to
partially define the subject name defined for a service.
DirLedger Specifies the path name of the TIBCO Rendezvous certified
messaging ledger file. The default is the root installation directory.
DirTrace Specifies the path name for log file used by the adapter. The default
is the root installation directory.
Domain The default value for file-based local projects is Domain. The value
for server-based projects is the domain to which the project was
saved.
JmsProviderUrl Tells applications where the JMS daemon is located. Setting this
value mostly makes sense in early stages of a project, when only
one JMS daemon is used.
JmsSslProviderUrl Tells applications where the JMS SSL daemon is located.
RemoteRvDaemon TIBCO Rendezvous routing daemon (rvrd) to be used. See TIBCO
Administrator Server Configuration Guide for details about setting
up a domain using rvrd.
RvDaemon TIBCO Rendezvous daemon. Sessions use this daemon to establish
communication. The default value is 7500.
RvNetwork TIBCO Rendezvous network. This variable need only be set on
computers with more than one network interface. If specified, the
TIBCO Rendezvous daemon uses that network for all outbound
messages.
In most cases, you can leave the default.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 33
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.
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.
Table 4 Predefined Global Variables (Sheet 2 of 2)
Variable Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
34 | Chapter 3 Adapter Instance Options
Adapter Instance Tabs
The following tabs are available when configuring an adapter instance.
• Configuration Tab
• Design-time Connection Tab
• Runtime Connection Tab
• Adapter Services Tab
• General Tab
• Logging Tab
• Startup Tab
• Monitoring Tab
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Configuration Tab | 35
Configuration Tab
You must define the options on the Configuration tab before other options can be
configured. Click Apply to apply the changes before leaving the Configuration tab. Table
5, Adapter Instance Configuration, on page 35.
Table 5 Adapter Instance Configuration
Field Description
Instance Name This is the name that was specified when creating the adapter configuration.
See Guidelines for Choosing an Instance Name on page 36 for more information.
Description A short description of the adapter configuration.
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 fro1 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.
• If a 4.x adapter instance is to be run with a 4.x runtime 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. runtime adapter and use the
validation utility to verify the instance before deploying the project. Invoke
the utility by selecting Project > Validate Project For Deployment 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 Select 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
dat.
In the drop-down list, vendor names enclosed in parenthesis are not supported.
For example Informix and INGRES.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
36 | Chapter 3 Adapter Instance Options
Guidelines for Choosing an Instance Name
• 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, an ADB adapter
instance named TEST and a 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.
DB2 AS400 Library (Appears when DB2 AS400 is selected in the Vendor field.) When this option is
selected, the adapter automatically creates an asynchronous queue named
TIBADB on the AS400 machine. Your programs will be created in TIBCOSRC in
the library specified in the DB2 AS400 Library field.
You must also set the trigger option under the publication service DB2/AS400
Options tab.
Convert Number Data Type
to String(Appears when Oracle is selected in the Vendor field.) When this option is
selected, the adapter will use string operation for number data type at runtime.
Write to Database on Save Select this box if you want to write configuration settings to the database when
this project is saved. This is the default mode.
Table 5 Adapter Instance Configuration (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Design-time Connection Tab | 37
Design-time Connection Tab
You must define the JDBC information and database account options in the Design-time
Connection tab before you can design the adapter instance.
After completing these fields, click the Apply button, then click the Test Connection
button to establish a connection to the database. When the connection is successful message
appears, click the OK button. 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.
Table 6 Design-time Configuration Parameters
Field Description
JDBC Driver 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.
See Table 7, JDBC Drivers and URLs, on page 38 for the supported JDBC Drivers and
the associated URLs
JDBC URL
User Name The database user that the design-time adapter uses to connect to the database.
Password The password for the database user.
Remember Password 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%%.
Use Design-time Connection
For Runtime
This field is not used.
Test Connection Click this button to test the connection using the specified parameters.
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 Using Connection Settings Templates on page 39.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
38 | Chapter 3 Adapter Instance Options
Table 7 JDBC Drivers and URLs
Database Driver and URL
Oracle JDBC Driver: tibcosoftwareinc.jdbc.oracle.OracleDriver
JDBC URL: jdbc:tibcosoftwareinc:oracle://server_name: 1521;SID=ORCL
Microsoft SQL
Server
JDBC Driver: tibcosoftwareinc.jdbc.sqlserver.
SQLServerDriver
JDBC URL: jdbc:tibcosoftwareinc:sqlserver://
server_name:1433;databaseName=database_name
Note: Default port number is 1433.
Sybase JDBC Driver: tibcosoftwareinc.jdbc.sybase.SybaseDriver
JDBC URL: jdbc:tibcosoftwareinc:sybase://server_name:
5000
Note: Specify a database_name parameter (as shown in the SQL Server
description above) if connecting to a database that is not the default database.
Sybase
Adaptive
Server
Anywhere
JDBC Driver:com.sybase.jdbc2.jdbc.SybDriver
JDBC URL: jdbc:sybase:Tds:localhost:2638/asademo
MySQL JDBC Driver: com.mysql.jdbc.Driver
JDBC URL: jdbc:mysql://server_name:3306/database_name
Teradata JDBC Driver: com.teradata.jdbc.TeraDriver
JDBC URL: jdbc:teradata://server_name
DB2 OS390 JDBC Driver: tibcosoftwareinc.jdbc.db2.DB2Driver
JDBC URL: jdbc:tibcosoftwareinc:db2://server_name:port;
locationName=DB2_location_name;packageName=package_name_prefix
DB2 AS400 JDBC Driver: com.ibm.as400.access.AS400JDBCDriver
JDBC URL: jdbc:as400://server_IP;libraries=lib
DB2 UDB JDBC Driver: tibcosoftwareinc.jdbc.db2.DB2Driver
JDBC URL: jdbc:tibcosoftwareinc:db2://server_name:
50000;databaseName=database_name;packageName=DEF00
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Design-time Connection Tab | 39
Using Connection Settings Templates
TIBCO ActiveMatrix Adapter for Database provides connection settings 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 Settings for Reuse
After you have customized the connection settings 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 ActiveMatrix Adapter for Database Configuration and Deployment
40 | Chapter 3 Adapter Instance Options
3. Type a name, then click the OK button. The following dialog displays:
4. Click either Yes or No button:
— 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 ActiveMatrix Adapter for Database Configuration and Deployment
Runtime Connection Tab | 41
Runtime Connection Tab
The settings available in the Runtime Connection tab must be configured before you start
the runtime adapter.
After configuring these settings, click the Apply button, then click the Test Connection
button to establish a connection to the database. When the connection is successful message
appears, click the OK button. The runtime adapter is now configured.
Table 8 Runtime Connection Tab
Field Description
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.
User Name This is the database user that the runtime adapter uses to connect to the database. This
field is automatically populated when you select a template as described in Using
Connection Settings Templates on page 39. 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 Settings Templates on page 39.
It cannot be changed here.
Default Schema This is the schema name of the current user. Usually it is the same as the username, but
can be different, for example, when using Microsoft SQL Server. For Teradata database,
the Default Schema must be the name of the database you want to connect to.
Database Disconnection
Codes
Specify the database disconnection codes provided by your database. Multiple codes can
be entered if each is separated by a semi-colon (;). No spaces are allowed between codes.
To populate this field with the default disconnection codes for your database, click
ActiveDatabase > Connection Templates > database_name.
If disconnection codes are not provided and a database operation fails, the adapter issues
a test query to verify whether the database connection is valid. If the connection is not
valid, the adapter attempts to reconnect and will shutdown if it cannot reconnect. This
approach is database independent, but affects performance because the adapter has to
send the query and wait for results.
If database disconnection codes are provided in this field, they are stored in a fatal error
code dictionary. When a database operation fails, most database systems return an error
code to the adapter. The adapter can look up the returned error code in the fatal error
code dictionary and determine if the database connection is lost and respond
accordingly. This is more efficient then sending the test query.
When using ODBC native driver to reconnect on DB2/UDB, add the database
disconnection code -30081 manually. For Oracle database, the disconnection code is
30046.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
42 | Chapter 3 Adapter Instance Options
Maximum Number of
Reconnect Attempts
The total number of reconnection attempts to make after the service has been suspended.
When this number is reached, the runtime 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.
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 used.
Table 8 Runtime Connection Tab (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Adapter Services Tab | 43
Adapter Services Tab
You are not required to change any settings in the Adapter Services tab. The settings
available in this tab 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 the Apply button to apply the changes before leaving this tab.
All Publication Services
The settings available in the All Publication Services panel apply to all Publication
services in the adapter.
Table 9 Publication Service Configuration Options
Field Description
Number of Publication
Service Threads
This field is currently disabled. Threads are allocated on demand. For example, if the
adapter instance has only a publication service configured, a publication thread and
database connection will be created automatically.
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. Note that if you specify a polling interval of 0, it is assumed
that you are using an alerter to manage polling.
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. For example, when polling a large number of
rows, the adapter works best if a fixed number of rows is specified in this field.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
44 | Chapter 3 Adapter Instance Options
Publisher Batch Confirm Size (Applies only to adapters with a publication service that uses certified message delivery.
Do not use this option when messages are published using a parameterized subject
name.)
The number of message status updates to include in a single batch.
Entering a value in this field optimizes performance. However, if an adapter stops before
a batch update is performed, the status column is not updated. As a result, messages that
were successfully published might still have a status of P (pending) in the publishing
table when the adapter is restarted. In this case, the ledger file contains the correct status
information. Smaller values in this field decrease this risk.
Publisher Batch Confirm
Timeout
(Applies only to publisher adapters with publications that use certified message delivery.
Do not use this option when messages are published using a parameterized subject
name.)
The number of milliseconds to wait before updating the status column. After this
interval, an update is performed even if the batch size value is not reached. The default
value is 10000 (10 seconds). A value of 0 means that no timeout interval is used.
If an adapter instance stops before a batch update is performed, the status column is not
updated. As a result, messages that were successfully published might still have a status
of P (pending) in the publishing table when the adapter is restarted. In this case, the
ledger file contains the correct status information. Smaller interval values decrease this
risk.
Publish Child Data This is selected by default. When selected, the parent row and all related child rows is
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.
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 65. For
information on adding related tables for a subscriber adapter, see Child Table Mappings
Tab on page 80.
Polling Commit for DB2 Select to enable the adapter publisher to do a commit after selecting query for DB2.
Table 9 Publication Service Configuration Options (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Adapter Services Tab | 45
All Subscription Services
The settings available in the All Subscription Services panel apply to all subscription
services in the adapter.
Considerations when using the Subscriber Bulk Insert Size parameter:
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.
Table 10 Subscription Service Configuration Options
Field Description
Number of Subscription
Service Threads
This field is currently disabled. Threads are allocated on demand. For example, if the
adapter instance has only a subscription service configured, a subscription thread and
database connection will be created automatically.
Subscriber Batch Commit
Size
The number of messages to batch before invoking a commit operation. The default value
is 0.
Subscriber Batch Commit option is not supported with RVCMQ Quality of Service. The
RVCMQ scheduler requires a message to be confirmed before dispatching the next
message, which prevents the adapter from operating in batch mode.
Subscriber Batch Commit
Timeout (milliseconds)
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.
When using RVCMQ, subscriber batch commit will timeout after each operation
(insert/update/delete) when batch commit size>1.
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.
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 Select this box to use an exception table. The exception table is defined when you create
a subscription service.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
46 | Chapter 3 Adapter Instance Options
• 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.
All Request-response Services
The settings available in the All Request-response Services panel apply to all
request-response services in the adapter, unless the individual service is configured
differently.
Table 11 Request-response Service Configuration Options
Field Description
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.
Request Response max Rows Specify the maximum number of rows to fetch. This can be used limit the memory usage
of the adapter. The unfetched rows will be ignored by the adapter.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
General Tab | 47
General Tab
The General 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 the Apply button to apply the changes before leaving the General tab.
Table 12 General Configuration Options
Field Description
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 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 Message Service User’s Guide for information about publishing
on a topic.
JMS Destination Prefix Specify this prefix if you are using the JMS transport and have selected the Use Separate
Service Thread option for a subscription service. The destination prefix is the subject used
by the single-threaded subscription service.
By default, the adapter uses a dynamic destination that is generated using the Domain
and Deployment global variables, and the adapter instance name. If you use this default
dynamic destination, make sure the values for Domain and Deployment are not empty.
You can override the default dynamic destination by specifying the static destination in
this field. The static destination must be defined with write permissions on the TIBCO
Enterprise Message Service server before it can be used by the runtime adapter.
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 runtime
adapter will throw an error if the encoding value you type is not supported.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
48 | Chapter 3 Adapter Instance Options
Debug Level This field is valid only when the Debug logging option is selected, as described in
Logging Tab on page 49.
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 with the database
Only the ODBC data source for each SQL command
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 49.
Check this box to include verbose output (all available information) at the console
window or log file location specified in the Log File field.
Generate Payload on Error Allows the adapter to log the payload information under Error role when an error occurs.
Script File Allows you to change the location where the SQL script file is written.
Alerter Name The name of the alerter service register in the database.
Table 12 General Configuration Options (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Logging Tab | 49
Logging Tab
Use the settings available in the Logging tab to configure a log file or log sinks, including
which types of trace messages you want logged and where they are sent. Click the Apply
button to apply the changes before leaving the Logging tab.
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.
Table 13 Logging Configuration Options
Field Description
Use Advanced Logging When this box is clear, the standard log file is used. This is the default. Fill out the
remaining fields on this tab. You do not need to read the rest of this field description.
When this box is selected, you can set two standard output destinations (sinks) for trace
messages and set the tracing level for the roles selected. The following sink types are
available:
• File
• STDIO
• Hawk
• Network
See Creating Log Sinks on page 51 for more information.
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 30 for more information.
Type the name and file system path, or click the Browse button 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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
50 | Chapter 3 Adapter Instance Options
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.
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.
By default, the Use Advanced Logging checkbox is not checked. In this mode, you
configure a standard log file using the fields on this tab, as shown in the example below.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Logging Tab | 51
When you check the Use Advanced Logging checkbox, 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.
Creating Log Sinks
1. Check the Use Advanced Logging checkbox.
2. Click the Apply button.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
52 | Chapter 3 Adapter Instance Options
3. In the TIBCO Designer project panel, expand the Log Sinks folder under the
Advanced folder.
4. Select an existing log sink or create a new one:
— Select either the fileSink or stdioSink 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 drop down
menu in the configuration panel. Click the Apply button.
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
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Logging Tab | 53
purposes. Specify the MicroAgent Name. (For details on Hawk sessions, see Using
Global Variables on page 30.)
— 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 ActiveMatrix Adapter for Database Configuration and Deployment
54 | Chapter 3 Adapter Instance Options
Startup Tab
Do not change the settings in the Startup tab. This tab displays the default startup
behavior.
Table 14 Startup Options
Field Description
Show Startup Banner The startup banner displays the runtime 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 ActiveMatrix Adapter for Database Configuration and Deployment
Monitoring Tab | 55
Monitoring Tab
The settings available in the Monitoring tab 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 the Apply button to apply the changes before leaving the Monitoring tab.
See Chapter 11, Monitoring the Adapter, on page 233 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.
Table 15 Monitoring Configuration Options
Field Description
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 runtime adapter.
Standard Microagent Timeout Specifies the amount of time the Hawk Agent should wait for HMA method invocations
to complete before timing them out. The default is 10000 milliseconds. Normally there is
no need to change this value, however, on machines under extreme stress where method
invocations are timing out, this new option allows the timeout value to be increased.
Enable Class Microagent Allows you to turn on or off the instance-specific or class-specific standard TIBCO
Hawk Microagent. You can configure how the class microagent is turned on and off in
this field: clicking the globe icon changes the checkbox to a a true/false text field.
Class Microagent Name This is the name for the class microagent that will be registered with the TIBCO Hawk
system. In most cases the default value is used,
COM.TIBCO.adb.%%deployment%%.%%InstanceId%%.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
56 | Chapter 3 Adapter Instance Options
Class Microagent Timeout Specifies the amount of time the Hawk Agent should wait for HMA method invocations
to complete before timing them out. The default is 10000 milliseconds. Normally there is
no need to change this value, however, on machines under extreme stress where method
invocations are timing out, this new option allows the timeout value to be increased.
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.
Table 15 Monitoring Configuration Options (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 57
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 58
• Adding Child Tables, page 65
• Publication Service Tabs, page 61
• Subscription Service Tabs, page 77
• Request-response Service Tabs, page 85
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
58 | Chapter 4 Adapter Service Options
Overview
The transport type (Rendezvous or JMS) you select for the runtime 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 Queue listener objects. Even though many
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 59
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 Adapter Instances on page 134 and TIBCO
ActiveEnterprise Concepts for more information.
• Transactional
This option is no longer supported. The option is only included for backward
compatibility.
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 TIBCO
Enterprise Message Service User’s Guide for more information.
• Persistent
In general, a message marked persistent will be available to a JMS client even if the
TIBCO Enterprise Message Service server goes down. Persistent messages are held in
secondary storage in the 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
A message marked non persistent will not be available to a JMS client if the TIBCO
Enterprise Message Service server goes down. These messages are never written to
persistent storage.
• Durable
(Topic only) Specify the subscriber as durable subscriber of the topic. Messages for
durable subscriptions are stored on the server as long as durable subscribers exist for
the topic.
• Non-Durable
(Topic only) Specify the subscriber as non-durable subscriber of a topic. Non-durable
subscribers only receive messages when they are active. If messages arrive on the
topic when the subscriber is not available, the subscriber does not receive those
messages.
Wire Formats
Services must use the same wire format to exchange data.
• Rendezvous Message (TIBCO Rendezvous transport type only)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
60 | 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 TIBCO Adapter SDK Programmer’s Guide for details about the control
information generated and sent with TIBCO ActiveEnterprise messages.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publication Service Tabs | 61
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 61
• Tables Tab on page 62
• Child Table Order By Tab on page 70
• DB2/OS390 Tab on page 68
• DB2/AS400 Tab on page 69
• Publisher Options Tab on page 72
• Advanced Tab on page 75
Configuration Tab
The wire format for the publication and subscription services must be the same, otherwise
an error will occur.
Table 16 Publication Service: Configuration Tab
Field Description
Name You can use the default name or replace it with a name of your choice.
Transport Type Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime adapter. This
selection determines which options appear in the rest of the Configuration tab.
The transport can be configured to use a trusted store and identity resource for use in SSL (Secure
Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL
configuration field which uses a dialog to perform SSL configuration.
To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the
Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL
configuration options are explained in the online help associated with the session dialog. Click the
question mark to display the online help.
Quality of Service (Only available when TIBCO Rendezvous is selected as the transport type) Select the level of
service that determines how messages are sent. See Quality of Service on page 58 for a description
of these options.
• Reliable
• Certified
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
62 | Chapter 4 Adapter Service Options
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.
Tables Tab
You must set publisher table options before configuring other publisher options.
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 59 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 59 for a description of each mode.
• Persistent
• Non-persistent
Table 16 Publication Service: Configuration Tab (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publication Service Tabs | 63
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 37 tab
must have the proper set of permissions granted. This is described in Referencing an
External Schema on page 64.
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 64.
You can use this icon to add different schema at the parent and child levels.
• Remove Table — Deletes the selected table from the list.
• Re-find Tables from Database — Causes TIBCO Designer to refresh stored table
schema information by retrieving new information from the database.
If a primary key is not defined for a table, the update and delete triggers will not be
generated for the table. To define a primary key for the table, select the User Key column
in a table row. The update and delete triggers will then be defined.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
64 | 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? checkboxes.
Referencing an External Schema
To reference an external schema in TIBCO Designer, the default schema must have the
proper access privileges. These are set in a command line. In the following syntax,
adb_schema refers to the default schema in create_user.sql.
For Oracle, log in as system and grant create any trigger and drop any trigger permissions to the
default schema. For example:
grant create any trigger to adb_schemagrant drop any trigger to adb_schema
Table 17 Publication Service Tables Tab
Field Description
Tables and
Columns
The loaded tables and columns.
indicates a table or child table.
indicates a normal column.
indicates a User Key column.
Type The primitive type.
AE Type The primitive type mapped to an TIBCO ActiveEnterprise type.
User Key Click to define the column as a user key.
Update Trigger Check the box to fire a trigger when an UPDATE statement changes a value in the column.
Use? Click to publish this column when data is changed.
Join To The name of a parent table column to join to for parent-child relationships.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publication Service Tabs | 65
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.
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.
• When parent-child relationships are defined, a subscriber adapter must use the same
repository as the publisher adapter.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
66 | Chapter 4 Adapter Service Options
When you add a child table, TIBCO Designer creates a class object in the repository for
the child table, and an association object for the relationship.
After adding child tables for a subscriber adapter, you create mappings between child
tables on the publisher side and child tables on the subscriber side. For instructions, see
Child Table Mappings Tab on page 80.
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 the OK button.
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.
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 the Apply button.
To enable publishing child table related data, the publisher adapter properties file must
have the adb.publishChildData option set to on.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publication Service Tabs | 67
In the following example, a publication service that publishes newly inserted rows into the
source table is created. Publisher Options Tab on page 72 explains how to configure the
publisher adapter to publish data by value or by reference.
In the following example, a subscription is created such that received data will be inserted
into the SUB_ORDER_DETAILS destination table. All three columns of the destination table
are configured to receive data.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
68 | Chapter 4 Adapter Service Options
The following example shows a child table mapped. The left column (Subscriber Child Table
Name) contains the subscriber child table and the right column (Publisher Child Table Name)
contains the publisher child table.
DB2/OS390 Tab
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.
Table 18 Publication Service DB2/OS390 Tab
Field Description
Database Name Enter the name of the database that you want to put your publisher table in.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publication Service Tabs | 69
DB2/AS400 Tab
This tab appears when the Vendor field in the Adapter Instance Configuration Tab is set to
DB2 AS400.
Trigger Option
• Synchronous (deprecated) — The trigger is written in RPG. When copying from the
source table to the publishing table, the prompt is not returned until all data is written.
• Asynchronous — When copying from the source table, data is inserted into a data
queue and then inserted into the publishing table asynchronously. The prompt is not
blocked, so you can continue working while data is inserted into the publishing table.
Specify values for the following options:
— Number of DataQueue Listeners: The number of prestarted listener jobs.
— Listener Job Queue: The name of the queue on the AS/400 machine where the
listener jobs are submitted.
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_).
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).
Table 18 Publication Service DB2/OS390 Tab (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
70 | Chapter 4 Adapter Service Options
If you select Asynchronous, you must go to the adapter’s Design-time Connection
tab and add ;transaction isolation level=none to the end of the JDBC URL field. For example:
• SQL — The trigger is written in SQL. When copying from the source table to the
publishing table, the prompt is not returned until all data is written.
Sybase Options
This tab appears when the Vendor field in the Adapter Instance Configuration Tab is set to
Sybase.
Check the Overwrite Triggers? checkbox to delete and re-create existing triggers of the
publishing table.
Child Table Order By Tab
This tab allows you to specify the column(s) of an Order By Clause used for each children
table queries. The adapter will return the child table result set in a particular sequence.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publication Service Tabs | 71
Click on a child table name and click the Select Column button.
The Select Child Table Order By Columns dialog box appears.
Select the column(s) for the Order By Clause from the left panel and click the Apply
button. Use the Up and Down buttons to arrange the column order by sequence. To sort in
descending value, select the check box next to the column name.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
72 | Chapter 4 Adapter Service Options
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.
Table 19 Publication Service DB2/AS400 Options Tab
Field Description
Storage Mode For each publisher service, you must specify a Storage Mode: Publish by Value or Publish by
Reference. See Publish by Value on page 73 and Publish by Reference on page 74 for more
information.
• 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.
Publishing Table Name of the database table used to store a copy of data to be published. The table name can be
qualified using the schema.table_name format. 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
Select 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 z/OS because of DB2 on
z/OS feature limitations.
Do Not Generate
Triggers
Select to prevent the generation of triggers. Although this option is not recommended, it allows you
to manually manage the insertion of data into the publishing table.
Use Alerter Select to use the alerter. This option appears only if you are using an Oracle database. See Chapter 6,
Using the Alerter, on page 97 for details.
Enable Group
Messaging
Select to use group messaging. Note that Rendezvous message wire format does not apply for group message.
Group Size Appears only when the Enable Group Messaging is checked. Specify the number of rows to publish
in a single message. Global variables are acceptable.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publication Service Tabs | 73
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 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.
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.
Enable Load
Balancing
Check to use load balancing which enables multiple publisher endpoints to poll and publish changes
of the same source (publisher) table. Set batch polling size before selecting this option.
Mutex Name Appears only when the Enable Load Balancing checkbox is checked. Specify the name for the
mutex table.
Table 19 Publication Service DB2/AS400 Options Tab (Cont’d)
Field Description
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
74 | Chapter 4 Adapter Service Options
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 94.
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.
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 171.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publication Service Tabs | 75
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.
Advanced Tab
This tab allows you to specify values for the following fields:
Table 20 Publication Service Advanced Tab
Field Description
Destination (Only available when JMS is selected as the transport type in the Adapter Instance Configuration
Tab on page 35)
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 TIBCO Enterprise Message Service server. The destination can be static or
dynamic.
See Subject and Destination Names on page 163 for information about specifying destinations.
See TIBCO Enterprise Message Service User’s Guide for more details about destinations.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
76 | Chapter 4 Adapter Service Options
Message Subject (Only available when TIBCO Rendezvous is selected as the transport type in the Adapter Instance
Configuration Tab on page 35)
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 Subject and Destination Names on page 163 for information about specifying subjects.
See TIBCO Rendezvous Concepts for more details about subjects.
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.
Table 20 Publication Service Advanced Tab (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Subscription Service Tabs | 77
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 77
• Table Tab on page 78
• Child Table Mappings Tab on page 80
• Child Exception Table Mappings Tab on page 81
• Subscriber Options Tab on page 82
• Advanced Tab on page 84
Configuration Tab
This tab allows you to specify values for the following fields:
Table 21 Subscription Service Configuration Tab
Field Description
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 Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime 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 ActiveMatrix Adapter for Database Configuration and Deployment
78 | Chapter 4 Adapter Service Options
Table Tab
You must set subscriber table options before configuring other subscriber 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 58 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 59 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 59 for a description
of each mode.
• Persistent
• Non-Persistent
Table 21 Subscription Service Configuration Tab (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Subscription Service Tabs | 79
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 more information see TIBCO ActiveMatrix
Adapter for Database Concepts.
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 ActiveMatrix Adapter for Database Configuration and Deployment
80 | Chapter 4 Adapter Service Options
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 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 64.
Remove Table — Deletes the selected table from the configuration.
Re-find Table from Database — Causes TIBCO Designer to refresh stored table
schema information by retrieving new information from the database.
Allow Key Columns Only — If selected, child columns are joined only to a key
colulmn. If unselected, child columns can be joined to any column.
Columns
Tables and Columns — Lists the table and columns.
Type — Lists the primitive type.
AE Type — Lists the primitive type mapped to an TIBCO ActiveEnterprise type.
User Key — Click to define as a user key.
Use? — Click to enable the column to be updated when a message arrives. Subscribe
only to columns that should be updated. Columns not configured to receive data will
retain their default value. For columns that have been configured to receive data but
do not get updated:
— In the TIBCO Rendezvous wire format, the columns get a NULL value.
— In the TIBCO ActiveEnterprise and XML wire formats, the columns are ignored in
the statement.
Join To — Joins two tables.
Child Table Mappings 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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Subscription Service Tabs | 81
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.
This tab allows you to specify values for the following fields:
Child Exception Table Mappings Tab
Each child table can be configured to use an exception table.
This tab allows you to specify values for the following fields:
Table 22 Subscription Service Child Table Mappings Tab
Field Description
Subscriber Child
Table Name
Displays the child tables that can be mapped. Entries are automatically created when you add child
tables for a subscription service.
Publisher Child
Table Name
Click in this column and type the name of a publisher child table. Prefix the table name with a
database user if your database requires it.
These options are only active when child tables have been specified on the Table Tab.
Table 23 Subscription Service Child Exception Table Mappings Tab
Field Description
Subscriber Child
Table Name
The child tables that can be mapped. Entries are automatically created when you add child tables for
a subscription service.
Publisher Child
Table Name
Click in this column and type the name of a exception child table. Prefix the exception table name
with a database user if your database requires it.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
82 | Chapter 4 Adapter Service Options
Subscriber Options for DB2 on OS/390 (z/OS)
This tab appears when the Vendor field in the Adapter Instance Configuration Tab is set to
DB2 OS390.
Subscriber Options Tab
This tab allows you to specify values for the following:
Table 24 Subsciption Service DB2/390 Options Tab
Field Description
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.
LOB Table Space
Name
The name of the LOB table space name where auxiliary table of the opaque exception table is
located.
Table 25 Subscription Service Subscriber Options Tab
Field Description
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 subscription
service creates it. For details, see Exception Table on page 149.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Subscription Service Tabs | 83
If you are using the JMS transport, you must set the JMS Destination Prefix. See JMS
Destination Prefix on page 47 for details.
Note that:
• All subscription service threads reconnect separately if the database connection is lost.
Use Opaque
Exceptions Table
Check the checkbox to use an opaque exceptions table. The table records each message (entirely)
into a column, along with the error message. A message is logged in the exceptions table if the
subscription service fails to generate records in the destination table or the adapter fails to insert a
message into an exception table.
For DB2/OS390 databases, you must create a Large Objects (LOB) tablespace before using the
opaque exceptions table, which will use the LOB tablespace.
Opaque
Exceptions Table
The name for the opaque exceptions table.
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.
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 58 and Delivery Mode
on page 59 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)
Use Separate
Service Thread
When selected, a new session is created and the service endpoint is moved to this session. The
subscriber batch commit count towards the number of messages processed by all the endpoints of
each session. You can select other subscription service sessions by changing the session reference
field (under the Advanced tab). This allow multiple services to share the same session and
dispatcher.
Enable Group
Message
Transaction
Support
When selected, the group message will be processed within a single transaction by the subscription
service. The adapter will either commit the whole message changes to the database, or none.
Service Bulk
Insert Size
You can set a different bulk insert size for this service. If not set, the service will use the bulk insert
size of adapter instance options.
Table 25 Subscription Service Subscriber Options Tab (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
84 | Chapter 4 Adapter Service Options
• TIBCO Hawk statistics display all subscription service thread information and
operation count.
• Debug messages provide the subscription service thread name in order to distinguish
which message is from which subscription service thread.
• If a subscription service thread encounter fatal errors such as failed to rollback
transaction or failed to update the exception table, the adapter terminates.
• At startup the subscription service dispatchers wait for all component to start before
dispatching subscriber messages.
Advanced Tab
This tab allows you to specify values for the following:
Table 26 Subscription Service Advanced Tab
Field Description
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 TIBCO Enterprise Message Service server. The destination can be static or
dynamic.
See Subject and Destination Names on page 163 for information about specifying destinations.
See TIBCO Enterprise Message Service User’s Guide for more details about destinations.
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 Subject and Destination Names on page 163 for information about specifying subjects.
See TIBCO Rendezvous Concepts for more details about subjects.
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 ActiveMatrix Adapter for Database Configuration and Deployment
Request-response Service Tabs | 85
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 85
• Call Operation Tab on page 87
• Advanced Tab on page 88
Configuration Tab
This tab allows you to specify values for the following fields:
Table 27 Request-response Service Configuration Tab (Sheet 1 of 3)
Field Description
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
86 | Chapter 4 Adapter Service Options
Transport Type Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime 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.
The transport can be configured to use a trusted store and identity resource for use in SSL (Secure
Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL
configuration field which uses a dialog to perform SSL configuration.
To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the
Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL
configuration options are explained in the online help associated with the session dialog. Click the
question mark to display the online help.
Quality of Service Only available when TIBCO Rendezvous is selected as the transport type) Select the level of service
that determines how messages are sent. See Quality of Service on page 58 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 59 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.
Table 27 Request-response Service Configuration Tab (Sheet 2 of 3)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Request-response Service Tabs | 87
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 the New button to enter data into the fields. After making changes, click the Apply
button.
TIBCO Designer retrieves the signature of each stored procedure and function from the
database.
This tab allows you to specify values for the following:
Delivery Mode (Only available when JMS is the transport type) The delivery mode for each message sending
operation. See Delivery Mode on page 59 for a description of each mode.
• Durable
• Non-Durable
Mode Specify if this endpoint will be a Request Reply Server or RPC (Remote Procedural Call) Server.
• Request Reply: A subscriber endpoint will be created. This subscriber will listen to
request and publish the reply to the reply subject.
• RPC: A server endpoint will be created. This server will receive a request from and
send back the reply to the client.
Use Custom
Operations
This checkbox appears when the Mode field is set to RPC. Selecting this checkbox and clicking the
Apply button creates the Call Operation Tab.
Table 27 Request-response Service Configuration Tab (Sheet 3 of 3)
Field Description
If you change the stored procedure or database connection while editing your project, you
must return to this dialog and click the Refresh button to retrieve the changes from the
database.
Table 28 Request-response Call Operation Tab
Field Description
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
88 | Chapter 4 Adapter Service Options
Advanced Tab
This tab allows you to specify values for the following:
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 or function to call.
Select Procedure Queries the database for available procedures or functions or the Procedure Name field. Clicking
this button displays a dialog showing the available procedure.
To select a procedure or function:
1. 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.
2. Click Select Procedure.
Maximum Rows (Optional) The maximum number of rows to retrieve.
One Way (Optional) Check this checkbox if you want to execute this procedure using a one-way operation. If
left unchecked, the procedure will execute using a two-way operation.
Table 28 Request-response Call Operation Tab (Cont’d)
Field Description
Table 29 Request-response Service Advanced Tab
Field Description
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 TIBCO Enterprise Message Service server. The destination can be static or
dynamic.
See Subject and Destination Names on page 163 for information about specifying destinations.
See TIBCO Enterprise Message Service User’s Guide for more details about destinations.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Request-response Service Tabs | 89
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 Subject and Destination Names on page 163 for information about specifying subjects.
See TIBCO Rendezvous Concepts for more details about subjects.
Reply Subject Type a TIBCO Rendezvous subject name that the adapter uses to respond, 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.
Table 29 Request-response Service Advanced Tab (Cont’d)
Field Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
90 | Chapter 4 Adapter Service Options
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 91
Chapter 5 Deploying and Starting the Adapter Using
TIBCO Administrator
Topics
• Create an EAR File in TIBCO Designer, page 92
• Deploy the Project, page 93
• Start or Stop the Adapter, page 94
• Monitor the Adapter, page 95
This chapter provides an overview about deploying, starting, stopping, and monitoring
adapter services using the TIBCO Administrator web interface.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
92 | Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator
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 ActiveMatrix BusinessWorks process engines, or
both.
In TIBCO Designer, follow these steps to create an EAR:
1. Configure the adapter services.
2. Drag and drop the Enterprise Archive resource from the palette panel to the design
panel.
If there are any configured adapter services in your project, an Adapter Archive
resource becomes available in the palette panel.
3. Drag the Adapter Archive into the design panel and specify information in the
Configuration tab.
4. Click the Apply button.
5. Go to the Enterprise Archive and click Build Archive to create the archive file.
See Also
See TIBCO Designer User’s Guide for more information about this procedure. The guide
is available from the Designer Help menu.
Building an archive creates the EAR file, which you can then deploy from TIBCO
Administrator. If you make changes to the business processes or adapter services included
in the archive, you need to rebuild the archive. Saving the project does not affect the
archive.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Deploy the Project | 93
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.
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.
Password Handling
At design time, the adapter uses a password to connect to the backend application and
fetch metadata. At runtime, 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 with 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 Runtime Variables section.
See Also
See TIBCO Administrator User’s Guide for an introduction to the TIBCO administration
domain and detailed information about the above steps.
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 ActiveMatrix Adapter for Database Configuration and Deployment
94 | Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator
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 checkbox 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 TIBCO Administrator User’s Guide for more information.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Monitor the Adapter | 95
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 TIBCO Administrator User’s Guide for information about configuring the above
monitoring options.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
96 | Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 97
Chapter 6 Using the Alerter
This chapter explains how to configure and start an alerter for each supported database.
Topics
• Introduction, page 98
• Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and
Above, page 99
• Setting Up and Starting the Alerter on Microsoft SQL Server 2000, page 103
• Setting Up and Starting the Alerter on Sybase SQL Server, page 106
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
98 | Chapter 6 Using the Alerter
Introduction
The alerter process is used to asynchronously notify running publication service 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 with 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.
The alerter is available on the following databases.
Oracle and Microsoft SQL Server 2005
An alerter for Oracle is part of the adapter and available on all operating systems
supported by the adapter. The alerter can be used in the TIBCO ActiveMatrix Adapter for
Database environment in cases where changes are infrequent and polling by the
publication service would result in unnecessary and expensive operations. The alerter is
supported on both the Rendezvous and JMS transports.
Microsoft SQL Server 2000
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. The alerter is only supported on the Rendezvous transport.
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. The
alerter is only supported on the Rendezvous transport.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and Above | 99
Setting Up and Starting the Alerter on Oracle or Microsoft SQL
Server 2005 and Above
The alerter on Oracle uses the Oracle AQ package and on MS SQLServer 2005 and above
uses the Service Broker component to send and receive information between sessions,
asynchronously allowing two or more sessions in the same database instance to
communicate.
As shown in the following figure, 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 Oracle AQ or MS SQLServer and that a publishing table has changed. The
alerter gets the notification from Oracle AQ or MS SQLServer 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 the TIBCO
transport. One or more instances can be notified.
Figure 4 Alerter Operation (Oracle and MSSQLServer)
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.
The Microsoft SQL Server mentioned below in this section refers to version 2005 and
above.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
100 | Chapter 6 Using the Alerter
The following object types and stored procedures are available for committing messages
when the alerter is used:
Name Type Description
adb_alerter_qtbl
(Oracle only)
AQ queue table Queue table for all alerters.
adb_alerter_q
(Oracle only)
AQ queue Queue for all alerters.
adb_alerter_typ Service Broker
Message Type
Object type for all messages.
adb_alerter_contract
(Microsoft SQL Server 2005 only)
Service Broker
Contract
The contract type used. The contract specifies the
message types that can be used.
instance_Id_q
(Microsoft SQL Server 2005 only)
Service Broker
Queue
Created by the config_alerter stored procedure.
instance_Id_send_service
(Microsoft SQL Server 2005 only)
Service Broker
Service
Created by the config_alerter stored procedure.
instance_Id_rcv_service
(Microsoft SQL Server 2005 only)
Service Broker
Service
Created by the config_alerter stored procedure.
adb_alerter_typ Object Object type for the payload message.
commit_and_notify Procedure Sends a change notification to all adapters.
commit_and_notify_agent
alerter_name
Procedure Sends a change notification to the named alerter.
commit_and_notify_table table_name Procedure Sends a change notification for a named table.
stop_alerter Procedure Stops all running alerters.
stop_alerter_agent alerter_name Procedure Stops the alerter for the named alerter.
config_alerter Procedure Alerter call to register itself as an AQ subscriber.
cleanup_alerter Procedure Alerter call to unregister itself as an AQ subscriber.
listen_pipe Procedure Alerter call to block on alerts.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and Above | 101
Before Starting
When using the alerter functionality with Oracle database, make sure you have executed
the create_user.sql and alerter.sql files with the database account used by the adapter, as
described in Post-Installation Tasks in TIBCO ActiveMatrix Adapter for Database
Installation.
When using the alerter functionality with Microsoft SQL Server database, make sure you
have enabled the service broker functionality in the database server. To check if the
service broker is enabled, execute:
SELECT is_broker_enabled FROM sys.databases WHERE database_id = DB_ID()
The returned value should be 1.
To enable service broker, execute
Alter database dbname set enable_broker with rollback immediate
Configuring and Starting the Alerter
To use the alerter, you must install the Oracle AQ or Microsoft SQL Server package. See
your Oracle documentation for information about installing the Oracle AQ or Microsoft
SQLServer package. When configuring the publication service, you must enable the
alerter by checking the Use Alerter checkbox under the Publisher Options tab. When the
adapter starts, the alerter will also start.
Oracle Alerter Example
This section describes how to execute the commit_and_notify_table stored procedure. It assumes
the rvpub.tra configuration has its data source name, user account name (demo) and password
defined in the repository. The rvpub adapter publication service has been configured with
the Use Alerter checkbox checked.
1. Start the adapter publication service instance by typing:
adbagent --propFile rvpub.tra rvpub.tra
2. After inserting a message, execute the commit_and_notify_table stored procedure with the
publishing table monitored by the adapter. For example, if the adapter is monitoring
the PUB_ORDER table:
sqlplus demo/demo
insert into ORDER_TABLE values(111,'Oak Table',499.95);
SQL> execute commit_and_notify_table (’PUB_ORDER’);
If an adapter that uses the alerter is not shutdown cleanly, you must call the cleanup_alerter
stored procedure before restarting the adapter. The procedure is normally called by the
adapter when it shuts down cleanly.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
102 | Chapter 6 Using the Alerter
The procedure puts a message on an Oracle AQ. 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.
SQL Server Alerter Example
This section describes how to execute the commit_and_notify_table stored procedure. It assumes
the rvpub.tra configuration has its data source name, user account name (demo) and password
defined in the repository. The rvpub adapter publication service has been configured with
the Use Alerter checkbox checked.
1. Start the adapter publication service instance by typing:
adbagent --propFile rvpub.tra rvpub.tra
2. After inserting a message, execute the commit_and_notify_table stored procedure with the
publishing table monitored by the adapter. For example, if the adapter is monitoring
the PUB_ORDER table:
isql -Udemo -Pdemo
SQL> insert into ORDER_TABLE values(111,'Oak Table',499.95);
SQL> execute commit_and_notify_table ’PUB_ORDER’;
The procedure puts a message to the service broker queue, which is picked up by the
adapter. 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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Setting Up and Starting the Alerter on Microsoft SQL Server 2000 | 103
Setting Up and Starting the Alerter on Microsoft SQL Server 2000
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 TIBCO ActiveMatrix Adapter for Database Installation 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 TIB_ADADB_HOME/lib
directory.
2. Copy the alerter library to the Binn directory where SQL Server is installed, for
example:
copy adbalerter_mssql.dll \Mssql7\Binn
3. Ensure the procedures are not already defined in the master database:
isql -Usa -Ppassword1> sp_dropextendedproc 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.
4. Add the procedures to the master database:
1> sp_addextendedproc 'notify','adbalerter_mssql.dll'
2> go
1> sp_addextendedproc 'notifytable','adbalerter_mssql.dll'
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
104 | Chapter 6 Using the Alerter
2> go
5. Set access permissions for the database account used by the adapter:
1> grant execute on notify to database_account2> go
1> grant execute on notifytable to database_account2> go
1> exit
6. Add TIBCO_HOME\tibrv\bin to the system PATH variable.
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 properties_file_name
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='rvpub'
2> go
Notifying: rvpub
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='rvpub
rvpub2 rvpub3'
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='rvpub rvpub2',@tablename='P_ORDER_TABLE’
2> go
Modifying RV Configuration
The RV configuration parameters used by the alerter to connect to a remote daemon can be
modified by including the configuration parameters when invoking the store procedure.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Setting Up and Starting the Alerter on Microsoft SQL Server 2000 | 105
For example,
execute master.dbo.notify @agentname='rvpub', @service='7500', @network=’lan0’, @daemon='10.105.176.21:7500'
execute master.dbo.notifytable @agentname='rvpub rvpub2', @pubtable='ADB_ORDER', @service='7500',
@network=’lan0’, @daemon='10.105.176.21:7500'
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
106 | Chapter 6 Using the 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 TIBCO ActiveMatrix Adapter for Database Installation 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 TIB_ADADB_HOME/lib
directory. Copy the alerter library as follows:
cp adbalerter_sybase.so sybase/lib
2. Ensure that the procedures are not already defined in the master database:
isql -Usa -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>create procedure notify
2>@agentname varchar(255),
You may need to shut down and restart your XP SERVER after copying the shared library
to the sybase/lib directory.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Setting Up and Starting the Alerter on Sybase SQL Server | 107
3>@service varchar(255)=’default_value’,4>@network varchar(255)=’default_value’,5>@daemon varchar(255)=’default_value’6> as external name 'adbalerter_sybase'
7>go
1>create procedure notifytable
2>@agentname varchar(255),
3>@tablename varchar(255),
4>@service varchar(255)=’default_value’,5>@network varchar(255)=’default_value’,6>@daemon varchar(255)=’default_value’7> as external name 'adbalerter_sybase'
8>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_account2> go
1> grant execute on notifytable to database_account2> go
1> exit
5. Add TIBCO_HOME/tibrv/lib/libtibrv.so to the system LD_LIBRARY_PATH variable.
6. Add TIBCO_HOME/tibrv/rvd/bin to the system PATH variable.
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 TIB_ADADB_HOME\lib
directory. Copy the alerter library as follows:
copy adbalerter_sybase.dll \Sybase\dll
2. Ensure that the procedures are not already defined in the master database:
isql -Usa -Ppassword1> sp_dropextendedproc notify
2> go
1> sp_dropextendedproc notifytable
2> go
1> sp_freedll "adbalerter_sybase"
2> go
3. Add the procedures to the master database:
You may need to shutdown and restart your XP SERVER after copying adbalerter_sybase.dll
to the \Sybase\dll directory.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
108 | Chapter 6 Using the Alerter
1>create procedure notify
2>@agentname varchar(255),
3>@service varchar(255)=’default_value’,4>@network varchar(255)=’default_value’,5>@daemon varchar(255)=’default_value’6> as external name 'adbalerter_sybase'
7>go
1>create procedure notifytable
2>@agentname varchar(255),
3>@tablename varchar(255),
4>@service varchar(255)=’default_value’,5>@network varchar(255)=’default_value’,6>@daemon varchar(255)=’default_value’7> as external name 'adbalerter_sybase'
8>go
4. Set access permissions for the database account used by the adapter:
1> grant execute on notify to database_account2> go
1> grant execute on notifytable to database_account2> go
1> exit
5. Add TIBCO_HOME\tibrv\bin to the system PATH variable.
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='rvpub'
2> go
Notifying: rvpub
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='rvpub rvpub2 rvpub3'
2> go
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Setting Up and Starting the Alerter on Sybase SQL Server | 109
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='rvpub rvpub2',@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.
Modifying RV Configuration
The RV configuration parameters used by the alerter to connect to a remote daemon can be
modified by including the configuration parameters when invoking the store procedure.
For example,
execute master.dbo.notify @agentname='rvpub', @service='7500', @network=’lan0’, @daemon='10.105.176.21:7500'
execute master.dbo.notifytable @agentname='rvpub rvpub2', @pubtable='ADB_ORDER', @service='7500',
@network=’lan0’, @daemon='10.105.176.21:7500'
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
110 | Chapter 6 Using the Alerter
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 111
Chapter 7 Using the Request-response Service
This chapter explains the request-response service, load balancing, and Oracle REF data
type support features.
See TIBCO ActiveMatrix Adapter for Database Examples for request-response exercises.
Topics
• Introduction, page 112
• Request-response Mode, page 114
• RPC Mode, page 122
• Load Balancing, page 132
• Oracle REF Data Type Support, page 139
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
112 | Chapter 7 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 85.
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.
Multiple adapter instances can be configured so that any one of the configurations
receives and processes the request:
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Introduction | 113
• 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
Instance Using Threads on page 132 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 Adapter
Instances on page 134 for details.
Use of Quotes in Microsoft SQL Server
When constructing a request in your application that will be processed by the adapter with
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.
The SQL statement should contain only ASCII characters.
If your SQL statements contain non-ASCII characters, convert them into a stored
procedure and invoke the procedure using custom RPC operations.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
114 | Chapter 7 Using the Request-response Service
Request-response Mode
TIBCO ActiveMatrix Adapter for Database 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 85. 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
• The column size of the return resultset should not exceed 128
• Multiple statements or procedures in a single transaction that send a nested TIBCO
Rendezvous message
• rv_Send(), rv_SendWithReply() and rv_Rpc() calls
• TIBCO Rendezvous C, C++, and Java APIs
Requests are described in the following sections:
• TIBCO ActiveEnterprise or XML Message Request Format, page 115
• TIBCO Rendezvous Message Request Format, page 115
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Request-response Mode | 115
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 118
• TIBCO Rendezvous Message Response Format, page 118
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 126.
<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_datarv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statementrv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statementrv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statement. . .
}
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
116 | Chapter 7 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_variablesrv_Name = “maxrows”, rvmsg_Type = RVMSG_INT, rvmsg_Data = optional_max_number_of_rows_to_fetchrv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_datarv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_datarv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_data. . .
}
The value Bind_data is a TIBCO Rendezvous Message with the following structure:Bind_data{
rv_Name = "position", rvmsg_Type = RVMSG_INT, rvmsg_Data = position_of_placeholder_starting_with_1_from_left_to_rightrv_Name = "column", rvmsg_Type = RVMSG_STRING, rvmsg_Data =
in_format_table-name.column-name_whose_column_type_matches_this_bound_variablerv_Name = "data", rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data}
If the position field is not specified, the order received is used.
Example TIBCO Rendezvous Message Requests
The section contains example requests that are based on SQL statements made by a client
application and sent to an adapter instance for processing.
Simple SQL Request Statement
Given that a client application submits the following SQL statement:
INSERT INTO order_table (order_id, order_description,
order_price) values (1, ‘Order 1’, 1.10)
The corresponding request could be formatted as a TIBCO Rendezvous Message similar
to the following:
{
name = “closure” value = optional_closure_argumentname = “stmt” value =
{
name = “sql” value = “INSERT INTO order_table (order_id, order_description, order_price) values (1, ‘Order 1’,
1.10)”
}
}
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Request-response Mode | 117
Bind Request Statement
Assume that a client application submits the following SQL statement, where ? is a
placeholder for an adbDateTime value:
INSERT INTO order_table (order_id, order_date) values (2, ?)
The corresponding request could be formatted as a message in TIBCO Rendezvous Message
format similar to the following:
{
name = “closure” value = optional_closure_argumentname = “stmt” value =
{
name = “sql” value = “INSERT INTO order_table (order_id, order_date) values (2, ?)”
name = “bind” value =
{
name = “order_table.order_date” type = RVMSG_STRING value = “1999-08-20 10:20:01”
}
}
}
To create a bind parameter for binary data, the actual data would be sent as an
RVMSG_OPAQUE.
Using Bind Entries
Bind entries are specific only to the stmt {} that contains them. For example, if you want to
insert three rows into REPLYTEST, you need to have three stmt {} blocks (and thus, three sets
of bind statements):
request: {
stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP"
data="1991-10-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[3 opaque bytes]}}
stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP"
data="1991-11-10 12:10:10"} bind={column="REPLYTEST.BINCOL" data=[4 opaque bytes]}}
stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP"
data="1991-12-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[5 opaque bytes]}}}
Not every data value sent to an SQL statement must be bound. The client can embed all
these values into the actual text of the statement instead. Embedding the values directly
into the SQL text results in better performance. However, binary values must be bound.
Types such as adbDateTime can either be bound or included in the SQL text by using the
native DBMS date conversion function.
For example, in ORACLE, you could use the TO-DATE function to enter a date:
INSERT INTO order_table (order_id, order_date) values (2,
TO_DATE(’1999-08-20 10:20:01’, ’YYYY-MM-DD HH24:MI:SS’));
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
118 | Chapter 7 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 125.
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 = Resultrv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data}
where Result is a message in TIBCO Rendezvous Message format of the following
structure:
Result{
name = “row” type = RVMSG_RVMSG value = List_of_columnsname = “row” type = RVMSG_RVMSG value = List_of_columnsname = “row” type = RVMSG_RVMSG value = List_of_columns. . .
}
where List_of_columns is a message in TIBCO Rendezvous Message format of the
following structure:
List_of_columns{
rv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_datarv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_datarv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data. . .
}
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Request-response Mode | 119
If the request processing was not successful, the response could also return an error code
and error description as shown next:
Reply{
rv_Name = “status” rvmsg_Type = RVMSG_INT rvmsg_Data = nonzero_numberrv_Name = “sql” rvmsg_Type = RVMSG_STRING rvmsg_Data = SQL_statement_that_caused_errorrv_Name = “error” rvmsg_Type = RVMSG_STRING rvmsg_Data = error_textrv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data}
The status value is an integer specifying success or error. Possible values are:
0: ok // No 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
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
120 | Chapter 7 Using the Request-response Service
Query Example
As an example, assume the SQL statement, SELECT * FROM ORDER_TABLE produces the
following result:
SQL> SELECT * FROM ORDER_TABLE;
ORDER_ID ORDER_DESCRIPTION ORDER_PRICE
1 Order 1 1.00
2 Order 2 2.00
In this case, the self-describing message in TIBCO Rendezvous Message format produced
by the adapter would have the following structure:
{
name = “closure” value = optional_closure_argumentname = “status” value = 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
The self-describing message produced by the adapter would have the following structure:
{
name = “closure” value = optional_closure_argument
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Request-response Mode | 121
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 ActiveMatrix Adapter for Database Configuration and Deployment
122 | Chapter 7 Using the Request-response Service
RPC Mode
TIBCO ActiveMatrix Adapter for Database 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 ActiveMatrix Adapter for Database. 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.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
RPC Mode | 123
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. The other classes, such as
SQL_STATEMENT, SQL_BIND, and SQL_RETURN, describe metadata for the input and output
parameters to the operations.
• Use SQL_BATCHEXECUTE to send one or more SQL statements in a request.
• SQL_BATCHRETRUN is the return class.
• If an error occurs while executing a statement, the adapter returns the error
immediately without executing the remaining statements.
• On Oracle only, all statements are executed within the same transaction.
SQL_OPS Class
The structure of the SQL_OPS class is:
<class
name = "SQL_OPS">
<operation
name = "SQL_EXECUTE"
returnClass = "SQL_RETURN">
<parameter name = "STATEMENT" classRef = "SQL_STATEMENT" direction = "in"> </parameter>
</operation>
<operation
name = "SQL_BATCHEXECUTE"
returnClass = "SQL_BATCHRETURN">
<parameter name = "STATEMENTS" classRef = "sequence[SQL_STATEMENT]"
direction = "in" />
</operation>
</class>
SQL_RESULTSET Class
The structure of the SQL_RESULTSET class is:
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
124 | Chapter 7 Using the Request-response Service
<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"/>
</assoc>
<assoc name="attribute">
<string name="name" value="CLOSURE"/>
<ref name="attributeType" value="/tibco/public/scalar/ae/any"/>
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
RPC Mode | 125
<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">
<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>
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
126 | Chapter 7 Using the Request-response Service
<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>
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
RPC Mode | 127
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 30 Request Schema Description
Input Item
Data Type or Classname
Description
INBINDS INPUT_BINDS The input parameters of the stored procedure.
OPTIONS INPUT_OPTIONS The input options:
Option Data Type Description
MAXROW
S
Integer The maximum number of rows to retrieve.
SQL String The SQL string use to execute the stored procedure.
This string is automatically generated by the palette.
CACHE Boolean True if user want the agent to cache the statement for
performance optimization
PACKAGE String read only, uses the call operation form to modify the
package of the stored procedure.
SCHEMA String read only, uses the call operation form to modify the
package of the stored procedure.
CLOSURE Any Closure argument. The reply returns this closure argument untouched.
Table 31 Reply Schema Description
Output ItemData Type or Classname
Description
OUTBINDS OUTPUT_BINDS The output parameters of the stored procedure
RESULTSET[1..n]/RESUL
TSETS
OUTPUT_ROWS/
SQL_RESULTSET
The result set(s) returned by the stored procedure, see section
'Result Set Support' for more description
STATUS String SUCCESS if the stored procedure is executed successfully.
FAILURE if there is an error. Error details are stored in the
OPTIONS class
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
128 | Chapter 7 Using the Request-response Service
Resultset Support
TIBCO ActiveMatrix Adapter for Database 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.
OPTIONS CUSTOM_OP_OUTPUT_OP
TION
Contains the error description and the SQL statement if an error
occurred.
CLOSURE Any Closure argument obtained from the request
Table 31 Reply Schema Description (Cont’d)
Output ItemData Type or Classname
Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
RPC Mode | 129
• If a driver does not return valid information for the resultset schema, TIBCO
ActiveMatrix Adapter for Database uses the generic class SQL_RESULTSETS as the
output schema, as described in Standard RPC Operation on page 122.
Implementing Client RPC Programs
Two sample clients are provided in the TIB_ADADB_HOME\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
TIBCO Adapter SDK Programmer’s Guide.
DataDirect JDBC 3.3 drivers only provide valid resultset schema information for Oracle
Server version 8.1.7 or higher.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
130 | Chapter 7 Using the Request-response Service
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 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.
3. Click the Apply button.
4. In the Project panel, expand the GenericAdapterConfiguration folder and expand
the Adapter Services folder.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
RPC Mode | 131
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 ActiveMatrix Adapter for Database Configuration and Deployment
132 | Chapter 7 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 Instance Using Threads
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. Check the Show All Tabs checkbox.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Load Balancing | 133
3. Display the Adapter Services tab.
4. Change the value of Number Of Request-Response Service Threads as needed.
5. Click the Apply button.
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 ActiveMatrix Adapter for Database Configuration and Deployment
134 | Chapter 7 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.
Load Balancing Across Adapter Instances
To achieve load balancing across adapter instances, TIBCO Rendezvous Distributed
Queueing can be used to assign each application request to exactly one adapter instance.
For example, the following diagram shows three adapter instances each connected to a
database server (not shown) that contains replicated data.
Figure 5 Request-Response Load Balancing
The adapter instances have been set up to use distributed queueing with one instance
acting as the scheduler. Only one of the three adapter instances will receive an incoming
request from an application. The scheduler will assign certified requests to the least loaded
member of the queue.
While the request message can be sent with either reliable or certified quality of service,
the response message is always sent back using the reliable quality of service.
TIBCO Messaging
Application
Adapter 4
Adapter 3
Adapter 2
Adapter 1
(Scheduler)
Request
Request
Request
RequestResponses
Distributed Queue
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Load Balancing | 135
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.
Configuring an Adapter Instance to use Distributed Queues
You can configure the adapter with a subscription service to use a distributed queue, then
use TIBCO Administrator Enterprise Edition to deploy multiple instances of the adapter.
The instances can be deployed on the same machine, or multiple machines. In this
scenario, each adapter instance uses the same (default) values for the distributed queue.
1. Start TIBCO Designer and create a new project.
2. Drag the ActiveDatabase Adapter Configuration icon to the design panel.
3. Configure the adapter instance with a design-time connection and ODBC DSN value.
4. Drag the ADBSubscriber icon to the design panel.
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 ActiveMatrix Adapter for Database Configuration and Deployment
136 | Chapter 7 Using the Request-response Service
5. Under the Configuration tab, set Transport Type to Rendezvous and Quality of
Service to Distributed Queue. For example:
6. Configure the service with a destination table name and other settings for your
environment.
7. Click Project > Save.
8. Click Tools > Create Project EAR. Under the Configuration tab, provide a name and
file location for the EAR file.
9. Click Build Archive.
After creating the EAR file, you are ready to import it into TIBCO Administrator
Enterprise Edition and add the adapter instance multiple times to the same machine or
multiple machines.
1. Start TIBCO Administrator Enterprise Edition.
2. Select Application Management, then click the New Folder button. In Name, provide
a name for the folder and click the Save button.
3. Select the folder, then click New Application.
4. Click the Browse button and navigate to the EAR file you created in Designer. Click
the OK button.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Load Balancing | 137
5. In the dialog that appears, click the Save button.
6. Expand the configuration, then double-click the name.aar file.
7. Click the Add To Additional Machine button and select the machine to bind to and
click the OK button.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
138 | Chapter 7 Using the Request-response Service
8. Repeat to create the number of adapter instances required for your environment. For
example, the next screen shows that three adapter instances have been added.
9. Click the Save button.
The adapter instances are ready to be deployed. After the instances are deployed, when a
message is sent to the adapter, the instance that is not busy will handle the request.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Oracle REF Data Type Support | 139
Oracle REF Data Type Support
The adapter supports the use of the REF data type (cursor) as an OUT parameter only 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 ActiveMatrix Adapter for Database Configuration and Deployment
140 | Chapter 7 Using the Request-response Service
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 141
Chapter 8 Working With Tables
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 142
• Source Table, page 148
• Exception Table, page 149
• Opaque Exception Table, page 152
• Incremental Parent-child Operation, page 154
• Database Types, page 156
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
142 | Chapter 8 Working With Tables
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.
The trigger generated at design time will automatically populate the values for these
additional columns. It is not recommended that you modify these values.
In addition to a copy of the source table’s columns, the publishing table has the following
additional columns.
Table 32 Publishing Table Additional Columns (Sheet 1 of 2)
Column Name Type Description
ADB_SUBJECT VARCHAR2(255) Used to specify the subject to publish the current row. Length is
255. You can set a message subject in this field which will take
precedence over the default service subject. The adapter will
publish this row with this new message subject.
In group messaging, the group message will be sent to the subject
set for the last row of the group.
ADB_SEQUENCE NUMBER(38) 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.
By default, the schema type is string. The adapter treats this
number as a string. This number can be larger than an integer if
the database supports it.
ADB_SET_SEQUENCE NUMBER(38) Currently not used.
ADB_TIMESTAMP DATE Time of row insertion in publishing table that is used to calculate
expiration of rows. The timestamp is generated automatically.
For Oracle databases, the timestamp includes the time zone
information.
For all new services:
Microsoft Windows platforms, the timestamp with time zone
option should be selected in the Advanced Settings tab of the
ODBC connection.
Unix platforms, the LocalTimeZoneOffset parameter in the
odbc.ini should be set to the local time zone. For example,
LocalTimeZoneOffset=+10:00.
Also the EnableTimestampWithTimeZone parameter in the
odbc.ini file should be set to 1.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publishing Table | 143
ADB_TRACKINGID VARCHAR2(40) Tracking ID of the message.
This is automatically added to the publishing table and the
publishing schema.
If you do not want to monitor the tracking id, you can manually
remove this field from the project schema and the publishing
table
ADB_OPCODE NUMBER(38) 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 154)
If an incoming TIBCO Rendezvous message does not have an
operation code, an INSERT occurs.
ADB_UPDATE_ALL NUMBER(38) Currently not used.
ADB_REF_OBJECT VARCHAR2(64) When publish by reference object is used, contains the name of
the reference object that provides source data.
ADB_L_DELIVERY_STAT
US
CHAR(1) 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(38) Certified messaging sequence number associated with this
message.
ADB_MARK VARCHAR2(64) It is a number that is retrieved from the publication load
balancing mutex table when the service instance is started. It
represents an identifier of each adapter instance in the publication
load balancing group.
ADB_INSTANCEID VARCHAR2(200) It is the adapter instance ID configured by the user.
Table 32 Publishing Table Additional Columns (Sheet 2 of 2)
Column Name Type Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
144 | Chapter 8 Working With Tables
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.
Publication Example
The following is a listing of the SQL commands used to create a publication. The listing
can be found in the TIB_ADADB_HOME\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 ActiveMatrix Adapter for Database
-- 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),
When publishing parent-child record or in Publish By Reference mode, if the key value is
empty (null) in the publishing table, the adapter will consider this as an error operation,
and update the failure status in the publication table by setting adb_l_delivery_status to F. The
data will not be published.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publishing Table | 145
ORDER_PRICE NUMBER(10,3)
);
-- *******************************************
-- Setup a publication
-- *******************************************
CREATE TABLE PUB_ORDER (
ORDER_ID NUMBER,
ORDER_DESCRIPTION VARCHAR2(128),
ORDER_PRICE NUMBER(10,3),
ADB_SUBJECT VARCHAR2(255) NULL,
ADB_SEQUENCE INTEGER NOT NULL,
ADB_SET_SEQUENCE INTEGER NULL,
ADB_TIMESTAMP DATE NULL,
ADB_OPCODE INTEGER NOT NULL,
ADB_UPDATE_ALL INTEGER NULL,
ADB_REF_OBJECT VARCHAR2(64) NULL,
ADB_L_DELIVERY_STATUS CHAR NULL,
ADB_L_CMSEQUENCE NUMBER(38, 0) NULL
)
/
CREATE UNIQUE INDEX IDX1_PUB_ORDER ON PUB_ORDER (ADB_SEQUENCE)
/
CREATE UNIQUE INDEX IDX2_PUB_ORDER ON PUB_ORDER (ADB_L_DELIVERY_STATUS,
ADB_SEQUENCE)
/
CREATE INDEX IDX3_PUB_ORDER ON PUB_ORDER (ADB_L_CMSEQUENCE)
/
CREATE SEQUENCE PUB_ORDER_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,
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
146 | Chapter 8 Working With Tables
SYSDATE,
1,
NULL,
NULL,
'N',
-1);
END IF;
IF UPDATING THEN
IF UPDATING('ORDER_ID') THEN
RAISE updating_key_fields;
END IF;
INSERT INTO PUB_ORDER VALUES (
:OLD.ORDER_ID,
:NEW.ORDER_DESCRIPTION,
:NEW.ORDER_PRICE,
NULL,
PUB_ORDER_SEQ.NEXTVAL,
0,
SYSDATE,
2,
NULL,
NULL,
'N',
-1);
END IF;
IF DELETING 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
-- *******************************************
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,
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publishing Table | 147
ADB_ERROR_TEXT VARCHAR(4000) NULL,
ADB_ERROR_TIME DATE DEFAULT SYSDATE
)
/
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)
Optimizing the Publication Sequence for Oracle RAC System
To optimize the performance and to avoid out of order generation of ADB_SEQUENCE,
it is recommended that you add the ORDER option and also increase the cache size.
Consult your system administrator to confirm the impact of these changes.
CREATE SEQUENCE PUB_ORDER_SEQ
START WITH 1
INCREMENT BY 1
NOMAXVALUE
ORDER
NOCYCLE
CACHE 50
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
148 | Chapter 8 Working With Tables
Source Table
If loop detection is enabled, the following column will be added to the source table.
If the source table contains a field ADB_TRACKINGID, it will be updated using the tracking id
of the message. If this field is not present, the tracking id field will be ignored..
The source table cannot contain any user-created columns where the column name starts
with ADB_. These characters are reserved for adapter use.
Table 33 Source Table Additional Columns
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.
Valid values are T or NULL.
T indicates the row is not to be published.
NULL indicates the row can be published.
ADB_TRACKINGID VARCHAR2(
40)
Tracking ID of the message.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Exception Table | 149
Exception Table
If a database restriction or failure occurs, 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 TIBCO Hawk Administrator’s Guide for details about creating a rulebase.
For bulk insert operations, the agent will insert all the rows into the exception table. 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 all 500 rows to the exception table. It will then commit the operation.
(The bulk insert operation is described in Adapter Services Tab on page 43.)
In addition to destination table columns, the following columns are added to the exception
table.
Table 34 Exception Table Additional Columns
Column Name Type Description
ADB_OPCODE NUMBER(38) 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_UPDATE_ALL NUMBER(38) Currently not used.
ADB_TRACKINGID VARCHAR2(40) Tracking ID of the message. This column is the primary key.
Each exception table that is mapped to a child table is connected
to the parent’s exception table by this column
ADB_ERROR_TEXT VARCHAR2(4000) Text of the error from the database server, ODBC driver, or other
source that caused the exception.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
150 | Chapter 8 Working With Tables
The exception table cannot contain any user-created columns where the column name
starts with ADB_. These characters are reserved for adapter use.
Child Exception Table
In addition to child table columns, the following columns are added to a child exception
table.
ADB_ERROR_TIME DATE Timestamp of the inserted record.
For Oracle databases, the timestamp includes the time zone
information.
For all new services:
Microsoft Windows platforms, the timestamp with time zone
option should be selected in the Advanced Settings tab of the
ODBC connection.
Unix platforms, the LocalTimeZoneOffset parameter in the
odbc.ini should be set to the local time zone. For example,
LocalTimeZoneOffset=+10:00
Also the EnableTimestampWithTimeZone parameter in the
odbc.ini file should be set to 1.
ADB_JOIN_ID VARCHAR Joined column used to link a parent record with its child record.
ADB_JOIN_ID is generated from ADB_TRACKINGID and
concatenated with the record number in the group. A child table’s
exception table is connected to its parent’s table exception table
by ADB_JOIN_ID.
Table 34 Exception Table Additional Columns (Cont’d)
Column Name Type Description
Table 35 Child Exception Table Additional Columns
Column Name Type Description
ADB_ERROR_TEXT VARCHAR Text of the error from the database server, ODBC driver, or
other source that caused the exception.
ADB_ERROR_VTIME DATE Timestamp of the inserted record.
ADB_TRACKINGID VARCHAR TrackingID of the message.
ADB_JOIN_ID VARCHAR Tracking ID of the Message.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Exception Table | 151
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 171) and choose your view as the reference object.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
152 | Chapter 8 Working With Tables
Opaque Exception Table
The subscription service uses two logical layers when processing a message. The first
layer decodes data from the message and the second layer provides the database
transaction. If an exception occurs in the first layer, the adapter logs the message to the
opaque exception table. In the second layer, if any DML command fails at any level, the
adapter rolls back this transaction and starts another transaction, inserting into exception
tables. If the insert into exception table transaction fails, the adapter then logs the message
to the opaque exception table.
The opaque exception table records the entire message into a column along with the error
message. The opaque exception table has the following columns:
Table 36 Opaque Exception Table Columns
Column Name Type Description
ADB_TRACKINGID VARCHAR Tracking ID of the message.
ADB_ERROR_TEXT VARCHAR Text of the error from the database server,
ODBC driver, Adapter SDK or other source that
caused the exception.
ADB_ERROR_TIME DATE Timestamp of the inserted record.
For Oracle databases, the timestamp includes the
time zone information.
For all new services:
Microsoft Windows platforms, the timestamp
with time zone option should be selected in the
Advanced Settings tab of the ODBC connection.
Unix platforms, the LocalTimeZoneOffset
parameter in the odbc.ini should be set to the
local time zone. For example,
LocalTimeZoneOffset=+10:00
Also the EnableTimestampWithTimeZone
parameter in the odbc.ini file should be set to 1.
ADB_MSG BLOB Raw bytes of the message.
ADB_SUBTAB VARCHAR Destination table name.
ADB_SUBJECT VARCHAR Subscription service destination or subject.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Opaque Exception Table | 153
The ADB_SUBTAB column allows you to configure several subscription services using
only one opaque exception table in the same database schema.
ADB_TRANSPORT INT Subscription service transport type:
0 unknown
1 Rendezvous
2 JMS
Table 36 Opaque Exception Table Columns (Cont’d)
Column Name Type Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
154 | Chapter 8 Working With Tables
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"
RVMSG_INT 4 ADB_OPCODE 4
RVMSG_REAL 8 A 1
RVMSG_STRING 2 B "a"
RVMSG_REAL 8 C 4
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Incremental Parent-child Operation | 155
}
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 ActiveMatrix Adapter for Database Configuration and Deployment
156 | Chapter 8 Working With Tables
Database Types
The database data types listed in this section are supported.
Oracle
The following Oracle data types are supported:
The following ANSI data types in Oracle are supported:
• CHAR • TIMESTAMP
• DATE • RAW
• LONG • VARCHAR2
• LONG RAW • CLOB
• NUMBER • BLOB
• TIMESTAMP WITH
TIMEZONE
• TIMESTAMP
WITH LOCAL
TIMEZONE
• NCHAR • NVARCHAR2
• DECIMAL • NCLOB
• XMLType
• DOUBLE PRECISION • INTEGER
• FLOAT • SMALLINT
• INT • REAL
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Database Types | 157
SQL Server
The following SQL Server data types are supported:
Sybase and Sybase Adaptive Server Anywhere
The following Sybase data types are supported:
DB2
The following DB2 data types are supported:
• BIGINT • INT • SMALLINT
• BINARY • MONEY • SMALLMONEY
• BIT • NCHAR • TEXT (publish by
reference only)
• CHAR • NTEXT • TIMESTAMP
• DATETIME • NUMERIC • TINYINT
• DECIMAL • NVARCHAR • UNIQUEIDENTIFIER
• FLOAT • REAL • VARBINARY
• IMAGE (Publish by
reference only)
• SMALLDATETIME • VARCHAR
• BINARY • INT • TEXT
• BIT • MONEY • TINYINT
• CHAR • NUMERIC • VARCHAR
• DATETIME • REAL • VARBINARY
• DECIMAL • SMALLDATETIME • BIGINT
• FLOAT • SMALLINT • NCHAR
• IMAGE (Publish by
reference only)
• SMALLMONEY • NVARCHAR
• CHARACTER • NUMERIC
• DECIMAL • REAL
• DOUBLE PRECISION • SMALLINT
• FLOAT • TIMESTAMP
• INTEGER • VARCHAR
• LONG VARGRAPHIC • LONG VARCHAR
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
158 | Chapter 8 Working With Tables
MySQL
The following MySQL data types are supported:
Teradata
The following Teradata data types are supported:
• DATE • TIME
• BIGINT • CLOB
• BLOB • CHAR
• DOUBLE
• BLOB • DATE
• LONGBLOB • TIMESTAMP
• MEDIUMBLOB • TIME
• TINYBLOB • YEAR
• BIT • VARBINARY
• BIGINT • ENUM
• MEDIUMINT • SET
• TINYINT • TEXT
• SMALLINT • LONGTEXT
• INT • MEDIUMTEXT
• CHAR • TINYTEXT
• VARCHAR • FLOAT
• BINARY • DECIMAL
• BOOL • DOUBLE
• DATETIME
• BYTE • CHAR(n)
• BYTEINT • VARCHAR(n)
• DECIMAL(n,p) • VARBYTE
• SMALLINT • LONG VARCHAR
• INTEGER • DATE
• NUMERIC(n,p) • TIME(n)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Database Types | 159
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.
• FLOAT(n) • TIME(n) WITH TIME
ZONE
• REAL • TIMESTAMP(n)
• DOUBLE PRECISION • TIMESTAMP(n) WITH
TIME ZONE
Table 37 Mapping to Database Types
ODBC TypeTIBCO ActiveEnterprise Type
TIBCO Rendezvous Message Type
SQL_CHAR
SQL_VARCHAR
SQL_LONGVARCHAR
string RVMSG_STRING
SQL_SMALLINT
SQL_INTEGER
i4 RVMSG_INT
SQL_REAL
SQL_DOUBLE
SQL_FLOAT
SQL_DECIMAL
SQL_NUMERIC
r8 RVMSG_REAL
SQL_BINARY
SQL_VARBINARY
SQL_LONGVARBINARY
binary RVMSG_OPAQUE
SQL_TIMESTAMP dateTime RVMSG_DATETIME
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
160 | Chapter 8 Working With Tables
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 161
Chapter 9 Advanced Features
Topics
• Subject and Destination Names, page 163
• Preregistering a Certified Subscriber, page 167
• Changing the Location of the Ledger File, page 169
• Sending Messages to an Adapter Instance, page 170
• Publishing by Reference Object, page 171
• User Callout Library, page 179
• Unique Connection Identifier for Oracle Databases, page 185
• Publishing in a Commitment Controlled Environment, page 186
• Using the Adapter with a Revision Control System, page 188
• Using a Log File for an Adapter Instance, page 189
• Using Database Deployment and Cleanup Scripts, page 194
• Changing the SQL Statement Terminator (DB2 for z/OS Only), page 197
• Fault Tolerance, page 198
• SSL Data Encryption using DataDirect ODBC Drivers, page 200
• OS Authentication, page 201
• Query Timeout, page 202
• Working with Multi-File Format Projects, page 203
• Subscriber Reply Sender, page 204
• Subscriber Pre-commit Stored Procedure Call, page 205
• JMS Durable Subscriber Name, page 206
• Runtime Schema, page 207
• Runtime Table Schema Configuration, page 208
• Group Message Transaction, page 209
• Load Balancing and Multithreading, page 210
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
162 | Chapter 9 Advanced Features
• Compressing JMS Messages, page 219
• Configuring RVCMQ Backlog Size, page 220
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Subject and Destination Names | 163
Subject and Destination Names
An adapter instance sends and receives messages using subject names when using the
TIBCO Rendezvous transport type, and destination names when using the JMS transport
type. Both subject and destination names are structured strings of alphanumeric characters
divided into elements by the dot (.) character. For example, Tibco.Tsi and News.Sports.Baseball
are valid subject and destination names.
Default subject or destination names are provided in TIBCO Designer. You can change
these default values to specify a custom subject or destination name. A default subject or
destination, depending on which transport type you choose to configure, is created each
time an adapter service is created.
The following are restrictions on subject names and destination names:
• Length of subject and destination 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 127 characters.
— Destination names are limited to a total length of 249 characters. Even though JMS
has a 249-character destination length limit, some of that length is reserved for
internal use. The destination space must be designed to conform to the length
restrictions. There can be at most 64 elements in a destination name. The maximum
element length is 127 characters. Dot separators are not included in element length.
• Wildcard characters
The asterisk (*) and greater than (>) are wildcard characters that can be used when
specifying subject names or destination names.
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. This feature also applies to destination names.
• Reserved underscore (_)
Subject or destination names beginning with underscore (_) are reserved. Application
programs cannot send subjects or destinations with an underscore as the first character
of the first element, however, _INBOX and _LOCAL are exceptions for subject names,
and _INBOX is an exception for destination names. It is also recommended that you do
not use tabs, spaces, or any unprintable character.
An underscore can be used elsewhere in subject or destination names. Subject names
are case sensitive.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
164 | Chapter 9 Advanced Features
• Empty strings
Empty strings ("") are not permitted.
• Dot character
The dot characer cannot be incorporated into an element by by using an escape
sequence.
See TIBCO Rendezvous Concepts for a full explanation of subject names and TIBCO
Enterprise Message Service User’s Guide for destination names.
Parameterized Subject or Destination Names
During the usage of TIBCO ActiveMatrix Adapter for Database, a subject name can be
created from one or more columns in a publishing table when using the TIBCO
Rendezvous transport type, and a destination name can be created when using the JMS
transport type. A subject or destination created this way is known as a parameterized
subject or destination. For example, you can use TIBCO Designer to define a publication
subject as 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 or destination is created from the contents of those columns.
This allows receiving applications to filter publications based on the values of certain
fields. Parameterized subject or destination names are supported with certified or reliable
delivery.
Parameterized Subject and Destination Name Restrictions
The following are restrictions on parameterized subject names and destination names:
• Length of parameterized subject and destination names
— A TIBCO Rendezvous parameterized subject name can be at most 255 characters
in length, with each component no more than127 characters.
— A JMS parameterized destination name can be at most 249 characters in length,
with each component no more than 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 or destination in place of the description value.
• Wildcard characters
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 or destination. Doing so makes the subject or destination invalid.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Subject and Destination Names | 165
For example, if the TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION parameterized subject
or destination 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_DESCRIPTION TABLE values(112,'>',99.91);
the publisher would return an error.
• Data type restrictions
— Do not use columns that contain Date types as part of a parameterized subject or
destination. Date values are likely to contain characters such as dashes and spaces
that can cause problems when used as part of a subject or destination.
— Do not use columns that contain binary types as part of a parameterized subject or
destination.
— Do not insert Float-type data as an attribute value in a column that is part of a
parameterized subject or destination. Doing so makes the subject or destination
invalid.
• Column name
Each element cannot represent more than one column. For example,
MYSUBJECT.$COLUMN1$COLUMN2 is an invalid parameterized subject name.
• Group messaging
The group messaging feature is not supported with parameterized subjects or
destinations. An error message will display and the adapter will automatically disable
the group messaging feature for the publisher. For example, if the TIBCO Rendezvous
transport type is used, the error message will be:
Cannot use parameterized subject with group Publishing. Disable group publishing.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
166 | Chapter 9 Advanced Features
• Pre-registration
Pre-registration in the adapter can not work when a parameterized subject or
destination is used.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Preregistering a Certified Subscriber | 167
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 ActiveMatrix Adapter for Database subscriber, or any other TIBCO Rendezvous
subscriber.
A subscriber adapter on the preregister list is certified to receive all messages sent on the
specified subject using the RVCM quality of service. If a subscriber is not preregistered, it
may miss one or more of the initial messages sent by the publisher adapter.
To preregister a certified subscriber in TIBCO Designer:
1. In the Project panel, under the publisher adapter, expand Advanced > Sessions >
adbadapterInstanceNamervcmRvCmSession endpoint object.
2. Click the publisher endpoint in the Design panel.
Wildcard TIBCO Rendezvous subject names are not supported for preregistered listeners.
Preregistration will not work when parametrized subjects are used.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
168 | Chapter 9 Advanced Features
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 the Apply button.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Changing the Location of the Ledger File | 169
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 TIB_ADADB_HOME/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.
When the adapter instance is restarted, it writes the ledger file to the new location. For
more information on using TIBCO Designer, see TIBCO Designer User’s Guide.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
170 | Chapter 9 Advanced Features
Sending Messages to an Adapter Instance
When TIBCO ActiveMatrix Adapter for Database 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 ActiveMatrix BusinessWorks, after some transformation has been performed.
Messages containing datetime data sent to TIBCO ActiveMatrix Adapter for Database
adapters must have that data in a string format. If it is in a different format, the TIBCO
ActiveMatrix Adapter for Database adapter will not be able to process the date values.
Formatting dates as strings allows the adapter to handle date values outside the range
allowed by RVMSG_DATETIME, January 1, 1970 to January 1, 2034.
The format used by the adbDateTime metadata class is described below.
adbDateTime Object
To view the structure of the adbDateTime class, from the project tree panel, navigate to
AESchemas > ae > ADB > adbmetadata > Classes > adbDateTime > dateTime
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.
Do not change any adbDateTime object information in this screen. Use this information to
determine how to format the third-party subscriber date value.
Timezone values are not supported.
The adapter will return an error when the input data contains timezone information. The
timezone information can be parsed using the TIBCO BusinessWorks XPath functionality
before passing it to the adapter.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publishing by Reference Object | 171
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 TIBCO ActiveMatrix Adapter for Database Concepts.
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 142. 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 the OK button.
If parent-child relationships are used, follow the steps under Adding Child Tables on
page 65 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 the Add
button. To select an object from a different schema, select Add From.
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
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
172 | Chapter 9 Advanced Features
Upsert to update a row in the destination table if the row exists and, if no such row
exists, perform an insert.
5. Click the Apply button.
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 the Apply button.
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 ActiveMatrix Adapter for Database Configuration and Deployment
Publishing by Reference Object | 173
Adding a Sequence
To add a sequence:
1. In the TIBCO Designer project tree panel, navigate to AESchemas > 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_child_table_name.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
174 | Chapter 9 Advanced Features
4. In the Select Sequence field, click the Browse button. 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 the OK button.
7. In TIBCO Designer, click the Apply button. 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 > 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 ActiveMatrix Adapter for Database Configuration and Deployment
Publishing by Reference Object | 175
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 the Apply button.
5. In the project tree panel, double-click the new association name to expand it.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
176 | Chapter 9 Advanced Features
6. In the Project panel, click Left Association to select it.
7. Enter a Role Name value that contains the reference object name. For example,
roleORDER_TABLE.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publishing by Reference Object | 177
8. In the Endpoint Class field, click the Browse icon. Navigate to the class that
represents the reference object, in this case ORDER_TABLE, and click the OK button.
9. In TIBCO Designer, click the Apply button.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
178 | Chapter 9 Advanced Features
The publishing table is created with necessary adapter fields, as well as CUST_ID and
ORDER_ID fields. When a row in CUSTOMER is modified, the trigger fires, populating fields
and copying the CUST_ID and ORDER_ID values, as well as the name of the reference object,
ORDER_VIEW, to the publishing table. When the adapter polls the publishing table, it detects
the new row. The adapter then selects the order and customer data from ORDER_VIEW, using
the CUST_ID and ORDER_ID values along with the view name found in the publishing table.
Then the message is published.
Table to Record Sequence Numbers (DB2 on iSeries)
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 ActiveMatrix Adapter for Database Configuration and Deployment
User Callout Library | 179
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
TIB_ADADB_HOME\demo\altermsg directory.
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.
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 ActiveMatrix Adapter for Database Configuration and Deployment
180 | Chapter 9 Advanced Features
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 or
XML wire format. Otherwise, leave the value as NULL.
Table 38 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.
pInst X MInstance of the message. Alter directly if necessary.
pMapp X TIBCO Adapter SDK MApp structure for this MInstance.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
User Callout Library | 181
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.
dataformat X X The data format of the message.
Valid values are:
M_RV_MESSAGE_FORMAT
M_AERV_MESSAGE_FORMAT
M_XMLJMS_MESSAGE_FORMAT
M_XMLRV_MESSAGE_FORMAT
Check TIBCO Adapter For SDK documentation for details
of these value.
Table 38 Wire Format Parameters and Descriptions (Cont’d)
Parameter R M Description
Table 39 adbPreCommit Parameter Descriptions
ParameterTIBCO Rendezvous Format
TIBCO ActiveEnterprise Format
Description
connectHandle X X The database connection handle.
pMapp X X TIBCO Adapter SDK MApp structure for this
MInstance.
pInst X MInstance of the message.
pTree X MTree containing the message.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
182 | Chapter 9 Advanced Features
Building the Callout Library
The callout library is build with TIBCO Adapter SDK and TIBCO Rendezvous software.
For compiler requirements and instructions, see the TIBCO Adapter for SDK guide.
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:
TIB_ADADB_HOME\demo\altermsg\altermsg.dsp
dataformat X X The data format of the message.
Valid values are:
M_RV_MESSAGE_FORMAT
M_AERV_MESSAGE_FORMAT
M_XMLJMS_MESSAGE_FORMAT
M_XMLRV_MESSAGE_FORMAT
Check TIBCO Adapter For SDK documentation
for details of these value.
Table 39 adbPreCommit Parameter Descriptions (Cont’d)
ParameterTIBCO Rendezvous Format
TIBCO ActiveEnterprise Format
Description
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 Appendix C, Adapter Properties File, on
page 329.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
User Callout Library | 183
3. Select Project > Settings. In the Project Settings dialog box:
a. As shown next, select the C/C++ tab. In the Category drop-down list, select
Preprocessor. In the Additional Include Directories field type the path to the
TIBCO Rendezvous include directory.
b. As shown next, select the Link tab. In the Category drop-down list, select Input.
In the Additional Library Path field, enter the path to the TIBCO Rendezvous
library directory.
4. Select Build > Build adbaltermsg.dll to create the library.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
184 | Chapter 9 Advanced Features
5. After building the library, change to the TIB_ADADB_HOME/lib 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 8:
RV_HOME=/usr/tibco/tibrv
2. Using a text editor open the MakeFile and set the SDK_Home environment variable. For
example:
SDK_HOME=/usr/tibco/adapter/sdk/5.6
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 TIB_ADADB_HOME\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 ActiveMatrix Adapter for Database Configuration and Deployment
Unique Connection Identifier for Oracle Databases | 185
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 ActiveMatrix Adapter for Database Configuration and Deployment
186 | Chapter 9 Advanced Features
Publishing in a Commitment Controlled Environment
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 iSeries system 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.
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
This feature applies only to DB2 on iSeries.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Publishing in a Commitment Controlled Environment | 187
iSeries 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 ActiveMatrix Adapter for Database Configuration and Deployment
188 | Chapter 9 Advanced Features
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 project_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 > adadb > Instance1.aeschemaproject_root > AESchemas > ae > adadb > 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 select Multi-User > Add Resources to RCS to add these files to the revision
control system.
For information about how to use the Multi-User feature in TIBCO Designer, see TIBCO
Designer User’s Guide.
Copy, Cut, Paste and Move Operations
To successfully copy and paste a service from adapter instance1 to instance2, the adapter
configuration and schema files for the instance2 must be checked out.
To successfully cut and paste a service from adapter instance1 to instance2, the adapter
configuration and schema files for both instance1 and instance2 must be checked out.
To successfully move a service from adapter instance1 to instance2, the adapter
configuration and schema files for both instance1 and instance2 must be checked out.
Regeneration When Moving, Copying and Pasting
• Default subjects are not regenerated to reflect the new instance name when a service is
moved.
• Manually changed certified messaging and certified messaging queue ledger file
names are regenerated to defaults when a service is moved, or copied and pasted to a
new instance.
• If a service associated with a custom session is moved, or copied and pasted, the
custom session is not moved, or copied and pasted. The session is regenerated as a
default session.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Using a Log File for an Adapter Instance | 189
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.
The adapter will trace to whatever sink is present in your adapter instance configuration. If
you have the default sinks of stdioSink and fileSink, the adapter will write to both the file and
stdout.
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.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
190 | 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 checked 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 the Apply
button.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Using a Log File for an Adapter Instance | 191
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.
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.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
192 | Chapter 9 Advanced Features
2. Click the Apply button. The following information displays:
3. In the Project 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. A global variable can be used for this field.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Using a Log File for an Adapter Instance | 193
File Count
Specifies the maximum number of log files that are created for this adapter instance. A
global variable can be used for this field.
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 ActiveMatrix Adapter for Database Configuration and Deployment
194 | Chapter 9 Advanced Features
Using Database Deployment and 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
TIB_ADADB_HOME\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 ActiveMatrix Adapter for Database Configuration and Deployment
Using Database Deployment and Cleanup Scripts | 195
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 Deployment Scripts
The generated SQL script for changes to database objects is stored in the instance_ name.sql
file under the TIB_ADADB_HOME\sql directory. You can modify this script to deploy
changes to different databases environment. For example, if the user schema is different
between the production and testing environment, you can change the schema name of the
database objects in the script and deploy the changes accordingly.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
196 | Chapter 9 Advanced Features
6. Select the adapter instance you were attempting to change when the errors occurred.
7. Save the project.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Changing the SQL Statement Terminator (DB2 for z/OS Only) | 197
Changing the SQL Statement Terminator (DB2 for z/OS 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 filen_ame
4. In the Window's Command Center, go to the Script menu and select options.
5. Check the Use Statement Termination Character checkbox 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 ActiveMatrix Adapter for Database Configuration and Deployment
198 | Chapter 9 Advanced Features
Fault Tolerance
Within the context of the adapter, a primary instance is the adapter instance that processes
messages between the TIBCO environment and the database. The secondary instance uses
the same adapter configuration but runs in a stand-by mode and takes over when the
primary instance goes down.
To run in the fault tolerance mode, the property adb.mutex has to be defined. The value of
this property is the name of the table that an adapter instance will attempt to lock.
At start up, if the adb.mutex property is present, the adapter will try to issue an exclusive
lock on the table defined by the value of this property before processing any messages.
The named table is created at run time if it does not exist. The adapter instance that is able
to lock this table is considered a primary instance. All instances that are not able to issue
an exclusive lock on this table are considered secondary instances. Instances that specifies
the same mutex table will be within a fault tolerance group.
The primary instance releases the lock prior to shutdown. If the primary instance
terminates for an unknown reason, the lock is collected by the database system. As soon as
the lock is released, one of the secondary instances will hold the lock and become the
primary.
Both the primary and secondary instances will use a separate database connection to issue
lock on the mutex table. The adapter will keep this connection active by executing a
dummy query from time to time.
You can customize the adapter fault tolerance feature with the following adapter
properties:
• adb.primary.heartbeat: The time interval that the primary instance will execute a
dummy select statement to the database in order to keep the connection that hold the
lock to remain active. Default value is 10000ms
• adb.secondary.heartbeat: The time interval that the secondary instance(s) will wait
before sending the next query message to detect the existence of a primary instance.
Default value is 10000ms
• adb.heartbeat (deprecated): If none of the above parameter specified, this value will be
used as both primary and secondary heartbeat. Default value is 10000ms
• adb.createMutexTable: By setting the TRA property to false, the adapter will not
create the mutex table during start up. Default value is on. User can use the following
SQL statement to create the mutex table before starting the adapter:
CREATE TABLE mutex_table_name (COL1 char(1))
• adb.maxQuery: The secondary instance will send a query message to detect the
existence of the primary instance. This is the number of queries for which if no reply
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Fault Tolerance | 199
is received the secondary instance will consider that a primary instance no longer
exists and will try to lock the mutex table.
• If the primary instance looses connection to the database, a reconnection will not be
attempted. The adapter instance will release the lock and gracefully shutdown letting
any secondary instance take over as the primary.
The time interval that the secondary instance(s) wait before attempting to lock the table
specified by the adb.mutex property is defined by the adb.heartbeat and adb.maxQuery properties.
Reconnection in the Fault Tolerance Mode
If the primary instance loses connection to the database, a reconnection will be attempted.
The adapter will perform reconnection base on the reconnection configuration, it will
gracefully shutdown if reconnection is not successful, letting any secondary instance take
over as the primary. If the secondary instance obtain the mutex lock while the primary
instance is reconnecting, the secondary instance will take over as primary. The original
primary instance will terminate if it cannot lock the mutex table after connection is
re-established.
On Oracle, you have to set the SQLNET.EXPIRE_TIME in sqlnet.ora script to a value greater than
0. This ensures that the server will collect the lock held by the invalid connection of the
primary instance due to connection lost.
On DB2, make sure the IDTHTOIN DSNZPARM parameter is greater than
adb.primary.heartbeat. This system parameter configures the timeout before the system
cancels an idle thread.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
200 | Chapter 9 Advanced Features
SSL Data Encryption using DataDirect ODBC Drivers
SSL data encryptions provide secure transmission of data. The adapter supports SSL data
encryption between the database and the adapter with DataDirect Wire Protocol ODBC
Drivers.
You may want to use data encryption in the following scenarios:
• You have offices that share confidential information over an intranet.
• You send sensitive data, such as credit card numbers, over a database connection.
• You need to comply with government or industry privacy and security requirements.
See ODBC Driver documentation for more information on the available features and the
required configuration details.
Data encryption may adversely affect performance because of the additional overhead
required to encrypt and decrypt data.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
OS Authentication | 201
OS Authentication
This release of the adapter provides SQL Server OS Authentication on Windows.
Microsoft SQL Server uses integrated login security to establish connections using this
data source, regardless of the current login security mode at the server. Any login ID or
password supplied is ignored. The Microsoft SQL Server system administrator must have
associated your Windows network ID with a Microsoft SQL Server login ID.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
202 | Chapter 9 Advanced Features
Query Timeout
This release of the adapter provides Query Timeout on all databases. The operation for
database would return with error instead of hang if it can not be completed when the
database server is busy. For the publication service, the polling operation would return
null and wait for the next polling. For the subscription service, it would return the
connection dead error, and then reconnect.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Working with Multi-File Format Projects | 203
Working with Multi-File Format Projects
The multi-file format creates one ActiveEnterprise XML file for each logical object (such
as an adapter instance, a set of related ActiveEnterprise classes, or a TIBCO ActiveMatrix
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 ActiveMatrix Adapter for Database,
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
For more information see TIBCO Designer User’s Guide.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
204 | Chapter 9 Advanced Features
Subscriber Reply Sender
The subscriber can be configured to send the subscription status as a reply to the message
sender if the message contains a reply subject. This AE schema
ADB_SUBSCRIBER_STATUS is used for this reply message:
Table 40 Description of ADB_SUBSCRIBER_STATUS Class Schema
Field Name AE Type Description
RETURN_CODE i4 return_code=0, when the data is inserted into destination table
successfully.
return_code=-1, when the data is inserted into exception table.
return_code=5, when the data is failed to insert in both destination and
exception tables.
If you specified subscriber pre-commit stored procedure, this field will
contain the value of the RETURN_CODE output parameter.
ADB_TEXT string Contains the status or error message of the subscriber operation.
CALLOUT_TEXT string Contains the error message from the database driver in case of error
operation.
If you specified subscriber pre-commit stored procedure, this field will
contain the value of the SP_TEXT output parameter.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Subscriber Pre-commit Stored Procedure Call | 205
Subscriber Pre-commit Stored Procedure Call
The subscriber can be configured to call a stored procedure 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.
User can specify this pre-commit stored procedure name in the Pre Commit Stored
Procedure field of the Subscription Service Subscriber Options.
The adapter will call the pre-commit stored procedure with the following syntax:
{call <pre-commit stored procedure name>(?, ?, ?)}.
This stored procedure need to be defined with a specific interface as specified below:
Table 41 Description of the Pre-commit Stored Procedure Parameters
Name Type Description
RETURN_
CODE
integer RETURN_CODE = 0, the adapter will assume the procedure was successful and write a
success message to the SDK INFO trace role when the verbose mode is used.
RETURN_CODE <> 0, the adapter will assume the procedure was not successful and
write SP_TEXT to the SDK ERROR trace role (whether verbose mode is on or off).
If the message has a reply subject, this output value will be returned to the message
sender. See Subscriber Reply Sender on page 204 for more details.
SP_TEXT varchar If the message has a reply subject, this output string will be returned to the message
sender. See Subscriber Reply Sender on page 204 for more details.
DO_ROLL
BACK
integer DO_ROLLBACK = 0, the adapter will commit the transaction and confirm the original
message.
DO_ROLLBACK <> 0, the adapter will rollback the transaction and not confirm the
message. Note, not confirming the message changes the RVCM behavior. All
subsequent RVCM messages will not be confirmed. It should only be done when this
RVCM behavior is really desired.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
206 | Chapter 9 Advanced Features
JMS Durable Subscriber Name
The JMS Durable Subscriber name can take the deployment time global variable value in
this release.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Runtime Schema | 207
Runtime Schema
In the case where the schema name of the tables objects are different between
development and production environment, you can use the following TRA properties to
specify the schemas configuration.
For all database environments other than IBM UDB iSeries (AS00):
• adb.originalSchema – Specify the design-time table objects schema.
• adb.runtime.schema – Specify the runtime table objects schema.
— If adb.originalSchema is specified, the adapter will compare the adb.originalSchema with the
prefix of the table objects. If they are the same, the adapter will replace the
design-time schema with this runtime schema. Otherwise, no action will be taken.
— If adb.orignalSchema is not specified, the adapter will append this runtime schema to
all table objects that do not have any schema specified at design time.
• adb.runtime.publisherSchema – Specify the runtime publisher table schema. This overrides
the adb.runtime.schema setting. This can be used if user has a different schema for the
publishing table then the other table objects such as source table.
For IBM iSeries (AS00):
• adb.as400.defaultLibrary – Specify the default iSeries library to be accessed.
• adb.as400.library – Specify the name of the runtime iSeries library where the adapter will
access.
These configurations do not apply to the referred object in publish by reference mode.
User need to specify the runtime schema for the referred object during the design time, or
in the ADB_REF_OBJECT column entry in the publishing table.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
208 | Chapter 9 Advanced Features
Runtime Table Schema Configuration
You can specify the runtime schema global variables in the administrator console during
the deployment of the adapter to enable the adapter to use these schemas in run time which
are different from the design-time schema configuration. This makes it easy for you to
move from one environment to another, most likely from the test environment to product
environment.
For publisher by reference object, you need to make sure the right schema and reference
object name are set correctly in the right publisher table, because the reference object
name is fetched from the publisher table, not an property from the design-time DAT file or
TRA file.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Group Message Transaction | 209
Group Message Transaction
This feature allows you to configure a group message to be processed within a single
transaction by the subscription service. The adapter will either commit the whole message
changes to the database, or none. See Subscriber Options Tab on page 82 for details.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
210 | Chapter 9 Advanced Features
Load Balancing and Multithreading
TIBCO ActiveMatrix Adapter for Database supports multithreading and load balancing to
improve the performance in high load scenario.
Improving Performance Using Threads
You can improve the adapter Subscription Service and Request-response Service
performance by specifying 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 the number of threads for a configuration:
1. In the Project panel, click the corresponding ActiveDatabase Adapter resource to
select it.
The TIBCO Designer window should look similar to the following:
2. Check the Show All Tabs checkbox.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Load Balancing and Multithreading | 211
3. Display the Adapter Services tab.
4. Change the value of Number Of Request-Response Service Threads or Number Of
Request-Response Service Threads as needed.
5. Click the Apply button.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
212 | Chapter 9 Advanced Features
Subscription Service
You can select Use Separate Service Thread in the Subscriber Options tab during design
time. When selected, a new session is created and the service endpoint is moved to this
session.
During runtime, the adapter will create a separate dispatcher to dispatch event from this
session. You can select other subscription service to use the same session by changing the
sessionReference field under the Advanced tab. This allows multiple services to share the
same session and dispatcher.
Request-Response Service
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
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Load Balancing and Multithreading | 213
connection to the database using the user name-password combination that was
provided to the adapter.
2. When an item is enqueued by the communication thread, one of the database
request-response threads picks it up and executes the one or more SQL statements in
the message as an atomic transaction.
3. It then composes a TIBCO Rendezvous self-describing response message and sends
back a response on a response subject. If the original request was sending using
rv_SendWithReply() or rv_Rpc(), the response is sent back on the subject that was specified
by the requesting application. Otherwise, the response is sent back on the subject that
was set up at configuration time.
Load Balancing Across Adapter Instances
Subscription and Request-Response Service
To achieve load balancing across adapter instances for subscription and request-response
services, TIBCO Rendezvous Distributed Queueing or TIBCO EMS Queue can be used to
assign each application request to exactly one adapter instance. For example, the
following diagram is an example for using TIBCO Rendezvous Distributed Queueing for
load balancing. It shows three adapter instances each connected to a database server (not
shown) that contains replicated data.
While the request message can be sent with either reliable or certified quality of service,
the response message is always sent back using the reliable quality of service.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
214 | Chapter 9 Advanced Features
Figure 6 Request-response Load Balancing
The adapter instances have been set up to use distributed queueing with one instance
acting as the scheduler. Only one of the three adapter instances will receive an incoming
request from an application. The scheduler will assign certified requests to the least loaded
member of the queue.
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.
Configuring an Adapter Instance to use TIBCO Rendezvous Distributed
Queues or TIBCO EMS Queue for Load Balancing
You can configure the adapter with a subscription service to use a distributed queue, then
use TIBCO Administrator Enterprise Edition to deploy multiple instances of the adapter.
The instances can be deployed on the same machine, or multiple machines. In this
scenario, each adapter instance uses the same (default) values for the distributed queue.
1. Start TIBCO Designer and create a new project.
2. Drag the ActiveDatabase Adapter Configuration icon to the design panel.
TIBCO Messaging
Application
Adapter 4
Adapter 3
Adapter 2
Adapter 1
(Scheduler)
Request
Request
Request
RequestResponses
Distributed Queue
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 ActiveMatrix Adapter for Database Configuration and Deployment
Load Balancing and Multithreading | 215
3. Configure the adapter instance with a design-time connection and ODBC DSN value.
4. Drag the ADBSubscriber icon to the design panel.
5. For using TIBCO Rendezvous transport, under the Configuration tab, select
Rendezvous in the Transport Type drop-down list, and Distributed Queue in the
Quality of Service drop-down list. For example:
For using TIBCO EMS Queue, set Transport Type to JMS and Quality of Service to
Queue.
6. Configure the service with a destination table name and other settings for your
environment.
7. Click Project > Save.
8. Click Tools > Create Project EAR. Under the Configuration tab, provide a name and
file location for the EAR file.
9. Click the Build Archive button.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
216 | Chapter 9 Advanced Features
Publication Service
You can check the Enable Load Balancing checkbox and specify the Mutex Name in the
Publisher Options tab during design time to balance load among multiple publication
service endpoints. Publication service with the same Mutex name specified will be in the
same load balance group.
When load balancing is enabled at design time, the adapter palette will create a publication
table with an additional column ADB_MARK.
At runtime, the publication services of the same load balancing group will create a mutex
table that was configured at design time, and poll the same publication table and distribute
loads. The service will synchronize by locking the mutex table to obtain and update the
sequence information.
Deploying an Adapter Instance for Load Balancing
After creating the EAR file, you are ready to import it into TIBCO Administrator
Enterprise Edition and add the adapter instance multiple times to the same machine or
multiple machines. Since these adapter instances have the same RVCMQ, EMS Queue, or
Mutex Name for publication configuration, they will participate as in same load balancing
group at runtime.
1. Start TIBCO Administrator Enterprise Edition.
When an adapter instance contains a publication service with load balancing enabled, it
can only run in batch polling mode. To turn on batch polling, enable the Use Polling
Batch Size option and specify the Polling Batch Size for the adapter instance.
For Sybase, the publisher load balancing feature requires the ddl in tran option be set to true:
sp_dboption database_name,"ddl in tran", true
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Load Balancing and Multithreading | 217
2. Select Application Management, then click the New Folder button. In Name, provide
a name for the folder and click the Save button.
3. Select the folder, then click New Application.
4. Click the Browse button and navigate to the EAR file you created in Designer. Click
the OK button.
5. In the dialog that appears, click the Save button.
6. Expand the configuration, then double-click the name.aar file.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
218 | Chapter 9 Advanced Features
7. Click the Add to Additional Machine button and select the machine to bind to and
click the OK button.
8. Repeat to create the number of adapter instances required for your environment. For
example, the next screen shows that three adapter instances have been added.
9. Click the Save button.
The adapter instances are ready to be deployed. After the instances are deployed, when a
message is sent to the adapter, the instance that is not busy will handle the request.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Compressing JMS Messages | 219
Compressing JMS Messages
JMS message compression is an instance-level option. It is especially useful when
messages are to be stored on the TIBCO Enterprise Message Service server, including
persistent queue messages, or topics with durable subscribers. Enabling compression
ensures that messages take less memory space in storage and are handled faster by the
TIBCO Enterprise Message Service server. When JMS messages are compressed and
stored, they are handled by the server in the compressed form.
The compression option only compresses the body of a message. Headers and properties
are never compressed. It is best to enable compression when the message bodies are large
and the messages are to be stored on a server.
When messages are not to be stored, compression is not as useful. Compression normally
takes time, and therefore the time to send or publish and receive compressed messages is
generally longer than the time to send the same messages uncompressed. There is little
purpose to message compression for small messages that are not to be stored by the server.
You can enable or disable this feature for message senders with the following adapter
property:
• adb.jmscompress: Either on or off. The default value is off, which indicates that messages will
not be compressed.
JMS message compression is only for publication service with JMS transport.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
220 | Chapter 9 Advanced Features
Configuring RVCMQ Backlog Size
The RVCMQ scheduler receives the inbound messages and assigns them to the worker.
The scheduler stores tasks in a message queue. You can limit the maximum size of that
queue with either one of the following two adapter properties or both of them:
• adb.taskBackLogLimitInBytes: Specifies the maximum size of the scheduler task queue by
number of bytes. This value must be an integer. The default value is unspecified.
• adb.taskBackLogLimitInMessages: Specifies the maximum size of the scheduler task queue by
number of messages. This value must be an integer. The default value is unspecified.
When the task messages in the queue exceed either of these limits, TIBCO Rendezvous
deletes new inbound task messages.
If neither of the above properties are specified, there will be no limit to the size of the
scheduler task queue.
RVCMQ backlog size configuration is for subscription and request-response services only,
which have RVCMQ or RVDQ transport, not for publication service, which does not have
this transport type.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 221
Chapter 10 Setting Encoding Options
This chapter describes how to use TIBCO ActiveMatrix Adapter for Database in an
international environment using non-ASCII languages.
Topics
• Overview, page 222
• Setting TIBCO Messaging Encoding, page 224
• Configuring the Adapter to Communicate with the Database, page 226
• Relevant Environment Settings, page 231
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
222 | Chapter 10 Setting Encoding Options
Overview
TIBCO ActiveMatrix Adapter for Database 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.
The following illustration shows an example of TIBCO ActiveMatrix Adapter for
Database in a Japanese language environment serving databases of different encodings.
The adapter converts the encoding between Unicode and the character sets of the
databases.
Figure 7 Example of Unicode Conversion
In this example, Shift-JIS encoded Japanese data is retrieved from an Oracle database by
the adapter 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.
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 garbling it.
Adapter Publishing Service
Adapter Subscription Service
TIBCO Messaging
Shift-JIS
UTF-8 UTF-8
EUC-JP
Oracle DB in Shift-JIS
Oracle DB in EUC-JP
Driver Manager/ODBC Driver/Database Client
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 223
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 ActiveMatrix Adapter for Database Configuration and Deployment
224 | 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
ActiveMatrix Adapter for Database, publication services use this encoding to publish data
into TIBCO messaging system, and subscription services use it to receive data from the
TIBCO messaging system.
There are currently two choices for TIBCO Messaging encoding: Latin-1 (ISO8859-1) for
transmitting ASCII and Latin-1 data, and UTF-8 for transmitting data of other languages.
The encoding property is set on the project itself at design time, and in the TIBCO
administration server’s property file when creating a TIBCO administration domain.
Encoding in a Server-based Project
The TIBCO administration server setting is used when the project is exported to a server
repository or deployed using TIBCO Administrator Enterprise Edition.
For a server based project, the TIBCO messaging encoding is set by the repo.encoding
property in the server's tibcoadmindomain_name.tra configuration file (located in
TIBCO_HOME/administrator/version/bin/).
The encoding is set when using the TIBCO Domain Utility to create the domain or by
editing the repo.encoding property in the TRA configuration file.
Each adapter or TIBCO application that uses the same server for storing and retrieving
configuration data uses this encoding setting when communicating to each other. This
assures that all TIBCO components (including adapters and other TIBCO applications)
that belong to the same project use the same encoding value to communicate.
Encoding in a Local Project File
If the project's configurations are saved in a local project file, which is the normal case
when the project is in design stage before deployment, the TIBCO Messaging encoding is
determined by the encoding property saved in the local project file.
The 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.
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 226 for more
information.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Setting TIBCO Messaging Encoding | 225
In order for different TIBCO components that each have their own local file repository to
communicate with each other without data garbled, they must use the same TIBCO
Messaging encoding, meaning that all these components must set their local project
encoding to the same value.
After a project is deployed as a server-based project, the encoding property set at design
time is superseded by the encoding property set for the TIBCO administration server.
The encoding property of a local project file is only for determining the TIBCO
Messaging encoding, not the encoding used for the persistent storage of the project files.
The project files are always saved as UTF-8 encoded files.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
226 | 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 ActiveMatrix Adapter for Database Configuration and Deployment
Configuring the Adapter to Communicate with the Database | 227
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, check
the Show All Tabs checkbox. In the General tab, choose the encoding that is
compatible with the encoding of the database instance to be connected to. See
Table 43, TIBCO ActiveMatrix Adapter for Database 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, See Appendix B in TIBCO Adapter Concepts.
— You can modify the adapter encoding property, adb.encoding, in the adapter’s TRA
configuration 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 Runtime 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 TIB_ADADB_HOME/odbc. In addition, you
must set the correct IANAAppCodePage to match the database encoding, if you are
using a wire protocol driver. See Table 42, IANAAppCodePage, on page 227 for a
list of IANAAppCodePage values. The complete list is available in
TIB_ADADB_HOME/odbc/help/odbcref/odbcref.pdf
— On Windows systems, use the Windows ODBC GUI to define a system DSN. Note
that if you are using a TIBCO wire protocol driver, the machine on which the
adapter is running must be on the locale that matches the database encoding.
Table 42 IANAAppCodePage
Value Encoding (Language)
3 ASCII (English)
4 ISO_8859-1 (Western European)
17 Shift_JIS (Japanese)
18 EUC_JP (Japanese)
38 EUC_KR (Korean)
113 GBK (Simplified Chinese)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
228 | Chapter 10 Setting Encoding Options
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 database has been converted to local system
encoding by the database client.
Special Configurations for Supporting a UTF-8 Database
This section applies only to TIBCO ODBC drivers.
2026 BIG5 (Traditional Chinese)
Table 42 IANAAppCodePage (Cont’d)
Value Encoding (Language)
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. See
the section Special Configurations for Supporting a UTF-8 Database on page 228.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Configuring the Adapter to Communicate with the Database | 229
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 ActiveMatrix Adapter for Database 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 UTF8.
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.
3. Set the NLS_LANG environment variable to language_territory.AL32UTF8 or
language_territory.UTF8 if using vendor or DataDirect non-wire driver.
Special Configurations for Retrieving Unicode Data from Database
To retrieve unicode data from unicode character data types such as NCHAR and
NVARCHAR, the following adapter properties are required:
adb.unicode — specify the unicode type of the data, either UTF8 or UTF16
adb.wchar — specify whether to retrieve the unicode code as character or binary string.
When adb.unicode is set, the adapter will automatically set the value of this property to
SQL_C_BINARY.
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.
When the adb.unicode option and the database national character set are both UTF8, the
adapter will add blanks after string values in published mess a age for nchar/nvarchar2
column.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
230 | Chapter 10 Setting Encoding Options
Runtime 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 ActiveMatrix Adapter for Database and Oracle NLS_Lang Values on
page 231 for a list of values.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Relevant Environment Settings | 231
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 ActiveMatrix Adapter for Database encoding values
as shown in TIBCO Designer.
Table 43 TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang Values
Adapter EncodingOracle NLS_LANG (containing NLS_CHARACTERSET)
Description
ASCII US7ASCII 7-bit ASCII
ISO8859-1 language_territory.WE8ISO8859P1 ISO8859-1 (Latin-1), West European
Shift_JIS (CP943) JAPANESE_JAPAN.JA16SJIS Japanese Shift-JIS, CP943
Shift_JIS (TIBCO) JAPANESE_JAPAN.JA16SJIS Variant of IBM-943 (created by TIBCO for
flavoring some MS-932 conversions)
KSC-5601 KOREAN_KOREA.KO16KSC5601 Korean KSC-5601
Big5 TRADITIONAL
CHINESE_TAIWAN.ZHT16BIG5
Traditional Chinese Big5 with Euro
GBK SIMPLIFIED CHINESE_CHINA.
ZHS16CGB231280
Simplified Chinese GBK (superset of
GB2312-80)
EUC-JP JAPANESE_JAPAN.JA16EUC Japanese EUC
UTF8 AMERICAN_AMERICA.UTF8 Unicode Transformation Format-8
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
232 | Chapter 10 Setting Encoding Options
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 233
Chapter 11 Monitoring the Adapter
Read this 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 49).
Topics
• Overview, page 234
• Starting TIBCO Hawk Software, page 235
• The Auto-Discovery Process, page 236
• Invoking Microagent Methods, page 237
• Available Microagents, page 240
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
234 | 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 ActiveMatrix Adapter for Database Configuration and Deployment
Starting TIBCO Hawk Software | 235
Starting TIBCO Hawk Software
The TIBCO Hawk agent can be configured to start automatically during the system boot
cycle. See TIBCO Hawk Installation and Configuration for information about starting
TIBCO Hawk.
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 ActiveMatrix Adapter for Database Configuration and Deployment
236 | 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 TIBCO Hawk Administrator’s
Guide.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Invoking Microagent Methods | 237
Invoking Microagent Methods
A set of default microagents is loaded when a TIBCO Hawk Agent is started. When you
install and start TIBCO ActiveMatrix Adapter for Database, 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 ActiveMatrix Adapter for Database Configuration and Deployment
238 | 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.
6. Click the Invoke button to invoke the selected method.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Invoking Microagent Methods | 239
The Invocation Results dialog displays the results returned by the method.
7. Click the Done button 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 TIBCO Hawk Administrator’s Guide.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
240 | Chapter 11 Monitoring the Adapter
Available Microagents
Each adapter has three microagents: a standard TIBCO Hawk microagent, a class
microagent, and a custom microagent.
When an adapter is started in TIBCO Designer or through a console, the available
microagents follow the below naming conventions:
• Standard Microagent: COM.TIBCO.ADAPTER.adb.%%Deployment%%.%%InstanceId%%
• Class Microagent: COM.TIBCO.adb.%%Deployment%%.%%InstanceId%%
• Custom Microagent:COM.TIBCO.adb.custom.%%Deployment%%.%%InstanceId%%
When an adapter is started from a deployed project in TIBCO Administrator, the available
microagents follow the below naming conventions:
• Standard Microagent: COM.TIBCO.ADAPTER.adb.domain_name.%%Deployment%%.%%InstanceId%%
• Class Microagent: COM.TIBCO.ADAPTER.adb.%%Deployment%%.%%InstanceId%%
• Custom Microagent:COM.TIBCO.adb.custom.%%Deployment%%.%%InstanceId%%
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
Microagents follow different naming conventions depending on how an adapter is started:
from TIBCO Designer, or from TIBCO Administrator.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Available Microagents | 241
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. 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 44 Standard Microagent Methods
Standard Method Description
activateTraceRole() Activates a mapping of a role to a sink at runtime.
deactivateTraceRole() Deactivates a mapping of a roles to sinks at runtime.
getAdapterServiceInformation() Returns information about the services implemented by
this adapter.
getComponents() Returns information about the publisher, subscriber and
IODescriptor.
getConfig() Returns basic configuration information. More specific
information is accessed by the more specific methods.
getConfigProperties() Returns a list of publishers and subscribers.
getHostInformation() Returns standard and extended application information.
getRvConfig() Returns information about all TIBCO Rendezvous
sessions defined.
getStatus() Returns general status information, such as the number
of TIBCO Rendezvous messages received and
published, the number of errors since the last call, the
PID of the application, and more.
getTraceSinks() Returns information about sinks to which traces
currently go.
getVersion() Returns the configuration ID, application name, version,
and date for this adapter instance.
_onUnsolictedMsg() Displays alert messages sent to the current adapter.
preRegisterListener() Preregisters an anticipated listener.
reviewLedger() Returns information retrieved from the ledger file of a
certified messaging session for a publisher adapter.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
242 | Chapter 11 Monitoring the Adapter
setTraceSinks() Adds a role or changes the file limit of a previously
specified sink.
stopApplicationInstance() Stops the running adapter instance.
unRegisterListener() Unregisters a currently preregistered listener.
Table 45 Custom Microagent Methods
Custom Method Description
getEventQueueSize() Retrieves the size of the TIBCO Rendezvous event
queue for the specified adapter instance.
setDebugLevel() Sets the debug level for the current adapter instance.
toggleVerboseFlag() Changes the value of the verbose flag from on to off, or
the reverse.
showConfiguration() Shows the configuration defined for the current agent.
terminateADBagent() Stops the current TIBCO ActiveMatrix Adapter for
Database agent.
getPollingInterval() Returns the current polling interval setting.
setPollingInterval() Set the polling interval for the publication service.
getPollingBatchSize() Get the polling batch size for the publication service.
setPollingBatchSize() Set the polling batch size for the publication service.
Table 46 Custom Microagent Methods with adb.perfMon
Custom Method Description
getActivityStatistics() Returns the total number of objects processed for all the
schemas, based on the request type. Also, returns the
number of success and error objects.
getActivityStatisticsByService Returns the total number of objects processed for each
of the schemas associated with the specified service.
getActivityStatisticsByOperation() Returns the total number of objects processed for all the
schemas by each service that is associated with a
specified operation.
Table 44 Standard Microagent Methods (Cont’d)
Standard Method Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Available Microagents | 243
getThreadStatistics() Return the operation counts of the current threads.
getQueueStatistics() Return the current count of elements in any internal
queue used by the adapter.
getConnectionStatistics() Returns the state and statistics for all the current
connections used by the adapter.
resetActivityStatistics() Resets all the counts for the activity statistics.
resetThreadStatistics() Resets all the counts for the thread statistics.
resetQueueStatistics() Resets all the counts for the queue statistics.
resetConnectionStatistics() Resets all the counts for the connection statistics.
Table 46 Custom Microagent Methods with adb.perfMon (Cont’d)
Custom Method Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
244 | 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 ActiveMatrix Adapter for Database Configuration and Deployment
deactivateTraceRole() | 245
deactivateTraceRole()
Purpose (Standard) Deactivates a mapping of a roles to sinks at runtime.
Parameters Parameters Type Description
Role Name string Name of the role to activate.
Sink Name string Name of a sink for which to activate the role.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
246 | 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
Returns
Parameter Type Description
Service Name string Name of the service from which to get information.
Default is ALL.
Returns Type Description
Line Integer Sequential row number.
Name string Name of the Service.
Endpoint string Name of the endpoint used for this service.
Type string Type of the endpoint, for example, Publisher,
Subscriber.
Quality of Service string Quality of service for the endpoint, for example,
RV, RVCM.
Adapter Name string Name of the application for this sink.
Session Name string Name of the TIBCO Rendezvous session.
Subject string Subject defined for this endpoint
Number of Messages Integer Number of messages processed for this endpoint.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
getComponents() | 247
getComponents()
Purpose (Standard) Returns information about the currently active TIBCO Hawk components such
as publishers, subscribers, or timers.
Parameters
Returns
Parameters Type Description
Component Name string Name of the TIBCO Hawk component. Default is all
components.
Component Type string Any of Publisher, Subscriber, Timer, or IODescriptor. The
default value is All.
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 ActiveMatrix Adapter for Database Configuration and Deployment
248 | 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
Connection
string URL of the repository used for adapter instance.
Configuration URL string Location of the adapter project; either a file name or
configuration URL.
Command string Command line arguments used to start the adapter.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
getConfigProperties() | 249
getConfigProperties()
Purpose (Standard) Returns all attributes and elements for the given repository object.
Parameters
Returns
Parameter Type Description
Property string Name of the property for which elements (tags) and
attributes are desired. For example, rvpub/startup.
If no value is given, all properties are returned.
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 ActiveMatrix Adapter for Database Configuration and Deployment
250 | 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 ActiveMatrix Adapter for Database Configuration and Deployment
getRvConfig() | 251
getRvConfig()
Purpose (Standard) Returns information about the TIBCO Rendezvous session defined by this
adapter. Information about all currently defined sessions is returned if no sessionName is
provided.
Parameters
Returns
Parameter Type Description
Session Name string Name of the TIBCO Rendezvous session for which
configuration is required (default is all).
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 ActiveMatrix Adapter for Database Configuration and Deployment
252 | 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 248 and getRvConfig() on page 251.
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 ActiveMatrix Adapter for Database Configuration and Deployment
getTraceSinks() | 253
getTraceSinks()
Purpose (Standard) Returns information about sinks to which traces currently go.
Parameters
Returns
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 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 ActiveMatrix Adapter for Database Configuration and Deployment
254 | 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 rvpub.
Version Version number as a string, for example 1.1.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
_onUnsolictedMsg() | 255
_onUnsolictedMsg()
Purpose (Standard) Displays all alert messages sent from the adapter or an error if not successful.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
256 | 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
Returns OK if the listener was preregistered successfully, false otherwise.
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
Name
string Name of the listener to preregister.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
reviewLedger() | 257
reviewLedger()
Purpose (Standard) Returns information retrieved from the ledger file of a TIBCO Rendezvous
certified messaging session. Before invoking this method, ensure that the certified
messaging publisher adapter has established a certified delivery agreement with its
subscriber agents.
Parameters
Returns
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 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 Name string Within each listener submessage, the Listener Session Name field contains the
name of the delivery-tracking listener session.
Last Confirmed string Within each listener submessage, the Last Confirmed field contains the sequence
number of the last message for which this listener session confirmed delivery.
Line integer Row number in ledger file.
UnacknowledgedMess
ages
integer Number of RVCM messages pending for this listener. The value is computed by
subtracting the last sent sequence number from the last acknowledged sequence
number.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
258 | Chapter 11 Monitoring the Adapter
setTraceSinks()
Purpose (Standard) Adds a role or changes the file limit of a previously specified sink.
Parameters
Returns OK if successful or an error if not successful.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
stopApplicationInstance() | 259
stopApplicationInstance()
Purpose (Standard) Stops the specified adapter by calling the internal stop() method.
Returns OK if successful or an error if not successful.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
260 | Chapter 11 Monitoring the Adapter
unRegisterListener()
Purpose (Standard) Unregisters a currently preregistered listener.
Parameters
Returns True if the listener was successfully unregistered, False otherwise.
Parameters Type Description
Publisher Name string Name of the component for which the listener should be
preregistered.
Listener Session
Name
string Name of the listener to unregister.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
getEventQueueSize() | 261
getEventQueueSize()
Purpose (Custom) Retrieves the size of the TIBCO Rendezvous event queue for the specified
adapter instance. For more information on events and event queues, see TIBCO
Rendezvous Concepts.
Parameters
Returns
Parameter Type Description
Session string Type of listener for this adapter instance. Possible values are
Subscriber or Request/Reply. The default value is Subscriber.
Return Type Description
QueueCount integer The number of events currently in the event queue.
QueueLimit integer The maximum number of events this adapter instance can have
in the event queue. This value is set using the
adb.rvMaxQueueSize option in the adapter’s properties file. The
default value is 0, which means the event queue has unlimited
size.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
262 | Chapter 11 Monitoring the Adapter
setDebugLevel()
Purpose (Custom) Sets the debug level for the current adapter instance.
Parameters
Returns Returns OK if successful or an error if not successful.
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 with the database shown.
2—ODBC data source for each SQL command shown.
3—All debug information displayed.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
toggleVerboseFlag() | 263
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 ActiveMatrix Adapter for Database Configuration and Deployment
264 | 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 with the database shown.
2—ODBC data source for each SQL command shown.
PollIntervalInfo string The poll interval in milliseconds.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
terminateADBagent() | 265
terminateADBagent()
Purpose (Custom) Stops the current TIBCO ActiveMatrix Adapter for Database 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 ActiveMatrix Adapter for Database Configuration and Deployment
266 | 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 ActiveMatrix Adapter for Database Configuration and Deployment
setPollingInterval() | 267
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 ActiveMatrix Adapter for Database Configuration and Deployment
268 | 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 ActiveMatrix Adapter for Database Configuration and Deployment
setPollingBatchSize() | 269
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 ActiveMatrix Adapter for Database Configuration and Deployment
270 | 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
Returns
Parameter Type Description
Get Subtotal By integer Statistics categorized by service or by operation.
Returns Type Description
Name string Name of the service or operation. The operation can be one
of the following:
Fetch
Poll
Insert
Update
Delete
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 ActiveMatrix Adapter for Database Configuration and Deployment
getActivityStatisticsByService | 271
getActivityStatisticsByService
Purpose (Custom with adb.perfMon) Returns the total number of objects processed for each of the
schemas associated with the specified service. Also, returns the number of success and
error objects.
Parameters
Returns
Parameter Type Description
Service Name string Name of the service.
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 ActiveMatrix Adapter for Database Configuration and Deployment
272 | 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
Returns
Parameter Type Description
Operation string Name of operation. Pick from one of the following form the
drop-down list.
Fetch
Poll
Insert
Update, and
Delete
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 ActiveMatrix Adapter for Database Configuration and Deployment
getThreadStatistics() | 273
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 ActiveMatrix Adapter for Database Configuration and Deployment
274 | 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 ActiveMatrix Adapter for Database Configuration and Deployment
getConnectionStatistics() | 275
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.
TotalNumOperations integer Total number of operations processed by this connection
since the adapter started.
CurrentNumOperatio
ns
integer Total number of operations processed by this connection
since the last reconnection.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
276 | Chapter 11 Monitoring the Adapter
resetActivityStatistics()
Purpose (Custom with adb.perfMon) Resets all the counts for the activity statistics.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
resetThreadStatistics() | 277
resetThreadStatistics()
Purpose (Custom with adb.perfMon) Resets all the counts for the thread statistics.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
278 | Chapter 11 Monitoring the Adapter
resetQueueStatistics()
Purpose (Custom with adb.perfMon) Resets all the counts for the queue statistics.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
resetConnectionStatistics() | 279
resetConnectionStatistics()
Purpose (Custom with adb.perfMon) Resets all the counts for the connection statistics.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
280 | Chapter 11 Monitoring the Adapter
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 287
Appendix A Frequently Asked Questions
This appendix lists answers to frequently asked questions.
Topics
• General Questions, page 288
• Request-response Questions, page 293
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
288 | 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. Navigate to Control Panel >
Administrative Tools > ODBC Data Sources. Activate tracing by clicking the Start
Tracing Now button 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 selecting Help >
Runtime Environment.
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 ActiveMatrix Adapter for Database detects it has lost its database connection, it
shuts down. You can configure the adapter for automatic reconnection (see Runtime
Connection Tab on page 45). 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 ActiveMatrix Adapter for Database Configuration and Deployment
General Questions | 289
Can an existing table be used as the publishing table?
No. TIBCO ActiveMatrix Adapter for Database 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 183.
If multiple updates occur between polling intervals, are updates published in multiple TIBCO
Rendezvous messages or a single large message?
If you are using publish by value, a TIBCO Rendezvous message is created for each individual
update. If you are using publish by reference, that operation will get the last update.
Is it possible to delete older entries in the publishing table?
Yes. When a row is published, the value of the ADB_L_DELIVERY_STATUS field in the
publishing table changes to either C (complete) or F (failed). You can write a trigger in
your publishing table that deletes the row when the delivery status changes to C or F.
You can also publish data directly from the source table by configuring the adapter
instance to publish by reference. A publishing table is created, but it contains only
required fields and key fields of the source table.
How does the exception table work?
Before starting an adapter instance, you must set the adb.useExceptTable option in the
adapter’s properties file to on and specify an exception table when configuring the adapter
instance. If an error occurs when inserting data into the destination table, it will be inserted
into the exception table. The transaction will be committed and a confirmation sent back
for the message (RVCM delivery). If the insertion into the exception table also fails, an
error message will display and the adapter instance will terminate.
Can an adapter instance be used to replicate binary types, such as BLOB?
There is only limited support for binary large object (BLOB) data types. Oracle LONG
and LONG RAW types are supported in top-level tables when the adapter is configured to
publish by reference. Oracle BLOB and CLOB data types are supported.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
290 | Appendix A Frequently Asked Questions
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 on referencing external
schemas, see TIBCO ActiveMatrix Adapter for Database Concepts.
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 ActiveMatrix Adapter for Database 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 ActiveMatrix Adapter for Database 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 ActiveMatrix Adapter for Database 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.
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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
General Questions | 291
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 ActiveMatrix Adapter for Database 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
ActiveMatrix Adapter for Database, so that we can use a standard naming convention
throughout the entire integration process?
No, the session names are fixed and used by TIBCO ActiveMatrix Adapter for Database
internally. They cannot be altered.
What’s the proper way to permanently remove an adbagent subscriber when using CM? One
way is to completely REMOVE the publisher’s ledger and to change all ’P’ records back to ’N’,
then restart the publisher. Is there a better, more correct or automated method?
There is a TIBCO Hawk method, unRegisterListener(), which unregisters a CM subscription.
This is the proper way to remove the adbagent subscriber as a CM listener.
Is it possible to run an adapter instance using a remote TIBCO Rendezvous daemon?
Yes. Change the default settings for network, service, and daemon parameters for the
adapter using TIBCO Designer.
Is it possible to run two configurations of the adapter on the same machine?
It's possible to run multiple configurations of the adapter on the same machine if each
adapter instance has a unique name. If both configurations use TIBCO Rendezvous
certified messaging, each must use a different RVCM session.
Can an adapter instance collate information from several database tables to send as a single
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
292 | Appendix A Frequently Asked Questions
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 76.
• 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 183 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 ActiveMatrix Adapter for Database Configuration and Deployment
Request-response Questions | 293
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 ActiveMatrix Adapter for Database Configuration and Deployment
294 | Appendix A Frequently Asked Questions
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 295
Appendix B Trace Messages
This appendix explains the trace messages in TIBCO ActiveMatrix Adapter for Database.
These include status messages, informational messages, error messages, and other types of
messages.
Topics
• Overview, page 296
• Status Messages, page 299
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
296 | 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 297. The following
example shows a trace message containing some of these fields and then identifies the
fields.
Example Trace Messages
The following trace messages were written during a session where TIBCO Adapter for
Files received an object from TIBCO Adapter for R/3, then processed the object.
Example 1:
Adapter Started
The following message indicates that TIBCO Adapter for Files has started. The timestamp
indicates when the adapter started, and the role indicates that the trace message is
informational, which means the activity is normal for the adapter. The category is
identified, and the corresponding status code is displayed. The status code indicates that
the adapter started successfully.
2003 Feb 22 20:14:51:718 GMT -8 FileAdapter.FileAdapterConfiguration Info [Configuration] AEFA-000058 TIBCO
Adapter for Files successfully initialized
2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter]
AEFA-000067 Message containing class /tibco/public/class/ae/Customer received on subject
FROM.SAP tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#
2003 Feb 22 20:15:12:937 GMT -8
FileAdapter.FileAdapterConfiguration
Info
[Adapter]
AEFA-000067 Message containing class
/tibco/public/class/ae/Customer received on subject FROM.SAP
tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#
Timestamp:
Adapter ID:
Role:
Category:
Status Code:
Tracking ID:
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Overview | 297
Example 2:
Message
Received
The next set of trace messages indicates the adapter received an object that was sent on the
TIBCO Rendezvous subject, FROM.SAP. The #MU3oTJ/WWCV1MU96J0zzwA9kzzw# tracking
identifier included in the trace message uniquely identifies the message. The adapter
(TIBCO Adapter for R/3) from which the message originated provided the identifier.
2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000067 Message
containing class /tibco/public/class/ae/Customer received on subject FROM.SAP
tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#
2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000068 Message
containing class /tibco/public/class/ae/Customer written to working file customers.txt in Working Directory
F:\ca\integration\001\data_sets\files\wip tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#
Example 3:
Object Moved
The final trace message indicates the object has been moved to the output directory, which
completes the adapter’s interaction with the object. Because the trace message is the
termination point, the tracking identifier is not displayed.
2003 Feb 22 20:15:42:812 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000070 File
customers.txt is moved to the Output Directory F:\ca\integration\001\data_sets\files\solutions\output
Trace Message Fields
Each trace message includes the following fields:
Table 47 Trace Message Fields (Sheet 1 of 2)
Field Name Description
Timestamp Timestamp of occurrence. For example, 2003 Feb 22 20:14:51:718 GMT -8.
Adapter Identifier Name of the adapter that wrote the trace message. This is a combination of the adapter acronym
and adapter configuration name. For example, the application identifier, ADB.publisher1
identifies a TIBCO ActiveMatrix Adapter for Database service named publisher1.
Role A role can be:
Info. Indicates normal adapter operation. No action is necessary. A tracing message tagged with
Info indicates that a significant processing step was reached and has been logged for tracking or
auditing purposes. Only info messages preceding a tracking identifier are considered significant
steps.
Warn. An abnormal condition was found. Processing will continue, but special attention from
an administrator is recommended.
Error. An unrecoverable error occurred. Depending on the error severity, the adapter may
continue with the next operation or may stop altogether.
Debug. A developer-defined tracing message. In normal operating conditions, debug messages
should not display.
When configuring the adapter you define what roles should or should not be logged. For
example, you may decide not to log Info roles to increase performance.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
298 | Appendix B Trace Messages
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 299 for details.
Tracking Identifier A unique identifier that is "stamped" on each message by the originating adapter. The tracking
identifier remains in effect from a message’s beginning to its completion as it is exchanged by
TIBCO applications. If the adapter is the termination point of the message, the tracking
identifier is not displayed in the trace message.
You cannot modify the tracking identifier format or configure what information is displayed.
Application
Information
Application-specific information added to the tracking info to trace the message back to its
source. Set initially by the originating adapter and carried forward. It is augmented by each
intermediate component.
Table 47 Trace Message Fields (Sheet 2 of 2)
Field Name Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 299
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 See an ODBC manual and 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 ActiveMatrix Adapter for Database Configuration and Deployment
300 | Appendix B Trace Messages
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.
AEADB-100017 Updated database
infoRole Adapter Normal operation; no action is necessary.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 301
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
302 | Appendix B Trace Messages
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
your project and re-configure the publication.
AEADB-200010 %1 cannot be larger than %2
errorRole Configuration Conflicting options are used. Check the log file and
restart the adapter with the correct options.
AEADB-200011 Unsupported encoding type: %1, Use default ASCII Encoding.
errorRole Configuration An unknown character set is detected. Check the
language configuration in the OS environment and
restart the adapter.
AEADB-200012 AEADB-POLLINGINTERVAL-NOVALUE-ERR
errorRole Configuration Unable to retrieve polling interval value from Hawk
method. Retaining original value of %1 milliseconds.
Please make sure a value is specified before invoking
the setPollingInterval method.
AEADB-200013 AEADB-POLLINGINTERVAL-NEGATIVE-ERR
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 303
errorRole Configuration Negative value of %1 for polling interval not
allowed. Retaining original value of %2
milliseconds. Please make sure to specify a
non-negative value for the polling interval.
AEADB-200014 AEADB-POLLINGINTERVAL-SAME-WARN
warnRole Configuration Polling interval already set to %1 milliseconds.
AEADB-200015 AEADB-POLLINGINTERVAL-CHANGED
infoRole Configuration Polling interval changed to %1 milliseconds.
AEADB-200016 AEADB-POLLINGBATCHSIZE-NOVALUE-ERR
errorRole Configuration Unable to retrieve polling batch size value from
Hawk method. Retaining original value of %1.
Please make sure a value is specified before invoking
the setPollingBatchSize method.
AEADB-200017 AEADB-POLLINGBATCHSIZE-NEGATIVE-ERR
errorRole Configuration Negative value of %1 for polling batch size not
allowed. Retaining original value of %2. Please make
sure to specify a non-negative value for the polling
batch size.
AEADB-200018 AEADB-POLLINGBATCHSIZE-SAME-WARN
warnRole Configuration Polling batch size already set to %1.
AEADB-200019 AEADB-POLLINGBATCHSIZE-CHANGED
infoRole Configuration Polling batch size changed to %1.
AEADB-200020 AEADB-POLLINGBATCHSIZE-CHANGED
warnRole Configuration The repository encoding should be set to UTF-8 if
your agent encoding is not ASCII or LATIN-1. Set
the repository encoding to UTF-8.
AEADB-300001 %1exception thrown in %2.
errorRole System An adapter internal error. Contact TIBCO Support.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
304 | Appendix B Trace Messages
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.
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 305
AEADB-300009 Out of memory building the WHERE clause
errorRole Adapter An adapter process has run out of memory. Increase
the amount of memory allowed to the adapter on
your system.
AEADB-400001 %1Unknown column name %2
errorRole Metadata Request is missing a column field in the Bind data.
Add a column, tableName.columnName field, to your bind
data.
AEADB-400002 %1Unknown column type: %2 for field: %3.
errorRole Metadata The type %2 is an invalid AE class type. Check in the
repository for attribute %3 and change the class type
to a valid AE class type.
AEADB-400003 Unknown column type, %1, %2
infoRole Metadata Normal operation; no action is necessary.
AEADB-400004 %1schema %2, tables: %3
debugRole Metadata
AEADB-400005 %1table %2, columns: %3
debugRole Metadata
AEADB-400006 Ill-formatted table name %1
errorRole Metadata A table name of this format is not supported by the
adapter. Use a different table name.
AEADB-600001 %1Failed to set limit policy for event queue %2 on session %3: %4
errorRole TibRvComm TIBCO Rendezvous failed to set the limit policy
according to the -rv-max-queue-size specification.
Please report this error text to TIBCO customer
support.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
306 | Appendix B Trace Messages
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-600005 MException thrown trying to publish message on "%1".
errorRole TibRvComm Unable to publish the message, check error
description for details. Check your daemon
connection.
AEADB-600006 %1Received ADVISORY %2
errorRole TibRvComm An unexpected TIBCO Rendezvous advisory was
received. See your TIBCO Rendezvous
documentation for resolution information.
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 307
AEADB-700004 %1database operation%2 succeeded
infoRole Adapter Normal operation; no action is necessary.
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
308 | Appendix B Trace Messages
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
AEADB-700023 %1Bulk insert turning off.
infoRole Adapter Normal operation; no action is necessary.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 309
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.
AEADB-700035 Parameterized subject %1 exceeds TibRv maximum subject length of %2
errorRole Adapter Shorten a parameterized subject string length.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
310 | Appendix B Trace Messages
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.
AEADB-700046 Confirming request
infoRole Adapter Normal operation; no action is necessary.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 311
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.
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
312 | Appendix B Trace Messages
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.
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 30.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 313
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.
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
314 | Appendix B Trace Messages
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.
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 315
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.
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
316 | Appendix B Trace Messages
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.
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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 317
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.
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-AEADB
_700301
Error executing listen_alert procedure call
errorRole Adapter Check the corresponding database error.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
318 | Appendix B Trace Messages
AEADB-AEADB
_700302
Error preparing listen_alert procedure call, stop alerter thread
errorRole Adapter Check if the listen_alert procedure exists in the
database and if the user has authorization to execute
it.
AEADB-AEADB
_700303
Listen_alert procedure call not found, stop alerter thread
errorRole Adapter Check if the listen_alert procedure exists in the
database and if the user has authorization to execute
it.
AEADB-AEADB
_700304
Cannot stop alerter successfully, stop_alerter_agent call failed.
errorRole Adapter Check if the listen_alert procedure exists in the
database and if the user has authorization to execute
it.
AEADB-AEADB
_700305
Error registering alerter, config_alerter procedure call failed, stop alerter thread
errorRole Adapter The alerter failed to add the AQ subscriber. Check if
the AQ database objects are configured properly in
the database and if the user has authorization to
access it
AEADB-AEADB
_700306
Error unregistering alerter, cleanup_alerter procedure call failed.
errorRole Adapter The alerter failed to remove the AQ subscriber.
Check if the AQ database objects are configured
properly in the database and if the user has
authorization to access it
AEADB-AEADB
_700307
Stopped ALerter
infoRole Adapter Normal operation; no action is necessary.
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
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 319
warnRole Adapter Reconnect failed on attempt %1 for service %2 --
will retry in %3 milliseconds. Make sure it is possible
to establish an ODBC connection to the database.
AEADB-890004 AEADB-CONN-PUBDUP
warnRole Adapter Connection reestablished for the publisher - message
may be a duplicate of a previously published
message.
AEADB-890005 AEADB-CONN-REQERR
errorRole Adapter The request received could not be processed due to
connection errors. Make sure it is possible to
establish an ODBC connection to the database.
AEADB-890006 AEADB-CONN-STOP
errorRole Adapter Adapter stopping due to persistent connection errors.
Please check your database and restart adapter. Make
sure it is possible to establish an ODBC connection
to the database.
AEADB-890007 AEADB-CONN-SVCSUSPEND
infoRole Adapter Adapter suspending service %1 due to persistent
connection errors.
AEADB-910004 AEADB-STARTUP-4
errorRole Startup Startup Error. SDK Exception %1 occurred in the
adapter initialization while creating the
MAppProperties object. The Repository URL is %2
and the Configuration URL is %3. Please see SDK
documentation for Repository URL and
Configuration URL specification. Please cut and
paste from SDK documentation for the above.
AEADB-910005 AEADB-STARTUP-5
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
320 | Appendix B Trace Messages
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. See 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. See the User Guide documentation.
AEADB-920001 AEADB-SUB-1
errorRole Subscriber Subscription error. Subscription service %1 listening
on %2 received an unexpected event: %3. The
Repository URL is %4 and the Configuration URL is
%5. Check the configuration of the application that is
publishing the event and make sure that it matches
the inbound event definition for the above
subscription service. Please see 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 see 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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 321
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 see 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 see 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.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
322 | Appendix B Trace Messages
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 see
User Guide for details on how to configure a
Publication service.
AEADB-940001 AEADB-REQRESP-1
errorRole Request_Respo
nse_Server
Request-Response error. Request-Response service
%1 listening on %2 received unexpected null data in
incoming request. Expects object %3. The
Repository URL is %4 and the Configuration URL is
%5. Please check the configuration of the application
that is requesting the event and make sure that it
matches the inbound event definition for the above
RequestResponse service. Please see User Guide for
details on configuration of RequestResponse service.
AEADB-940009 AEADB-REQRESP-9
errorRole Request_Respo
nse_Server
Request-Response error. Request-Response service
%1 listening on subject %2 failed due to database
error: %3Database is %4 and inbound event is %5.
Please check the target application command and the
parameters and make sure they are valid. Please look
at the database error, note the database error code and
consult with your database documentation.
AEADB-940010 AEADB-REQRESP-10
errorRole Request_Respo
nse_Server
Request-Response error. Request-Response service
%1 listening on subject %2 failed to create Reply
Business Object. Please check the database command
and the parameters and make sure they are valid.
AEADB-940012 AEADB-REQRESP-12
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Status Messages | 323
errorRole Request_Respo
nse_Server
Request-Response error. Request-Response service
%1 listening on subject %2 receive an error while
sending Data on Reply Address %3. Error Message
%4. Please check whether the request client is alive
or message transport is functioning.
AEADB-990002 AEADB-SHUT-2
errorRole Shutdown Shutdown error. SDK cleanup exception = %1.
Status Code Role Category Resolution (Cont’d)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
324 | Appendix B Trace Messages
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 325
Appendix C Adapter Properties File
Topics
• Overview, page 326
• Properties File Format, page 327
• Runtime Adapter Properties File Parameters, page 328
• Obfuscating or Encrypting a Password in the Properties File, page 341
• Using Hints, page 343
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
326 | Appendix C Adapter Properties File
Overview
The runtime adapter parses a properties file at startup. The default runtime adapter
properties file is named adbagent.tra.
The default properties file is located in the TIB_ADADB_HOME\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.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Properties File Format | 327
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 ActiveMatrix
Adapter for Database 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 341 for
more information.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
328 | Appendix C Adapter Properties File
Runtime 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 runtime adapter, the following properties
must be correct for the adapter’s configuration.
All paths inside a properties file, including Microsoft Windows directory names, must use
forward slashes.
Table 48 Required Runtime 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
tibco.configurl relative_path
or
tibco.configurl absolute_path
The location of the adapter service inside the project file. If a
relative path is specified, the adapter service is assumed to be
under the default area in the project file (/tibco/private/adapter/).
For example, the following value connects to an adapter
service named adbpub in the /tibco/private/adapter/ directory:
tibco.configurl adbpub
If an absolute path is specified, the adapter instance is looked
up in the repository as defined by the argument. For example:
tibco:configurl /tibco/private/adapter/adbpub
tibco.instanceid instance name The name of the adapter instance.
The length of the name cannot be larger than 80 characters.
tibco.clientVar.adb.password The password to connect to the targeted database. This can be
obfuscated using the instructions in Obfuscating or
Encrypting a Password in the Properties File on page 341.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Runtime Adapter Properties File Parameters | 329
Additional Properties
You can modify the following parameters as necessary. Properties that start with ntservice
are available only on Microsoft Windows platforms. The following table is alphabetically
sorted by the property name.
application.args The properties (.tra) file to pass to TIBCO ActiveMatrix
Adapter for Database. For example:
application.args adbagent -system:propFile
C:/tibco/adapter/adadb/6.0/bin/adbsub.tra
application.start.dir The pathname of the adapter to start. For example:
application.start.dir C:/tibco/adapter/adadb/6.0/bin/
application.library The name of the dynamic library of the adapter instance.
application.ase.library The name of the dynamic library of the adapter service
engine instance.
This property is used only on the UNIX platforms.
Table 48 Required Runtime Adapter Properties File Parameters (Cont’d)
Property Description
All paths inside a properties file, including Microsoft Windows directory names, must use
forward slashes.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 1 of 12)
Property Description
adb.publication_service_name.lookback Enables the adapter to look for remaining records if it
did not fetch the number of records specified by the
pollingBatchSize parameter for the publisher.
For example, if the publisher service name is
ADBPublisher, the property name is
adb.ADBPublisher.lookback.
adb.publication_service_name.preRegister
edListeners
Preregisters RVCM names for the specified subjects.
For example,
adb.ADBPublisher.preRegisteredListeners=adb.sub1:rvcm1,ad
b.sub2:rvcm2
preregisters RVCM name rvcm1 to subject adb.sub1,
and RVCM name rvcm2 to subject adb.sub2.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
330 | Appendix C Adapter Properties File
adb.table_name.poll.hint. hint_value This feature helps improve the performance of your
queries. This feature is only supported by Oracle and
SQLServer databases.
See Using Hints on page 343 for more information.
adb.addCustomHawkMethodsToClassMAgent
on|off The property is not set by default. Setting the
property to off disallows adding custom methods to
the adapter’s standard microagent. Setting to on
allows custom methods to be added to the adapter’s
standard microagent.
adb.as400.defaultLibrary The default iSeries library to be accessed.
adb.as400.library The name of the library where the programs will be
created.
adb.batchPubStatusUpdates on|off -max_rows When adb.PollingBatchSize is used, this optimizes
publishing performance by batching message status
updates to the publishing table. Do not use this option
when messages are published using a parameterized
subject name.
If an adapter instance stops before a batch update is
performed, the status column is not updated. As a
result, duplicate messages are published when the
instance is restarted.
adb.createMutextable When set to off, the adapter does not create the mutex
table that is used in the fault tolerance mode.
The mutex table can be manually created before
starting the adapter with the following SQL
command:
CREATE TABLE <mutex_table_name> (COL1 char(1))
The default value is on.
adb.customScaleForNumberType This property sets the default scale of Oracle
Number(empty) datatype.
adb.database The DB2 database name for OS390. The adapter uses
the value of this property when creating the table
used by the fault tolerance functionality.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 2 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Runtime Adapter Properties File Parameters | 331
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 with 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.disableTerminationSubject When this property is set to on, the adapter does not
terminate on receiving a termination subject
message.
adb.dsn ODBC system data source name. If not specified, the
system data source name is read from the repository.
adb.encoding The encoding to use. Required when using a
non-ASCII character set, as in globalization. See
Overview, page 228, and Relevant Environment
Settings, page 237, for more information.
Valid Values
The corresponding TIBCO Designer selection is in
parenthesis.
(no value) defaults to ASCII
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.groupsize Specifies the number of rows to publish in a single
message. Overrides the Group Size setting in the
publication service configuration.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 3 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
332 | Appendix C Adapter Properties File
adb.heartbeat The time interval, in milliseconds, the secondary
instance(s) waits before it tries to lock the table
specified by the adb.mutex property.
If neither the adb.primary.heartbeat or
adb.secondary.heartbeat properties are specified, the
value of this property will be used as both the
primary and secondary heartbeat.
Default value is 10000ms
adb.jmscompress on|off Applies only to the publication service with JMS
transport.
Either on or off. The default value is off, which
indicates that JMS messages will not be compressed.
adb.maxLongLen The buffer size. Used for long data types such as
BLOB.
adb.maxQuery The maximum number of queries the secondary
instance would send to the primary to determine if
the primary instance is still active. Default value is
3.
adb.mutex This is a table that is used by the fault tolerance
functionality. When an adapter instance starts and
this property is present, it will try to issue an
exclusive lock on the named table before processing
any messages.
The adapter instance that is able to lock this table is
considered a primary instance. All instances that are
not able to issue an exclusive lock on this table are
considered secondary instances.
The table name is shared within a fault tolerance
group. For example,
adb.mutex FTtablename.
adb.noDupDetection Disables detection of duplicate configurations.
Either on or off. The default value is off which
indicates that duplicate configurations will be
detected.
adb.originalSchema The design-time table objects schema.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 4 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Runtime Adapter Properties File Parameters | 333
adb.password Password for the user account used to access your
database. If not specified, the password stored in the
repository is used.
adb.payloadOnError on|off This property specifies whether only the error
information or all the logging information is printed
in the log file.
Either on or off. The default value is off. If it is on or
the Generate Payload On Error checkbox on the
General tab is checked when configuring an adapter
instance, and the Log Info Messages checkbox on the
Logging tab is unchecked, only the error log
information will be printed.
adb.perfMon on|off Either on or off. The default is off.
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, 000
milliseconds, is used.
adb.PollingCommitForDB2 Either on or off. The default is off.
adb.primary.heartbeat When using the adapter in the fault tolerance mode,
this is the time interval (in ms) for which the adapter
waits before issuing a dummy select statement.
This select statement is used to maintain the
connection that holds the lock.
Default value is 10000.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 5 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
334 | Appendix C Adapter Properties File
adb.pubBatchConfirmSize Applies only to publisher instances with publications
that use certified message delivery. Optimizes
performance by batching message status advisories to
the publishing table. The value indicates the number
of advisory messages to include in a single batch.
Do not use this option when messages are published
using a parameterized subject name.
Note: If an adapter instance stops before a batch
update is performed, the status column is not
updated. As a result, messages that were successfully
published might still have a status of P (pending) in
the publishing table when the adapter instance is
restarted. In this case, the ledger file contains the
correct status information. A smaller value for this
property decreases this risk.
adb.pubBatchConfirmTimeout Applies only to publisher instances with publications
that use certified message delivery. This property
specifies the number of milliseconds to wait before
updating the status column. After this interval, an
update is performed even if the batch size value is not
reached. The default value is 10,000 (10 seconds). A
value of 0 means that no timeout interval is used.
Do not use this option when messages are published
using a parameterized subject name.
Note: If an adapter instance stops before a batch
update is performed, the status column is not
updated. As a result, messages that were successfully
published might still have a status of P (pending) in
the publishing table when the adapter instance is
restarted. In this case, the ledger file contains the
correct status information. A smaller value for this
property decreases this risk.
adb.publishChildData Either on or off. Applies only to publisher instances.
Enables publishing of table rows related to the source
publishing table. By default, related table rows are
not published.
adb.RequestResponseMaxRows This property specifies the maximum number of rows
to fetch. This can be used limit the memory usage of
the adapter. The unfetched rows will be ignored by
the adapter.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 6 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Runtime Adapter Properties File Parameters | 335
adb.requestResponseThreads The number of threads used by the Request/response
Service. The default value is 1.
adb.RetryTotal Total number of reconnection attempts.
adb.runtime.publisherSchema The runtime publisher table schema. This overrides
the adb.runtime.schema setting. This can be used if the
user has a different schema for the publishing table
than the other table objects, such as the source table.
adb.runtime.schema The runtime table objects schema.
• If adb.originalSchema is specified, the adapter
will compare the adb.originalSchema with the
prefix of the table objects. If they are the
same, the adapter will replace the
design-time schema with this runtime
schema. Otherwise, no action will be taken.
• If adb.orignalSchema is not specified, the
adapter will append this runtime schema to
all table objects that do not have any
schema specified at design time.
adb.rvAdvisoryNoLog on|off This property specifies whether RV advisory
messages are be logged in the adapter log files. The
default value is off.
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.secondary.heartbeat The time interval that secondary instance waits
before sending the next query message to detect the
existence of the primary instance.
Default value is 10000.
adb.setClientInfo on|off When set to on, the adapter will call
SET_CLIENT_INFO to set the database session
client information.
The default value is on.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 7 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
336 | Appendix C Adapter Properties File
adb.setEmptyStringNullForRvMsg on|off Either on or off. Specifies whether the RVMSG fields
of an empty string are treated as NULL or "" (empty
strings). The default setting is off.
If the property value is set to on, empty strings are
treated as NULL and if the property value is set to off,
empty strings are treated as empty strings if the
database allows it.
adb.SleepBetweenRetries Milliseconds of sleep between two reconnection
attempts.
adb.stmtCache The number of cache statements for a generic RPC
request/ reply service.
The number of statements that the adapter will cache
so that it will execute the statement directly for
repeated requests. If the cache is full, the adapter will
remove the oldest message from the cache and will
add the new statement. The default setting is off.
Example, adb.stmtCache 10
adb.subBatchCommitSize Applies only to subscriber instances. The number of
messages to batch before invoking a commit
operation. The default is 0(zero).
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,000 milliseconds 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.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 8 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Runtime Adapter Properties File Parameters | 337
adb.tablespace The DB2 tablespace name for OS390. The adapter
uses the value of this property when creating the table
used by the fault tolerance functionality.
adb. taskBackLogLimitInBytes The scheduler stores tasks in a queue. This property
limits the maximum size of that scheduler task queue
by the number of bytes. The properties can control
the memory usage on the adapter side.
This value must be an integer. The default value is
unspecified, which indicates that there is no limit to
the size of the scheduler task queue.
adb. taskBackLogLimitInMessages The scheduler stores tasks in a queue. This property
limits the maximum size of that scheduler task queue
by the number of messages. The properties can
control the memory usage on the adapter side.
This value must be an integer. The default value is
unspecified, which indicates that there is no limit to
the size of the scheduler task queue.
adb.terminateOnPubFail Specifies that if publication fails, the agent will
terminate after the status has been updated to ’F’. The
default value is off.
adb.traceOldMessages on|off Either on or off.
adb.unicode The unicode setting.
The default value is UTF8.
Valid values are UTF8 and UTF16
Additionally, the following options have to be set:
On Microsoft Windows, select the Enable N-CHAR
option from the Advanced tab when configuring the
ODBC system data source.
On UNIX platforms, set the EnableNcharSupport option
to 1 in the ODBC initialization files.
See the ODBC driver documentation for more
details.
For Microsoft SQL Server, set the value of this
property to UTF16.
adb.useBetweenClause This property disable the use of the BETWEEN
clause in the select query of the publisher.
The default value is on.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 9 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
338 | Appendix C Adapter Properties File
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.useSqlColumns on|off Either on or off. Specifies whether the adapter should
use SQLColumns() instead of a SELECT query to
retrieve metadata for a table.
Note: Typically, a SELECT * FROM <table> WHERE 1>9
(which returns no results) is the fastest way to get
metadata for that table. However, on some databases,
such as DB2 OS390 v6, the database is not optimized
for this query and a full table scan can result. Using
an ODBC API call, SQLColumns(), can avoid this.
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_CHAR. Required when using
UTF-8 encoding with an adapter that uses a
DataDirect driver to retrieve UTF-8 data from the
database.
If the adb.unicode is set, this property is set by
default to SQL_C_BINARY to retreive unicode data.
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/6.0/bin/adbagent.exe
ntservice.dependencies The number of dependencies.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 10 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Runtime Adapter Properties File Parameters | 339
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 true|false Either true or false. Specifies whether the Windows
Service is interactive. Set to false if you are not using
a system account.
ntservice.name Name for this Windows Service.
This property is useful if you wish to have multiple
Windows Services for the same executable. That is,
you may wish to have two adapters running on the
same machine. By specifying different service names
and display names for the adapters, you can
accomplish this.
For example:
ntservice.name adapter_instance_name
ntservice.password Password for the username in the ntservice.account
property.
You can use this property to initially set the password
for the user account, but once the service is installed,
use the Services control to change the password.
ntservice.starttype manual|automatic 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.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 11 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
340 | Appendix C Adapter Properties File
tibco.clientVar Runtime values for global variables defined inside
the repository. This value takes precedence over any
global value set in the repository. Substitution takes
place at runtime.
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/6.0/myledger
Do not include the % character of substitution
variables. For example, to set
%%RvDaemon%%="tcp:7500", use tibco.clientVar.RvDaemon
"tcp:7500".
tibco.username
tibco.password
User name and password used by the repository
server to access the project. The password can be
obfuscated using the instructions in Obfuscating or
Encrypting a Password in the Properties File on
page 341.
-version Displays a banner with version information, then
exits. This option is for troubleshooting purposes
only.
Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 12 of 12)
Property Description
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Obfuscating or Encrypting a Password in the Properties File | 341
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 runtime, 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.5, and use the configuration with a 4.x adapter version, some special
considerations are required for security.
If you plan to run the adapter locally, define the runtime password value to be a global
variable. Before starting the adapter, include the runtime 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
Obfuscating a Password
The runtime 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 runtime, you open the .tra file
and add the password in clear text in the tibco.clientVar.adb.password=#password property. You
can use the obfuscate tool to hide this password so it cannot be viewed by unauthorized
users.
To obfuscate the password:
1. Using TIBCO Designer, open the adapter configuration and display the Design-time
Connection tab.
2. Uncheck the Remember Password checkbox.
3. Apply the changes and save the project. This saves the global variable
%%adb.password%% as the value of the password property in the project.
Do not set the password by typing Password in the Global Variables section for adapter
configurations that are set to AE Version 4.0 or AE Version 5.0 (in the Version field of the
Configuration tab) or any intermediate version.
If you don’t want to obfuscate the password, remove the # at the beginning of the
password.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
342 | Appendix C Adapter Properties File
4. In the runtime 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 with the properties file. This tool is
named obfuscate.exe and resides in the TIBCO_HOME\tra\version\bin directory.
The command syntax is:
obfuscate TRA_file_path
where TRA_file_path is the absolute pathname of the adapter properties file that
contains the tibco.clientVar.adb.password=#password property.
For example, on Microsoft Windows :
C:\tibco\tra\version\bin>obfuscate C:\tibco\adapter\adadb\version\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.x 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:
Repo.serverPassword = #!mysecret
2. Invoke the obfuscate utility from the command line:
TIBCO_HOME/tra/version/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 ActiveMatrix Adapter for Database Configuration and Deployment
Using Hints | 343
Using Hints
Hints help improve the performance of your queries. When the adapter publication service
executes a poll operation to fetch data from a table, using hints greatly enhances the query.
Usage
To use hints add the following line to the adapter TRA properties file:
adb.table_name.poll.hint hint_value
where, table_name is the name of your table and hint_value is the hint.
Note that in this release hints are only supported in Oracle and SQL Server databases.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
344 | Appendix C Adapter Properties File
Examples
a. To force an index scan when polling in an Oracle database, set the property as
follows:
adb.p1.poll.hint /*+INDEX(P1,P1_INDX)*/
where p1 is the publisher table, and P1_INDX is the index created on the publishing
table.
The adapter will execute this select query on the publishing table:
SELECT /*+INDEX(P1,P1_INDX)*/ * FROM P1 WHERE ID = ?
b. To use NOLOCK hint when polling in a SQL Server database, set the property as
follows:
adb.p1.poll.hint WITH(NOLOCK)
where P1 is the publisher table.
The adapter will execute this select query on the publishing table, but will not issue
shared locks or honor exclusive locks:
SELECT * FROM P1 WITH(NOLOCK) WHERE ADB_L_DELIVERY_STATUS =’N’
c. To force an index scan when the adapter fetches records from a child table set the
property as follows:
adb.C1.poll.hint /*+INDEX(C1,C1_INDEX)*/
where C1 is the child table, and C1_INDEX is the index created on the child table.
The adapter will execute this select query on the child table:
SELECT /*+INDEX(C1,C1_INDEX)*/ * FROM C1 WHERE ID = ?
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
| 351
Index
Symbols
_ 30, 167
. 168
* 167
> 167
A
access to DB2 AS/400 tables 69
adapter
changing a configuration 31, 199
component (operation) information through TIBCO
Hawk 253
error messages when changing a configuration 32
naming restrictions 30
size limitations 30
stopping 30
tracing 194
unicode setting 343
adapter configuration, changing 31, 199
Adapter Services folder 6
adapter setting client info 340
ADB_ERROR_TEXT 154
ADB_ERROR_TIME 155
time zone 155, 157
ADB_L_CMSEQUENCE 148
ADB_L_DELIVERY_STATUS 148
ADB_OPCODE 147, 154
ADB_REF_OBJECT column in the publishing table 175
ADB_SEQUENCE 146
ADB_SET_SEQUENCE 146
ADB_SOURCE 153, 153
ADB_SUBJECT 146
ADB_TIMESTAMP 147
timezone 147
ADB_UPDATE_ALL 147, 154
adbDateTime 174
adbPreCommit() 185
adding
listeners 171
adding a sequence for parent-child 177
adding an association for parent-child 178
advanced folder 6
agents 240
alerter
on Sybase SQL Server 110
alerts 240
auto-discovery process, TIBCO Hawk 242
B
binary type 169
bind statements 121
C
callout library 183
certified message delivery
exception handling 291
moving ledger files 173
preregistering listeners 171
changes from the previous release xvi
Class Microagent Name field, adapter 60
closure field 120
column names in an exception table 156
column names, reserved prefix 31
columns, maximum number 30
command line arguments 254
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
352 | Index
commands
adbagent 108, 112
Connect 41, 45
copy 107, 111
cp 110
isql 107, 108, 110, 111, 112
select 22, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23,
23, 23, 23, 24, 24, 24, 24, 24, 24, 24, 24, 25, 25, 25,
25, 26, 26, 26
sqlplus 19, 26, 105, 106
tibrvsend 25
commit_and_notify_table 103
CONFIG_HOME xviii
configuration properties, retrieving through TIBCO
Hawk 254
custom RPC operation 131
customer support xxi
D
dat file format 16
data source, ODBC
using 335
database errors, capturing 154
database type mapping 167
Date types 169
date/time values 174
dateTime 164
DB2 on OS/390 trigger statements syntax 202
debug, adapter option 334, 334
delete trigger 67
Destination 167
distributed queues 138, 218
dot character 168
dsn, adapter option 335
E
ENV_NAME xviii
error messages about database cleanup 32
examples
REF cursor procedure 143
Exceed FAQ 293
exception table
structure of 154
exception table, column names in 156
F
fault tolerance 337
file format
dat 16
VC 16
Float data type 169
G
global variables 32
setting for monitoring 59
L
ledger files
location 173
moving 173
publication size status 338
publication timeout status 339
retrieving information through TIBCO Hawk 263
listeners, adding 171
load balancing
across adapters 138, 218
in an adapter 136, 215
Log File field, adapter 53
log file options 194
log files location 55
Log to Standard field, adapter 53
LONG data type 77
loop detection
column used for 153
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Index | 353
M
mapping database types 167
metadata 7
microagent methods supported 247
Microagent Session field, adapter 60
multiple file project 208
N
naming restrictions
adapters 30
database columns 31
publishing table 76
subjects 167
notify procedure
on Microsoft SQL Server 107
on Sybase 110
notifytable procedure
on Microsoft SQL Server 107
on Sybase 110
NULL attributes 83
O
obfuscation 331
P
palettes 6
parameterized subject 168
binary type 169
Date types 169
Float type 169
illegal characters 169
parameters
AE Type 68, 84
Child Table Mapping 85, 86
Class Reference 80, 89, 94
Deploy On Save 31
Do Not Generate Triggers 76
Enable Loop Detection 76
Endpoint Reference 80, 89, 94
Join To 68, 84
Publishing Table 76
Reply Subject 94
Subscriber Bulk Insert Size 50
Table Name 85, 86
Tables and Columns 68, 84
Type 68, 84
Update Mode 76
Update Trigger 68
Use? 68, 84
User Key 68, 84
parent-child association 178
parent-child sequence 177
password property 346
PL/SQL procedure for REF cursor 143
preregistering listeners 171
publications
size limitations 30
publish-child-data, adapter option 339
publishing
by reference 77
source data 175
publishing table
columns in 146
name size 76
restrictions for 77
Q
quality of service
and load balancing 138, 218
queue member load 139, 219
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
354 | Index
R
record size, limitations 30
REF data type 143
reference object location 175
repository instance 7
request
defined 118
request/response
load balancing for 138, 218
using 116
using multiple threads 136, 215
response defined 119
reviewLedger, TIBCO Hawk method 263
RPC programs, client 133
rv_Rpc() 122
rv_Send() 122
rv_SendWithReply() 122
RVMSG_DATETIME 164
RVMSG_INT 164
RVMSG_OPAQUE 164
RVMSG_REAL 164
RVMSG_STRING 164
S
schema changes affecting adapter configuration 32
schema data 7
schemas
for related tables 69
See 168
sequence number 146
source data publishing 175
source data publishing example 181
source table
loop detection column 153
SQL statement terminator 202
SQL_BATCHRETURN class, structure of 129, 129
SQL_BIND class, structure of 130, 130
SQL_OPS class, structure of 127
SQL_RESULTSET class, structure of 128
SQL_RETURN class, structure of 128
SQL_ROW class, structure of 128
SQL_STATEMENT class, structure of 130, 130
standard RPC operation 126
starting an alerter on Oracle 103
stopping an adapter 30
sub-batch-commit-timeout, adapter option 341
sub-bulk-insert-size, adapter option 341
subjects
naming restrictions 167
parameterized 168
subscriber 30
using wildcards 167, 171
subscriptions
size limitations 30
wire format for 174
substitution 32
support, contacting xxi
system
configurl command-line argument 332, 332
T
table access problems, overcoming 69
technical support xxi
TIB_ADADB_HOME xviii
TIBCO Hawk
background information 240
enterprise monitor components 240
methods supported 247
Monitoring tab use with 59
TIBCO Hawk methods
getComponents 253
getConfig 254
getRvConfig 257
getStatus 258
reviewLedger 263
TIBCO Rendezvous, retrieving configuration through
TIBCO Hawk 257
TIBCO_HOME xviii
Tracing 296, 296
tracing features 194
Tracing Levels and Fields 297, 297
tracking identifier 296, 299
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
Index | 355
triggers
no primary key 67
U
underscore character 167
update trigger 67
Use Advanced Logging field, adapter 55
user authority 69
user callout library 183
user schema 102
username property 346
use-trace-file, adapter option 194
V
variable substitution 32
variables 32
version, adapter option 346
W
wildcard subject names 167, 171
Top Related