writing custom rules

TIBCO Hawk Rendezvous Messaging AdapterUsers GuideSoftware Release 4.9November 2010

Important InformationSOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE 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 Rendezvous, TIBCO Adapter, TIBCO AdapterAdministrator, TIBCO Repository, and TIBCO Hawk are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README 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-2010 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| iiiContents

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixRelated Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

TIBCO Hawk Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiThird-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiConnecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv

How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xivHow to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xivHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Functional Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

The TIBCO Rendezvous System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5The TIBCO Hawk System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5AMI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Benefits of Monitoring with the TIBCO Rendezvous System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9Installing on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Uninstalling the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Installing a Custom Adapter as a Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Installing on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Transcript of the Solaris installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 TIBCO Hawk Rendezvous Messaging Adapter Users Guide

iv |

Uninstalling the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 3 Configuring the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Configuration File Elements and Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Specifying Field Names in Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Validating an XML Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Performing XML Consistency Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Starting and Stopping the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Starting the Adapter on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Stopping the Adapter on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Starting the Adapter on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Stopping the Adapter on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Changing the Service Log On Account on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Viewing the Adapter Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 4 Testing the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Verify Sample Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Start the Sample Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Start TIBCO Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Send and Receive a Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Other Sample Adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Chapter 5 Using Adapter Methods in a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Monitor a Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Identify the Logfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Define the Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56View the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Monitor an Applications Heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Define the Subject and Timeout Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Define the Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Chapter 6 Adapter Methods Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Methods Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65getReleaseVersion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66getTraceParameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67setTraceParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68TIBCO Hawk Rendezvous Messaging Adapter Users Guide

| v

getTraceLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69setTraceLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70getMaxThreads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71setMaxThreads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72tibrvsend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73tibrvlisten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74dynamicSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75_onUnsolicitedMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Appendix A Java Pattern Matching Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77Pattern Matching Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Appendix B TIBCO Hawk Service Wrapper for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79Windows Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Installing the Adapter as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Uninstalling the Adapter as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Executing the Adapter as a Windows console application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Executing the Adapter as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85 TIBCO Hawk Rendezvous Messaging Adapter Users Guide

vi |TIBCO Hawk Rendezvous Messaging Adapter Users Guide

| viiTables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiTable 2 TIBCO Rendezvous Features and TIBCO Hawk Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Table 3 Supported UNIX PLatforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Table 4 Download Sites for JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Table 5 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Table 6 Commands to Remove the Adapter on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Table 7 TIBHAWK_AMI Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Table 8 microagent Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Table 9 method Element Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Table 10 inputParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Table 11 valueChoices Element Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Table 12 legalValueChoices Element Attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Table 13 constantParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Table 14 outputParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Table 15 Examples of using Argument{0} in Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Table 16 Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Table 17 JVM Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 TIBCO Hawk Rendezvous Messaging Adapter Users Guide

viii |TIBCO Hawk Rendezvous Messaging Adapter Users Guide

| ixPreface

The TIBCO Hawk Rendezvous Messaging Adapter allow TIBCO Hawk to send and receive custom TIBCO Rendezvous messages. Using XML configuration files, you can specify the subject and message structure to be sent or received for each method, then use TIBCO Hawk to execute the method. The adapter also provides a set of built-in methods to monitor TIBCO Rendezvous messages.

This manual assumes you are familiar with the TIBCO Rendezvous and TIBCO Hawk environments.

Topics

Related Documentation, page x

Typographical Conventions, page xii

Connecting with TIBCO Resources, page xiv TIBCO Hawk Rendezvous Messaging Adapter Users Guide

x | Related DocumentationRelated Documentation

This section lists documentation resources you may find useful.

TIBCO Hawk DocumentationThe following documents form the TIBCO Hawk documentation set:

TIBCO Hawk Installation and Configuration Read this book first. It contains step-by-step instructions for installing TIBCO Hawk software on various operating system platforms. It also describes how to configure the software for specific applications, once it is installed. An installation FAQ is included.

TIBCO Hawk Administrators Guide This manual includes basic descriptions of TIBCO Hawk concepts, instructions for using TIBCO Hawk Display, monitoring strategies with examples, a comprehensive FAQ, and a glossary. All books in the documentation set refer to features explained in this book.

TIBCO Hawk Plug-in for TIBCO Administrator Contains detailed descriptions of the TIBCO Hawk plug-ins accessed via TIBCO Administrator.

TIBCO Hawk Programmers Guide All programmers should read this manual. It covers the AMI protocol, AMI messages, the AMI Workbench development tool, and the TIBCO Hawk security framework and its classes. Programmers should then refer to the appropriate language reference for the AMI API. The TIBCO Hawk Application Management Interface (AMI) exposes internal application methods to TIBCO Hawk.

TIBCO Hawk AMI C Reference Contains detailed descriptions of each datatype and function in the TIBCO Hawk C AMI API.

TIBCO Hawk AMI C++ Reference Contains detailed descriptions of each datatype and function in the TIBCO Hawk C++ AMI API.

TIBCO Hawk AMI Java Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Java AMI API.

TIBCO Hawk Console API Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Console API, a set of Java interfaces that allow you to manage and interact with TIBCO Hawk agents and monitor alerts generated by these agents.

TIBCO Hawk Configuration Object API Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Configuration Object API.

TIBCO Hawk Methods Reference A reference to the microagents and methods used by a TIBCO Hawk Agent for system and application monitoring.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Preface | xi

TIBCO Hawk HTTP Adapter Users Guide Contains information about

performing discovery, monitoring of agent status, monitoring of agent alerts, method invocation, method subscription, and many more activities on TIBCO Hawk and third-party products.

TIBCO Hawk Enterprise Message Service Administrator Plug-in Microagent Reference Contains details about the microagent methods that are used to administer and monitor the TIBCO Enterprise Message Service server.

TIBCO Hawk 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 DocumentationYou may find it useful to read the documentation for the following TIBCO products:

TIBCO Rendezvous

TIBCO Rendezvous Concepts

TIBCO Rendezvous Administration

TIBCO Rendezvous Configuration Tools

TIBCO Enterprise Message Service

TIBCO Enterprise Message Service Installation

TIBCO Enterprise Message Service Users Guide

TIBCO Administator

TIBCO Administrator Installation Guide

Third-Party DocumentationYou may find the following third-party documentation useful.

The Java Language Specification by Gosling, Joy, and Steele TIBCO Hawk Rendezvous Messaging Adapter Users Guide

xii | Typographical ConventionsTypographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME

CONFIG_FOLDER

HAWK_HOME

Many TIBCO products CAN be installed within the same directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME depends on the operating system. For example, on Windows systems, the default value is C:\tibco.

Incompatible products and multiple instances of the same product should be installed into different installation environments.

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

TIBCO Hawk installs into a directory within . This directory is referenced in documentation as HAWK_HOME. The value of HAWK_HOME depends on the operating system. For example on Windows systems, the default value is C:\tibco\hawk\4.9 .

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code font

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]TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Preface | xiiiitalic font Italic font is used in the following ways:

