Beruflich Dokumente
Kultur Dokumente
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 LICENSE.PDF) 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. TIB, TIBCO, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Rendezvous, TIBCO Administrator, TIBCO Designer, TIBCO Runtime Agent, TIBCO Hawk, TIBCO Enterprise Message Service, TIBCO Designer Add-in for TIBCO Business Studio, TIBCO ActiveMatrix Service Grid, TIBCO ActiveMatrix Service Bus, TIBCO ActiveMatrix BusinessWorks Service Engine, and TIBCO Business Studio are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. 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-2009 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information
| iii
Contents
Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 TIBCO Administration Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 TIBCO Administration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 TIBCO Administrator GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Adapter Project Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Create the Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Configure the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Start the Adapter Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
iv
| Contents
Change the Table Values and Receive Notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Exit the Query Tool and Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Clean Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Adapter Instance Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Design-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Connection Settings Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving Connection Settings for Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Saved Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 43 44 45
Run-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Adapter Services Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 All Subscription Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 All Request-Response Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 General Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Logging Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Startup Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Monitoring Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
64 64 65 65 67 67 69 71 75 76 76 77
Contents v
Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Subscription Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Table Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Child Table Mappings Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Child Exception Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscriber Options for DB2 on OS/390 (z/OS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscriber Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request-Response Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Call Operation Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 82 84 86 87 87 89 90 92 92 95 96
vi
| Contents
TIBCO Rendezvous Message Request Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 TIBCO ActiveEnterprise or XML Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 TIBCO Rendezvous Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 RPC Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Custom RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing Client RPC Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 129 133 136
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Load Balancing in a Single Instance Using Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Load Balancing Across Adapter Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Oracle REF Data Type Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Source Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Exception Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Child Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Using an Exception Table as a Source Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Opaque Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Incremental Parent-child Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sybase and Sybase Adaptive Server Anywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping to Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 162 162 163 163 164
Contents vii
Table to Record Sequence Numbers (DB2 on iSeries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 User Callout Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the alterMsgPub and alterMsgSub Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the adbPreCommit Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building the Callout Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 182 183 184
Unique Connection Identifier for Oracle Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Publishing in a Commitment Controlled Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Using the Adapter with a Revision Control System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Using a Log File for an Adapter Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fine-Tuning Tracing Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Log File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Advanced Logging Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 193 195 195
Using Database Cleanup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Change the SQL Statement Terminator (DB2 for z/OS Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Fault Tolerance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 SSL Data Encryption using DataDirect ODBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Working with Multi-File Format Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
viii
| Contents
Appendix B Trace Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Status Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Figures ix
Figures
TIBCO Administrator GUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Diagram of Publish-Subscribe Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Alerter Operation (Oracle and MSSQLServer 2005) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Request-Response Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Example of Unicode Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
| Figures
Tables xi
Tables
Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 Table 14 Table 15 Table 16 Table 17 Table 18 Table 19 Table 20 Table 21 Table 22 Table 23 Table 24 Table 25 Table 26 Table 27 Table 28
General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Values to Use for TIBCO Rendezvous and JMS Transport Types . . . . . . . . . . . . . . . . . . . . . . . . 18 Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Adapter Instance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Design-Time Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 JDBC Drivers and URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Run-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Publication Service Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Subscription Service Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Request-Response Service Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 General Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Logging Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Startup Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Monitoring Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Publication Service:Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Publication Service Tables tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Publication Service DB2/OS390 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Publication Service DB2/AS400 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Publication Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Subscription Service Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Subscription Service Child Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Subscription Service Child Exception Table Mappings Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Subscriber Options for DB2 on OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Subscription Service Subscriber Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Subscription Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Request-Response Service Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Request-Response Call Operation Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Request-Response Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
xii
| Tables
Table 29 Table 30 Table 31 Table 32 Table 33 Table 34 Table 35 Table 36 Table 37 Table 38 Table 39 Table 40 Table 41 Table 42 REQUEST Schema Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 REPLY Schema Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Publishing Table Additional Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Mapping to Database Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Wire Format Parameters and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 adbPreCommit Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 IANAAppCodePage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang Values . . . . . . . . . . . . . . . . . . 215 Standard Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Custom Microagent Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Custom Microagent Methods with adb.perfMon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Required Run-Time Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Additional Run-Time Adapter Properties File Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
| xiii
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
Related Documentation, page xiv How to Contact TIBCO Customer Support, page xvii
xiv
| Related Documentation
Related Documentation
This section lists documentation resources you may find useful.
Preface xv
Typographical Conventions
The following typographical conventions are used in this manual Table 1 General Typographical Conventions Convention
TIBCO_HOME ENV_HOME
Use Many TIBCO products must be installed within the same home directory. This directory is referenced in documentation as TIBCO_HOME. The 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. Incompatible products and multiple instances of the same product are installed into different installation environments. The directory into which such products are installed is referenced in documentation as ENV_HOME. The value of ENV_HOME depends on the operating system. For example, on Windows systems the default value is C:\tibco.
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.
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 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
xvi
| Typographical Conventions
Table 1 General Typographical Conventions (Contd) Convention Key combinations Use 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.
Preface xvii
|1
Chapter 1
Introduction
271
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
| 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, and Microsoft SQL Server 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 78. 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 79. Publish on parameterized subjects, which allows a subject to be created from the contents of one or more table columns. See Parameterized Subject Names on page 166. Preregister certified subscribers with a certified publisher. See Preregistering a Certified Subscriber on page 168. 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 71. Specify that a group of rows fetched from the publishing table is sent in a single message. 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 168. Perform batch commits based on message count or time out value. See Adapter Instance Tabs on page 39.
Overview 3
Use request-response semantics to publish SQL statements, stored procedures, or both on a specified subject: Execute stored procedures with IN parameters, OUT parameters, or both. (Binary OUT parameters are not supported. This is a limitation of the Oracle ODBC driver.) See Oracle REF Data Type Support on page 145.
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 120 and RPC Mode on page 128. Change published messages for a publication or subscription service by customizing the supplied callout library. See User Callout Library on page 181. Customize adapter behavior to suit your needs: Specify relationships between tables, then publish related tables together. See Tables Tab on page 69. Monitor for database changes using periodic polling or notification by an alerting mechanism. See Adapter Services Tab on page 48.
Rely on standards: Connect to multiple database vendors using ODBC or JDBC drivers. See Design-time Connection Tab on page 42 and Run-time Connection Tab on page 46. Interoperate with other TIBCO products through the use of TIBCO Adapter SDK software. See Sending Messages to an Adapter Instance on page 172. Monitor your adapter service using TIBCO Hawk software. See Monitoring Tab on page 60 and Chapter 11, Monitoring the Adapter, on page 217. Choose message transports: TIBCO Rendezvous or Java Messaging Service (JMS).
Configure the adapter easily using TIBCO Designer. See Chapter 3 on page 29.
| 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
Menu bar
Project panel
Palette panel
Configuration panel
Configuration 5
Project Panel Each TIBCO Designer window contains one and only one project, which is represented as the root folder in the panel. 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.
| Chapter 1
Introduction
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. 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 Apply 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 Reset 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
Configuration 7
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. 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.
| 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.
Deployment 9
Deployment
After an integration project has been developed and tested, it is necessary to deploy the run-time 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.
10
| Chapter 1
Introduction
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 run-time 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 98 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 99 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. Start the Adapter
Task I
The adapter is started and stopped using the TIBCO Administrator GUI.
See Start or Stop the Adapter on page 100 for more information.
14
| Chapter 1
Introduction
| 15
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 16 Create the Database Tables, page 20 Configure the Properties File, page 21 Start the Adapter Services, page 23 Change the Table Values and Receive Notification, page 24 Exit the Query Tool and Adapters, page 26 Clean Up, page 27
16
| 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.
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 Users Guide for more information. That document also describes the multi-file format used by TIBCO Designer, and converting to and from the .dat file format used by the run-time adapter. The TIBCO Designer Users Guide is available from TIBCO Designer by clicking the Help>Designer Help menu choice.
Tables
The tables are created by running a script specific to your database vendor. The script creates the following tables, all with a common set of columns:
Source table to which you will add new data. Publishing table to which the new data from the source table is copied using
the trigger set on the source table. This table has additional columns (prefixed by ADB_) that are used by the adapter.
Overview 17
Destination table that TIBCO ActiveMatrix Adapter for Database will update
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
Insert Trigger
Publishing Table
Source Table
Adapter Publisher
Adapter Subscriber
TIBCO Messaging
18
| Chapter 2
Tasks
Getting Started
This exercise consists of the following tasks: Create the Database Tables Configure the Properties File Start the Adapter Services Change the Table Values and Receive Notification Exit the Query Tool and Adapters Clean Up
Exercise
This exercise uses the Oracle database. You can use the TIBCO Rendezvous or JMS transport. When performing this exercise, use the appropriate transport values for your configuration (as listed in Table 2) and follow the instructions that pertain to your particular database vendor. You will need the following information, specific to your user environment: Database user ID Database password Database service
The values you will enter for the tables and the publisher and subscriber adapter instances are different, depending on which transport type you are using. (The kind of database you are using does not affect these names.) Table 2 Values to Use for TIBCO Rendezvous and JMS Transport Types Item Source Table Publishing Table Destination Table Exception Table Publisher Adapter TIBCO Rendezvous Transport Value
ORDER_TABLE PUB_ORDER SUB_ORDER SUB_ORDER_EXCEP rvpub
Overview 19
Table 2 Values to Use for TIBCO Rendezvous and JMS Transport Types Item Subscriber Adapter TIBCO Rendezvous Transport Value
rvsub
20
| Chapter 2
Getting Started
2. Execute the demo1_databaseVendor.sql script in the subdirectory to create the tables for your database. Use your environment-specific user ID, password, and database service. For example:
> sqlplus
userid/pswd@dbService @demo1_ora.sql
The script creates the items and displays the status. For example:
C:\TIBCO\adapter\adadb\<version_number>\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>
Value
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. 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.password
pwd
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.
For example:
C:\TIBCO\adapter\adadb\<version_number>\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
22
| Chapter 2
Getting Started
. . .
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.
2. Open a new command window and change directory to the adapter bin directory. For example:
> cd c:\tibco\adapter\adadb\<version_number>\bin
3. In separate command windows, start the publisher and subscriber adapters for your database. If using TIBCO Rendezvous:
> adbagent --propFile C:\TIBCO\adapter\adadb\<version_number>\demo\demo1 \rvpub.tra > adbagent --propFile C:\TIBCO\adapter\adadb\<version_number>\demo\demo1\ rvsub.tra
24
| Chapter 2
Getting Started
2. Invoke the query tool using the environment-specific user ID, password, and database service specified in Create the Database Tables, page 20.
> sqlplus
userid/pswd@dbService
3. Insert three values into the source table, then commit the change. If using TIBCO Rendezvous:
SQL> insert into ORDER_TABLE values(111,'Oak Table',499.95); SQL> commit;
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
The following example result confirms that the data has been inserted:
ITEM_ID
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.
26
| Chapter 2
Getting Started
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
Note that the tibrvsend program is typically not used to terminate the adapter. Instead, a JMS program typically sends a JMS message to the JMS termination destination configured for the adapter.
Clean Up 27
Clean Up
This cleanup script removes the example tables that were created by the demo1_cleanup_databasevendor.sql script. 1. In a command window, change directory to the demo1 directory. For example:
> cd c:\tibco\adapter\adadb\<version_number>\demo\demo1\
userid/pswd@dbService @demo1_cleanup_databasevendor.sql
For example:
> sqlplus karlh/karlh@ORCL @demo1_cleanup_ora.sql
28
| Chapter 2
Getting Started
| 29
Chapter 3
This chapter explains how to create an adapter instance by configuring standard settings. All configuration tasks are performed in TIBCO Designer and the information is stored in a project that is later used by the run-time adapter.
Topics
Overview, page 30 Adapter Instance Tabs, page 39 Configuration Tab, page 40 Design-time Connection Tab, page 42 Run-time Connection Tab, page 46 Adapter Services Tab, page 48 General Tab, page 52 Logging Tab, page 54 Startup Tab, page 59 Monitoring Tab, page 60
30
| Chapter 3
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 30 Saving the Project, page 31 Testing the Adapter, page 31 Notes on Configuring an Adapter, page 32 Configuration Recommendations, page 33 Changing an Existing Configuration, page 33
Overview 31
6. As necessary, modify the following default values for the instance: Default startup state and session, metadata search URL: see Startup Tab on page 59 Standard, class, and default MicroAgents: see Monitoring Tab on page 60 Logging options: see Logging Tab on page 54 Termination subject, encoding, and debugging options: see General Tab on page 52 Threads, polling, publishing child data, bulk insert size, TIBCO Rendezvous queue size, exception table: see Adapter Services Tab on page 48 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 services Configuration tab, set the combination of options for each service. This is required. 9. As necessary, define tables, mappings, message and reply subjects, endpoints, and other service options. 10. Save the project as a server repository project. After configuring the adapter, create the run-time adapter property file and add the project name and adapter instance name. Also define and test the run-time connection options for the instance if you did not do it earlier. See Run-time Connection Tab on page 46.
32
| Chapter 3
You should be aware of the following before starting or configuring an adapter. A database account must have been created for running the adapter. For details, see the TIBCO 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 Run-time Connection Tab on page 46). 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 100.
Overview 33
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: The wire format for both the publishing and destination tables must be the same, otherwise an error will occur. Publisher and subscriber information should be defined in the same project for all cases. When using parent-child tables or the XML wire format, define the publisher and subscriber in the same repository. The following limitations apply to TIBCO Rendezvous transport type parameterized subject names: Do not insert the * or > character as an attribute value (varchar, char) in a column that is part of a parameterized subject. Do not insert data of Float type as an attribute value in a column that is part of a parameterized subject. Do not use Date type columns as part of a parameterized subject. Dates generally contain characters such as dashes and spaces that do not work well as part of a subject.
34
| Chapter 3
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 services schema. This is important when another adapter instance is also associated with the same schema. If an adapter instance is renamed, the schema associated with that configuration is also renamed, and if another configuration is associated with that same schema, the association will become invalid once the schema is renamed.
If legitimate changes to the database result in error messages while you are trying to save the changes, you may need to run the cleanup script that the adapter creates during the save operation. For more information about these error messages and using the script, see Using Database Cleanup Scripts on page 198.
Overview 35
Variables can be used anywhere in the configuration and will be replaced by the locally-defined adapter instance. Variable Specification The adapter can specify variables: In the project during configuration using TIBCO Designer. In a properties file. In TIBCO Administrator Enterprise Edition when deploying the project.
The values in the properties file or Enterprise Edition take precedence over the values set in the project through TIBCO Designer. Specifying Variables Using TIBCO Designer Global variables provide an easy way to set defaults for use throughout your project. For example, you could assign the value 7474 to the predefined global variable RvDaemon. You can then use the variable in different sessions in your adapter. If you wish to change the TIBCO Rendezvous daemon for your adapter, you can globally set it to a different value or override it from the command line. To Specify Global Variables: 1. In the project panel, select the Global
Variables
tab.
36
| Chapter 3
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 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 3 Predefined Global Variables Variable
Deployment
Description
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.
Overview 37
Description (Contd)
Specifies the path name of the TIBCO Rendezvous certified messaging ledger file. The default is the root installation directory. Specifies the path name for log file used by the adapter. The default is the root installation directory. 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. 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. Tells applications where the JMS SSL daemon is located. TIBCO Rendezvous routing daemon (rvrd) to be used. See TIBCO Administrator Server Configuration Guide for details about setting up a domain using rvrd. TIBCO Rendezvous daemon. Sessions use this daemon to establish communication. The default value is 7500. 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.
DirTrace
Domain
JmsProviderUrl
JmsSslProviderUrl RemoteRvDaemon
RvDaemon
RvNetwork
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.
38
| Chapter 3
Table 3 Predefined Global Variables (Contd) Variable (Contd) RvaPort Description (Contd)
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. 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.
TIBHawkDaemon
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.
40
| Chapter 3
Configuration Tab
You must define the options on this tab before other options can be configured. Click Apply to apply the changes before leaving this dialog.Table 4, Adapter Instance Configuration. Table 4 Adapter Instance Configuration Field
Adapter Name Instance Name
Description
(Read only) The value of this fields is set to Database_Adapter_Configuration. This is the name that was specified when creating the adapter configuration. See Guidelines for Choosing an Instance Name on page 41 for more information.
Description 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 against a 4.x run-time adapter, the instance must be saved with the Version field set to AE Version 4.0. If you are using TIBCO Designer 5.x to modify 4.x adapter instances, change only features supported by the 4.x. run-time adapter and use the validation utility to verify the instance before deploying the project. Invoke the utility from the Project>Validate Project for Deployment menu command in Designer.
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 Programmers Guide for information about writing a message filter. Select this box to display additional tabs for configuring advanced options.
Configuration Tab 41
Field
Vendor
Description 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.
(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.
Select this box if you want to write configuration settings to the database when this project is saved. This is the default mode.
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.
42
| Chapter 3
Description 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.
Refer to Table 6, JDBC Drivers and URLs for the supported JDBC Drivers and the assciated URLs
User Name
The database user that the design-time adapter uses to connect to the database. The password for the database user. 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%%.
This field is not used. 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 43.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
JDBC URL: jdbc:tibcosoftwareinc:sqlserver:// servername:1433;databaseName=databaseName Note: Default port number is 1433. Sybase JDBC Driver: tibcosoftwareinc.jdbc.sybase.SybaseDriver JDBC URL: jdbc:tibcosoftwareinc:sybase://servername:
5000
Note: Specify a databaseName parameter (as shown in the SQL Server description above) if connecting to a database that is not the default database. Sybase Adaptive Server Anywhere DB2 OS390 JDBC Driver:
com.sybase.jdbc2.jdbc.SybDriver
JDBC URL: jdbc:sybase:Tds:localhost:2638/asademo JDBC Driver: tibcosoftwareinc.jdbc.db2.DB2Driver JDBC URL: jdbc:tibcosoftwareinc:db2://servername:port; locationName=DB2locationName;packageName=packageNamePrefix
DB2 AS400
DB2 UDB
44
| Chapter 3
To populate the fields with default values, select ActiveDatabase>Connection then select your database type from the submenu. The following screen sample shows Oracle being selected.
templates,
4. Click either Yes or No: 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,
Yes
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.
The fields on the Configuration and Connection tabs are populated with the values stored in the parameter set.
46
| Chapter 3
Description 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 adapters properties file or on the command line. This is the database user that the run-time adapter uses to connect to the database. This field is automatically populated when you select a template as described in Using Connection Settings Templates on page 43. It cannot be changed here. 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 43. It cannot be changed here. 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.
User Name
Password
The total number of reconnection attempts to make after the service has been suspended. When this number is reached, the run-time adapter or adapter service will be stopped. A value of -1 means reconnection attempts will continue indefinitely.
Field
Number of Reconnect Attempts Before Suspending Impacted Service(s) Interval between Reconnect Attempts (milliseconds) Adapter Termination Criteria (after max number of reconnect attempts) Test Connection
Description Specify the number of reconnection attempts to make before suspending the service. This value is 1 and cannot be changed.
Specify the time interval (in milliseconds) to elapse between each reconnection attempt.
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. This option is not used.
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.
48
| Chapter 3
Description
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. 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. 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. (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. (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.
Polling Interval
Field
Publisher Batch Confirm Size
Description
(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.
(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.
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 60. For information on adding related tables for a subscriber adapter, see Child Table Mappings Tab on page 76.
50
| Chapter 3
Description
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. 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.
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. 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 subscribers memory from overflowing if the publisher is too fast. Select this box to use an exception table. The exception table is defined when you create a subscription service.
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. 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.
Description
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. 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.
52
| Chapter 3
General Tab
This tab allows you to set a termination subject or topic and specify the encoding type, debug level, and verbose mode. Note that the adapter should communicate only with other applications that support the same code pages or Unicode. Click Apply to apply the changes before leaving this dialog. Table 11 General Configuration Options Field
Termination Subject or Topic
Description
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 Users Guide for information about publishing on a topic.
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 run-time 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 run-time adapter will throw an error if the encoding value you type is not supported.
General Tab 53
Field
Debug Level
Description
This field is valid only when the Debug logging option is selected, as described in Logging Tab on page 54. Select how much debugging output to provide at the console window or log file location specified in the Log File field. The options are: No debug information Only SQL commands executed against the database Only the ODBC data source for each SQL command All debug information
This field is valid only when the Information logging option is selected, as described in Logging Tab on page 54. Check this box to include verbose output (all available information) at the console window or log file location specified in the Log File field.
Allows you to change the location where the SQL script file is written. The name of the alerter service register in the database.
54
| Chapter 3
Logging Tab
Use these settings to configure a log file or log sinks, including which types of trace messages you want logged and where they are sent. Click Apply to apply the changes before leaving this dialog. Table 12 Logging Configuration Options Field
Use Advanced Logging
Description
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 57 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. 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 34 for more information. Type the name and file system path, or click Browse and select an existing log file. If no file name is specified, trace information is not written to a file. Log Info/ Debug/ Warning/ Error Messages Select the types of trace messages you want logged.
Log File
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
Logging Tab 55
logged are any TIBCO Rendezvous or TIBCO Adapter SDK errors that appear at startup time before tracing can be initialized. Logging trace messages is helpful for troubleshooting. There are four levels of trace messages that you can log: Information, Warning, Debug, and Error. Trace messages are described and listed in Appendix B, Trace Messages Logging affects system performance. It is recommended that you use logging only as needed. 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 option is not selected. In this mode, you configure a standard log file using the fields on this tab, as shown in the example below.
When you select Use Advanced Logging, you configure log sinks using icons in the TIBCO Designer project panel. This gives you complete control on selecting the destinations and associating desired roles with each of the destinations.
56
| Chapter 3
Logging Tab 57
Creating Log Sinks 1. Check the Use Advanced Logging box. 2. Click Apply. 3. In the TIBCO Designer project panel, select the Log Advanced folder.
Sinks
4. Select an existing log sink or create a new one: Select the File or STDIO log sink icon. Create a new log sink by dragging and dropping the Generic log sink icon from the palette panel into the design panel, then assign a type to it from the drop down menu in the configuration panel. Click Apply.
58
| Chapter 3
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, is selected.
stdout
Hawk sink sends each trace message to TIBCO Hawk Monitor or TIBCO Hawk Display using the Hawk session, which is created by the adapter for monitoring purposes. Specify the MicroAgent Name. (For details on Hawk sessions, see Using Global Variables on page 34.) Network sink publishes each trace message on TIBCO Rendezvous. Specify the session and the subject on which the trace messages needs to be published. .
Startup Tab 59
Startup Tab
Do not change the setting in this tab. This tab displays the default startup behavior. Table 13 Startup Options Field
Show Startup Banner
Description
The startup banner displays the run-time adapter version, the infrastructure version on which the adapter is built, and copyright information in the console window when the adapter is started. 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.
60
| Chapter 3
Monitoring Tab
These settings do not need to be configured unless TIBCO Hawk is installed. You can use microagents to supplement the monitoring information provided by the standard logging capability. Examples of supplemental information that you can obtain with microagents include the repository URL and the command line arguments used to start the adapter. Click Apply to apply the changes before leaving this dialog. See Chapter 11, Monitoring the Adapter, on page 217 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 14 Monitoring Configuration Options Field
Enable Standard Microagent
Description
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. This is the name for the standard microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used, COM.TIBCO.ADAPTER.adb.%%deployment%%.%%InstanceId%%. The value for the %%deployment%% global variable can be set or modified by selecting the session icon and then clicking the Global Variables tab in the project panel. The %%InstanceId%% variable does not need to be set because it is automatically set at run time by the run-time adapter.
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. 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.
Monitoring Tab 61
Field
Class Microagent Name
Description
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%%. 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. 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.
62
| Chapter 3
| 63
Chapter 4
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 64 Adding Child Tables, page 71 Publication Service Tabs, page 67 Subscription Service Tabs, page 82 Request-Response Service Tabs, page 92
64
| Chapter 4
Overview
The transport type (Rendezvous or JMS) you select for the run-time adapter determines which quality of service, delivery mode, and wire format the service can use. Only options that are compatible with a services 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
Overview 65
Queue
listener objects. Even though many members listen for each inbound message (or task), only one member processes the message. For details on distributed queues, see TIBCO Rendezvous Concepts.
See Load Balancing Across Adapter Instances on page 140 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 the TIBCO Enterprise Message Service Users 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 (JMS transport type only) 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.
Wire Formats
Services must use the same wire format to exchange data. Rendezvous Message (TIBCO Rendezvous transport type only) 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)
66
| Chapter 4
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
An externally-described XML wire format supported by the TIBCO Adapter SDK. Control information for validation is sent in the message. If no control information is included, an exception is returned to the subscriber. TIBCO ActiveEnterprise standard wire format provides class information and packing rules for the TIBCO Adapter SDK set of data types. This format allows TIBCO ActiveEnterprise components to perform extra validation on messages sent or received. See the TIBCO Adapter SDK Programmers Guide for details about the control information generated and sent with TIBCO ActiveEnterprise messages.
Configuration Tab
The wire format for the publication and subscription services must be the same, otherwise an error will occur. . Table 15 Publication Service:Configuration Tab Field
Name Transport Type
Description
You can use the default name or replace it with a name of your choice. Select the transport type (JMS or TIBCO Rendezvous) to be used by the run-time adapter. This selection determines which options appear in the rest of the Configuration tab. The transport can be configured to use a trusted store and identity resource for use in SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field which uses a dialog to perform SSL configuration. To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.
Quality of Service
(Only available when TIBCO Rendezvous is selected as the transport type) Select the level of service that determines how messages are sent. See Quality of Service on page 64 for a description of these options.
Reliable Certified
68
| Chapter 4
Description
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 65 for a description of these formats. ActiveEnterprise Message (TIBCO Rendezvous transport type only) Rendezvous Message (TIBCO Rendezvous transport type only) XML Message
(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 65 for a description of each mode. Persistent Non-Persistent
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. 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 42 tab must have the proper set of permissions granted. This is described in Referencing an External Schema on page 70. If a primary key is not defined for a table, the update and delete triggers will not be generated for the table. To define a primary key for the table, select the User Key column in a table row. The update and delete triggers will then be defined.
Icons
Add Table Click to display a dialog box that list tables available to the database user specified in the adapter Connection tab. Select the source table to publish from when data is inserted into it.
Displays a dialog box from which a secondary table can be added to the configuration.
Add Child Table
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 70. You can use this icon to add different schema at the parent and child levels.
Add Table from Other Schema Remove Table
Causes TIBCO Designer to refresh stored table schema information by retrieving new information from the database.
Re-find Tables from Database
70
| Chapter 4
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.
Load Table Schema from Database
Allow Key Columns Only When this box is checked, child columns are joined only to a key column. When unchecked, child columns can be joined to any column. Select/Deselect All Columns to Publish When this box is checked, all of the boxes in the Use column are checked, so all columns in the tables are published. Unchecking this box unselects all of the columns. You can also individually check and uncheck the Use boxes. Table 16 Publication Service Tables tab Field
Tables and Columns
Description
The loaded tables and columns. indicates a table or child table. indicates a normal column. indicates a User Key column.
The primitive type. The primitive type mapped to an TIBCO ActiveEnterprise type. Click to define the column as a user key. Check the box to fire a trigger when an UPDATE statement changes a value in the column. Click to publish this column when data is changed. The name of a parent table column to join to for parent-child relationships.
Referencing an External Schema To reference an external schema in TIBCO Designer, the default schema must have the proper access privileges. These are set in a command line. In the following syntax, adb_schema refers to the default schema in create_user.sql. For Oracle, log in as system and grant create any trigger and drop trigger permissions to the default schema. For example:
grant create any trigger to adb_schema grant drop any trigger to adb_schema any
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.
72
| Chapter 4
When you add a child table, TIBCO Designer creates a class object in the repository for the child table, and an association object for the relationship. To enable publishing child table related data, the publisher adapter properties file must have the adb.publishChildData option set to on. After adding child tables for a subscriber adapter, you create mappings between child tables on the publisher side and child tables on the subscriber side. For instructions, see Child Table Mappings Tab on page 86. 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
3. Select the related child table from the list and click OK. 4. Repeat the above steps to add more child tables. When all of the child tables are added, you then designate a foreign key column as a key in each child table so that a relationship to the parent table can be defined. 5. Click the User Key checkbox for the foreign key column in the child table to select it. A key icon displays next to the column name. You must also specify the relationship between the primary column in the parent table and the foreign key column in the child table. 6. Click in the Join To field for the child table column, and select the name of the parent table primary key column from the drop-down list. 7. Click Apply.
In the following example, a publication service that publishes newly inserted rows into the source table is created. Publisher Options Tab on page 77 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.
74
| Chapter 4
The following example shows a child table mapped. The left column (Subscriber contains the subscriber child table and the right column (Publisher Child Table Name) contains the publisher child table.
Child Table Name)
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 tables INSERT triggers. Loaded data is not published.
Description
Enter the name of the database that you want to put your publisher table in. Enter the name of the table space where the publisher table is located.
Optional. Enter the designator of the storage group that will hold the publisher table indexes. Optional. Enter the name of the buffer pool to be used for indexes. Enter a suffix of your choice, up to 13 characters, that the adapter will append to each of the indexes (IDX1_, IDX2_, and IDX3_). Enter a suffix of your choice, up to 5 characters, that adapter software will append to each of the triggers (T1, T2, and T3).
Trigger Suffix
76
| Chapter 4
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.
Connection
If you select Asynchronous, you must go to the adapters Design-time tab and add ;transaction isolation level=none to the end of the JDBC URL field value. 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 checkbox for Overwrite Triggers? to delete and re-create existing triggers of the publishing table.
Description
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.
For each publisher service, you must specify a Storage Mode: Publish by Value or Publish by Reference. See Publish by Value on page 78 and Publish by Reference on page 79 for more information. 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>.<tableName> 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. 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. Select to use the alerter. This option appears only if you are using an Oracle database. See Chapter 6, Using the Alerter, on page 103 for details. Select to use group messaging.
78
| Chapter 4
Description
Appears only when Enable Group Messaging is selected. Specify the number of rows to publish in a single message.
Publish by Value With Publish by Value, all specified columns in the source table are copied to the publishing table. Publishing by value is fast, but does not support some data types, for example Oracle LONG and LONG RAW. Note the following restrictions on publishing tables when you publish by value: Publishing tables cannot contain columns with LONG data types. If you have a source table that contains a column with a LONG data type, that column cannot be specified for inclusion in the publishing table. This is because the trigger generated by the palette cannot refer to the LONG column via the :new construct. This is an Oracle restriction documented in the Oracle SQL Reference manual. The problem is not detected by Oracle during trigger creation. However, when the trigger fires and it attempts to copy the LONG column value to the publishing table, the database connection will hang for some time and then eventually terminate. If you define parent-child relationships between tables, the publishing table that is created for a parent table should not contain a column with a LONG data type. However, a child table can contain a column with a LONG data type. This is because data on child table rows is not copied using the :new construct. LONG RAW data is not allowed in the publishing table. These restrictions do not apply to publishing tables when you publish by reference and LONG or LONG RAW are non-key types. In the following example, the publishing table P_CUSTOMER is created for the source table, CUSTOMER. When CUSTOMER is updated, the new data will be copied to P_CUSTOMER. The adapter will poll P_CUSTOMER and publish the new data. In this example, loop detection is enabled. If a subscription exists that uses the same subject and CUSTOMER as the destination table, any changes to CUSTOMER will not be published repeatedly.
Publish by Reference With Publish by Reference, only key column values are copied to the publishing table. The publish by reference feature allows you to publish data directly from the source table without first copying the data from the source table to a publishing table. A trigger, stored procedure, and publishing table are created, but the publishing table contains the necessary adapter fields and only the key fields of the source table. For more information, see Start or Stop the Adapter on page 100. 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 173.
80
| Chapter 4
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
Specify values for the following fields: Table 19 Publication Service Advanced Tab Field
Destination
Description
(Only available when JMS is selected as the transport type in the Adapter Instance Configuration Tab) The publisher destination. A service uses a default destination generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default destination, make sure the values for Domain and Deployment are not empty. Alternatively, you can manually enter a destination in this field. The destination does not have to be predefined in the TIBCO Enterprise Message Service server. The destination can be static or dynamic. See the TIBCO Enterprise Message Service documentation for information about destinations.
Message Subject
(Only available when TIBCO Rendezvous is selected as the transport type in the Adapter Instance Configuration Tab) Publisher subject. By default, a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names.
Endpoint Reference
Displays the endpoint reference. Click the Browse icon to change the endpoint reference, the Go To icon to reconfigure the existing reference, or the Delete icon to delete the reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference. 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.
Class Reference
82
| Chapter 4
Configuration Tab
Specify values for the following fields: Table 20 Subscription Service Configuration Tab Field
Name
Description
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 run-time adapter. This selection determines which options appear in the rest of the Configuration tab. The transport can be configured to use a trusted store and identity resource for use in SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field which uses a dialog to perform SSL configuration. To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.
Description
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 64 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 65 for a description of these formats. Rendezvous Message (TIBCO Rendezvous only) XML Message (TIBCO Rendezvous or JMS) ActiveEnterprise Message (TIBCO Rendezvous only)
Connection Factory objects create JMS connections for sending and receiving messages. Topic (JMS only) A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe. Queue (JMS only) A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point.
Delivery Mode
(Only available when JMS is the transport type and Topic is the connection factory type) The delivery mode for each message sending operation. See Delivery Mode on page 65 for a description of each mode. Persistent Non-Persistent
84
| Chapter 4
Table Tab
You must set subscriber table options before configuring other subscriber options. An incoming message need not contain data for all the columns defined in the subscriber table. An adapter can be configured to expect only a subset of the columns. The adapter checks the repository for attributes defined in the subscriber table's class object definition. When a message arrives, the adapter iterates through the attributes in the subscriber tables 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.
Icons 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 Table
Displays a dialog box from which a secondary table can be added to the configuration.
Add Child Table
Allows you to enter a schema. For instructions on granting access privileges to an external schema, see Referencing an External Schema on page 70.
Add Table from Other Schema Remove Table
Causes TIBCO Designer to refresh stored table schema information by retrieving new information from the database.
Re-find Table from Database
If selected, child columns are joined only to a key colulmn. If unselected, child columns can be joined to any column.
Allow Key Columns Only
Columns
Tables and Columns Type
Lists the primitive type. Lists the primitive type mapped to an TIBCO ActiveEnterprise Click to define as a user key.
AE Type
type.
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
86
| Chapter 4
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
Specify values for the following fields: Table 21 Subscription Service Child Table Mappings Tab Field
Subscriber Child Table Name
Description
Displays the child tables that can be mapped. Entries are automatically created when you add child tables for a subscription service.
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.
Description
The child tables that can be mapped. Entries are automatically created when you add child tables for a subscription service. 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.
Description
Enter the name of the database that you want to put your exception table in.
88
| Chapter 4
Description
Enter the name of the table space where the exception table is located.
The name of the LOB table space name where auxillary table of the opaque exception table is located.
Description
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 155. 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.
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.
The value entered here represents the name of a stored procedure the subscriber will call after the database insert, update, or delete and prior to commit. You can use this stored procedure as a hook to accomplish further processing inside the database and return the results to the adapter. No value means the adapter will not call a stored procedure. 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 64 and Delivery Mode on page 65 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)
When selected, a new session is created and the service endpoint is moved to this 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.
If you are using the JMS transport, you must set the JMS Destination Prefix. See JMS Destination Prefix on page 52 for details.
90
| Chapter 4
Note that: All subscription service threads reconnect separately if the database connection is lost. 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
Specify values for the following: Table 25 Subscription Service Advanced Tab Field
Message Subject
Description
(TIBCO Rendezvous transport type only) By default a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names.
Destination
(JMS transport type only) The subscriber destination. A service uses a default destination generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default destination, make sure the values for Domain and Deployment are not empty. Alternatively, you can manually enter a destination in this field. The destination does not have to be predefined in the TIBCO Enterprise Message Service server. The destination can be static or dynamic. See the TIBCO Enterprise Message Service Users Guide for information about destinations.
Endpoint Reference
Displays the endpoint reference. Click the Browse icon to change the endpoint reference or the Go To icon to reconfigure the existing reference. You can also click the Delete icon to remove the reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.
Description
Click the Go To icon to reconfigure the existing reference. Class reference objects are explained in TIBCO Designer Palette Reference.
92
| Chapter 4
Configuration Tab
Specify values for the following fields: Table 26 Request-Response Service Configuration Tab Field
Name
Description
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.
Description Select the transport type (JMS or TIBCO Rendezvous) to be used by the run-time adapter. This selection determines which options appear in the rest of the Configuration tab. Only the options that are available with the selected Transport Type, Connection Factory Type, Mode or Wire Format are displayed. 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 64 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 65 for a description of these formats. Rendezvous Message (TIBCO Rendezvous only) XML Message (TIBCO Rendezvous or JMS) ActiveEnterprise Message (TIBCO Rendezvous only)
Connection Factory objects create JMS connections for sending and receiving messages. Topic (JMS only) A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe. Queue (JMS only) A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point.
94
| Chapter 4
Description
(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 65 for a description of each mode. Persistent Non-Persistent
This checkbox appears when the Mode field is set to RPC. Selecting this checkbox and clicking Apply creates the Call Operation Tab.
Description
Enter a unique name for the call operation. (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. (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. Name of the database procedure or function to call. 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. 2. 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. Click Select Procedure.
Schema
(Optional) The maximum number of rows to retrieve. (Optional) Check this box if you want to execute this procedure using a one-way operation. If left unchecked, the procedure will execute using a two-way operation.
96
| Chapter 4
Advanced Tab
Specify values for the following: Table 28 Request-Response Service Advanced Tab Field
Message Subject
Description
(TIBCO Rendezvous transport type only) By default a service uses a message subject that is generated using the Domain and global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names.
Deployment
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 the TIBCO Enterprise Message Service Users Guide for information about destinations.
Reply Subject
Type a TIBCO Rendezvous subject name that the adapter uses to respond, if no response subject is specified in the request message. 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. Click the Go To icon to reconfigure the existing reference. Class reference objects are explained in TIBCO Designer Palette Reference.
Endpoint Reference
Class Reference
| 97
Chapter 5
This chapter provides an overview about deploying, starting, stopping, and monitoring adapter services using the TIBCO Administrator web interface.
Topics
Create an EAR File in TIBCO Designer, page 98 Deploy the Project, page 99 Start or Stop the Adapter, page 100 Monitor the Adapter, page 101
98
| Chapter 5
100
| Chapter 5
you to start,
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 service.
Instance
3. Click the Start Selected button. The status changes from Stopped to Starting
up
to Started.
4. To stop the adapter service, click the Stop Selected button. See Also See the TIBCO Administrator Users Guide for more information.
See Also See the TIBCO Administrator Users Guide for information about configuring the above monitoring options.
102
| Chapter 5
| 103
Chapter 6
This chapter explains how to configure and start an alerter for each supported database.
Topics
Introduction, page 104 Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005, page 105 Setting Up and Starting the Alerter on Microsoft SQL Server 2000, page 109 Setting Up and Starting the Alerter on Sybase SQL Server, page 112
104
| Chapter 6
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 against a database instance, not user schema, an adapter instance cannot poll the publishing table name for just one user schema. For example, if the same publishing table exists for two user schemas and two instances are monitoring the same publication table, each instance with a different user, both instances will check the same publication table whenever the alerter checks for changes in the publication table. 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.
Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 105
Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005
The alerter on Oracle uses the Oracle AQ package and on MS SQLServer 2005 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 2005 that a publishing table has changed. The alerter gets the notification from Oracle AQ or MS SQLServer 2005 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 2005)
Oracle AQ/ MS Microsoft SQL Server 2005 Service Broker
1. Send Notification commit_and_notify 2. Receive Notification
Alerter
TIBCO ActiveMatrix Adapter for Database
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.
106
| Chapter 6
The following object types and stored procedures are available for committing messages when the alerter is used: Name
adb_alerter_qtbl (Oracle only) adb_alerter_q (Oracle only) adb_alerter_typ Service Broker Message Type Service Broker Contract Service Broker Queue Service Broker Service Service Broker Service Object Procedure Procedure Object type for all messages. AQ queue Queue for all alerters.
Type
AQ queue table
Description
Queue table for all alerters.
adb_alerter_contract (Microsoft SQL Server 2005 only) <instanceId>_q (Microsoft SQL Server 2005 only) <instanceId>_send_service (Microsoft SQL Server 2005 only) <instanceId>_rcv_service (Microsoft SQL Server 2005 only) adb_alerter_typ commit_and_notify commit_and_notify_agent <alerter name> commit_and_notify_table <tablename> stop_alerter stop_alerter_agent <alerter name> config_alerter cleanup_alerter listen_pipe
The contract type used. The contract specifies the message types that can be used. Created by the config_alerter stored procedure.
Object type for the payload message. Sends a change notification to all adapters. Sends a change notification to the named alerter.
Procedure
Stops all running alerters. Stops the alerter for the named alerter. Alerter call to register itself as an AQ subscriber. Alerter call to unregister itself as an AQ subscriber. Alerter call to block on alerts.
Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 107
Before Starting
When using the alerter functionality with Oracle database, make sure you have executed the create_user.sql and alerter.sql files against the database account used by the adapter, as described in Post-Installation Tasks in the TIBCO ActiveMatrix Adapter for Database Installation.
2. After inserting a message, execute the commit_and_notify_table stored procedure against 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);
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.
108
| Chapter 6
2. After inserting a message, execute the commit_and_notify_table stored procedure against the publishing table monitored by the adapter. For example, if the adapter is monitoring the PUB_ORDER table:
osql osql -Udemo-Pdemo 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.
Setting Up and Starting the Alerter on Microsoft SQL Server 2000 109
table_name. Sends a TIBCO Rendezvous message to the given instance or instances that the given publishing table has been updated.
notifytable
Before Starting
A database account must have been created for running the adapter. This is typically done after installation. See the TIBCO ActiveMatrix Adapter for Database Installation for details.
Alerter Setup
Before using the alerter you must copy the alerter dynamic link library 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.
adbalerter_mssql.dll
1. Open a command window and change directory to the <install-path>/tibco/adapter/adadb/<version_number>/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 -Ppassword 1> sp_dropextendedproc notify 2> go 1> sp_dropextendedproc notifytable 2> go 1> DBCC adbalerter_mssql(FREE) 2> go DBCC execution completed. If DBCC printed error messages, contact your system administrator.
110
| Chapter 6
5. Set access permissions for the database account used by the adapter:
1> 2> 1> 2> 1> grant execute on notify to database_account go grant execute on notifytable to database_account go exit
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 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
Setting Up and Starting the Alerter on Microsoft SQL Server 2000 111
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. For example,
execute master.dbo.notify @agentname='rvpub', @service='7500', @network=lan0, @daemon='10.105.176.21:7500'
112
| Chapter 6
Sends a TIBCO Rendezvous message to the given configuration or configurations that one or more publishing tables have been updated.
table_name. Sends a TIBCO Rendezvous message to the given configuration or configurations that the given publishing table has been updated.
notifytable
Before Starting
A database account must be created for running the adapter. This is typically done after installation. See the TIBCO ActiveMatrix Adapter for Database Installation for details.
You may need to shut down and restart your XP shared library to the sybase/lib directory.
SERVER
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
This example shows how to add procedures on Solaris. 4. Set access permissions for the database account used by the adapter:
1> 2> 1> 2> 1> grant execute on notify to database_account go grant execute on notifytable to database_account go exit
5. Add the <install-path>/tibco/tibrv/lib/libtibrv.so to the system LD_LIBRARY_PATH variable. 6. Add <install-path>/tibco/tibrv/bin/rvd to the system PATH variable.
You may need to shutdown and restart your XP SERVER after copying adbalerter_sybase.dll to the \Sybase\dll directory. 2. Ensure that the procedures are not already defined in the master database:
isql -Usa -Ppassword 1> sp_dropextendedproc notify 2> go
114
| Chapter 6
4. Set access permissions for the database account used by the adapter:
1> 2> 1> 2> 1> grant execute on notify to database_account go grant execute on notifytable to database_account go exit
5. Add the <install-path>\tibco\tibrv\bin\tibrv.dll to the system PATH variable. 6. Add <install-path>\tibco\tibrv\bin\rvd to the system PATH variable.
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
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
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'
116
| Chapter 6
| 117
Chapter 7
This chapter explains the request-response service, load balancing, and Oracle REF data type support features. See the TIBCO ActiveMatrix Adapter for Database Examples for request-response exercises.
Topics
Introduction, page 118 Request-Response Mode, page 120 RPC Mode, page 128 Load Balancing, page 138 Oracle REF Data Type Support, page 145
118
| Chapter 7
Introduction
Request-response operations are set up using the Request-Response Service dialog. This dialog is described in Configuration Tab on page 92.
Using request-response semantics, client applications can send SQL statements, stored procedures, or both on a specified subject to an adapter instance. The adapter processes the request and returns the results in a response to the client. 1. A request may be a query to the database or any DDL or DML command to be performed on the database. Multiple statements, procedures or both can be sent in one message. 2. The adapter executes the statement, procedure or both. Requests within a message are processed as a single transaction. 3. The adapter sends back the response to the Inbox, subject or response subject that was set up by the client application. The response consists of a result code or one or more result sets, based on the request. A response can also be an error code or error description, if the request was not successful.
Introduction 119
Multiple adapter instances can be configured so that any one of the configurations receives and processes the request: For a single configuration, the number of threads can be configured that will be responsible for processing application requests. See Load Balancing in a Single Instance Using Threads on page 138 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 140 for details.
Use of Quotes in Microsoft SQL Server When constructing a request in your application that will be processed by the adapter against a Microsoft SQL Server database, you must take care when using quotes. For example, the following procedure is part of a request from an application. Double quotation marks are used, which is incorrect. An error will be returned.
select @qry = "Update " + @tablename + " set ORDER_DESCRIPTION = 'UPDATE TEST'" + ", ORDER_PRICE = 10109.25"
The following procedure is the same as above, but uses single quotes. It will be correctly processed.
select @qry = 'Update ' + @tablename + ' set ORDER_DESCRIPTION = ''UPDATE TEST'', ORDER_PRICE = 10109.25'
See Delimited Identifiers in your Microsoft SQL Server documentation for details.
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.
120
| Chapter 7
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 92. 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()
If rv_SendWithReply() or rv_Rpc() calls are used, the adapter sends the response to the Inbox or subject that was set by the application for the response. Otherwise, the adapter sends the response on the response subject that was set at configuration time. Requests are described in the following sections: TIBCO ActiveEnterprise or XML Message Request Format, page 121 TIBCO Rendezvous Message Request Format, page 121
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 124 TIBCO Rendezvous Message Response Format, page 124
data
122
| Chapter 7
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
Statement
{ rv_Name = sql, rvmsg_Type = RVMSG_STRING, rvmsg_Data = Rendezvous Message
SQL_statement_with_possible_bind_variables
rv_Name = maxrows, rvmsg_Type = RVMSG_INT, rvmsg_Data =
Optional_max_number_of_rows_to_fetch
rv_Name = bind, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = rv_Name = bind, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = rv_Name = bind, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = . . . }
Rendezvous Message
position_of_placeholder_starting_with_1_from_left_to_right
rv_Name = "column", rvmsg_Type = RVMSG_STRING, rvmsg_Data = rv_Name = "data", rvmsg_Type = }
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)
Rendezvous Message
{ name = closure value = optional_closure_argument name = stmt value = { name = sql value = INSERT INTO order_table (order_id, order_description, order_price) values (1, Order 1, 1.10) } }
Bind Request Statement Assume that a client application submits the following SQL statement, where ? is a placeholder for an adbDateTime value:
INSERT INTO order_table (order_id, order_date) values (2, ?)
The corresponding request could be formatted as a message in TIBCO Rendezvous Message format similar to the following:
{ name = closure value = optional_closure_argument name = stmt value = { name = sql value = INSERT INTO order_table (order_id, order_date) values (2, ?) name = bind value = { name = order_table.order_date type = RVMSG_STRING value = 1999-08-20 10:20:01 } } }
To create a bind parameter for binary data, the actual data would be sent as an RVMSG_OPAQUE. Not every data value sent to an SQL statement must be bound. The client can embed all these values into the actual text of the statement instead. Embedding the values directly into the SQL text results in better performance. However, binary values must be bound. Types such as adbDateTime can either be bound or included in the SQL text by using the native DBMS date conversion function. For example, in ORACLE, you could use the TO-DATE function to enter a date:
INSERT INTO order_table (order_id, order_date) values (2, TO_DATE(1999-08-20 10:20:01, YYYY-MM-DD HH24:MI:SS));
Using Bind Entries Bind entries are specific only to the stmt {} that contains them. For example, if you want to insert three rows into REPLYTEST, you need to have three stmt {} blocks (and thus, three sets of bind statements):
request: { stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-10-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[3 opaque bytes]}} stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-11-10 12:10:10"} bind={column="REPLYTEST.BINCOL" data=[4 opaque bytes]}} stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-12-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[5 opaque bytes]}}}
124
| Chapter 7
format is
optional_closure_data
}
Rendezvous Message
{ name = row type = RVMSG_RVMSG value = name = row type = RVMSG_RVMSG value = name = row type = RVMSG_RVMSG value = . . . }
Rendezvous Message
format of the
column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data rv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data
rv_Name = . . . }
If the request processing was not successful, the response could also return an error code and error description as shown next:
Reply
{ rv_Name rv_Name rv_Name rv_Name } = = = = status rvmsg_Type = RVMSG_INT rvmsg_Data = nonzero_number sql rvmsg_Type = RVMSG_STRING rvmsg_Data = SQL_statement_that_caused_error error rvmsg_Type = RVMSG_STRING rvmsg_Data = error_text closure, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data
The status value is an integer specifying success or error. Possible values are:
0: 1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: ok noMem notInitialized typeConversion dbNotFound serverError serverMessage vendorLib notConnected endOfFetch invalidUsage columnNotFound invalidPosition notSupported nullReference notFound missing noMultiReaders noDeleter noInserter noUpdater noReader noIndex noDrop wrongConnection noPrivilege noCursor cantOpen applicationError // // // // // // // // // // // // // // // // // // // // // // // // // // // // // // No error Out of Memory Object never initialized Type conversion error Database not registered Error reported by server Message from server Error in vendor's library Lost connection End of fetch invalid usage of object Column does not exist invalid positioning within object,i.e.bounds err Unsupported feature Null reference parameter Database Object not found Required piece of information is missing This object cannot support multiple readers This object cannot support deletions This object cannot support insertions This object cannot support updates This object cannot support readers This object cannot support indices This object cannot be dropped Incorrect connection was supplied This object cannot support privileges This object cannot support cursors Unable to open For errors produced at the application level For future use
29: notReady
126
| Chapter 7
Example TIBCO Rendezvous Message Responses This section has two examples. The first shows a successful query response and the second shows an unsuccessful query response. Query Example As an example, assume the SQL statement, SELECT produces the following result:
SQL> SELECT * FROM ORDER_TABLE; ORDER_ID 1 2 ORDER_DESCRIPTION Order 1 Order 2 ORDER_PRICE 1.00 2.00 Message * FROM ORDER_TABLE
In this case, the self-describing message in TIBCO Rendezvous produced by the adapter would have the following structure:
{ name = closure value = optional_closure_argument name = status value = 0 name = results value = { name = row value = { name = order_id type = RVMSG_INT value = 1 name = order_description type = RVMSG_STRING name = order_price type = RVMSG_REAL value = } name = row value = { name = order_id type = RVMSG_INT value = 2 name = order_description type = RVMSG_STRING name = order_price type = RVMSG_REAL value = } } }
format
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 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. }
128
| Chapter 7
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.
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
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.
130
| Chapter 7
<parameter name = "STATEMENTS" classRef = "sequence[SQL_STATEMENT]" direction = "in" /> </operation> </class>
<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"/> <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>
132
| Chapter 7
Description The input parameters of the stored procedure. The input options: Option
MAXROWS SQL
Description The maximum number of rows to retrieve. The SQL string use to execute the stored procedure. This string is automatically generated by the palette. True if user want the agent to cache the statement for performance optimization read only, uses the call operation form to modify the package of the stored procedure. read only, uses the call operation form to modify the package of the stored procedure.
CACHE
PACKAGE
SCHEMA
CLOSURE
Any
134
| Chapter 7
Description The output parameters of the stored procedure The result set(s) returned by the stored procedure, see section 'Result Set Support' for more description "SUCCESS" if the stored procedure is executed successfully. "FAILURE" if there is an error. Error details are stored in the OPTIONS class Contains the error description and the SQL statement if an error occurred. Closure argument obtained from the request
String
OPTIONS
CUSTOM_OP_OUTPUT_ OPTION
CLOSURE
Any
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. 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 129.
DataDirect JDBC 3.3 drivers only provide valid resultset schema information for Oracle Server version 8.1.7 or higher.
136
| Chapter 7
Creating a Custom RPC Client There are two tasks in creating a custom RPC client: 1. Write an RPC client program using the TIBCO Adapter SDK. This task is described in the TIBCO Adapter SDK Programmers Guide. 2. Create a new entry for the RPC client in the repository. This task is described below. For more information on RPC server and client endpoint type fields, see TIBCO Designer Palette Reference. To create a new RPC client entry in the repository: Perform these steps after writing the client program and configuring the adapter, as described above. Detailed instructions for configuring a generic adapter are in the TIBCO Designer Users Guide. 1. In TIBCO Designer, drag a Generic design panel.
Adapter Configuration
icon to the
3. Click Apply. 4. In the project tree panel, expand the GenericAdapterConfiguration icon and click the Adapter Services folder. 5. Drag a Request-Response Invocation Service icon to the designer panel.
6. In the Configuration tab, set the name of the service and transport type of your client service. 7. In the Transport tab, set the message subject, quality of service, and wire format of your client service. If using the TIBCO Rendezvous message transport, you must use the TIBCO ActiveEnterprise wire format. 8. In the Schema tab, set the classReference to point to the correct class schema. For a standard RPC schema, use the following class schema:
AESchemas/ae/ADB/adbmetadata/Classes/SQL_OPS
For custom RPC schema, use the class schema that corresponds to the server endpoint:
AESchemas/ae/ADB/serviceName/Classes/ADBServer_OPS
9. Click Apply.
138
| Chapter 7
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.
Services
tab.
4. Change the value of Number of Request-Response Service Threads as needed. 5. Click Apply. Each request-response service thread is dedicated to listening on an agreed request subject. 1. When a request message is received by the request-response communication thread, it enqueues it into an in-memory queue. Each database request-response thread has a connection to the database using the user name-password combination that was provided to the adapter. 2. When an item is enqueued by the communication thread, one of the database request-response threads picks it up and executes the one or more SQL statements in the message as an atomic transaction.
140
| Chapter 7
3. It then composes a TIBCO Rendezvous self-describing response message and sends back a response on a response subject. If the original request was sending using rv_SendWithReply() or rv_Rpc(), the response is sent back on the subject that was specified by the requesting application. Otherwise, the response is sent back on the subject that was set up at configuration time. While the request message can be sent with either reliable or certified quality of service, the response message is always sent back using the reliable quality of service.
Request
Adapter 3
Adapter 2
Responses
TIBCO Messaging
Application
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 members load is determined by the number of pending processes that are waiting to be processed by the members database request-response thread. After the request is processed, the processing configuration sends a response back to the requesting application. 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 members load. 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
3. Configure the adapter instance with a design-time connection and ODBC value. 4. Drag the ADBSubscriber icon to the design panel.
142
| Chapter 7
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 Configuration, 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 Save. 3. Select the folder, then click New Application. 4. Click Browse and navigate to the EAR file you created in Designer. Click OK. 5. In the dialog that appears, click Save.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
7. Click the Add to Additional Machine button and select the machine to bind to and click OK.
144
| Chapter 7
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 Save. 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.
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
146
| Chapter 7
| 147
Chapter 8
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 148 Source Table, page 154 Exception Table, page 155 Opaque Exception Table, page 158 Incremental Parent-child Operation, page 160 Database Types, page 162
148
| Chapter 8
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 designtime will automatically populate the values for these additional columns. It is not reccomended that you modify these values. In addition to a copy of the source tables columns, the publishing table has the following additional columns. Table 31 Publishing Table Additional Columns
Type VARCHAR2(2 55) NUMBER(38) Description Used to specify the subject to publish the current row. Length is 255. 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. This number should be greater than 0 (zero). ADB_SET_SEQUENCE ADB_TIMESTAMP NUMBER(38) DATE Currently not used. 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.
ADB_SEQUENCE
Table 31
ADB_OPCODE
NUMBER(38)
indicates UPSERT. UPDATE if row exists, otherwise INSERT. indicates BYPASS (See Incremental Parent-child Operation on page 160)
10
If an incoming TIBCO Rendezvous message does not have an operation code, an INSERT occurs. ADB_UPDATE_ALL ADB_REF_OBJECT NUMBER(38) VARCHAR2(6 4) CHAR(1) Currently not used. When publish by reference object is used, contains the name of the reference object that provides source data. Delivery status of a TIBCO Rendezvous message:
P N C F
ADB_L_DELIVERY_STATUS
indicates that a new message has arrived, but has not yet been published. indicates complete. indicates failed.
ADB_L_CMSEQUENCE
NUMBER(38)
The publication table cannot contain any user-created columns where the column name starts with ADB_. These characters are reserved for adapter use.
150
| Chapter 8
Publication Example
The following is a listing of the SQL commands used to create a publication. The listing can be found in the demo\demo1\demo_database.sql file. The file shows the stored procedure, and insert, update and delete triggers that are generated for a publication.
-- ******************************************* -TIBCO 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), ORDER_PRICE NUMBER(10,3) ); -- ******************************************* -Setup a publication -- *******************************************
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, SYSDATE, 1, NULL, NULL, 'N', -1); END IF; IF UPDATING THEN IF UPDATING('ORDER_ID') THEN RAISE updating_key_fields; END IF;
152
| Chapter 8
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, ADB_ERROR_TEXT VARCHAR(4000) NULL, ADB_ERROR_TIME DATE DEFAULT SYSDATE ) / COMMIT;
154
| Chapter 8
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..
Column Name ADB_SOURCE Type CHAR Description 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.
The source table cannot contain any user-created columns where the column name starts with ADB_. These characters are reserved for adapter use.
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 the TIBCO Hawk Administrators Guide for details about creating a rulebase. For bulk insert operations, the agent will insert the unsuccessful rows in the exception table only when an exception occurs. For example, if the agent attempts to perform a bulk insert of 500 rows to the destination table, and the first 300 rows are inserted successfully but the last 200 rows are unsuccessful, the agent will insert only the last 200 rows to the exception table. It will then commit the operation. (The bulk insert operation is described in Adapter Services Tab on page 48.) In addition to destination table columns, the following columns are added to the exception table.
Column Name ADB_OPCODE Type NUMBER(38) Description 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 ADB_TRACKINGID NUMBER(38) VARCHAR2(40) Currently not used. 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 parents exception table by this column Text of the error from the database server, ODBC driver, or other source that caused the exception.
ADB_ERROR_TEXT
VARCHAR2(4000)
156
| Chapter 8
Type DATE
Description 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 tables exception table is connected to its parents table exception table by ADB_JOIN_ID.
The exception table cannot contain any user-created columns where the column name starts with ADB_. These characters are reserved for adapter use.
158
| Chapter 8
ADB_ERROR_TIME
DATE
Type INT
The ADB_SUBTAB column allows you to configure several subscription services using only one opaque exception table in the same database schema.
160
| Chapter 8
4 8 2 8
ADB_OPCODE A B C
4 1 "a" 4
"S_KEYP3" 3 1 "a" 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);
162
| Chapter 8
Database Types
The database data types listed in this section are supported.
Oracle
The following Oracle data types are supported: CHAR DATE LONG LONG RAW NUMBER TIMESTAMP WITH TIMEZONE TIMESTAMP RAW VARCHAR2 CLOB BLOB TIMESTAMP WITH LOCAL TIMEZONE
The following ANSI data types in Oracle are supported: DOUBLE PRECISION FLOAT INT INTEGER SMALLINT REAL
SQL Server
The following SQL Server data types are supported: BINARY BIT CHAR DATETIME DECIMAL FLOAT IMAGE (publish by reference only) INT MONEY NTEXT NUMERIC NVARCHAR REAL SMALLDATETIME SMALLINT SMALLMONEY TEXT (publish by reference only) TINYINT UNIQUEIDENTIFIER VARBINARY VARCHAR TIMETAMP
DB2
The following DB2 data types are supported: CHARACTER DECIMAL DOUBLE PRECISION FLOAT INTEGER LONG VARGRAPHIC DATETIME NUMERIC REAL SMALLINT TIMESTAMP VARCHAR LONG VARCHAR TIME
164
| Chapter 8
ODBC Type
SQL_CHAR SQL_VARCHAR SQL_LONGVARCHAR SQL_SMALLINT SQL_INTEGER SQL_REAL SQL_DOUBLE SQL_FLOAT SQL_DECIMAL SQL_NUMERIC SQL_BINARY SQL_VARBINARY SQL_LONGVARBINARY SQL_TIMESTAMP
i4
RVMSG_INT
r8
RVMSG_REAL
binary
RVMSG_OPAQUE
dateTime
RVMSG_DATETIME
| 165
Chapter 9
Advanced Features
Topics
Subject Names, page 166 Preregistering a Certified Subscriber, page 168 Changing the Location of the Ledger File, page 170 Sending Messages to an Adapter Instance, page 172 Publishing by Reference Object, page 173 User Callout Library, page 181 Publishing in a Commitment Controlled Environment, page 189 Using the Adapter with a Revision Control System, page 191 Using a Log File for an Adapter Instance, page 193 Using Database Cleanup Scripts, page 198 Change the SQL Statement Terminator (DB2 for z/OS Only), page 200 Fault Tolerance, page 201 SSL Data Encryption using DataDirect ODBC Drivers, page 203 Working with Multi-File Format Projects, page 204
166
| Chapter 9
Advanced Features
Subject Names
An adapter instance sends and receives messages using TIBCO Rendezvous subject names. Subject names are structured strings of alphanumeric characters. Each subject name is a string of characters divided into elements by the dot (.) character. For example, Tibco.Tsi and sales.accounting.order are valid subject names. Default subject names are provided in TIBCO Designer. You can change these default values to specify a custom subject name. A default subject is created each time an adapter service is created. The following are restrictions on subject names: Subject names are limited to a total length of 255 characters (including the dot delimiters). Even though TIBCO Rendezvous has a 255-character subject length limit, it is very unlikely that applications will need to use the full length. If you want to run an adapter instance against Microsoft SQL Server, you must design your subject space to conform to the length restrictions. There can be at most 100 elements in a subject name. The maximum element length is 255 characters. The asterisk (*) and greater than (>) are wildcard characters that can be used by subscriber configurations. For example, if messages are published on the tsi.sales.sports and tsi.sales.clothing subjects and your subscriber adapter listens on the tsi.sales.* subject, the configuration will get messages sent on both subjects. The underscore (_) character is reserved. An underscore and any other unprintable character should not be used in your subject name elements. It is also recommended that you do not use tabs or spaces in subject names. It is illegal to incorporate the dot character into an element by using an escape sequence. Subject names are case sensitive.
See the TIBCO Rendezvous Concepts manual for a full explanation of subject names.
where COLUMN1 and COLUMN2 are names of columns in the publishing table. For example:
TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION
On publication, a subject is created from the contents of those columns. This allows receiving applications to filter publications based on value of certain fields. Parameterized subject names are supported with certified or reliable delivery. Parameterized Subject Name Restrictions A TIBCO Rendezvous parameterized subject name can be at most 255 characters in length, with each component at most 127 characters. In the previous example, if the ORDER_DESCRIPTION column contains a description value that is longer than 127 characters, the parameter name $ORDER_DESCRIPTION is used as the subject in place of the description value. The asterisk (*) or greater than (>) characters or empty strings should not be used as attribute values (varchar, char) in a column that is part of a parameterized subject. Doing so makes the subject invalid. For example, if the TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION parameterized subject name is defined and the following values are inserted into ORDER_TABLE:
insert into ORDER_TABLE values(111,'*',88.81);
and the following values are inserted into the ORDER_DESCRIPTION table:
insert into ORDER_TABLE values(112,'>',99.91);
the publisher would return an error. Do not use columns that contain Date types as part of a parameterized subject. Date values are likely to contain characters such as dashes and spaces that can cause problems when used as part of a subject. Do not use columns that contain binary types as part of a parameterized subject. Do not insert data of Float type as an attribute value in a column that is part of a parameterized subject. Doing so makes the subject invalid. If a column should not be published, do not include the column name as part of the parameterized subject name.
168
| Chapter 9
Advanced Features
endpoint
object.
2. Click the publisher endpoint in the design panel. The Configuration Tab for this endpoint is displayed, as shown below.
3. Verify the name of the certified subscriber in the Preregistered Listeners field: %%Domain%%.%%Deployment%%.adb.%%Adapter_name%%.CM. In this example, the preregistered listener is the subscriber adapter named rvsub. 4. Click Apply.
170
| Chapter 9
Advanced Features
When the adapter instance is restarted, it writes the ledger file to the new location. For more information on using TIBCO Designer, see the TIBCO Designer Users Guide.
172
| Chapter 9
Advanced Features
adbDateTime Object
Do not change any adbDateTime object information in this screen. Use this information to determine how to format the third-party subscriber date value. To view the structure of the adbDateTime class, 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. 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.
3. To add a source table for a publisher adapter, do the following in the Tables tab: a. Click the Add
Table
b. Select a source table from the list and click OK. If parent-child relationships are used, follow the steps under Adding Child Tables on page 71 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
Storage Mode Options
tab:
by Reference.
Type the table name to use for storage. A common practice is to use the source table name prefixed by P_.
Publishing Table
Type the name of the view or other database object to select source data from. To select from a list of tables in the current user schema, click Add. To select an object from a different schema, select Add From.
Referred Object
174
| Chapter 9
Advanced Features
Select the method for updating tables from the drop-down list. Choose Update to update a row in the destination table only if the row exists. Choose Upsert to update a row in the destination table if the row exists and, if no such row exists, perform an insert.
Update Mode
5. Click Apply. Designating the Key Column To designate a column of the reference object as the key: 1. In the TIBCO Designer project tree panel, navigate to
AESchemas\ae\ADB\adapter_instance\classes\ref_object\key_column.
The TIBCO
2. In the Configuration tab, click the Key Field checkbox to select it. 3. Click Apply.
Adding a Sequence To add a sequence: 1. In the TIBCO Designer project tree panel, navigate to
AESchemas\ae\Classes\ae\ADB\adapter_instance\Classes\reference_object.
2. Drag a Generic Sequence icon from the palette panel to the design panel to add it to the reference object class. The TIBCO Designer window should look similar to the following:
176
| Chapter 9
Advanced Features
Sequence
5. Click the name of the sequence that represents the child table for the publication service, for example, sequence[ORDER_DETAILS]. 6. Click OK. 7. In TIBCO Designer, click Apply. The sequence is added to the metadata for the reference object. Adding an Association To add an association: 1. In the TIBCO Designer project tree panel, navigate to
AESchemas\ae\ADB\adapter_instance_name\Associations.
Several associations could display, at least one for the parent table to the child table on the publisher side, and another for the destination parent table to the child table on the subscriber side.
2. Click each of the resource icons that represent the parent-child relationship on the publisher side. For example:
3. In the Configuration tab, click in the Name field and replace the name of the publishing table with the name of the reference object. For example, P_CUSTOMER^ORDER_DETAILS becomes ORDER_VIEW^ORDER_DETAILS. 4. Click Apply. 5. In the project tree panel, double-click the new association name to expand it.
178
| Chapter 9
Advanced Features
7. Enter a Role Name value that contains the reference object name. For example, roleORDER_TABLE.
8. In the Endpoint Class field, click Browse. Navigate to the class that represents the reference object, in this case ORDER_TABLE, and click OK.
Example
In the following example, the publisher adapter is configured to publish source data from the CUSTOMER table and its child table, EXTERNAL_ORDER_DETAILS. The relevant key columns are CUST_ID and ORDER_ID. The publishing table is created with necessary adapter fields, as well as CUST_ID and ORDER_ID fields. When a row in CUSTOMER is modified, the trigger fires, populating fields and copying the CUST_ID and ORDER_ID values, as well as the name of the reference object, ORDER_VIEW, to the publishing table. When the
180
| Chapter 9
Advanced Features
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.
The table must be journalled. You can create this table or if journalling is automatically turned on, the palette will create the table automatically.
The source code is included in your installation media in the install-path\demo\altermsg directory. If you send or receive messages in the TIBCO Rendezvous Message wire format, the TIBCO Rendezvous Message APIs cannot be used to directly alter those messages. Instead, you will receive an MTree to which various functions can be applied to view or traverse the TIBCO Rendezvous message. If you must change the message, create a new message and pass it back to the adapter using the newmsg argument.
182
| Chapter 9
Advanced Features
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 33 Wire Format Parameters and Descriptions Parameter subj msg R X X M X Description Subject on which the message is sent or received. MTree containing the message to send or receive.
Table 33 Wire Format Parameters and Descriptions (Contd) Parameter newmsg pInst pMapp dataformat X R X X X X M Description New MTree user creates if msg must be altered. MInstance of the message. Alter directly if necessary. TIBCO Adapter SDK MApp structure for this MInstance. 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. When sending or receiving messages in the TIBCO ActiveEnterprise wire format, you must use the pInst argument to change the message.
Message
184
| Chapter 9
Advanced Features
The following table contains parameter descriptions. Table 34 adbPreCommit Parameter Descriptions Parameter connectHandle pMapp pInst pTree dataformat X TIBCO Rendezvous Format X X TIBCO ActiveEnterprise Format X X X X X Description The database connection handle. TIBCO Adapter SDK MApp structure for this MInstance. MInstance of the message. MTree containing the message. 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.
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 309.
Building the Callout Library on Microsoft Windows 1. Using Visual C++, create a new workspace and insert a new project into the workspace. 2. In the new project, open the file:
install-path\demo\altermsg\altermsg.dsp
3. Select Project>Settings. In the Project Settings dialog box: a. As shown next, select the C/C++ tab. In Category, select Preprocessor. In Additional include directories field type the path to the TIBCO Rendezvous include directory.
186
| Chapter 9
Advanced Features
b. As shown next, select the Link tab. In Category, select Input. In Additional library path type the path to the TIBCO Rendezvous library directory.
4. Select Build>Build
adbaltermsg.dll
5. After building the library, change to the <install-path>/tibco/adapter/adadb/<version_number>/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
6. After building the library, change to the install-path\lib directory. a. Make a backup copy of the existing libadbaltermsg.so library. b. Copy the new libadbaltermsg.so library into the lib directory.
188
| Chapter 9
Advanced Features
(publication service update connection) (publication service confirm connection) (subscription service connection) (request-response service connection
InstanceId.ADBPubConfirm InstanceId.ADBSubscriber
InstanceId.ADBRequestReply.n
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 F F O E Disk Rename(P_EMPL:Pub_Record) UsrOpn Commit
Make sure that the application program that is accessing the source table is running with commitment control enabled. Otherwise, the trigger program will encounter a runtime error with this keyword. 3. After editing the trigger program member, save and compile it with options DFTACTGRP(*NO) and ACTGRP(*CALLER). These options ensure that the trigger program runs as part of the calling application program's commitment cycle. The trigger program will run in the application program's activation group. Any database updates done by the trigger program will be done or undone by a Commit or Rollback issued by the application program, thus ensuring database integrity.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
190
| Chapter 9
Advanced Features
4. To have the trigger program run under commitment control, the publishing table (listed in the trigger program) must be journalized. This can be done by using the 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.
When the project is saved and a revision control system has been specified, the adapter displays a warning that additional files were created and should be added to the revision control system. This warning appears only when the files are created for the first time. The warning displays a Go To Resource button that helps in navigating to the resource. You should use the Multi-User>Add Resources to RCS menu command to add these files to the revision control system. For information about how to use the Multi-User feature in TIBCO Designer, refer to the TIBCO Designer Users 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.
192
| Chapter 9
Advanced Features
If a service associated with a custom session is moved, or copied and pasted, the custom session is not moved, or copied and pasted. The session is regenerated as a default session.
194
| Chapter 9
Advanced Features
The Log to Standard I/O checkbox is selected so that trace information can be written to the console window where the adapter instance was started. The log file is generated in the start directory unless specified otherwise in the properties file. To disable file tracing for the adapter instance, delete this file name and click Apply.
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
The following checkboxes control the level of trace information that is captured:
Log Info MessagesCapture
error and warning information. all available information. warning information only.
196
| Chapter 9
Advanced Features
3. In the project tree panel, navigate to adapter_instance_name\Advanced\Log Sinks\fileSink. The TIBCO Designer window looks similar to the following:
File Count Specifies the maximum number of log files that are created for this adapter instance. Append Mode When this box is checked (the default), information is written to the log file in the Append mode, where trace information is appended to existing entries in the file. Unchecking this box changes to Overwrite mode, where the adapter instance overwrites the current log file the next time the adapter starts.
198
| Chapter 9
Advanced Features
If the scripts created for legitimate database changes are generated successfully but an error occurs while these changes are being saved to the database, a message such as the following sample may display.
To Run the Cleanup Scripts 1. Select each message in the top portion of the message window and read the explanation for it in the bottom portion of the message window. 2. In TIBCO Designer, close the project containing the adapter instance that you changed. 3. Fix the errors that caused the database changes to fail, as indicated by the messages. 4. If necessary, clean up the old database configuration by running the scripts created by the adapter. The scripts are in the sql directory and are named instanceId.sql or instanceId.undo.sql, where instanceId is the name of the adapter instance you changed. 5. Reopen the project in TIBCO Designer. 6. Select the adapter instance you were attempting to change when the errors occurred. 7. Save the project.
200
| Chapter 9
Advanced Features
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
filename
4. In the Window's Command Center, go to the Script menu and select options. 5. Check the use
statement termination character
7. Cut the SQL statements from the script file and paste them into the Command Center GUI, then execute.
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 runtime 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. 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. 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
202
| Chapter 9
Advanced Features
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 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 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. 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. Reconnection in the Fault Tolerance Mode If the primary instance looses 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.
Refer to 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.
204
| Chapter 9
Advanced Features
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
| 205
Chapter 10
This chapter describes how to use TIBCO ActiveMatrix Adapter for Database in an international environment using non-ASCII languages.
Topics
Overview, page 206 Setting TIBCO Messaging Encoding, page 208 Configuring the Adapter to Communicate with the Database, page 210 Relevant Environment Settings, page 215
206
| Chapter 10
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 6 Example of Unicode Conversion
Oracle DB in Shift-JIS Oracle DB in EUC-JP
TIBCO Messaging
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 garbled. . 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.
Overview 207
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.
208
| Chapter 10
The encoding value is set on the root project folder in TIBCO Designer. By default, the value is set to ISO8859-1. You can change the value by selecting the folder and under the Project Settings tab, changing the value for the TIBCO Message Encoding field. In order for different TIBCO components that each have their own local file repository to communicate with each other without data garbled, they must use the same TIBCO Messaging encoding, meaning that all these components must set their local project encoding to the same value. The encoding property of a local project file is only for determining the TIBCO Messaging encoding, not the encoding used for the persistent storage of the project files. The project files are always saved as UTF-8 encoded files. After a project is deployed as a server-based project, the encoding property set at design-time is superseded by the encoding property set for the TIBCO administration server.
210
| Chapter 10
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
You must select or enter a valid encoding that the adapter understands. The adapter assumes the data coming from the database is in this encoding and ensures that data sent to the database is in this encoding. The encoding given here should match the encoding set for the database to which the adapter connects. There are two ways to do this configuration: In TIBCO Designer, set this in the adapter resource. In the Configuration tab, click Show All Tabs. In the General tab, choose the encoding that is compatible with the encoding of the database instance to be connected to. Refer to Table 36, 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, refer to Appendix B in TIBCO Adapter Concepts. You can modify the adapter encoding property, adb.encoding, in the adapters.tra file. This setting supersedes the encoding option chosen in TIBCO Designer. 4. Set the ODBC DSN in TIBCO Designer This field is set under the adapters Run-time Connection tab. You must also define the ODBC DSN on the machine on which the adapter is running. On Unix systems, modify the odbc.ini file
<install-path>/tibco/adapter/adadb/<version_number>/odbc. In addition, you must set the correct IANAAppCodePage to match the database encoding, if you are using a wire protocol driver. See IANAAppCodePage on page 211 for a list of IANAAppCodePage values. The complete list is available in <install-path>/tibco/adapter/adadb/<version_number>/odbc/help/odbcr
ef/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 35 IANAAppCodePage Value 3 4 17 Encoding (Language) ASCII (English) ISO_8859-1 (Western European) Shift_JIS (Japanese)
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
212
| Chapter 10
Table 35 IANAAppCodePage Value 18 38 113 2026 Encoding (Language) EUC_JP (Japanese) EUC_KR (Korean) GBK (Simplified Chinese) BIG5 (Traditional Chinese)
Using a non-Oracle Database When using a database other than Oracle, contact the database vendor for information about whether the database's proprietary client performs any encoding conversion to the data flow, and how to configure the database client to eliminate the conversion possibly conducted by it. Several possibilities exist: The database client does not perform any conversion to the data flow in any cases. In this case, you only need to set the adapter encoding to be compatible with the database instance's encoding. The database client relies on a local setting, such as an environment variable, to determine whether or not a conversion should to be conducted. This is similar to the above Oracle example, where you need to set both this local setting and the adapters 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. When using the DataDirect non-wire protocol ODBC driver and UTF-8 as the adapter encoding to support multilingual data exchange, the configuration is totally different. Please refer to the section Special Configurations for Supporting a UTF-8 Database.
This forces the adapter to use binary mode to communicate with the database. These are for the internationalization configuration, which forces the adapter to use binary mode to communicate to the database instance. No further encoding related configurations are necessary. For example, on UNIX there is no need to set the AppCodePage attribute, and when using a non-wire driver there is no need to set the proprietary database client.
214
| Chapter 10
216
| Chapter 10
| 217
Chapter 11
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 54).
Topics
Overview, page 218 Starting TIBCO Hawk Software, page 219 The Auto-Discovery Process, page 220 Invoking Microagent Methods, page 221 Available Microagents, page 224
218
| Chapter 11
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: DisplayGUI 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. AgentsIntelligent processes that perform monitoring and take actions as defined in rules. RulebasesRules 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. MicroagentsFeed information back to TIBCO Hawk and expose action methods to rulebases. For more information, see the TIBCO Hawk documentation.
220
| Chapter 11
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.
222
| Chapter 11
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 Invoke to invoke the selected method. The Invocation Results dialog displays the results returned by the method.
7. Click Done to close the dialog. These steps describe how to interactively invoke a microagent method and receive a single set of results in TIBCO Hawk Display. You can also use a microagent method as the data source of a TIBCO Hawk rule. Rules automatically receive method results, apply tests to evaluate them, then take action if necessary. For more information on building TIBCO Hawk rules and rule bases, see your TIBCO Hawk Administrators Guide.
224
| Chapter 11
Available Microagents
Each adapter has two microagents, a standard TIBCO Hawk microagent named COM.TIBCO.ADAPTER.xyz (where xyz is the adapter configuration name) and a custom microagent. These microagents provide: Business level statisticsstatistics that report the progress of the adapter as it interacts with the database. For example, in a database adapter such statistics might indicate whether objects were successfully or unsuccessfully inserted, updated, or deleted in the database. Queries that return information about the state of the adapter. This can be an important tool for seeing the internals of an adapter and debugging it if something appears wrong. For example, methods can return information about threads, internal queues, or connections to the target system. Using these methods, one might be able to identify certain bottlenecks or gauge how successfully an adapter is scaling with respect to the current environment. Updates of the adapter runtime parameters. This includes retrieving the current runtime parameters and setting new runtime parameters without restarting the adapter. An example of this is getting and setting the polling interval. Updating a runtime parameter through the Hawk microagent only affects the setting of the instance that is running. It does not make a permanent change of the setting in either the repository or the .tra file.
The following table lists each method available for the adapter and page on which the method is explained. Although the Microagents, Methods and Arguments dialog in TIBCO Hawk Display lists more methods than are documented here, only the following methods are supported. Table 37 Standard Microagent Methods Standard Method
activateTraceRole()
Description Activates a mapping of a role to a sink at runtime. Deactivates a mapping of a roles to sinks at runtime. Returns information about the services implemented by this adapter. Returns information about the publisher, subscriber and IODescriptor.
deactivateTraceRole()
Description (Contd) Returns basic configuration information. More specific information is accessed by the more specific methods. Returns a list of publishers and subscribers. Returns standard and extended application information. Returns information about all TIBCO Rendezvous sessions defined. 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. Returns information about sinks to which traces currently go. Returns the configuration ID, application name, version, and date for this adapter instance. Displays alert messages sent to the current adapter. Preregisters an anticipated listener. Returns information retrieved from the ledger file of a certified messaging session for a publisher adapter. Adds a role or changes the file limit of a previously specified sink. Stops the running adapter instance. Unregisters a currently preregistered listener.
Page 232
getConfigProperties()
getHostInformation()
getRvConfig()
getStatus()
getTraceSinks()
237 238
getVersion()
_onUnsolictedMsg()
preRegisterListener() reviewLedger()
setTraceSinks()
226
| Chapter 11
Description Retrieves the size of the TIBCO Rendezvous event queue for the specified adapter instance. Sets the debug level for the current adapter instance. Changes the value of the verbose flag from on to off, or the reverse. Shows the configuration defined for the current agent. Stops the current TIBCO ActiveMatrix Adapter for Database agent. Returns the current polling interval setting. Set the polling interval for the publication service. Get the polling batch size for the publication service. Set the polling batch size for the publication service.
Page 245
setDebugLevel()
Table 39 Custom Microagent Methods with adb.perfMon Custom Method getActivityStatistics() Description 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. Page 254
Table 39 Custom Microagent Methods with adb.perfMon (Contd) Custom Method (Contd) getActivityStatisticsBySer vice getActivityStatisticsByOp eration() Description (Contd) Returns the total number of objects processed for each of the schemas associated with the specified service. Returns the total number of objects processed for all the schemas by each service that is associated with a specified operation. Return the operation counts of the current threads. Return the current count of elements in any internal queue used by the adapter. Returns the state and statistics for all the current connections used by the adapter. Resets all the counts for the activity statistics. Resets all the counts for the thread statistics. Resets all the counts for the queue statistics. Resets all the counts for the connection statistics. Page 255
256
228
| Chapter 11
activateTraceRole()
Purpose
(Standard) Activates a mapping of a role to a sink at runtime. This replaces the now-deprecated setTraceSink() TIBCO Hawk method. Parameters roleName sinkName Type string string Description Name of the role to activate. Name of a sink for which to activate the role.
Parameters
deactivateTraceRole() 229
deactivateTraceRole()
Purpose Parameters
(Standard) Deactivates a mapping of a roles to sinks at runtime. Parameters roleName sinkName Type string string Description Name of the role to activate. Name of a sink for which to activate the role.
230
| Chapter 11
getAdapterServiceInformation()
Purpose
(Standard) Returns information about the services implemented by this adapter. The information is a summary of available adapter services. Parameter serviceName Type string Description Name of the service from which to get information. Default is ALL. Description Sequential row number. Name of the Service. Name of the endpoint used for this service. Type of the endpoint, for example, Publisher, Subscriber. Quality of service for the endpoint, for example, RV, RVCM. Name of the application for this sink. Name of the TIBCO Rendezvous session. Subject defined for this endpoint Number of messages processed for this endpoint.
Parameters
Returns
Returns Line Name Endpoint Type Quality of Service Adapter Name Session Name Subject Number of Messages
Type Integer string string string string string string string Integer
getComponents() 231
getComponents()
Purpose
(Standard) Returns information about the currently active TIBCO Hawk components such as publishers, subscribers, or timers. Parameters Component Name Component Type Type string string Description Name of the TIBCO Hawk component. Default is all components. Any of Publisher, Subscriber, Timer, or IODescriptor. The default value is All. Description Name of the TIBCO Hawk component. Name of this adapter instance. Name of the adapter. Name of the TIBCO Rendezvous session. 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. Information about this TIBCO Hawk component, for example, time interval, signal type, validating publisher (or subscriber) etc.
Parameters
Returns
Returns Component Name Instance ID Adapter Name Session Name Component Type
Description
string
232
| Chapter 11
getConfig()
Purpose
(Standard) Retrieves generic configuration information. More specific configuration information is accessed through separate methods. Returns Instance ID Adapter Name Repository Connection Configuration URL Command Type string string string string string Description Configuration ID of this adapter. Name of the adapter. URL of the repository used for adapter instance. Location of the adapter project; either a file name or configuration URL. Command line arguments used to start the adapter.
Returns
getConfigProperties() 233
getConfigProperties()
Purpose Parameters
(Standard) Returns all attributes and elements for the given repository object. Parameter Property Type string Description 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
Description Repository directory for the property. Name of the repository object attribute. Value of the repository object attribute. Line number in which this property is defined in the project file.
234
| Chapter 11
getHostInformation()
Purpose Returns
(Standard) Returns standard and extended application information. Returns Name Value Type string string Description Name of the property. Value of the property.
getRvConfig() 235
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. Parameter Session Name Type string Description Name of the TIBCO Rendezvous session for which configuration is required (default is all). Description The configuration ID of this adapter. Name of the adapter. Name of the session. Service parameter for this session. Daemon parameter for this session. Network parameter for this session. Returns 1 if this is a synchronous session, 0 otherwise. Type of session; one of M_RV, M_RVCM, or
M_RVCMQ.
Parameters
Returns
Returns Instance ID Adapter Name Session Name Service Daemon Network Synchronous? Session Type Certified Name Ledger File
Type string string string string string string boolean string string string
Name of this certified session. Ledger file for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions. Timeout for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.
CM Timeout
string
236
| Chapter 11
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 232 and getRvConfig() on page 235.
Returns
Returns Instance ID Adapter Name Uptime Messages Received Messages Sent New Errors Total Errors Process ID Host
Type string string integer integer integer integer integer integer string
Description Configuration ID for this adapter instance. Name of the adapter. Number of seconds since startup. Number of TIBCO Rendezvous messages received. Number of TIBCO Rendezvous messages published. Number of errors since the last call to this method. Total number of errors since startup. Process ID of the application. Name of host machine on which this adapter is running.
getTraceSinks() 237
getTraceSinks()
Purpose Parameters
(Standard) Returns information about sinks to which traces currently go. Parameters Sink Name Type string Description Name of the sink for which you need information. If no name is specified, information about all sinks is returned. Default is all. Name of the role for which you need information for the specified sink or sinks. Default is all. Description Name of this adapter instance as a string. Name of the application for this sink. Name of the sink Type of this sink. One of fileSink, rvSink, hawkSink, stderrSink. Roles this sink supports, as a string. For example warning, error, debug.
Role Name
string
Returns
238
| Chapter 11
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 Instance ID Adapter Name Version Description The configuration ID as a string, for example SDK. Name of the adapter as a string, for example rvpub. Version number as a string, for example 1.1.
Returns
_onUnsolictedMsg() 239
_onUnsolictedMsg()
Purpose
(Standard) Displays all alert messages sent from the adapter or an error if not successful.
240
| Chapter 11
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 senders ledger. If the listening correspondent requires old messages, it receives the backlogged messages when it requests certified delivery. Parameters Session Name Publisher Name Listener Session Name Type string string string Description Name of the session that anticipates the listener. Name of the component for which the listener should be preregistered. Name of the listener to preregister.
Parameters
Returns
reviewLedger() 241
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 Session Name Subject Type string string Description Name of the TIBCO Rendezvous session for which ledger information is desired (default is all). Name of the subject for which ledger information is desired.
Parameters
Returns
Returns Session Name Subject Last Sent Message Total Messages Total Size
Description Name of the TIBCO Rendezvous CM session to which this information applies. Subject name for this session. Sequence number of the most recently sent message with this subject name. Total number of pending messages with this subject name. 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. Within each listener submessage, the Listener Session Name field contains the name of the delivery-tracking listener session. Within each listener submessage, the Last Confirmed field contains the sequence number of the last message for which this listener session confirmed delivery. Row number in ledger file. 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
string string
integer integer
242
| Chapter 11
setTraceSinks()
Purpose Parameters
(Standard) Adds a role or changes the file limit of a previously specified sink. Parameters Sink Name Role Name Type string string Description Name of the sink for which you want to add a role or change the file limit. Name of the role you want to add to this sink (warning, error, debug, or user defined). Default is all. Maximum file size for this sink. This parameter is ignored if the sink specified by sinkName is not a file sink.
File Size
integer
Returns
stopApplicationInstance() 243
stopApplicationInstance()
Purpose Returns
(Standard) Stops the specified adapter by calling the internal stop() method. OK if successful or an error if not successful.
244
| Chapter 11
unRegisterListener()
Purpose Parameters
(Standard) Unregisters a currently preregistered listener. Parameters Session Name Publisher Name Listener Session Name Type string string string Description Name of the session that anticipates the listener. Name of the component for which the listener should be preregistered. Name of the listener to unregister.
Returns
getEventQueueSize() 245
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. Parameter Session Type string Description Type of listener for this adapter instance. Possible values are Subscriber or Request/Reply. The default value is Subscriber. Description The number of events currently in the event queue. 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 adapters properties file. The default value is 0, which means the event queue has unlimited size.
Parameters
Returns
246
| Chapter 11
setDebugLevel()
Purpose Parameters
(Custom) Sets the debug level for the current adapter instance. Parameter DebugLevel Type integer Description Sets the debug level to 0 (off), 1, 2, or 3. 0 No debug information displayed. 1SQL commands executed against the database shown. 2ODBC data source for each SQL command shown. 3All debug information displayed.
Returns
toggleVerboseFlag() 247
toggleVerboseFlag()
Purpose Returns
(Custom) Changes the value of the verbose flag from on to off, or the reverse. This method returns OK if successful or an error if not successful.
248
| Chapter 11
showConfiguration()
Purpose Parameters
(Custom) Shows the configuration defined for the current agent. Parameter VerboseInfo DebugLevelInfo Type string string Description The current setting for the verbose mode, on or off. The debug level setting:
0
1SQL
terminateADBagent() 249
terminateADBagent()
Purpose Remarks
(Custom) Stops the current TIBCO ActiveMatrix Adapter for Database agent. Invoking this method displays a warning message with the text MicroAgent returned error. AMI Method invocation timed out. The message can be ignored. This method returns OK if successful or an error if not successful.
Returns
250
| Chapter 11
getPollingInterval()
Purpose Returns
(Custom) Returns the current polling interval setting. Returns PollingInterval Type integer Description Polling interval in milliseconds.
setPollingInterval() 251
setPollingInterval()
Purpose Parameters
(Custom) Set the polling interval for the publication service. Parameter PollingInterval ServiceName Type integer string Description Polling interval in milliseconds. (Optional) Name of service where the polling interval is set.
252
| Chapter 11
getPollingBatchSize()
Purpose Returns
(Custom) Get the polling batch size for the publication service. Returns BatchSize Type integer Description The batch size for the publication service.
setPollingBatchSize() 253
setPollingBatchSize()
Purpose Parameters
(Custom) Set the polling batch size for the publication service. Parameter BatchSize Type integer Description The new batch size for the publication service.
254
| Chapter 11
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. Parameter Get Subtotal By Type integer Type string Description Statistics categorized by service or by operation. Description Name of the service or operation. The operation can be one of the following: Total integer Fetch Poll Insert Update Delete
Parameters
Returns
Returns Name
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. 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.
Failure
integer
getActivityStatisticsByService 255
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. Parameter Service Name Type string Type string string integer Description Name of the service. Description Type of operation that the service performs. Name of the schema that is associated with the service. 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. 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.
Parameters
Returns
Failure
integer
256
| Chapter 11
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. Parameter Operation Type string Description Name of operation. Pick from one of the following form the drop-down list. Fetch Poll Insert Update, and Delete
Parameters
Returns
Description Name of the service that is associated with the specified operation. 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. 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.
Failure
integer
getThreadStatistics() 257
getThreadStatistics()
Purpose Returns
(Custom with adb.perfMon) Return the operation counts of the current threads. Returns ThreadID ThreadType TaskType TaskCount Type string string string integer Description A unique identification of a particular thread. A type or key that will match this thread to a queue or connection. Short description of the tasks this thread processes. Number of tasks processed by this thread.
258
| Chapter 11
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 QueueID QueueType QueueCount MaxQueueSize Type string string integer integer Description A unique identification of a particular queue. A type or key that will match this queue to a thread or connection. Current number of elements in the queue. Maximum number of elements in the queue.
Returns
getConnectionStatistics() 259
getConnectionStatistics()
Purpose
(Custom with adb.perfMon) Returns the state and statistics for all the current connections used by the adapter. Returns Connection ID Connection Type State NumRetries TotalNumOperat ions CurrentNumOpe rations Type string string string integer integer integer Description A unique identification of a particular connection. A type or key that will match this connection to a thread or queue. Current state: CONNECTED or DISCONNECTED Total number of times this connection had to be reestablished. Total number of operations processed by this connection since the adapter started. Total number of operations processed by this connection since the last reconnection.
Returns
260
| Chapter 11
resetActivityStatistics()
Purpose
(Custom with adb.perfMon) Resets all the counts for the activity statistics.
resetThreadStatistics() 261
resetThreadStatistics()
Purpose
(Custom with adb.perfMon) Resets all the counts for the thread statistics.
262
| Chapter 11
resetQueueStatistics()
Purpose
(Custom with adb.perfMon) Resets all the counts for the queue statistics.
resetConnectionStatistics() 263
resetConnectionStatistics()
Purpose
(Custom with adb.perfMon) Resets all the counts for the connection statistics.
264
| Chapter 11
| 265
266
| Chapter 11
| 267
Appendix A
Topics
General Questions, page 268 Request-Response Questions, page 274
268
| Appendix A
General Questions
How can I determine the source of a problem or an error? In some cases it is helpful to turn on ODBC tracing. Activate tracing in Control Panel>ODBC Data Sources on the Tracing tab. For details, see your Microsoft Windows documentation. How can I find the version number of an adapter instance? A banner displays when an adapter instance starts. The banner lists component versions for the adapter and for TIBCO Adapter SDK software. You can use this information to diagnose compatibility issues, or to report any problem details to Customer Support. You can also display version information in TIBCO Designer by clicking the Help>Runtime Environment menu command. Why is a database trigger error not logged in the exception table? When using an adapter instance as a publisher, if an error occurs in the database trigger that is used to copy data from the source table to the publishing table, the database trigger error will not be logged in the exception table for the subscriber adapter. How should the adapter react if the database connection is lost and the database is later restarted? Does it automatically try to reconnect? If TIBCO ActiveMatrix Adapter for Database detects it has lost its database connection, it shuts down. You can configure the adapter for automatic reconnection (see Run-time Connection Tab on page 46). 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. 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 181. 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.
270
| Appendix A
How does the exception table work? Before starting an adapter instance, you must set the adb.useExceptTable option in the adapters properties file to on and specify an exception table when configuring the adapter instance. If an error occurs when inserting data into the destination table, it will be inserted into the exception table. The transaction will be committed and a confirmation sent back for the message (RVCM delivery). If the insertion into the exception table also fails, an error message will display and the adapter instance will terminate. Can an adapter instance be used to replicate binary types, such as BLOB? There is only limited support for binary large object (BLOB) data types. Oracle LONG and LONG RAW types are supported in top-level tables when the adapter is configured to publish by reference. Oracle BLOB and CLOB data types are supported. Can an adapter instance write to tables that belong to a database account different from that used by the adapter? Yes. A source table or destination table can belong to a different database user than the default account created in create_user.sql. For more information 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. 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 adapters 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
The session names are automatically created. Can these be changed, without confusing TIBCO
TIBCO ActiveMatrix Adapter for Database Configuration and Deployment
272
| Appendix A
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. Whats the proper way to permanently remove an adbagent subscriber when using CM? One way is to completely REMOVE the publishers ledger and to change all P records back to N, then restart the publisher. Is there a better, more correct or automated method? There is a TIBCO Hawk method, unRegisterListener(), which unregisters a CM subscription. This is the proper way to remove the adbagent subscriber as a CM listener. Is it possible to run an adapter instance using a remote TIBCO Rendezvous daemon? Yes. Change the default settings for network, service, and daemon parameters for the adapter using TIBCO Designer. Is it possible to run two configurations of the adapter on the same machine? It's possible to run multiple configurations of the adapter on the same machine if each adapter instance has a unique name. If both configurations use TIBCO Rendezvous certified messaging, each must use a different RVCM session. Can an adapter instance collate information from several database tables to send as a single TIBCO Rendezvous message, or can it only publish data from a single table, in the format defined by that table? There are two ways to publish related tables: Set the adb.publishChildData option to on when configuring the adapters 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 77. 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 181 for details.
Why does TIBCO Designer display a Java exception error while Im 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
274
| Appendix A
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.
| 275
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 276 Status Messages, page 283
276
| 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 277. The following example shows a trace message containing some of these fields and then identifies the fields.
2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000067 Message containing class /tibco/public/class/ae/Customer received on subject FROM.SAP tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#
Timestamp: 2003 Feb 22 20:15:12:937 GMT -8 Adapter ID: FileAdapter.FileAdapterConfiguration Role: Info Category: [Adapter] Status Code: AEFA-000067 Message containing class
/tibco/public/class/ae/Customer received on subject FROM.SAP
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
Overview 277
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#
The final trace message indicates the object has been moved to the output directory, which completes the adapters 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
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.
278
| Appendix B
Trace Messages
Table 40 Trace Message Fields (Contd) Field Name Role Description (Contd) 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.
Overview 279
Table 40 Trace Message Fields (Contd) Field Name Category Description (Contd) 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 283 for details. A unique identifier that is "stamped" on each message by the originating adapter. The tracking identifier remains in effect from a messages 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.
Tracking Identifier
280
| Appendix B
Trace Messages
Table 40 Trace Message Fields (Contd) Field Name Role Description (Contd) 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.
Overview 281
Table 40 Trace Message Fields (Contd) Field Name Category Description (Contd) 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 283 for details. A unique identifier that is "stamped" on each message by the originating adapter. The tracking identifier remains in effect from a messages 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.
Tracking Identifier
282
| Appendix B
Trace Messages
Table 40 Trace Message Fields (Contd) Field Name Application Information Description (Contd) Application-specific information added to the tracking info to trace the message back to its source. Set initially by the originating adapter and carried forward. It is augmented by each intermediate component.
Status Messages
Role
Category
Resolution
AEADB-100002
%1Database connection failed. errorRole Database Check and test the ODBC configuration and restart the TIBCO Runtime Agent.
AEADB-100003
odbc connection as: DSN: %1, User: %2 infoRole Database Normal operation; no action is necessary.
AEADB-100004
Database driver code: %1Database vendor message: %2 errorRole Database Refer to an ODBC manual and to the manual of the native database by using the error code.
AEADB-100005
Unknown database system. warnRole Database The adapter is unable to detect the DBMS type of the database it connects to. Make sure a supported DBMS is used. This condition sometimes occurs because a native character set is used. If you are using a supported DBMS, ignore this warning.
AEADB-100006
%1SQL statement preparation succeeded. infoRole Database Normal operation; no action is necessary.
AEADB-100007
%1SQL statement preparation failed. errorRole Database Preparation of a SQL statement failed. Check the configuration for this adapter service and restart the adapter.
284
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
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
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
AEADB-100015
AEADB-100016
Role
Category
Resolution (Contd)
AEADB-100018
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
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.
286
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
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
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
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.
Role
Category
Resolution (Contd)
AEADB-POLLINGINTERVAL-NOVALUE-ERR errorRole Configuration Unable to retrieve polling interval value from Hawk method. Retaining original value of %1 milliseconds. Please make sure a value is specified before invoking the setPollingInterval method.
AEADB-200013
AEADB-POLLINGINTERVAL-NEGATIVE-ERR errorRole Configuration Negative value of %1 for polling interval not allowed. Retaining original value of %2 milliseconds. Please make sure to specify a non-negative value for the polling interval.
AEADB-200014
AEADB-200015
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-200019
288
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
AEADB-POLLINGBATCHSIZE-CHANGED warnRole Configuration The repository encoding should be set to UTF-8 if your agent encoding is not ASCII or LATIN-1. Set the repository encoding to UTF-8.
AEADB-300001
%1exception thrown in %2. errorRole System An adapter internal error. Contact TIBCO Support.
AEADB-300002
Not enough memory available. errorRole System Check the virtual memory of the system and restart the adapter. If it keeps happening, contact TIBCO Support.
AEADB-300003
MException throw in %1: %2. errorRole System An Adapter SDK exception was thrown. Report the SDK error code and text to TIBCO Support.
AEADB-300004
%1 on connect socket in thread failed errorRole System A TCP system call failed. Check your computers 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 computers 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 computers 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 computers network ports and TCP libraries. Rebooting the computer may solve the problem.
Role
Category
Resolution (Contd)
Socket creation in thread failed errorRole System A TCP system call failed. Check your computers network ports and TCP libraries. Rebooting the computer may solve the problem.
AEADB-300009
Out of memory building the WHERE clause errorRole Adapter An adapter process has run out of memory. Increase the amount of memory allowed to the adapter on your system.
AEADB-400001
%1Unknown column name %2 errorRole Metadata Request is missing a column field in the Bind data. Add a column, tableName.columnName field, to your bind data.
AEADB-400002
%1Unknown column type: %2 for field: %3. errorRole Metadata The type %2 is an invalid AE class type. Check in the repository for attribute %3 and change the class type to a valid AE class type.
AEADB-400003
Unknown column type, %1, %2 infoRole Metadata Normal operation; no action is necessary.
AEADB-400004
AEADB-400005
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.
290
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
%1Failed to set limit policy for event queue %2 on session %3: %4 errorRole TibRvComm TIBCO Rendezvous failed to set the limit policy according to the -rv-max-queue-size specification. Please report this error text to TIBCO customer support.
AEADB-600002
%1Failed to get queue count for event queue %2 on session %3: %4 errorRole TibRvComm TIBCO Rendezvous failed to get the queue count for the given session. Please report this error text to TIBCO customer support.
AEADB-600003
%1Failed to get queue limit for event queue %2 on session %3: %4 errorRole TibRvComm TIBCO Rendezvous failed to get the limit policy for the given session. Report the this error text to TIBCO Support.
AEADB-600004
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. Refer to your TIBCO Rendezvous documentation for resolution information.
AEADB-700001
AEADB-700002
%1Building SQL statement succeeded%2. infoRole Adapter Normal operation; no action is necessary.
Role
Category
Resolution (Contd)
%1Binding data to placeholders: unknown column type, %1 for field %2. Ignoring errorRole Adapter The type %1 is an invalid AE class type. Check in the repository for attribute %2 and change the class type to a valid AE class type.
AEADB-700004
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
AEADB-700007
AEADB-700008
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.
292
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
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
AEADB-700013
%1Cold start failed. errorRole Adapter Run the adapter using debug 3 and verbose mode.
AEADB-700014
AEADB-700015
AEADB-700016
AEADB-700017
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.
Role %1 = %2 debugRole
Category
Resolution (Contd)
Adapter
AEADB-700022
AEADB-700023
%1Bulk insert turning off. infoRole Adapter Normal operation; no action is necessary.
AEADB-700024
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
AEADB-700030
AEADB-700031
AEADB-700032
294
| Appendix B
Trace Messages
Role %1 infoRole
Category
Resolution (Contd)
Adapter
AEADB-700034
Bad date encountered: %1 errorRole Adapter Check your dateTime-related message data and make sure it is in the correct format.
AEADB-700035
Parameterized subject %1 exceeds TibRv maximum subject length of %2 errorRole Adapter Shorten a parameterized subject string length.
AEADB-700036
AEADB-700037
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
Role
Category
Resolution (Contd)
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
AEADB-700046
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.
296
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
%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
AEADB-700054
%1Error sending reply to %2 - %3 errorRole Adapter TIBCO Rendezvous failed to send a reply message to the request client. Report this error text to TIBCO Support.
AEADB-700055
%1Failed to create sender for reply errorRole Adapter TIBCO Rendezvous failed to create a reply sender. Please report this error text to TIBCO customer support.
AEADB-700056
RequestReply: No reply name. Not sending reply errorRole Adapter Specify a reply-subject when defining an adapter request-response service.
AEADB-700057
%1Error retrieving bind position errorRole Adapter Check the request message format. For a given field in the message, make sure it is present in the database.
AEADB-700058
AEADB-700059
Starting thread (name: %1, id: %2) infoRole Adapter Normal operation; no action is necessary.
AEADB-700063
Role
Category
Resolution (Contd)
AEADB-700065
AEADB-700066
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 32.
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.
298
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
%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
AEADB-700077
AEADB-700078
Received message discarded by alterMsgSub() infoRole Adapter Normal operation; no action is necessary.
AEADB-700079
%1Unable to create AE object from the message: %2 warnRole Adapter An unpacking error occurred in the Adapter SDK layer. The message may be corrupted or of a wrong format. Check the Adapter SDK error message if any to determine what the problem is.
AEADB-700080
Received its own message. Discarding. infoRole Adapter Normal operation; no action is necessary.
AEADB-700081
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
Role
Category
Resolution (Contd)
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
AEADB-700086
Publisher batch confirm timeout infoRole Adapter Normal operation; no action is necessary.
AEADB-700087
AEADB-700088
Unknown driver %1 errorRole Adapter The adapter currently only supports ODBC drivers (including the IBM client access driver).
AEADB-700089
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.
300
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
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
AEADB-700096
Unable to insert %1 into list errorRole Adapter Wildcard TIBCO Rendezvous subject names are not currently supported for preregistered listeners.
AEADB-700097
AEADB-700098
%1Error binding parameter %2 errorRole Adapter There was a database error that occurred while binding parameters to a SQL statement. The message will not be processed. Use the database error if any to determine what the problem is.
AEADB-700099
RequestReply: Error retrieving value for parameter %1 errorRole Adapter A request has no value specified for input parameter %1. Add a (data, rvmsgData) field to the [Bind Data] of the request.
AEADB-700100
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.
Role
Category
Resolution (Contd)
Database object %1 not found errorRole Adapter The database object was not found. Check to see if the object really exists (perhaps in another schema) and if you have permission to access it.
AEADB-700103
%1Unknown column type: %2 for field: %3. Ignoring warnRole Adapter The type %2 is an invalid AE class type. For this particular situation, the adapter will skip this attribute and continue processing. Check in the repository for attribute %3 and change the class type to a valid AE class type.
AEADB-700104
Insert into the exception table failed errorRole Adapter There was an error inserting into the exception table. This is a fatal error and the adapter will terminate. Use the error returned by the database to fix the inserts into the exception table.
AEADB-700105
%1%2 are not supported. errorRole Adapter These AE/TIBCO Rendezvous data types are currently not supported by the adapter. Use only supported data types to represent this field instead; for example, a string or binary.
AEADB-700106
AEADB-700107
AEADB-700108
Bulk insert of %1 rows executed for %2 infoRole Adapter Normal operation; no action is necessary.
302
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
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
Error executing listen_alert procedure call errorRole Adapter Check the corresponding database error.
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.
Role
Category
Resolution (Contd)
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-890002
AEADB-890003
AEADB-CONN-RETRYFAIL warnRole Adapter Reconnect failed on attempt %1 for service %2 -will retry in %3 milliseconds. Make sure it is possible to establish an ODBC connection to the database.
AEADB-890004
AEADB-CONN-PUBDUP
304
| Appendix B
Trace Messages
Status Code
Role warnRole
Category Adapter
Resolution (Contd) Connection reestablished for the publisher message may be a duplicate of a previously published message.
AEADB-890005
AEADB-CONN-REQERR errorRole Adapter The request received could not be processed due to connection errors. Make sure it is possible to establish an ODBC connection to the database.
AEADB-890006
AEADB-CONN-STOP errorRole Adapter Adapter stopping due to persistent connection errors. Please check your database and restart adapter. Make sure it is possible to establish an ODBC connection to the database.
AEADB-890007
AEADB-CONN-SVCSUSPEND infoRole Adapter Adapter suspending service %1 due to persistent connection errors.
AEADB-910004
AEADB-STARTUP-4 errorRole Startup Startup Error. SDK Exception %1 occurred in the adapter initialization while creating the MAppProperties object. The Repository URL is %2 and the Configuration URL is %3. Please refer to SDK documentation for Repository URL and Configuration URL specification. Please cut and paste from SDK documentation for the above.
AEADB-910005
AEADB-STARTUP-5 errorRole Startup Startup Error. SDK Exception %1 received on starting the adapter after initialization. The Repository URL is %2 and the Configuration URL is %3. Please verify your repository and environment settings. Refer to the User Guide documentation.
AEADB-910007
AEADB-STARTUP-7
Status Code
Role errorRole
Category Startup
Resolution (Contd) Startup Error. Unable to create a connection with the target database using the dsn %1. The database error is: %2 Terminating adapter. Please verify your repository settings for the validity of connection parameters. Refer to the User Guide documentation.
AEADB-920001
AEADB-SUB-1 errorRole Subscriber Subscription error. Subscription service %1 listening on %2 received an unexpected event: %3. The Repository URL is %4 and the Configuration URL is %5. Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to User Guide for details on configuration of subscription service.
AEADB-920002
AEADB-SUB-2 errorRole Subscriber Subscription error. Subscription service %1 failed to deserialize the event received on subject %2 and SDK exception thrown is %3. The event is: %4. The Repository URL is %5 and the Configuration URL is %6. Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to User Guide for details on configuration of subscription service.
AEADB-920006
AEADB-SUB-6 errorRole Subscriber Subscription error. Subscription service %1 listening on subject %2 received error %3 in SDK message level UserExit %4. Make sure the UserExit parameters are valid and the user exit is invokable from SDK.
306
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
AEADB-SUB-7 errorRole Subscriber Subscription error. Subscription service %1 listening on subject %2 could not get the class description of %3. The Repository URL is %4 and the Configuration URL is %5. Please check the repository configuration for this service. Please make sure the classes to be used by this service are accessible in the repository. Please refer to User Guide for details on how to configure, run and test the subscription service.
AEADB-920015
AEADB-SUB-15 errorRole Subscriber Subscription error. Subscription service %1 listening on subject %2 failed due to database error: %3 Database is %4. The database commands and parameters are %5. Please look at the database error, note the database error code and consult with your database documentation.
AEADB-920017
AEADB-SUB-17 errorRole Subscriber Subscription error. Subscription service %1 listening on %2 could not send response %3 on reply subject %4. The SDK error is %5. Please check your repository settings for the publish endpoint of this subscription service. Please refer to user guide on how to configure the subscription service.
AEADB-930002
AEADB-PUB-2 errorRole Publisher Publication error. Publication service %1 with publication subject %2 encountered database error: %3 while trying to create publish event with schema %4. Database is %5. The database command is %6. Make sure that the publication service is configured properly. Please look at the database error, note the database error code and consult with your database documentation.
Role
Category
Resolution (Contd)
AEADB-PUB-3 errorRole Publisher Publication error. Publication service %1 with publishing subject as %2 received event database %3. It failed while converting the event to "Minstance" as it could not get the class description for %4. Repository URL is %5 and the Configuration URL is %6. Please verify the configuration of the publication service and check that the schema/class definitions are present in the repository. Please refer to User Guide for details on how to configure a Publication service.
AEADB-940001
AEADB-REQRESP-1 errorRole Request_Resp onse_Server Request-Response error. Request-Response service %1 listening on %2 received unexpected null data in incoming request. Expects object %3. The Repository URL is %4 and the Configuration URL is %5. Please check the configuration of the application that is requesting the event and make sure that it matches the inbound event definition for the above RequestResponse service. Please refer to User Guide for details on configuration of RequestResponse service.
AEADB-940009
AEADB-REQRESP-9 errorRole Request_Resp onse_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.
308
| Appendix B
Trace Messages
Role
Category
Resolution (Contd)
AEADB-REQRESP-10 errorRole Request_Resp onse_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 errorRole Request_Resp onse_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
| 309
Appendix C
Topics
Overview, page 310 Properties File Format, page 310 Run-time Adapter Properties File Parameters, page 311 Obfuscating or Encrypting a Password in the Properties File, page 323
310
| Appendix C
Overview
The run-time adapter parses a properties file at startup. The default run-time adapter properties file is named adbagent.tra. The default properties file is located in the install-path\bin subdirectory. Each line in a properties file is a single property. Each property consists of a key and a value. The key starts with the first non-whitespace character and ends at the first "=", ":", or whitespace character. The value starts at the first character after the equal sign (=). For example:
tibco.configurl=/tibco/private/adapter/test/config/config1 tibco.repourl=tibcr://TEST_PROJECT tibco.username=admin tibco.password=samplePassword tibco.clientVar.service=7600 tibco.clientVar.daemon=tcp:7600
Properties defined in the properties file override the same properties defined in the project.
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 323 for more information.
Overview 311
Description
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
The name of the adapter instance. The length of the name cannot be larger than 80 characters.
312
| Appendix C
Table 41 Required Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
tibco.clientVar.adb.passwor d
Description (Contd)
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 323. 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.args
application.start.dir
application.library
The name of the dynamic library of the adapter instance. The name of the dynamic library of the adapter service engine instance. This property is used only on the UNIX platforms.
application.ase.library
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. . All paths inside a properties file, including Microsoft Windows directory names, must use forward slashes. Table 42 Additional Run-Time Adapter Properties File Parameters Property
adb.<publisher_service_name>.lookba ck
Description
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.
Overview 313
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.<table name>.poll.hint. <hint_value>
Description (Contd)
This feature helps improve the performance of your queries. This feature is only supported by Oracle databases. See Using Oracle Hints on page 325 for more information.
adb.ADBPublisher.preRegisteredLis teners
preregisters RVCM name rvcm1 to subject adb.sub1, and RVCM name rvcm2 to subject adb.sub2.
adb.addCustomHawkMethodsTo ClassMAgent <on/off>
The property is not set by default. Setting the property to off disallows adding custom methods to the adapters standard microagent. Setting to on allows custom methods to be added to the adapters standard microagent. The default iSeries library to be accessed. The name of the library where the programs will be created. 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.as400.defaultLibrary adb.as400.library
314
| Appendix C
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.createMutextable
Description (Contd)
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. The DB2 database name for OS390. The adapter uses the value of this property when creating the table used by the fault tolerance functionality. The debug printing level. If not specified, the default, 0, is used. Possible values are: 0 - No debug information displayed. 1 - SQL commands executed against the database display. 2 - In addition to 1, the ODBC data source for each SQL command displays. 3 - Displays values for all ODBC placeholders. adb.disableTerminationSubject When this property is set to on, the adapter does not terminate on receiving a termination subject message. ODBC system data source name. If not specified, the system data source name is read from the repository.
adb.database
adb.debug
adb.dsn
Overview 315
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.encoding
Description (Contd)
The encoding to use. Required when using a non-ASCII character set, as in globalization. See Overview, page 206, and Relevant Environment Settings, page 215, 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 LATIN_1 ibm-949 ibm-943 tibx-943 UTF8 (GBK ) (ISO8859-1 ) (KSC-5601 ) ( Shift_JIS (CP943)) ( Shift_JIS (TIBCO))
( UTF8)
adb.groupsize
Specifies the number of rows to publish in a single message. Overrides the Group Size setting in the publication service configuration. 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.heartbeat
adb.maxLongLen
The buffer size. Used for long data types such as BLOB. 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.maxQuery
316
| Appendix C
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.mutex
Description (Contd)
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. 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.password
Password for the user account used to access your database. If not specified, the password stored in the repository is used. Either on or off. The default is off. 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. Specific polling period. Applies only to publisher instances. If not specified the default, 10, 000 milliseconds, is used. 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.
adb.perfMon adb.PollingBatchSize
adb.PollingInterval
adb.primary.heartbeat
Overview 317
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.pubBatchConfirmSize
Description (Contd)
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.
318
| Appendix C
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.RequestResponseMaxRows
Description (Contd)
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. The number of threads used by the Request/response Service. The default value is 1. Total number of reconnection attempts. This property specifies whether RV advisory messages are be logged in the adapter log files. The default value is off. 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. 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.requestResponseThreads
adb.RetryTotal adb.rvAdvisoryNoLog
adb.rvMaxQueueSize
adb.secondary.heartbeat
adb.setClientInfo
When set to on, the adapter will call SET_CLIENT_INFO to set the database session client information. The default value is on.
adb.setEmptyStringNullForRvMsg
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
Overview 319
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.stmtCache
Description (Contd)
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. Applies only to subscriber instances. All incoming messages to insert are stored until this size is reached. Then a bulk insert operation is performed on the destination table. This value must be less than or equal to the value specified for adb.subBatchCommitSize, if used. The default value is 1. If an update statement is published while messages are being batched, the bulk insert is performed regardless of whether the size value has been reached. After records have been inserted, the update operation is performed. Note: Do not use this option if LONG, LONG RAW, image, or varbinary records are published.
adb.subBulkInsertSize
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.
320
| Appendix C
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.terminateOnPubFail
Description (Contd)
Specifies that if publication fails, the agent will terminate after the status has been updated to F. The default value is off. Either on or off. 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. Refer to the ODBC driver documentation for more details. For Microsoft SQL Server, set the value of this property to UTF16.
adb.traceOldMessages adb.unicode
adb.useBetweenClause
This property disable the use of the BETWEEN clause in the select query of the publisher. The default value is on.
adb.useExceptTable on|off
Enables the use of the exception table. The exception table is defined when a subscription is created. Database account name used by the adapter to access your database. If not specified, the database username stored in the repository is used.
adb.user
Overview 321
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
adb.useSqlColumns
Description (Contd)
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. 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.
adb.wchar
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
322
| Appendix C
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
ntservice.displayname
Description (Contd)
Name to display in the Services control for this Windows Service. This property is useful if you wish to have multiple Windows Services for the same executable. That is, you may wish to have two adapter running on the same machine. By specifying different service names and display names for the adapters, you can accomplish this.
ntservice.interactive
Either true or false. Specifies whether the Windows Service is interactive. Set to false if you are not using a system account. 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.name
ntservice.password
ntservice.account
You can use this property to initially set the password for the user account, but once the service is installed, use the Services control to change the password. ntservice.starttype Start type for this Windows Service. Either manual or automatic. For example: ntservice.starttype automatic You can use this property to initially set the start type for the service, but once the service is installed, use the Windows Services control to change the start type of services.
Overview 323
Table 42 Additional Run-Time Adapter Properties File Parameters (Contd) Property (Contd)
tibco.clientVar
Description (Contd)
Run-time values for global variables defined inside the repository. This value takes precedence over any global value set in the repository. Substitution takes place at run-time. You append the global variable to tibco.clientVar, then give its value. For example, a global variable named DirLedger is specified as follows:
tibco.clientVar.DirLedger C:/tibco/adapter/adadb /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 323. Displays a banner with version information, then exits. This option is for troubleshooting purposes only.
-version
324
| Appendix C
If you plan to run the adapter locally, define the run-time password value to be a global variable. Before starting the adapter, include the run-time password as client variable in the adapter's .tra file and obfuscate it using obfuscate tool. For example, if the password value is defined as %%myPassword%%, create a global variable named myPassword in the global variables section with no value and include the following entry in the adapter's .tra file:
tibco.clientVar.myPassword
Do not set the password to type Password in the global variables section for adapter configurations that are set to AE Version 4.0 or AE Version 5.0 (in the Configuration tab Version field) or any intermediate version. Obfuscating a Password The run-time adapter needs a password to access the backend database. If you have unchecked the Remember Password checkbox in the Design-time Connection tab, the global variable %%adb.password%% is saved in the project. For run-time, you open the .tra file and add the password in clear text in the tibco.clientVar.adb.password=#password property. You can use the obfuscate tool to hide this password so it cannot be viewed by unauthorized users. If you dont want to obfuscate the password, remove the # at the beginning of the password. To obfuscate the password: 1. Using TIBCO Designer, open the adapter configuration and display the Design-time Connection tab. 2. Uncheck the Remember Password checkbox. 3. Apply the changes and save the project. This saves the global variable %%adb.password%% as the value of the password property in the project. 4. In the run-time adapter properties file, verify that the tibco.clientVar.adb.password=#password property is defined in clear text. 5. Run the obfuscation tool supplied with the adapter against the properties file. This tool is named obfuscate.exe and resides in the TIBCO_home\tra\<version_number>\bin directory. The command syntax is:
obfuscate
tra_file_pathName
where tra_file_pathName is the absolute pathname of the adapter properties file that contains the tibco.clientVar.adb.password=#password property.
Overview 325
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:
<install-path>/tibco/tra/<version_number>/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.
<hint value>
where, <table-name> is the name of your table and<hint value> is the Oracle hint.
326
| Appendix C
Examples a. To force an index scan when polling, set the property as follows:
adb.p_p1.poll.hint /*+INDEX(P1,P1_INDX)*/
where P1 is the publisher table, and P1_INDX is 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 force a index scan when the adapter fetches records from a child table set the property as follows: adb.p_p1.poll.hint /*+INDEX(C1,P1_INDX)*/ where C1 is the child table, and P1_INDX is the index created on the child table. The adapter will execute this select query on the child table:
SELECT /*+INDEX(C1,P1_INDX)*/ * FROM C1 WHERE ID = ?"
| 327
Index
Symbols
* 166 . 166 > 166 _ 32, 166
A
access to DB2 AS/400 tables 71 adapter changing a configuration 33, 198 component (operation) information through TIBCO Hawk 231 error messages when changing a configuration 34 naming restrictions 32 size limitations 32 stopping 32 tracing 193 unicode setting 320 adapter configuration, changing 33, 198 Adapter Services folder 5 adapter setting client info 318 ADB_ERROR_TEXT 155 ADB_ERROR_TIME 156 time zone 156, 158 ADB_L_CMSEQUENCE 149 ADB_L_DELIVERY_STATUS 149 ADB_OPCODE 149, 155 ADB_REF_OBJECT column in the publishing table 173 ADB_SEQUENCE 148 ADB_SET_SEQUENCE 148 ADB_SOURCE 154 ADB_SUBJECT 148 ADB_TIMESTAMP 148 timezone 148
ADB_UPDATE_ALL 149, 155 adbDateTime 172 adbPreCommit() 183 adding listeners 168 adding a sequence for parent-child 175 adding an association for parent-child 176 advanced folder 5 agents 218 alerter on Sybase SQL Server 112 alerts 218 auto-discovery process, TIBCO Hawk 220
B
binary type 167 bind statements 123
C
callout library 181 certified message delivery exception handling 271 moving ledger files 170 preregistering listeners 168 Class Microagent Name field, adapter 61 closure field 122 column names in an exception table 157 column names, reserved prefix 33 columns, maximum number 32 command line arguments 232
328
| Index
commands adbagent 110, 114 Connect 42, 46 copy 109, 113 cp 112 isql 109, 110, 112, 113, 114 select 23, 24, 25, 26, 27 sqlplus 20, 27, 107, 108 tibrvsend 26 commit_and_notify_table 105 configuration properties, retrieving through TIBCO Hawk 232 custom RPC operation 133 customer support xvii exception table, column names in 157
F
fault tolerance 316 file format dat 16 VC 16 Float data type 167
G D
dat file format 16 data source, ODBC using 314 database errors, capturing 155 database type mapping 166 Date types 167 date/time values 172 dateTime 164 DB2 on OS/390 trigger statements syntax 200 debug, adapter option 313 delete trigger 69 distributed queues 140 dot character 166 dsn, adapter option 314 global variables 34 setting for monitoring 60
L
ledger files location 170 moving 170 publication size status 317 publication timeout status 317 retrieving information through TIBCO Hawk 241 listeners, adding 168 load balancing across adapters 140 in an adapter 138 Log File field, adapter 54 log file options 193 log files location 55 Log to Standard field, adapter 54 LONG data type 78 loop detection column used for 154
E
ENV_HOME xv error messages about database cleanup 34 examples REF cursor procedure 145 Exceed FAQ 273 exception table structure of 155
TIBCO ActiveMatrix Adapter for Database Users Guide
Index 329
M
mapping database types 166 metadata 6 microagent methods supported 224 Microagent Session field, adapter 61 multiple file project 204
N
naming restrictions adapters 32 database columns 33 publishing table 77 subjects 166 notify procedure on Microsoft SQL Server 109 on Sybase 112 notifytable procedure on Microsoft SQL Server 109 on Sybase 112 NULL attributes 84
O
obfuscation 310
P
palettes 5 parameterized subject 166 binary type 167 Date types 167 Float type 167 illegal characters 167
parameters AE Type 70, 85 Child Table Mapping 86, 87 Class Reference 81, 91, 96 Deploy On Save 34 Do Not Generate Triggers 77 Enable Loop Detection 77 Endpoint Reference 81, 90, 96 Join To 70, 86 Publishing Table 77 Reply Subject 96 Subscriber Bulk Insert Size 50 Table Name 86, 87 Tables and Columns 70, 85 Type 70, 85 Update Mode 77 Update Trigger? 70 Use? 70, 85 User Key 70, 85 parent-child association 176 parent-child sequence 175 password property 323 PL/SQL procedure for REF cursor 145 preregistering listeners 168 publications size limitations 32 publish-child-data, adapter option 317 publishing by reference 78 source data 173 publishing table columns in 148 name size 77 restrictions for 78
Q
quality of service and load balancing 140 queue member load 141
330
| Index
R
record size, limitations 32 REF data type 145 reference object location 173 repository instance 6 request defined 120 request/response load balancing for 140 using 118 using multiple threads 138 response defined 121 reviewLedger, TIBCO Hawk method 241 RPC programs, client 136 rv_Rpc() 124 rv_Send() 124 rv_SendWithReply() 124 RVMSG_DATETIME 164 RVMSG_INT 164 RVMSG_OPAQUE 164 RVMSG_REAL 164 RVMSG_STRING 164 standard RPC operation 129 starting an alerter on Oracle 105 stopping an adapter 32 sub-batch-commit-timeout, adapter option 319 sub-bulk-insert-size, adapter option 319 subjects naming restrictions 166 parameterized 166 subscriber 32 using wildcards 166, 168 subscriptions size limitations 32 wire format for 172 substitution 34 support, contacting xvii system configurl command-line argument 311
T
table access problems, overcoming 71 technical support xvii TIBCO Hawk background information 218 enterprise monitor components 218 methods supported 224 Monitoring tab use with 60 TIBCO Hawk methods getComponents 231 getConfig 232 getRvConfig 235 getStatus 236 reviewLedger 241 TIBCO Rendezvous, retrieving configuration through TIBCO Hawk 235 TIBCO_HOME xv Tracing 276 tracing features 193 Tracing Levels and Fields 277 tracking identifier 276, 279, 281 triggers no primary key 69
S
schema changes affecting adapter configuration 34 schema data 6 schemas for related tables 71 sequence number 148 source data publishing 173 source data publishing example 179 source table loop detection column 154 SQL statement terminator 200 SQL_BATCHRETURN class, structure of 132 SQL_BIND class, structure of 132 SQL_OPS class, structure of 129 SQL_RESULTSET class, structure of 130 SQL_RETURN class, structure of 130 SQL_ROW class, structure of 130 SQL_STATEMENT class, structure of 132
TIBCO ActiveMatrix Adapter for Database Users Guide
Index 331
U
underscore character 166 update trigger 69 Use Advanced Logging field, adapter 57 user authority 71 user callout library 181 user schema 104 username property 323 use-trace-file, adapter option 193
V
variable substitution 34 variables 34 version, adapter option 323
W
wildcard subject names 166, 168
332
| Index