TIBCO ActiveMatrix Adapter for Database Configuration and ...

TIBCO ActiveMatrix® Adapter for

Database

Configuration and Deployment

Software Release 6.2

January 2012

Important Information

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

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

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

TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Adapter SDK, TIBCO Administrator, TIBCO Database Drivers Supplement, TIBCO Designer, TIBCO Enterprise Message Service, TIBCO Hawk, TIBCO Rendezvous, and TIBCO Runtime Agent are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

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

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

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

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

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

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

TIBCO Software Inc. Confidential Information

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

| iii

Contents

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

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

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

Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

TIBCO ActiveMatrix Adapter for Database Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi

How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi

How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi

How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

TIBCO Administration Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

TIBCO Administration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

TIBCO Administrator GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Adapter Project Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Required Platform and Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18


iv | Contents

Create the Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Configure the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Start the Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

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

Exit the Query Tool and Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Clean Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3 Adapter Instance Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Configuration Task Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Saving the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Testing the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Notes on Configuring an Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Configuration Recommendations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Changing an Existing Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Using Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Adapter Instance Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Design-time Connection Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Using Connection Settings Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Saving Connection Settings for Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Using Saved Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Runtime Connection Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Adapter Services Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

All Publication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

All Subscription Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

All Request-response Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Logging Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Startup Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Monitoring Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 4 Adapter Service Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Quality of Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Delivery Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Wire Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Publication Service Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Tables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66


Contents | v

DB2/OS390 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

DB2/AS400 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Sybase Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Child Table Order By Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Publisher Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Subscription Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Table Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Child Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Child Exception Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Subscriber Options for DB2 on OS/390 (z/OS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Subscriber Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Request-response Service Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Call Operation Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Advanced Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator . . . . . . . . . . . . . . .95

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

Deploy the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Monitor the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Chapter 6 Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and Above . . . . . . . . . . . . . . . . . . 103

Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Configuring and Starting the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Oracle Alerter Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

SQL Server Alerter Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Setting Up and Starting the Alerter on Microsoft SQL Server 2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Alerter Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Setting Up and Starting the Alerter on Sybase SQL Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Before Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Alerter Setup on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Alerter Setup on Microsoft Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Using the Alerter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112


vi | Contents

Chapter 7 Using the Request-response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Request-response Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

TIBCO ActiveEnterprise or XML Message Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

TIBCO Rendezvous Message Request Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

TIBCO ActiveEnterprise or XML Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

TIBCO Rendezvous Message Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

RPC Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Standard RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Custom RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Implementing Client RPC Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Load Balancing in a Single Instance Using Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Load Balancing Across Adapter Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Oracle REF Data Type Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Chapter 8 Working With Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Publishing Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Removing Records from the Publication Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Publication Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Changing the Publication Trigger to Publish a Subset of Rows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Optimizing the Publication Sequence for Oracle RAC System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Source Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Exception Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Child Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Using an Exception Table as a Source Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Opaque Exception Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Incremental Parent-child Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Sybase and Sybase Adaptive Server Anywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

MySQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Teradata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Mapping to Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Chapter 9 Advanced Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Subject and Destination Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Parameterized Subject or Destination Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Preregistering a Certified Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171


Contents | vii

Changing the Location of the Ledger File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Sending Messages to an Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

adbDateTime Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Publishing by Reference Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Changing Repository Objects for Parent-child Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Table to Record Sequence Numbers (DB2 on iSeries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

User Callout Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Using the alterMsgPub and alterMsgSub Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Using the adbPreCommit Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Building the Callout Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Unique Connection Identifier for Oracle Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Publishing in a Commitment Controlled Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

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

Using a Log File for an Adapter Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Fine-tuning Tracing Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Log File Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Using Advanced Logging Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Using Database Deployment and Cleanup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Changing the SQL Statement Terminator (DB2 for z/OS Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

SSL Data Encryption using DataDirect ODBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

OS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Query Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Working with Multi-File Format Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Subscriber Reply Sender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Subscriber Pre-commit Stored Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

JMS Durable Subscriber Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Runtime Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Runtime Table Schema Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Group Message Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Load Balancing and Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Improving Performance Using Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Load Balancing Across Adapter Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Compressing JMS Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Configuring RVCMQ Backlog Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225


viii | Contents

Chapter 10 Setting Encoding Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Setting TIBCO Messaging Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Configuring the Adapter to Communicate with the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Configuring the Adapter at Design Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Special Configurations for Supporting a UTF-8 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Special Configurations for Retrieving Unicode Data from Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Runtime Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Relevant Environment Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Chapter 11 Monitoring the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Starting TIBCO Hawk Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

The Auto-Discovery Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Invoking Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Available Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Appendix A Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

General Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Request-response Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Appendix B Trace Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Status Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Appendix C Adapter Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Properties File Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Tagging Values for Obfuscation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Runtime Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Required Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Additional Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Obfuscating or Encrypting a Password in the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Password Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Obfuscating a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Encrypting a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Using Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349


Contents | ix

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351


x | Contents


Figures | xi

Figures

Figure 1 TIBCO Designer Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Figure 2 TIBCO Administrator GUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Figure 3 Diagram of Publish-Subscribe Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Figure 4 Alerter Operation (Oracle and MSSQLServer). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Figure 5 Request-Response Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Figure 6 Request-response Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Figure 7 Example of Unicode Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228


xii | Figures


Tables | xiii

Tables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Table 2 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

Table 3 Values to Use for TIBCO Rendezvous and JMS Transport Types . . . . . . . . . . . . . . . . . . . . . . . . 18

Table 4 Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Table 5 Adapter Instance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Table 6 Design-time Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Table 7 JDBC Drivers and URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Table 8 Runtime Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Table 9 Publication Service Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Table 10 Subscription Service Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Table 11 Request-response Service Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Table 12 General Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Table 13 Logging Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Table 14 Startup Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Table 15 Monitoring Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Table 16 Publication Service: Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Table 17 Publication Service Tables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Table 18 Publication Service DB2/OS390 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Table 19 Publication Service DB2/AS400 Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Table 20 Publication Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Table 21 Subscription Service Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Table 22 Subscription Service Child Table Mappings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Table 23 Subscription Service Child Exception Table Mappings Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Table 24 Subsciption Service DB2/390 Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Table 25 Subscription Service Subscriber Options Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Table 26 Subscription Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Table 27 Request-response Service Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Table 28 Request-response Call Operation Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92


xiv | Tables

Table 29 Request-response Service Advanced Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Table 30 Request Schema Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Table 31 Reply Schema Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Table 32 Publishing Table Additional Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Table 33 Source Table Additional Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Table 34 Exception Table Additional Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Table 35 Child Exception Table Additional Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Table 36 Opaque Exception Table Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Table 37 Mapping to Database Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Table 38 Wire Format Parameters and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Table 39 adbPreCommit Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Table 40 Description of ADB_SUBSCRIBER_STATUS Class Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Table 41 Description of the Pre-commit Stored Procedure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Table 42 IANAAppCodePage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Table 43 TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang Values . . . . . . . . . . . . . . . . . . 237

Table 44 Standard Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Table 45 Custom Microagent Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Table 46 Custom Microagent Methods with adb.perfMon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Table 47 Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Table 48 Required Runtime Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Table 49 Additional Runtime Adapter Properties File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334


| xv

Preface

TIBCO ActiveMatrix Adapter for Database software is a bidirectional gateway between

databases and applications configured for the TIBCO environment. The software supports

both publish-subscribe and request-response interactions.

Topics

• Changes from the Previous Release of this Guide, page xvi

• Related Documentation, page xvii

• Typographical Conventions, page xviii

• Connecting with TIBCO Resources, page xxi


xvi | Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide

This section itemizes the major changes from the previous release of this guide.

Support for Teradata Database

Adapter instance configuration and supported data types for the Teradata database have

been added. See JDBC Drivers and URLs on page 42, Runtime Connection Tab on

page 45, and Database Types on page 161 for more information.

Support for JMS Message Compression

JMS message compression is an instance-level option that ensures messages will take less

memory space in storage and be handled faster by the TIBCO Enterprise Message Service

server. See Compressing JMS Messages on page 224 for more information.

Support for RVCMQ Backlog Size Configuration

The RVCMQ scheduler receives inbound messages and assigns them to the worker. The

scheduler stores tasks in a message queue. You can limit the maximum size of that queue

by either number of bytes or number of messages, or both. See Configuring RVCMQ

Backlog Size on page 225 for more information.

Parameterized Destination Name Information

Publishing on parameterized subjects or destinations allows a subject or destination to be

created from the contents of one or more table columns. See Parameterized Subject or

Destination Names on page 168 for more information.


Preface | xvii

Related Documentation

This section lists documentation resources you may find useful.

TIBCO ActiveMatrix Adapter for Database Documentation

The following documents form the TIBCO ActiveMatrix Adapter for Database

documentation set:

• TIBCO ActiveMatrix Adapter for Database Concepts Read this manual to gain an

understanding of adapters in general that you can apply to the various tasks you may

undertake.

• TIBCO ActiveMatrix Adapter for Database Installation Read this manual to learn

how to install TIBCO ActiveMatrix Adapter for Database.

• TIBCO ActiveMatrix Adapter for Database Configuration and Deployment This

manual explains how to create and configure adapter projects. Information on

deploying adapter projects is also included.

• TIBCO ActiveMatrix Adapter for Database Examples Read this manual to work

through the examples provided with the adapter.

• TIBCO ActiveMatrix Adapter for Database Release Notes Read the release notes for

a list of new and changed features. This document also contains lists of known issues

and closed issues for this release.

Other TIBCO Product Documentation

You may find it useful to read the documentation for the following TIBCO products:

• TIBCO® Adapter SDK

• TIBCO Administrator™

• TIBCO ActiveMatrix BusinessWorks™

• TIBCO® Database Drivers Supplement

• TIBCO Designer™

• TIBCO Enterprise Message Service™

• TIBCO Hawk®

• TIBCO Rendezvous®

• TIBCO Runtime Agent™


xviii | Typographical Conventions

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME

TIB_ADADB_HOME

ENV_NAME

CONFIG_HOME

Many TIBCO products must be installed within the same home directory. This

directory is referenced in documentation as TIBCO_HOME. The default value of

TIBCO_HOME depends on the operating system. For example, on Windows systems,

the default value is C:\tibco.

Other TIBCO products are installed into an installation environment. Products

installed into different installation environments do not share components.

Incompatible products and multiple instances of the same product must be installed

into different installation environments. An installation environment consists of the

following properties:

• Name Identifies the installation environment. The name is appended to the

name of Windows services created by the installer and is a component of the

path to the product in the Windows Start > All Programs menu. This directory is

referenced in documentation as ENV_HOME.

• Path The directory into which the product is installed. This directory is

referenced in documentation as TIBCO_HOME. TIBCO ActiveMatrix Adapter

for Database installs into a directory within TIBCO_HOME. This directory is

referenced in documentation as TIB_ADADB_HOME. The default value of

TIB_ADADB_HOME depends on the operating system. For example, on Unix

systems, the default value is TIBCO_HOME/adapter/adadb/version.

A TIBCO configuration folder stores configuration data generated by TIBCO

products. Configuration data can include sample scripts, session data, configured

binaries, logs, and so on. This folder is referenced in documentation as

CONFIG_HOME. The default location of the folder is

USER_HOME/ENV_NAME/tibco/cfgmgmt/product_name. For example, on Windows, the

default location is C:\Documents and Settings\user_name\Application

Data\ENV_NAME\tibco\cfgmgmt\product_name.

code font Code font identifies commands, code examples, filenames, pathnames, and output

displayed in a command window. For example:

Use MyCommand to start the foo process.


Preface | xix

bold code font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin.

• In large code samples, to indicate the parts of the sample that are of particular

interest.

• In command syntax, to indicate the default parameter for a command. For

example, if no parameter is specified, MyCommand is enabled:

MyCommand [enable | disable]

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrix

BusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain several

portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For

example: MyCommand PathName

Key combinations Key name separated by a plus sign indicate keys pressed simultaneously. For

example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the

other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for

example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the

information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data

loss or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Cont’d)

Convention Use


xx | Typographical Conventions

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical OR that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3

{ } A logical group of items in a command. Other syntax notations may appear within

each logical group.

For example, the following command requires two parameters, which can be either

the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can

be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The

first parameter must be param1. You can optionally include param2 as the second

parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}


Preface | xxi

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident

experts. It is a place to share and access the collective experience of the TIBCO

community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To

register, go to http://www.tibcommunity.com.

How to Access TIBCO Documentation

You can access TIBCO documentation here:

http://docs.tibco.com

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO

Support as follows.

• For an overview of TIBCO Support, and information about getting started with

TIBCO Support, visit this site:

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

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

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name,

you can request one.

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

https://support.tibco.com

http://docs.tibco.com

http://www.tibcommunity.com


xxii | Connecting with TIBCO Resources


| 1

271

Chapter 1 Introduction

This book provides information on configuring an adapter instance, using adapter

features, and deploying the adapter to the runtime environment.

Topics

• Overview, page 2

• Configuration, page 4

• Deployment, page 9

• Adapter Project Lifecycle, page 11


2 | Chapter 1 Introduction

Overview

TIBCO ActiveMatrix Adapter for Database software (the adapter) allows data changes in

a database to be sent as they occur to other databases and applications. It extends

publish-subscribe and request-response technology to databases, making multiple levels

of delivery services available to applications that need access to these databases. ODBC

and JDBC compliant databases such as Oracle, Sybase, Microsoft SQL Server, MySQL,

and Teradata are supported. While the adapter does not run on z/OS and iSeries systems, it

can remotely connect to a DB2 database running on these systems.

Features

The following capabilities are described in detail in this manual.

• Automatically publish data when rows in pre-specified database tables are inserted,

updated or deleted:

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

— Publish by reference (publish data directly from the source database table without

first copying the data from the source table to a publishing table). See Publish by

Reference on page 74.

— Publish on parameterized subjects or destinations, which allows a subject or

destination to be created from the contents of one or more table columns. See

Parameterized Subject or Destination Names on page 164.

— Preregister certified subscribers with a certified publisher. See Preregistering a

Certified Subscriber on page 167.

— Update both parent and child tables within a publication. Both the parent row and

all related child rows will be published if the user has set up to publish child data.

See Adding Child Tables on page 65.

— Specify that a group of rows fetched from the publishing table is sent in a single

message.

The subject names mentioned in this document are referred to as subject names when

using the TIBCO Rendezvous transport type, but are referred to as destination names

when using the JMS (Java Messaging Service) transport type.


Overview | 3

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

tables in a database:

— Subscribe using wildcard subject names. See Preregistering a Certified Subscriber

on page 167.

— Perform batch commits based on message count or time out value. See Adapter

Instance Tabs on page 34.

— Subscribe a group of rows set in a single message. You can configure the adapter

to update all rows in a single database transaction by turning on the Enable Group

Message Transaction Support option. See Subscriber Options Tab on page 82.

• Use request-response semantics to publish SQL statements, stored procedures, or both

on a specified subject:

— Execute stored procedures with IN parameters, OUT parameters, or both. (Binary

OUT parameters are not supported. This is a limitation of the Oracle ODBC driver.)

See Oracle REF Data Type Support on page 139.

• Support RPC (Remote Procedure Calls). The adapter can act as an operation server

providing a simple means for a client to execute a single or batch of SQL statements.

See Request-response Mode on page 114 and RPC Mode on page 122.

• Change published messages for a publication or subscription service by customizing

the supplied callout library. See User Callout Library on page 179.

• Customize adapter behavior to suit your needs:

— Specify relationships between tables, then publish related tables together. See

Tables Tab on page 62.

— Monitor for database changes using periodic polling or notification by an alerting

mechanism. See Adapter Services Tab on page 43.

• Rely on standards:

— Connect to multiple database vendors using ODBC or JDBC drivers. See

Design-time Connection Tab on page 37 and Table 8, Runtime Connection Tab, on

page 41.

— Interoperate with other TIBCO products through the use of TIBCO Adapter SDK

software. See Sending Messages to an Adapter Instance on page 170.

— Monitor your adapter service using TIBCO Hawk software. See Monitoring Tab on

page 55 and Chapter 11, Monitoring the Adapter, on page 233.

— Choose message transports: TIBCO Rendezvous or JMS (Java Messaging

Service).

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



Configuration

TIBCO Designer, the design-time component, is an easy-to-use graphic user interface.

The TIBCO ActiveMatrix Adapter for Database palette in TIBCO Designer is used to

create adapter instances, configure adapter services, download schemas, and save the

resulting configuration in a project.

Before using TIBCO Designer, make sure you read the TIBCO Designer product

documentation.

The following figure shows the TIBCO Designer interface.

Figure 1 TIBCO Designer Main Window

Project Panel

Each TIBCO Designer window contains one and only one project, which is represented as

the root folder in the panel.

Design

Configurationpanel

Menu bar

Projectpanel

panelPalette

panel

Tool bar


Configuration | 5

Projects are the key organizational principle for the configuration information you specify.

A project is a collection of all configured resources. Resources are the components of a

project. For example, an adapter publication service is a resource. Resources can be

complex and contain other resources, much like a folder can contain other folders on your

computer file system. Together, these resources make up your integration project. The

top-level (root) folder in the project tree panel represents a project. The top-level folder is

initially named Untitled and is renamed to the name of the project when you save the project

for the first time.

Most adapter resources have context-sensitive help available for the configuration of that

resource. Right-click on the resource and choose What Is This? from the popup menu for

more information on configuring the resource.

An adapter project contains the following folders:

• AESchemas Folder

The AESchemas folder is the default location for all TIBCO ActiveEnterprise schema

files. Each schema file contains a collection of classes, scalars, associations, unions,

and sequences.

• Adapter Services Folder

The Adapter Services folder contains services available to the adapter. Most adapters

include publication, subscription, request-response, and request-response invocation

services.

• Advanced Folder

The Advanced folder contains resources created by TIBCO Designer while the adapter

is configured. For example, each time you add a service to an adapter, a session and

endpoint are created and stored in the Advanced folder. Other resources such as

advanced logging resources are accessed directly from the folder. Adapter developers

typically do not access resources in this folder. Most of the adapter configuration is

done by changing resources that are available from the Adapter Services folder.

Palette Panel

Palettes organize resources and allow you to add them into your project. Palettes are

available from the palette panel in TIBCO Designer. Resources are visible components in

a palette. You select resources in the palette panel and drag-and-drop them into the design

panel to add them to your project.

Each adapter you install adds one or more palettes during installation. Which palette is

displayed depends on the resource selected in the project tree and on your preferences. In

the default view, the current selection in the project tree determines which palettes are

displayed in the palette panel.



Design Panel

The design panel displays the current resource selected in the project tree panel. For

resources that contain other resources, the contents of the selected resource are shown in

the design panel. For example, if you select a folder, its contents are displayed.

Configuration Panel

The configuration panel allows you to specify configuration options for the selected

resource. The type and the purpose of the resource determine the contents of the

configuration panel. There are usually one or more tabs in the configuration panel that

allow you to access the various configuration options. The tabs provide an organization to

the options for the resource.

You can click the question mark icon (?) in the top right corner of the configuration panel

for online help on the current selection.

For each tab, you must click the Apply button after you have specified configuration

information before you can select another tab. If you decide you do not want to add the

configuration information, click the Reset button before you apply any changes to return

to the previous values for each field in the tab.

Projects

A project is a named collection of data, usually schema data, and configuration data that is

persistently stored. Each project is opened and saved in multi-file format, which allows

the project to be used with a version control system. It allows different developers to

collaborate on a project and merge changes as needed.

When a project is ready to be deployed, it can be created or exported in the following

formats:

• Enterprise Archive File

• Local Repository

• Server Repository

• ZIP Archive

Enterprise Archive File

An Enterprise Archive file contains information about the adapter instances and processes

you wish to deploy. The format is used by TIBCO Administrator. The EAR file is

imported into Administrator where you can deploy, start, and manage the adapter instance

on the machines of your choice.


Configuration | 7

Local Repository

A project exported to a local repository is saved in .dat format. Projects saved in .dat format

should only be used for development and testing. The format can be used where data is not

shared by more than one adapter. It is possible to have a few local adapters accessing a

local project in read-only mode. It is, however, not possible to have more than one local

adapter accessing a local project in read and write mode.

Data are loaded at startup for local projects, so a local project has higher memory

requirements.

Server Repository

A project exported to a server repository is managed by a TIBCO Administration Server

running in a separate process, typically elsewhere on the network. One or more adapters

can communicate with a project managed by an Administration Server. Each can support

multiple projects.

An Administration Server is identified by a name that must be unique among all

administration servers on a network. The server-based mode of operation is scalable and

generally recommended for production situations. Server repositories allow multiple

simultaneous write operations with locking, automatic updates of clients, and notification.

Data are loaded on demand for server-based projects.

ZIP Archive

A project exported to a ZIP archive is written to the location you specify as a read-only

ZIP file. A project exported as a ZIP archive can be imported into TIBCO Designer.

Version Control

TIBCO Designer allows multiple developers to work on the same project and to use file

sharing (locking) or a version control system so that the same resource is not changed by

two developers at the same time. Different users can then add resources to the project and

lock the parts of the project they are working on.



TIBCO 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

runtime components to the machines on which they will ultimately run in a production

environment. An adapter instance can be deployed, started and managed using TIBCO

Administrator from the Administrator web browser.

Using TIBCO Administrator, you can upload the EAR, deploy the adapter on the

machine(s) of your choice, and set runtime options before deployment. Additionally you

can start and stop the adapter using TIBCO Administrator.

TIBCO Administrator also provides built-in tools to monitor and manage the adapter.

TIBCO Administrator provides user, resource, and application management modules for

adapters.

• User Management. This module allows you to set permissions for adapter users. You

define authentication, users and groups, and assign access control lists to users. This

includes security for server-based projects at design time and for deployed

applications at runtime.

• Resource Management. This module allows you to monitor machines and all

running applications in a TIBCO administration domain. Alerts can be created, for

example, to notify an administrator if the number of processes or disk usage exceed a

certain number.

• Application Management. This module allows you to upload Enterprise Archive

(EAR) files, and create, configure, and deploy adapters. This console is also used to

start and stop adapters.

TIBCO Administration Domain

A TIBCO administration domain is installed only if you have also installed the User

Management module.

A TIBCO administration domain is a collection of users, machines, and components that

an administration server manages. There is only one Administration Server for each

administration domain. Components within an administration domain can communicate

with systems outside of the domain, but the domain is the administrative boundary of your

enterprise integration project.

.See the TIBCO Administrator product documentation for more information.



TIBCO Administration Server

The TIBCO Administrator Server provides a central storage and distribution point for

configuration data and schema data needed by an adapter. The server is included in both

Administrator editions.

Each administration domain has one and only one TIBCO Administration Server. The

TIBCO Administration Server is the machine process that handles the stored project and

requests to manage the TIBCO administration domain.

The TIBCO Administrator Server contains its own web server (Apache Tomcat) that can

be accessed via the TIBCO Administrator GUI for configuration and monitoring

information.

TIBCO Administrator GUI

You can access the TIBCO Administration Server using the web-based TIBCO

Administrator GUI. The GUI allows you to create users and assign access to projects

managed by the Administration Server. You can invoke the GUI from any machine in a

TIBCO administration domain. The next diagram shows the GUI.

Figure 2 TIBCO Administrator GUI


Adapter Project Lifecycle | 11

Adapter Project Lifecycle

This section describes the high-level steps required to configure and deploy an adapter.

Each of these steps are described in details in subsequent chapters. Adapter projects are

configured using TIBCO Designer.

Configuration

Task A Configure the Vendor Application to work with the Adapter

This task is completed as part of installing the adapter and before configuring an adapter

instance for the first time.

Task B Define an Adapter Project

When starting TIBCO Designer, you create or select a project. A project contains adapter

configuration information, such as the service and messaging transport to use, logging

options, and other specific settings. A project is opened and saved in multi-file format,

which allows a version control system to manage the files associated with the project.

See Adapter Instance Tabs on page 34 for more information.

Task C Set Global Variables

By default each project you create in TIBCO Designer includes several global variables.

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

Default values are predefined for some of the variables. You can define additional

variables and, optionally, set their values when configuring your adapter.

When the project is deployed and the configured adapters are run, all occurrences of the

global variable name are replaced with the global variable value.

A global variable value set in TIBCO Designer can be overridden at runtime by redefining

the value in TIBCO Administrator.

See Using Global Variables on page 30 for more information.

Task D Configure an Adapter Service

The adapter supports the following services: publication, subscription, request-response,

and request-response invocation.



Task E Test the Adapter Configuration

The adapter tester can be used to verify an adapter service after it has been configured.

When invoked, all adapter services configured in the project are displayed. You select the

adapter service to test, and start and stop the adapter from the tester. The tester window

displays adapter output within the tool so you can easily view results.

Deployment

During development, you save your design to a project. When you are ready to deploy

your project to a machine, you generate an Enterprise archive file (EAR file) from TIBCO

Designer. The EAR file contains information on what you wish to deploy

Task F Generate and Import an Enterprise Archive File

An Enterprise Archive file contains adapter instance configuration information, which is

used by a runtime adapter. An Enterprise Archive file is generated using TIBCO Designer

and imported into TIBCO Administrator.

See Create an EAR File in TIBCO Designer on page 92 for more information.

Task G Specify Deployment Information

After importing an Enterprise Archive file, the adapter can be deployed. This involves:

• Assigning adapter services to the machines in the administration domain.

• Specifying startup options for each process engine and adapter service.

See Deploy the Project on page 93 for more information.

Task H Specify Monitoring Options

Before starting the adapter you can optionally specify monitoring options, including:

• Specifying alerts or TIBCO Hawk rulebases for each machine.

• Specifying alerts and TIBCO Hawk rulebases for an adapter service.

• Setting log file properties for an adapter service instance.

Task I Start the Adapter

The adapter is started and stopped using the TIBCO Administrator GUI.

See Start or Stop the Adapter on page 94 for more information.


| 13

Chapter 2 Getting Started

This chapter helps you get familiar with the adapter by walking you through a basic

exercise. Work through the exercise to get a hands-on understanding on how the adapter

works.

Topics


• Create the Database Tables, page 17

• Configure the Properties File, page 18

• Start the Adapter Services, page 20

• Change the Table Values and Receive Notification, page 21

• Exit the Query Tool and Adapters, page 23

• Clean Up, page 24


14 | Chapter 2 Getting Started

Overview

In this exercise, you create tables in your database and configure a publisher adapter and a

subscriber adapter. Then you modify a table and observe how the publisher adapter and

subscriber adapter handle the change and update the subscription table.

Required Platform and Software

This exercise can be performed on any supported operating system, using adapters

provided with TIBCO ActiveMatrix Adapter for Database. The exercise can be run using

the TIBCO Rendezvous transport method or the JMS transport method.

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

A sample DAT file that can be used with an Oracle database, ADBDemo2-ora.dat, is included

in the TIB_ADADB_HOME\demo\demo2 directory.

Before Starting

Before performing this exercise, make sure that TIBCO ActiveMatrix Adapter for

Database is installed according to the procedures in the TIBCO ActiveMatrix Adapter for

Database Installation.

You should be familiar with using TIBCO Designer to open and close projects and drag

and drop resources; see the TIBCO Designer User’s Guide for more information. That

document also describes the multi-file format used by TIBCO Designer, and converting to

and from the .dat file format used by the runtime adapter. The TIBCO Designer User’s

Guide is available from TIBCO Designer by selecting Help > Designer Help.

Tables

The tables are created by running a script specific to your database vendor. The script

creates the following tables, all with a common set of columns:

• Source table to which you will add new data.

• Publishing table to which the new data from the source table is copied using the

trigger set on the source table. This table has additional columns (prefixed by ADB_)

that are used by the adapter.

• Destination table that TIBCO ActiveMatrix Adapter for Database will update with

the new data.

• Exception table to which TIBCO ActiveMatrix Adapter for Database will write any

errors that occur during subscription.


Overview | 15

Actions

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

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

2. The publisher adapter polls the publishing table to check if any new rows have been

inserted. Newly inserted rows are fetched using ODBC, packed into a message, and

published.

3. The subscriber adapter listens for messages. When a message arrives, the subscriber

adapter inserts it into the destination table using ODBC.

The following diagram illustrates the activity.

Figure 3 Diagram of Publish-Subscribe Steps

Tasks

This exercise consists of the following tasks:

• Create the Database Tables, page 17

• Configure the Properties File, page 18

• Start the Adapter Services, page 20

• Change the Table Values and Receive Notification, page 21

Source

Table

TIBCO Messaging

Adapter

PublisherAdapter

Subscriber

Publishing

Table

Destination

Table

Exception

Table

Insert Trigger



• Exit the Query Tool and Adapters, page 23

• Clean Up, page 24

Exercise

This exercise uses the Oracle database. You can use the TIBCO Rendezvous or JMS

transport. When performing this exercise, use the appropriate transport values for your

configuration (as listed in Table 3 on page 16) and follow the instructions that pertain to

your particular database vendor.

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

• Database user ID

• Database password

• Database service7

The values you will enter for the tables and the publisher and subscriber adapter instances

are different, depending on which transport type you are using. (The kind of database you

are using does not affect these names.)

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

ItemTIBCO Rendezvous Transport Value

JMS Transport Value

Source Table ORDER_TABLE ITEM_TABLE

Publishing Table PUB_ORDER PUB_ITEM

Destination Table SUB_ORDER SUB_ITEM

Exception Table SUB_ORDER_EXCEP SUB_ITEM_EXCEP

Publisher Adapter rvpub jmspub

Subscriber Adapter rvsub jmssub


Create the Database Tables | 17

Create the Database Tables

The first task is to create the database tables.

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

example:

> cd TIB_ADADB_HOME\demo\demo1

2. Execute the demo1_databaseVendor.sql script in the subdirectory to create the tables for

your database. Use your environment-specific user ID, password, and database

service. For example:

> sqlplus userid/password@dbService @demo1_ora.sql

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

TIB_ADADB_HOME\demo\demo1>sqlplus karlh/karlh@ORCL @demo1_ora.sql

SQL*Plus: Release 8.1.7.0.0 - Production on Tue Aug 10 13:10:48 2004

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

Connected to:

Personal Oracle8i Release 8.1.7.0.0 - Production

With the Partitioning option

JServer Release 8.1.7.0.0 - Production

Table created.

Table created.

Table created.

Index created.

Index created.

Index created.

Sequence created.

Trigger created.

Table created.

Table created.

Table created.

Table created.

Index created.

Index created.

Sequence created.

Trigger created.

Table created.

Commit complete.

SQL>



Configure the Properties File

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

1. In the demo1 subdirectory, locate the correct publisher adapter properties file for the

transport type you are using. See Table 3 on page 16.

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

For example:

TIB_ADADB_HOME\demo\demo1>write rvpub.tra#

# Sample ADB properties file

# Optional properties file you can use in place of command line parameters

# Usage: adbagent --propFile propFilename.

.

.

# Change these settings for your login and dsn for Demo1

adb.user karlh

adb.password karlh

adb.dsn Oracle001

.

.

.

Property Value

adb.user username Use the database account name used by the adapter instance.

This is the same username entered during TIBCO

ActiveMatrix Adapter for Database post installation

procedure when creating a database account for the adapter.

adb.password pwd Use the database account password used by the adapter

instance. This is the same password entered during TIBCO

ActiveMatrix Adapter for Database post installation

procedure when creating a database account for the adapter.

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

%%adb.password%% is saved instead.

adb.dsn data source Use the name of the ODBC system data source for the adapter.

The data source is configured as a post installation procedure.

See the TIBCO ActiveMatrix Adapter for Database

Installation for more information.


Configure the Properties File | 19

3. Save and close the publisher adapter file.

4. In the same subdirectory, locate the correct subscriber adapter file for the transport

type you are using.

5. Open the subscriber adapter file and repeat the changes you made in step 2.

6. Save and close the subscriber adapter file.



Start the Adapter Services

You can use TIBCO Rendezvous or TIBCO Enterprise Message Service as the message

transport.

1. If you are using TIBCO Rendezvous transport, skip this step and proceed to step 2.

If you are using JMS transport, open a command window and change directory to the

TIBCO Enterprise Message Service bin directory and start the server. Note that this

step is not required if the server is running as a service on Microsoft Windows. For

example:

cd TIBCO_HOME\ems\bin

> tibemsd

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

example:

> cd TIB_ADADB_HOME\bin

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

database.

If using TIBCO Rendezvous:

> adbagent --propFile

TIB_ADADB_HOME\demo\demo1\rvpub.tra


TIB_ADADB_HOME\demo\demo1\rvsub.tra

If using TIBCO Enterprise Message Service:


TIB_ADADB_HOME\demo\demo1\jmspub.tra


TIB_ADADB_HOME\demo\demo1\jmssub.tra


Change the Table Values and Receive Notification | 21

Change the Table Values and Receive Notification

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

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

example:

> cd TIB_ADADB_HOME\demo\demo1

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

service specified in Create the Database Tables, page 17.

> sqlplus userid/password@dbService

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


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

SQL> commit;


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

SQL> commit;

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

delay, received in the subscriber adapter window.

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


SQL> select * from ORDER_TABLE;

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

ORDER_ID

----------

ORDER_DESCRIPTION

---------------------------------------------------

ORDER_PRICE

-----------

111

Oak Table

499.95


SQL> select * from ITEM_TABLE;

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

ITEM_ID

----------



ITEM_DESCRIPTION

---------------------------------------------------

ITEM_PRICE

-----------

111

Oak Table

499.95

5. Insert additional rows of data, if you wish. If you do, be aware that the first column

(containing the value 111 in the example) is a primary key and must contain a value

that is unique within the table.


Exit the Query Tool and Adapters | 23

Exit the Query Tool and Adapters

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

1. Exit the SQL query tool. For example:

SQL> exit

2. In a command window, use the tibrvsend application to send a message on the terminate

subject to stop each adapter instance:


tibrvsend _ADB.rvpub.TERMINATE now

tibrvsend _ADB.rvsub.TERMINATE now


tibrvsend _ADB.jmspub.TERMINATE now

tibrvsend _ADB.jmssub.TERMINATE now

Note that the tibrvsend program is typically not used to terminate the adapter. Instead, a

JMS program typically sends a JMS message to the JMS termination destination

configured for the adapter.



Clean Up

This cleanup script removes the example tables that were created by the

demo1_cleanup_databasevendor.sql script.

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

> cd TIB_ADADB_HOME\demo\demo1\

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

> sqlplus userid/password@dbService @demo1_cleanup_databasevendor.sql

For example:

> sqlplus karlh/karlh@ORCL @demo1_cleanup_ora.sql


| 25

Chapter 3 Adapter Instance Options

This chapter explains how to create an adapter instance by configuring standard settings.

All configuration tasks are performed in TIBCO Designer and the information is stored in

a project that is later used by the runtime adapter.

Topics


• Adapter Instance Tabs, page 34

• Configuration Tab, page 35

• Design-time Connection Tab, page 37

• Runtime Connection Tab, page 41

• Adapter Services Tab, page 43

• General Tab, page 47

• Logging Tab, page 49

• Startup Tab, page 54

• Monitoring Tab, page 55


26 | Chapter 3 Adapter Instance Options

Overview

The adapter instance tabs in TIBCO Designer allow you to create, design, and run an

adapter. Adding services to an adapter is described in Chapter 4, Adapter Service Options.

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

• Configuration Task Sequence, page 26

• Saving the Project, page 27

• Testing the Adapter, page 27

• Notes on Configuring an Adapter, page 27

• Configuration Recommendations, page 28

• Changing an Existing Configuration, page 29

Configuration Task Sequence

Use the following sequence to create and configure an adapter service.

1. Start TIBCO Designer and open a multi-file project. See the TIBCO Designer

documentation for details.

2. Drag the ActiveDatabase Adapter Configuration icon from the palettes panel to the

design panel. This creates an adapter instance named, by default,

ActiveDatabaseAdapterConfiguration.

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

page 35.

4. Define and test the design-time connection options for the instance. See Design-time

Connection Tab on page 37.

5. Either now or when the instance is ready to deploy, define and test the runtime

connection options for the instance. See Runtime Connection Tab on page 41.

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

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

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

— Logging options: see Logging Tab on page 49

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

— Threads, polling, publishing child data, bulk insert size, TIBCO Rendezvous queue

size, exception table: see Adapter Services Tab on page 43


Overview | 27

7. Add one or more services to the adapter instance by dragging a service icon from the

palettes panel and dropping it in the design panel: see Chapter 4, Adapter Service

Options.

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

This is required.

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

other service options.

10. Save the project as a server repository project.

After configuring the adapter, create the runtime adapter property file and add the project

name and adapter instance name.

Also define and test the runtime connection options for the instance if you did not do it

earlier. See Runtime Connection Tab on page 41.

Saving the Project

Configuration information for an adapter and all other parameter settings related to the

adapter are saved as a project. At any time while configuring the adapter, you can save the

associated project. Each time you save a project, any configuration information you have

entered is saved as a project.

For detailed steps and more information about exporting or importing projects to different

formats (such as .dat), see the TIBCO Designer User’s Guide.

Testing the Adapter

You can use the Adapter Tester to verify that an adapter instance is configured correctly.

The tester is invoked from the TIBCO Designer Tools menu and is documented in TIBCO

Designer Palette Reference.

Notes on Configuring an Adapter

Required and Optional Settings

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

• The Design-time Connection Tab options are required before you can start designing

the adapter and adding services.

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

as needed.

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



• A database account must have been created for running the adapter. For details, see

the TIBCO ActiveMatrix Adapter for Database Installation.

• The database server process, and the repository server process if you are using a

remote repository, must be running to start an adapter instance.

• Each adapter must have configuration information defined in a project using TIBCO

Designer. For instructions, see Chapter 3, Adapter Instance Options.

• Data source connection parameters for an adapter instance can be specified in the

adapter properties file and in TIBCO Designer. Values given in the properties file

override the same values specified in TIBCO Designer.

• An adapter instance name is defined in TIBCO Designer. Names must be

alphanumeric, can contain underscores (_) and hyphens(-), and must be less then 80

characters.

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

same subject.

• Multiple subscribers in different instances can be configured to listen on the same

subject but should not write to the same destination table.

• An adapter instance can be configured as a publisher, subscriber, or both. It can handle

request-response operations if it is configured to do so.

• An adapter instance can publish or subscribe to a maximum of 1024 database columns

per table. The maximum size of each record is restricted by the number of bytes per

row supported by the database server, and the amount of contiguous space in memory

available to build the message.

• If an adapter instance cannot access the database at startup, the adapter will not start.

If the connection fails after startup, you can configure the adapter to attempt automatic

reconnections (see the Runtime Connection Tab on page 41). You can also build a

TIBCO Hawk rule to restart the adapter instance after the database is restarted.

• To start or stop an adapter instance see Start or Stop the Adapter on page 94.

• An adapter instance logs error, warning, debug and information messages to the

console window by default. Some of the output can be directed to a log file that can be

located anywhere on your file system.

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

product.

Configuration Recommendations

The following recommendations and limitations apply when using TIBCO ActiveMatrix

Adapter for Database:


Overview | 29

• The wire format for both the publishing and destination tables must be the same,

otherwise an error will occur.

• Publisher and subscriber information should be defined in the same project for all

cases. When using parent-child tables or the XML wire format, define the publisher

and subscriber in the same repository.

• For the limitations that apply to parameterized subject names and destination names,

see Parameterized Subject and Destination Name Restrictions on page 164.

Changing an Existing Configuration

You can change an existing adapter instance before or after it is deployed, but doing so

may have unintended consequences to the database, the schema, and to other adapter

instances associated with the same schema. When making changes, be aware of the

following:

• It is recommended to back up your project before making major configuration

changes. To back up a project, use TIBCO Designer to export the project. The export

file can be imported into TIBCO Designer, if necessary. For more information, see

TIBCO Designer Palette Reference.

• Legitimate changes to the database as a result of adapter instance changes may not be

immediately successful, for example, if the database was not available at the time the

change was made.

• If you want adapter instance changes to be reflected in the database, make sure the

Deploy On Save checkbox is selected; otherwise, make sure this checkbox is cleared.

This checkbox is on the Configuration tab of the configured adapter resource.

• If you delete an adapter instance or service that is already deployed, the related

database will be cleaned up as soon as you confirm the deletion, and the changes will

be irreversible.

• If you change an adapter instance or service that is already deployed, the related

database will be cleaned up as soon as you re-save the project.

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

• When deleting an adapter service, you have the opportunity to save the service’s

schema. This is important when another adapter instance is also associated with the

same schema.

• If an adapter instance is renamed, the schema associated with that configuration is also

renamed, and if another configuration is associated with that same schema, the

association will become invalid once the schema is renamed.



If legitimate changes to the database result in error messages while you are trying to save

the changes, you may need to run the cleanup script that the adapter creates during the

save operation. For more information about these error messages and using the script, see

Using Database Deployment and Cleanup Scripts on page 194.

Using Global Variables

The variable substitution mechanism can override global variables predefined in the

project in a restricted manner. Predefined variables can be viewed and set in TIBCO

Designer. Variables are specified as %%VARNAME%% and cannot contain any white space.

Variable substitution allows you to accomplish the following.

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

• Locally define the value for a variable for a specific project. The local value takes

precedence over any global value.

• Specify the value for a variable in a properties file. This overrides the project

repository and values set in code, but not variables set on the command line.

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

Variables can be used anywhere in the configuration and will be replaced by the

locally-defined adapter instance.

Variable Specification

The adapter can specify variables:

• In the project during configuration using TIBCO Designer.

• In a properties file.

• In TIBCO Administrator Enterprise Edition when deploying the project.

The values in the properties file or Enterprise Edition take precedence over the values set

in the project through TIBCO Designer.

Specifying Variables Using TIBCO Designer

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

For example, you could assign the value 7474 to the predefined global variable RvDaemon.

You can then use the variable in different sessions in your adapter. If you wish to change

the TIBCO Rendezvous daemon for your adapter, you can globally set it to a different

value or override it from the command line.


Overview | 31

To Specify Global Variables:

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

The project panel displays all currently defined global variables. You have these

choices for modifying global variables:

— To assign or change a variable value, triple-click the variable. The variable expands

so you can change either the variable name or the variable value. Press Enter when

done.

— To add a new global variable group, click the group icon (on the left below the

project panel). Specify the name of the group, then press Enter.

— To add a global variable to the list, click the abc icon below the project panel. A new

global variable item is added to the bottom of the list. Type the variable name and,

optionally, the value. Press Enter when done.

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

icon below the project panel.

— Click the pencil icon to open the advanced editor where you can add more

information to a global variable.

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

2. When you want to use the global variable in the fields of a resource, enter the variable

name surrounded by %% on both sides.

When the project is deployed and the configured components are run, all occurrences

of the global variable name are replaced with the global variable value (unless it was



overridden in a way that had higher precedence). For example, RvServiceTest would be

replaced with 7800.

A number of global variables are predefined. See Predefined Global Variables in the next

section for information. You may add definitions of any variables you need to the

predefined variables.

Predefined Global Variables

The following table lists and explains the predefined global variables. Some global

variables are automatically used within the system when an adapter instance is configured.

Table 4 Predefined Global Variables (Sheet 1 of 2)

Variable Description

Deployment Defaults to the TIBCO Designer project name. This value can be

any string value. This global variable is used by the system to

partially define the subject name defined for a service.

DirLedger Specifies the path name of the TIBCO Rendezvous certified

messaging ledger file. The default is the root installation directory.

DirTrace Specifies the path name for log file used by the adapter. The default

is the root installation directory.

Domain The default value for file-based local projects is Domain. The value

for server-based projects is the domain to which the project was

saved.

JmsProviderUrl Tells applications where the JMS daemon is located. Setting this

value mostly makes sense in early stages of a project, when only

one JMS daemon is used.

JmsSslProviderUrl Tells applications where the JMS SSL daemon is located.

RemoteRvDaemon TIBCO Rendezvous routing daemon (rvrd) to be used. See TIBCO

Administrator Server Configuration Guide for details about setting

up a domain using rvrd.

RvDaemon TIBCO Rendezvous daemon. Sessions use this daemon to establish

communication. The default value is 7500.

RvNetwork TIBCO Rendezvous network. This variable need only be set on

computers with more than one network interface. If specified, the

TIBCO Rendezvous daemon uses that network for all outbound

messages.

In most cases, you can leave the default.


Overview | 33

RvService TIBCO Rendezvous service. The TIBCO Rendezvous daemon

divides the network into logical partitions. Each transport

communicates on a single service. A transport can communicate

only on the same service with other transports.

Unless you are using a non-default TIBCO Rendezvous

configuration, you should leave the default (7500).

RvaHost Computer on which the TIBCO Rendezvous agent runs. This

variable is only relevant if you are using the TIBCO Rendezvous

Agent (rva) instead of the TIBCO Rendezvous daemon, and if you

have configured a non-default setup. See TIBCO Rendezvous

Administration for details about specifying the rva parameters.

RvaPort TCP port where the TIBCO Rendezvous agent (rva) listens for

client connection requests. See TIBCO Rendezvous Administration

for details about specifying the rva parameters. Defaults to 7501.

TIBHawkDaemon TIBCO Rendezvous daemon used in the TIBCO Hawk session.

Specifies which Hawk daemon handles communication for the

session. A local daemon is specified by the communications type

(always tcp) and a socket number. The default configuration uses the

local daemon with the TCP socket number 7474.

Specify a remote daemon by inserting its host name or IP address

between the tcp entry and the port number of the daemon parameter,

such as tcp:remote_computer:7800.

See the TIBCO Hawk Installation and Configuration manual for

details about this parameter.

TIBHawkNetwork TIBCO Rendezvous network used by the TIBCO Hawk session.

Specifies which network to use for outbound session

communications when a computer is connected to more than one

network, and also specifies the multicast groups to use for

communication.



TIBHawkService TIBCO Rendezvous service used by the TIBCO Hawk session. The

Service parameter specifies which User Datagram Protocol (UDP)

service group the TIBCO Rendezvous daemon should use for

session communications. The default service port is 7474.



Table 4 Predefined Global Variables (Sheet 2 of 2)

Variable Description



Adapter Instance Tabs

The following tabs are available when configuring an adapter instance.

• Configuration Tab

• Design-time Connection Tab

• Runtime Connection Tab

• Adapter Services Tab

• General Tab

• Logging Tab

• Startup Tab

• Monitoring Tab


Configuration Tab | 35

Configuration Tab

You must define the options on the Configuration tab before other options can be

configured. Click Apply to apply the changes before leaving the Configuration tab. Table

5, Adapter Instance Configuration, on page 35.

Table 5 Adapter Instance Configuration

Field Description

Instance Name This is the name that was specified when creating the adapter configuration.

See Guidelines for Choosing an Instance Name on page 36 for more information.

Description A short description of the adapter configuration.

Version The version string indicates the TIBCO ActiveEnterprise (AE) configuration

format in which the adapter instance is saved. An adapter instance can be saved

in AE 4.0, AE 5.0 or AE fro1 format.

When a new adapter instance is created in TIBCO Designer 5.x, the version

string is set to AE Version 5.1. When a 4.x adapter instance is opened in Designer

5.x, the Version field is set to AE Version 4.0.

• If a 4.x adapter instance is to be run with a 4.x runtime adapter, the instance

must be saved with the Version field set to AE Version 4.0.

• If you are using TIBCO Designer 5.x to modify 4.x adapter instances,

change only features supported by the 4.x. runtime adapter and use the

validation utility to verify the instance before deploying the project. Invoke

the utility by selecting Project > Validate Project For Deployment in

Designer.

To change versions, click the Change Version button.

Message Filter Specify a message filter, if you have configured a message filter resource for use with

the adapter. The plugin allows you to manipulate incoming and outgoing data before

sending it on the network or handing it to the target application. Plugins can be written

using the TIBCO Adapter SDK. See the TIBCO Adapter SDK Programmer’s Guide for

information about writing a message filter.

Show All Tabs Select this box to display additional tabs for configuring advanced options.

Vendor Select the database vendor to which the adapter connects. This populates the JDBC

Driver and JDBC URL fields in the Design-time Connection Tab with the appropriate

dat.

In the drop-down list, vendor names enclosed in parenthesis are not supported.

For example Informix and INGRES.



Guidelines for Choosing an Instance Name

• An instance name must use alphanumeric characters. An underscore (_) character can

be used. The entire instance name must be less than 80 characters. The space character

cannot be used in an instance name.

• An instance name cannot use global variables.

• An instance name must be unique with respect to other adapter instances for the same

adapter in the project. The same instance name can be used to name an adapter

instance for a different adapter in the same project. For example, an ADB adapter

instance named TEST and a Siebel adapter instance named TEST can coexist in the same

project.

• Each instance name must be unique per adapter within a project even if each instance

is defined in a different folder. That is, configuring same-named adapter instances in

different folders will not make their names unique.

When you create an adapter instance, the palette automatically creates several resources

for it. The names of these resources derive from the name of the instance they belong to.

Changing the adapter instance name results in an automatic regeneration of the resources

names. If you manually modify any resource name, that particular name will not be

automatically regenerated next time your rename the adapter instance.

DB2 AS400 Library (Appears when DB2 AS400 is selected in the Vendor field.) When this option is

selected, the adapter automatically creates an asynchronous queue named

TIBADB on the AS400 machine. Your programs will be created in TIBCOSRC in

the library specified in the DB2 AS400 Library field.

You must also set the trigger option under the publication service DB2/AS400

Options tab.

Convert Number Data Type

to String(Appears when Oracle is selected in the Vendor field.) When this option is

selected, the adapter will use string operation for number data type at runtime.

Write to Database on Save Select this box if you want to write configuration settings to the database when

this project is saved. This is the default mode.

Table 5 Adapter Instance Configuration (Cont’d)

Field Description


Design-time Connection Tab | 37

Design-time Connection Tab

You must define the JDBC information and database account options in the Design-time

Connection tab before you can design the adapter instance.

After completing these fields, click the Apply button, then click the Test Connection

button to establish a connection to the database. When the connection is successful message

appears, click the OK button. You can now begin design-time configuration of the adapter.

Many of the following fields can use global variables. Click the Global Variables tab in

the project panel to add or modify a global variable.

Table 6 Design-time Configuration Parameters

Field Description

JDBC Driver The name and URL of the JDBC driver used during design-time configuration. The

following table lists all the supported JDBC drivers and their URLs. For detailed

parameter descriptions, see your JDBC driver documentation.

See Table 7, JDBC Drivers and URLs, on page 38 for the supported JDBC Drivers and

the associated URLs

JDBC URL

User Name The database user that the design-time adapter uses to connect to the database.

Password The password for the database user.

Remember Password The next time you open this project, the Password field displays the masked password

and the adapter will connect to the database without the user needing to know or enter

the password.

If this field is not checked, the password must be entered here each time the project is

opened. The password is saved in the project file as the global variable

%%adb.password%%.

Use Design-time Connection

For Runtime

This field is not used.

Test Connection Click this button to test the connection using the specified parameters.

Instead of manually entering the following driver and URL values, you can populate these

fields using a connection template or previously-stored connection parameters. For more

information, see Using Connection Settings Templates on page 39.



Table 7 JDBC Drivers and URLs

Database Driver and URL

Oracle JDBC Driver: tibcosoftwareinc.jdbc.oracle.OracleDriver

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

Microsoft SQL

Server

JDBC Driver: tibcosoftwareinc.jdbc.sqlserver.

SQLServerDriver

JDBC URL: jdbc:tibcosoftwareinc:sqlserver://

server_name:1433;databaseName=database_name

Note: Default port number is 1433.

Sybase JDBC Driver: tibcosoftwareinc.jdbc.sybase.SybaseDriver

JDBC URL: jdbc:tibcosoftwareinc:sybase://server_name:

5000

Note: Specify a database_name parameter (as shown in the SQL Server

description above) if connecting to a database that is not the default database.

Sybase

Adaptive

Server

Anywhere

JDBC Driver:com.sybase.jdbc2.jdbc.SybDriver

JDBC URL: jdbc:sybase:Tds:localhost:2638/asademo

MySQL JDBC Driver: com.mysql.jdbc.Driver

JDBC URL: jdbc:mysql://server_name:3306/database_name

Teradata JDBC Driver: com.teradata.jdbc.TeraDriver

JDBC URL: jdbc:teradata://server_name

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

JDBC URL: jdbc:tibcosoftwareinc:db2://server_name:port;

locationName=DB2_location_name;packageName=package_name_prefix

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

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

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

JDBC URL: jdbc:tibcosoftwareinc:db2://server_name:

50000;databaseName=database_name;packageName=DEF00


Design-time Connection Tab | 39

Using Connection Settings Templates

TIBCO ActiveMatrix Adapter for Database provides connection settings templates with

JDBC driver information for each supported database vendor. The templates populate the

JDBC Driver and JDBC URL fields with the default settings as shown above. You then

replace the variables with values appropriate for your configuration.

To populate the fields with default values, select ActiveDatabase > Connection

templates, then select your database type from the submenu. The following screen sample

shows Oracle being selected.

Saving Connection Settings for Reuse

After you have customized the connection settings on this tab for your configuration, you

can save them for use in another adapter. You can save as many sets of customized

connection parameters as you need. The parameter sets can include the user name and

password.

To save a set of connection parameters:

1. Fill in the connection parameters for the adapter.

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



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

4. Click either Yes or No button:

— Yes saves the password in the parameter set. (If the Password field is empty, no

password is saved.) When the user selects the parameter set, the Password field will

be populated with the current password in clear text, even if the password is not

saved in the project file or if it has been obfuscated in the project file.

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

enter it manually.

The connection parameters are saved.

Using Saved Connection Parameters

To use a saved set of connection parameters, select ActiveDatabase > User connections,

then select a parameter set from the submenu.

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

parameter set.


Runtime Connection Tab | 41

Runtime Connection Tab

The settings available in the Runtime Connection tab must be configured before you start

the runtime adapter.

After configuring these settings, click the Apply button, then click the Test Connection

button to establish a connection to the database. When the connection is successful message

appears, click the OK button. The runtime adapter is now configured.

Table 8 Runtime Connection Tab

Field Description

ODBC DSN The name of an ODBC system data source for the database where the source or

destination database table resides. The adapter uses this data source to send and receive

information. If not specified, the data source name must be given in the adapter’s

properties file or on the command line.

User Name This is the database user that the runtime adapter uses to connect to the database. This

field is automatically populated when you select a template as described in Using

Connection Settings Templates on page 39. It cannot be changed here.

Password This is the password for the database user. This field is automatically populated when

you select a template as described in Using Connection Settings Templates on page 39.

It cannot be changed here.

Default Schema This is the schema name of the current user. Usually it is the same as the username, but

can be different, for example, when using Microsoft SQL Server. For Teradata database,

the Default Schema must be the name of the database you want to connect to.

Database Disconnection

Codes

Specify the database disconnection codes provided by your database. Multiple codes can

be entered if each is separated by a semi-colon (;). No spaces are allowed between codes.

To populate this field with the default disconnection codes for your database, click

ActiveDatabase > Connection Templates > database_name.

If disconnection codes are not provided and a database operation fails, the adapter issues

a test query to verify whether the database connection is valid. If the connection is not

valid, the adapter attempts to reconnect and will shutdown if it cannot reconnect. This

approach is database independent, but affects performance because the adapter has to

send the query and wait for results.

If database disconnection codes are provided in this field, they are stored in a fatal error

code dictionary. When a database operation fails, most database systems return an error

code to the adapter. The adapter can look up the returned error code in the fatal error

code dictionary and determine if the database connection is lost and respond

accordingly. This is more efficient then sending the test query.

When using ODBC native driver to reconnect on DB2/UDB, add the database

disconnection code -30081 manually. For Oracle database, the disconnection code is

30046.



Maximum Number of

Reconnect Attempts

The total number of reconnection attempts to make after the service has been suspended.

When this number is reached, the runtime adapter or adapter service will be stopped.

A value of -1 means reconnection attempts will continue indefinitely.

Number of Reconnect

Attempts Before Suspending

Impacted Service(s)

Specify the number of reconnection attempts to make before suspending the service.

This value is 1 and cannot be changed.

Interval between Reconnect

Attempts (milliseconds)

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

Adapter Termination Criteria

(after max number of

reconnect attempts)

The adapter and all of its services is stopped if any one of its services has been unable to

re-establish connection after the Maximum Number of Reconnect Attempts has been

made. This option cannot be changed.

Test Connection This option is not used.

Table 8 Runtime Connection Tab (Cont’d)

Field Description


Adapter Services Tab | 43

Adapter Services Tab

You are not required to change any settings in the Adapter Services tab. The settings

available in this tab affect all publishers, subscribers, and request-response services

defined for the adapter, unless overridden by the individual service configurations as

described in Chapter 4, Adapter Service Options.

Click the Apply button to apply the changes before leaving this tab.

All Publication Services

The settings available in the All Publication Services panel apply to all Publication

services in the adapter.

Table 9 Publication Service Configuration Options

Field Description

Number of Publication

Service Threads

This field is currently disabled. Threads are allocated on demand. For example, if the

adapter instance has only a publication service configured, a publication thread and

database connection will be created automatically.

Use Polling Batch Size Check this box to activate Polling Batch Size (Maximum Rows). If Polling Batch Size is

not active, the adapter picks up all new rows and then tries to send all of them before

returning to the event loop. This could affect adapter performance in a high volume

environment.

Polling Interval Type a specific polling interval in milliseconds. This is how often an adapter with a

publication service checks the publishing table for new rows. The default is 5000, or

once every five seconds. Note that if you specify a polling interval of 0, it is assumed

that you are using an alerter to manage polling.

Polling Batch Size

(Maximum Rows)

(Only active when Use Polling Batch Size is checked) The maximum number of

messages that are picked up per polling interval. The adapter returns to the event loop

when it is finished sending those messages. Using this option helps process TIBCO

Rendezvous events in an efficient manner. For example, when polling a large number of

rows, the adapter works best if a fixed number of rows is specified in this field.

Batch Publish Status Updates (Only active when Use Polling Batch Size is checked. Do not use this option when

messages are published using a parameterized subject name.)

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

to the publishing table.

If an adapter stops before a batch update is performed, the status column is not updated.

As a result, duplicate messages may be published when the adapter is restarted.



Publisher Batch Confirm Size (Applies only to adapters with a publication service that uses certified message delivery.

Do not use this option when messages are published using a parameterized subject

name.)

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

Entering a value in this field optimizes performance. However, if an adapter stops before

a batch update is performed, the status column is not updated. As a result, messages that

were successfully published might still have a status of P (pending) in the publishing

table when the adapter is restarted. In this case, the ledger file contains the correct status

information. Smaller values in this field decrease this risk.

Publisher Batch Confirm

Timeout

(Applies only to publisher adapters with publications that use certified message delivery.

Do not use this option when messages are published using a parameterized subject

name.)

The number of milliseconds to wait before updating the status column. After this

interval, an update is performed even if the batch size value is not reached. The default

value is 10000 (10 seconds). A value of 0 means that no timeout interval is used.

If an adapter instance stops before a batch update is performed, the status column is not

updated. As a result, messages that were successfully published might still have a status

of P (pending) in the publishing table when the adapter is restarted. In this case, the

ledger file contains the correct status information. Smaller interval values decrease this

risk.

Publish Child Data This is selected by default. When selected, the parent row and all related child rows is

published when a parent row is updated. Upon receipt of such a message, a subscriber

adapter updates the parent row and then updates all the child rows with the data that was

received in the message.

Any changes to the child tables without a change in the parent table will not be

processed. The adapter monitors only the parent table for publishing.

The adapter updates the child rows by deleting all the related child rows, then inserting

child rows again based on the data in the received message. For information on adding

related tables for a publisher adapter, see Adding Child Tables on page 65. For

information on adding related tables for a subscriber adapter, see Child Table Mappings

Tab on page 80.

Polling Commit for DB2 Select to enable the adapter publisher to do a commit after selecting query for DB2.

Table 9 Publication Service Configuration Options (Cont’d)

Field Description


Adapter Services Tab | 45

All Subscription Services

The settings available in the All Subscription Services panel apply to all subscription

services in the adapter.

Considerations when using the Subscriber Bulk Insert Size parameter:

Note the following considerations:

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

turned off.

• If an update statement is published while messages are being batched, the bulk insert

is performed regardless of whether the size value has been reached. After records have

been inserted, the update operation is performed.

Table 10 Subscription Service Configuration Options

Field Description

Number of Subscription

Service Threads

This field is currently disabled. Threads are allocated on demand. For example, if the

adapter instance has only a subscription service configured, a subscription thread and

database connection will be created automatically.

Subscriber Batch Commit

Size

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

is 0.

Subscriber Batch Commit option is not supported with RVCMQ Quality of Service. The

RVCMQ scheduler requires a message to be confirmed before dispatching the next

message, which prevents the adapter from operating in batch mode.

Subscriber Batch Commit

Timeout (milliseconds)

Specify an interval (in milliseconds) that can expire before confirmation messages

regarding successful insertion into the exception table are sent back to the publisher. The

default is 1.

The batch commit feature does not commit all received messages if the adapter instance

terminates before the batch commit value or time-out value is met.

When using RVCMQ, subscriber batch commit will timeout after each operation

(insert/update/delete) when batch commit size>1.

Subscriber Bulk Insert Size All incoming messages to insert are stored until this size is reached. Then, a bulk insert

operation is performed on the destination table. This number must be less than or equal

to the value in Subscriber Batch Commit Size. The default value is 1.

Rendezvous Maximum

Queue Size

Maximum number of messages to allow in the TIBCO Rendezvous event queue. The

default value is 0, which means no limit is placed on event queue size. Use this option to

prevent a subscriber’s memory from overflowing if the publisher is too fast.

Use Exception Table Select this box to use an exception table. The exception table is defined when you create

a subscription service.



• Do not use this option if LONG, LONG RAW, image, or variable-length BINARY

type records are published. These records cannot be bulk inserted into a destination

table.

All Request-response Services

The settings available in the All Request-response Services panel apply to all

request-response services in the adapter, unless the individual service is configured

differently.

Table 11 Request-response Service Configuration Options

Field Description

Number of Request-Response

Service Threads

Indicate the number of database request-response threads to use. Valid values are from 1

through n. Each thread has a separate connection to the database. Specifying multiple

threads allows you to load balance incoming RPC requests.

Request Response max Rows Specify the maximum number of rows to fetch. This can be used limit the memory usage

of the adapter. The unfetched rows will be ignored by the adapter.


General Tab | 47

General Tab

The General tab allows you to set a termination subject or topic and specify the encoding

type, debug level, and verbose mode. Note that the adapter should communicate only with

other applications that support the same code pages or Unicode.

Click the Apply button to apply the changes before leaving the General tab.

Table 12 General Configuration Options

Field Description

Termination Subject or Topic A message sent on this subject (if TIBCO Rendezvous is the transport) or topic (if JMS

is the transport) stops the adapter.

The default termination subject or topic for a project is:

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

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

_ADB.%%InstanceId%%.TERMINATE

See TIBCO Rendezvous Concepts for information about specifying subject names. See

the TIBCO Enterprise Message Service User’s Guide for information about publishing

on a topic.

JMS Destination Prefix Specify this prefix if you are using the JMS transport and have selected the Use Separate

Service Thread option for a subscription service. The destination prefix is the subject used

by the single-threaded subscription service.

By default, the adapter uses a dynamic destination that is generated using the Domain

and Deployment global variables, and the adapter instance name. If you use this default

dynamic destination, make sure the values for Domain and Deployment are not empty.

You can override the default dynamic destination by specifying the static destination in

this field. The static destination must be defined with write permissions on the TIBCO

Enterprise Message Service server before it can be used by the runtime adapter.

Adapter Encoding Select the encoding from the drop down menu. The adapter may support other encodings

not shown. See Chapter 10, Setting Encoding Options, for a list of additional encodings

that can be typed into this field.

The palette does not validate encoding values that you type into the field. The runtime

adapter will throw an error if the encoding value you type is not supported.



Debug Level This field is valid only when the Debug logging option is selected, as described in

Logging Tab on page 49.

Select how much debugging output to provide at the console window or log file location

specified in the Log File field. The options are:

No debug information

Only SQL commands executed with the database

Only the ODBC data source for each SQL command

All debug information

Generate Verbose Output This field is valid only when the Information logging option is selected, as described in

Logging Tab on page 49.

Check this box to include verbose output (all available information) at the console

window or log file location specified in the Log File field.

Generate Payload on Error Allows the adapter to log the payload information under Error role when an error occurs.

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

Alerter Name The name of the alerter service register in the database.

Table 12 General Configuration Options (Cont’d)

Field Description


Logging Tab | 49

Logging Tab

Use the settings available in the Logging tab to configure a log file or log sinks, including

which types of trace messages you want logged and where they are sent. Click the Apply

button to apply the changes before leaving the Logging tab.

By default all error, warning, debug and information messages are printed in the console

window in which the adapter was started. Alternatively, you can specify a log file and path

to redirect trace output to a log file located anywhere on your file system. The default log

file name is %%DirTrace%%/%%Deployment%%.%%InstanceId%%.log, and is saved in the same

directory where your project (repository instance) is stored.

Most errors received by the adapter are logged. The only errors that might not be logged

are any TIBCO Rendezvous or TIBCO Adapter SDK errors that appear at startup time

before tracing can be initialized.

Table 13 Logging Configuration Options

Field Description

Use Advanced Logging When this box is clear, the standard log file is used. This is the default. Fill out the

remaining fields on this tab. You do not need to read the rest of this field description.

When this box is selected, you can set two standard output destinations (sinks) for trace

messages and set the tracing level for the roles selected. The following sink types are

available:

• File

• STDIO

• Hawk

• Network

See Creating Log Sinks on page 51 for more information.

Log to Standard I/O When selected, trace messages are displayed in the command prompt window where the

adapter is started. This is the same as creating a STDIO sink. When not selected, trace

messages do not display in the window.

Log File Specify the name of the log file to which trace messages are written. This is the same as

creating a file sink. Global variables can be used to specify the location of the log file.

See Using Global Variables on page 30 for more information.

Type the name and file system path, or click the Browse button and select an existing

log file. If no file name is specified, trace information is not written to a file.

Log Info/ Debug/ Warning/

Error Messages

Select the types of trace messages you want logged.



Logging trace messages is helpful for troubleshooting. There are four levels of trace

messages that you can log: Information, Warning, Debug, and Error. Trace messages are

described and listed in Appendix B, Trace Messages

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

needed.

Debug messages should not be logged unless requested by the TIBCO Product Support

Group. This option writes a lot of information to the log file and significantly reduces the

speed of the adapter.

By default, the Use Advanced Logging checkbox is not checked. In this mode, you

configure a standard log file using the fields on this tab, as shown in the example below.


Logging Tab | 51

When you check the Use Advanced Logging checkbox, you configure log sinks using

icons in the TIBCO Designer project panel. This gives you complete control on selecting

the destinations and associating desired roles with each of the destinations.

Creating Log Sinks

1. Check the Use Advanced Logging checkbox.

2. Click the Apply button.



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

Advanced folder.

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

— Select either the fileSink or stdioSink icon.

— Create a new log sink by dragging and dropping the Generic log sink icon from the

palette panel into the design panel, then assign a type to it from the drop down

menu in the configuration panel. Click the Apply button.

5. With the desired log sink icon selected in the design panel, fill in the fields in the

configuration panel. You can also change the name and enter a description for each

sink by right-clicking on the sink icon in the project panel.

— File sink logs the trace messages to a file. Specify the file limit, file count, and the

option to append or overwrite. By default, the file limit is 30000 bytes, the file

count is 3, and the mode is append.

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

— Hawk sink sends each trace message to TIBCO Hawk Monitor or TIBCO Hawk

Display using the Hawk session, which is created by the adapter for monitoring


Logging Tab | 53

purposes. Specify the MicroAgent Name. (For details on Hawk sessions, see Using

Global Variables on page 30.)

— Network sink publishes each trace message on TIBCO Rendezvous. Specify the

session and the subject on which the trace messages needs to be published.



Startup Tab

Do not change the settings in the Startup tab. This tab displays the default startup

behavior.

Table 14 Startup Options

Field Description

Show Startup Banner The startup banner displays the runtime adapter version, the infrastructure version on

which the adapter is built, and copyright information in the console window when the

adapter is started.

Metadata Search URL This field is predefined and cannot be changed. It specifies the location where the

adapter searches for base schemas. All schemas that have been defined and saved at this

location are loaded at startup.


Monitoring Tab | 55

Monitoring Tab

The settings available in the Monitoring tab do not need to be configured unless TIBCO

Hawk is installed.

You can use microagents to supplement the monitoring information provided by the

standard logging capability. Examples of supplemental information that you can obtain

with microagents include the repository URL and the command line arguments used to

start the adapter.

Click the Apply button to apply the changes before leaving the Monitoring tab.

See Chapter 11, Monitoring the Adapter, on page 233 for a list of all supported

microagents.

Many of the following fields can use global variables. Click the Global Variables tab in

the project panel to add or modify a global variable.

Table 15 Monitoring Configuration Options

Field Description

Enable Standard Microagent Allows you to turn on or off the standard TIBCO Hawk Microagent. Clicking the globe

icon changes the checkbox to a text field, allowing you to specify a global variable.

When this is a text field, turn the microagent on and off by entering true or false.

Standard Microagent Name This is the name for the standard microagent that will be registered with the TIBCO

Hawk system. In most cases the default value is used,

COM.TIBCO.ADAPTER.adb.%%deployment%%.%%InstanceId%%.

The value for the %%deployment%% global variable can be set or modified by selecting the

session icon and then clicking the Global Variables tab in the project panel.

The %%InstanceId%% variable does not need to be set because it is automatically set at run

time by the runtime adapter.

Standard Microagent Timeout Specifies the amount of time the Hawk Agent should wait for HMA method invocations

to complete before timing them out. The default is 10000 milliseconds. Normally there is

no need to change this value, however, on machines under extreme stress where method

invocations are timing out, this new option allows the timeout value to be increased.

Enable Class Microagent Allows you to turn on or off the instance-specific or class-specific standard TIBCO

Hawk Microagent. You can configure how the class microagent is turned on and off in

this field: clicking the globe icon changes the checkbox to a a true/false text field.

Class Microagent Name This is the name for the class microagent that will be registered with the TIBCO Hawk

system. In most cases the default value is used,

COM.TIBCO.adb.%%deployment%%.%%InstanceId%%.



Class Microagent Timeout Specifies the amount of time the Hawk Agent should wait for HMA method invocations

to complete before timing them out. The default is 10000 milliseconds. Normally there is

no need to change this value, however, on machines under extreme stress where method

invocations are timing out, this new option allows the timeout value to be increased.

Default Microagent Session This field is predefined and cannot be changed. The session is automatically generated

by TIBCO Designer and will be used by the standard, class, and custom microagents.

Table 15 Monitoring Configuration Options (Cont’d)

Field Description


| 57

Chapter 4 Adapter Service Options

After configuring an adapter instance, select one or more adapter services for the instance.

All configuration tasks are performed in TIBCO Designer.

Topics


• Adding Child Tables, page 65

• Publication Service Tabs, page 61

• Subscription Service Tabs, page 77

• Request-response Service Tabs, page 85


58 | Chapter 4 Adapter Service Options

Overview

The transport type (Rendezvous or JMS) you select for the runtime adapter determines

which quality of service, delivery mode, and wire format the service can use. Only options

that are compatible with a service’s transport type will be available for selection.

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

Quality of Service

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

Possible values are:

• Reliable

(TIBCO Rendezvous transport type only) Reliable message delivery. Ensures that

each multicast or broadcast message is received as long as the physical network and

packet recipients are working, and that the loss of a message is detected. This choice

can compensate for brief network failures because it can retransmit a message on

request if the first attempt failed. This choice is appropriate when message delivery is

expected but some loss can be tolerated. Messages are received without explicit

confirmation.

• Certified

(TIBCO Rendezvous transport type only) Certified message delivery. Offers stronger

assurances of message receipt, along with tighter control, greater flexibility and

fine-grained reporting. Guarantees that every certified message reaches its intended

recipient in the order sent. The message can be sent across network boundaries, and if

a network fails, delivery attempts continue until delivery succeeds or until the

message's time limit expires.

If certified message delivery is used, data is stored in a ledger file. The size of the

ledger depends on several factors, the most important of which is the retention rate of

stored data. That is, the ledger grows fastest in response to the cumulative length of

undeliverable messages. You must ensure that sufficient disk space is available for the

expected size of the ledger.

• Distributed Queue

(TIBCO Rendezvous transport type only) A distributed queue is a group of

cooperating transport objects, each in a separate process. To obtain load balancing

among servers, the adapter uses distributed queues for one-of-n delivery of messages

to a group of servers. Each member of a distributed queue listens for the same subject

using the TIBCO Rendezvous Distributed Queue listener objects. Even though many


Overview | 59

members listen for each inbound message (or task), only one member processes the

message. For details on distributed queues, see TIBCO Rendezvous Concepts.

See Load Balancing Across Adapter Instances on page 134 and TIBCO

ActiveEnterprise Concepts for more information.

• Transactional

This option is no longer supported. The option is only included for backward

compatibility.

Delivery Mode

(JMS transport type only) The method of delivery for a JMS message. The semantics for

these fields are somewhat more complex than the explanation given here. See TIBCO

Enterprise Message Service User’s Guide for more information.

• Persistent

In general, a message marked persistent will be available to a JMS client even if the

TIBCO Enterprise Message Service server goes down. Persistent messages are held in

secondary storage in the server and have guaranteed delivery when sent to a topic that

has durable subscribers. (If a topic has no durable subscribers, there are no subscribers

that need messages resent in the event of a server failure and therefore messages do

not need to be saved.) Performance is improved because disk I/O is not required.

• Non-Persistent

A message marked non persistent will not be available to a JMS client if the TIBCO

Enterprise Message Service server goes down. These messages are never written to

persistent storage.

• Durable

(Topic only) Specify the subscriber as durable subscriber of the topic. Messages for

durable subscriptions are stored on the server as long as durable subscribers exist for

the topic.

• Non-Durable

(Topic only) Specify the subscriber as non-durable subscriber of a topic. Non-durable

subscribers only receive messages when they are active. If messages arrive on the

topic when the subscriber is not available, the subscriber does not receive those

messages.

Wire Formats

Services must use the same wire format to exchange data.

• Rendezvous Message (TIBCO Rendezvous transport type only)



A self-describing wire format used by TIBCO Rendezvous applications. Control

information for validation is not sent in the message. If you use this format, the

adapter is compatible with adapters not developed with TIBCO Adapter SDK.

• XML Message (TIBCO Rendezvous and JMS transport types)

The XML Message wire format conforms to specifically constructed and fully compliant

XML Schema (XSD) based on the existing definition of the TIBCO ActiveEnterprise

schema.

• ActiveEnterprise Message (TIBCO Rendezvous transport type only)

An externally-described XML wire format supported by the TIBCO Adapter SDK.

Control information for validation is sent in the message. If no control information is

included, an exception is returned to the subscriber. TIBCO ActiveEnterprise standard

wire format provides class information and packing rules for the TIBCO Adapter

SDK set of data types. This format allows TIBCO ActiveEnterprise components to

perform extra validation on messages sent or received.

See TIBCO Adapter SDK Programmer’s Guide for details about the control

information generated and sent with TIBCO ActiveEnterprise messages.


Publication Service Tabs | 61

Publication Service Tabs

When running as a publisher, the adapter extracts data from the changed rows from

database tables and publishes them on appropriate subject names.

You can configure parameters under the following tabs:

• Configuration Tab on page 61

• Tables Tab on page 62

• Child Table Order By Tab on page 70

• DB2/OS390 Tab on page 68

• DB2/AS400 Tab on page 69

• Publisher Options Tab on page 72

• Advanced Tab on page 75

Configuration Tab

The wire format for the publication and subscription services must be the same, otherwise

an error will occur.

Table 16 Publication Service: Configuration Tab

Field Description

Name You can use the default name or replace it with a name of your choice.

Transport Type Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime adapter. This

selection determines which options appear in the rest of the Configuration tab.

The transport can be configured to use a trusted store and identity resource for use in SSL (Secure

Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL

configuration field which uses a dialog to perform SSL configuration.

To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the

Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL

configuration options are explained in the online help associated with the session dialog. Click the

question mark to display the online help.

Quality of Service (Only available when TIBCO Rendezvous is selected as the transport type) Select the level of

service that determines how messages are sent. See Quality of Service on page 58 for a description

of these options.

• Reliable

• Certified



Note the following restrictions:

• A service name must use alphanumeric characters. An underscore (_) character can be

used. The entire instance name must be less than 80 characters. The space character

cannot be used in an instance name.

• A service name cannot use global variables.

Tables Tab

You must set publisher table options before configuring other publisher options.

Wire Format The wire format in which data will be sent. Note that the wire format for both the publisher and

subscriber must be the same, otherwise an error will occur. See Wire Formats on page 59 for a

description of these formats.

• ActiveEnterprise Message (TIBCO Rendezvous transport type only)

• Rendezvous Message (TIBCO Rendezvous transport type only)

• XML Message

Connection

Factory Type

(Only available when JMS is selected as the transport type) Connection Factory objects create JMS

connections for sending and receiving messages. Available choices are:

• Topic

Publish-subscribe messaging. A message published to a topic is broadcast to one or more

subscribers. All messages published to the topic are received by all services that have subscribed to

the topic.

• Queue

Point-to-point messaging. A message sent to a queue is consumed by one and only one receiver.

Each message has only one receiver though multiple receivers may connect to the queue. The first

receiver to access the queue gets the message. The other receivers do not.

Delivery Mode (Only available when JMS is selected as the transport type) The delivery mode for each message

sending operation. See Delivery Mode on page 59 for a description of each mode.

• Persistent

• Non-persistent

Table 16 Publication Service: Configuration Tab (Cont’d)

Field Description



Source table names can be qualified with a database user name. To access tables in other

schemas, the database user specified in the Design-time Connection Tab on page 37 tab

must have the proper set of permissions granted. This is described in Referencing an

External Schema on page 64.

Icons

• Add Table — Click to display a dialog box that list tables available to the

database user specified in the adapter Connection tab. Select the source table to

publish from when data is inserted into it.

• Add Child Table — Displays a dialog box from which a secondary table can be

added to the configuration.

• Add Table from Other Schema — Allows you to add a table from a different

schema than the current database user schema. For instructions on granting access

privileges to an external schema, see Referencing an External Schema on page 64.

You can use this icon to add different schema at the parent and child levels.

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

• Re-find Tables from Database — Causes TIBCO Designer to refresh stored table

schema information by retrieving new information from the database.

If a primary key is not defined for a table, the update and delete triggers will not be

generated for the table. To define a primary key for the table, select the User Key column

in a table row. The update and delete triggers will then be defined.



• Load Table Schema from Database — Allows you to load a database table

schema, convert it into a TIBCO ActiveEnterprise schema, and store it in the schema

folder of an instance.

Allow Key Columns Only

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

unchecked, child columns can be joined to any column.

Select/Deselect All Columns to Publish

When this box is checked, all of the boxes in the Use column are checked, so all columns

in the tables are published. Unchecking this box unselects all of the columns. You can also

individually check and uncheck the Use? checkboxes.

Referencing an External Schema

To reference an external schema in TIBCO Designer, the default schema must have the

proper access privileges. These are set in a command line. In the following syntax,

adb_schema refers to the default schema in create_user.sql.

For Oracle, log in as system and grant create any trigger and drop any trigger permissions to the

default schema. For example:

grant create any trigger to adb_schemagrant drop any trigger to adb_schema

Table 17 Publication Service Tables Tab

Field Description

Tables and

Columns

The loaded tables and columns.

indicates a table or child table.

indicates a normal column.

indicates a User Key column.

Type The primitive type.

AE Type The primitive type mapped to an TIBCO ActiveEnterprise type.

User Key Click to define the column as a user key.

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

Use? Click to publish this column when data is changed.

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



In addition, Oracle and Sybase users must have permission to SELECT from a source table

in an external schema. If table relationships are used, SELECT permission is required for

both parent and child tables. SELECT, INSERT, UPDATE, and DELETE permissions are required

for accessing a destination table in an external schema.

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

sp_role "grant", sa_role, adb_schema

For SQL Server 7.0 and 2000, log in as sa and then execute the following before creating

catalog tables for the external schema:

use master

EXEC sp_addsrvrolemember 'adb_schema', 'sysadmin'

For DB2 on AS400 you can avoid table access problems by changing the ActiveDatabase

user authority to *ALLOBJ.

Adding Child Tables

This section describes how to add a related child table definition for publishing data.

Data models typically contain tables that share column data through a relationship. You

can configure a publishing table to include related data from another table when it

publishes. Data from the related table is not copied into the publishing table, but is fetched

by reference.

When rows are inserted into the publishing table, a message that includes data from the

source table and related (child) table is published. On the subscriber side, a corresponding

table with the same columns as the child table associated with the publishing table must be

specified.

Adding child tables requires two separate procedures, one for the publisher adapter and

another for the subscriber. First, you add child tables for the source table, then you add

child tables for the destination table.

The database schema must be the same for all tables, but the table names can be different.

If the child table associated with the publishing table and the child table associated with

the destination table have different names, you must set a mapping between the child

tables.

The following restrictions apply to parent and child tables:

• The child table in the source database and child table in the destination database must

have the same columns.

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

repository as the publisher adapter.



When you add a child table, TIBCO Designer creates a class object in the repository for

the child table, and an association object for the relationship.

After adding child tables for a subscriber adapter, you create mappings between child

tables on the publisher side and child tables on the subscriber side. For instructions, see

Child Table Mappings Tab on page 80.

To add child tables for parent-child relationships, do the following in the Publication

Service Tables Tab:

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

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

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

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

When all of the child tables are added, you then designate a foreign key column as a key in

each child table so that a relationship to the parent table can be defined.

5. Click the User Key checkbox for the foreign key column in the child table to select it.

A key icon displays next to the column name.

You must also specify the relationship between the primary column in the parent table and

the foreign key column in the child table.

6. Click in the Join To field for the child table column, and select the name of the parent

table primary key column from the drop-down list.


To enable publishing child table related data, the publisher adapter properties file must

have the adb.publishChildData option set to on.



In the following example, a publication service that publishes newly inserted rows into the

source table is created. Publisher Options Tab on page 72 explains how to configure the

publisher adapter to publish data by value or by reference.

In the following example, a subscription is created such that received data will be inserted

into the SUB_ORDER_DETAILS destination table. All three columns of the destination table

are configured to receive data.



The following example shows a child table mapped. The left column (Subscriber Child Table

Name) contains the subscriber child table and the right column (Publisher Child Table Name)

contains the publisher child table.

DB2/OS390 Tab

This tab appears when the Vendor field in the Adapter Instance Configuration Tab is set to

DB2 OS390.

When the DB2 load utility loads rows to the source table, it does not activate the table’s

INSERT triggers. Loaded data is not published.

Table 18 Publication Service DB2/OS390 Tab

Field Description

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



DB2/AS400 Tab


DB2 AS400.

Trigger Option

• Synchronous (deprecated) — The trigger is written in RPG. When copying from the

source table to the publishing table, the prompt is not returned until all data is written.

• Asynchronous — When copying from the source table, data is inserted into a data

queue and then inserted into the publishing table asynchronously. The prompt is not

blocked, so you can continue working while data is inserted into the publishing table.

Specify values for the following options:

— Number of DataQueue Listeners: The number of prestarted listener jobs.

— Listener Job Queue: The name of the queue on the AS/400 machine where the

listener jobs are submitted.

Table Space

Name

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

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

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

Index Suffix Enter a suffix of your choice, up to 13 characters, that the adapter will append to each of the indexes

(IDX1_, IDX2_, and IDX3_).

Trigger Suffix Enter a suffix of your choice, up to 5 characters, that adapter software will append to each of the

triggers (T1, T2, and T3).

Table 18 Publication Service DB2/OS390 Tab (Cont’d)

Field Description



If you select Asynchronous, you must go to the adapter’s Design-time Connection

tab and add ;transaction isolation level=none to the end of the JDBC URL field. For example:

• SQL — The trigger is written in SQL. When copying from the source table to the

publishing table, the prompt is not returned until all data is written.

Sybase Options


Sybase.

Check the Overwrite Triggers? checkbox to delete and re-create existing triggers of the

publishing table.

Child Table Order By Tab

This tab allows you to specify the column(s) of an Order By Clause used for each children

table queries. The adapter will return the child table result set in a particular sequence.



Click on a child table name and click the Select Column button.

The Select Child Table Order By Columns dialog box appears.

Select the column(s) for the Order By Clause from the left panel and click the Apply

button. Use the Up and Down buttons to arrange the column order by sequence. To sort in

descending value, select the check box next to the column name.



Publisher Options Tab

When you add a new publishing table, a new entry is inserted into the repository for the

publisher adapter. The entry includes the name of a publishing table along with a

sequence, stored procedure, and trigger. A class object for the publication is created in the

repository.

Table 19 Publication Service DB2/AS400 Options Tab

Field Description

Storage Mode For each publisher service, you must specify a Storage Mode: Publish by Value or Publish by

Reference. See Publish by Value on page 73 and Publish by Reference on page 74 for more

information.

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

• Publish by Reference copies only key column values to the publishing table. If no key column is

defined in the database, a substitute non-key column must be defined to publish by reference.

Publishing Table Name of the database table used to store a copy of data to be published. The table name can be

qualified using the schema.table_name format. The publishing table cannot contain any user-created

columns where the column name starts with ADB_. These characters are reserved for use by the

adapter.

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

A publishing table name must be less than 64 characters.

Update Mode Select the method by which tables are updated.

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

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

insert.

Enable Loop

Detection

Select to enable loop detection and prevent an infinite loop from occurring when the publishing and

destination table are the same table. Loop detection is disabled for DB2 on z/OS because of DB2 on

z/OS feature limitations.

Do Not Generate

Triggers

Select to prevent the generation of triggers. Although this option is not recommended, it allows you

to manually manage the insertion of data into the publishing table.

Use Alerter Select to use the alerter. This option appears only if you are using an Oracle database. See Chapter 6,

Using the Alerter, on page 97 for details.

Enable Group

Messaging

Select to use group messaging. Note that Rendezvous message wire format does not apply for group message.

Group Size Appears only when the Enable Group Messaging is checked. Specify the number of rows to publish

in a single message. Global variables are acceptable.



Publish by Value

With Publish by Value, all specified columns in the source table are copied to the

publishing table. Publishing by value is fast, but does not support some data types, for

example Oracle LONG and LONG RAW.

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

• Publishing tables cannot contain columns with LONG data types. If you have a source

table that contains a column with a LONG data type, that column cannot be specified

for inclusion in the publishing table. This is because the trigger generated by the

palette cannot to the LONG column via the :new construct.

This is an Oracle restriction documented in the Oracle SQL Reference manual. The

problem is not detected by Oracle during trigger creation. However, when the trigger

fires and it attempts to copy the LONG column value to the publishing table, the

database connection will hang for some time and then eventually terminate.

• If you define parent-child relationships between tables, the publishing table that is

created for a parent table should not contain a column with a LONG data type.

However, a child table can contain a column with a LONG data type. This is because

data on child table rows is not copied using the :new construct.

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

These restrictions do not apply to publishing tables when you publish by reference and

LONG or LONG RAW are non-key types.

In the following example, the publishing table P_CUSTOMER is created for the source table,

CUSTOMER. When CUSTOMER is updated, the new data will be copied to P_CUSTOMER. The

adapter will poll P_CUSTOMER and publish the new data.

Enable Load

Balancing

Check to use load balancing which enables multiple publisher endpoints to poll and publish changes

of the same source (publisher) table. Set batch polling size before selecting this option.

Mutex Name Appears only when the Enable Load Balancing checkbox is checked. Specify the name for the

mutex table.

Table 19 Publication Service DB2/AS400 Options Tab (Cont’d)

Field Description

In this example, loop detection is enabled. If a subscription exists that uses the same

subject and CUSTOMER as the destination table, any changes to CUSTOMER will not be

published repeatedly.



Publish by Reference

With Publish by Reference, only key column values are copied to the publishing table. The

publish by reference feature allows you to publish data directly from the source table

without first copying the data from the source table to a publishing table. A trigger, stored

procedure, and publishing table are created, but the publishing table contains the

necessary adapter fields and only the key fields of the source table. For more information,

see Start or Stop the Adapter on page 94.

The advantage of publishing by reference is that the data to be published is stored just

once. Also, data types such as Oracle LONG and LONG RAW are supported for

publishing by reference.

A key column or substitute key column is required when publishing by reference, since

the publishing table contains only key values. If no column is specified, the publication is

not added.

To use a view or other database object as the source table, you can configure the adapter to

publish by reference object, where key columns are stored in the publishing table and data

to publish is selected from the reference object. For details, see Publishing by Reference

Object on page 171.



In the following example, the publisher adapter is configured to publish from the

P_CUSTOMER table with a key field CUST_ID. The publishing table is created with the

necessary fields and the CUST_ID field. When a row in the P_CUSTOMER table is modified,

the trigger fires, populating fields and copying the CUST_ID value to the publishing table.

When the adapter polls the publishing table, it detects the new row and selects from the

P_CUSTOMER table using the CUST_ID value found in the publishing table. Then the message

is published.

Advanced Tab

This tab allows you to specify values for the following fields:

Table 20 Publication Service Advanced Tab

Field Description

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

Tab on page 35)

The publisher destination. A service uses a default destination generated using the Domain and

Deployment global variables, the adapter acronym, the adapter instance name and the service name. If

you use this default destination, make sure the values for Domain and Deployment are not empty.

Alternatively, you can manually enter a destination in this field. The destination does not have to be

predefined in the TIBCO Enterprise Message Service server. The destination can be static or

dynamic.

See Subject and Destination Names on page 163 for information about specifying destinations.

See TIBCO Enterprise Message Service User’s Guide for more details about destinations.



Message Subject (Only available when TIBCO Rendezvous is selected as the transport type in the Adapter Instance

Configuration Tab on page 35)

Publisher subject. By default, a service uses a message subject that is generated using the Domain

and Deployment global variables, the adapter acronym, the adapter instance name and the service

name. If you use this default subject, make sure the values for Domain and Deployment are not

empty. You can type a TIBCO Rendezvous subject name different from the default in this field.

See Subject and Destination Names on page 163 for information about specifying subjects.

See TIBCO Rendezvous Concepts for more details about subjects.

Endpoint

Reference

Displays the endpoint reference. Click the Browse icon to change the endpoint reference, the Go To

icon to reconfigure the existing reference, or the Delete icon to delete the reference. Endpoint

reference objects are explained in TIBCO Designer Palette Reference.

Class Reference Click the Go To icon to reconfigure the existing reference. Clear reference can be used to remove the

reference under Endpoint Reference. Class reference objects are explained in TIBCO Designer

Palette Reference.

Table 20 Publication Service Advanced Tab (Cont’d)

Field Description


Subscription Service Tabs | 77

Subscription Service Tabs

When running as a subscriber, the adapter listens on a subject, receives messages and

updates the relevant tables in its associated database. The data is then available to other

applications that have access to the database.



• Table Tab on page 78

• Child Table Mappings Tab on page 80

• Child Exception Table Mappings Tab on page 81

• Subscriber Options Tab on page 82


Configuration Tab


Table 21 Subscription Service Configuration Tab

Field Description

Name Type a name unique among all subscribers defined for this project. You can use the default name or

replace it with a name of your choice.

A service name must use alphanumeric characters, including underscore (_). You cannot use a blank

space. The entire instance name must be less than 80 characters.

A service name cannot use global variables.

Transport Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime adapter. This

selection determines which options appear in the rest of the Configuration tab.










Table Tab

You must set subscriber table options before configuring other subscriber options.

Quality of Service Only available when TIBCO Rendezvous is selected as the transport type) Select the level of service

that determines how messages are sent. See Quality of Service on page 58 for a description of these

options.

• Certified

• Reliable





• Rendezvous Message (TIBCO Rendezvous only)

• XML Message (TIBCO Rendezvous or JMS)

• ActiveEnterprise Message (TIBCO Rendezvous only)

Connection

Factory Type

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

• Topic (JMS only)

A message published to a topic is broadcast to one or more subscribers. All messages published to

the topic are received by all services that have subscribed to the topic. This messaging model is

known as publish-subscribe.

• Queue (JMS only)

A message sent to a queue is consumed by one and only one receiver. Each message has only one

receiver though multiple receivers may connect to the queue. The first receiver to access the queue

gets the message. The other receivers do not. This messaging model is known as point-to-point.

Delivery Mode (Only available when JMS is the transport type and Topic is the connection factory type) The

delivery mode for each message sending operation. See Delivery Mode on page 59 for a description

of each mode.

• Persistent

• Non-Persistent

Table 21 Subscription Service Configuration Tab (Cont’d)

Field Description



An incoming message need not contain data for all the columns defined in the subscriber

table. An adapter can be configured to expect only a subset of the columns. The adapter

checks the repository for attributes defined in the subscriber table's class object definition.

When a message arrives, the adapter iterates through the attributes in the subscriber table’s

class object definition and looks for those same attributes in the incoming message.

Subscriber table names can be qualified with a schema name, such as SCOTT.EMP. To access

tables in other schemas, the database user defined in the adapter Connection tab must have

the proper set of permissions granted. For more information see TIBCO ActiveMatrix

Adapter for Database Concepts.

When configuring the destination table, subscribe only to columns that should be updated.

If you subscribe to a column that should not be updated and a message arrives with no data

for that column, a NULL will be written to that column. For example:

• If a source table is configured to send data for columns, c1, c2 and c3 and the

destination table is configured to receive data for columns c1, c2, c3, c4, and c5:

— For the TIBCO Rendezvous message wire format, columns c1, c2, and c3 will get the data

and columns c4 and c5 will get a NULL value.

— For the TIBCO ActiveEnterprise message and XML message wire format, columns c4 and c5

will be ignored and take on whatever default values they are supposed to have.

• If a source table is configured to send data for columns, c1, c2, and c3 and the

destination table is configured to receive data for columns c1, c2, and c3 but not

configured to receive data for columns c4 and c5, columns c4 and c5 will retain the

defaults applicable to both tables.

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

use the same repository as the publisher adapter.



Icons

Add Table — Click to display a dialog box that list tables available to the

database user specified in the adapter Connection tab. Select the table to be used as the

subscription table where data is inserted when received.

Add Child Table — Displays a dialog box from which a secondary table can be

added to the configuration.

Add Table from Other Schema — Allows you to enter a schema. For instructions

on granting access privileges to an external schema, see Referencing an External

Schema on page 64.

Remove Table — Deletes the selected table from the configuration.

Re-find Table from Database — Causes TIBCO Designer to refresh stored table

schema information by retrieving new information from the database.

Allow Key Columns Only — If selected, child columns are joined only to a key

colulmn. If unselected, child columns can be joined to any column.

Columns

Tables and Columns — Lists the table and columns.

Type — Lists the primitive type.

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

User Key — Click to define as a user key.

Use? — Click to enable the column to be updated when a message arrives. Subscribe

only to columns that should be updated. Columns not configured to receive data will

retain their default value. For columns that have been configured to receive data but

do not get updated:

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

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

the statement.

Join To — Joins two tables.

Child Table Mappings Tab

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

same name.

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



The following example shows a child table mapped. The left column (Subscriber Child

Table Name) contains the subscriber child table and the right column (Publisher Child

Table Name) contains the publisher child table.


Child Exception Table Mappings Tab

Each child table can be configured to use an exception table.


Table 22 Subscription Service Child Table Mappings Tab

Field Description

Subscriber Child

Table Name

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

tables for a subscription service.

Publisher Child

Table Name

Click in this column and type the name of a publisher child table. Prefix the table name with a

database user if your database requires it.

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

Table 23 Subscription Service Child Exception Table Mappings Tab

Field Description

Subscriber Child

Table Name

The child tables that can be mapped. Entries are automatically created when you add child tables for

a subscription service.

Publisher Child

Table Name

Click in this column and type the name of a exception child table. Prefix the exception table name

with a database user if your database requires it.



Subscriber Options for DB2 on OS/390 (z/OS)


DB2 OS390.

Subscriber Options Tab

This tab allows you to specify values for the following:

Table 24 Subsciption Service DB2/390 Options Tab

Field Description

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

Table Space

Name

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

LOB Table Space

Name

The name of the LOB table space name where auxiliary table of the opaque exception table is

located.

Table 25 Subscription Service Subscriber Options Tab

Field Description

Exceptions Table Name of exception table where data is written if the adapter cannot write to the subscriber table.

This table will hold messages that caused an exception. If the table does not exist, the subscription

service creates it. For details, see Exception Table on page 149.

The exception table cannot contain any user-created columns where the column name starts with

ADB_. These characters are reserved for use by the adapter.



If you are using the JMS transport, you must set the JMS Destination Prefix. See JMS

Destination Prefix on page 47 for details.

Note that:

• All subscription service threads reconnect separately if the database connection is lost.

Use Opaque

Exceptions Table

Check the checkbox to use an opaque exceptions table. The table records each message (entirely)

into a column, along with the error message. A message is logged in the exceptions table if the

subscription service fails to generate records in the destination table or the adapter fails to insert a

message into an exception table.

For DB2/OS390 databases, you must create a Large Objects (LOB) tablespace before using the

opaque exceptions table, which will use the LOB tablespace.

Opaque

Exceptions Table

The name for the opaque exceptions table.

Pre Commit

Stored Procedure

The value entered here represents the name of a stored procedure the subscriber will call after the

database insert, update, or delete and prior to commit.

Reply Sender

Quality of Service

If the subscriber must send a reply to the sender, this value identifies the quality of service or

delivery mode to use when sending the reply. See Quality of Service on page 58 and Delivery Mode

on page 59 for a description of these fields.

• Reliable (TIBCO Rendezvous transport type only)

• Certified (TIBCO Rendezvous transport type only)

• Persistent (JMS transport type only)

• Non-persistent (JMS transport type only)

Use Separate

Service Thread

When selected, a new session is created and the service endpoint is moved to this session. The

subscriber batch commit count towards the number of messages processed by all the endpoints of

each session. You can select other subscription service sessions by changing the session reference

field (under the Advanced tab). This allow multiple services to share the same session and

dispatcher.

Enable Group

Message

Transaction

Support

When selected, the group message will be processed within a single transaction by the subscription

service. The adapter will either commit the whole message changes to the database, or none.

Service Bulk

Insert Size

You can set a different bulk insert size for this service. If not set, the service will use the bulk insert

size of adapter instance options.

Table 25 Subscription Service Subscriber Options Tab (Cont’d)

Field Description



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


Table 26 Subscription Service Advanced Tab

Field Description

Destination (JMS transport type only)

The subscriber destination. A service uses a default destination generated using the Domain and





dynamic.



Message Subject (TIBCO Rendezvous transport type only)

By default a service uses a message subject that is generated using the Domain and Deployment global

variables, the adapter acronym, the adapter instance name and the service name. If you use this

default subject, make sure the values for Domain and Deployment are not empty. You can type a

TIBCO Rendezvous subject name different from the default in this field.



Endpoint

Reference

Displays the endpoint reference. Click the Browse icon to change the endpoint reference or the Go

To icon to reconfigure the existing reference. You can also click the Delete icon to remove the

reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.

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



Request-response Service Tabs | 85

Request-response Service Tabs

This service is often called a Request Reply Server or RPC (Remote Procedural Call)

Server. When running as a request-response service, the adapter receives requests from

other applications, parses them, calls the appropriate component interface API to set the

input fields, then calls another set of component interface APIs to get the output fields.

The output fields are wrapped in a schema and sent back to the caller.

A request-response service is renamed ADBServer when you drag its icon into the design

panel. Configuration involves specifying its name, quality of service and wire format. A

server operation allows the adapter to process requests from client applications and return

results in a response to the client.

When using the RPC server, you can configure custom operations. These are configured

under the Call Operation Tab.



• Call Operation Tab on page 87


Configuration Tab


Table 27 Request-response Service Configuration Tab (Sheet 1 of 3)

Field Description

Name Type a name unique among all request-response services defined for this project. You can use the

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

A service name must use alphanumeric characters, including underscore (_). You cannot use a blank

space. The entire instance name must be less than 80 characters.

A service name cannot use global variables.



Transport Type Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime adapter. This

selection determines which options appear in the rest of the Configuration tab. Only the options that

are available with the selected Transport Type, Connection Factory Type, Mode or Wire Format are

displayed.








Quality of Service Only available when TIBCO Rendezvous is selected as the transport type) Select the level of service

that determines how messages are sent. See Quality of Service on page 58 for a description of these

options.

• Certified

• Reliable





• Rendezvous Message (TIBCO Rendezvous only)

• XML Message (TIBCO Rendezvous or JMS)

• ActiveEnterprise Message (TIBCO Rendezvous only)

Connection

Factory Type

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

• Topic (JMS only)

A message published to a topic is broadcast to one or more subscribers. All messages published to

the topic are received by all services that have subscribed to the topic. This messaging model is

known as publish-subscribe.

• Queue (JMS only)

A message sent to a queue is consumed by one and only one receiver. Each message has only one

receiver though multiple receivers may connect to the queue. The first receiver to access the queue

gets the message. The other receivers do not. This messaging model is known as point-to-point.


Field Description



Call Operation Tab

This tab appears when the mode is set to RPC and the Use Custom Operations box is

checked in the Request-Response Service Configuration tab.

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

button.

TIBCO Designer retrieves the signature of each stored procedure and function from the

database.


Delivery Mode (Only available when JMS is the transport type) The delivery mode for each message sending

operation. See Delivery Mode on page 59 for a description of each mode.

• Durable

• Non-Durable

Mode Specify if this endpoint will be a Request Reply Server or RPC (Remote Procedural Call) Server.

• Request Reply: A subscriber endpoint will be created. This subscriber will listen to

request and publish the reply to the reply subject.

• RPC: A server endpoint will be created. This server will receive a request from and

send back the reply to the client.

Use Custom

Operations

This checkbox appears when the Mode field is set to RPC. Selecting this checkbox and clicking the

Apply button creates the Call Operation Tab.


Field Description

If you change the stored procedure or database connection while editing your project, you

must return to this dialog and click the Refresh button to retrieve the changes from the

database.

Table 28 Request-response Call Operation Tab

Field Description

Name Enter a unique name for the call operation.

Catalog/Package (Optional, only applicable to databases that have more than one catalog or package.) The catalog or

package in which the procedure resides. This name is used to resolve naming conflicts if more than

one catalog or package in the database has the selected procedure with the same name. See your

database documentation for more information about catalogs and packages.



Advanced Tab


Schema (Optional) The schema in which the procedure resides. This name is used to resolve naming

conflicts if more than one schema in the database has the selected procedure with the same name.

Procedure Name Name of the database procedure or function to call.

Select Procedure Queries the database for available procedures or functions or the Procedure Name field. Clicking

this button displays a dialog showing the available procedure.

To select a procedure or function:

1. Select a call operation from the list on the left. Its input and output parameters, if any,

are displayed in the fields on the right side of the dialog.

2. Click Select Procedure.

Maximum Rows (Optional) The maximum number of rows to retrieve.

One Way (Optional) Check this checkbox if you want to execute this procedure using a one-way operation. If

left unchecked, the procedure will execute using a two-way operation.

Table 28 Request-response Call Operation Tab (Cont’d)

Field Description

Table 29 Request-response Service Advanced Tab

Field Description

Destination (JMS transport type only)

The subscriber destination. A service uses a default destination generated using the Domain and





dynamic.





Message Subject (TIBCO Rendezvous transport type only)

By default a service uses a message subject that is generated using the Domain and Deployment global

variables, the adapter acronym, the adapter instance name and the service name. If you use this

default subject, make sure the values for Domain and Deployment are not empty. You can type a

TIBCO Rendezvous subject name different from the default in this field.



Reply Subject Type a TIBCO Rendezvous subject name that the adapter uses to respond, if no response subject is

specified in the request message.

Endpoint

Reference

Displays the endpoint reference. Click the Browse icon to change the endpoint reference or the Go

To icon to reconfigure the existing reference. You can also click the Delete icon to remove the

reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.

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


Table 29 Request-response Service Advanced Tab (Cont’d)

Field Description


| 91

Chapter 5 Deploying and Starting the Adapter Using

TIBCO Administrator

Topics

• Create an EAR File in TIBCO Designer, page 92

• Deploy the Project, page 93

• Start or Stop the Adapter, page 94

• Monitor the Adapter, page 95

This chapter provides an overview about deploying, starting, stopping, and monitoring

adapter services using the TIBCO Administrator web interface.


92 | Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator

Create an EAR File in TIBCO Designer

Generate an Enterprise Archive file (EAR) that contains information about the adapter

services to deploy.

The EAR file contains information on what you wish to deploy. This could be one or more

adapter services, one or more TIBCO ActiveMatrix BusinessWorks process engines, or

both.

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

1. Configure the adapter services.

2. Drag and drop the Enterprise Archive resource from the palette panel to the design

panel.

If there are any configured adapter services in your project, an Adapter Archive

resource becomes available in the palette panel.

3. Drag the Adapter Archive into the design panel and specify information in the

Configuration tab.


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

See Also

See TIBCO Designer User’s Guide for more information about this procedure. The guide

is available from the Designer Help menu.

Building an archive creates the EAR file, which you can then deploy from TIBCO

Administrator. If you make changes to the business processes or adapter services included

in the archive, you need to rebuild the archive. Saving the project does not affect the

archive.


Deploy the Project | 93

Deploy the Project

Before deploying a project, the machine on which the adapter is installed must be part of a

TIBCO administration domain. After you have installed the TIBCO Administration

Server, any machine on which you install TIBCO Runtime Agent (required by an adapter)

can be added to the administration domain. The TIBCO software installed on the machine

is then visible and accessible via the TIBCO Administrator GUI.

When you deploy a project, startup scripts and other information about the different

components are sent to the machines to which the components were assigned. The project

data store and TIBCO Administration Server are updated with the deployed components.

To deploy a project:

1. Import the EAR file into TIBCO Administrator.

2. Assign adapter archives in the EAR file to adapters installed in the administration

domain and likewise assign process archives to process engines.

3. Specify startup options for each adapter service.

Password Handling

At design time, the adapter uses a password to connect to the backend application and

fetch metadata. At runtime, the adapter uses a password to connect to the back-end

application and interoperate with it. If you create a 4.x configuration using TIBCO

Designer 5.1, and use the configuration with a 4.x adapter version, some special

considerations are required for security.

When deploying the adapter check the Service property of the global variable in the global

variables section, then go to the Advanced tab of the adapter archive and set the password

value under the Runtime Variables section.

See Also

See TIBCO Administrator User’s Guide for an introduction to the TIBCO administration

domain and detailed information about the above steps.

Do not set the password to type Password in the global variables section for adapter

configurations that are set to AE Version 4.0 or AE Version 5.0 (in the Configuration tab

Version field) or any intermediate version.



Start or Stop the Adapter

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

deployed applications.

To start an adapter service from the module:

1. In the Administrator GUI left pane, expand Application Management >

application_name > Service Instances.

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

3. Click the Start Selected button.

The status changes from Stopped to Starting up to Started.

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

See Also

See TIBCO Administrator User’s Guide for more information.


Monitor the Adapter | 95

Monitor the Adapter

TIBCO Administrator offers a number of monitoring options.

• Specify alerts and TIBCO Hawk rulebases for each machine in the domain.

• Specify alerts and Hawk rulebases for each adapter service.

• View the log for each adapter service.

See Also

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

monitoring options.


| 97

Chapter 6 Using the Alerter

This chapter explains how to configure and start an alerter for each supported database.

Topics

• Introduction, page 98

• Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and

Above, page 99

• Setting Up and Starting the Alerter on Microsoft SQL Server 2000, page 103

• Setting Up and Starting the Alerter on Sybase SQL Server, page 106


98 | Chapter 6 Using the Alerter

Introduction

The alerter process is used to asynchronously notify running publication service instances

of database changes. The adapter does not need to poll its publishing table for existence of

new rows. Use the alerter only when database changes are infrequent.

The procedures can be executed on the SQL command line or through any supported

Application Programming Interfaces (the procedures cannot be invoked successfully from

within a trigger). The procedures commit the inserts into the database table and notify the

adapter of the commit.

Because the alerter process runs with a database instance, not user schema, an adapter

instance cannot poll the publishing table name for just one user schema. For example, if

the same publishing table exists for two user schemas and two instances are monitoring

the same publication table, each instance with a different user, both instances will check

the same publication table whenever the alerter checks for changes in the publication

table.

The alerter is available on the following databases.

Oracle and Microsoft SQL Server 2005

An alerter for Oracle is part of the adapter and available on all operating systems

supported by the adapter. The alerter can be used in the TIBCO ActiveMatrix Adapter for

Database environment in cases where changes are infrequent and polling by the

publication service would result in unnecessary and expensive operations. The alerter is

supported on both the Rendezvous and JMS transports.

Microsoft SQL Server 2000

An alerter function for Microsoft SQL Server is available on all operating systems

supported by the adapter. The procedures are executed on the SQL command line itself,

and there is no separate program. The alerter functionality is embedded in a dynamic

linked library. The alerter is only supported on the Rendezvous transport.

Sybase SQL Server

An alerter function for Sybase SQL Server is available on Microsoft Windows along with

Solaris. The procedures are executed on the SQL command line itself, and there is no

separate program. The alerter functionality is embedded in a dynamic linked library. The

alerter is only supported on the Rendezvous transport.


Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and Above | 99

Setting Up and Starting the Alerter on Oracle or Microsoft SQL

Server 2005 and Above

The alerter on Oracle uses the Oracle AQ package and on MS SQLServer 2005 and above

uses the Service Broker component to send and receive information between sessions,

asynchronously allowing two or more sessions in the same database instance to

communicate.

As shown in the following figure, when a source table is updated with data and the

commit_and_notify procedure executed, a trigger copies the data to the publishing table and

notifies the Oracle AQ or MS SQLServer and that a publishing table has changed. The

alerter gets the notification from Oracle AQ or MS SQLServer and sends a notification

message to the adapter that a publishing table has changed. The adapter then queries all its

configured publishing tables for the new data and sends it on a subject to the TIBCO

transport. One or more instances can be notified.

Figure 4 Alerter Operation (Oracle and MSSQLServer)

If there are multiple publishing tables under the same database account, you can use the

commit_and_notify_table procedure to specify that only a particular table be checked by the

adapter. This prevents the adapter from needlessly checking all its publishing tables for

updates when only one table has been updated with new data. This notification can be sent

to one or more instances.

The Microsoft SQL Server mentioned below in this section refers to version 2005 and

above.



The following object types and stored procedures are available for committing messages

when the alerter is used:

Name Type Description

adb_alerter_qtbl

(Oracle only)

AQ queue table Queue table for all alerters.

adb_alerter_q

(Oracle only)

AQ queue Queue for all alerters.

adb_alerter_typ Service Broker

Message Type

Object type for all messages.

adb_alerter_contract

(Microsoft SQL Server 2005 only)

Service Broker

Contract

The contract type used. The contract specifies the

message types that can be used.

instance_Id_q


Service Broker

Queue

Created by the config_alerter stored procedure.

instance_Id_send_service


Service Broker

Service


instance_Id_rcv_service


Service Broker

Service


adb_alerter_typ Object Object type for the payload message.

commit_and_notify Procedure Sends a change notification to all adapters.

commit_and_notify_agent

alerter_name

Procedure Sends a change notification to the named alerter.

commit_and_notify_table table_name Procedure Sends a change notification for a named table.

stop_alerter Procedure Stops all running alerters.

stop_alerter_agent alerter_name Procedure Stops the alerter for the named alerter.

config_alerter Procedure Alerter call to register itself as an AQ subscriber.

cleanup_alerter Procedure Alerter call to unregister itself as an AQ subscriber.

listen_pipe Procedure Alerter call to block on alerts.


Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and Above | 101

Before Starting

When using the alerter functionality with Oracle database, make sure you have executed

the create_user.sql and alerter.sql files with the database account used by the adapter, as

described in Post-Installation Tasks in TIBCO ActiveMatrix Adapter for Database

Installation.

When using the alerter functionality with Microsoft SQL Server database, make sure you

have enabled the service broker functionality in the database server. To check if the

service broker is enabled, execute:

SELECT is_broker_enabled FROM sys.databases WHERE database_id = DB_ID()

The returned value should be 1.

To enable service broker, execute

Alter database dbname set enable_broker with rollback immediate

Configuring and Starting the Alerter

To use the alerter, you must install the Oracle AQ or Microsoft SQL Server package. See

your Oracle documentation for information about installing the Oracle AQ or Microsoft

SQLServer package. When configuring the publication service, you must enable the

alerter by checking the Use Alerter checkbox under the Publisher Options tab. When the

adapter starts, the alerter will also start.

Oracle Alerter Example

This section describes how to execute the commit_and_notify_table stored procedure. It assumes

the rvpub.tra configuration has its data source name, user account name (demo) and password

defined in the repository. The rvpub adapter publication service has been configured with

the Use Alerter checkbox checked.

1. Start the adapter publication service instance by typing:

adbagent --propFile rvpub.tra rvpub.tra

2. After inserting a message, execute the commit_and_notify_table stored procedure with the

publishing table monitored by the adapter. For example, if the adapter is monitoring

the PUB_ORDER table:

sqlplus demo/demo

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

SQL> execute commit_and_notify_table (’PUB_ORDER’);

If an adapter that uses the alerter is not shutdown cleanly, you must call the cleanup_alerter

stored procedure before restarting the adapter. The procedure is normally called by the

adapter when it shuts down cleanly.



The procedure puts a message on an Oracle AQ. The publisher adapter then reads its

publishing table and sends a message containing the changed data on its configured

subject.

This example shows how to tell the adapter instance to poll a single table, PUB_ORDER,

for changes. Use the commit_and_notify stored procedure to poll all publishing tables for

changes.

SQL Server Alerter Example

This section describes how to execute the commit_and_notify_table stored procedure. It assumes

the rvpub.tra configuration has its data source name, user account name (demo) and password

defined in the repository. The rvpub adapter publication service has been configured with

the Use Alerter checkbox checked.

1. Start the adapter publication service instance by typing:

adbagent --propFile rvpub.tra rvpub.tra

2. After inserting a message, execute the commit_and_notify_table stored procedure with the

publishing table monitored by the adapter. For example, if the adapter is monitoring

the PUB_ORDER table:

isql -Udemo -Pdemo

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

SQL> execute commit_and_notify_table ’PUB_ORDER’;

The procedure puts a message to the service broker queue, which is picked up by the

adapter. The publisher adapter then reads its publishing table and sends a message

containing the changed data on its configured subject.

This example shows how to tell the adapter instance to poll a single table, PUB_ORDER,

for changes. Use the commit_and_notify stored procedure to poll all publishing tables for

changes.


Setting Up and Starting the Alerter on Microsoft SQL Server 2000 | 103

Setting Up and Starting the Alerter on Microsoft SQL Server 2000

On Microsoft SQL Server the alerter mechanism is an extended stored procedure in a

dynamic link library (provided with installation media) that is dynamically loaded into

SQL Server.

Two stored procedures are available for sending messages when using the alerter:

• notify. Sends a TIBCO Rendezvous message to the given instance or instances that one

or more publishing tables have been updated.

• notifytable table_name. Sends a TIBCO Rendezvous message to the given instance or

instances that the given publishing table has been updated.

Before Starting

A database account must have been created for running the adapter. This is typically done

after installation. See TIBCO ActiveMatrix Adapter for Database Installation for details.

Alerter Setup

Before using the alerter you must copy the alerter dynamic link library adbalerter_mssql.dll to

the Binn directory where SQL Server is installed, add the notify and notifytable external stored

procedures to the master database and set execute permission on the procedures for the

database account used by the adapter.

1. Open a command window and change directory to the TIB_ADADB_HOME/lib

directory.

2. Copy the alerter library to the Binn directory where SQL Server is installed, for

example:

copy adbalerter_mssql.dll \Mssql7\Binn

3. Ensure the procedures are not already defined in the master database:

isql -Usa -Ppassword1> sp_dropextendedproc notify

2> go

1> sp_dropextendedproc notifytable

2> go

1> DBCC adbalerter_mssql(FREE)

2> go

DBCC execution completed. If DBCC printed error messages, contact your system administrator.

4. Add the procedures to the master database:

1> sp_addextendedproc 'notify','adbalerter_mssql.dll'

2> go

1> sp_addextendedproc 'notifytable','adbalerter_mssql.dll'



2> go

5. Set access permissions for the database account used by the adapter:

1> grant execute on notify to database_account2> go

1> grant execute on notifytable to database_account2> go

1> exit

6. Add TIBCO_HOME\tibrv\bin to the system PATH variable.

Using the Alerter

When using the alerter, the adapter instance must be started with polling disabled. In this

example, after adding a row in a table monitored by the adapter, the alerter procedure is

invoked and the adapter checks for updates in its publishing table. The database server

name is itaska and database name is activedb.

1. In a command window, start an adapter instance with polling disabled (set the

adb.PollingInterval value to 0 in the properties file):

adbagent --propFile properties_file_name

2. In another command window, insert a row into the database table being monitored by

the adapter, commit the transaction, then invoke the notify procedure:

isql -Uadb -Padb -dactivedb

1> insert into ORDER_TABLE values(406,'walnut table',9899.89)

2> go

1> execute itaska.master.dbo.notify @agentname='rvpub'

2> go

Notifying: rvpub

You can also execute the notify procedure for more then one adapter instance. Each

configuration name must be separated using a space character. For example:

1> execute itaska.master.dbo.notify @agentname='rvpub

rvpub2 rvpub3'

2> go

The notifytable procedure can be invoked for one or more adapter instances and one

publishing table. If the database used by the adapter and master database are on the

same database server, the server prefix need not be given.

1> execute itaska.master.dbo.notifytable

@agentname='rvpub rvpub2',@tablename='P_ORDER_TABLE’

2> go

Modifying RV Configuration

The RV configuration parameters used by the alerter to connect to a remote daemon can be

modified by including the configuration parameters when invoking the store procedure.


Setting Up and Starting the Alerter on Microsoft SQL Server 2000 | 105

For example,

execute master.dbo.notify @agentname='rvpub', @service='7500', @network=’lan0’, @daemon='10.105.176.21:7500'

execute master.dbo.notifytable @agentname='rvpub rvpub2', @pubtable='ADB_ORDER', @service='7500',

@network=’lan0’, @daemon='10.105.176.21:7500'



Setting Up and Starting the Alerter on Sybase SQL Server

On Sybase SQL Server the alerter mechanism is an extended stored procedure in a

dynamic link library (provided with the installation media) that is dynamically loaded into

Sybase SQL Server. Two stored procedures are available for sending messages when the

alerter is used:

• notify. Sends a TIBCO Rendezvous message to the given configuration or

configurations that one or more publishing tables have been updated.

• notifytable table_name. Sends a TIBCO Rendezvous message to the given configuration

or configurations that the given publishing table has been updated.

Before Starting

A database account must be created for running the adapter. This is typically done after

installation. See TIBCO ActiveMatrix Adapter for Database Installation for details.

Alerter Setup on Solaris

Before using the alerter you must copy the alerter shared library to the Sybase/lib directory,

add the notify and notifytable external stored procedures to the master database and set

execute permission on the procedures for the database account used by the adapter. The

name of the shared library file is adbalerter_sybase.so.

1. Open a command window and change directory to the TIB_ADADB_HOME/lib

directory. Copy the alerter library as follows:

cp adbalerter_sybase.so sybase/lib

2. Ensure that the procedures are not already defined in the master database:

isql -Usa -Ppassword

1> sp_dropextendedproc notify

2> go


2> go

1> sp_freedll "adbalerter_sybase"

2> go


1>create procedure notify

2>@agentname varchar(255),

You may need to shut down and restart your XP SERVER after copying the shared library

to the sybase/lib directory.


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

3>@service varchar(255)=’default_value’,4>@network varchar(255)=’default_value’,5>@daemon varchar(255)=’default_value’6> as external name 'adbalerter_sybase'

7>go

1>create procedure notifytable


3>@tablename varchar(255),


8>go

This example shows how to add procedures on Solaris.




1> exit

5. Add TIBCO_HOME/tibrv/lib/libtibrv.so to the system LD_LIBRARY_PATH variable.

6. Add TIBCO_HOME/tibrv/rvd/bin to the system PATH variable.

Alerter Setup on Microsoft Windows

Before using the alerter you must copy the alerter dynamic link library, add the external

stored procedures to the master database and set execute permission on the procedures for

the database account used by the adapter.

1. Open a command window and change directory to the TIB_ADADB_HOME\lib

directory. Copy the alerter library as follows:

copy adbalerter_sybase.dll \Sybase\dll

2. Ensure that the procedures are not already defined in the master database:

isql -Usa -Ppassword1> sp_dropextendedproc notify

2> go


2> go

1> sp_freedll "adbalerter_sybase"

2> go


You may need to shutdown and restart your XP SERVER after copying adbalerter_sybase.dll

to the \Sybase\dll directory.



1>create procedure notify



7>go

1>create procedure notifytable


3>@tablename varchar(255),


8>go




1> exit

5. Add TIBCO_HOME\tibrv\bin to the system PATH variable.

Using the Alerter

When using the alerter, an adapter instance must be started with polling disabled. In this

example, after adding a row in a table monitored by the adapter, the alerter procedure is

invoked and the adapter checks for updates in its publishing table. The database server

name is itaska and database name is activedb.

1. In a command window, start the adapter instance with polling disabled (set the

adb.PollingInterval value to 0 in the properties file):

adbagent --propFile propFilename

2. In another command window, insert a row into the database table being monitored by

the adapter, commit the transaction, then invoke the notify procedure:

isql -Uadb -Padb -dactivedb

1> insert into ORDER_TABLE values(406,'walnut table',9899.89)

2> go

1> execute itaska.master.dbo.notify @agentname='rvpub'

2> go

Notifying: rvpub

You can also execute the notify procedure for more than one adapter instance. Each

configuration name must be separated using a space character. For example:

1> execute itaska.master.dbo.notify @agentname='rvpub rvpub2 rvpub3'

2> go


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

The notifytable procedure can be invoked for one or more adapter instances and one

publishing table. For example:

1> execute itaska.master.dbo.notifytable

@agentname='rvpub rvpub2',@tablename='P_ORDER_TABLE'

2> go

If the database used by the adapter and master database are on the same database

server, the server prefix need not be given.

Modifying RV Configuration

The RV configuration parameters used by the alerter to connect to a remote daemon can be

modified by including the configuration parameters when invoking the store procedure.

For example,

execute master.dbo.notify @agentname='rvpub', @service='7500', @network=’lan0’, @daemon='10.105.176.21:7500'

execute master.dbo.notifytable @agentname='rvpub rvpub2', @pubtable='ADB_ORDER', @service='7500',

@network=’lan0’, @daemon='10.105.176.21:7500'


| 111

Chapter 7 Using the Request-response Service

This chapter explains the request-response service, load balancing, and Oracle REF data

type support features.

See TIBCO ActiveMatrix Adapter for Database Examples for request-response exercises.

Topics

• Introduction, page 112

• Request-response Mode, page 114

• RPC Mode, page 122

• Load Balancing, page 132

• Oracle REF Data Type Support, page 139


112 | Chapter 7 Using the Request-response Service

Introduction

Request-response operations are set up using the Request-Response Service dialog. This

dialog is described in Configuration Tab on page 85.

Using request-response semantics, client applications can send SQL statements, stored

procedures, or both on a specified subject to an adapter instance. The adapter processes

the request and returns the results in a response to the client.

1. A request may be a query to the database or any DDL or DML command to be

performed on the database. Multiple statements, procedures or both can be sent in one

message.

2. The adapter executes the statement, procedure or both. Requests within a message are

processed as a single transaction.

3. The adapter sends back the response to the Inbox, subject or response subject that was

set up by the client application. The response consists of a result code or one or more

result sets, based on the request. A response can also be an error code or error

description, if the request was not successful.

Multiple adapter instances can be configured so that any one of the configurations

receives and processes the request:


Introduction | 113

• For a single configuration, the number of threads can be configured that will be

responsible for processing application requests. See Load Balancing in a Single

Instance Using Threads on page 132 for details.

• For multiple configurations, TIBCO Rendezvous Distributed Queuing can be used to

balance the load across a number of configurations in a queue. The task will be

assigned to the least loaded member of the queue. See Load Balancing Across Adapter

Instances on page 134 for details.

Use of Quotes in Microsoft SQL Server

When constructing a request in your application that will be processed by the adapter with

a Microsoft SQL Server database, you must take care when using quotes.

For example, the following procedure is part of a request from an application. Double

quotation marks are used, which is incorrect. An error will be returned.

select @qry = "Update " + @tablename + " set ORDER_DESCRIPTION = 'UPDATE TEST'" + ", ORDER_PRICE =

10109.25"

The following procedure is the same as above, but uses single quotes. It will be correctly

processed.

select @qry = 'Update ' + @tablename + ' set ORDER_DESCRIPTION = ''UPDATE TEST'', ORDER_PRICE =

10109.25'

See Delimited Identifiers in your Microsoft SQL Server documentation for details.

The SQL statement should contain only ASCII characters.

If your SQL statements contain non-ASCII characters, convert them into a stored

procedure and invoke the procedure using custom RPC operations.



Request-response Mode

TIBCO ActiveMatrix Adapter for Database request-response mode supports the

Rendezvous, ActiveEnterprise and XML message formats.

Requests

A request can contain one or more SQL statements, stored procedures, or both to be

executed as a transaction. The text of the SQL statement follows the conventions for

ODBC SQL syntax. All SQL statements supported by the DBMS are allowed and

placeholders (represented by a question mark, ‘?’) are permitted in the SQL statement,

conforming to the ODBC rules. For performance reasons, it is recommended to use a SQL

statement. The ‘?’convention should only be used to bind binary data or call stored

procedures.

An adapter instance is configured for request-response activity as described in

Request-response Service Tabs on page 85. In so doing, the adapter listens on the subject

on which the application sends requests. The application uses TIBCO Rendezvous or the

TIBCO Adapter SDK to send a self-describing message containing a request on the agreed

subject to the adapter instance.

The following are supported:

• DDL and DML SQL statements

• The column size of the return resultset should not exceed 128

• Multiple statements or procedures in a single transaction that send a nested TIBCO

Rendezvous message

• rv_Send(), rv_SendWithReply() and rv_Rpc() calls

• TIBCO Rendezvous C, C++, and Java APIs

Requests are described in the following sections:

• TIBCO ActiveEnterprise or XML Message Request Format, page 115

• TIBCO Rendezvous Message Request Format, page 115

If rv_SendWithReply() or rv_Rpc() calls are used, the adapter sends the response to the Inbox or

subject that was set by the application for the response. Otherwise, the adapter sends the

response on the response subject that was set at configuration time.


Request-response Mode | 115

Responses

A response from the adapter to a client application has a result code and one or more result

sets. Each result set contains nested self-describing messages, each of which encodes a

result row, such as that returned from a query. A response can also return an error code and

error description if the request was not successful.

Responses are described in the following sections:

• TIBCO ActiveEnterprise or XML Message Response Format, page 118

• TIBCO Rendezvous Message Response Format, page 118

TIBCO ActiveEnterprise or XML Message Request Format

In these formats, the input class is SQL_REQUEST. The SQL_REQUEST class is

described below. Also see SQL_STATEMENT Class on page 126.

<object name="SQL_REQUEST" lastModified="1036435805361" id="503">

<assoc name="attribute">

<string name="name" value="STATEMENTS"/>

<ref name="attributeType"

value="/tibco/public/sequence/ae/class/ae/ADB/adbmetadata/sequence[SQL_STATEMENT]"/>

<string name="isKey" value="false"/>

<string name="isReadable" value="true"/>

<string name="isWriteable" value="true"/>

</assoc>


<string name="name" value="CLOSURE"/>

<ref name="attributeType" value="/tibco/public/scalar/ae/any"/>




</assoc>

<string name="family" value="ae"/>

<string name="objectType" value="class"/>

</object>

TIBCO Rendezvous Message Request Format

This is an example structure of the nested self-describing request message sent by an

application to the adapter.Request{

rv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_datarv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statementrv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statementrv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Statement. . .

}



The closure field is an optional field. If included in the request, the response returns the

same closure argument untouched, so the client application can use this information as a

means of matching requests with responses.

The value Statement is a TIBCO Rendezvous Message of the following structure:Statement{

rv_Name = “sql”, rvmsg_Type = RVMSG_STRING, rvmsg_Data = SQL_statement_with_possible_bind_variablesrv_Name = “maxrows”, rvmsg_Type = RVMSG_INT, rvmsg_Data = optional_max_number_of_rows_to_fetchrv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_datarv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_datarv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data = Bind_data. . .

}

The value Bind_data is a TIBCO Rendezvous Message with the following structure:Bind_data{

rv_Name = "position", rvmsg_Type = RVMSG_INT, rvmsg_Data = position_of_placeholder_starting_with_1_from_left_to_rightrv_Name = "column", rvmsg_Type = RVMSG_STRING, rvmsg_Data =

in_format_table-name.column-name_whose_column_type_matches_this_bound_variablerv_Name = "data", rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data}

If the position field is not specified, the order received is used.

Example TIBCO Rendezvous Message Requests

The section contains example requests that are based on SQL statements made by a client

application and sent to an adapter instance for processing.

Simple SQL Request Statement

Given that a client application submits the following SQL statement:

INSERT INTO order_table (order_id, order_description,

order_price) values (1, ‘Order 1’, 1.10)

The corresponding request could be formatted as a TIBCO Rendezvous Message similar

to the following:

{

name = “closure” value = optional_closure_argumentname = “stmt” value =

{

name = “sql” value = “INSERT INTO order_table (order_id, order_description, order_price) values (1, ‘Order 1’,

1.10)”

}

}



Bind Request Statement

Assume that a client application submits the following SQL statement, where ? is a

placeholder for an adbDateTime value:

INSERT INTO order_table (order_id, order_date) values (2, ?)

The corresponding request could be formatted as a message in TIBCO Rendezvous Message

format similar to the following:

{

name = “closure” value = optional_closure_argumentname = “stmt” value =

{

name = “sql” value = “INSERT INTO order_table (order_id, order_date) values (2, ?)”

name = “bind” value =

{

name = “order_table.order_date” type = RVMSG_STRING value = “1999-08-20 10:20:01”

}

}

}

To create a bind parameter for binary data, the actual data would be sent as an

RVMSG_OPAQUE.

Using Bind Entries

Bind entries are specific only to the stmt {} that contains them. For example, if you want to

insert three rows into REPLYTEST, you need to have three stmt {} blocks (and thus, three sets

of bind statements):

request: {

stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP"

data="1991-10-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[3 opaque bytes]}}


data="1991-11-10 12:10:10"} bind={column="REPLYTEST.BINCOL" data=[4 opaque bytes]}}


data="1991-12-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[5 opaque bytes]}}}

Not every data value sent to an SQL statement must be bound. The client can embed all

these values into the actual text of the statement instead. Embedding the values directly

into the SQL text results in better performance. However, binary values must be bound.

Types such as adbDateTime can either be bound or included in the SQL text by using the

native DBMS date conversion function.

For example, in ORACLE, you could use the TO-DATE function to enter a date:

INSERT INTO order_table (order_id, order_date) values (2,

TO_DATE(’1999-08-20 10:20:01’, ’YYYY-MM-DD HH24:MI:SS’));



TIBCO ActiveEnterprise or XML Message Response Format

In the TIBCO ActiveEnterprise Message or XML format, the input class is

SQL_BATCHRETURN. This class is described in SQL_ BATCHRETURN Class on

page 125.

TIBCO Rendezvous Message Response Format

If rv_SendWithReply() or rv_Rpc() is used to send the request, the response is sent back on the

subject or Inbox that was associated with the request.

If rv_Send() is used to send the request, because no response subject was specified with the

request, the response subject set when the adapter was configured is used. To receive a

response from the adapter, the client application must listen on the response subject.

The structure of a response message in TIBCO Rendezvous Message format is shown

below.

Reply{

rv_Name = “status” rvmsg_Type = RVMSG_INT rvmsg_Data = 0

rv_Name = “results” rvmsg_Type = RVMSG_RVMSG rvmsg_Data = Resultrv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data}

where Result is a message in TIBCO Rendezvous Message format of the following

structure:

Result{

name = “row” type = RVMSG_RVMSG value = List_of_columnsname = “row” type = RVMSG_RVMSG value = List_of_columnsname = “row” type = RVMSG_RVMSG value = List_of_columns. . .

}

where List_of_columns is a message in TIBCO Rendezvous Message format of the

following structure:

List_of_columns{

rv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_datarv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_datarv_Name = column_name, rvmsg_Type = type_of_bound_data, rvmsg_Data = value_of_bound_data. . .

}



If the request processing was not successful, the response could also return an error code

and error description as shown next:

Reply{

rv_Name = “status” rvmsg_Type = RVMSG_INT rvmsg_Data = nonzero_numberrv_Name = “sql” rvmsg_Type = RVMSG_STRING rvmsg_Data = SQL_statement_that_caused_errorrv_Name = “error” rvmsg_Type = RVMSG_STRING rvmsg_Data = error_textrv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data}

The status value is an integer specifying success or error. Possible values are:

0: ok // No error

1: noMem // Out of Memory

2: notInitialized // Object never initialized

3: typeConversion // Type conversion error

4: dbNotFound // Database not registered

5: serverError // Error reported by server

6: serverMessage // Message from server

7: vendorLib // Error in vendor's library

8: notConnected // Lost connection

9: endOfFetch // End of fetch

10: invalidUsage // invalid usage of object

11: columnNotFound // Column does not exist

12: invalidPosition // invalid positioning within

object,i.e.bounds err

13: notSupported // Unsupported feature

14: nullReference // Null reference parameter

15: notFound // Database Object not found

16: missing // Required piece of information is missing

17: noMultiReaders // This object cannot support multiple readers

18: noDeleter // This object cannot support deletions

19: noInserter // This object cannot support insertions

20: noUpdater // This object cannot support updates

21: noReader // This object cannot support readers

22: noIndex // This object cannot support indices

23: noDrop // This object cannot be dropped

24: wrongConnection // Incorrect connection was supplied

25: noPrivilege // This object cannot support privileges

26: noCursor // This object cannot support cursors

27: cantOpen // Unable to open

28: applicationError // For errors produced at the application

level

29: notReady // For future use

Example TIBCO Rendezvous Message Responses

This section has two examples. The first shows a successful query response and the

second shows an unsuccessful query response.



Query Example

As an example, assume the SQL statement, SELECT * FROM ORDER_TABLE produces the

following result:

SQL> SELECT * FROM ORDER_TABLE;

ORDER_ID ORDER_DESCRIPTION ORDER_PRICE

1 Order 1 1.00

2 Order 2 2.00

In this case, the self-describing message in TIBCO Rendezvous Message format produced

by the adapter would have the following structure:

{

name = “closure” value = optional_closure_argumentname = “status” value = 0

name = “results” value =

{

name = “row” value =

{

name = “order_id” type = RVMSG_INT value = 1

name = “order_description” type = RVMSG_STRING value = “Order 1”

name = “order_price” type = RVMSG_REAL value = 1.00

}

name = “row” value =

{

name = “order_id” type = RVMSG_INT value = 2

name = “order_description” type = RVMSG_STRING value = “Order 2”

name = “order_price” type = RVMSG_REAL value = 2.00

}

}

}

Error Example

If the request that was processed resulted in an error, the adapter returns a message

containing an error code and description as shown below. In this example, assume the

SQL statement SELECT * FROM ORDER_TABLE produced an error because there was no table

named ORDER_TABLE defined in the database:

SQL> SELECT * FROM ORDER_TABLE;

SELECT * FROM ORDER_TABLE

*

ERROR at line 1:

ORA-00942: table or view does not exist

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

{

name = “closure” value = optional_closure_argument



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.

}



RPC Mode

TIBCO ActiveMatrix Adapter for Database uses the TIBCO Adapter SDK Operations

API for RPCServer.

In TIBCO Designer, you can configure an adapter to act as an RPC (remote procedure

call) server on behalf of a client. Selecting RPC mode creates an object in the repository

describing the RPC server that the adapter instance will start.

This section presents the structure of the TIBCO Repository class objects that provide

MOperation support. Based on these class descriptions, you can create an RPC client to send

requests to the adapter in the expected structure.

For convenience, class structure is shown in XML format.

Schema Types

Two schema types can be used for the server object created in the repository. For

Standard RPC Operation, the standard request and reply object schema are pre-defined

by TIBCO ActiveMatrix Adapter for Database. This schema can be used to describe the

input and output of any database request, allowing a request/response service to process

database operations on any tables or execute any stored procedures.

In some cases, using a standard schema can make the request/reply service difficult to

integrate with third-party applications, as standard request and reply object schema do not

describe the actual input and output values of a database operation or a stored procedure.

The third-party application has to do its own parsing and mapping of the request and reply

objects. The Custom RPC Operation, which allows you to define your operations, can be

used in these situations. You can specify the stored procedure to be executed at design

time. These operation definitions are stored in the repository in a way that allows easy

integration with other applications.

One-way and Two-way Invocation

An RPC operation uses two-way invocation by default, in which it expects a reply from

the server. You can make an RPC operation use one-way invocation, where no reply is

expected by the server.

Standard RPC Operation

The repository contains descriptions of the classes and operations provided for MOperation

support.

The SQL_OPS class describes the operations that the adapter instance, acting as an RPC

server, can handle.


RPC Mode | 123

The structure of the server object is:

<servers>

<rvCmRpcServer

name = "agentNamereqreprvcmRPCServer" session = "agentNamepubreqreprvcmRvCmSession" subject = "ADB.SDK.OPERATION"

classRef = "SQL_OPS"

/>

</servers>

Two types of operations are supported, SQL_EXECUTE and SQL_BATCHEXECUTE.

SQL_EXECUTE takes a single SQL statement and processes it. SQL_BATCHEXECUTE takes a

sequence of SQL statements and processes them. The other classes, such as

SQL_STATEMENT, SQL_BIND, and SQL_RETURN, describe metadata for the input and output

parameters to the operations.

• Use SQL_BATCHEXECUTE to send one or more SQL statements in a request.

• SQL_BATCHRETRUN is the return class.

• If an error occurs while executing a statement, the adapter returns the error

immediately without executing the remaining statements.

• On Oracle only, all statements are executed within the same transaction.

SQL_OPS Class

The structure of the SQL_OPS class is:

<class

name = "SQL_OPS">

<operation

name = "SQL_EXECUTE"

returnClass = "SQL_RETURN">

<parameter name = "STATEMENT" classRef = "SQL_STATEMENT" direction = "in"> </parameter>

</operation>

<operation

name = "SQL_BATCHEXECUTE"

returnClass = "SQL_BATCHRETURN">

<parameter name = "STATEMENTS" classRef = "sequence[SQL_STATEMENT]"

direction = "in" />

</operation>

</class>

SQL_RESULTSET Class

The structure of the SQL_RESULTSET class is:



<class name = "SQL_RESULTSET">

<attribute name = "HEADER" class = "sequence[string]">

</attribute>

<attribute name = "ROWVALUES" class = "sequence[SQL_ROW]">

</attribute>

<attribute name = "OUTBINDS" class = "sequence[SQL_BIND]">

</attribute>

</class>

SQL_ROW Class

The structure of the SQL_ROW class is:

<class name = "SQL_ROW">

<attribute name = "ROW" class = "sequence[any]">

</attribute>

</class>

SQL_RETURN Class

The structure of the SQL_RETURN class is:

<object name="SQL_RETURN" lastModified="1046487158293" id="202">


<string name="name" value="STATUS"/>

<ref name="attributeType" value="/tibco/public/scalar/ae/string"/>




</assoc>


<string name="name" value="SQL"/>





</assoc>


<string name="name" value="ERROR_DESC"/>





</assoc>


<string name="name" value="CLOSURE"/>

<ref name="attributeType" value="/tibco/public/scalar/ae/any"/>


RPC Mode | 125




</assoc>


<string name="name" value="RETURNVALUE"/>

<ref name="attributeType" value="/tibco/public/class/ae/ADB/adbmetadata/SQL_RETURNVALUE"/>




</assoc>



</object>

SQL_RETURNVALUE

<object name="SQL_RETURNVALUE" lastModified="1046487158293" id="204">


<string name="name" value="OUTBINDS"/>

<ref name="attributeType" value="/tibco/public/sequence/ae/class/ae/ADB/adbmetadata/sequence[SQL_BIND]"/>




</assoc>


<string name="name" value="RESULTSETS"/>

<ref name="attributeType" value="/tibco/public/sequence/ae/class/ae/ADB/adbmetadata/sequence[SQL_RESULTSET]"/>




</assoc>



</object>

SQL_ BATCHRETURN Class

The structure of the SQL_BATCHRETURN class is:

<class name = "SQL_BATCHRETURN">

<attribute name = "STATUS" class = "string">

</attribute>

<attribute name = "RESULTSETS" class = "sequence[SQL_RESULTSET]">

</attribute>

<attribute name = "SQL" class = "string">

</attribute>

<attribute name = "ERROR_DESC" class = "string">

</attribute>



<attribute name = "CLOSURE" class = "any"

</attribute>

</class>

SQL_BIND Class

The structure of the SQL_BIND class is:

<class name = "SQL_BIND">

<attribute name = "POSITION" class = "i4">

</attribute>

<attribute name = "TYPE" class = "string">

</attribute>

<attribute name = "DATA" class = "any">

</attribute>

<attribute name = "NAME" class = "string">

</attribute>

</class>

SQL_STATEMENT Class

The structure of the SQL_STATEMENT class is:

<class name = "SQL_STATEMENT">

<attribute name = "SQL_STRING" class = "string">

</attribute>

<attribute name = "BINDS" class = "sequence[SQL_BIND]">

</attribute>

<attribute name = "CLOSURE" class = "any"

</attribute>

<attribute name = "MAXROWS" class = "i4">

</attribute>

</class>

Custom RPC Operation

When you select Use Custom Operations in the Configuration tab of the

Request-Response dialog, you can create custom schema for your operations. You can

define the call operations to be executed by the RPC server in advance. The palette

automatically generates the input and output schema for the call operation.


RPC Mode | 127

The operation takes one input class, REQUEST, which describes the input parameters and

other input options for the stored procedure execution. The operation returns a class called

REPLY, which describe the output schema of the stored procedure or any error message

the agent returns.

Table 30 Request Schema Description

Input Item

Data Type or Classname

Description

INBINDS INPUT_BINDS The input parameters of the stored procedure.

OPTIONS INPUT_OPTIONS The input options:

Option Data Type Description

MAXROW

S

Integer The maximum number of rows to retrieve.

SQL String The SQL string use to execute the stored procedure.

This string is automatically generated by the palette.

CACHE Boolean True if user want the agent to cache the statement for

performance optimization

PACKAGE String read only, uses the call operation form to modify the

package of the stored procedure.

SCHEMA String read only, uses the call operation form to modify the

package of the stored procedure.

CLOSURE Any Closure argument. The reply returns this closure argument untouched.

Table 31 Reply Schema Description

Output ItemData Type or Classname

Description

OUTBINDS OUTPUT_BINDS The output parameters of the stored procedure

RESULTSET[1..n]/RESUL

TSETS

OUTPUT_ROWS/

SQL_RESULTSET

The result set(s) returned by the stored procedure, see section

'Result Set Support' for more description

STATUS String SUCCESS if the stored procedure is executed successfully.

FAILURE if there is an error. Error details are stored in the

OPTIONS class



Resultset Support

TIBCO ActiveMatrix Adapter for Database supports multiple resultsets returned for a

stored procedure. The class generated for the resultset output depends on the schema

information provided by the JDBC driver.

• For drivers that return valid information of a resultset schema, ADB creates an output

class, named OUTPUT_ROW[1..n], for each result set. This is shown in the screen below.

OPTIONS CUSTOM_OP_OUTPUT_OP

TION

Contains the error description and the SQL statement if an error

occurred.

CLOSURE Any Closure argument obtained from the request

Table 31 Reply Schema Description (Cont’d)

Output ItemData Type or Classname

Description


RPC Mode | 129

• If a driver does not return valid information for the resultset schema, TIBCO

ActiveMatrix Adapter for Database uses the generic class SQL_RESULTSETS as the

output schema, as described in Standard RPC Operation on page 122.

Implementing Client RPC Programs

Two sample clients are provided in the TIB_ADADB_HOME\demo\operation directory:

• a sample C++ client program that you can build and change

• a sample RPC client

Creating a Custom RPC Client

There are two tasks in creating a custom RPC client:

1. Write an RPC client program using the TIBCO Adapter SDK. This task is described in

TIBCO Adapter SDK Programmer’s Guide.

DataDirect JDBC 3.3 drivers only provide valid resultset schema information for Oracle

Server version 8.1.7 or higher.



2. Create a new entry for the RPC client in the repository. This task is described below.

For more information on RPC server and client endpoint type fields, see TIBCO Designer

Palette Reference.

To create a new RPC client entry in the repository:

Perform these steps after writing the client program and configuring the adapter, as

described above. Detailed instructions for configuring a generic adapter are in TIBCO

Designer User’s Guide.

1. In TIBCO Designer, drag a Generic Adapter Configuration icon to the design panel.

2. Enter an Instance Name and an SDK AppName for the adapter.


4. In the Project panel, expand the GenericAdapterConfiguration folder and expand

the Adapter Services folder.


RPC Mode | 131

5. Drag a Request-Response Invocation Service icon to the designer panel.

6. In the Configuration tab, set the name of the service and transport type of your client

service.

7. In the Transport tab, set the message subject, quality of service, and wire format of

your client service.

If using the TIBCO Rendezvous message transport, you must use the TIBCO

ActiveEnterprise wire format.

8. In the Schema tab, set the classReference to point to the correct class schema.

— For a standard RPC schema, use the following class schema:

AESchemas/ae/ADB/adbmetadata/Classes/SQL_OPS

— For custom RPC schema, use the class schema that corresponds to the server

endpoint:

AESchemas/ae/ADB/serviceName/Classes/ADBServer_OPS

9. Click Apply.



Load Balancing

The adapter balances the load of requests coming in from applications in two ways, within

a single adapter instance and across multiple adapter instances.

Load Balancing in a Single Instance Using Threads

An adapter instance performs load balancing within itself by allowing you to specify the

number of threads that will be responsible for processing application requests. The

number of threads to be spawned is specified in TIBCO Designer for an adapter instance.

To set load balancing parameters for a configuration:

1. In the project tree panel, click the corresponding ActiveDatabase Adapter resource to

select it.

The TIBCO Designer window should look similar to the following:

2. Check the Show All Tabs checkbox.


Load Balancing | 133

3. Display the Adapter Services tab.

4. Change the value of Number Of Request-Response Service Threads as needed.


Each request-response service thread is dedicated to listening on an agreed request

subject.

1. When a request message is received by the request-response communication thread, it

enqueues it into an in-memory queue. Each database request-response thread has a

connection to the database using the user name-password combination that was

provided to the adapter.

2. When an item is enqueued by the communication thread, one of the database

request-response threads picks it up and executes the one or more SQL statements in

the message as an atomic transaction.



3. It then composes a TIBCO Rendezvous self-describing response message and sends

back a response on a response subject. If the original request was sending using

rv_SendWithReply() or rv_Rpc(), the response is sent back on the subject that was specified

by the requesting application. Otherwise, the response is sent back on the subject that

was set up at configuration time.

Load Balancing Across Adapter Instances

To achieve load balancing across adapter instances, TIBCO Rendezvous Distributed

Queueing can be used to assign each application request to exactly one adapter instance.

For example, the following diagram shows three adapter instances each connected to a

database server (not shown) that contains replicated data.

Figure 5 Request-Response Load Balancing

The adapter instances have been set up to use distributed queueing with one instance

acting as the scheduler. Only one of the three adapter instances will receive an incoming

request from an application. The scheduler will assign certified requests to the least loaded

member of the queue.

While the request message can be sent with either reliable or certified quality of service,

the response message is always sent back using the reliable quality of service.

TIBCO Messaging

Application

Adapter 4

Adapter 3

Adapter 2

Adapter 1

(Scheduler)

Request

Request

Request

RequestResponses

Distributed Queue



A queue member’s load is determined by the number of pending processes that are waiting

to be processed by the member’s database request-response thread. After the request is

processed, the processing configuration sends a response back to the requesting

application.

Configuring an Adapter Instance to use Distributed Queues

You can configure the adapter with a subscription service to use a distributed queue, then

use TIBCO Administrator Enterprise Edition to deploy multiple instances of the adapter.

The instances can be deployed on the same machine, or multiple machines. In this

scenario, each adapter instance uses the same (default) values for the distributed queue.

1. Start TIBCO Designer and create a new project.

2. Drag the ActiveDatabase Adapter Configuration icon to the design panel.

3. Configure the adapter instance with a design-time connection and ODBC DSN value.

4. Drag the ADBSubscriber icon to the design panel.

Reliable requests in a certified environment use a simpler type of load balancing. In this

example, the scheduler distributes the first reliable request to Adapter 2, the second to Adapter

3, and the third to Adapter 4 without evaluating a queue member’s load.



5. Under the Configuration tab, set Transport Type to Rendezvous and Quality of

Service to Distributed Queue. For example:

6. Configure the service with a destination table name and other settings for your

environment.

7. Click Project > Save.

8. Click Tools > Create Project EAR. Under the Configuration tab, provide a name and

file location for the EAR file.

9. Click Build Archive.

After creating the EAR file, you are ready to import it into TIBCO Administrator

Enterprise Edition and add the adapter instance multiple times to the same machine or

multiple machines.

1. Start TIBCO Administrator Enterprise Edition.

2. Select Application Management, then click the New Folder button. In Name, provide

a name for the folder and click the Save button.

3. Select the folder, then click New Application.

4. Click the Browse button and navigate to the EAR file you created in Designer. Click

the OK button.



5. In the dialog that appears, click the Save button.

6. Expand the configuration, then double-click the name.aar file.

7. Click the Add To Additional Machine button and select the machine to bind to and

click the OK button.



8. Repeat to create the number of adapter instances required for your environment. For

example, the next screen shows that three adapter instances have been added.

9. Click the Save button.

The adapter instances are ready to be deployed. After the instances are deployed, when a

message is sent to the adapter, the instance that is not busy will handle the request.


Oracle REF Data Type Support | 139

Oracle REF Data Type Support

The adapter supports the use of the REF data type (cursor) as an OUT parameter only in

an Oracle stored procedure. The adapter returns a result in the same way as it does a result

set from a SELECT query. The exact usage depends on the driver used (DataDirect

Connect or Oracle ODBC), as described below.

For example, consider the following PL/SQL procedure:

-- Create a REF cursor procedure

CREATE OR REPLACE PACKAGE ORDER_DEMO AS

TYPE OrderCurTyp IS REF CURSOR RETURN SUB_ORDER%ROWTYPE;

PROCEDURE FindOrders (price IN NUMBER, order_cv OUT OrderCurTyp);

END ORDER_DEMO;

CREATE OR REPLACE PACKAGE BODY ORDER_DEMO AS

PROCEDURE FindOrders (price IN NUMBER, order_cv OUT OrderCurTyp) IS

BEGIN

OPEN order_cv FOR SELECT * FROM SUB_ORDER where ORDER_PRICE > price;

END FindOrders;

END ORDER_DEMO;

Using DataDirect Connect Drivers

When using DataDirect Connect® (Merant) drivers, the procedure is called by leaving the

REF cursor parameter out of the procedure's call list. For example, the procedure

ORDER_DEMO.FindOrders with an input price of $1.00 can be called through the request

program with the following request:

{stmt={sql="{call ORDER_DEMO.FindOrders(?)}" bind={position=1 type="IN" data=1}}}

The REF cursor's data will be returned in the results section of the reply.

Also, ProcedureRetResults=1 must be added to the data source entry in the odbc.ini file.

Using Oracle ODBC Drivers

When using the Oracle ODBC Driver, the procedure is called by including the REF cursor

parameters in the call list but not binding them. For example, the procedure

ORDER_DEMO.FindOrders with an input price of $1.00 can be called through the request

program with the following request:

{stmt={sql="{call ORDER_DEMO.FindOrders(?, ?)}" bind={position=1 type="IN" data=1}}}

The REF cursor's data will be returned in the results section of the reply.


| 141

Chapter 8 Working With Tables

This chapter describes advanced features such as the format of a publishing table, stored

procedures and the triggers used to populate publishing tables and adapter instance

options.

Topics

• Publishing Table, page 142

• Source Table, page 148

• Exception Table, page 149

• Opaque Exception Table, page 152

• Incremental Parent-child Operation, page 154

• Database Types, page 156


142 | Chapter 8 Working With Tables

Publishing Table

Publishing tables mirror tables that you have identified for monitoring. They contain

additional columns, primarily a sequence number and delivery status, which are needed by

the adapter to detect new rows. You create a publishing table for each table you want to

activate using TIBCO Designer.

The trigger generated at design time will automatically populate the values for these

additional columns. It is not recommended that you modify these values.

In addition to a copy of the source table’s columns, the publishing table has the following

additional columns.

Table 32 Publishing Table Additional Columns (Sheet 1 of 2)

Column Name Type Description

ADB_SUBJECT VARCHAR2(255) Used to specify the subject to publish the current row. Length is

255. You can set a message subject in this field which will take

precedence over the default service subject. The adapter will

publish this row with this new message subject.

In group messaging, the group message will be sent to the subject

set for the last row of the group.

ADB_SEQUENCE NUMBER(38) Stores the monotonically increasing sequence number that

represents new rows in the publishing table. If a column with this

name exists, the number is generated automatically.

By default, the schema type is string. The adapter treats this

number as a string. This number can be larger than an integer if

the database supports it.

ADB_SET_SEQUENCE NUMBER(38) Currently not used.

ADB_TIMESTAMP DATE Time of row insertion in publishing table that is used to calculate

expiration of rows. The timestamp is generated automatically.

For Oracle databases, the timestamp includes the time zone

information.

For all new services:

Microsoft Windows platforms, the timestamp with time zone

option should be selected in the Advanced Settings tab of the

ODBC connection.

Unix platforms, the LocalTimeZoneOffset parameter in the

odbc.ini should be set to the local time zone. For example,

LocalTimeZoneOffset=+10:00.

Also the EnableTimestampWithTimeZone parameter in the

odbc.ini file should be set to 1.


Publishing Table | 143

ADB_TRACKINGID VARCHAR2(40) Tracking ID of the message.

This is automatically added to the publishing table and the

publishing schema.

If you do not want to monitor the tracking id, you can manually

remove this field from the project schema and the publishing

table

ADB_OPCODE NUMBER(38) Operation code used by an adapter instance:

1 indicates INSERT.

2 indicates UPDATE.

3 indicates DELETE.

4 indicates UPSERT. UPDATE if row exists, otherwise INSERT.

10 indicates BYPASS (See Incremental Parent-child Operation on

page 154)

If an incoming TIBCO Rendezvous message does not have an

operation code, an INSERT occurs.

ADB_UPDATE_ALL NUMBER(38) Currently not used.

ADB_REF_OBJECT VARCHAR2(64) When publish by reference object is used, contains the name of

the reference object that provides source data.

ADB_L_DELIVERY_STAT

US

CHAR(1) Delivery status of a TIBCO Rendezvous message:

P indicates pending acknowledgement.

N indicates that a new message has arrived, but has not yet been

published.

C indicates complete.

F indicates failed.

ADB_L_CMSEQUENCE NUMBER(38) Certified messaging sequence number associated with this

message.

ADB_MARK VARCHAR2(64) It is a number that is retrieved from the publication load

balancing mutex table when the service instance is started. It

represents an identifier of each adapter instance in the publication

load balancing group.

ADB_INSTANCEID VARCHAR2(200) It is the adapter instance ID configured by the user.

Table 32 Publishing Table Additional Columns (Sheet 2 of 2)




The publication table cannot contain any user-created columns where the column name

starts with ADB_. These characters are reserved for adapter use.

Removing Records from the Publication Table

An adapter instance does not remove the records from the publication table automatically,

because often that information must be retained for auditing reasons. You can use the

following command at the SQL prompt to manually remove records from the given

publishing table. The command deletes all rows where ADB_L_DELIVERY_STATUS is

C or F.

SQL> delete from publication_table_name where ADB_L_DELIVERY_STATUS = "C" or ADB_L_DELIVERY_STATUS = "F";

To automate the process, you could include this statement in a trigger.

Publication Example

The following is a listing of the SQL commands used to create a publication. The listing

can be found in the TIB_ADADB_HOME\demo\demo1\demo_database.sql file. The file shows the

stored procedure, and insert, update and delete triggers that are generated for a

publication.

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

-- TIBCO ActiveMatrix Adapter for Database

-- Demo SQL script

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

-- Spool the output of sql commands to a log file spool demo.log

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

-- Create sample tables

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

-- Publication source table

CREATE TABLE ORDER_TABLE (

ORDER_ID NUMBER PRIMARY KEY,

ORDER_DESCRIPTION VARCHAR2(128),

ORDER_PRICE NUMBER(10,3)

);

-- Create the destination table

CREATE TABLE SUB_ORDER (

ORDER_ID NUMBER PRIMARY KEY,


When publishing parent-child record or in Publish By Reference mode, if the key value is

empty (null) in the publishing table, the adapter will consider this as an error operation,

and update the failure status in the publication table by setting adb_l_delivery_status to F. The

data will not be published.



ORDER_PRICE NUMBER(10,3)

);

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

-- Setup a publication

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

CREATE TABLE PUB_ORDER (

ORDER_ID NUMBER,


ORDER_PRICE NUMBER(10,3),

ADB_SUBJECT VARCHAR2(255) NULL,

ADB_SEQUENCE INTEGER NOT NULL,

ADB_SET_SEQUENCE INTEGER NULL,

ADB_TIMESTAMP DATE NULL,

ADB_OPCODE INTEGER NOT NULL,

ADB_UPDATE_ALL INTEGER NULL,

ADB_REF_OBJECT VARCHAR2(64) NULL,

ADB_L_DELIVERY_STATUS CHAR NULL,

ADB_L_CMSEQUENCE NUMBER(38, 0) NULL

)

/

CREATE UNIQUE INDEX IDX1_PUB_ORDER ON PUB_ORDER (ADB_SEQUENCE)

/

CREATE UNIQUE INDEX IDX2_PUB_ORDER ON PUB_ORDER (ADB_L_DELIVERY_STATUS,

ADB_SEQUENCE)

/

CREATE INDEX IDX3_PUB_ORDER ON PUB_ORDER (ADB_L_CMSEQUENCE)

/

CREATE SEQUENCE PUB_ORDER_SEQ

START WITH 1

INCREMENT BY 1

NOMAXVALUE

NOCYCLE

CACHE 10

/

CREATE OR REPLACE TRIGGER TRI_PUB_ORDER AFTER INSERT OR DELETE OR UPDATE ON

ORDER_TABLE FOR EACH ROW DECLARE

updating_key_fields EXCEPTION;

BEGIN

IF INSERTING THEN

INSERT INTO PUB_ORDER VALUES (

:NEW.ORDER_ID,

:NEW.ORDER_DESCRIPTION,

:NEW.ORDER_PRICE,

NULL,

PUB_ORDER_SEQ.NEXTVAL,

0,



SYSDATE,

1,

NULL,

NULL,

'N',

-1);

END IF;

IF UPDATING THEN

IF UPDATING('ORDER_ID') THEN

RAISE updating_key_fields;

END IF;


:OLD.ORDER_ID,

:NEW.ORDER_DESCRIPTION,

:NEW.ORDER_PRICE,

NULL,


0,

SYSDATE,

2,

NULL,

NULL,

'N',

-1);

END IF;

IF DELETING THEN


:OLD.ORDER_ID,

:OLD.ORDER_DESCRIPTION,

:OLD.ORDER_PRICE,

NULL,


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

Changing the Publication Trigger to Publish a Subset of Rows

You can set up a publication to publish only a subset of the rows within a table. That is,

there may be scenarios where it is desirable to publish only if the inserted, deleted, or

updated row satisfies certain conditions. While it is possible to use the callout library to do

this additional filtering, it is simpler and more efficient to use a trigger that directly tests

whether publishing conditions are met.

For Oracle, add a when clause to a row level trigger to test for the desired conditions. For

Sybase and Microsoft SQL Server, use the if statement within a trigger body to test for the

desired conditions.

For example, you could change the demo.sql trigger described in the previous section to fire

only if the ORDER_PRICE value is $1.00 or greater:

CREATE OR REPLACE TRIGGER TRI_P_ORDER_TABLE AFTER INSERT OR UPDATE OR DELETE ON

ORDER_TABLE

FOR EACH ROW WHEN (new.ORDER_PRICE >= 1.00)

Optimizing the Publication Sequence for Oracle RAC System

To optimize the performance and to avoid out of order generation of ADB_SEQUENCE,

it is recommended that you add the ORDER option and also increase the cache size.

Consult your system administrator to confirm the impact of these changes.

CREATE SEQUENCE PUB_ORDER_SEQ

START WITH 1

INCREMENT BY 1

NOMAXVALUE

ORDER

NOCYCLE

CACHE 50



Source Table

If loop detection is enabled, the following column will be added to the source table.

If the source table contains a field ADB_TRACKINGID, it will be updated using the tracking id

of the message. If this field is not present, the tracking id field will be ignored..

The source table cannot contain any user-created columns where the column name starts

with ADB_. These characters are reserved for adapter use.

Table 33 Source Table Additional Columns


ADB_SOURCE CHAR Used for loop detection. Denotes whether the row was inserted or updated

as the result of a TIBCO Rendezvous message, rather than user

intervention.

Valid values are T or NULL.

T indicates the row is not to be published.

NULL indicates the row can be published.

ADB_TRACKINGID VARCHAR2(

40)

Tracking ID of the message.


Exception Table | 149

Exception Table

If a database restriction or failure occurs, an exception table can be configured to receive

the message. If insertion into an exception table also fails, an error message will display

and the adapter instance will terminate. You can build a TIBCO Hawk rulebase that

detects when the configuration is down and automatically restarts it when the database is

up. See TIBCO Hawk Administrator’s Guide for details about creating a rulebase.

For bulk insert operations, the agent will insert all the rows into the exception table. For

example, if the agent attempts to perform a bulk insert of 500 rows to the destination table,

and the first 300 rows are inserted successfully but the last 200 rows are unsuccessful, the

agent will insert all 500 rows to the exception table. It will then commit the operation.

(The bulk insert operation is described in Adapter Services Tab on page 43.)

In addition to destination table columns, the following columns are added to the exception

table.

Table 34 Exception Table Additional Columns


ADB_OPCODE NUMBER(38) Operation code used by the adapter:

1 indicates INSERT

2 indicates UPDATE

3 indicates DELETE

4 indicates UPDATE if row exists, otherwise INSERT.

If an incoming TIBCO Rendezvous message does not have an

operation code, an INSERT occurs.

ADB_UPDATE_ALL NUMBER(38) Currently not used.

ADB_TRACKINGID VARCHAR2(40) Tracking ID of the message. This column is the primary key.

Each exception table that is mapped to a child table is connected

to the parent’s exception table by this column

ADB_ERROR_TEXT VARCHAR2(4000) Text of the error from the database server, ODBC driver, or other

source that caused the exception.



The exception table cannot contain any user-created columns where the column name

starts with ADB_. These characters are reserved for adapter use.

Child Exception Table

In addition to child table columns, the following columns are added to a child exception

table.

ADB_ERROR_TIME DATE Timestamp of the inserted record.

For Oracle databases, the timestamp includes the time zone

information.


Microsoft Windows platforms, the timestamp with time zone

option should be selected in the Advanced Settings tab of the

ODBC connection.

Unix platforms, the LocalTimeZoneOffset parameter in the

odbc.ini should be set to the local time zone. For example,

LocalTimeZoneOffset=+10:00

Also the EnableTimestampWithTimeZone parameter in the

odbc.ini file should be set to 1.

ADB_JOIN_ID VARCHAR Joined column used to link a parent record with its child record.

ADB_JOIN_ID is generated from ADB_TRACKINGID and

concatenated with the record number in the group. A child table’s

exception table is connected to its parent’s table exception table

by ADB_JOIN_ID.

Table 34 Exception Table Additional Columns (Cont’d)


Table 35 Child Exception Table Additional Columns


ADB_ERROR_TEXT VARCHAR Text of the error from the database server, ODBC driver, or

other source that caused the exception.

ADB_ERROR_VTIME DATE Timestamp of the inserted record.

ADB_TRACKINGID VARCHAR TrackingID of the message.

ADB_JOIN_ID VARCHAR Tracking ID of the Message.


Exception Table | 151

Using an Exception Table as a Source Table

If you want to publish from an exception table and also want to use that exception table as

the source table, do not use the ADB_ERROR_TEXT or ADB_OPCODE column names. Instead,

follow these guidelines:

• Create a database view that mirrors the exception table, but rename the

ADB_ERROR_TEXT and ADB_OPCODE columns so that they do not begin with "ADB_."

• After renaming the columns, use Publish By Reference Object (see Publishing by

Reference Object, page 171) and choose your view as the reference object.



Opaque Exception Table

The subscription service uses two logical layers when processing a message. The first

layer decodes data from the message and the second layer provides the database

transaction. If an exception occurs in the first layer, the adapter logs the message to the

opaque exception table. In the second layer, if any DML command fails at any level, the

adapter rolls back this transaction and starts another transaction, inserting into exception

tables. If the insert into exception table transaction fails, the adapter then logs the message

to the opaque exception table.

The opaque exception table records the entire message into a column along with the error

message. The opaque exception table has the following columns:

Table 36 Opaque Exception Table Columns


ADB_TRACKINGID VARCHAR Tracking ID of the message.

ADB_ERROR_TEXT VARCHAR Text of the error from the database server,

ODBC driver, Adapter SDK or other source that

caused the exception.

ADB_ERROR_TIME DATE Timestamp of the inserted record.

For Oracle databases, the timestamp includes the

time zone information.


Microsoft Windows platforms, the timestamp

with time zone option should be selected in the

Advanced Settings tab of the ODBC connection.

Unix platforms, the LocalTimeZoneOffset

parameter in the odbc.ini should be set to the

local time zone. For example,

LocalTimeZoneOffset=+10:00

Also the EnableTimestampWithTimeZone

parameter in the odbc.ini file should be set to 1.

ADB_MSG BLOB Raw bytes of the message.

ADB_SUBTAB VARCHAR Destination table name.

ADB_SUBJECT VARCHAR Subscription service destination or subject.


Opaque Exception Table | 153

The ADB_SUBTAB column allows you to configure several subscription services using

only one opaque exception table in the same database schema.

ADB_TRANSPORT INT Subscription service transport type:

0 unknown

1 Rendezvous

2 JMS

Table 36 Opaque Exception Table Columns (Cont’d)




Incremental Parent-child Operation

To support incremental parent-child operations, each child row has an opcode, that is, an

extra ADB_OPCODE field that is added to the child schema. The opcode ADB_OPCODE_BYPASS

is used to bypass the current table operation. The adapter determines if the operation is an

incremental parent-child operation by checking the first level child opcode. If the first

level child opcode is not set, the adapter treats it as a complete operation. For the

subsequence child level, if the child opcode is not set, it will inherit the parent opcode.

Mixed parent-child operations are also supported. You can send a message to insert new

child rows, update other child rows, and delete other child rows for an existing

parent-child object. Following is an example of a mixed parent-child operation:

adb.key

{

RVMSG_INT 2 ^type^ 1

RVMSG_INT 2 ^pfmt^ 10

RVMSG_INT 2 ^ver^ 30

RVMSG_INT 2 êncoding^ 1

RVMSG_RVMSG 110 ^prefixList^

{

RVMSG_STRING 49 1 "/tibco/public/sequence/ae/class/ae/ADB/abc"

RVMSG_STRING 37 default "/tibco/public/class/ae/ADB/abc"

}

RVMSG_RVMSG 77 ^tracking^

{

RVMSG_STRING 30 îd^ "Gi2--4--DGMSk--s-064zzw8L-zzw"

RVMSG_STRING 22 ^1^ "adb.key"

}

RVMSG_RVMSG 1200 ^data^

{

RVMSG_STRING 8 ^class^ "S_KEYP1"

RVMSG_INT 4 ADB_OPCODE 10

RVMSG_RVMSG 480 ADB_SEQUENCE_S_KEYP2

{

RVMSG_STRING 18 ^class^ "sequence[S_KEYP2]"

RVMSG_INT 4 îdx^ 1

RVMSG_RVMSG 210 ^1^

{




{


RVMSG_INT 4 îdx^ 1

RVMSG_RVMSG 58 ^1^

{



RVMSG_REAL 8 A 1

RVMSG_STRING 2 B "a"

RVMSG_REAL 8 C 4


Incremental Parent-child Operation | 155

}

RVMSG_RVMSG 58 ^2^

{



RVMSG_REAL 8 A 1


RVMSG_REAL 8 C 4

}

}

}

RVMSG_RVMSG 210 ^2^

{



RVMSG_REAL 8 A 2


RVMSG_REAL 8 C 4


{


RVMSG_INT 4 ^idx^ 1

RVMSG_RVMSG 58 ^1^

{


RVMSG_REAL 8 A 2


RVMSG_REAL 8 C 4

}

}

}

}

}

}

When the adapter receives this message, it performs the following database operations in

sequence:

1. Bypass the parent table operation

2. Bypass first row operation on child table S_KEYP2

3. UPDATE S_KEYP3 set B = 'a', C = 4 where A = 1;

4. DELETE FROM S_KEYP3 where A = 1;

5. INSERT INTO S_KEYP2 (A, B, C) values (2, 'a', 4);

6. INSERT INTO S_KEYP3 (A, B, C) values (2, 'a', 4);



Database Types

The database data types listed in this section are supported.

Oracle

The following Oracle data types are supported:

The following ANSI data types in Oracle are supported:

• CHAR • TIMESTAMP

• DATE • RAW

• LONG • VARCHAR2

• LONG RAW • CLOB

• NUMBER • BLOB

• TIMESTAMP WITH

TIMEZONE

• TIMESTAMP

WITH LOCAL

TIMEZONE

• NCHAR • NVARCHAR2

• DECIMAL • NCLOB

• XMLType

• DOUBLE PRECISION • INTEGER

• FLOAT • SMALLINT

• INT • REAL


Database Types | 157

SQL Server

The following SQL Server data types are supported:

Sybase and Sybase Adaptive Server Anywhere

The following Sybase data types are supported:

DB2

The following DB2 data types are supported:

• BIGINT • INT • SMALLINT

• BINARY • MONEY • SMALLMONEY

• BIT • NCHAR • TEXT (publish by

reference only)

• CHAR • NTEXT • TIMESTAMP

• DATETIME • NUMERIC • TINYINT

• DECIMAL • NVARCHAR • UNIQUEIDENTIFIER

• FLOAT • REAL • VARBINARY

• IMAGE (Publish by

reference only)

• SMALLDATETIME • VARCHAR

• BINARY • INT • TEXT

• BIT • MONEY • TINYINT

• CHAR • NUMERIC • VARCHAR

• DATETIME • REAL • VARBINARY

• DECIMAL • SMALLDATETIME • BIGINT

• FLOAT • SMALLINT • NCHAR

• IMAGE (Publish by

reference only)

• SMALLMONEY • NVARCHAR

• CHARACTER • NUMERIC

• DECIMAL • REAL

• DOUBLE PRECISION • SMALLINT

• FLOAT • TIMESTAMP

• INTEGER • VARCHAR

• LONG VARGRAPHIC • LONG VARCHAR



MySQL

The following MySQL data types are supported:

Teradata

The following Teradata data types are supported:

• DATE • TIME

• BIGINT • CLOB

• BLOB • CHAR

• DOUBLE

• BLOB • DATE

• LONGBLOB • TIMESTAMP

• MEDIUMBLOB • TIME

• TINYBLOB • YEAR

• BIT • VARBINARY

• BIGINT • ENUM

• MEDIUMINT • SET

• TINYINT • TEXT

• SMALLINT • LONGTEXT

• INT • MEDIUMTEXT

• CHAR • TINYTEXT

• VARCHAR • FLOAT

• BINARY • DECIMAL

• BOOL • DOUBLE

• DATETIME

• BYTE • CHAR(n)

• BYTEINT • VARCHAR(n)

• DECIMAL(n,p) • VARBYTE

• SMALLINT • LONG VARCHAR

• INTEGER • DATE

• NUMERIC(n,p) • TIME(n)


Database Types | 159

Mapping to Database Types

The adapter converts values fetched from the database to types supported by the wire

format. Similarly, data fields received in a message must be converted to meaningful

database types before being stored.

The following table shows the mapping used by the adapter for such conversion.

• FLOAT(n) • TIME(n) WITH TIME

ZONE

• REAL • TIMESTAMP(n)

• DOUBLE PRECISION • TIMESTAMP(n) WITH

TIME ZONE

Table 37 Mapping to Database Types

ODBC TypeTIBCO ActiveEnterprise Type

TIBCO Rendezvous Message Type

SQL_CHAR

SQL_VARCHAR

SQL_LONGVARCHAR

string RVMSG_STRING

SQL_SMALLINT

SQL_INTEGER

i4 RVMSG_INT

SQL_REAL

SQL_DOUBLE

SQL_FLOAT

SQL_DECIMAL

SQL_NUMERIC

r8 RVMSG_REAL

SQL_BINARY

SQL_VARBINARY

SQL_LONGVARBINARY

binary RVMSG_OPAQUE

SQL_TIMESTAMP dateTime RVMSG_DATETIME


| 161

Chapter 9 Advanced Features

Topics

• Subject and Destination Names, page 163

• Preregistering a Certified Subscriber, page 167

• Changing the Location of the Ledger File, page 169

• Sending Messages to an Adapter Instance, page 170

• Publishing by Reference Object, page 171

• User Callout Library, page 179

• Unique Connection Identifier for Oracle Databases, page 185

• Publishing in a Commitment Controlled Environment, page 186

• Using the Adapter with a Revision Control System, page 188

• Using a Log File for an Adapter Instance, page 189

• Using Database Deployment and Cleanup Scripts, page 194

• Changing the SQL Statement Terminator (DB2 for z/OS Only), page 197

• Fault Tolerance, page 198

• SSL Data Encryption using DataDirect ODBC Drivers, page 200

• OS Authentication, page 201

• Query Timeout, page 202

• Working with Multi-File Format Projects, page 203

• Subscriber Reply Sender, page 204

• Subscriber Pre-commit Stored Procedure Call, page 205

• JMS Durable Subscriber Name, page 206

• Runtime Schema, page 207

• Runtime Table Schema Configuration, page 208

• Group Message Transaction, page 209

• Load Balancing and Multithreading, page 210


162 | Chapter 9 Advanced Features

• Compressing JMS Messages, page 219

• Configuring RVCMQ Backlog Size, page 220


Subject and Destination Names | 163

Subject and Destination Names

An adapter instance sends and receives messages using subject names when using the

TIBCO Rendezvous transport type, and destination names when using the JMS transport

type. Both subject and destination names are structured strings of alphanumeric characters

divided into elements by the dot (.) character. For example, Tibco.Tsi and News.Sports.Baseball

are valid subject and destination names.

Default subject or destination names are provided in TIBCO Designer. You can change

these default values to specify a custom subject or destination name. A default subject or

destination, depending on which transport type you choose to configure, is created each

time an adapter service is created.

The following are restrictions on subject names and destination names:

• Length of subject and destination names

— Subject names are limited to a total length of 255 characters (including the dot

delimiters). Even though TIBCO Rendezvous has a 255-character subject length

limit, it is very unlikely that applications will need to use the full length. If you want

to run an adapter instance against Microsoft SQL Server, you must design your

subject space to conform to the length restrictions. There can be at most 100

elements in a subject name. The maximum element length is 127 characters.

— Destination names are limited to a total length of 249 characters. Even though JMS

has a 249-character destination length limit, some of that length is reserved for

internal use. The destination space must be designed to conform to the length

restrictions. There can be at most 64 elements in a destination name. The maximum

element length is 127 characters. Dot separators are not included in element length.

• Wildcard characters

The asterisk (*) and greater than (>) are wildcard characters that can be used when

specifying subject names or destination names.

For example, if messages are published on the tsi.sales.sports and tsi.sales.clothing subjects

and your subscriber adapter listens on the tsi.sales.* subject, the configuration will get

messages sent on both subjects. This feature also applies to destination names.

• Reserved underscore (_)

Subject or destination names beginning with underscore (_) are reserved. Application

programs cannot send subjects or destinations with an underscore as the first character

of the first element, however, _INBOX and _LOCAL are exceptions for subject names,

and _INBOX is an exception for destination names. It is also recommended that you do

not use tabs, spaces, or any unprintable character.

An underscore can be used elsewhere in subject or destination names. Subject names

are case sensitive.



• Empty strings

Empty strings ("") are not permitted.

• Dot character

The dot characer cannot be incorporated into an element by by using an escape

sequence.

See TIBCO Rendezvous Concepts for a full explanation of subject names and TIBCO

Enterprise Message Service User’s Guide for destination names.

Parameterized Subject or Destination Names

During the usage of TIBCO ActiveMatrix Adapter for Database, a subject name can be

created from one or more columns in a publishing table when using the TIBCO

Rendezvous transport type, and a destination name can be created when using the JMS

transport type. A subject or destination created this way is known as a parameterized

subject or destination. For example, you can use TIBCO Designer to define a publication

subject as MYSUBJECT.$COLUMN1.$COLUMN2, where COLUMN1 and COLUMN2 are names of

columns in the publishing table. For example:

TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION.

On publication, a subject or destination is created from the contents of those columns.

This allows receiving applications to filter publications based on the values of certain

fields. Parameterized subject or destination names are supported with certified or reliable

delivery.

Parameterized Subject and Destination Name Restrictions

The following are restrictions on parameterized subject names and destination names:

• Length of parameterized subject and destination names

— A TIBCO Rendezvous parameterized subject name can be at most 255 characters

in length, with each component no more than127 characters.

— A JMS parameterized destination name can be at most 249 characters in length,

with each component no more than 127 characters.

In the previous example, if the ORDER_DESCRIPTION column contains a description

value that is longer than 127 characters, the parameter name $ORDER_DESCRIPTION is

used as the subject or destination in place of the description value.

• Wildcard characters

The asterisk (*) or greater than (>) characters, or empty strings should not be used as

attribute values (VARCHAR, CHAR) in a column that is part of a parameterized

subject or destination. Doing so makes the subject or destination invalid.


Subject and Destination Names | 165

For example, if the TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION parameterized subject

or destination name is defined and the following values are inserted into

ORDER_TABLE:

insert into ORDER_TABLE values(111,'*',88.81);

and the following values are inserted into the ORDER_DESCRIPTION table:

insert into ORDER_DESCRIPTION TABLE values(112,'>',99.91);

the publisher would return an error.

• Data type restrictions

— Do not use columns that contain Date types as part of a parameterized subject or

destination. Date values are likely to contain characters such as dashes and spaces

that can cause problems when used as part of a subject or destination.

— Do not use columns that contain binary types as part of a parameterized subject or

destination.

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

parameterized subject or destination. Doing so makes the subject or destination

invalid.

• Column name

Each element cannot represent more than one column. For example,

MYSUBJECT.$COLUMN1$COLUMN2 is an invalid parameterized subject name.

• Group messaging

The group messaging feature is not supported with parameterized subjects or

destinations. An error message will display and the adapter will automatically disable

the group messaging feature for the publisher. For example, if the TIBCO Rendezvous

transport type is used, the error message will be:

Cannot use parameterized subject with group Publishing. Disable group publishing.



• Pre-registration

Pre-registration in the adapter can not work when a parameterized subject or

destination is used.


Preregistering a Certified Subscriber | 167

Preregistering a Certified Subscriber

You can add one or more certified subscribers, or listeners, for a publisher adapter that

sends messages on subjects using the RVCM quality of service. The name of the

subscriber is added to the publisher adapter’s preregistered list. The subscriber can be a

TIBCO ActiveMatrix Adapter for Database subscriber, or any other TIBCO Rendezvous

subscriber.

A subscriber adapter on the preregister list is certified to receive all messages sent on the

specified subject using the RVCM quality of service. If a subscriber is not preregistered, it

may miss one or more of the initial messages sent by the publisher adapter.

To preregister a certified subscriber in TIBCO Designer:

1. In the Project panel, under the publisher adapter, expand Advanced > Sessions >

adbadapterInstanceNamervcmRvCmSession endpoint object.

2. Click the publisher endpoint in the Design panel.

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

Preregistration will not work when parametrized subjects are used.



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.



Changing the Location of the Ledger File | 169

Changing the Location of the Ledger File

The ledger file provides temporary storage for published messages that are sent by a

publisher adapter using the TIBCO Rendezvous certified messaging quality of service.

Each message is held in the ledger until an acknowledgement is received from the

subscriber that the message has been consumed. If there are many subscribers, the ledger

file can grow to a substantial size. In this case, it might be preferable to store the ledger

file in a directory other than the default directory (which is TIB_ADADB_HOME/ledger).

To change the location of the ledger file in TIBCO Designer:

1. In the project tree panel, navigate to the open the Advanced > Sessions >

adbadapterInstanceNamervcmRvCmSession object, as shown in the previous

section, Preregistering a Certified Subscriber.

2. Edit the Ledger File value to point to the new ledger file location.

In the following example the name of the ledger file has been changed to

adbdemo2pubrvcm.ldg, and it will be generated in the directory in which you run the

adapter instance.

When the adapter instance is restarted, it writes the ledger file to the new location. For

more information on using TIBCO Designer, see TIBCO Designer User’s Guide.



Sending Messages to an Adapter Instance

When TIBCO ActiveMatrix Adapter for Database publishes messages including datetime

data, the wire format is handled implicitly since both publisher and subscriber use the

same format.

In many scenarios, however, a separate product acts as the publisher, which means that

you must explicitly specify the wire format. For example, an adapter instance might

subscribe to messages published by another TIBCO ActiveEnterprise product, such as

TIBCO ActiveMatrix BusinessWorks, after some transformation has been performed.

Messages containing datetime data sent to TIBCO ActiveMatrix Adapter for Database

adapters must have that data in a string format. If it is in a different format, the TIBCO

ActiveMatrix Adapter for Database adapter will not be able to process the date values.

Formatting dates as strings allows the adapter to handle date values outside the range

allowed by RVMSG_DATETIME, January 1, 1970 to January 1, 2034.

The format used by the adbDateTime metadata class is described below.

adbDateTime Object

To view the structure of the adbDateTime class, from the project tree panel, navigate to

AESchemas > ae > ADB > adbmetadata > Classes > adbDateTime > dateTime

The input is a string value with one of the following formats:

yyyy-mm-dd

yyyy-mm-dd hh:mm:ss.xxx

where xxx represents the millisecond value.

Do not change any adbDateTime object information in this screen. Use this information to

determine how to format the third-party subscriber date value.

Timezone values are not supported.

The adapter will return an error when the input data contains timezone information. The

timezone information can be parsed using the TIBCO BusinessWorks XPath functionality

before passing it to the adapter.


Publishing by Reference Object | 171

Publishing by Reference Object

When source data is stored in a view or other database object, you can publish this data

using the publish by reference object feature. Publishing by reference object is an

extension of the publish by reference feature. For a description of publishing by reference,

see TIBCO ActiveMatrix Adapter for Database Concepts.

In both cases, only key values from the source table are stored in the publishing table. The

difference when publishing by reference object is when a row changes in the source table

and the associated trigger fires, the adapter fetches data from the reference object, rather

than the source table. The name of the reference object is stored in an ADB_REF_OBJECT

column in the publishing table. For a description of this column, see Publishing Table on

page 142. Publishing by reference object is recommended when a view provides the most

efficient access to source data, for example when many levels of nesting exist between a

parent and child table.

To Configure a Publisher Adapter to Publish Data by Reference Object:

1. Drag the ActiveDatabase Adapter Configuration icon to the design panel or select

the resource in the project panel.

2. Drag a Publication Service icon to the design panel.

3. To add a source table for a publisher adapter, do the following in the Tables tab:

a. Click the Add Table icon. The Add Table dialog displays.

b. Select a source table from the list and click the OK button.

If parent-child relationships are used, follow the steps under Adding Child Tables on

page 65 to add child tables.

You must explicitly designate a key column or substitute key column for the reference

object, since a reference object has no external designation of the key column.

4. Specify the following options in the Publisher Options tab:

Storage Mode — From the drop-down list, select Publish by Reference.

Publishing Table — Type the table name to use for storage. A common practice is to

use the source table name prefixed by P_.

Referred Object — Type the name of the view or other database object to select source

data from. To select from a list of tables in the current user schema, click the Add

button. To select an object from a different schema, select Add From.

Update Mode — Select the method for updating tables from the drop-down list.

Choose Update to update a row in the destination table only if the row exists. Choose



Upsert to update a row in the destination table if the row exists and, if no such row

exists, perform an insert.


Designating the Key Column

To designate a column of the reference object as the key:

1. In the TIBCO Designer project tree panel, navigate to AESchemas > ae > ADB >

adapter_instance > classes > ref_object > key_column. The TIBCO Designer window

should look similar to the following:

2. In the Configuration tab, click the Key Field checkbox to select it.


Changing Repository Objects for Parent-child Relationships

If your publication service includes parent-child relationships, you must also add a

sequence and association to the metadata stored in the repository. These tasks are

described in the following sections.



Adding a Sequence

To add a sequence:


adapter_instance > Classes > reference_object.

2. Drag a Generic Sequence icon from the Palette panel to the Design panel to add it to

the reference object class. The TIBCO Designer window should look similar to the

following:

3. In the Name field, type ADB_SEQUENCE_child_table_name.



4. In the Select Sequence field, click the Browse button. The Select Resource dialog

displays:

5. Click the name of the sequence that represents the child table for the publication

service, for example, sequence[ORDER_DETAILS].

6. Click the OK button.

7. In TIBCO Designer, click the Apply button. The sequence is added to the metadata

for the reference object.

Adding an Association

To add an association:


adapter_instance > Associations.

Several associations could display, at least one for the parent table to the child table on

the publisher side, and another for the destination parent table to the child table on the

subscriber side.



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.


5. In the project tree panel, double-click the new association name to expand it.



6. In the Project panel, click Left Association to select it.

7. Enter a Role Name value that contains the reference object name. For example,

roleORDER_TABLE.



8. In the Endpoint Class field, click the Browse icon. Navigate to the class that

represents the reference object, in this case ORDER_TABLE, and click the OK button.

9. In TIBCO Designer, click the Apply button.

Example

In the following example, the publisher adapter is configured to publish source data from

the CUSTOMER table and its child table, EXTERNAL_ORDER_DETAILS. The relevant key

columns are CUST_ID and ORDER_ID.



The publishing table is created with necessary adapter fields, as well as CUST_ID and

ORDER_ID fields. When a row in CUSTOMER is modified, the trigger fires, populating fields

and copying the CUST_ID and ORDER_ID values, as well as the name of the reference object,

ORDER_VIEW, to the publishing table. When the adapter polls the publishing table, it detects

the new row. The adapter then selects the order and customer data from ORDER_VIEW, using

the CUST_ID and ORDER_ID values along with the view name found in the publishing table.

Then the message is published.

Table to Record Sequence Numbers (DB2 on iSeries)

The palette will attempt to create the following table (if it does not exist) to record

sequence numbers:

CREATE TABLE library.ADB_SEQTAB (PUB_TABLE VARCHAR(64) NOT NULL,

ADB_SEQ NUMERIC(20),

constraint ADB.ADB_SEQTAB_KEY primary key (PUB_TABLE))

The table must be journalled.

You can create this table or if journalling is automatically turned on, the palette will create

the table automatically.


User Callout Library | 179

User Callout Library

The user callout shared library allows the transformation of a message that the adapter

publishes into a structure that you want to be published. The shared library can be

customized to apply limited transformations to outgoing and incoming messages.

To use the callout library, the TIBCO Adapter SDK must be installed because the callout

library uses SDK include files and links with SDK libraries. Additionally, you must use

the same TIBCO Adapter SDK version that your adapter instance is using.

If a message is modified before it is sent by a publisher adapter, all subscribers will

receive the modified message. If a message is modified before it is received by a

subscriber adapter, only that adapter will get the modified message.

For example, at the publisher adapter, a message can be modified to have a field added, or

publish an empty message if a certain criteria is met. At the subscriber adapter a message

can be modified to be written to the database or not, based on a filter, or have the subject

name inserted into the table.

Before a message is sent or received, the adapter checks the callout library. If the callout

library has not been modified, the message is passed back to the adapter unchanged. If the

callout library has been modified, the message is passed back to the adapter with the

modification. After receiving a modified message from the callout library, the adapter

instance sends or consumes the message like any other message.

• The altermsg.cpp source file must be edited with your custom code.

• The callout library must be rebuilt for your platform.

The source code is included in your installation media in the

TIB_ADADB_HOME\demo\altermsg directory.

Using the alterMsgPub and alterMsgSub Functions

Two functions are available in the altermsg.cpp source file for creating callouts, alterMsgPub() to

create a callout for a publisher and alterMsgSub() to create a callout for a subscriber. Two

examples are included in the altermsg.cpp file. You can change the examples for your needs,

or write new code in the file. The first example appends a new field to a message. The

second example works in conjunction with the demo and returns an empty message if the

message meets a certain criteria.

If you send or receive messages in the TIBCO Rendezvous Message wire format, the

TIBCO Rendezvous Message APIs cannot be used to directly alter those messages.

Instead, you will receive an MTree to which various functions can be applied to view or

traverse the TIBCO Rendezvous message. If you must change the message, create a new

message and pass it back to the adapter using the newmsg argument.



The alterMsgPub() and alterMsgSub() functions are the entry points into the callout library.

These two function names and their signatures must not be changed.

The alterMsgPub and alterMsgSub functions allow you to alter messages in the TIBCO

ActiveEnterprise Message, TIBCO Rendezvous Message, and XML wire formats. The

function signatures are:

alterMsgPub(char * subj,

const MTree *msg,

MTree **newmsg,

MInstance *pInst,

MApp *pMapp,

MMessageFormat dataformat);

alterMsgSub(char * subj,

const MTree *msg,

MTree **newmsg,

MInstance *pInst,

MApp *pMapp,


Both functions share the same set of parameters. However, several parameters are specific

to a particular wire format.

The following table contains parameter descriptions and a column for each format. If the

R column contains an X, use the parameter for TIBCO Rendezvous Message wire format.

If the M column contains an X, use the parameter for TIBCO ActiveEnterprise Message or

XML wire format. Otherwise, leave the value as NULL.

Table 38 Wire Format Parameters and Descriptions

Parameter R M Description

subj X X Subject on which the message is sent or received.

msg X MTree containing the message to send or receive.

newmsg X New MTree user creates if msg must be altered.

pInst X MInstance of the message. Alter directly if necessary.

pMapp X TIBCO Adapter SDK MApp structure for this MInstance.



When sending or receiving messages in the TIBCO ActiveEnterprise Message wire

format, you must use the pInst argument to change the message.

Using the adbPreCommit Function

The adbPreCommit function allows you to perform a custom operation, such as invoking a

stored procedure or sending a TIBCO Rendezvous message, just before the transaction is

committed. This function is called by the subscriber after all inserts, updates and delete

operations have been performed on both parent and child tables.

The function signature is:

adbPreCommit(SQLHDBC connectHandle,

MApp *pMapp,

MInstance *pInst,

MTree *pTree,


The following table contains parameter descriptions.

dataformat X X The data format of the message.

Valid values are:

M_RV_MESSAGE_FORMAT

M_AERV_MESSAGE_FORMAT

M_XMLJMS_MESSAGE_FORMAT

M_XMLRV_MESSAGE_FORMAT

Check TIBCO Adapter For SDK documentation for details

of these value.

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

Parameter R M Description

Table 39 adbPreCommit Parameter Descriptions

ParameterTIBCO Rendezvous Format

TIBCO ActiveEnterprise Format

Description

connectHandle X X The database connection handle.

pMapp X X TIBCO Adapter SDK MApp structure for this

MInstance.

pInst X MInstance of the message.

pTree X MTree containing the message.



Building the Callout Library

The callout library is build with TIBCO Adapter SDK and TIBCO Rendezvous software.

For compiler requirements and instructions, see the TIBCO Adapter for SDK guide.

Building the Callout Library on Microsoft Windows

1. Using Visual C++, create a new workspace and insert a new project into the

workspace.

2. In the new project, open the file:

TIB_ADADB_HOME\demo\altermsg\altermsg.dsp

dataformat X X The data format of the message.

Valid values are:

M_RV_MESSAGE_FORMAT

M_AERV_MESSAGE_FORMAT

M_XMLJMS_MESSAGE_FORMAT

M_XMLRV_MESSAGE_FORMAT

Check TIBCO Adapter For SDK documentation

for details of these value.

Table 39 adbPreCommit Parameter Descriptions (Cont’d)

ParameterTIBCO Rendezvous Format

TIBCO ActiveEnterprise Format

Description

If an adapter is configured to use the adb.subBatchCommitTimeout or adb.subBatchCommitSize

options, the custom operation is performed once for each message received. However, the

entire transaction is not committed until the size or time-out values are reached. Adapter

instances that use the bulk-insert-size option cannot use adbPreCommit.

For more information on these options, see Appendix C, Adapter Properties File, on

page 329.



3. Select Project > Settings. In the Project Settings dialog box:

a. As shown next, select the C/C++ tab. In the Category drop-down list, select

Preprocessor. In the Additional Include Directories field type the path to the

TIBCO Rendezvous include directory.

b. As shown next, select the Link tab. In the Category drop-down list, select Input.

In the Additional Library Path field, enter the path to the TIBCO Rendezvous

library directory.

4. Select Build > Build adbaltermsg.dll to create the library.



5. After building the library, change to the TIB_ADADB_HOME/lib directory.

a. Make a backup copy of the existing adbaltermsg.dll library.

b. Copy the new adbaltermsg.dll library into the bin directory.

Building the Callout Library on UNIX

1. Using a text editor open the MakeFile and set the RV_Home environment variable. For

example, for Solaris 8:

RV_HOME=/usr/tibco/tibrv

2. Using a text editor open the MakeFile and set the SDK_Home environment variable. For

example:

SDK_HOME=/usr/tibco/adapter/sdk/5.6

3. Set the command to invoke your compiler. For example:

CC= CC

4. Set the options to be passed to your compiler. For example:

DEBUG=-g

OPT=-O4

5. Save the MakeFile and execute:

% make libadbaltermsg.so

6. After building the library, change to the TIB_ADADB_HOME\lib directory.

a. Make a backup copy of the existing libadbaltermsg.so library.

b. Copy the new libadbaltermsg.so library into the lib directory.


Unique Connection Identifier for Oracle Databases | 185

Unique Connection Identifier for Oracle Databases

Within each adapter instance, the adapter typically creates multiple database connections

or sessions. Each connection has a different responsibility (such as selecting from the

publishing table or inserting into the destination table) and each is identified using a

unique connection identifier.

The unique identifier added to each session allows a database administrator to monitor the

adapter’s database activity from Oracle by being able to identify what each database

connection is doing. The Oracle DBA can query the CLIENT_INFO column of V$SESSION to

identify each Oracle connection the adapter is using. The identifiers for each service are:

• InstanceId.ADBPubPolling (publication service polling connection)

• InstanceId.ADBPubUpdate (publication service update connection)

• InstanceId.ADBPubConfirm (publication service confirm connection)

• InstanceId.ADBSubscriber (subscription service connection)

• InstanceId.ADBRequestReply.n (request-response service connection where n is the thread

ID)



Publishing in a Commitment Controlled Environment

You can enable the adapter to publish messages in a commitment controlled environment.

In its standard functionality the adapter generates and attaches database triggers to an

application table that is the source for publishing data. A trigger program is activated on a

database event on the source table (Insert, Update, Delete) and the trigger program uses

the source table data to reflect the database event change on a publishing table.

Therefore, if the source table is being accessed by an application under commitment

control, it is critical from a database integrity standpoint that the trigger program be part of

the same commitment cycle.

To publish messages in a commitment controlled environment:

These steps assume that the trigger program is being generated by the palette in the RPG

ILE language.

1. Once the adapter is configured and saved in TIBCO Designer, the trigger programs

will be compiled and attached to the source table. Log on to the iSeries system using a

profile that has *PGMR rights to the library and source file where the trigger program

is created. The trigger program is always created in a source file called TIBCOSRC that

is in a library representing the DB2 collection.

2. Edit the trigger program member in the TIBCOSRC file by adding the keyword 'Commit'

on the F-Spec for the publishing table. An example is given below.

FP_EMPL O E Disk Rename(P_EMPL:Pub_Record)

F UsrOpn

F Commit

Make sure that the application program that is accessing the source table is running

with commitment control enabled. Otherwise, the trigger program will encounter a

runtime error with this keyword.

3. After editing the trigger program member, save and compile it with options

DFTACTGRP(*NO) and ACTGRP(*CALLER). These options ensure that the trigger program

runs as part of the calling application program's commitment cycle. The trigger

program will run in the application program's activation group. Any database updates

done by the trigger program will be done or undone by a Commit or Rollback issued

by the application program, thus ensuring database integrity.

4. To have the trigger program run under commitment control, the publishing table

(listed in the trigger program) must be journalized. This can be done by using the

This feature applies only to DB2 on iSeries.


Publishing in a Commitment Controlled Environment | 187

iSeries command STRJRNPF. The journal that is being used to log changes to the source

table can be used for the publishing table as well.



Using the Adapter with a Revision Control System

TIBCO Designer supports revision control systems such as MicroSoft Visual SourceSafe

and Perforce. If you are using a revision control system, you must manually add some

configured resources to the revision control system and check in the resources when

completing the instance configuration.

As part of service configuration, the adapter creates schema files in project_root >

AESchemas > ae > adadb. For example, if you configure a service in an adapter

configuration instance1, the following files are created:

project_root > AESchemas > ae > adadb > Instance1.aeschemaproject_root > AESchemas > ae > adadb > Instance1 > businessObjects.aeschema

When the project is saved and a revision control system has been specified, the adapter

displays a warning that additional files were created and should be added to the revision

control system. This warning appears only when the files are created for the first time. The

warning displays a Go To Resource button that helps in navigating to the resource. You

should select Multi-User > Add Resources to RCS to add these files to the revision

control system.

For information about how to use the Multi-User feature in TIBCO Designer, see TIBCO

Designer User’s Guide.

Copy, Cut, Paste and Move Operations

To successfully copy and paste a service from adapter instance1 to instance2, the adapter

configuration and schema files for the instance2 must be checked out.

To successfully cut and paste a service from adapter instance1 to instance2, the adapter

configuration and schema files for both instance1 and instance2 must be checked out.

To successfully move a service from adapter instance1 to instance2, the adapter

configuration and schema files for both instance1 and instance2 must be checked out.

Regeneration When Moving, Copying and Pasting

• Default subjects are not regenerated to reflect the new instance name when a service is

moved.

• Manually changed certified messaging and certified messaging queue ledger file

names are regenerated to defaults when a service is moved, or copied and pasted to a

new instance.

• If a service associated with a custom session is moved, or copied and pasted, the

custom session is not moved, or copied and pasted. The session is regenerated as a

default session.


Using a Log File for an Adapter Instance | 189

Using a Log File for an Adapter Instance

By default all error, warning and information messages are printed in the console window

in which the configuration was started and to a default log file. The log file can be located

anywhere on your file system.

The adapter will trace to whatever sink is present in your adapter instance configuration. If

you have the default sinks of stdioSink and fileSink, the adapter will write to both the file and

stdout.

Fine-tuning Tracing Attributes

The tracing facility allows you to fine-tune where and what different types of information

are sent.

To access tracing attributes for an adapter instance:

1. In the Project tree panel, click the corresponding ActiveDatabase Adapter resource to

select it.

Only errors that originate in the adapter instance itself are logged in the log file. Errors

from other sources, for example TIBCO Rendezvous APIs or TIBCO Adapter SDK APIs,

are not logged to a log file, but are printed to the console window where the configuration

started.




2. Display the Logging Tab, as shown below.

The Log to Standard I/O checkbox is checked so that trace information can be written to

the console window where the adapter instance was started. The log file is generated in the

start directory unless specified otherwise in the properties file.

To disable file tracing for the adapter instance, delete this file name and click the Apply

button.



The following checkboxes control the level of trace information that is captured:

• Log Info Messages—Capture error and warning information.

• Log Debug Messages—Capture all available information.

• Log Warning Messages—Capture warning information only.

• Log Error Messages—Capture error information only.

Log File Size

When a log file name is specified in the Logging tab, the adapter does the following:

1. Creates a file with no extension, using the file name specified in TIBCO Designer.

2. Redirects all trace statements generated by this configuration to that file until it

reaches the default file size of 30 KB.

3. When this file size is reached (that is, as soon as the file is greater than or equal to the

limit), renames the current file to file.1 and creates a new file with no extension.

Note that the log file can be slightly larger than the limit because the new file is only

created after the limit has been reached.

4. Repeats this process of rolling log files and renaming files each time a new file is

generated, until 3 log files exist.

Using Advanced Logging Features

The example in this section shows how to change default log file attributes in TIBCO

Designer.

To access advanced logging features in TIBCO Designer:

1. With the Logging tab selected in the Configuration panel, click the Use Advanced

Logging checkbox.

With these default settings, the adapter instance overwrites the oldest file after 3 files have

been created and the last file reaches 3 KB. For instructions on changing the default

settings, see the next section.



2. Click the Apply button. The following information displays:

3. In the Project panel, navigate to adapter_instance_name > Advanced > Log Sinks > fileSink.

The TIBCO Designer window looks similar to the following:

File Limit (bytes)

Sets the maximum size of a log file. A global variable can be used for this field.



File Count

Specifies the maximum number of log files that are created for this adapter instance. A

global variable can be used for this field.

Append Mode

When this box is checked (the default), information is written to the log file in the Append

mode, where trace information is appended to existing entries in the file.

Unchecking this box changes to Overwrite mode, where the adapter instance overwrites

the current log file the next time the adapter starts.



Using Database Deployment and Cleanup Scripts

Changing an existing adapter instance typically generates legitimate changes in the

database. During this change process, the adapter creates a SQL script for changing the

database objects and an associated cleanup script and stores them in the

TIB_ADADB_HOME\sql directory. If the legitimate database changes result in error

messages, you may need to run these scripts. The messages and procedure for running the

scripts are given in this section.

If the scripts created for legitimate database changes are not generated successfully, a

message such as the following sample may display.


Using Database Deployment and Cleanup Scripts | 195

If the scripts created for legitimate database changes are generated successfully but an

error occurs while these changes are being saved to the database, a message such as the

following sample may display.

To Run the Deployment Scripts

The generated SQL script for changes to database objects is stored in the instance_ name.sql

file under the TIB_ADADB_HOME\sql directory. You can modify this script to deploy

changes to different databases environment. For example, if the user schema is different

between the production and testing environment, you can change the schema name of the

database objects in the script and deploy the changes accordingly.

To Run the Cleanup Scripts

1. Select each message in the top portion of the message window and read the

explanation for it in the bottom portion of the message window.

2. In TIBCO Designer, close the project containing the adapter instance that you

changed.

3. Fix the errors that caused the database changes to fail, as indicated by the messages.

4. If necessary, clean up the old database configuration by running the scripts created by

the adapter. The scripts are in the sql directory and are named instanceId.sql or

instanceId.undo.sql, where instanceId is the name of the adapter instance you changed.

5. Reopen the project in TIBCO Designer.



6. Select the adapter instance you were attempting to change when the errors occurred.

7. Save the project.


Changing the SQL Statement Terminator (DB2 for z/OS Only) | 197

Changing the SQL Statement Terminator (DB2 for z/OS Only)

The SQL statement terminator by default is a semicolon (";"), but DB2 trigger statements

use embedded semicolons as part of their syntax. Because of this, adapter SQL statements

use a pound sign ("#") as the SQL statement terminator.

When using the adapter in the default (real-time) mode, where repoOnly=false, the SQL

statement terminator is not used and no changes are necessary.

However, when running the adapter in batch mode (repoOnly=true), you must change the

SQL statement terminator from the default semicolon to the pound sign ("#") in order to

avoid conflicts with DB2 trigger statements.

Common methods of changing the SQL statement terminator are:

• Use SPUFI to set the terminator to # in the default panel.

• Include the following control statement at the beginning of the script file, or

immediately before the DDL statement to be executed:

--#SET TERMINATOR #

• Use DSNTEP2 or DSNTIAD to code the RUN command as follows:

RUN PROGRAM(DSNTEP2) PLAN(DSNTEP61) PARMS(’SQLTERM(#)’)

Task A Change the Statement Terminator

The following steps change the statement terminator to a '#', then executes the SQL from

the script file.

1. In a Windows command prompt, go to the directory where the script file resides.

2. Connect to DB2/OS390. For example:

C:\your_directoryDB2 Connect to S390LOC user logon_id using password

3. Execute your script file. For example:

C:\your_directoryDB2 -td# -f filen_ame

4. In the Window's Command Center, go to the Script menu and select options.

5. Check the Use Statement Termination Character checkbox and enter '#'.

6. Connect to DB2/OS390 from the Command Center GUI. For example:

Connect to S390LOC user logon_id using password

7. Cut the SQL statements from the script file and paste them into the Command Center

GUI, then execute.



Fault Tolerance

Within the context of the adapter, a primary instance is the adapter instance that processes

messages between the TIBCO environment and the database. The secondary instance uses

the same adapter configuration but runs in a stand-by mode and takes over when the

primary instance goes down.

To run in the fault tolerance mode, the property adb.mutex has to be defined. The value of

this property is the name of the table that an adapter instance will attempt to lock.

At start up, if the adb.mutex property is present, the adapter will try to issue an exclusive

lock on the table defined by the value of this property before processing any messages.

The named table is created at run time if it does not exist. The adapter instance that is able

to lock this table is considered a primary instance. All instances that are not able to issue

an exclusive lock on this table are considered secondary instances. Instances that specifies

the same mutex table will be within a fault tolerance group.

The primary instance releases the lock prior to shutdown. If the primary instance

terminates for an unknown reason, the lock is collected by the database system. As soon as

the lock is released, one of the secondary instances will hold the lock and become the

primary.

Both the primary and secondary instances will use a separate database connection to issue

lock on the mutex table. The adapter will keep this connection active by executing a

dummy query from time to time.

You can customize the adapter fault tolerance feature with the following adapter

properties:

• adb.primary.heartbeat: The time interval that the primary instance will execute a

dummy select statement to the database in order to keep the connection that hold the

lock to remain active. Default value is 10000ms

• adb.secondary.heartbeat: The time interval that the secondary instance(s) will wait

before sending the next query message to detect the existence of a primary instance.

Default value is 10000ms

• adb.heartbeat (deprecated): If none of the above parameter specified, this value will be

used as both primary and secondary heartbeat. Default value is 10000ms

• adb.createMutexTable: By setting the TRA property to false, the adapter will not

create the mutex table during start up. Default value is on. User can use the following

SQL statement to create the mutex table before starting the adapter:

CREATE TABLE mutex_table_name (COL1 char(1))

• adb.maxQuery: The secondary instance will send a query message to detect the

existence of the primary instance. This is the number of queries for which if no reply


Fault Tolerance | 199

is received the secondary instance will consider that a primary instance no longer

exists and will try to lock the mutex table.

• If the primary instance looses connection to the database, a reconnection will not be

attempted. The adapter instance will release the lock and gracefully shutdown letting

any secondary instance take over as the primary.

The time interval that the secondary instance(s) wait before attempting to lock the table

specified by the adb.mutex property is defined by the adb.heartbeat and adb.maxQuery properties.

Reconnection in the Fault Tolerance Mode

If the primary instance loses connection to the database, a reconnection will be attempted.

The adapter will perform reconnection base on the reconnection configuration, it will

gracefully shutdown if reconnection is not successful, letting any secondary instance take

over as the primary. If the secondary instance obtain the mutex lock while the primary

instance is reconnecting, the secondary instance will take over as primary. The original

primary instance will terminate if it cannot lock the mutex table after connection is

re-established.

On Oracle, you have to set the SQLNET.EXPIRE_TIME in sqlnet.ora script to a value greater than

0. This ensures that the server will collect the lock held by the invalid connection of the

primary instance due to connection lost.

On DB2, make sure the IDTHTOIN DSNZPARM parameter is greater than

adb.primary.heartbeat. This system parameter configures the timeout before the system

cancels an idle thread.



SSL Data Encryption using DataDirect ODBC Drivers

SSL data encryptions provide secure transmission of data. The adapter supports SSL data

encryption between the database and the adapter with DataDirect Wire Protocol ODBC

Drivers.

You may want to use data encryption in the following scenarios:

• You have offices that share confidential information over an intranet.

• You send sensitive data, such as credit card numbers, over a database connection.

• You need to comply with government or industry privacy and security requirements.

See ODBC Driver documentation for more information on the available features and the

required configuration details.

Data encryption may adversely affect performance because of the additional overhead

required to encrypt and decrypt data.


OS Authentication | 201

OS Authentication

This release of the adapter provides SQL Server OS Authentication on Windows.

Microsoft SQL Server uses integrated login security to establish connections using this

data source, regardless of the current login security mode at the server. Any login ID or

password supplied is ignored. The Microsoft SQL Server system administrator must have

associated your Windows network ID with a Microsoft SQL Server login ID.



Query Timeout

This release of the adapter provides Query Timeout on all databases. The operation for

database would return with error instead of hang if it can not be completed when the

database server is busy. For the publication service, the polling operation would return

null and wait for the next polling. For the subscription service, it would return the

connection dead error, and then reconnect.


Working with Multi-File Format Projects | 203

Working with Multi-File Format Projects

The multi-file format creates one ActiveEnterprise XML file for each logical object (such

as an adapter instance, a set of related ActiveEnterprise classes, or a TIBCO ActiveMatrix

BusinessWorks process flow) that occurs in the repository instance. This kind of project is

referred to as a multi-file project.

Multi-file projects can be checked into a version control system, and a project can contain

more than one adapter configuration. This allows a number of people to work on the same

project at the same time, with different people working on each adapter configuration: a

developer can check out the specific file corresponding to an object that needs to be

changed, updated the file, and check it back in. TIBCO Designer accesses the local

synchronized copies of the files on the developer’s hard drive.

The multi-file format provides a hierarchical structure with directories taking the place of

RepoDirectory nodes. In previous releases of TIBCO ActiveMatrix Adapter for Database,

repository nodes contained references to other repository nodes (such as sessions and

endpoints of that instance) using a format such as:

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

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

ProjectRoot/multi-file_project_name/#type.name

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

project:

ProjectRoot/Adapters/adb/test/instance1/publisher1

For more information see TIBCO Designer User’s Guide.



Subscriber Reply Sender

The subscriber can be configured to send the subscription status as a reply to the message

sender if the message contains a reply subject. This AE schema

ADB_SUBSCRIBER_STATUS is used for this reply message:

Table 40 Description of ADB_SUBSCRIBER_STATUS Class Schema

Field Name AE Type Description

RETURN_CODE i4 return_code=0, when the data is inserted into destination table

successfully.

return_code=-1, when the data is inserted into exception table.

return_code=5, when the data is failed to insert in both destination and

exception tables.

If you specified subscriber pre-commit stored procedure, this field will

contain the value of the RETURN_CODE output parameter.

ADB_TEXT string Contains the status or error message of the subscriber operation.

CALLOUT_TEXT string Contains the error message from the database driver in case of error

operation.

If you specified subscriber pre-commit stored procedure, this field will

contain the value of the SP_TEXT output parameter.


Subscriber Pre-commit Stored Procedure Call | 205

Subscriber Pre-commit Stored Procedure Call

The subscriber can be configured to call a stored procedure after the database insert,

update, or delete and prior to commit. You can use this stored procedure as a hook to

accomplish further processing inside the database and return the results to the adapter.

User can specify this pre-commit stored procedure name in the Pre Commit Stored

Procedure field of the Subscription Service Subscriber Options.

The adapter will call the pre-commit stored procedure with the following syntax:

{call <pre-commit stored procedure name>(?, ?, ?)}.

This stored procedure need to be defined with a specific interface as specified below:

Table 41 Description of the Pre-commit Stored Procedure Parameters

Name Type Description

RETURN_

CODE

integer RETURN_CODE = 0, the adapter will assume the procedure was successful and write a

success message to the SDK INFO trace role when the verbose mode is used.

RETURN_CODE <> 0, the adapter will assume the procedure was not successful and

write SP_TEXT to the SDK ERROR trace role (whether verbose mode is on or off).

If the message has a reply subject, this output value will be returned to the message

sender. See Subscriber Reply Sender on page 204 for more details.

SP_TEXT varchar If the message has a reply subject, this output string will be returned to the message

sender. See Subscriber Reply Sender on page 204 for more details.

DO_ROLL

BACK

integer DO_ROLLBACK = 0, the adapter will commit the transaction and confirm the original

message.

DO_ROLLBACK <> 0, the adapter will rollback the transaction and not confirm the

message. Note, not confirming the message changes the RVCM behavior. All

subsequent RVCM messages will not be confirmed. It should only be done when this

RVCM behavior is really desired.



JMS Durable Subscriber Name

The JMS Durable Subscriber name can take the deployment time global variable value in

this release.


Runtime Schema | 207

Runtime Schema

In the case where the schema name of the tables objects are different between

development and production environment, you can use the following TRA properties to

specify the schemas configuration.

For all database environments other than IBM UDB iSeries (AS00):

• adb.originalSchema – Specify the design-time table objects schema.

• adb.runtime.schema – Specify the runtime table objects schema.

— If adb.originalSchema is specified, the adapter will compare the adb.originalSchema with the

prefix of the table objects. If they are the same, the adapter will replace the

design-time schema with this runtime schema. Otherwise, no action will be taken.

— If adb.orignalSchema is not specified, the adapter will append this runtime schema to

all table objects that do not have any schema specified at design time.

• adb.runtime.publisherSchema – Specify the runtime publisher table schema. This overrides

the adb.runtime.schema setting. This can be used if user has a different schema for the

publishing table then the other table objects such as source table.

For IBM iSeries (AS00):

• adb.as400.defaultLibrary – Specify the default iSeries library to be accessed.

• adb.as400.library – Specify the name of the runtime iSeries library where the adapter will

access.

These configurations do not apply to the referred object in publish by reference mode.

User need to specify the runtime schema for the referred object during the design time, or

in the ADB_REF_OBJECT column entry in the publishing table.



Runtime Table Schema Configuration

You can specify the runtime schema global variables in the administrator console during

the deployment of the adapter to enable the adapter to use these schemas in run time which

are different from the design-time schema configuration. This makes it easy for you to

move from one environment to another, most likely from the test environment to product

environment.

For publisher by reference object, you need to make sure the right schema and reference

object name are set correctly in the right publisher table, because the reference object

name is fetched from the publisher table, not an property from the design-time DAT file or

TRA file.


Group Message Transaction | 209

Group Message Transaction

This feature allows you to configure a group message to be processed within a single

transaction by the subscription service. The adapter will either commit the whole message

changes to the database, or none. See Subscriber Options Tab on page 82 for details.



Load Balancing and Multithreading

TIBCO ActiveMatrix Adapter for Database supports multithreading and load balancing to

improve the performance in high load scenario.

Improving Performance Using Threads

You can improve the adapter Subscription Service and Request-response Service

performance by specifying the number of threads that will be responsible for processing

application requests. The number of threads to be spawned is specified in TIBCO

Designer for an adapter instance.

To set the number of threads for a configuration:

1. In the Project panel, click the corresponding ActiveDatabase Adapter resource to

select it.


2. Check the Show All Tabs checkbox.


Load Balancing and Multithreading | 211

3. Display the Adapter Services tab.

4. Change the value of Number Of Request-Response Service Threads or Number Of

Request-Response Service Threads as needed.




Subscription Service

You can select Use Separate Service Thread in the Subscriber Options tab during design

time. When selected, a new session is created and the service endpoint is moved to this

session.

During runtime, the adapter will create a separate dispatcher to dispatch event from this

session. You can select other subscription service to use the same session by changing the

sessionReference field under the Advanced tab. This allows multiple services to share the

same session and dispatcher.

Request-Response Service

Each request-response service thread is dedicated to listening on an agreed request

subject.

1. When a request message is received by the request-response communication thread, it

enqueues it into an in-memory queue. Each database request-response thread has a



connection to the database using the user name-password combination that was

provided to the adapter.

2. When an item is enqueued by the communication thread, one of the database

request-response threads picks it up and executes the one or more SQL statements in

the message as an atomic transaction.

3. It then composes a TIBCO Rendezvous self-describing response message and sends

back a response on a response subject. If the original request was sending using

rv_SendWithReply() or rv_Rpc(), the response is sent back on the subject that was specified

by the requesting application. Otherwise, the response is sent back on the subject that

was set up at configuration time.

Load Balancing Across Adapter Instances

Subscription and Request-Response Service

To achieve load balancing across adapter instances for subscription and request-response

services, TIBCO Rendezvous Distributed Queueing or TIBCO EMS Queue can be used to

assign each application request to exactly one adapter instance. For example, the

following diagram is an example for using TIBCO Rendezvous Distributed Queueing for

load balancing. It shows three adapter instances each connected to a database server (not

shown) that contains replicated data.

While the request message can be sent with either reliable or certified quality of service,

the response message is always sent back using the reliable quality of service.



Figure 6 Request-response Load Balancing

The adapter instances have been set up to use distributed queueing with one instance

acting as the scheduler. Only one of the three adapter instances will receive an incoming

request from an application. The scheduler will assign certified requests to the least loaded

member of the queue.

A queue member’s load is determined by the number of pending processes that are waiting

to be processed by the member’s database request-response thread. After the request is

processed, the processing configuration sends a response back to the requesting

application.

Configuring an Adapter Instance to use TIBCO Rendezvous Distributed

Queues or TIBCO EMS Queue for Load Balancing

You can configure the adapter with a subscription service to use a distributed queue, then

use TIBCO Administrator Enterprise Edition to deploy multiple instances of the adapter.

The instances can be deployed on the same machine, or multiple machines. In this

scenario, each adapter instance uses the same (default) values for the distributed queue.

1. Start TIBCO Designer and create a new project.

2. Drag the ActiveDatabase Adapter Configuration icon to the design panel.

TIBCO Messaging

Application

Adapter 4

Adapter 3

Adapter 2

Adapter 1

(Scheduler)

Request

Request

Request

RequestResponses

Distributed Queue

Reliable requests in a certified environment use a simpler type of load balancing. In this

example, the scheduler distributes the first reliable request to Adapter 2, the second to Adapter

3, and the third to Adapter 4 without evaluating a queue member’s load.



3. Configure the adapter instance with a design-time connection and ODBC DSN value.

4. Drag the ADBSubscriber icon to the design panel.

5. For using TIBCO Rendezvous transport, under the Configuration tab, select

Rendezvous in the Transport Type drop-down list, and Distributed Queue in the

Quality of Service drop-down list. For example:

For using TIBCO EMS Queue, set Transport Type to JMS and Quality of Service to

Queue.

6. Configure the service with a destination table name and other settings for your

environment.

7. Click Project > Save.

8. Click Tools > Create Project EAR. Under the Configuration tab, provide a name and

file location for the EAR file.

9. Click the Build Archive button.



Publication Service

You can check the Enable Load Balancing checkbox and specify the Mutex Name in the

Publisher Options tab during design time to balance load among multiple publication

service endpoints. Publication service with the same Mutex name specified will be in the

same load balance group.

When load balancing is enabled at design time, the adapter palette will create a publication

table with an additional column ADB_MARK.

At runtime, the publication services of the same load balancing group will create a mutex

table that was configured at design time, and poll the same publication table and distribute

loads. The service will synchronize by locking the mutex table to obtain and update the

sequence information.

Deploying an Adapter Instance for Load Balancing

After creating the EAR file, you are ready to import it into TIBCO Administrator

Enterprise Edition and add the adapter instance multiple times to the same machine or

multiple machines. Since these adapter instances have the same RVCMQ, EMS Queue, or

Mutex Name for publication configuration, they will participate as in same load balancing

group at runtime.

1. Start TIBCO Administrator Enterprise Edition.

When an adapter instance contains a publication service with load balancing enabled, it

can only run in batch polling mode. To turn on batch polling, enable the Use Polling

Batch Size option and specify the Polling Batch Size for the adapter instance.

For Sybase, the publisher load balancing feature requires the ddl in tran option be set to true:

sp_dboption database_name,"ddl in tran", true



2. Select Application Management, then click the New Folder button. In Name, provide

a name for the folder and click the Save button.

3. Select the folder, then click New Application.

4. Click the Browse button and navigate to the EAR file you created in Designer. Click

the OK button.

5. In the dialog that appears, click the Save button.

6. Expand the configuration, then double-click the name.aar file.



7. Click the Add to Additional Machine button and select the machine to bind to and

click the OK button.

8. Repeat to create the number of adapter instances required for your environment. For

example, the next screen shows that three adapter instances have been added.

9. Click the Save button.

The adapter instances are ready to be deployed. After the instances are deployed, when a

message is sent to the adapter, the instance that is not busy will handle the request.


Compressing JMS Messages | 219

Compressing JMS Messages

JMS message compression is an instance-level option. It is especially useful when

messages are to be stored on the TIBCO Enterprise Message Service server, including

persistent queue messages, or topics with durable subscribers. Enabling compression

ensures that messages take less memory space in storage and are handled faster by the

TIBCO Enterprise Message Service server. When JMS messages are compressed and

stored, they are handled by the server in the compressed form.

The compression option only compresses the body of a message. Headers and properties

are never compressed. It is best to enable compression when the message bodies are large

and the messages are to be stored on a server.

When messages are not to be stored, compression is not as useful. Compression normally

takes time, and therefore the time to send or publish and receive compressed messages is

generally longer than the time to send the same messages uncompressed. There is little

purpose to message compression for small messages that are not to be stored by the server.

You can enable or disable this feature for message senders with the following adapter

property:

• adb.jmscompress: Either on or off. The default value is off, which indicates that messages will

not be compressed.

JMS message compression is only for publication service with JMS transport.



Configuring RVCMQ Backlog Size

The RVCMQ scheduler receives the inbound messages and assigns them to the worker.

The scheduler stores tasks in a message queue. You can limit the maximum size of that

queue with either one of the following two adapter properties or both of them:

• adb.taskBackLogLimitInBytes: Specifies the maximum size of the scheduler task queue by

number of bytes. This value must be an integer. The default value is unspecified.

• adb.taskBackLogLimitInMessages: Specifies the maximum size of the scheduler task queue by

number of messages. This value must be an integer. The default value is unspecified.

When the task messages in the queue exceed either of these limits, TIBCO Rendezvous

deletes new inbound task messages.

If neither of the above properties are specified, there will be no limit to the size of the

scheduler task queue.

RVCMQ backlog size configuration is for subscription and request-response services only,

which have RVCMQ or RVDQ transport, not for publication service, which does not have

this transport type.


| 221

Chapter 10 Setting Encoding Options

This chapter describes how to use TIBCO ActiveMatrix Adapter for Database in an

international environment using non-ASCII languages.

Topics


• Setting TIBCO Messaging Encoding, page 224

• Configuring the Adapter to Communicate with the Database, page 226

• Relevant Environment Settings, page 231


222 | Chapter 10 Setting Encoding Options

Overview

TIBCO ActiveMatrix Adapter for Database provides internationalization support by

taking advantage of Unicode, which is supported by the TIBCO Adapter SDK. Currently

the international data support is provided for text data only.

The following illustration shows an example of TIBCO ActiveMatrix Adapter for

Database in a Japanese language environment serving databases of different encodings.

The adapter converts the encoding between Unicode and the character sets of the

databases.

Figure 7 Example of Unicode Conversion

In this example, Shift-JIS encoded Japanese data is retrieved from an Oracle database by

the adapter publication service, which converts the data into UTF-8 and publishes the

UTF-8 data to the TIBCO messaging environment. An adapter subscription service

receives this message and converts it from UTF-8 to EUC-JP, and inserts the data into an

Oracle EUC-JP database to which it is connected.

By using UTF-8 as the TIBCO Messaging encoding between TIBCO ActiveEnterprise

components, the two adapter services can serve databases of different encodings by

exchanging data without data garbling it.

Adapter Publishing Service

Adapter Subscription Service

TIBCO Messaging

Shift-JIS

UTF-8 UTF-8

EUC-JP

Oracle DB in Shift-JIS

Oracle DB in EUC-JP

Driver Manager/ODBC Driver/Database Client

In certain cases, intermediate entities (such as an ODBC driver, ODBC driver manager, or

the database vendor's proprietary database client) may also perform some encoding

conversion.


Overview | 223

In circumstances where only ASCII and Latin-1 data (including English and Western

European languages) are exchanged in the system, you can use Latin-1 encoding as the

TIBCO Messaging encoding between TIBCO ActiveEnterprise components. It is not

necessary to use UTF-8 as the TIBCO Messaging encoding in this case. UTF-8 is only

required when the data to be exchanged is not included in the Latin-1 character set, as is

the case with Asian languages and other European languages.

To configure the adapter to work correctly in transmitting non-ASCII data, you must set

the TIBCO messaging encoding property. The following sections explain how to do this.



Setting TIBCO Messaging Encoding

TIBCO ActiveEnterprise components (TIBCO applications and adapters) use TIBCO

Messaging encoding when communicating with each other. In the case of TIBCO

ActiveMatrix Adapter for Database, publication services use this encoding to publish data

into TIBCO messaging system, and subscription services use it to receive data from the

TIBCO messaging system.

There are currently two choices for TIBCO Messaging encoding: Latin-1 (ISO8859-1) for

transmitting ASCII and Latin-1 data, and UTF-8 for transmitting data of other languages.

The encoding property is set on the project itself at design time, and in the TIBCO

administration server’s property file when creating a TIBCO administration domain.

Encoding in a Server-based Project

The TIBCO administration server setting is used when the project is exported to a server

repository or deployed using TIBCO Administrator Enterprise Edition.

For a server based project, the TIBCO messaging encoding is set by the repo.encoding

property in the server's tibcoadmindomain_name.tra configuration file (located in

TIBCO_HOME/administrator/version/bin/).

The encoding is set when using the TIBCO Domain Utility to create the domain or by

editing the repo.encoding property in the TRA configuration file.

Each adapter or TIBCO application that uses the same server for storing and retrieving

configuration data uses this encoding setting when communicating to each other. This

assures that all TIBCO components (including adapters and other TIBCO applications)

that belong to the same project use the same encoding value to communicate.

Encoding in a Local Project File

If the project's configurations are saved in a local project file, which is the normal case

when the project is in design stage before deployment, the TIBCO Messaging encoding is

determined by the encoding property saved in the local project file.

The encoding value is set on the root project folder in TIBCO Designer. By default, the

value is set to ISO8859-1. You can change the value by selecting the folder and under the

Project Settings tab, changing the value for the TIBCO Message Encoding field.

The services do not use TIBCO Messaging encoding to connect to the backend database.

See Configuring the Adapter to Communicate with the Database on page 226 for more

information.


Setting TIBCO Messaging Encoding | 225

In order for different TIBCO components that each have their own local file repository to

communicate with each other without data garbled, they must use the same TIBCO

Messaging encoding, meaning that all these components must set their local project

encoding to the same value.

After a project is deployed as a server-based project, the encoding property set at design

time is superseded by the encoding property set for the TIBCO administration server.

The encoding property of a local project file is only for determining the TIBCO

Messaging encoding, not the encoding used for the persistent storage of the project files.

The project files are always saved as UTF-8 encoded files.



Configuring the Adapter to Communicate with the Database

The TIBCO message encoding is a project setting used for data conversion among

different components. However, the adapter uses a different encoding value for

exchanging data with the database. Because there are many intermediate entities between

the adapter and the database (such as the ODBC driver manager, ODBC driver, and

possibly the database native client), and each of these entities may conduct encoding

conversions to the data stream flow between the service and the database, the data

encoding from the database might not be known, while the data encoding to the database

must be compatible to that of the database.

To eliminate the complexity introduced by these intermediate entities, you can make some

configuration changes that ensure the service’s encoding setting are compatible with the

database instance's encoding. This also boosts the performance by eliminating

unnecessary intermediate data conversions.

The configuration changes differ depending on the operating system that the service is

running on, the database vendor, the ODBC driver used, and other factors. The following

sections explain how to configure the adapter to communicate with the database.

Configuring the Adapter at Design Time

Use the following steps to set the adapter’s encoding.

1. Determine your database server encoding. This is the encoding you want to use for the

adapter’s encoding. For example, for the Oracle database, the encoding can be found

by querying the database with:

select * from nls_database_parameters;

2. Set the NLS_LANG environment variable for the client system.

Set the client machine's NLS_LANG environment variable to be consistent to the

database instance's character set (NLS_CHARACTERSET) value. The client machine

is where the adapter service is going to run. Consult your database administrator for

the NLS_CHARACTERSET value of the database instance to connect to, and how to

choose the right NLS_LANG value.

As an example, the system may use an Oracle database instance with the

NLS_CHARACTERSET value set to JA16SJIS. In this case, the client machine's

NLS_LANG environment variable must be set to JAPANESE_JAPAN.JA16SJIS.

The correct setting of the NLS_LANG environment variable eliminates the encoding

conversion possibly conducted by the Oracle proprietary client.

3. Set the Adapter encoding in TIBCO Designer.


Configuring the Adapter to Communicate with the Database | 227

You must select or enter a valid encoding that the adapter understands. The adapter

assumes the data coming from the database is in this encoding and ensures that data

sent to the database is in this encoding. The encoding given here should match the

encoding set for the database to which the adapter connects.

There are two ways to do this configuration:

— In TIBCO Designer, set this in the adapter resource. In the Configuration tab, check

the Show All Tabs checkbox. In the General tab, choose the encoding that is

compatible with the encoding of the database instance to be connected to. See

Table 43, TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang

Values.

The adapter may support more encoding values than those shown in TIBCO

Designer. You can type in these encoding values. For more information about

these, See Appendix B in TIBCO Adapter Concepts.

— You can modify the adapter encoding property, adb.encoding, in the adapter’s TRA

configuration file. This setting supersedes the encoding option chosen in TIBCO

Designer.

4. Set the ODBC DSN in TIBCO Designer

This field is set under the adapter’s Runtime Connection tab. You must also define the

ODBC DSN on the machine on which the adapter is running.

— On Unix systems, modify the odbc.ini file TIB_ADADB_HOME/odbc. In addition, you

must set the correct IANAAppCodePage to match the database encoding, if you are

using a wire protocol driver. See Table 42, IANAAppCodePage, on page 227 for a

list of IANAAppCodePage values. The complete list is available in

TIB_ADADB_HOME/odbc/help/odbcref/odbcref.pdf

— On Windows systems, use the Windows ODBC GUI to define a system DSN. Note

that if you are using a TIBCO wire protocol driver, the machine on which the

adapter is running must be on the locale that matches the database encoding.

Table 42 IANAAppCodePage

Value Encoding (Language)

3 ASCII (English)

4 ISO_8859-1 (Western European)

17 Shift_JIS (Japanese)

18 EUC_JP (Japanese)

38 EUC_KR (Korean)

113 GBK (Simplified Chinese)



Using a non-Oracle Database

When using a database other than Oracle, contact the database vendor for information

about whether the database's proprietary client performs any encoding conversion to the

data flow, and how to configure the database client to eliminate the conversion possibly

conducted by it. Several possibilities exist:

• The database client does not perform any conversion to the data flow in any cases. In

this case, you only need to set the adapter encoding to be compatible with the database

instance's encoding.

• The database client relies on a local setting, such as an environment variable, to

determine whether or not a conversion should to be conducted. This is similar to the

above Oracle example, where you need to set both this local setting and the adapter’s

adapter encoding property to be compatible with the database server instance's

encoding.

• The database client relies on the local system encoding to determine the conversion.

— When the local system encoding is compatible with the database instance

encoding, no conversion will be conducted by the database client. You only need

to set the adapter encoding to be compatible with the database server instance

encoding;

— When the local system encoding is different from the database instance's encoding,

the proprietary database client may do the encoding conversion between the two

different encodings. This conversion cannot be avoided by any settings you can

make. In this case, set the adapter encoding to be consistent with the local system

encoding, because the data from the database has been converted to local system

encoding by the database client.

Special Configurations for Supporting a UTF-8 Database

This section applies only to TIBCO ODBC drivers.

2026 BIG5 (Traditional Chinese)

Table 42 IANAAppCodePage (Cont’d)

Value Encoding (Language)

When using the DataDirect non-wire protocol ODBC driver and UTF-8 as the adapter

encoding to support multilingual data exchange, the configuration is totally different. See

the section Special Configurations for Supporting a UTF-8 Database on page 228.


Configuring the Adapter to Communicate with the Database | 229

Companies doing business globally may require their database to be multilingual, that is, a

single database instance supporting multiple languages so the data from the company's

global business can be stored in it. Unicode is a natural choice for the encoding of this

kind of database instance.

This requires the adapter to be able to use Unicode, or specifically, UTF-8 encoding, to

communicate with the database. While this is already a supported feature, an exception

exists when using TIBCO ODBC drivers.

TIBCO ActiveMatrix Adapter for Database contains a binary mode for use with an

embedded TIBCO driver when UTF-8 is the encoding to communicate with the backend

database instance. The configurations described below are applicable to both Windows

and UNIX platforms, and both non-wire and wire protocol drivers.

1. Set the adapter’s encoding option to UTF8.

2. In the adapter’s.tra file, uncomment the following line:

#ADB.WCHAR = SQL_C_BINARY

This forces the adapter to use binary mode to communicate with the database.

3. Set the NLS_LANG environment variable to language_territory.AL32UTF8 or

language_territory.UTF8 if using vendor or DataDirect non-wire driver.

Special Configurations for Retrieving Unicode Data from Database

To retrieve unicode data from unicode character data types such as NCHAR and

NVARCHAR, the following adapter properties are required:

adb.unicode — specify the unicode type of the data, either UTF8 or UTF16

adb.wchar — specify whether to retrieve the unicode code as character or binary string.

When adb.unicode is set, the adapter will automatically set the value of this property to

SQL_C_BINARY.

These are for the internationalization configuration, which forces the adapter to use binary

mode to communicate to the database instance. No further encoding related configurations

are necessary. For example, on UNIX there is no need to set the AppCodePage attribute, and

when using a non-wire driver there is no need to set the proprietary database client.

When the adb.unicode option and the database national character set are both UTF8, the

adapter will add blanks after string values in published mess a age for nchar/nvarchar2

column.



Runtime Environment Variables

In general, after deploying the adapter, all information should be in the correct place,

however you should verify the deployed TRA file and platform settings. The encoding

conversion is dependent on the TIB_ICU_DATA environment variable. The deployed

adapter TRA file should have a property called tibco.env.TIB_ICU_DATA. Make sure it points

to the directory containing the tibicudata.dat file.

For the Oracle database, make sure the installed NLS_LANG attribute’s value matches the

database character set. If not, set NLS_LANG to the correct value before starting the

adapter. See TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang Values on

page 231 for a list of values.


Relevant Environment Settings | 231

Relevant Environment Settings

In order to support international languages, the adapter uses the tibicudata.dat file to convert

between the original database encoding and the TIBCO Messaging encoding (usually

UTF-8). The environment variable TIB_ICU_DATA is already configured to point to the

directory containing this file. Do not change this setting.

This environment variable setting is required on both Windows and Unix platforms.

The following table lists the TIBCO ActiveMatrix Adapter for Database encoding values

as shown in TIBCO Designer.

Table 43 TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang Values

Adapter EncodingOracle NLS_LANG (containing NLS_CHARACTERSET)

Description

ASCII US7ASCII 7-bit ASCII

ISO8859-1 language_territory.WE8ISO8859P1 ISO8859-1 (Latin-1), West European

Shift_JIS (CP943) JAPANESE_JAPAN.JA16SJIS Japanese Shift-JIS, CP943

Shift_JIS (TIBCO) JAPANESE_JAPAN.JA16SJIS Variant of IBM-943 (created by TIBCO for

flavoring some MS-932 conversions)

KSC-5601 KOREAN_KOREA.KO16KSC5601 Korean KSC-5601

Big5 TRADITIONAL

CHINESE_TAIWAN.ZHT16BIG5

Traditional Chinese Big5 with Euro

GBK SIMPLIFIED CHINESE_CHINA.

ZHS16CGB231280

Simplified Chinese GBK (superset of

GB2312-80)

EUC-JP JAPANESE_JAPAN.JA16EUC Japanese EUC

UTF8 AMERICAN_AMERICA.UTF8 Unicode Transformation Format-8


| 233

Chapter 11 Monitoring the Adapter

Read this if you have installed TIBCO Hawk and want to use TIBCO Hawk microagents

through the Monitoring tab of an adapter instance. TIBCO Hawk is an optional tool from

TIBCO Software Inc. that can be used in addition to the standard trace message logging

method described under Logging Tab on page 49).

Topics


• Starting TIBCO Hawk Software, page 235

• The Auto-Discovery Process, page 236

• Invoking Microagent Methods, page 237

• Available Microagents, page 240


234 | Chapter 11 Monitoring the Adapter

Overview

TIBCO Hawk is a sophisticated tool for enterprise-wide monitoring and managing of all

distributed applications and systems. System administrators can use it to monitor adapters

in a wide area network of any size. TIBCO Hawk can be configured to monitor system and

adapter parameters and to take actions when predefined conditions occur. These actions

include: sending alarms that are graphically displayed in the TIBCO Hawk display,

sending email, paging, running executables, or modifying the behavior of a managed

adapter.

Unlike other monitoring applications, TIBCO Hawk relies on a purely distributed

intelligent agent architecture using publish or subscribe to distribute alerts. TIBCO Hawk

uses TIBCO Rendezvous for all messaging and thus gains the benefits and scalability

from the TIBCO Rendezvous features of publish/subscribe, subject name addressing,

interest-based routing, and reliable multicast.

TIBCO Hawk is a purely event-based system that uses alerts. The agents are configured

with rules that instruct them on everything from what and how to monitor to what actions

to take when problems are discovered. Thus the workload is fully distributed throughout

the enterprise. Every agent is autonomous in that it does not depend on other components

to perform its functions.

The TIBCO Hawk Enterprise Monitor consists of these components:

• Display—GUI front end that displays alarms and provides editors to create rule bases,

create tests, view messages, and invoke microagents to request information or initiate

an action.

• Agents—Intelligent processes that perform monitoring and take actions as defined in

rules.

• Rulebases—Rules that are loaded by agents to determine agent behavior.

• Application Management Interface (AMI)—Manages network applications via

TIBCO Rendezvous and supports communication between a network application and

monitoring TIBCO Hawk agents, including the ability to examine application

variables, invoke methods, and monitor system performance.

• Microagents—Feed information back to TIBCO Hawk and expose action methods to

rulebases.

For more information, see the TIBCO Hawk documentation.


Starting TIBCO Hawk Software | 235

Starting TIBCO Hawk Software

The TIBCO Hawk agent can be configured to start automatically during the system boot

cycle. See TIBCO Hawk Installation and Configuration for information about starting

TIBCO Hawk.

TIBCO Hawk Administrator’s Guide explains how to start the TIBCO Hawk Display.

The guides are included in your TIBCO Hawk software installation area.



The Auto-Discovery Process

After you start an instance of TIBCO Hawk Display, it continually discovers machines

running TIBCO Hawk Agents on your network. Container icons are created for each

agent, and arranged hierarchically in clusters. By default, agent icons are clustered

according to subnets.

At first, the Agents container is empty. Its counter displays a value of zero and, on the

right, the Discovered counter is also at zero. Both icons are initially green in color to show

that no alerts, or warning messages, are in effect. As agents are discovered, the counters

increment to reflect the current number of discovered agents:

Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a

container in the left panel displays nested items on the right.

Icon colors change to reflect the highest level of alert found on discovered agents. For

explanations of icon elements and characteristics, see TIBCO Hawk Administrator’s

Guide.


Invoking Microagent Methods | 237

Invoking Microagent Methods

A set of default microagents is loaded when a TIBCO Hawk Agent is started. When you

install and start TIBCO ActiveMatrix Adapter for Database, its microagents are

dynamically added to the local agent.

To invoke a microagent method:

1. In TIBCO Hawk Display, right-click on the agent icon and select Get Microagents.

If TIBCO Hawk security is implemented on your system and you do not have access

to microagents on this agent, an error dialog displays. Select another agent, or contact

your system administrator to obtain access.

The Microagents, Methods and Arguments dialog displays. The panel on the upper

left lists microagents you can access on the current agent.

This dialog has two modes, Invoke and Subscribe. Invoking a method immediately

returns a single set of current results. Subscribing provides updates of current results

at regular intervals. Radio buttons at the bottom of the dialog control these modes.

2. Click a microagent name, such as Self, to display a list of associated methods and text

descriptions in the panels below.



3. Click the name of the method to invoke, such as getComponentInfo.

If the method accepts arguments, fields for each argument display in the upper right

panel. Detailed help text displays in the lower panel.

4. Specify any arguments for the method invocation.

5. Verify that the Invoke radio button is selected.

6. Click the Invoke button to invoke the selected method.


Invoking Microagent Methods | 239

The Invocation Results dialog displays the results returned by the method.

7. Click the Done button to close the dialog.

These steps describe how to interactively invoke a microagent method and receive a single

set of results in TIBCO Hawk Display. You can also use a microagent method as the data

source of a TIBCO Hawk rule. Rules automatically receive method results, apply tests to

evaluate them, then take action if necessary. For more information on building TIBCO

Hawk rules and rule bases, see TIBCO Hawk Administrator’s Guide.



Available Microagents

Each adapter has three microagents: a standard TIBCO Hawk microagent, a class

microagent, and a custom microagent.

When an adapter is started in TIBCO Designer or through a console, the available

microagents follow the below naming conventions:

• Standard Microagent: COM.TIBCO.ADAPTER.adb.%%Deployment%%.%%InstanceId%%

• Class Microagent: COM.TIBCO.adb.%%Deployment%%.%%InstanceId%%

• Custom Microagent:COM.TIBCO.adb.custom.%%Deployment%%.%%InstanceId%%

When an adapter is started from a deployed project in TIBCO Administrator, the available

microagents follow the below naming conventions:

• Standard Microagent: COM.TIBCO.ADAPTER.adb.domain_name.%%Deployment%%.%%InstanceId%%

• Class Microagent: COM.TIBCO.ADAPTER.adb.%%Deployment%%.%%InstanceId%%

• Custom Microagent:COM.TIBCO.adb.custom.%%Deployment%%.%%InstanceId%%

These microagents provide:

• Business level statistics—statistics that report the progress of the adapter as it interacts

with the database. For example, in a database adapter such statistics might indicate

whether objects were successfully or unsuccessfully inserted, updated, or deleted in

the database.

• Queries that return information about the state of the adapter. This can be an important

tool for seeing the internals of an adapter and debugging it if something appears

wrong. For example, methods can return information about threads, internal queues,

or connections to the target system. Using these methods, one might be able to

identify certain bottlenecks or gauge how successfully an adapter is scaling with

respect to the current environment.

• Updates of the adapter runtime parameters. This includes retrieving the current

runtime parameters and setting new runtime parameters without restarting the adapter.

An example of this is getting and setting the polling interval. Updating a runtime

parameter through the Hawk microagent only affects the setting of the instance that is

Microagents follow different naming conventions depending on how an adapter is started:

from TIBCO Designer, or from TIBCO Administrator.


Available Microagents | 241

running. It does not make a permanent change of the setting in either the repository or

the .tra file.

The following table lists each method available for the adapter. Although the Microagents,

Methods and Arguments dialog in TIBCO Hawk Display lists more methods than are

documented here, only the following methods are supported.

Table 44 Standard Microagent Methods

Standard Method Description

activateTraceRole() Activates a mapping of a role to a sink at runtime.

deactivateTraceRole() Deactivates a mapping of a roles to sinks at runtime.

getAdapterServiceInformation() Returns information about the services implemented by

this adapter.

getComponents() Returns information about the publisher, subscriber and

IODescriptor.

getConfig() Returns basic configuration information. More specific

information is accessed by the more specific methods.

getConfigProperties() Returns a list of publishers and subscribers.

getHostInformation() Returns standard and extended application information.

getRvConfig() Returns information about all TIBCO Rendezvous

sessions defined.

getStatus() Returns general status information, such as the number

of TIBCO Rendezvous messages received and

published, the number of errors since the last call, the

PID of the application, and more.

getTraceSinks() Returns information about sinks to which traces

currently go.

getVersion() Returns the configuration ID, application name, version,

and date for this adapter instance.

_onUnsolictedMsg() Displays alert messages sent to the current adapter.

preRegisterListener() Preregisters an anticipated listener.

reviewLedger() Returns information retrieved from the ledger file of a

certified messaging session for a publisher adapter.



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

specified sink.

stopApplicationInstance() Stops the running adapter instance.

unRegisterListener() Unregisters a currently preregistered listener.

Table 45 Custom Microagent Methods

Custom Method Description

getEventQueueSize() Retrieves the size of the TIBCO Rendezvous event

queue for the specified adapter instance.

setDebugLevel() Sets the debug level for the current adapter instance.

toggleVerboseFlag() Changes the value of the verbose flag from on to off, or

the reverse.

showConfiguration() Shows the configuration defined for the current agent.

terminateADBagent() Stops the current TIBCO ActiveMatrix Adapter for

Database agent.

getPollingInterval() Returns the current polling interval setting.

setPollingInterval() Set the polling interval for the publication service.

getPollingBatchSize() Get the polling batch size for the publication service.

setPollingBatchSize() Set the polling batch size for the publication service.

Table 46 Custom Microagent Methods with adb.perfMon


getActivityStatistics() Returns the total number of objects processed for all the

schemas, based on the request type. Also, returns the

number of success and error objects.

getActivityStatisticsByService Returns the total number of objects processed for each

of the schemas associated with the specified service.

getActivityStatisticsByOperation() Returns the total number of objects processed for all the

schemas by each service that is associated with a

specified operation.

Table 44 Standard Microagent Methods (Cont’d)

Standard Method Description


Available Microagents | 243

getThreadStatistics() Return the operation counts of the current threads.

getQueueStatistics() Return the current count of elements in any internal

queue used by the adapter.

getConnectionStatistics() Returns the state and statistics for all the current

connections used by the adapter.

resetActivityStatistics() Resets all the counts for the activity statistics.

resetThreadStatistics() Resets all the counts for the thread statistics.

resetQueueStatistics() Resets all the counts for the queue statistics.

resetConnectionStatistics() Resets all the counts for the connection statistics.

Table 46 Custom Microagent Methods with adb.perfMon (Cont’d)




activateTraceRole()

Purpose (Standard) Activates a mapping of a role to a sink at runtime. This replaces the

now-deprecated setTraceSink() TIBCO Hawk method.

Parameters Parameters Type Description

roleName string Name of the role to activate.

sinkName string Name of a sink for which to activate the role.


deactivateTraceRole() | 245

deactivateTraceRole()

Purpose (Standard) Deactivates a mapping of a roles to sinks at runtime.

Parameters Parameters Type Description

Role Name string Name of the role to activate.

Sink Name string Name of a sink for which to activate the role.



getAdapterServiceInformation()

Purpose (Standard) Returns information about the services implemented by this adapter. The

information is a summary of available adapter services.

Parameters

Returns

Parameter Type Description

Service Name string Name of the service from which to get information.

Default is ALL.

Returns Type Description

Line Integer Sequential row number.

Name string Name of the Service.

Endpoint string Name of the endpoint used for this service.

Type string Type of the endpoint, for example, Publisher,

Subscriber.

Quality of Service string Quality of service for the endpoint, for example,

RV, RVCM.

Adapter Name string Name of the application for this sink.

Session Name string Name of the TIBCO Rendezvous session.

Subject string Subject defined for this endpoint

Number of Messages Integer Number of messages processed for this endpoint.


getComponents() | 247

getComponents()

Purpose (Standard) Returns information about the currently active TIBCO Hawk components such

as publishers, subscribers, or timers.

Parameters

Returns

Parameters Type Description

Component Name string Name of the TIBCO Hawk component. Default is all

components.

Component Type string Any of Publisher, Subscriber, Timer, or IODescriptor. The

default value is All.


Component Name string Name of the TIBCO Hawk component.

Instance ID string Name of this adapter instance.

Adapter Name string Name of the adapter.

Session Name string Name of the TIBCO Rendezvous session.

Component Type string The name of the TIBCO Adapter SDK class for this

TIBCO Hawk component, such as MPublisher,

MSubscriber, or MIODescriptorSource. For more information,

see your TIBCO Adapter SDK documentation.

Description string Information about this TIBCO Hawk component, for

example, time interval, signal type, validating publisher

(or subscriber) etc.



getConfig()

Purpose (Standard) Retrieves generic configuration information. More specific configuration

information is accessed through separate methods.

Returns Returns Type Description

Instance ID string Configuration ID of this adapter.


Repository

Connection

string URL of the repository used for adapter instance.

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

configuration URL.

Command string Command line arguments used to start the adapter.


getConfigProperties() | 249

getConfigProperties()

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

Parameters

Returns


Property string Name of the property for which elements (tags) and

attributes are desired. For example, rvpub/startup.

If no value is given, all properties are returned.


Element Name string Repository directory for the property.

Attribute Name string Name of the repository object attribute.

Attribute Value string Value of the repository object attribute.

Line integer Line number in which this property is defined in the

project file.



getHostInformation()

Purpose (Standard) Returns standard and extended application information.


Name string Name of the property.

Value string Value of the property.


getRvConfig() | 251

getRvConfig()

Purpose (Standard) Returns information about the TIBCO Rendezvous session defined by this

adapter. Information about all currently defined sessions is returned if no sessionName is

provided.

Parameters

Returns


Session Name string Name of the TIBCO Rendezvous session for which

configuration is required (default is all).


Instance ID string The configuration ID of this adapter.


Session Name string Name of the session.

Service string Service parameter for this session.

Daemon string Daemon parameter for this session.

Network string Network parameter for this session.

Synchronous? boolean Returns 1 if this is a synchronous session, 0 otherwise.

Session Type string Type of session; one of M_RV, M_RVCM, or M_RVCMQ.

Certified Name string Name of this certified session.

Ledger File string Ledger file for this certified messaging session. Returns the

empty string for sessions that are not certified messaging

sessions.

CM Timeout string Timeout for this certified messaging session. Returns the

empty string for sessions that are not certified messaging

sessions.



getStatus()

Purpose (Standard) Retrieves basic status information about the adapter.

This information is fairly limited; for more detail, additional methods are provided:

getConfig() on page 248 and getRvConfig() on page 251.


Instance ID string Configuration ID for this adapter instance.


Uptime integer Number of seconds since startup.

Messages Received integer Number of TIBCO Rendezvous messages received.

Messages Sent integer Number of TIBCO Rendezvous messages published.

New Errors integer Number of errors since the last call to this method.

Total Errors integer Total number of errors since startup.

Process ID integer Process ID of the application.

Host string Name of host machine on which this adapter is running.


getTraceSinks() | 253

getTraceSinks()

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

Parameters

Returns


Sink Name string Name of the sink for which you need information. If no name

is specified, information about all sinks is returned. Default is

all.

Role Name string Name of the role for which you need information for the

specified sink or sinks. Default is all.


Instance ID string Name of this adapter instance as a string.

Adapter Name string Name of the application for this sink.

Sink Name string Name of the sink

Sink Type string Type of this sink. One of fileSink, rvSink, hawkSink, stderrSink.

Roles string Roles this sink supports, as a string. For example “warning,

error, debug”.



getVersion()

Purpose (Standard) Retrieves version information for the current application. Two lines may be

returned, one for the TIBCO Adapter SDK, one for the adapter.

Returns Returns Description

Instance ID The configuration ID as a string, for example SDK.

Adapter Name Name of the adapter as a string, for example rvpub.

Version Version number as a string, for example 1.1.


_onUnsolictedMsg() | 255

_onUnsolictedMsg()

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



preRegisterListener()

Purpose (Standard) Preregister an anticipated listener. Some sending applications can anticipate

requests for certified delivery even before the listening applications start running. In such

situations, the sender can preregister listeners, so TIBCO Rendezvous software begins

storing outbound messages in the sender’s ledger. If the listening correspondent requires

old messages, it receives the backlogged messages when it requests certified delivery.

Parameters

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


Session Name string Name of the session that anticipates the listener.

Publisher Name string Name of the component for which the listener should be

preregistered.

Listener Session

Name

string Name of the listener to preregister.


reviewLedger() | 257

reviewLedger()

Purpose (Standard) Returns information retrieved from the ledger file of a TIBCO Rendezvous

certified messaging session. Before invoking this method, ensure that the certified

messaging publisher adapter has established a certified delivery agreement with its

subscriber agents.

Parameters

Returns


Session Name string Name of the TIBCO Rendezvous session for which ledger

information is desired (default is all).

Subject string Name of the subject for which ledger information is desired.


Session Name string Name of the TIBCO Rendezvous CM session to which this information applies.

Subject string Subject name for this session.

Last Sent Message integer Sequence number of the most recently sent message with this subject name.

Total Messages string Total number of pending messages with this subject name.

Total Size integer Total storage (in bytes) occupied by all pending messages with this subject name.

If the ledger contains ten messages with this subject name, then this field sums the

storage space over all of them.

Listener Session Name string Within each listener submessage, the Listener Session Name field contains the

name of the delivery-tracking listener session.

Last Confirmed string Within each listener submessage, the Last Confirmed field contains the sequence

number of the last message for which this listener session confirmed delivery.

Line integer Row number in ledger file.

UnacknowledgedMess

ages

integer Number of RVCM messages pending for this listener. The value is computed by

subtracting the last sent sequence number from the last acknowledged sequence

number.



setTraceSinks()

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

Parameters

Returns OK if successful or an error if not successful.


Sink Name string Name of the sink for which you want to add a role or

change the file limit.

Role Name string Name of the role you want to add to this sink (warning,

error, debug, or user defined). Default is all.

File Size integer Maximum file size for this sink.

This parameter is ignored if the sink specified by

sinkName is not a file sink.


stopApplicationInstance() | 259

stopApplicationInstance()

Purpose (Standard) Stops the specified adapter by calling the internal stop() method.

Returns OK if successful or an error if not successful.



unRegisterListener()

Purpose (Standard) Unregisters a currently preregistered listener.

Parameters

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


Publisher Name string Name of the component for which the listener should be

preregistered.

Listener Session

Name

string Name of the listener to unregister.


getEventQueueSize() | 261

getEventQueueSize()

Purpose (Custom) Retrieves the size of the TIBCO Rendezvous event queue for the specified

adapter instance. For more information on events and event queues, see TIBCO

Rendezvous Concepts.

Parameters

Returns


Session string Type of listener for this adapter instance. Possible values are

Subscriber or Request/Reply. The default value is Subscriber.

Return Type Description

QueueCount integer The number of events currently in the event queue.

QueueLimit integer The maximum number of events this adapter instance can have

in the event queue. This value is set using the

adb.rvMaxQueueSize option in the adapter’s properties file. The

default value is 0, which means the event queue has unlimited

size.



setDebugLevel()

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

Parameters

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


DebugLevel integer Sets the debug level to 0 (off), 1, 2, or 3.

0— No debug information displayed.

1—SQL commands executed with the database shown.

2—ODBC data source for each SQL command shown.

3—All debug information displayed.


toggleVerboseFlag() | 263

toggleVerboseFlag()

Purpose (Custom) Changes the value of the verbose flag from on to off, or the reverse.

Returns This method returns OK if successful or an error if not successful.



showConfiguration()

Purpose (Custom) Shows the configuration defined for the current agent.

Parameters Parameter Type Description

VerboseInfo string The current setting for the verbose mode, on or off.

DebugLevelInfo string The debug level setting:

0— No debug information displayed.

1—SQL commands executed with the database shown.

2—ODBC data source for each SQL command shown.

PollIntervalInfo string The poll interval in milliseconds.


terminateADBagent() | 265

terminateADBagent()

Purpose (Custom) Stops the current TIBCO ActiveMatrix Adapter for Database agent.

Remarks Invoking this method displays a warning message with the text MicroAgent returned error. AMI

Method invocation timed out. The message can be ignored.

Returns This method returns OK if successful or an error if not successful.



getPollingInterval()

Purpose (Custom) Returns the current polling interval setting.


PollingInterval integer Polling interval in milliseconds.


setPollingInterval() | 267

setPollingInterval()

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


PollingInterval integer Polling interval in milliseconds.

ServiceName string (Optional) Name of service where the polling interval is

set.



getPollingBatchSize()

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


BatchSize integer The batch size for the publication service.


setPollingBatchSize() | 269

setPollingBatchSize()

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


BatchSize integer The new batch size for the publication service.



getActivityStatistics()

Purpose (Custom with adb.perfMon) Returns the total number of objects processed for all the

schemas, based on the request type. Also, returns the number of success and error objects.

Parameters

Returns


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


Name string Name of the service or operation. The operation can be one

of the following:

Fetch

Poll

Insert

Update

Delete

Total integer Total number of objects processed for this schema for a

publication service.

Total number of objects received for this schema for a

subscription service.

Success integer The number of objects that were successfully identified for

this schema which will be published or written to a file.

Failure integer The number of objects that were identified for this schema

but were not published because the header of the schema

failed validation for the publication service, or was written to

a file because the schema was not associated with the

subscriber for a subscription service.


getActivityStatisticsByService | 271

getActivityStatisticsByService

Purpose (Custom with adb.perfMon) Returns the total number of objects processed for each of the

schemas associated with the specified service. Also, returns the number of success and

error objects.

Parameters

Returns


Service Name string Name of the service.


Operation string Type of operation that the service performs.

Schema Name string Name of the schema that is associated with the service.

Total integer Number of objects processed for this schema for a


Number of objects received for this schema for a











getActivityStatisticsByOperation()

Purpose (Custom with adb.perfMon) Returns the total number of objects processed for all the

schemas by each service that is associated with a specified operation. Also, returns the

number of success and error objects.

Parameters

Returns


Operation string Name of operation. Pick from one of the following form the

drop-down list.

Fetch

Poll

Insert

Update, and

Delete


Service Name string Name of the service that is associated with the specified

operation.

Total integer Total number of objects processed for this schema for a


Total number of objects received for this schema for a










getThreadStatistics() | 273

getThreadStatistics()

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


ThreadID string A unique identification of a particular thread.

ThreadType string A type or key that will match this thread to a queue or

connection.

TaskType string Short description of the tasks this thread processes.

TaskCount integer Number of tasks processed by this thread.



getQueueStatistics()

Purpose (Custom with adb.perfMon) Return the current count of elements in any internal queue used

by the adapter. This includes the TIBCO Rendezvous event queues automatically spawned

by TIBCO Rendezvous for each adapter.


QueueID string A unique identification of a particular queue.

QueueType string A type or key that will match this queue to a thread or

connection.

QueueCount integer Current number of elements in the queue.

MaxQueueSize integer Maximum number of elements in the queue.


getConnectionStatistics() | 275

getConnectionStatistics()

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

used by the adapter.


Connection ID string A unique identification of a particular connection.

Connection Type string A type or key that will match this connection to a thread or

queue.

State string Current state: CONNECTED or DISCONNECTED

NumRetries integer Total number of times this connection had to be

reestablished.

TotalNumOperations integer Total number of operations processed by this connection

since the adapter started.

CurrentNumOperatio

ns

integer Total number of operations processed by this connection

since the last reconnection.



resetActivityStatistics()

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


resetThreadStatistics() | 277

resetThreadStatistics()

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



resetQueueStatistics()

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


resetConnectionStatistics() | 279

resetConnectionStatistics()

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


| 287

Appendix A Frequently Asked Questions

This appendix lists answers to frequently asked questions.

Topics

• General Questions, page 288

• Request-response Questions, page 293


288 | Appendix A Frequently Asked Questions

General Questions

How can I determine the source of a problem or an error?

In some cases it is helpful to turn on ODBC tracing. Navigate to Control Panel >

Administrative Tools > ODBC Data Sources. Activate tracing by clicking the Start

Tracing Now button on the Tracing tab. For details, see your Microsoft Windows

documentation.

How can I find the version number of an adapter instance?

A banner displays when an adapter instance starts. The banner lists component versions

for the adapter and for TIBCO Adapter SDK software. You can use this information to

diagnose compatibility issues, or to report any problem details to Customer Support.

You can also display version information in TIBCO Designer by selecting Help >

Runtime Environment.

Why is a database trigger error not logged in the exception table?

When using an adapter instance as a publisher, if an error occurs in the database trigger

that is used to copy data from the source table to the publishing table, the database trigger

error will not be logged in the exception table for the subscriber adapter.

How should the adapter react if the database connection is lost and the database is later

restarted? Does it automatically try to reconnect?

If TIBCO ActiveMatrix Adapter for Database detects it has lost its database connection, it

shuts down. You can configure the adapter for automatic reconnection (see Runtime

Connection Tab on page 45). Alternatively, TIBCO Hawk rules can be written to detect

this and restart the adapter whenever this occurs.

Must an incoming message contain all the columns that are defined for the destination table?

The incoming message need not contain all the columns defined in the destination

database table. You can configure the adapter to expect only a subset of the columns,

defined in the repository. The adapter is driven from the subscribing class description and

will iterate through the attributes in the class definition for the subscribing table and

specifically look for those attributes in the incoming messages. It inserts NULLs for the

attributes that it is expecting but does not find in the message. If there are more columns in

the subscribing table than are listed in the subscribing class (set when adding a

subscription), those extra columns will get whatever default values were specified during

the table creation.


General Questions | 289

Can an existing table be used as the publishing table?

No. TIBCO ActiveMatrix Adapter for Database requires additional columns in the

publishing table. Even when every field in a table is published, a separate publishing table

is required.

Does the TIBCO Rendezvous message that is published have to contain every field in the

publishing table?

Yes. You can control which fields are copied to the publishing table by configuring the

adapter and by changing the publication trigger to publish a subset of rows. You can also

append additional fields to a message or drop a message based on some criteria using the

user callout library. For more information on the user callout library, see User Callout

Library on page 183.

If multiple updates occur between polling intervals, are updates published in multiple TIBCO

Rendezvous messages or a single large message?

If you are using publish by value, a TIBCO Rendezvous message is created for each individual

update. If you are using publish by reference, that operation will get the last update.

Is it possible to delete older entries in the publishing table?

Yes. When a row is published, the value of the ADB_L_DELIVERY_STATUS field in the

publishing table changes to either C (complete) or F (failed). You can write a trigger in

your publishing table that deletes the row when the delivery status changes to C or F.

You can also publish data directly from the source table by configuring the adapter

instance to publish by reference. A publishing table is created, but it contains only

required fields and key fields of the source table.

How does the exception table work?

Before starting an adapter instance, you must set the adb.useExceptTable option in the

adapter’s properties file to on and specify an exception table when configuring the adapter

instance. If an error occurs when inserting data into the destination table, it will be inserted

into the exception table. The transaction will be committed and a confirmation sent back

for the message (RVCM delivery). If the insertion into the exception table also fails, an

error message will display and the adapter instance will terminate.

Can an adapter instance be used to replicate binary types, such as BLOB?

There is only limited support for binary large object (BLOB) data types. Oracle LONG

and LONG RAW types are supported in top-level tables when the adapter is configured to

publish by reference. Oracle BLOB and CLOB data types are supported.



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.


General Questions | 291

For the subscriber adapter, if failure occurs after doing a database update and before sending

an acknowledgement back to the publisher adapter, can the restarted configuration be

prevented from redoing the update operation?

No. This would cause a duplicate insert.

For a certified subscriber adapter, if an insert exception occurs and no exception table is

specified, what happens?

If the tibco.clientVar.DirTrace option is specified in the adapter’s properties file when the

adapter is started, exception handling information is written to the log file and the

configuration continues to run. Since the insert could not be performed, the

ADB_L_DELIVERY_STATUS publishing table column has a value of P for the message.

How do I pre-register non-TIBCO ActiveMatrix Adapter for Database subscribers, like custom

adapters, to ensure no messages are lost?

Specify the CM name of the listener’s RVCM session

The session names are automatically created. Can these be changed, without confusing TIBCO

ActiveMatrix Adapter for Database, so that we can use a standard naming convention

throughout the entire integration process?

No, the session names are fixed and used by TIBCO ActiveMatrix Adapter for Database

internally. They cannot be altered.

What’s the proper way to permanently remove an adbagent subscriber when using CM? One

way is to completely REMOVE the publisher’s ledger and to change all ’P’ records back to ’N’,

then restart the publisher. Is there a better, more correct or automated method?

There is a TIBCO Hawk method, unRegisterListener(), which unregisters a CM subscription.

This is the proper way to remove the adbagent subscriber as a CM listener.

Is it possible to run an adapter instance using a remote TIBCO Rendezvous daemon?

Yes. Change the default settings for network, service, and daemon parameters for the

adapter using TIBCO Designer.

Is it possible to run two configurations of the adapter on the same machine?

It's possible to run multiple configurations of the adapter on the same machine if each

adapter instance has a unique name. If both configurations use TIBCO Rendezvous

certified messaging, each must use a different RVCM session.

Can an adapter instance collate information from several database tables to send as a single



TIBCO Rendezvous message, or can it only publish data from a single table, in the format

defined by that table?

There are two ways to publish related tables:

• Set the adb.publishChildData option to on when configuring the adapter’s properties file.

When there are insertions into parent table, the adapter will publish parent rows and

the corresponding child rows using TIBCO ActiveEnterprise or XML format.

Note that the adapter currently does not support publishing child data in the TIBCO

Rendezvous Message format. Update and delete on parent-child relationship when

publishing is also not supported. See Publisher Options Tab on page 76.

• Combine several tables into one table using a trigger and then publish from the

combined table.

When publishing or subscribing, an adapter instance allows you to change the message

using the callout library. See User Callout Library on page 183 for details.

Why does TIBCO Designer display a Java exception error while I’m trying to use TIBCO

Designer through Exceed?

When using Exceed to simulate an X Windows environment, start the X Windows server

in the Exceed Session Startup Application. In this application, make sure the Run X server

checkbox is selected, then try TIBCO Designer again.

When my Sybase transaction log becomes full, the adapter hangs. How can I fix this problem?

When a Sybase transaction log becomes full, if the database setting abort trans on log full is set

to false, your application will hang instead of printing a transaction log full error. Execute

the following command:

sp_dboption dbname, "abort tran on log full", true


Request-response Questions | 293

Request-response Questions

When using request-response, can an INSERT statement with values only (without field names)

be sent to the improve application's performance.?

Yes this is allowed. Your application can also send INSERT statements without the binds.

Can an application send UPDATE statements to a subscriber adapter with only those fields

which are being updated? That is, if a table has ten records and only two should be updated,

can an UPDATE statement be constructed and sent only for those fields?

Yes, this is supported.

Does an adapter instance send responses back as one large message with all rows in it or is

the message sent in chunks?

The adapter sends results back to an application as one large message.

If a failure occurs when doing an insert or update, what is returned to the application?

If an error occurs while the adapter is processing a request, an error code and description is

returned to the application. In the case of success, a result set and row count is returned to

the application.


| 295

Appendix B Trace Messages

This appendix explains the trace messages in TIBCO ActiveMatrix Adapter for Database.

These include status messages, informational messages, error messages, and other types of

messages.

Topics


• Status Messages, page 299


296 | Appendix B Trace Messages

Overview

Trace messages provide information about adapter activities. The messages are logged to

the console where the runtime adapter was started and to a log file in a location specified

during configuration. Trace messages can also be redirected to the TIBCO Hawk Display

application, or sent to other applications using the TIBCO Rendezvous transport.

Each trace message can include the following fields in the order shown:

Timestamp Adapter_Identifier Role Category Status_Code Tracking_Identifier Application_Information

The above fields are explained in Trace Message Fields on page 297. The following

example shows a trace message containing some of these fields and then identifies the

fields.

Example Trace Messages

The following trace messages were written during a session where TIBCO Adapter for

Files received an object from TIBCO Adapter for R/3, then processed the object.

Example 1:

Adapter Started

The following message indicates that TIBCO Adapter for Files has started. The timestamp

indicates when the adapter started, and the role indicates that the trace message is

informational, which means the activity is normal for the adapter. The category is

identified, and the corresponding status code is displayed. The status code indicates that

the adapter started successfully.

2003 Feb 22 20:14:51:718 GMT -8 FileAdapter.FileAdapterConfiguration Info [Configuration] AEFA-000058 TIBCO

Adapter for Files successfully initialized

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter]

AEFA-000067 Message containing class /tibco/public/class/ae/Customer received on subject

FROM.SAP tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

2003 Feb 22 20:15:12:937 GMT -8

FileAdapter.FileAdapterConfiguration

Info

[Adapter]

AEFA-000067 Message containing class

/tibco/public/class/ae/Customer received on subject FROM.SAP

tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

Timestamp:

Adapter ID:

Role:

Category:

Status Code:

Tracking ID:


Overview | 297

Example 2:

Message

Received

The next set of trace messages indicates the adapter received an object that was sent on the

TIBCO Rendezvous subject, FROM.SAP. The #MU3oTJ/WWCV1MU96J0zzwA9kzzw# tracking

identifier included in the trace message uniquely identifies the message. The adapter

(TIBCO Adapter for R/3) from which the message originated provided the identifier.

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000067 Message

containing class /tibco/public/class/ae/Customer received on subject FROM.SAP

tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000068 Message

containing class /tibco/public/class/ae/Customer written to working file customers.txt in Working Directory

F:\ca\integration\001\data_sets\files\wip tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

Example 3:

Object Moved

The final trace message indicates the object has been moved to the output directory, which

completes the adapter’s interaction with the object. Because the trace message is the

termination point, the tracking identifier is not displayed.

2003 Feb 22 20:15:42:812 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000070 File

customers.txt is moved to the Output Directory F:\ca\integration\001\data_sets\files\solutions\output

Trace Message Fields

Each trace message includes the following fields:

Table 47 Trace Message Fields (Sheet 1 of 2)

Field Name Description

Timestamp Timestamp of occurrence. For example, 2003 Feb 22 20:14:51:718 GMT -8.

Adapter Identifier Name of the adapter that wrote the trace message. This is a combination of the adapter acronym

and adapter configuration name. For example, the application identifier, ADB.publisher1

identifies a TIBCO ActiveMatrix Adapter for Database service named publisher1.

Role A role can be:

Info. Indicates normal adapter operation. No action is necessary. A tracing message tagged with

Info indicates that a significant processing step was reached and has been logged for tracking or

auditing purposes. Only info messages preceding a tracking identifier are considered significant

steps.

Warn. An abnormal condition was found. Processing will continue, but special attention from

an administrator is recommended.

Error. An unrecoverable error occurred. Depending on the error severity, the adapter may

continue with the next operation or may stop altogether.

Debug. A developer-defined tracing message. In normal operating conditions, debug messages

should not display.

When configuring the adapter you define what roles should or should not be logged. For

example, you may decide not to log Info roles to increase performance.



Category One of the following:

• Adapter. The adapter is processing an event.

• Application. The adapter is interacting with the database.

• Configuration. The adapter is reading configuration information.

• Database. The adapter is interacting with a database.

• Metadata. The adapter is retrieving metadata from the database.

• Palette. The adapter is interacting with the palette.

• Publisher Service. The publication service is reporting this trace message.

• Request-Response Client Service. The request-response invocation service is

reporting this trace message.

• Request-Response Server. The request-response service is reporting this trace

message.

• Shutdown. The adapter is shutting down.

• Startup. The adapter is starting.

• Subscription Service. The subscription service is reporting this trace message.

• System. This category is not linked to a specific event process. The trace message

may be related to a Windows service related messages, memory allocation, file

system error, and so on.

• TibRvComm. The adapter is communicating with TIBCO Rendezvous.

• XML. The adapter is parsing XML documents.

Status Code Unique code for the message and description. Status codes are identified by a unique number

and description. If a trace message includes an error or warn role, the status code documentation

includes a resolution. See Status Messages on page 299 for details.

Tracking Identifier A unique identifier that is "stamped" on each message by the originating adapter. The tracking

identifier remains in effect from a message’s beginning to its completion as it is exchanged by

TIBCO applications. If the adapter is the termination point of the message, the tracking

identifier is not displayed in the trace message.

You cannot modify the tracking identifier format or configure what information is displayed.

Application

Information

Application-specific information added to the tracking info to trace the message back to its

source. Set initially by the originating adapter and carried forward. It is augmented by each

intermediate component.

Table 47 Trace Message Fields (Sheet 2 of 2)

Field Name Description


Status Messages | 299

Status Messages

Status Code Role Category Resolution

AEADB-100001 %1Database connection succeeded.

infoRole Database Normal operation; no action is necessary.

AEADB-100002 %1Database connection failed.

errorRole Database Check and test the ODBC configuration and restart

the TIBCO Runtime Agent.

AEADB-100003 odbc connection as: DSN: %1, User: %2


AEADB-100004 Database driver code: %1Database vendor message: %2

errorRole Database See an ODBC manual and the manual of the native

database by using the error code.

AEADB-100005 Unknown database system.

warnRole Database The adapter is unable to detect the DBMS type of the

database it connects to. Make sure a supported

DBMS is used. This condition sometimes occurs

because a native character set is used. If you are

using a supported DBMS, ignore this warning.

AEADB-100006 %1SQL statement preparation succeeded.


AEADB-100007 %1SQL statement preparation failed.

errorRole Database Preparation of a SQL statement failed. Check the

configuration for this adapter service and restart the

adapter.



AEADB-100008 Problem reading values for %1 from Database

errorRole Database The adapter cannot retrieve data from tables. In the

adapter properties file, set the adb.verbose option to on and

the adb.debug option to 3 to print the SQL statement to

the log file then report this error to TIBCO support.

AEADB-100009 Database Connection Lost, Terminating....

errorRole Database Check the connection to the underlying database and

restart the adapter.

AEADB-100010 JDBC connection as: Driver %1, URL %2, User %3


AEADB-100011 %1Database connection closed


AEADB-100012 %1Invalid statement

errorRole Database The adapter detected an invalid SQL statement. For

request-response service, an invalid request is

processed; otherwise, check your adapter service

configuration and restart the adapter instance.

AEADB-100013 Attribute %1 (class %2): No column data ignoring


AEADB-100014 Inserted %1into database

infoRole Adapter Normal operation; no action is necessary.

AEADB-100015 Deleted from database


AEADB-100016 No rows deleted


AEADB-100017 Updated database


Status Code Role Category Resolution (Cont’d)



AEADB-100018 No rows updated


AEADB-100019 No columns specified for WHERE clause in %1

errorRole Adapter The adapter could not find key fields to construct the

WHERE clause. Check the repository definition of

this class and make sure there is at least one field

with isKey=true.

AEADB-100020 Building %1 criteria


AEADB-200001 Foreign key attribute %1 not found in the publishing class.

errorRole Configuration Check your parent-child relationship in publisher

configuration and make sure that the child table is

joined with the parent table by a common key

column, then restart the adapter.

AEADB-200002 %1Class registry not found: %2.

errorRole Configuration Check the configuration of that service to make sure

that the class registry exists.

AEADB-200003 %1Class description not found: %2.

errorRole Configuration Check the configuration of that service to make sure

that the class description exists. Sometimes, if the

loadUrl is not set correctly, this problem occurs.

AEADB-200004 Problem encountered when reading from ADB_PREREGLISTENER

errorRole Configuration The adapter has problems reading from the

ADB_PREREGLISTENER table. Check to see that

access to that table is allowed and the table is not

corrupted.




AEADB-200005 Could not register Hawk method %1

warnRole Configuration A description of a TIBCO Hawk method was not

found in the repository. This can happen if the

adapter instance is not the latest. Configure the

adapter with the latest TIBCO Designer version.

AEADB-200006 Setting %1 = %2.

infoRole Configuration Normal operation; no action is necessary.

AEADB-200007 %1 cannot be used with %2

warnRole Configuration Incomplete options or conflicting options are used.

Check the log file for the detailed information and

restart the adapter with correct options.

AEADB-200008 Preregistering %1 on %2

infoRole Configuration Normal operation; no action is necessary.

AEADB-200009 %1 creation failed

errorRole Configuration There was an error initializing the publication. Check

your project and re-configure the publication.

AEADB-200010 %1 cannot be larger than %2

errorRole Configuration Conflicting options are used. Check the log file and

restart the adapter with the correct options.

AEADB-200011 Unsupported encoding type: %1, Use default ASCII Encoding.

errorRole Configuration An unknown character set is detected. Check the

language configuration in the OS environment and

restart the adapter.

AEADB-200012 AEADB-POLLINGINTERVAL-NOVALUE-ERR

errorRole Configuration Unable to retrieve polling interval value from Hawk

method. Retaining original value of %1 milliseconds.

Please make sure a value is specified before invoking

the setPollingInterval method.

AEADB-200013 AEADB-POLLINGINTERVAL-NEGATIVE-ERR




errorRole Configuration Negative value of %1 for polling interval not

allowed. Retaining original value of %2

milliseconds. Please make sure to specify a

non-negative value for the polling interval.

AEADB-200014 AEADB-POLLINGINTERVAL-SAME-WARN

warnRole Configuration Polling interval already set to %1 milliseconds.

AEADB-200015 AEADB-POLLINGINTERVAL-CHANGED

infoRole Configuration Polling interval changed to %1 milliseconds.

AEADB-200016 AEADB-POLLINGBATCHSIZE-NOVALUE-ERR

errorRole Configuration Unable to retrieve polling batch size value from

Hawk method. Retaining original value of %1.

Please make sure a value is specified before invoking

the setPollingBatchSize method.

AEADB-200017 AEADB-POLLINGBATCHSIZE-NEGATIVE-ERR

errorRole Configuration Negative value of %1 for polling batch size not

allowed. Retaining original value of %2. Please make

sure to specify a non-negative value for the polling

batch size.

AEADB-200018 AEADB-POLLINGBATCHSIZE-SAME-WARN

warnRole Configuration Polling batch size already set to %1.

AEADB-200019 AEADB-POLLINGBATCHSIZE-CHANGED

infoRole Configuration Polling batch size changed to %1.

AEADB-200020 AEADB-POLLINGBATCHSIZE-CHANGED

warnRole Configuration The repository encoding should be set to UTF-8 if

your agent encoding is not ASCII or LATIN-1. Set

the repository encoding to UTF-8.

AEADB-300001 %1exception thrown in %2.

errorRole System An adapter internal error. Contact TIBCO Support.




AEADB-300002 Not enough memory available.

errorRole System Check the virtual memory of the system and restart

the adapter. If it keeps happening, contact TIBCO

Support.

AEADB-300003 MException throw in %1: %2.

errorRole System An Adapter SDK exception was thrown. Report the

SDK error code and text to TIBCO Support.

AEADB-300004 %1 on connect socket in thread failed

errorRole System A TCP system call failed. Check your computer’s

network ports and TCP libraries. Rebooting the

computer may solve the problem.

AEADB-300005 Binding address to socket failed. Listenport = %1




AEADB-300006 Listen call on socket failed



machine may solve the problem.

AEADB-300007 Accept on socket failed




AEADB-300008 Socket creation in thread failed







AEADB-300009 Out of memory building the WHERE clause

errorRole Adapter An adapter process has run out of memory. Increase

the amount of memory allowed to the adapter on

your system.

AEADB-400001 %1Unknown column name %2

errorRole Metadata Request is missing a column field in the Bind data.

Add a column, tableName.columnName field, to your bind

data.

AEADB-400002 %1Unknown column type: %2 for field: %3.

errorRole Metadata The type %2 is an invalid AE class type. Check in the

repository for attribute %3 and change the class type

to a valid AE class type.

AEADB-400003 Unknown column type, %1, %2

infoRole Metadata Normal operation; no action is necessary.

AEADB-400004 %1schema %2, tables: %3

debugRole Metadata

AEADB-400005 %1table %2, columns: %3

debugRole Metadata

AEADB-400006 Ill-formatted table name %1

errorRole Metadata A table name of this format is not supported by the

adapter. Use a different table name.

AEADB-600001 %1Failed to set limit policy for event queue %2 on session %3: %4

errorRole TibRvComm TIBCO Rendezvous failed to set the limit policy

according to the -rv-max-queue-size specification.

Please report this error text to TIBCO customer

support.




AEADB-600002 %1Failed to get queue count for event queue %2 on session %3: %4

errorRole TibRvComm TIBCO Rendezvous failed to get the queue count for

the given session. Please report this error text to

TIBCO customer support.

AEADB-600003 %1Failed to get queue limit for event queue %2 on session %3: %4

errorRole TibRvComm TIBCO Rendezvous failed to get the limit policy for

the given session. Report the this error text to TIBCO

Support.

AEADB-600004 OnEvent: eventname %1

infoRole TibRvComm Normal operation; no action is necessary.

AEADB-600005 MException thrown trying to publish message on "%1".

errorRole TibRvComm Unable to publish the message, check error

description for details. Check your daemon

connection.

AEADB-600006 %1Received ADVISORY %2

errorRole TibRvComm An unexpected TIBCO Rendezvous advisory was

received. See your TIBCO Rendezvous

documentation for resolution information.

AEADB-700001 SQL: %1


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


AEADB-700003 %1Binding data to placeholders: unknown column type, %1 for field %2.

Ignoring

errorRole Adapter The type %1 is an invalid AE class type. Check in the

repository for attribute %2 and change the class type

to a valid AE class type.




AEADB-700004 %1database operation%2 succeeded


AEADB-700005 %1database operation%2 failed

errorRole Adapter The execution of this database statement failed. Use

the error returned by the database to determine how

to allow this SQL statement to succeed.

AEADB-700006 %1database transaction begin


AEADB-700007 %1database transaction commit


AEADB-700008 %1database transaction rollback.


AEADB-700009 %1Cannot bulk insert for variable binary type in column %2.%3.

warnRole Adapter The subscriber bulk insert option does not support a

variable binary data type. Do not use bulk insert for

tables with a variable binary data type.

AEADB-700010 %1Database transaction commit failed.

warnRole Adapter The database was unable to commit the transaction.

Use the error returned by the database to determine

how to allow this transaction to succeed.

AEADB-700011 Encoding error from %1 to %2.

errorRole Adapter An Adapter SDK error converting data to the

specified encoding. Make sure the encoding is a

supported one.

AEADB-700012 %1Cold start completed.





AEADB-700013 %1Cold start failed.

errorRole Adapter Run the adapter using debug 3 and verbose mode.

AEADB-700014 %1Confirming message.


AEADB-700015 %1 batch commit timeout.


AEADB-700016 %1Bulk insert begins.


AEADB-700017 %1Bulk insert ends.


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


AEADB-700019 %1Exception table is not specified.

warnRole Adapter Reconfigure the subscriber by specifying an

exception table, or turn off the adb.useExceptTable option

(in the adapter properties file) when starting the

adapter.

AEADB-700020 %1Cannot find bound data for %2.


AEADB-700021 %1 = %2

debugRole Adapter

AEADB-700022 %1 = NULL

debugRole Adapter

AEADB-700023 %1Bulk insert turning off.





AEADB-700024 Polling publishing table %1


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


AEADB-700026 %1 = %2

debugRole Adapter

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


AEADB-700029 %1


AEADB-700030 Received request %1.


AEADB-700031 Built reply %1.


AEADB-700032 %1sent to %2


AEADB-700033 %1


AEADB-700034 Bad date encountered: %1

errorRole Adapter Check your dateTime-related message data and make

sure it is in the correct format.

AEADB-700035 Parameterized subject %1 exceeds TibRv maximum subject length of %2

errorRole Adapter Shorten a parameterized subject string length.




AEADB-700036 Unrecognized event

errorRole Adapter An unrecognized event received. Disable it if

possible.

AEADB-700037 %1

errorRole Adapter An unexpected error happened internally. Contact

TIBCO Support.

AEADB-700038 Poll for change failed


Check printed database error code.

AEADB-700039 Update sequence Failed


Check the update statement database error code.

AEADB-700041 %1, data = %2


AEADB-700042 Maximum of %1 thread allowed for %2 assuming %3

warnRole Adapter Maximum threads have been exceeded; however, the

adapter runs by assuming the default thread count.

Currently a publisher manager, subscriber manager

and request-response communication can only have

one thread each.

AEADB-700044 Main thread (name: %1, id: %2)


AEADB-700045 %1endpoints %2


AEADB-700046 Confirming request





AEADB-700048 %1Error creating reply message

errorRole Adapter Cannot create an Adapter SDK MTree object for a

reply message. Contact TIBCO Support.

AEADB-700049 %1Request is being handled by thread %2


AEADB-700050 %1Could not start transaction

errorRole Adapter Cannot set autoCommit to false. Check the status of

the database you are trying to connect to and try

again. If it still fails, contact TIBCO Support.

AEADB-700051 Request Reply: Error retrieving %1

errorRole Adapter Missing required "sql" field when sending a request

(rvMsg) to a request-response service for execution.

Reconstruct the request message to include a "sql"

field.

AEADB-700052 %1Error binding variables

errorRole Adapter Check the request message format. For a given field,

make sure the data type in the message is the same as

defined in the database.

AEADB-700053 %1Reply sent to %2


AEADB-700054 %1Error sending reply to %2 - %3

errorRole Adapter TIBCO Rendezvous failed to send a reply message to

the request client. Report this error text to TIBCO

Support.

AEADB-700055 %1Failed to create sender for reply

errorRole Adapter TIBCO Rendezvous failed to create a reply sender.

Please report this error text to TIBCO customer

support.




AEADB-700056 RequestReply: No reply name. Not sending reply

errorRole Adapter Specify a reply-subject when defining an adapter

request-response service.

AEADB-700057 %1Error retrieving bind position

errorRole Adapter Check the request message format. For a given field

in the message, make sure it is present in the

database.

AEADB-700058 Stopped thread (%1)


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


AEADB-700063 %1starts


AEADB-700064 %1Request: %2

debugRole Adapter

AEADB-700065 %1Reply: %2

debugRole Adapter

AEADB-700066 Load catalog table %1


AEADB-700071 Duplicate agent found %1

errorRole Adapter The adapter is terminated because a same-named

configuration is started on the same TIBCO

Rendezvous network. For more information, see to

Notes on Configuring an Adapter on page 30.




AEADB-700072 %1MExceptionEvent - Not an RVMSG_RVMSG: %2

errorRole Adapter The adapter received an MExceptionEvent where an

MDataEvent is expected. Check other running

components’ configurations to determine the source

of this message.

AEADB-700073 %1Unknown message format

errorRole Adapter The adapter received a TIBCO Rendezvous message

of unknown format. Check other running

components’ configurations to determine the source

of this message.

AEADB-700074 %1Not processing message

errorRole Adapter The message is not being processed because an error

has occurred. Check for related error messages to

determine what the problem is.

AEADB-700075 %1Error converting event into an Mtree

errorRole Adapter A conversion error occurred in the Adapter SDK

layer. The message may be corrupted or of a wrong

format. Check the Adapter SDK error message if any

to determine what the problem is.

AEADB-700076 %1CM sender: %2, CM sequence number: %3

debugRole Adapter

AEADB-700077 Received message altered:


AEADB-700078 Received message discarded by alterMsgSub()


AEADB-700079 %1Unable to create AE object from the message: %2

warnRole Adapter An unpacking error occurred in the Adapter SDK

layer. The message may be corrupted or of a wrong

format. Check the Adapter SDK error message if any

to determine what the problem is.




AEADB-700080 Received its own message. Discarding.


AEADB-700081 Batch confirming %1 messages


AEADB-700082 RequestReply: Bind argument %1 must include a table name

errorRole Adapter The format of the Bind argument name should be

tablename.columnname. This message will not be

processed.

AEADB-700083 Published message on %1


AEADB-700084 ADB_SEQUENCE class %1 not supported

errorRole Adapter The class type of ADB_SEQUENCE can only be

either string or i4. Make sure the class type of the

ADB_SEQUENCE column of the publishing table is

specified correctly in the repository.

AEADB-700085 Received ADVISORY %1


AEADB-700086 Publisher batch confirm timeout


AEADB-700087 %1 method invoked


AEADB-700088 Unknown driver %1

errorRole Adapter The adapter currently only supports ODBC drivers

(including the IBM client access driver).

AEADB-700089 %1Request received from %2





AEADB-700090 Database error updating %1

errorRole Adapter An error occurred while updating the publishing

table. This is a fatal error and the adapter will

terminate. Use the error returned by the database to

determine how to solve the problem.

AEADB-700091 Publishing ADBOPAQUE format not supported

errorRole Adapter The adapter currently does not support publishing in

opaque format.

AEADB-700092 Keeping on original subject token %1


AEADB-700093 Binding data to insert placeholders


AEADB-700094 Polling for database change


AEADB-700095 Terminating agent


AEADB-700096 Unable to insert %1 into list

errorRole Adapter Wildcard TIBCO Rendezvous subject names are not

currently supported for preregistered listeners.

AEADB-700097 Updating CM sequence failed

errorRole Adapter Currently not used.

AEADB-700098 %1Error binding parameter %2

errorRole Adapter There was a database error that occurred while

binding parameters to a SQL statement. The message

will not be processed. Use the database error if any to

determine what the problem is.




AEADB-700099 RequestReply: Error retrieving value for parameter %1

errorRole Adapter A request has no value specified for input parameter

%1. Add a (data, rvmsgData) field to the [Bind Data]

of the request.

AEADB-700100 Received message:


AEADB-700101 Transaction rollback failed

errorRole Adapter The database was unable to rollback the transaction.

Use the error returned by the database to determine

how to allow this transaction to roll back.

AEADB-700102 Database object %1 not found

errorRole Adapter The database object was not found. Check to see if

the object really exists (perhaps in another schema)

and if you have permission to access it.

AEADB-700103 %1Unknown column type: %2 for field: %3. Ignoring

warnRole Adapter The type %2 is an invalid AE class type. For this

particular situation, the adapter will skip this attribute

and continue processing. Check in the repository for

attribute %3 and change the class type to a valid AE

class type.

AEADB-700104 Insert into the exception table failed

errorRole Adapter There was an error inserting into the exception table.

This is a fatal error and the adapter will terminate.

Use the error returned by the database to fix the

inserts into the exception table.

AEADB-700105 %1%2 are not supported.

errorRole Adapter These AE/TIBCO Rendezvous data types are

currently not supported by the adapter. Use only

supported data types to represent this field instead;

for example, a string or binary.




AEADB-700106 No data fetched for %1


AEADB-700107 New SQL: %1


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


AEADB-700109 Error executing bulk insert of %1 rows for %2

errorRole Adapter There was an error doing the bulk insert into the

table. Use the error returned by the database to

determine how to fix inserts into the table.

AEADB-700110 Statement changed, flush all previous bulk insert rows


AEADB-700111 Reassign data value to insert statement:


AEADB-700112 Cannot find publication entry. Not publishing message.

errorRole Adapter Internal error. Contact TIBCO Support.

AEADB-700113 Error retrieving column %1

errorRole Adapter The adapter could not retrieve this attribute from the

message. Make sure the incoming message contains a

value for this attribute.

AEADB-700114 %1

errorRole Adapter Internal error. Contact TIBCO Support.

AEADB-AEADB

_700301

Error executing listen_alert procedure call

errorRole Adapter Check the corresponding database error.




AEADB-AEADB

_700302

Error preparing listen_alert procedure call, stop alerter thread

errorRole Adapter Check if the listen_alert procedure exists in the

database and if the user has authorization to execute

it.

AEADB-AEADB

_700303

Listen_alert procedure call not found, stop alerter thread



it.

AEADB-AEADB

_700304

Cannot stop alerter successfully, stop_alerter_agent call failed.



it.

AEADB-AEADB

_700305

Error registering alerter, config_alerter procedure call failed, stop alerter thread

errorRole Adapter The alerter failed to add the AQ subscriber. Check if

the AQ database objects are configured properly in

the database and if the user has authorization to

access it

AEADB-AEADB

_700306

Error unregistering alerter, cleanup_alerter procedure call failed.

errorRole Adapter The alerter failed to remove the AQ subscriber.

Check if the AQ database objects are configured

properly in the database and if the user has

authorization to access it

AEADB-AEADB

_700307

Stopped ALerter


AEADB-890001 AEADB-CONN-RETRY

infoRole Adapter Reconnect attempt %1 for service %2.

AEADB-890002 AEADB-CONN-RETRYSUCCESS

infoRole Adapter Reconnect succeeded on attempt %1 for service %2.

AEADB-890003 AEADB-CONN-RETRYFAIL




warnRole Adapter Reconnect failed on attempt %1 for service %2 --

will retry in %3 milliseconds. Make sure it is possible

to establish an ODBC connection to the database.

AEADB-890004 AEADB-CONN-PUBDUP

warnRole Adapter Connection reestablished for the publisher - message

may be a duplicate of a previously published

message.

AEADB-890005 AEADB-CONN-REQERR

errorRole Adapter The request received could not be processed due to

connection errors. Make sure it is possible to

establish an ODBC connection to the database.

AEADB-890006 AEADB-CONN-STOP

errorRole Adapter Adapter stopping due to persistent connection errors.

Please check your database and restart adapter. Make

sure it is possible to establish an ODBC connection

to the database.

AEADB-890007 AEADB-CONN-SVCSUSPEND

infoRole Adapter Adapter suspending service %1 due to persistent

connection errors.

AEADB-910004 AEADB-STARTUP-4

errorRole Startup Startup Error. SDK Exception %1 occurred in the

adapter initialization while creating the

MAppProperties object. The Repository URL is %2

and the Configuration URL is %3. Please see SDK

documentation for Repository URL and

Configuration URL specification. Please cut and

paste from SDK documentation for the above.





errorRole Startup Startup Error. SDK Exception %1 received on

starting the adapter after initialization. The

Repository URL is %2 and the Configuration URL is

%3. Please verify your repository and environment

settings. See the User Guide documentation.


errorRole Startup Startup Error. Unable to create a connection with the

target database using the dsn %1. The database error

is: %2 Terminating adapter. Please verify your

repository settings for the validity of connection

parameters. See the User Guide documentation.

AEADB-920001 AEADB-SUB-1

errorRole Subscriber Subscription error. Subscription service %1 listening

on %2 received an unexpected event: %3. The


%5. Check the configuration of the application that is

publishing the event and make sure that it matches

the inbound event definition for the above

subscription service. Please see User Guide for

details on configuration of subscription service.


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


%6. Check the configuration of the application that is

publishing the event and make sure that it matches

the inbound event definition for the above

subscription service. Please see User Guide for

details on configuration of subscription service.



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.






on subject %2 could not get the class description of

%3. The Repository URL is %4 and the

Configuration URL is %5. Please check the

repository configuration for this service. Please make

sure the classes to be used by this service are

accessible in the repository. Please see User Guide

for details on how to configure, run and test the




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.



on %2 could not send response %3 on reply subject

%4. The SDK error is %5. Please check your

repository settings for the publish endpoint of this

subscription service. Please see user guide on how to

configure the subscription service.

AEADB-930002 AEADB-PUB-2

errorRole Publisher Publication error. Publication service %1 with

publication subject %2 encountered database error:

%3 while trying to create publish event with schema

%4. Database is %5. The database command is %6.

Make sure that the publication service is configured

properly. Please look at the database error, note the

database error code and consult with your database

documentation.




AEADB-930003 AEADB-PUB-3

errorRole Publisher Publication error. Publication service %1 with

publishing subject as %2 received event database

%3. It failed while converting the event to

"Minstance" as it could not get the class description

for %4. Repository URL is %5 and the Configuration

URL is %6. Please verify the configuration of the

publication service and check that the schema/class

definitions are present in the repository. Please see

User Guide for details on how to configure a

Publication service.

AEADB-940001 AEADB-REQRESP-1

errorRole Request_Respo

nse_Server

Request-Response error. Request-Response service

%1 listening on %2 received unexpected null data in

incoming request. Expects object %3. The


%5. Please check the configuration of the application

that is requesting the event and make sure that it

matches the inbound event definition for the above

RequestResponse service. Please see User Guide for

details on configuration of RequestResponse service.



nse_Server


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



nse_Server


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






nse_Server


%1 listening on subject %2 receive an error while

sending Data on Reply Address %3. Error Message

%4. Please check whether the request client is alive

or message transport is functioning.

AEADB-990002 AEADB-SHUT-2

errorRole Shutdown Shutdown error. SDK cleanup exception = %1.



| 325

Appendix C Adapter Properties File

Topics


• Properties File Format, page 327

• Runtime Adapter Properties File Parameters, page 328

• Obfuscating or Encrypting a Password in the Properties File, page 341

• Using Hints, page 343


326 | Appendix C Adapter Properties File

Overview

The runtime adapter parses a properties file at startup. The default runtime adapter

properties file is named adbagent.tra.

The default properties file is located in the TIB_ADADB_HOME\bin subdirectory.

Each line in a properties file is a single property. Each property consists of a key and a

value. The key starts with the first non-whitespace character and ends at the first "=", ":",

or whitespace character. The value starts at the first character after the equal sign (=). For

example:

tibco.configurl=/tibco/private/adapter/test/config/config1

tibco.repourl=tibcr://TEST_PROJECT

tibco.username=admin

tibco.password=samplePassword

tibco.clientVar.service=7600

tibco.clientVar.daemon=tcp:7600

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


Properties File Format | 327

Properties File Format

The following restrictions apply to properties:

• The "!" character may not be used as a comment line indicator. Only the "#" character

is recognized.

• The line continuation character is ignored (a value must fit on a line).

• The key may not contain any of the termination characters. Java allows termination

characters by escaping the value with a preceding "\" character. TIBCO ActiveMatrix

Adapter for Database does not support this syntax.

Tagging Values for Obfuscation

The presence of a "#" character as the first character in a value (not the key) indicates that

the value has been obfuscated or is to be obfuscated. The obfuscation command-line tool

prompts for values to be obfuscated when it encounters a value with "#" as the first

character in the properties file.

When the obfuscate tool is run, it rewrites the properties file with the obfuscated value in

place. See Obfuscating or Encrypting a Password in the Properties File on page 341 for

more information.



Runtime Adapter Properties File Parameters

Properties are in two categories: Required Properties and Additional Properties. These are

listed and described below.

Required Properties

In order for a properties file to be used with a runtime adapter, the following properties

must be correct for the adapter’s configuration.

All paths inside a properties file, including Microsoft Windows directory names, must use

forward slashes.

Table 48 Required Runtime Adapter Properties File Parameters

Property Description

tibco.repourl repourl The absolute pathname to the local repository where the

adapter instance is defined. For example:

C:/TIBCO/LocalRepositories/repo.dat

For a remote project, the repourl value should use the form

tibco.repourl tibcr@name where name is the repository name.

For example:

tibco.repourl tibcr@ADBRepoDefault

For Unix systems, the path separator should include a single

slash, "/". For example: /local/tibco/repo/repo.dat

tibco.configurl relative_path

or

tibco.configurl absolute_path

The location of the adapter service inside the project file. If a

relative path is specified, the adapter service is assumed to be

under the default area in the project file (/tibco/private/adapter/).

For example, the following value connects to an adapter

service named adbpub in the /tibco/private/adapter/ directory:

tibco.configurl adbpub

If an absolute path is specified, the adapter instance is looked

up in the repository as defined by the argument. For example:

tibco:configurl /tibco/private/adapter/adbpub

tibco.instanceid instance name The name of the adapter instance.

The length of the name cannot be larger than 80 characters.

tibco.clientVar.adb.password The password to connect to the targeted database. This can be

obfuscated using the instructions in Obfuscating or

Encrypting a Password in the Properties File on page 341.


Runtime Adapter Properties File Parameters | 329

Additional Properties

You can modify the following parameters as necessary. Properties that start with ntservice

are available only on Microsoft Windows platforms. The following table is alphabetically

sorted by the property name.

application.args The properties (.tra) file to pass to TIBCO ActiveMatrix

Adapter for Database. For example:

application.args adbagent -system:propFile

C:/tibco/adapter/adadb/6.0/bin/adbsub.tra

application.start.dir The pathname of the adapter to start. For example:

application.start.dir C:/tibco/adapter/adadb/6.0/bin/

application.library The name of the dynamic library of the adapter instance.

application.ase.library The name of the dynamic library of the adapter service

engine instance.

This property is used only on the UNIX platforms.

Table 48 Required Runtime Adapter Properties File Parameters (Cont’d)


All paths inside a properties file, including Microsoft Windows directory names, must use

forward slashes.

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 1 of 12)


adb.publication_service_name.lookback Enables the adapter to look for remaining records if it

did not fetch the number of records specified by the

pollingBatchSize parameter for the publisher.

For example, if the publisher service name is

ADBPublisher, the property name is

adb.ADBPublisher.lookback.

adb.publication_service_name.preRegister

edListeners

Preregisters RVCM names for the specified subjects.

For example,

adb.ADBPublisher.preRegisteredListeners=adb.sub1:rvcm1,ad

b.sub2:rvcm2

preregisters RVCM name rvcm1 to subject adb.sub1,

and RVCM name rvcm2 to subject adb.sub2.



adb.table_name.poll.hint. hint_value This feature helps improve the performance of your

queries. This feature is only supported by Oracle and

SQLServer databases.

See Using Hints on page 343 for more information.

adb.addCustomHawkMethodsToClassMAgent

on|off The property is not set by default. Setting the

property to off disallows adding custom methods to

the adapter’s standard microagent. Setting to on

allows custom methods to be added to the adapter’s

standard microagent.

adb.as400.defaultLibrary The default iSeries library to be accessed.

adb.as400.library The name of the library where the programs will be

created.

adb.batchPubStatusUpdates on|off -max_rows When adb.PollingBatchSize is used, this optimizes

publishing performance by batching message status

updates to the publishing table. Do not use this option

when messages are published using a parameterized

subject name.

If an adapter instance stops before a batch update is

performed, the status column is not updated. As a

result, duplicate messages are published when the

instance is restarted.

adb.createMutextable When set to off, the adapter does not create the mutex

table that is used in the fault tolerance mode.

The mutex table can be manually created before

starting the adapter with the following SQL

command:

CREATE TABLE <mutex_table_name> (COL1 char(1))

The default value is on.

adb.customScaleForNumberType This property sets the default scale of Oracle

Number(empty) datatype.

adb.database The DB2 database name for OS390. The adapter uses

the value of this property when creating the table

used by the fault tolerance functionality.





adb.debug The debug printing level. If not specified, the default,

0, is used. Possible values are:

0 - No debug information displayed.

1 - SQL commands executed with the database display.

2 - In addition to 1, the ODBC data source for each

SQL command displays.

3 - Displays values for all ODBC placeholders.

adb.disableTerminationSubject When this property is set to on, the adapter does not

terminate on receiving a termination subject

message.

adb.dsn ODBC system data source name. If not specified, the

system data source name is read from the repository.

adb.encoding The encoding to use. Required when using a

non-ASCII character set, as in globalization. See

Overview, page 228, and Relevant Environment

Settings, page 237, for more information.

Valid Values

The corresponding TIBCO Designer selection is in

parenthesis.

(no value) defaults to ASCII

ibm-1370 (Big5 )

tibx-eucJP ( EUC-JP)

ibm-1386 (GBK )

LATIN_1 (ISO8859-1 )

ibm-949 (KSC-5601 )

ibm-943 ( Shift_JIS (CP943))

tibx-943 ( Shift_JIS (TIBCO))

UTF8 ( UTF8)

adb.groupsize Specifies the number of rows to publish in a single

message. Overrides the Group Size setting in the

publication service configuration.





adb.heartbeat The time interval, in milliseconds, the secondary

instance(s) waits before it tries to lock the table

specified by the adb.mutex property.

If neither the adb.primary.heartbeat or

adb.secondary.heartbeat properties are specified, the

value of this property will be used as both the

primary and secondary heartbeat.

Default value is 10000ms

adb.jmscompress on|off Applies only to the publication service with JMS

transport.

Either on or off. The default value is off, which

indicates that JMS messages will not be compressed.

adb.maxLongLen The buffer size. Used for long data types such as

BLOB.

adb.maxQuery The maximum number of queries the secondary

instance would send to the primary to determine if

the primary instance is still active. Default value is

3.

adb.mutex This is a table that is used by the fault tolerance

functionality. When an adapter instance starts and

this property is present, it will try to issue an

exclusive lock on the named table before processing

any messages.

The adapter instance that is able to lock this table is

considered a primary instance. All instances that are

not able to issue an exclusive lock on this table are

considered secondary instances.

The table name is shared within a fault tolerance

group. For example,

adb.mutex FTtablename.

adb.noDupDetection Disables detection of duplicate configurations.

Either on or off. The default value is off which

indicates that duplicate configurations will be

detected.

adb.originalSchema The design-time table objects schema.





adb.password Password for the user account used to access your

database. If not specified, the password stored in the

repository is used.

adb.payloadOnError on|off This property specifies whether only the error

information or all the logging information is printed

in the log file.

Either on or off. The default value is off. If it is on or

the Generate Payload On Error checkbox on the

General tab is checked when configuring an adapter

instance, and the Log Info Messages checkbox on the

Logging tab is unchecked, only the error log

information will be printed.

adb.perfMon on|off Either on or off. The default is off.

adb.PollingBatchSize Applies only to publisher instances. Limits the

amount of messages to be picked up. The value

indicates the number of parent rows to fetch for a poll

interval. The default value, 0, indicates that all new

rows should be fetched.

adb.PollingInterval Specific polling period. Applies only to publisher

instances. If not specified the default, 10, 000

milliseconds, is used.

adb.PollingCommitForDB2 Either on or off. The default is off.

adb.primary.heartbeat When using the adapter in the fault tolerance mode,

this is the time interval (in ms) for which the adapter

waits before issuing a dummy select statement.

This select statement is used to maintain the

connection that holds the lock.

Default value is 10000.





adb.pubBatchConfirmSize Applies only to publisher instances with publications

that use certified message delivery. Optimizes

performance by batching message status advisories to

the publishing table. The value indicates the number

of advisory messages to include in a single batch.

Do not use this option when messages are published

using a parameterized subject name.

Note: If an adapter instance stops before a batch

update is performed, the status column is not

updated. As a result, messages that were successfully

published might still have a status of P (pending) in

the publishing table when the adapter instance is

restarted. In this case, the ledger file contains the

correct status information. A smaller value for this

property decreases this risk.

adb.pubBatchConfirmTimeout Applies only to publisher instances with publications

that use certified message delivery. This property

specifies the number of milliseconds to wait before

updating the status column. After this interval, an

update is performed even if the batch size value is not

reached. The default value is 10,000 (10 seconds). A

value of 0 means that no timeout interval is used.

Do not use this option when messages are published

using a parameterized subject name.

Note: If an adapter instance stops before a batch

update is performed, the status column is not

updated. As a result, messages that were successfully

published might still have a status of P (pending) in

the publishing table when the adapter instance is

restarted. In this case, the ledger file contains the

correct status information. A smaller value for this

property decreases this risk.

adb.publishChildData Either on or off. Applies only to publisher instances.

Enables publishing of table rows related to the source

publishing table. By default, related table rows are

not published.

adb.RequestResponseMaxRows This property specifies the maximum number of rows

to fetch. This can be used limit the memory usage of

the adapter. The unfetched rows will be ignored by

the adapter.





adb.requestResponseThreads The number of threads used by the Request/response

Service. The default value is 1.

adb.RetryTotal Total number of reconnection attempts.

adb.runtime.publisherSchema The runtime publisher table schema. This overrides

the adb.runtime.schema setting. This can be used if the

user has a different schema for the publishing table

than the other table objects, such as the source table.

adb.runtime.schema The runtime table objects schema.

• If adb.originalSchema is specified, the adapter

will compare the adb.originalSchema with the

prefix of the table objects. If they are the

same, the adapter will replace the

design-time schema with this runtime

schema. Otherwise, no action will be taken.

• If adb.orignalSchema is not specified, the

adapter will append this runtime schema to

all table objects that do not have any

schema specified at design time.

adb.rvAdvisoryNoLog on|off This property specifies whether RV advisory

messages are be logged in the adapter log files. The

default value is off.

adb.rvMaxQueueSize Applies only to subscriber instances. Maximum

number of messages to allow in the TIBCO

Rendezvous event queue. The default value is 0,

which means no limit is placed on event queue size.

adb.secondary.heartbeat The time interval that secondary instance waits

before sending the next query message to detect the

existence of the primary instance.

Default value is 10000.

adb.setClientInfo on|off When set to on, the adapter will call

SET_CLIENT_INFO to set the database session

client information.






adb.setEmptyStringNullForRvMsg on|off Either on or off. Specifies whether the RVMSG fields

of an empty string are treated as NULL or "" (empty

strings). The default setting is off.

If the property value is set to on, empty strings are

treated as NULL and if the property value is set to off,

empty strings are treated as empty strings if the

database allows it.

adb.SleepBetweenRetries Milliseconds of sleep between two reconnection

attempts.

adb.stmtCache The number of cache statements for a generic RPC

request/ reply service.

The number of statements that the adapter will cache

so that it will execute the statement directly for

repeated requests. If the cache is full, the adapter will

remove the oldest message from the cache and will

add the new statement. The default setting is off.

Example, adb.stmtCache 10

adb.subBatchCommitSize Applies only to subscriber instances. The number of

messages to batch before invoking a commit

operation. The default is 0(zero).

Note: if messages greater than 32K are published,

batching is automatically turned off.

adb.subBatchCommitTimeout Applies only to subscriber instances. The amount of

time that can expire after which a batch commit

operation is invoked. If not specified the default

value of 10,000 milliseconds is used.

adb.subBulkInsertSize Applies only to subscriber instances. All incoming

messages to insert are stored until this size is reached.

Then a bulk insert operation is performed on the

destination table. This value must be less than or

equal to the value specified for

adb.subBatchCommitSize, if used. The default value is 1.

If an update statement is published while messages

are being batched, the bulk insert is performed

regardless of whether the size value has been

reached. After records have been inserted, the update

operation is performed.

Note: Do not use this option if LONG, LONG RAW,

image, or varbinary records are published.





adb.tablespace The DB2 tablespace name for OS390. The adapter

uses the value of this property when creating the table

used by the fault tolerance functionality.

adb. taskBackLogLimitInBytes The scheduler stores tasks in a queue. This property

limits the maximum size of that scheduler task queue

by the number of bytes. The properties can control

the memory usage on the adapter side.

This value must be an integer. The default value is

unspecified, which indicates that there is no limit to

the size of the scheduler task queue.

adb. taskBackLogLimitInMessages The scheduler stores tasks in a queue. This property

limits the maximum size of that scheduler task queue

by the number of messages. The properties can

control the memory usage on the adapter side.

This value must be an integer. The default value is

unspecified, which indicates that there is no limit to

the size of the scheduler task queue.

adb.terminateOnPubFail Specifies that if publication fails, the agent will

terminate after the status has been updated to ’F’. The

default value is off.

adb.traceOldMessages on|off Either on or off.

adb.unicode The unicode setting.

The default value is UTF8.

Valid values are UTF8 and UTF16

Additionally, the following options have to be set:

On Microsoft Windows, select the Enable N-CHAR

option from the Advanced tab when configuring the

ODBC system data source.

On UNIX platforms, set the EnableNcharSupport option

to 1 in the ODBC initialization files.

See the ODBC driver documentation for more

details.

For Microsoft SQL Server, set the value of this

property to UTF16.

adb.useBetweenClause This property disable the use of the BETWEEN

clause in the select query of the publisher.






adb.useExceptTable on|off Enables the use of the exception table. The exception

table is defined when a subscription is created.

adb.user Database account name used by the adapter to access

your database. If not specified, the database

username stored in the repository is used.

adb.useSqlColumns on|off Either on or off. Specifies whether the adapter should

use SQLColumns() instead of a SELECT query to

retrieve metadata for a table.

Note: Typically, a SELECT * FROM <table> WHERE 1>9

(which returns no results) is the fastest way to get

metadata for that table. However, on some databases,

such as DB2 OS390 v6, the database is not optimized

for this query and a full table scan can result. Using

an ODBC API call, SQLColumns(), can avoid this.

adb.verbose on|off Verbose mode. Print all available information to the

console window or log file location. By default the

verbose mode is off.

adb.wchar Default is SQL_C_CHAR. Required when using

UTF-8 encoding with an adapter that uses a

DataDirect driver to retrieve UTF-8 data from the

database.

If the adb.unicode is set, this property is set by

default to SQL_C_BINARY to retreive unicode data.

ntservice.account Username under which to run the Windows Service.

You can use this property to initially set the account

for the service, but once the service is installed, use

the Services control to change the user account of

services.

ntservice.binary.path.absolute Absolute path to the executable that is run when the

service is started. For example:

ntservice.binary.path.absolute

C:/tibco/adapter/adadb/6.0/bin/adbagent.exe

ntservice.dependencies The number of dependencies.





ntservice.displayname Name to display in the Services control for this

Windows Service.

This property is useful if you wish to have multiple

Windows Services for the same executable. That is,

you may wish to have two adapter running on the

same machine. By specifying different service names

and display names for the adapters, you can

accomplish this.

ntservice.interactive true|false Either true or false. Specifies whether the Windows

Service is interactive. Set to false if you are not using

a system account.

ntservice.name Name for this Windows Service.

This property is useful if you wish to have multiple

Windows Services for the same executable. That is,

you may wish to have two adapters running on the

same machine. By specifying different service names

and display names for the adapters, you can

accomplish this.

For example:

ntservice.name adapter_instance_name

ntservice.password Password for the username in the ntservice.account

property.

You can use this property to initially set the password

for the user account, but once the service is installed,

use the Services control to change the password.

ntservice.starttype manual|automatic Start type for this Windows Service. Either manual or

automatic. For example:

ntservice.starttype automatic

You can use this property to initially set the start type

for the service, but once the service is installed, use

the Windows Services control to change the start type

of services.





tibco.clientVar Runtime values for global variables defined inside

the repository. This value takes precedence over any

global value set in the repository. Substitution takes

place at runtime.

You append the global variable to tibco.clientVar, then

give its value. For example, a global variable named

DirLedger is specified as follows:

tibco.clientVar.DirLedger

C:/tibco/adapter/adadb/6.0/myledger

Do not include the % character of substitution

variables. For example, to set

%%RvDaemon%%="tcp:7500", use tibco.clientVar.RvDaemon

"tcp:7500".

tibco.username

tibco.password

User name and password used by the repository

server to access the project. The password can be

obfuscated using the instructions in Obfuscating or

Encrypting a Password in the Properties File on

page 341.

-version Displays a banner with version information, then

exits. This option is for troubleshooting purposes

only.




Obfuscating or Encrypting a Password in the Properties File | 341

Obfuscating or Encrypting a Password in the Properties File

Password Handling

At design time, the adapter uses a password to connect to the backend application and

fetch metadata. At runtime, the adapter uses a password to connect to the back-end

application and interoperate with it. If you create a 4.x configuration using TIBCO

Designer 5.5, and use the configuration with a 4.x adapter version, some special

considerations are required for security.

If you plan to run the adapter locally, define the runtime password value to be a global

variable. Before starting the adapter, include the runtime password as client variable in the

adapter's .tra file and obfuscate it using obfuscate tool. For example, if the password value

is defined as %%myPassword%%, create a global variable named myPassword in the global

variables section with no value and include the following entry in the adapter's TRA file:

tibco.clientVar.myPassword

Obfuscating a Password

The runtime adapter needs a password to access the backend database. If you have

unchecked the Remember Password checkbox in the Design-time Connection tab, the

global variable %%adb.password%% is saved in the project. For runtime, you open the .tra file

and add the password in clear text in the tibco.clientVar.adb.password=#password property. You

can use the obfuscate tool to hide this password so it cannot be viewed by unauthorized

users.

To obfuscate the password:

1. Using TIBCO Designer, open the adapter configuration and display the Design-time

Connection tab.

2. Uncheck the Remember Password checkbox.

3. Apply the changes and save the project. This saves the global variable

%%adb.password%% as the value of the password property in the project.

Do not set the password by typing Password in the Global Variables section for adapter

configurations that are set to AE Version 4.0 or AE Version 5.0 (in the Version field of the

Configuration tab) or any intermediate version.

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

password.



4. In the runtime adapter properties file, verify that the tibco.clientVar.adb.password=#password

property is defined in clear text.

5. Run the obfuscation tool supplied with the adapter with the properties file. This tool is

named obfuscate.exe and resides in the TIBCO_HOME\tra\version\bin directory.

The command syntax is:

obfuscate TRA_file_path

where TRA_file_path is the absolute pathname of the adapter properties file that

contains the tibco.clientVar.adb.password=#password property.

For example, on Microsoft Windows :

C:\tibco\tra\version\bin>obfuscate C:\tibco\adapter\adadb\version\bin\adbagent.tra

The password is now obfuscated and you can start the adapter with the changed

properties file.

Encrypting a Password

Encryption is only supported for version 5.x adapters and higher. If you have a property in

a properties file the needs to be encrypted, follow these steps:

1. In the property file, add the #! characters in front of the value you wish to encrypt. For

example:

Repo.serverPassword = #!mysecret

2. Invoke the obfuscate utility from the command line:

TIBCO_HOME/tra/version/bin/obfuscate.exe --propertyfile=property_file_name

The next time you open the property file, mysecret will have been replaced with a random

sequence of characters.


Using Hints | 343

Using Hints

Hints help improve the performance of your queries. When the adapter publication service

executes a poll operation to fetch data from a table, using hints greatly enhances the query.

Usage

To use hints add the following line to the adapter TRA properties file:

adb.table_name.poll.hint hint_value

where, table_name is the name of your table and hint_value is the hint.

Note that in this release hints are only supported in Oracle and SQL Server databases.



Examples

a. To force an index scan when polling in an Oracle database, set the property as

follows:

adb.p1.poll.hint /*+INDEX(P1,P1_INDX)*/

where p1 is the publisher table, and P1_INDX is the index created on the publishing

table.

The adapter will execute this select query on the publishing table:

SELECT /*+INDEX(P1,P1_INDX)*/ * FROM P1 WHERE ID = ?

b. To use NOLOCK hint when polling in a SQL Server database, set the property as

follows:

adb.p1.poll.hint WITH(NOLOCK)

where P1 is the publisher table.

The adapter will execute this select query on the publishing table, but will not issue

shared locks or honor exclusive locks:

SELECT * FROM P1 WITH(NOLOCK) WHERE ADB_L_DELIVERY_STATUS =’N’

c. To force an index scan when the adapter fetches records from a child table set the

property as follows:

adb.C1.poll.hint /*+INDEX(C1,C1_INDEX)*/

where C1 is the child table, and C1_INDEX is the index created on the child table.

The adapter will execute this select query on the child table:

SELECT /*+INDEX(C1,C1_INDEX)*/ * FROM C1 WHERE ID = ?


| 351

Index

Symbols

_ 30, 167

. 168

* 167

> 167

A

access to DB2 AS/400 tables 69

adapter

changing a configuration 31, 199

component (operation) information through TIBCO

Hawk 253

error messages when changing a configuration 32

naming restrictions 30

size limitations 30

stopping 30

tracing 194

unicode setting 343

adapter configuration, changing 31, 199

Adapter Services folder 6

adapter setting client info 340

ADB_ERROR_TEXT 154

ADB_ERROR_TIME 155

time zone 155, 157

ADB_L_CMSEQUENCE 148

ADB_L_DELIVERY_STATUS 148

ADB_OPCODE 147, 154

ADB_REF_OBJECT column in the publishing table 175

ADB_SEQUENCE 146

ADB_SET_SEQUENCE 146

ADB_SOURCE 153, 153

ADB_SUBJECT 146

ADB_TIMESTAMP 147

timezone 147

ADB_UPDATE_ALL 147, 154

adbDateTime 174

adbPreCommit() 185

adding

listeners 171

adding a sequence for parent-child 177

adding an association for parent-child 178

advanced folder 6

agents 240

alerter

on Sybase SQL Server 110

alerts 240

auto-discovery process, TIBCO Hawk 242

B

binary type 169

bind statements 121

C

callout library 183

certified message delivery

exception handling 291

moving ledger files 173

preregistering listeners 171

changes from the previous release xvi

Class Microagent Name field, adapter 60

closure field 120

column names in an exception table 156

column names, reserved prefix 31

columns, maximum number 30

command line arguments 254


352 | Index

commands

adbagent 108, 112

Connect 41, 45

copy 107, 111

cp 110

isql 107, 108, 110, 111, 112

select 22, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23,

23, 23, 23, 24, 24, 24, 24, 24, 24, 24, 24, 25, 25, 25,

25, 26, 26, 26

sqlplus 19, 26, 105, 106

tibrvsend 25

commit_and_notify_table 103

CONFIG_HOME xviii

configuration properties, retrieving through TIBCO

Hawk 254

custom RPC operation 131

customer support xxi

D

dat file format 16

data source, ODBC

using 335

database errors, capturing 154

database type mapping 167

Date types 169

date/time values 174

dateTime 164

DB2 on OS/390 trigger statements syntax 202

debug, adapter option 334, 334

delete trigger 67

Destination 167

distributed queues 138, 218

dot character 168

dsn, adapter option 335

E

ENV_NAME xviii

error messages about database cleanup 32

examples

REF cursor procedure 143

Exceed FAQ 293

exception table

structure of 154

exception table, column names in 156

F

fault tolerance 337

file format

dat 16

VC 16

Float data type 169

G

global variables 32

setting for monitoring 59

L

ledger files

location 173

moving 173

publication size status 338

publication timeout status 339

retrieving information through TIBCO Hawk 263

listeners, adding 171

load balancing

across adapters 138, 218

in an adapter 136, 215

Log File field, adapter 53

log file options 194

log files location 55

Log to Standard field, adapter 53

LONG data type 77

loop detection

column used for 153


Index | 353

M

mapping database types 167

metadata 7

microagent methods supported 247

Microagent Session field, adapter 60

multiple file project 208

N

naming restrictions

adapters 30

database columns 31

publishing table 76

subjects 167

notify procedure

on Microsoft SQL Server 107

on Sybase 110

notifytable procedure

on Microsoft SQL Server 107

on Sybase 110

NULL attributes 83

O

obfuscation 331

P

palettes 6

parameterized subject 168

binary type 169

Date types 169

Float type 169

illegal characters 169

parameters

AE Type 68, 84

Child Table Mapping 85, 86

Class Reference 80, 89, 94

Deploy On Save 31

Do Not Generate Triggers 76

Enable Loop Detection 76

Endpoint Reference 80, 89, 94

Join To 68, 84

Publishing Table 76

Reply Subject 94

Subscriber Bulk Insert Size 50

Table Name 85, 86

Tables and Columns 68, 84

Type 68, 84

Update Mode 76

Update Trigger 68

Use? 68, 84

User Key 68, 84

parent-child association 178

parent-child sequence 177

password property 346

PL/SQL procedure for REF cursor 143

preregistering listeners 171

publications

size limitations 30

publish-child-data, adapter option 339

publishing

by reference 77

source data 175

publishing table

columns in 146

name size 76

restrictions for 77

Q

quality of service

and load balancing 138, 218

queue member load 139, 219


354 | Index

R

record size, limitations 30

REF data type 143

reference object location 175

repository instance 7

request

defined 118

request/response

load balancing for 138, 218

using 116

using multiple threads 136, 215

response defined 119

reviewLedger, TIBCO Hawk method 263

RPC programs, client 133

rv_Rpc() 122

rv_Send() 122

rv_SendWithReply() 122

RVMSG_DATETIME 164

RVMSG_INT 164

RVMSG_OPAQUE 164

RVMSG_REAL 164

RVMSG_STRING 164

S

schema changes affecting adapter configuration 32

schema data 7

schemas

for related tables 69

See 168

sequence number 146

source data publishing 175

source data publishing example 181

source table

loop detection column 153

SQL statement terminator 202

SQL_BATCHRETURN class, structure of 129, 129

SQL_BIND class, structure of 130, 130

SQL_OPS class, structure of 127

SQL_RESULTSET class, structure of 128

SQL_RETURN class, structure of 128

SQL_ROW class, structure of 128

SQL_STATEMENT class, structure of 130, 130

standard RPC operation 126

starting an alerter on Oracle 103

stopping an adapter 30

sub-batch-commit-timeout, adapter option 341

sub-bulk-insert-size, adapter option 341

subjects

naming restrictions 167

parameterized 168

subscriber 30

using wildcards 167, 171

subscriptions

size limitations 30

wire format for 174

substitution 32

support, contacting xxi

system

configurl command-line argument 332, 332

T

table access problems, overcoming 69

technical support xxi

TIB_ADADB_HOME xviii

TIBCO Hawk

background information 240

enterprise monitor components 240

methods supported 247

Monitoring tab use with 59

TIBCO Hawk methods

getComponents 253

getConfig 254

getRvConfig 257

getStatus 258

reviewLedger 263

TIBCO Rendezvous, retrieving configuration through

TIBCO Hawk 257

TIBCO_HOME xviii

Tracing 296, 296

tracing features 194

Tracing Levels and Fields 297, 297

tracking identifier 296, 299


Index | 355

triggers

no primary key 67

U

underscore character 167

update trigger 67

Use Advanced Logging field, adapter 55

user authority 69

user callout library 183

user schema 102

username property 346

use-trace-file, adapter option 194

V

variable substitution 32

variables 32

version, adapter option 346

W

wildcard subject names 167, 171

TIBCO ActiveMatrix Adapter for Database Configuration and ...

Documents

Transcript of TIBCO ActiveMatrix Adapter for Database Configuration and ...