To indicate a document title. For example: See TIBCO BusinessWorks Concepts.

To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname

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 (Contd)

Convention Use TIBCO Hawk Rendezvous Messaging Adapter Users Guide

xiv | Connecting with TIBCO ResourcesConnecting with TIBCO Resources

How to Join TIBCOmmunityTIBCOmmunity is an online destinaton for TIBCO customers, partners, and resident expertsa 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 All TIBCO DocumentationAfter you join TIBCOmmunity, you can access the documentation for all supported product versions here:

http://docs.tibco.com/TibcoDoc

How to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows.

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

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

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

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you can request one.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

| 1Chapter 1 Introduction

This chapter gives an overview of TIBCO Hawk Rendezvous Messaging Adapter software, including the integration between TIBCO Rendezvous software and the TIBCO Hawk system.

Topics

Overview, page 2

Architecture, page 3

Functional Components, page 5 TIBCO Hawk Rendezvous Messaging Adapter Users Guide

2 | IntroductionOverview

TIBCO Hawk monitors systems and applications and uses TIBCO Rendezvous to communicate with the agents. The TIBCO Hawk Rendezvous Messaging Adapter (adapter) adds to TIBCO Hawk the ability to send and receive TIBCO Rendezvous messages. The adapter also provides a set of built-in methods to monitor TIBCO Rendezvous messages. Using XML configuration files, you can specify the subject and message structure to be sent or received for each method, then use TIBCO Hawk to execute the method.

The adapter can be used to:

Monitor applications that are not TIBCO Hawk-enabled, but publish TIBCO Rendezvous messages.

Provide "action methods" for TIBCO Hawk rulebases to send user specified messages. Typical scenarios are:

Notifying other applications of an error condition. A rulebase detects an error condition and uses the adapter to call a user-defined method that sends a message to applications about the error condition.

Distributing data collected by other TIBCO Hawk methods to applications. The adapter can send TIBCO Rendezvous messages to other applications using a user-defined method.

Participate in a remote procedure call exchange with other applications. The adapter can send an operations request to a TIBCO Rendezvous RPC server, which processes the request and returns the results to the adapter. A TIBCO Hawk rulebase can be written to monitor the result. If message format conversion is required, TIBCO MessageBroker can be used to translate the message during the exchange.

For example, a request may go through TIBCO MessageBroker to the TIBCO Adapter for R/3 adapter to get information from a SAP system. The reply can be sent back to TIBCO MessageBroker to filter out unwanted data and it can reply to the adapter with a simple TIBCO Rendezvous message. The reply can be monitored by a TIBCO Hawk rulebase.

Provide a mechanism to subscribe to periodic heartbeat messages in order to monitor the health of an application.

If a TIBCO Hawk action is to be performed on a remote machine (for example, to start another application process), an adapter provided method can be used to notify the TIBCO Hawk Agent on the remote machine of the action. On the remote machine a rulebase can be written that uses an adapter provided method to subscribe to the subject on which the messages are published and invoke the appropriate action.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Architecture | 3Architecture

The TIBCO Hawk Application Management Interface (AMI), a protocol for communicating between a TIBCO Hawk Agent and other applications, enables an external system to be monitored using TIBCO Hawk software. When you start the adapter, it uses AMI to exchange messages with a TIBCO Hawk Agent using TIBCO Rendezvous software. All communication between TIBCO Hawk product components is provided by TIBCO Rendezvous software.

The adapter is a TIBCO Rendezvous subscriber and publisher. Like other TIBCO Rendezvous programs, it sends and receives messages using subject-based addressing. Each instance of the adapter maintains a one or many TIBCO Rendezvous sessions. Multiple adapter instances can run on the same network or the same machine providing fault-tolerance, load-balancing, or added security.

The following diagram shows adapter interaction with TIBCO Hawk, TIBCO Rendezvous and other applications.

Figure 1 Architecture

Configuration details for the adapter are stored in an XML file that is flexible and easy to modify. The file contains XML elements and attributes that define custom TIBCO Hawk microagents for processing TIBCO Rendezvous messages. Syntax rules are defined in an external DTD, so a third-party validating parser can be used to validate the XML before it is used.

When the adapter is started, it parses and loads the configuration file. Using values specified in the file, the adapter dynamically builds microagents and methods.

TIBCO HawkDisplay

TIBCO Rendezvous

TIBCO HawkDisplay

TIBCO HawkAgent

TIBCO HawkAgent

Adapter Adapter

ApplicationApplicationApplication TIBCO Hawk Rendezvous Messaging Adapter Users Guide

4 | Introduction

All results returned by the adapters running on the same machine can be accessed by the local TIBCO Hawk Agent. Data returned by one instance of the adapter can be used as the data source of another rule. The TIBCO Hawk Agent can then apply logic to the results and possibly take action. The action can be another method invocation, such as sending a TIBCO Rendezvous message.

Like other microagents, the adapter uses AMI to communicate directly with the TIBCO Hawk Agent on the local node. The adapter microagents expose interfaces with methods and arguments so you can manage its activities from TIBCO Hawk Display. For more information, see Adapter Methods Reference on page 63. For more information about TIBCO Hawk Agents, microagents, and TIBCO Hawk Display, see the TIBCO Hawk Administrators Guide. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Functional Components | 5Functional Components

This section provides a general overview of each product component used by the TIBCO Hawk Rendezvous Messaging Adapter.

The TIBCO Rendezvous SystemTIBCO Rendezvous software allows you to exchange data among applications across a network. It provides software support for network data transport and network data representation. TIBCO Rendezvous software supports many hardware and software platforms, so applications running on many different kinds of computers on a network can communicate seamlessly.

TIBCO Hawk software uses TIBCO Rendezvous software for all network and intra-machine communications between TIBCO Hawk product components. Both broadcast and multicast network environments are supported. Connectivity across wide-area networks is provided by the TIBCO Rendezvous routing daemon, which routes messages efficiently and reliably between networks.

The TIBCO Hawk System TIBCO Hawk software is a tool for monitoring distributed systems and applications that is based on the TIBCO Rendezvous messaging system. The TIBCO Hawk monitoring solution is highly flexible, scalable, and easy to implement.

In a TIBCO Hawk environment, agents on each local computer perform the monitoring work. Agents use microagents to represent and interact with managed objects, such as an application or operating system component. Microagents use methods to extract monitoring information and carry out specified tasks internally, in the managed object. This allows a total de coupling of the management data from the management rules or policies. Microagent methods can be accessed and invoked from TIBCO Hawk Display or Console API applications. They are also used with the agent's powerful rules engine in autonomous monitoring.

Monitoring logic is stored in rulebases on each agent. Rulebases contain rules, which are user-defined statements about a managed object. Using specialized editing menus in TIBCO Hawk Display, administrators can easily construct rules that carry out specific tests and actions. No special syntax or scripting is required. Rules can then be grouped and distributed to multiple agents with similar monitoring requirements. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

6 | Introduction

The TIBCO Hawk Display application is the primary means of interacting with managed objects on your network. The main window of the TIBCO Hawk Display graphically represents system behavior with each monitored node represented by a container icon. Alert messages published by TIBCO Hawk Agents on TIBCO Rendezvous software are also displayed. All Display users can view the same managed objects without complicated configuration schemes, and each user can customize the interface without affecting others. For more information, see the TIBCO Hawk Administrators Guide.

AMI ProtocolThe TIBCO Hawk Application Management Interface (AMI) is an open, TIBCO Rendezvous-based protocol for instrumenting an application with a powerful management interface. Using AMI, applications can be monitored and controlled internally using TIBCO Hawk software in the same way as any other system component. The protocol allows for complete independence between the TIBCO Hawk Agent and the managed application with two-way dynamic discovery.

AMI features are:

AMI API libraries, which implement the protocol, are provided in C, C++ and Java. Direct AMI using the TIBCO Rendezvous APIs are also supported in ActiveX, and Perl.

AMI can be easily back-fitted into existing applications, even those that do not currently utilize TIBCO Rendezvous software, and expose existing internal application methods to a TIBCO Hawk Agent.

Third-party applications can be managed by writing an AMI wrapper that interfaces with an API or other mechanism provided by the application for the purpose of managing it.

For more information, see the TIBCO Hawk Programmers Guide.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Functional Components | 7

Benefits of Monitoring with the TIBCO Rendezvous System

The TIBCO Hawk system uses TIBCO Rendezvous software as a foundation and shares many important TIBCO Rendezvous benefits. Table 2 shows how TIBCO Rendezvous features contribute to TIBCO Hawk benefits.

Table 2 TIBCO Rendezvous Features and TIBCO Hawk Benefits

TIBCO Rendezvous Feature TIBCO Hawk Benefit Applications in a TIBCO Rendezvous network communicate with location transparency.

Monitoring applications can work from any point in the network.

Self-describing messages make it possible for applications to share information easily.

Monitoring activities can be shared among cooperating entities to distribute the monitoring load.

The publish-subscribe interaction is more efficient than sending many point-to-point messages (polling, for example).

Monitoring activities have a light impact on network traffic.

Subject-based addressing hides such network details as IP addresses.

Reconfiguring for network changes can be done quickly and easily.

The TIBCO Rendezvous framework is open and flexible.

Monitoring applications can provide ample capacity for specialized monitoring needs. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

8 | IntroductionTIBCO Hawk Rendezvous Messaging Adapter Users Guide

| 9Chapter 2 Installation

This chapter explains how to install TIBCO Hawk Rendezvous Messaging Adapter software. It contains information about software requirements, installation and verification procedures.

Topics

Installing on Windows, page 10

Installing on UNIX, page 13 TIBCO Hawk Rendezvous Messaging Adapter Users Guide

10 | InstallationInstalling on Windows

Before starting the installation procedure, review the topics in this section to determine that your system meets the basic requirements and that you have the prerequisite software installed.

Although many of the examples in this book specifically refer to the Windows NT platform, they also apply to the Windows 2000 platform.

System RequirementsThe following system requirements are recommended. The actual requirements depend on your application environment.

Free Disk Space: 60MB minimum.

Memory: 256MB RAM minimum

Software RequirementsThe following software is required and must be installed before starting the installation procedure:

Windows NT 4.0 with Service Pack 6 (build 1381) or above; or Windows 2000 (build 2195) Professional, Server, or Advanced Server.

TIBCO Rendezvous 6.6 or higher.

If you already have installed TIBCO Rendezvous software on a network-wide basis, you will not need additional TIBCO Rendezvous licenses unless you will be running applications instrumented with the TIBCO Hawk Rendezvous Messaging Adapter Application Management Interface (AMI) on unlicensed computers.

TIBCO Hawk software, version 3.0.0 or higher. A TIBCO Hawk Agent must be installed and running on the adapter machine.

Java Runtime Environment (JRE) 1.1.8 or higher. JRE 1.1.8 is recommended, and is included on the TIBCO Hawk Rendezvous Messaging Adapter CD-ROM. It can be automatically installed if no JRE is detected.

Installation StepsTo run the adapter installation program, you must have administrative privileges on the adapter machine.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Installing on Windows | 11

To install the adapter:

1. Verify that the machine where the adapter is being installed has an installed version of TIBCO Hawk 3.0.0 or higher.

2. Download the installation media.

3. Navigate to the download folder and double-click to open the TIB_hawkrvhma_4.0.0_w32.exe package.

4. Follow the InstallShield instructions.

By default, the adapter is installed in the \adapters\rvhma directory on the adapter machine. If a different version of the adapter exists on this machine, the installation program displays a prompt. Upon confirmation, the installation program removes the existing version and installs the current version.

The adapter can be installed as a Windows service. For instructions on starting the service, see Starting the Adapter on Windows on page 38.

5. Restart your computer.

After InstallationIt is recommended that the users first start with the sample configuration files present in the samples directory to get familiar with the features of the adapter. Before starting the adapter, the attributes values associated with the TIBHAWK_AMI elements in the sample configuration files may have to be updated. See Starting and Stopping the Adapter on page 38 for details.

It is also recommended that users read the rvhma.dtd file as it contains the grammar rules and descriptions for adapter configurations which are important.

Uninstalling the SoftwareTo uninstall the adapter:

Click Start>Settings>Control Panel>Add/Remove Programs>TIBCO Hawk RV Messaging Adapter TIBCO Hawk Rendezvous Messaging Adapter Users Guide

12 | Installation

Installing a Custom Adapter as a Service

During installation, a default service can be installed. This instance of the adapter uses the default configuration files. You can install an instance of the adapter that uses a custom configuration file as a Windows Service. When writing custom configuration files, we recommend you start by using the sample configuration files in the \adapters\rvhma\samples directory.

For a details on installing and uninstalling the adapter as a service, see Appendix B on Page 79.

You may have to modify the environment variable settings in the sample configuration files before using them. See Overview on page 20 for details.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Installing on UNIX | 13Installing on UNIX

Before starting the installation procedure, review the topics in this section to determine that your system meets the basic requirements and that you have the prerequisite software installed.

System RequirementsOne of the following operating system software is required:

Software RequirementsThe following software is required and must be installed before starting the installation procedure:

TIBCO Rendezvous software, version 6.6 or higher.

TIBCO Hawk software, version 3.0.0 or higher. A TIBCO Hawk Agent must be installed and running on the adapter machine.

Table 3 Supported UNIX PLatforms

Platform OS VersionHP HP-UX 10.20, 11.x, 11i

IBM AIX 4.3

SUN Solaris 2.6, 7, 8

DEC UNIX 4.0F

LINUX Red Hat LINUX 6.0, 6.2

x86 Solaris 7

TIBCO Hawk uses a TIBCO Rendezvous flavored license. You must have an actual TIBCO Rendezvous license to use the messaging adapter. If TIBCO Rendezvous is already installed on your network, additional licenses are required only if you are adding additional hosts (client, server, development subnets, and so on) to your network. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

14 | Installation

Java Runtime Environment (JRE) 1.1.8 or above. The following table lists the

download sites for obtaining JRE for the supported UNIX platforms.

Installation StepsTo run the installation program, you must be a superuser on the adapter machine. The software must be installed on a local disk.

1. Login to the machine where the adapter should be installed.

2. Uncompress the adapter package.

For example, on Solaris 2.x: $ uncompress TIB_hawkrvhma_4.0.0_s4_56_CC.tar.Z

3. Unpack the tar file

For example, on Solaris 2.x:$ tar xvf TIB_hawkrvhma_4.0.0_s4_56_CC.tar

4. Execute the tibinstall script and follow the instructions.$ ./tibinstall

Transcript of the Solaris installationA transcript of a typical tar installation transcript, for a user logged in as root, appears below. In this example, the system administrator installs adapter on a Sun workstation running Solaris 2.x. All text entered by the user appears in bold.# ./tibinstall

The following platform will be installed:

Table 4 Download Sites for JRE

Platform Download Sites for JREHP www.hp.com/products1/unix/java

IBM www.ibm.com/java/jdk/aix/supported/118ga/

SUN www.sun.com/solaris/jre

DEC www.compaq.com/java/download

LINUX You can select a download site for the JRE for Linux from www.blackdown.org/java-linux/mirrors.htmlFor example, one suitable site for North America is:ftp://iodynamics.com/pub/mirror/linux-jdk/ TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Installing on UNIX | 15

s4_56_CC - SPARC based systems running Solaris 2.x (CC)

Welcome to the TIBCO Hawk Rendezvous Messaging Adapter(tm) Software

Please read the license agreement before installing the TIBCO Hawk Rendezvous Messaging Adapter Software.

END USER LICENSE AGREEMENT

Copyright (c) 1994-2001 TIBCO Software Inc. ALL RIGHTS RESERVED.

Addenda:None

Do you accept the terms and conditions of this agreement [y]? y

Destination directory : /opt/tibco/hawkStarting installation for platform s4_56_CCplease wait ...

Installation of was successful.

Pre-requisites for TIBCO Hawk Rendezvous Messaging Adapter 4.0.0

1. TIBHawk 4.0.0 or greater2. Java Runtime Environment (JRE) version 1.1.8 or greater (version 1.1.8 recommended)

TIBCO Hawk Rendezvous Messaging Adapter 4.0.0 has been successfully installed at /opt/tibco/hawk/adapters/rvhma.

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

16 | Installation

After Installation

1. Make sure JRE is installed on your system

2. Create the following environment variables:

It is recommended that you first start with the sample configuration files present in the samples directory to get familiar with the features of the adapter. Before using starting the adapter, the TIBHAWK_AMI elements in the sample configuration files may have to be updated. See TIBHAWK_AMI Element Attributes on page 21 for details

It is also recommended that you read the rvhma.dtd file as it contains the grammar rules and descriptions for adapter configurations which are important. The file is located in the samples directory.

Table 5 Environment Variables

Environment Variable Description Example

HAWK_ROOT The directory where the TIBCO Hawk software is installed.

For csh: setenv HAWK_ROOT /opt/tibco/hawk

For sh or ksh: HAWK_ROOT=/opt/tibco/hawk; export HAWK_ROOT

RV_ROOT The directory where the TIBCO Rendezvous software is installed.

For csh: setenv RV_ROOT /opt/tibco/rv

For sh or ksh: RV_ROOT=/opt/tibco/rv; export RV_ROOT

JRE_ROOT The directory where the JRE is installed.

For csh: setenv JRE_ROOT /opt/tibco/javaFor sh or ksh: JRE_ROOT=/opt/tibco/java; export JRE_ROOT

PATH Modify this environment variable to include $HAWK_ROOT/bin

For csh:

setenv PATH

$HAWK_ROOT/bin:${PATH} For sh or ksh: PATH = $HAWK_ROOT/bin:${PATH}; export PATHTIBCO Hawk Rendezvous Messaging Adapter Users Guide

Installing on UNIX | 17

Uninstalling the Software

Before uninstalling the adapter, you should backup files created during installation that you have modified. The package remove utility deletes all files that were originally created during installation. If you have modified any installed files, they will be removed.

To uninstall the adapter, do the following.

1. Login as root.

2. Execute the one of the following commands depending on your platform:

This command removes all files that were added during installation.

Table 6 Commands to Remove the Adapter on UNIX

Platform CommandHP swremove Hawkrvhma

IBM rm -rf

SUN /usr/sbin/pkgrm Hawkrvhma

DEC /usr/sbin/setld -d Hawkrvhma

LINUX rm -fr TIBCO Hawk Rendezvous Messaging Adapter Users Guide

18 | InstallationTIBCO Hawk Rendezvous Messaging Adapter Users Guide

| 19Chapter 3 Configuring the Adapter

This chapter describes how to configure and begin using TIBCO Hawk Rendezvous Messaging Adapter software.

Topics

Overview, page 20

Configuration File Elements and Attributes, page 21

Specifying Field Names in Parameters, page 34

Validating an XML Configuration File, page 36

Starting and Stopping the Adapter, page 38

Viewing the Adapter Log File, page 42 TIBCO Hawk Rendezvous Messaging Adapter Users Guide

20 | Configuring the AdapterOverview

A set of sample configuration files and executable files are copied to the installation area in the samples directory when the adapter is installed. The files contains sample methods, as well as several default method definitions that are helpful for performing routine tasks.

You can start using the adapter with one of the sample files, or create your own file using the sample file as a template. If you use the sample file, see page 45 for a list of attribute values that require modification. If you create your own file, copy the definitions of any sample methods you want to use from the sample file to your configuration file. See Chapter 4, Testing the Adapter for more information.

Before using the sample executable files, you may have to modify the file for your environment. See Verify Sample Adapter Configuration on page 45 for details.

The rvhma.dtd file contains syntax rules for the adapter configuration file. During installation, this file is copied to the samples directory, located in your installation area. When you use a validating parser to validate the XML in an adapter configuration file, instructions specified in the DTD are used to check file entries for syntax errors. For instructions on validating configuration file syntax, see Validating an XML Configuration File on page 36.

Using any text editor, you can specify values for attributes in the XML file. The new values are used the next time the adapter is started. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Configuration File Elements and Attributes | 21Configuration File Elements and Attributes

The rvhma.dtd file defines the grammar for all the constructs used in an adapter XML configuration file. With this file included, the XML configuration file can be syntax checked using any validating XML parser.

The following tables describe the attributes that can be set in an XML configuration file:

TIBHAWK_AMI Element Attributes

microagent Element Attributes

microagent Element Attributes

method Element Attributes

inputParameter Element Attributes

valueChoices Element Attribute

legalValueChoices Element Attribute

constantParameter Element Attributes

outputParameter Element Attributes

The top level element, TIBHAWK_AMI describes TIBCO Rendezvous and tracing attributes that can applied to all microagents. Some of the attributes can be redefined for an individual microagent in the microagent element.

Table 7 TIBHAWK_AMI Element Attributes

Attribute Type Descriptiondtd_type enume

rationREQUIRED. (RVHMA).

dtd_version enumeration

REQUIRED. (1.0).

xml_file_version string IMPLIED. Can be used to identify the version of this XML file. It must be in the form of .., for example, 1.1.0 . The XML file name and this version number can be queried with the built-in method, getReleaseVersion . TIBCO Hawk Rendezvous Messaging Adapter Users Guide

22 | Configuring the Adapterami_rvd_service ami_rvd_network ami_rvd_daemon

string IMPLIED. These attributes together configure the TIBCO Rendezvous parameters for creating an TIBCO Rendezvous transport for the communication with the TIBCO Hawk agent. If any of the attributes are not specified, the TIBCO Rendezvous default values are used.

rvService

rvNetwork

rvDaemon

string IMPLIED. These attributes together configure the TIBCO Rendezvous parameters for creating a TIBCO Rendezvous transport for the rvd connection used by all publish, subscribe and RPC methods in the adapter. If any of the attributes are not specified, the TIBCO Rendezvous default values are used.

cmName

cmLedger

string IMPLIED. These attributes together form an RVCM (TIBCO Rendezvous Certified Message) transport. All methods in this adapter that use RVCM will use this RVCM transport.

cmName is the RVCM reusable name which represents a persistent correspondent.

If cmLedger is specified, it must be a valid file name. The cmLedger attribute is ignored if cmName is not specified.


Attribute Type DescriptionTIBCO Hawk Rendezvous Messaging Adapter Users Guide

Configuration File Elements and Attributes | 23rvAdvisoryTraceLevel enumeration

IMPLIED. One of: ERROR, WARN or INFO. Specifies the lowest level of TIBCO Rendezvous advisory messages to be tracked by the adapter.

For example, if WARN is specified, then all WARN or ERROR advisory messages are tracked by this adapter.

The default value WARN. If an advisory message not tracked by the adapter is received, it will be sent to the adapter standard output if of class WARN or ERROR and discarded if of class INFO.

rvAdvisoryForward enumeration

IMPLIED. Either true or false. Specifies whether a tracked advisory message will be sent to the TIBCO HAWK Agent as an unsolicited message.

The default is false, which means tracked advisory messages are logged to the adapter's log file.

ftGroupName string IMPLIED. Specifies the name of the TIBCO Rendezvous fault tolerance group.

ftWeight

ftActiveGoal

ftHeartbeatInterval

ftPrepInterval

ftActiveInterval

string IMPLIED. These attributes together define TIBCO Rendezvous fault tolerance parameters. The default values are:

ftWeight 100.

ftActiveGoal 1

ftHeartbeatInterval 30 seconds

ftPrepInterval 60 seconds

These attributes are used only if the ftGroupName is specified.


Attribute Type Description TIBCO Hawk Rendezvous Messaging Adapter Users Guide

24 | Configuring the AdapterAt least one method must be defined for each microagent. Multiple microagents can be defined in a single configuration file.

traceFile

traceFileMaxSize

traceFileMaxNumber

traceLevel

string IMPLIED. These attributes together specify the AMI tracing parameters. If not defined, tracing is sent to stderr.

traceFile. Absolute pathname of the trace file.

traceFileMaxSize. Maximum size the trace file is allowed to grow.

traceFileMaxNumber. Maximum number of roll over trace files to be maintained.

traceLevel. Starting trace level.

The defined trace file (or default) is used for all microagents defined in the XML configuration file unless different values of these attributes are specified along with a microagent element. If so, the attributes specified there will be used for the tracing of that microagent only.

Table 8 microagent Element Attributes

name string REQUIRED. Name for the microagent.

help string IMPLIED. Help text describing the microagent. Each help attribute is paired with a name attribute. If not defined, the name attribute value is used as the help text.

displayName string IMPLIED. Name that is displayed in the TIBCO Hawk Display.



Configuration File Elements and Attributes | 25rvService

rvNetwork

rvDaemon

string IMPLIED. These attributes together configure the TIBCO Rendezvous parameters for creating a TIBCO Rendezvous transport for the rvd connection used by all publish, subscribe and RPC methods in the microagent only.

If any of the attributes are specified differently from those specified for the TIBHAWK_AMI element, a new rvd transport is created and all the methods belong to this microagent will use the new transport.

If the attributes are not specified, the values specified for the corresponding attributes associated with the TIBHAWK_AMI element are used.

cmName

cmLedger

string IMPLIED. These attributes together form an RVCM (TIBCO Rendezvous Certified Message) transport. All methods in this microagent that use RVCM will use this RVCM transport.

cmName is the RVCM reusable name which represents a persistent correspondent.

If cmLedger is specified, it must be a valid file name. The cmLedger attribute is ignored if not specified.

maxThreads string IMPLIED. Defines the maximum number of threads a microagent can have to perform method invocations in parallel. The default value is 1. That is, for each microagent only one thread is availableall the methods invocation of that microagent are serialized (a method must wait until a previous method execution completes before it can execute).

Table 8 microagent Element Attributes TIBCO Hawk Rendezvous Messaging Adapter Users Guide

26 | Configuring the AdapterIf a method has parameters, the method must have at least one input or constant parameter. If a method has a return value, it must have at least one output parameter.

traceFile

traceFileMaxSize

traceFileMaxNumber

traceLevel

string IMPLIED. These attributes together specify the tracing parameters for this microagent. If not defined, tracing is sent to stderr. The attributes override the corresponding attributes associated with the TIBHAWK_AMI element.

traceFile. Absolute pathname of the trace file.

traceFileMaxSize. Maximum size the trace file is allowed to grow.

traceFileMaxNumber. Maximum number of roll over trace files to be maintained.

traceLevel. Starting trace level.

Table 9 method Element Attributes

Attribute Type Descriptionname string REQUIRED. The method name.

help string IMPLIED. Help text describing the method. Each help attribute is paired with a name attribute. If not defined, the name attribute value is used as the help text.

index string IMPLIED. If a method returns more than one row of information, the index attribute must be specified with the name of the output parameter which can uniquely identify each row.

If multiple output parameters are required to uniquely identify a row (that is, a composite index), the index attribute must be specified with parameter names separated by commas.

Table 8 microagent Element AttributesTIBCO Hawk Rendezvous Messaging Adapter Users Guide

Configuration File Elements and Attributes | 27subject string IMPLIED. Specifies the subject to subscribe or to publish. For a subscription subject, the subject name segments may contain "*", and the last segment may be ">".

The attribute is required if the first input parameter is not named Subject or if the method publishes RVCM messages.

timeout string IMPLIED. The timeout attribute is meaningful (and required) only for RPC methods. If the timeout interval expires and no reply is received, the first return timeout parameter is set to true.

Note that the thread executing the RPC is blocked while waiting for the reply. If a microagent has multiple simultaneous RPC calls, the maxThreads attribute for the microagent must be adjusted higher accordingly.



28 | Configuring the AdapterhandlerType enumerationS

REQUIRED. One of: P, SU, RPC, DS, T or S

Specifies how a method should be handled:

P. Publishers sending TIBCO Rendezvous messages.

SU. Subscribers receiving TIBCO Rendezvous messages.

RPC. RPC client sending TIBCO Rendezvous messages, then waiting for the reply.

DS. Used for the factory provided methods tibrvlisten , tibrvecho and dynamicSubscribe .

T. Used for the factory provided method timeoutTest only.

S. Used for factory provided system methods, which include reviewLedger and shutdown .

For subscriber and RPC methods (with handlerType SU and RPC respectively) the specified fields must have a one to one correspondence with the methods return (output) parameters.

For publisher methods (with handlerType P and RPC respectively), the message publish subject and all fields must be specified in the message.

useCM string IMPLIED. If set to true, the method is an RVCM publisher or subscriber. If not specified, RVCM is not used.

cmListenerList string IMPLIED. Only meaningful if the useCM attribute is set to true and the method handlerType value is P (is a publisher method). The cmListenerList attribute specifies a list of cmName names in the form:, , , ...



Configuration File Elements and Attributes | 29

For methods with handlerType SU , P, or RPC , if the first inputParameter is named Subject , it is used as the subject for subscription or publish. (Note: In this case, the subject attribute for the method should not be defined.) This allows subjects to be specified at runtime.

For each parameter, you can define either one or more acceptable choices in a valueChoices element, or one or more legal choices in a legalValueChoices element. If one of these elements is included in the parameter definition, users can select method argument values from a dropdown list in TIBCO Hawk Display. If neither is included, the corresponding method argument is represented by an editable field.

Table 10 inputParameter Element Attributes

Attribute Type Descriptionname string REQUIRED. Name for the input parameter.

help string IMPLIED. Help text describing the input parameter. Each help attribute is paired with a name attribute. If not defined, the name attribute value is used as the help text.

type enumeration

REQUIRED. The datatypes follow the TIBCO Rendezvous 6.x datatypes convention:

BOOL, F32, F64, I8, I16, I32, I64, U8, U16, U32, STRING

fieldName string IMPLIED. Must be in the form of F1[.F2[...[.FN]]] where F1 - FN are the TIBCO Rendezvous message field names in each nested level.

If the fieldName attribute is not specified, it is assumed to be the same as the name attribute.

See Specifying Field Names in Parameters, page 34 for details. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

30 | Configuring the AdapterAn input parameter may have an optional element, valueChoices or legalValueChoices but not both.

The valueChoices element defines some acceptable values for an inputParameter element. These values are included in the dropdown list for method arguments in TIBCO Hawk Display. Users can also type a value not in the list. This element is optional, and can only be used if the legalValueChoices element is not specified

pattern string IMPLIED. Specifies a pattern to convert string data to a desired form. The pattern syntax is based on the java.text.MessageFormat class specification. See Java Pattern Matching Syntax, page 77 for more information.

For example, a pattern {0, number} KB could be used to convert a string 123 KB to a number 123 (not a string). If the pattern in the example is {0} KB , a string of 123 is extracted.

Note that only the first argument placeholder (that is, {0..} ) is used to extract the value for the parameter and others are ignored.

Table 11 valueChoices Element Attribute

Attribute Type Descriptionvalue string IMPLIED. Defines suggested values. The values

are separated by comma characters. For example: 0, 30, 45, 60, 90

Table 10 inputParameter Element Attributes


Configuration File Elements and Attributes | 31

The legalValueChoices element defines the only possible values that can be specified in an inputParameter method. This element is optional, and can only be used if valueChoices is not specified. Use this element to limit users to specific values, which are included in the dropdown list for method arguments in TIBCO Hawk Display. Users can only specify values included in the list.

Constant parameters are not exposed to the TIBCO Hawk Agent or TIBCO Hawk Display. Constant parameter values are passed to the rvhma method internally. This type of parameters are used when some fixed constant values need to be passed to rvhma methods.

Constant parameters are used to fill in constant value fields in the message.

Table 12 legalValueChoices Element Attribute

Attribute Type Descriptionvalue string IMPLIED. Defines legal values only. The values

are separated by comma characters. For example: 0, 30, 45, 60, 90

Table 13 constantParameter Element Attributes

Attribute Type Descriptionname string REQUIRED. Name for the constant parameter.


type enumeration





See Specifying Field Names in Parameters, page 34 for details. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

32 | Configuring the Adapter

For subscriber methods (with method handlerType SU or DS), there are three special outputParameter names:

Subscription Subject . Returns the subject used in the subscription. It can contain wild card characters.

Message Subject . Returns the actual subject used by the publisher to publish the received message.

Reply Subject . Returns the reply subject of the received message. The reply subject is blank if the sender does not specify a reply subject

For RPC methods (with method handlerType RPC), there is a special outputParameter with the name Timeout and type BOOL . It is required and must be the first outputParameter. It is used to indicate whether a timeout has occurred while waiting for the reply.

Table 14 outputParameter Element Attributes

Attribute Type Descriptionname string REQUIRED. Name for the output parameter.


type enumeration





See Specifying Field Names in Parameters, page 34 for details.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Configuration File Elements and Attributes | 33pattern string IMPLIED. Specifies a pattern to convert string data to a desired form. The pattern syntax is based on the java.text.MessageFormat class specification. See Java Pattern Matching Syntax, page 77 for more information.

For example, a pattern {0, number} KB could be used to convert a string 123 KB to a number 123 (not a string). If the pattern in the example is {0} KB , a string of 123 is extracted.

Note that only the first argument placeholder (that is, {0..} ) is used to extract the value for the parameter and others are ignored.

Table 14 outputParameter Element Attributes


34 | Configuring the AdapterSpecifying Field Names in Parameters

The fieldName attribute in an inputParameter, outputParameter, or constantParameter element can specify a single field name, nested fields, repeating fields or arrays.

The following example shows how to specify a single field name:

A nested field must be in the form of F1[.F2[...[.FN]]] where F1 - FN are the TIBCO Rendezvous message field names in each nested level. For example, a message has a field NESTED_FIELD , which is another TIBCO Rendezvous message and that message has a field L2 . For a parameter corresponding to the value of the field L3 in NESTED_FIELD.L2 , its fieldName attribute should be:

If a field is a repeating field, the instance number (starting from 1) must also be specified using the notation of {instance number} appended after the field name. For example, NESTED_FIELD.L2.L3R{1} means the field L3R belongs to the first instance of the repeating field L3R of NESTED_FIELD.L2 . In the second example, NESTED_FIELD.L2.L3R{2} means the field L3R belongs to the second instance of the repeating field L3R of NESTED_FIELD.L2 .

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Specifying Field Names in Parameters | 35

If a field is an array, a parameter can be used to represent only one element in an array. The element index number (starting from 0) must be specified using the notation of [index number] appended after the field name. For example, NESTED_FIELD.L2.L3A[0] means the first array element in field L3A where L3A is a field of L2 and L2 is field of NESTED_FIELD . In the second example, NESTED_FIELD.L2.L3A[1] means the second array element in field L3A where L3A is a field of L2 and L2 is field of NESTED_FIELD .

Note that the type of "array of TibrvMsg" is not supported by TIBCO Rendezvous and a fieldName such as F1.F2[2].F3 is not valid. When repeating fields or array fields appear in the input or constant parameters (for sending), the sequence numbers or the index numbers must be in order, that is., no skipping is allowed. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

36 | Configuring the AdapterValidating an XML Configuration File

The adapter includes an external DTD file, rvhma .dtd . During installation, this file is copied to the samples directory where the adapter is installed. The DTD defines valid syntax for all elements and attributes in the adapter configuration file.

Since this information is stored in a separate file, you can use a validating XML parser to check the syntax after editing the file. The parser applies syntax rules specified in the DTD to the file contents. Validating the XML is an optional step that helps prevent errors resulting from invalid syntax.

To validate XML syntax in the adapter configuration file:

1. Using any text editor, open the file.

2. Change the following line:

to:

by deleting the comment characters.

3. Save and close the file.

4. Pass the file name to any available validating XML parser.

After validating the XML configuration file, you should restore the deleted comment characters and save the rvhma .dtd file. If the line that references the adapter DTD is active, the adapter does not start.

Performing XML Consistency ChecksThe adapter also includes a utility for checking the consistency of XML syntax. This utility applies adapter-specific logic to the contents of the configuration file, providing more advanced syntax validation than a generic parser. Checking for consistency detects whether internal syntax dependencies are met. For example, some attributes of the method element are either required or optional, depending on the type of method. The consistency checker verifies that required attributes are specified.

To check XML consistency execute the following at a command prompt:

On Unixstarttibhawkrvhma -xml_file < filename> -check_only

On Windows tibhawkrvhma --name -xml_file < filename> -check_onlyTIBCO Hawk Rendezvous Messaging Adapter Users Guide

Validating an XML Configuration File | 37

Where, is the complete path to the configuration XML file and is the internal Windows service name given to this instance of the adapter.

The for the default service installed is TIBHawkRVHma .When the -check_only option is used when starting the adapter, it checks the XML syntax only. Any syntax errors are displayed in the console window where the command was run. The adapter process stops automatically after checking completes. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

38 | Configuring the AdapterStarting and Stopping the Adapter

The adapter can run as a service on Windows or from the command line on Windows and Unix.

Starting the Adapter on WindowsDuring installation, the adapter can be installed as a service. The installation procedure configures the service to start manually. To begin using the adapter, you must start the service.

To start the service:

1. In Windows NT Control Panel, open Services .

In Windows 2000 Control Panel, open Administrative Tools , then open Services .

2. Click TIBCO Hawk RV Messaging Adapter, then click Start .

The adapter service starts.

See Appendix B for information about adding the adapter as a service in Windows.

To start the adapter from the command line:

tibhawkrvhma -xml_file

Where is the complete path to the XML configuration file.

Before starting the adapter for the first time, follow the configuration instructions in Configuring the Adapter on page 19.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Starting and Stopping the Adapter | 39

Stopping the Adapter on Windows

Use the default shutdown method from the TIBCO Hawk Display to stop the adapter. For a description of this method, see page 65.

To stop the service:

1. In Windows NT Control Panel, open Services .


2. Click TIBCO Hawk RV Messaging Adapter, then click Stop .

The adapter service stops. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

40 | Configuring the Adapter

Starting the Adapter on UNIX

To start the adapter, execute the following command:

starttibhawkrvhma -xml_file

Where is the complete path to the XML configuration file.

The default configuration files are in the $HAWK_ROOT/adapters/rvhma/samples directory.

Stopping the Adapter on UNIXAn instance of the adapter can be stopped by any one of the following ways:

Using the default shutdown method from the TIBCO Hawk Display. For a description of this method, see page 65.

Using the kill command.

Where is the process ID of the adapter instance.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Changing the Service Log On Account on Windows | 41Changing the Service Log On Account on Windows

The adapter is configured to use the built-in system account. To use a different account, create the account with administrator privileges and configure it to log on as a service. Then, follow these steps to change the user account:

1. In Windows NT Control Panel, open Services


2. Click TIBCO Hawk RV Messaging Adapter, then click Startup .

3. In the Log On As panel, click This Account and type the new user account and password.

4. Click OK .

5. Click Close to exit the Services dialog, then close the Control Panel window.

You must re-boot the machine for the service configuration changes to take effect. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

42 | Configuring the AdapterViewing the Adapter Log File

The adapter log file contains status information specific to the adapter. The location of this file depends on the value of the traceFile attribute in the adapter configuration file. By default, minimal information is written to the log file. The following lines are typical of a log file with the default setting:2000/04/25 13:40:12.107 RVHma 1.0 started with configuration file: c:\tibco\hawk\adapters\samples\rvhmaSample1.xml

2000/04/25 13:40:12.848 RVHma is ready...

2000/04/25 17:54:00.664 RVHma Shutting down...

You can change the level of information logged in the file using the traceLevel attribute in the TIB_HAWKAMI element or the traceLevel attribute in the microagent element. Any values specified at the microagent level override the TIB_HAWKAMI settings for that microagent. However, it is recommended to use a single log file per adapter.

You can also modify trace settings by invoking the standard setTraceLevel TIBCO Hawk method.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

| 43Chapter 4 Testing the Adapter

This chapter explains how to test the adapter by using its methods directly. See Chapter 5 for examples of using adapter methods in a rulebase.

Topics

Overview, page 44

Verify Sample Adapter Configuration, page 45

Start the Sample Adapter, page 46

Start TIBCO Hawk, page 47

Send and Receive a Message, page 48

Other Sample Adapters, page 52 TIBCO Hawk Rendezvous Messaging Adapter Users Guide

44 | Testing the AdapterOverview

When you start the TIBCO Hawk Rendezvous Messaging Adapter using the sample configuration file, a microagent for the adapter is dynamically added to the local agent.

The adapter microagent methods are described in detail in Chapter 6. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Verify Sample Adapter Configuration | 45Verify Sample Adapter Configuration

To follow the examples in this section, the sample adapter configuration file must contain correct values for your TIBCO Rendezvous and TIBCO Hawk environments.

To verify the configuration setting:

1. In a command window change directory to the adapter installation samples directory. For example, on Windows, type cd C:\TIBCO\hawk\adapters\rvhma\samples

2. Using a text editor, open the rvhma.xml adapter configuration file.

The following parameters require modification before starting the adapter if TIBCO Rendezvous or TIBCO Hawk is not configured as defined. See TIBHAWK_AMI Element Attributes, page 21 for details about the parameters.ami_rvd_service = "7474"ami_rvd_network = ""ami_rvd_daemon = "tcp:7474"rvService = "7500"rvNetwork = ""rvDaemon = "tcp:7500"traceFile = "${hawk.hawk_root}/adapters/rvhma/log/rvhma.log"traceLevel = "0"

3. Using a text editor, open the consoleRVHma.bat executable file. Verify that the following parameters are correct for your environment:set RV_ROOT=c:\TIBCO\TIBRVset HAWK_ROOT=c:\TIBCO\hawkset JRE_ROOT=c:\TIBCO\JRE\1.3.1

On Unix, modify the file runRVHma in a similar way. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

46 | Testing the AdapterStart the Sample Adapter

The adapter can be run as a service on Windows or from the command line on Windows and Unix. At installation the adapter is typically installed as a service on Windows. See Appendix B for information about adding the adapter as a service to Windows.

In this exercise, the sample rvhma service is started from the command line.

To start the adapter:

1. In a command window change directory to the adapter installation sample directory. For example, on Windows, type cd C:\TIBCO\hawk\adapters\rvhma\samples

2. Start the adapter.

On Windows, type consoleRVHma.bat

On Unix, type runRVHma

For this exercise the adapter must not already be running as a service on Windows or as a process on Unix.

Before starting the example on Windows, ensure that the service is not running by displaying the Services dialog box and verifying that TIBCO Hawk RV Messaging Adapter Status is not set to Started .

Before starting the example on Unix, ensure that the adapter process is not running.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Start TIBCO Hawk | 47Start TIBCO Hawk

To start TIBCO Hawk Display:

On Windows:

Select Start>Programs>TIB-Hawk Software>Hawk Display from the Start menu, or double-click Hawk Display in the TIBCO Hawk program group.

On Unix:

Type startdisplay at a command prompt.

The TIB/Hawk Display main window displays.

The next section explains how to use the adapter methods to send and receive TIBCO Rendezvous messages and to shutdown the adapter. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

48 | Testing the AdapterSend and Receive a Message

This section is an exercise that shows how to dynamically execute the tibrvlisten and tibrvsend methods to send and receive a TIBCO Rendezvous message. The exercise also shows how to use the shutdown method to stop the adapter from TIBCO Hawk Display.

1. In TIBCO Hawk Display, right-click on the agent icon and select Get Microagents .

The Microagents, Methods and Arguments dialog displays. The panel on the upper left lists microagents you can access on the current agent.

For synchronous methods, 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.

For asynchronous methods, the Invoke mode should be not be used. Executing Invoke on an asynchronous method will produce an error.

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.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Send and Receive a Message | 49

2. Click the microagent name, in this case rvhma.Default:0 , to display a list of

associated methods and text descriptions in the panels below. For detailed descriptions of these methods, see page 64.

3. Click tibrvlisten and type the name of the subject. For example, testmsg .

4. Verify that the Subscribe radio button is selected and Click the Subscribe button to execute the method.

The Subscription Results dialog box appears.

5. Repeat step 1 and step 2 to display another method window.

6. Click tibrvsend and type the subject name, testmsg . In Message , type Hello . TIBCO Hawk Rendezvous Messaging Adapter Users Guide

50 | Testing the Adapter

7. Verify that the Invoke radio button is selected and Click the Invoke button to

execute the method.

A Message dialog box displays:

8. Click OK to close the dialog.

9. Click the Subsciption Results dialog to view the results.

10. Click Done to close the Subscription Results dialog box.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Send and Receive a Message | 51

11. In one Microagents, Methods and Arguments dialog box, click the

shutdown method, then click Invoke .

The adapter is shutdown.

12. Click OK to close the dialog box. You can close all open windows and exit the TIBCO Hawk program. TIBCO Hawk Rendezvous Messaging Adapter Users Guide

52 | Testing the AdapterOther Sample Adapters

Sample adapters are available in the HAWK_ROOT/adapters/rvhma/samples directory. The samples are written for advanced users, but all users can benefit by from them. The rvhmaSample1 adapter has methods for publishing messages or initiating RPC requests. The rvhmaSample2 adapter has methods that subscribe to messages. For testing purposes, both should be running to communicate with each other.

Before invoking a sample adapter .bat file, you may need to edit it and its corresponding XML configuration file for your environment. See page 45 for details.

To run the sample adapters:

On Windows, type console_rvhmaSample.bat

On Unix, type run_rvhmaSample

On Windows, the sample adapters can also be installed as Windows services by invoking the install_rvhmaSample.bat files. Before invoking the files, you may need to modify them for your environment by editing the connection environment variables.

Two sample TIBCO Hawk rulebases, rvhmaSample1.hrb and rvhmaSample2.hrb are also provided for use with the rvhmaSample1 and rvhmaSample2 adapters. The sample adapters must be running before these rulebases can be applied.

Before starting the sample adapters, ensure that the adapter is not already running:

Before starting the example on Windows, ensure that the service is not running by displaying the Services dialog box and verifying that TIBCO Hawk RV Messaging Adapter Status is not set to Started .

Before starting the example on Unix, ensure that the adapter process is not running.TIBCO Hawk Rendezvous Messaging Adapter Users Guide

| 53Chapter 5 Using Adapter Methods in a Rulebase

This chapter describes several sample implementations of default and custom adapter methods. Adapter methods can be used as a data source or an action in a TIBCO Hawk rulebase, a collection of user-defined monitoring policies.

Topics

Monitor a Log File, page 54

Monitor an Applications Heartbeat, page 59 TIBCO Hawk Rendezvous Messaging Adapter Users Guide

54 | Using Adapter Methods in a RulebaseMonitor a Log File

In this example, a rulebase is written that monitors a logfile (MyDemoApp.log) that is created and updated by an application (MyDemoApp) running on the same system as the TIBCO Hawk agent. This application need not be an object managed by TIBCO Hawk.

When shutting down, the application writes the line MyDemoApp is SHUTTING DOWN down into the logfile. When the rulebase detects such a line, it publishes a message announcing the shutdown of the application.

These steps demonstrate how to create a TIBCO Hawk rulebase to publish a TIBCO Rendezvous message. The rulebase contains a simple rule that uses the Logfile:onNewLine() method as the data source. Every line returned by this method is scanned for the words SHUTTING . When this condition is satisfied, the rulebase publishes a message. The example has the following sections:

Identify the Logfile

Define the Test

View the Results

Identify the Logfile1. Start the adapter (see Starting and Stopping the Adapter on page 38), then

start TIBCO Hawk (see Start TIBCO Hawk on page 47).

2. Right-click on the agent icon where the adapter is running and select Get Configuration>Rulebases . TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Monitor a Log File | 55

The Rulebase List for Agent dialog displays. This dialog lists

Documents

writing custom rules