Writing Custom Rules

TIBCO Hawk Rendezvous
Messaging Adapter
Users Guide
Software Release 4.9
November 2010
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED
OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED
ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED
SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR
ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A
LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE
AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER
LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE
SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE 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
| iii
Contents
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
TIBCO Hawk Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Third-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
How to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Functional Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
The TIBCO Rendezvous System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
The TIBCO Hawk System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
AMI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Benefits of Monitoring with the TIBCO Rendezvous System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Installing on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Uninstalling the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Installing a Custom Adapter as a Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Installing on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Transcript of the Solaris installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
TIBCO Hawk Rendezvous Messaging Adapter Users Guide
iv
|
Uninstalling the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 3 Configuring the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Configuration File Elements and Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Specifying Field Names in Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Validating an XML Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Performing XML Consistency Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Starting and Stopping the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Adapter on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping the Adapter on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Adapter on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping the Adapter on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
38
38
39
40
40
Changing the Service Log On Account on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Viewing the Adapter Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 4 Testing the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Verify Sample Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Start the Sample Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Start TIBCO Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Send and Receive a Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Other Sample Adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Chapter 5 Using Adapter Methods in a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Monitor a Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identify the Logfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Define the Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
View the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
54
54
56
58
Monitor an Applications Heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Define the Subject and Timeout Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Define the Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Chapter 6 Adapter Methods Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Methods Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getReleaseVersion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getTraceParameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
setTraceParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
65
66
67
68
|v
getTraceLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
setTraceLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getMaxThreads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
setMaxThreads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tibrvsend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tibrvlisten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dynamicSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
_onUnsolicitedMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
69
70
71
72
73
74
75
76
Appendix A Java Pattern Matching Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Pattern Matching Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Appendix B TIBCO Hawk Service Wrapper for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79

Windows Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Installing the Adapter as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Uninstalling the Adapter as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Executing the Adapter as a Windows console application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Executing the Adapter as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
vi
| vii
Tables
Table 1
General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Table 2
TIBCO Rendezvous Features and TIBCO Hawk Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Table 3
Supported UNIX PLatforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Table 4
Download Sites for JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Table 5
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Table 6
Commands to Remove the Adapter on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Table 7
TIBHAWK_AMI Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 8
microagent Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 9
method Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 10
inputParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 11
valueChoices Element Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 12
legalValueChoices Element Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 13
constantParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 14
outputParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Table 15
Examples of using Argument{0} in Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Table 16
Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Table 17
JVM Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
viii
| ix
Preface
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
| Related Documentation
Related Documentation
This section lists documentation resources you may find useful.
TIBCO Hawk Documentation

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

You 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 Documentation
You may find the following third-party documentation useful.
The Java Language Specification by Gosling, Joy, and Steele
xii
| Typographical Conventions
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions
Convention
Use
TIBCO_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.
CONFIG_FOLDER
HAWK_HOME
code font
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 <TIBCO_HOME>. 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 : \ t i b c o \ h a w k \ 4 . 9 .
Code font identifies commands, code examples, filenames, pathnames, and
output displayed in a command window. For example:
Use M y C o m m a n d to start the foo process.
bold code
Bold code font is used in the following ways:
font
In procedures, to indicate what a user types. For example: Type a d m i n .
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, M y C o m m a n d is enabled:
MyCommand [e n a b l e | disable]
Preface xiii
Table 1 General Typographical Conventions (Contd)

Convention
Use
italic font
Italic font is used in the following ways:
Key
combinations
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: M y C o m m a n d pathname
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.
xiv
| Connecting with TIBCO Resources

Connecting with TIBCO Resources
How to Join TIBCOmmunity

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

After you join TIBCOmmunity, you can access the documentation for all
supported product versions here:
http://docs.tibco.com/TibcoDoc
How to Contact TIBCO Support

For 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.
|1
Chapter 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
| Introduction
Overview
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.
Architecture 3
Architecture
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
Application
Application
Application
Adapter
Adapter
TIBCO Rendezvous
TIBCO Hawk
Agent
TIBCO Hawk
Display
TIBCO Hawk
Agent
TIBCO Hawk
Display
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.
| 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.
Functional Components 5
Functional Components
This section provides a general overview of each product component used by the
TIBCO Hawk Rendezvous Messaging Adapter.
The TIBCO Rendezvous System

TIBCO 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.
| 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 Protocol
The 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.
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.
| Introduction
|9
Chapter 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
10
| Installation
Installing 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 Requirements
The following system requirements are recommended. The actual requirements
depend on your application environment.
Free Disk Space: 60MB minimum.
Memory: 256MB RAM minimum
Software Requirements
The 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 Steps
To run the adapter installation program, you must have administrative privileges
on the adapter machine.
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
T I B _ h a w k r v h m a _ 4 . 0 . 0 _ w 3 2 . e x e package.
4. Follow the InstallShield instructions.
By default, the adapter is installed in the < H A W K _ R O O T > \ a d a p t e r s \ r v h m a
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 Installation
It is recommended that the users first start with the sample configuration files
present in the s a m p l e s directory to get familiar with the features of the adapter.
Before starting the adapter, the attributes values associated with the T I B H A W K _ A M I
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 r v h m a . d t d file as it contains the
grammar rules and descriptions for adapter configurations which are important.
Uninstalling the Software

To uninstall the adapter:
Click
Start>Settings>Control Panel>Add/Remove Programs>TIBCO
Hawk RV Messaging Adapter
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 < H A W K _ R O O T > \ a d a p t e r s \ r v h m a \ s a m p l e s directory.
You may have to modify the environment variable settings in the sample
configuration files before using them. See Overview on page 20 for details.
For a details on installing and uninstalling the adapter as a service, see
Appendix B on Page 79.
Installing on UNIX 13
Installing 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 Requirements
One of the following operating system software is required:
Table 3 Supported UNIX PLatforms
Platform
OS Version
HP
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
Software Requirements
The following software is required and must be installed before starting the
installation procedure:
TIBCO Rendezvous software, version 6.6 or higher.

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 software, version 3.0.0 or higher. A TIBCO Hawk Agent must be
installed and running on the adapter machine.
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.
Table 4 Download Sites for JRE

Platform
Download Sites for JRE
HP
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.html
For example, one suitable site for North America is:

ftp://iodynamics.com/pub/mirror/linux-jdk/
Installation Steps
To 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 installation

A transcript of a typical t a r 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:
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/hawk
Starting installation for platform
s4_56_CC
please wait ...
Installation of <hawkrvhma> was successful.
Pre-requisites for TIBCO Hawk Rendezvous Messaging Adapter 4.0.0
1. TIBHawk 4.0.0 or greater
2. 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.
16
| Installation
After Installation
1. Make sure JRE is installed on your system
2. Create the following environment variables:
Table 5 Environment Variables
Environment
Variable
HAWK_ROOT
RV_ROOT
JRE_ROOT
Description
Example
The directory where

the TIBCO Hawk
software is
installed.
For csh:
The directory where

the TIBCO
Rendezvous
software is
installed.
For csh:
The directory where

the JRE is installed.
For csh:
setenv HAWK_ROOT /opt/tibco/hawk
For sh or ksh:
HAWK_ROOT=/opt/tibco/hawk;
export HAWK_ROOT
setenv RV_ROOT /opt/tibco/rv
For sh or ksh:
RV_ROOT=/opt/tibco/rv; export
RV_ROOT
setenv JRE_ROOT /opt/tibco/java
For 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 PATH
It is recommended that you first start with the sample configuration files present
in the s a m p l e s directory to get familiar with the features of the adapter. Before
using starting the adapter, the T I B H A W K _ A M I 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 r v h m a . d t d file as it contains the
grammar rules and descriptions for adapter configurations which are important.
The file is located in the s a m p l e s directory.
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:
Table 6 Commands to Remove the Adapter on UNIX
Platform
Command
HP
swremove Hawkrvhma
IBM
r m - r f < adapter-install-directory>
SUN
/usr/sbin/pkgrm Hawkrvhma
DEC
/usr/sbin/setld -d Hawkrvhma
LINUX
r m - f r < adapter-install-directory>
This command removes all files that were added during installation.
18
| Installation
| 19
Chapter 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
20
| Configuring the Adapter

Overview
A set of sample configuration files and executable files are copied to the
installation area in the s a m p l e s 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 r v h m a . d t d file contains syntax rules for the adapter configuration file.
During installation, this file is copied to the s a m p l e s 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.
Configuration File Elements and Attributes 21
Configuration File Elements and Attributes

The r v h m a . d t d 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
Description
dtd_type
enume
ration
REQUIRED. (RVHMA).
dtd_version
enume
ration
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 <major>.<minor>.<update>, for
example, 1 . 1 . 0 . The XML file name and
this version number can be queried with
the built-in method, g e t R e l e a s e V e r s i o n .
22

Attribute
Type
Description
ami_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
string

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.
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.
rvNetwork
rvDaemon
cmName
cmLedger
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
Description
rvAdvisoryTraceLevel
enume
ration
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
enume
ration
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
string
IMPLIED. These attributes together define

TIBCO Rendezvous fault tolerance
parameters. The default values are:
ftActiveGoal
ftHeartbeatInterval
ftPrepInterval
ftActiveInterval
ftWeight 100.
ftActiveGoal 1
ftHeartbeatInterval 30 seconds
ftPrepInterval 60 seconds
These attributes are used only if the

ftGroupName is specified.
24

Attribute
Type
Description
traceFile
string

specify the AMI tracing parameters. If not
defined, tracing is sent to stderr.
traceFileMaxSize
traceFileMaxNumber
traceFile. Absolute pathname of the trace

file.
traceLevel
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.
At least one method must be defined for each microagent. Multiple microagents
can be defined in a single configuration file.
Table 8 microagent Element Attributes
name
string
REQUIRED. Name for the microagent.
help
string
IMPLIED. Help text describing the microagent.

Each h e l p attribute is paired with a n a m e attribute.
If not defined, the n a m e attribute value is used as
the help text.
displayName
string
IMPLIED. Name that is displayed in the TIBCO

Hawk Display.
rvService
string
rvNetwork
rvDaemon
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
string
cmLedger
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).
26

traceFile
string
traceFileMax
Size
traceFileMax
Number
traceLevel
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.
If 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.
Table 9 method Element Attributes
Attribute
Type
Description
name
string
REQUIRED. The method name.
help
string
IMPLIED. Help text describing the method. Each

attribute is paired with a n a m e attribute. If
not defined, the n a m e attribute value is used as the
help text.
help
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.

Attribute
Type
Description
subject
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 S u b j e c t or if the method
publishes RVCM messages.
timeout
string
IMPLIED. The t i m e o u t attribute is meaningful

(and required) only for RPC methods. If the
timeout interval expires and no reply is received,
the first return t i m e o u t 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 m a x T h r e a d s
attribute for the microagent must be adjusted
higher accordingly.
28

Attribute
Type
Description
handlerType
enume
rationS
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

t i b r v l i s t e n , t i b r v e c h o and
dynamicSubscribe.
T. Used for the factory provided method

t i m e o u t T e s t only.
S. Used for factory provided system methods,

which include r e v i e w L e d g e r and s h u t d o w n .
For subscriber and RPC methods (with

and R P C respectively) the
specified fields must have a one to one
correspondence with the methods return (output)
parameters.
handlerType SU
For publisher methods (with h a n d l e r T y p e P and

respectively), the message publish subject and
all fields must be specified in the message.
RPC
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 u s e C M attribute

is set to t r u e and the method h a n d l e r T y p e value
is P (is a publisher method). The cmListenerList
attribute specifies a list of c m N a m e names in the
form:
<name1>, <name2>, <name3>, ...
For methods with h a n d l e r T y p e S U , P, or R P C , if the first i n p u t P a r a m e t e r is

named S u b j e c t , it is used as the subject for subscription or publish. (Note: In this
case, the s u b j e c t 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
element, or one or more legal choices in a l e g a l V a l u e C h o i c e s
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.
valueChoices
Table 10 inputParameter Element Attributes

Attribute
Type
Description
name
string
REQUIRED. Name for the input parameter.
help
string
IMPLIED. Help text describing the input parameter.

Each h e l p attribute is paired with a n a m e attribute. If
help text.
type
enume
ration
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 f i e l d N a m e attribute is not specified, it is
assumed to be the same as the n a m e attribute.
See Specifying Field Names in Parameters, page 34 for
details.
30

Table 10 inputParameter Element Attributes
Attribute
Type
Description
pattern
string
IMPLIED. Specifies a pattern to convert string data to

a desired form. The pattern syntax is based on the
j a v a . t e x t . M e s s a g e F o r m a t class specification. See
Java Pattern Matching Syntax, page 77 for more
information.
For example, a pattern { 0 , n u m b e r } K B could be used
to convert a string 1 2 3 K B to a number 1 2 3 (not a
string). If the pattern in the example is { 0 } K B , 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.
An input parameter may have an optional element, v a l u e C h o i c e s or

l e g a l V a l u e C h o i c e s but not both.
The v a l u e C h o i c e s element defines some acceptable values for an
i n p u t P a r a m e t e r 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 l e g a l V a l u e C h o i c e s
element is not specified
Table 11 valueChoices Element Attribute
Attribute
Type
Description
value
string
IMPLIED. Defines suggested values. The values

are separated by comma characters. For
example: 0, 30, 45, 60, 90
The l e g a l V a l u e C h o i c e s element defines the only possible values that can be

specified in an i n p u t P a r a m e t e r method. This element is optional, and can only
be used if v a l u e C h o i c e s 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.
Table 12 legalValueChoices Element Attribute
Attribute
Type
Description
value
string
IMPLIED. Defines legal values only. The values

are separated by comma characters. For
example: 0, 30, 45, 60, 90
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 13 constantParameter Element Attributes
Attribute
Type
Description
name
string
REQUIRED. Name for the constant parameter.
help
string

help text.
type
enume
ration

fieldName
string

details.
32

For subscriber methods (with method h a n d l e r T y p e
special outputParameter names:
SU
or D S ), there are three
Subscription Subject.
M e s s a g e S u b j e c t . Returns the actual subject used by the publisher to publish

the received message.
R e p l y S u b j e c t . Returns the reply subject of the received message. The reply

subject is blank if the sender does not specify a reply subject
Returns the subject used in the subscription. It can

contain wild card characters.
For RPC methods (with method h a n d l e r T y p e R P C ), there is a special

o u t p u t P a r a m e t e r with the name T i m e o u t and type B O O L . It is required and must
be the first o u t p u t P a r a m e t e r. It is used to indicate whether a timeout has
occurred while waiting for the reply.
Table 14 outputParameter Element Attributes
Attribute
Type
Description
name
string
REQUIRED. Name for the output parameter.
help
string

not defined, the n a m e attribute value is used as the help
text.
type
enume
ration

fieldName
string

details.
Table 14 outputParameter Element Attributes

Attribute
Type
Description
pattern
string
IMPLIED. Specifies a pattern to convert string data to a

desired form. The pattern syntax is based on the
j a v a . t e x t . M e s s a g e F o r m a t class specification. See
Java Pattern Matching Syntax, page 77 for more
information.
For example, a pattern { 0 , n u m b e r } K B could be used
to convert a string 1 2 3 K B to a number 1 2 3 (not a
string). If the pattern in the example is { 0 } K B , 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.
34

Specifying Field Names in Parameters
The f i e l d N a m e attribute in an i n p u t P a r a m e t e r, o u t p u t P a r a m e t e r, or
c o n s t a n t P a r a m e t e r element can specify a single field name, nested fields,
repeating fields or arrays.
The following example shows how to specify a single field name:
<constantParameter
name = "A first level field"
fieldName = "STR_FIELD"
type = "STRING"
value = "test"
>
</constantParameter>
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 N E S T E D _ F I E L D , which is another TIBCO Rendezvous message and that
message has a field L 2 . For a parameter corresponding to the value of the field L 3
in N E S T E D _ F I E L D . L 2 , its f i e l d N a m e attribute should be:
<constantParameter
name = "A nested field"
fieldName = "NESTED_FIELD.L2.L3"
type = "I8"
value = "1"
>
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, N E S T E D _ F I E L D . L 2 . L 3 R { 1 } means the field L3R belongs to the first
instance of the repeating field L 3 R of N E S T E D _ F I E L D . L 2 . In the second example,
N E S T E D _ F I E L D . L 2 . L 3 R { 2 } means the field L3R belongs to the second instance of
the repeating field L 3 R of N E S T E D _ F I E L D . L 2 .
<constantParameter
name = "First repeating field L3R in L2"
fieldName = "NESTED_FIELD.L2.L3R{1}"
type = "I16"
value = "2"
>
<inputParameter
name = "Second repeating field L3R in L2"
fieldName = "NESTED_FIELD.L2.L3R{2}"
type = "I64"
>
</inputParameter>
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,
N E S T E D _ F I E L D . L 2 . L 3 A [ 0 ] means the first array element in field L 3 A where L 3 A is
a field of L 2 and L 2 is field of N E S T E D _ F I E L D . In the second example,
N E S T E D _ F I E L D . L 2 . L 3 A [ 1 ] means the second array element in field L 3 A where
L 3 A is a field of L 2 and L 2 is field of N E S T E D _ F I E L D .
<constantParameter
name = "First array element of L3A in L2"
fieldName = "NESTED_FIELD.L2.L3A[0]"
type = "U32"
value = "4"
>
<inputParameter
name = "Second array element of L3A in L2"
fieldName = "NESTED_FIELD.L2.L3A[1]"
type = "U8"
>
</inputParameter>
Note that the type of "array of TibrvMsg" is not supported by TIBCO Rendezvous
and a f i e l d N a m e such as F 1 . F 2 [ 2 ] . F 3 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.
36

Validating an XML Configuration File
The adapter includes an external DTD file, r v h m a .d t d . During installation, this file
is copied to the s a m p l e s 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:
<!DOCTYPE TIBHAWK_AMI SYSTEM "rvhma.dtd">
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 r v h m a .d t d file. If the line that references the
adapter DTD is active, the adapter does not start.
Performing XML Consistency Checks

The 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 Unix
s t a r t t i b h a w k r v h m a - x m l _ f i l e < filename> - c h e c k _ o n l y
On Windows
t i b h a w k r v h m a - - n a m e < servicename> - x m l _ f i l e < filename> - c h e c k _ o n l y
Validating an XML Configuration File 37
Where, <filename> is the complete path to the configuration XML file and
<servicename> is the internal Windows service name given to this instance of the
adapter.
The <servicename> for the default service installed is T I B H a w k R V H m a .
When the - c h e c k _ o n l y 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.
38

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

During 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.
Before starting the adapter for the first time, follow the configuration
instructions in Configuring the Adapter on page 19.
To start the service:
1. In Windows NT Control Panel, open S e r v i c e s .
In Windows 2000 Control Panel, open A d m i n i s t r a t i v e
Services.
2. Click T I B C O
H a w k R V M e s s a g i n g A d a p t e r,
Tools,
then open
then click S t a r t .
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
<file_name>
Where <file_name > is the complete path to the XML configuration file.
Starting and Stopping the Adapter 39
Stopping the Adapter on Windows

Use the default s h u t d o w n method from the TIBCO Hawk Display to stop the
adapter. For a description of this method, see page 65.
To stop the service:
Services.
2. Click T I B C O
Tools,
then open
then click S t o p .
The adapter service stops.
40

Starting the Adapter on UNIX
To start the adapter, execute the following command:
starttibhawkrvhma -xml_file
<file_name>
Where <file_name > is the complete path to the XML configuration file.
The default configuration files are in the $ H A W K _ R O O T / a d a p t e r s / r v h m a / s a m p l e s
directory.
Stopping the Adapter on UNIX

An instance of the adapter can be stopped by any one of the following ways:
Using the default s h u t d o w n method from the TIBCO Hawk Display. For a
description of this method, see page 65.
Using the k i l l
< pid>
command.
Where <pid> is the process ID of the adapter instance.
Changing the Service Log On Account on Windows 41
Changing 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 S e r v i c e s
Services.
2. Click T I B C O
3. In the Log On As panel, click T h i s

and password.
Account
Tools,
then open
then click S t a r t u p .
and type the new user account
4. Click O K .
5. Click C l o s e 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.
42

Viewing 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 t r a c e F i l e 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 t r a c e L e v e l
attribute in the TIB_HAWKAMI element or the t r a c e L e v e l 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 s e t T r a c e L e v e l
TIBCO Hawk method.
| 43
Chapter 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
44
| Testing the Adapter

Overview
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.
Verify Sample Adapter Configuration 45
Verify 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 s a m p l e s
directory. For example, on Windows, type
cd C:\TIBCO\hawk\adapters\rvhma\samples
2. Using a text editor, open the r v h m a . x m l 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 c o n s o l e R V H m a . b a t executable file. Verify that

the following parameters are correct for your environment:
set RV_ROOT=c:\TIBCO\TIBRV
set HAWK_ROOT=c:\TIBCO\hawk
set JRE_ROOT=c:\TIBCO\JRE\1.3.1
On Unix, modify the file r u n R V H m a in a similar way.
46

Start 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.
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 T I B C O
H a w k R V M e s s a g i n g A d a p t e r S t a t u s is not set to S t a r t e d .
Before starting the example on Unix, ensure that the adapter process is not
running.
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 c o n s o l e R V H m a . b a t
On Unix, type r u n R V H m a
Start TIBCO Hawk 47
Start TIBCO Hawk

To start TIBCO Hawk Display:
On Windows:
Select S t a r t > P r o g r a m s > T I B - H a w k S o f t w a r e > H a w k D i s p l a y from the S t a r t
menu, or double-click H a w k D i s p l a y in the TIBCO Hawk program group.
On Unix:
Type s t a r t d i s p l a y 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.
48

Send and Receive a Message
This section is an exercise that shows how to dynamically execute the
t i b r v l i s t e n and t i b r v s e n d methods to send and receive a TIBCO Rendezvous
message. The exercise also shows how to use the s h u t d o w n method to stop the
adapter from TIBCO Hawk Display.
1. In TIBCO Hawk Display, right-click on the agent icon and select G e t
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.
For synchronous methods, this dialog has two modes, I n v o k e and
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.
Subscribe.
For asynchronous methods, the I n v o k e mode should be not be used.

Executing I n v o k e on an asynchronous method will produce an error.
Send and Receive a Message 49
2. Click the microagent name, in this case r v h m a . D e f a u l t : 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 t i b r v l i s t e n and type the name of the subject. For example, t e s t m s g .

4. Verify that the S u b s c r i b e radio button is selected and Click the S u b s c r i b e
button to execute the method.
The S u b s c r i p t i o n
Results
dialog box appears.
5. Repeat step 1 and step 2 to display another method window.

6. Click t i b r v s e n d and type the subject name, t e s t m s g . In M e s s a g e , type H e l l o .
50

7. Verify that the I n v o k e radio button is selected and Click the I n v o k e button to
execute the method.
A M e s s a g e dialog box displays:
8. Click O K to close the dialog.

9. Click the S u b s c i p t i o n
Results
dialog to view the results.
10. Click Done to close the Subscription Results dialog box.
Send and Receive a Message 51
11. In one M i c r o a g e n t s , M e t h o d s a n d A r g u m e n t s dialog box, click the

s h u t d o w n method, then click I n v o k e .
The adapter is shutdown.

12. Click O K to close the dialog box. You can close all open windows and exit the
TIBCO Hawk program.
52

Other Sample Adapters
Sample adapters are available in the H A W K _ R O O T / a d a p t e r s / r v h m a / s a m p l e s
directory. The samples are written for advanced users, but all users can benefit by
from them. The r v h m a S a m p l e 1 adapter has methods for publishing messages or
initiating RPC requests. The r v h m a S a m p l e 2 adapter has methods that subscribe to
messages. For testing purposes, both should be running to communicate with
each other.
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 T I B C O
H a w k R V M e s s a g i n g A d a p t e r S t a t u s is not set to S t a r t e d .
Before starting the example on Unix, ensure that the adapter process is not
running.
Before invoking a sample adapter . b a t 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 c o n s o l e _ r v h m a S a m p l e <n>. b a t
On Unix, type r u n _ r v h m a S a m p l e <n>
On Windows, the sample adapters can also be installed as Windows services by

invoking the i n s t a l l _ r v h m a S a m p l e <n>. b a t 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, r v h m a S a m p l e 1 . h r b and r v h m a S a m p l e 2 . h r b
are also provided for use with the r v h m a S a m p l e 1 and r v h m a S a m p l e 2 adapters.
The sample adapters must be running before these rulebases can be applied.
| 53
Chapter 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
54
| Using Adapter Methods in a Rulebase

Monitor a Log File
In this example, a rulebase is written that monitors a logfile (M y D e m o A p p . l o g ) that
is created and updated by an application (M y D e m o A p p ) 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 M y D e m o A p p i s S H U T T I N G
into the logfile. When the rulebase detects such a line, it publishes a
message announcing the shutdown of the application.
DOWN down
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
L o g f i l e : o n N e w L i n e ( ) method as the data source. Every line returned by this
method is scanned for the words S H U T T I N G . 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 Logfile

1. 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 G e t
Configuration>Rulebases.
Monitor a Log File 55
The R u l e b a s e L i s t f o r A g e n t dialog displays. This dialog lists rulebases

loaded by the current agent and provides options for performing rulebase
operations.
3. Click the C r e a t e button.
4. Type M y D e m o S h u t d o w n in the R u l e b a s e
Name
field.
5. Click the C r e a t e button to display the R u l e E d i t o r dialog.

6. Click E d i t , opposite the D a t a
The M i c r o a g e n t s ,
Source
field.
Methods and Arguments
dialog displays:
7. Click the L o g f i l e : 0 microagent, then click the o n N e w L i n e method.

This method returns the new line added to the specified log file.
This is a synchronous method. When the rule is active, the agent subscribes to
this method and receives data every 60 seconds, by default.
8. In the l o g f i l e field, type c : \ m y d e m o a p p \ m y d e m o a p p . l o g , then click O K .
This argument in the name of the logfile to monitor.
56

Define the Test
The following test checks the log file and takes action if S H U T T I N G is found.
1. In the Rule Editor dialog, click the C r e a t e button to display the T e s t E d i t o r.
The I f field is for the test expression, which you create in the T e s t
dialog.
Builder
The T h e n field is for one or more actions to take if the test evaluates to true.
For more information, see the TIBCO Hawk Administrators Guide.
2. Click the Edit button next to the I f field.
The T e s t
Builder
dialog displays.
3. Click n e x t L i n e to use as the test parameter.

This is one of the result fields returned by the o n N e w L i n e method, which is the
data source for this rule. The text area below the parameter list displays a
short description of each parameter.
4. Click the C o n t a i n s operator. Only operators that apply to the current
parameter are included in the list.
5. Click in the C o n t a i n s field and type S H U T T I N G .
The dialog should look like the following:
6. Click OK to save the I f test.

7. In the T e s t E d i t o r dialog, click the C r e a t e button on the toolbar.
8. In A c t i o n T y p e , click M e t h o d . In M e t h o d , click the E d i t button to specify the
method information.
Monitor a Log File 57
dialog displays.
9. Click the r v h m a : D e f a u l t : < n > microagent, then click the t i b r v s e n d method.

10. In the Subject field, type M y D e m o A p p . I N F O .
The Alert Detail window displays detailed properties of the alert, including
the generating agent and rulebase, message text, and the date and time
generated.
11. In the Message field, type A p p l i c a t i o n
MyDemoApp is SHUTTING DOWN.
The display should look like:
12. Click O K to save the action information.

13. In the Action Editor, click the A d v a n c e d button.
By default, actions are performed only once. For this rule to retrieve data
periodically, you must modify the default action settings. For more
information on how actions are triggered and performed, see the TIBCO Hawk
Administrator's Guide.
14. Click the Always radio button to select it.
This setting triggers the action every time the associated test is performed, in
this case at every data collection interval.
15. Click OK to exit the A d v a n c e d
Editors.
Action, Action, Test, Rule
and R u l e b a s e
58

The M y D e m o A p p _ r u l e b a s e rulebase is included in the R u l e b a s e
dialog on the adapter machine:
List For
Agent
16. Click A p p l y
running.
Changes
to save the rulebase on the agent where the adapter is
View the Results

When the adapter is running, the TIBCO Rendezvous messages sent and received
are written to the adapter log file if the DEBUG trace level is turned on. The log
file is specified by the t r a c e F i l e parameter. The log file entry for the TIBCO
Rendezvous message sent looks like the following:
DEBUG
2001/03/16 14:30:07.763 Msg to send:{ _data_="MyDemoApp is
SHUTTING DOWN" }
RV
2001/03/16 14:30:07.824
publish on subject:MyDemoApp.INFO
msg: { _data_="MyDemoApp is SHUTTING DOWN" }
You can also use the t i b r v l i s t e n method to subscribe to the M y D e m o A p p . I N F O

subject to view the results.
Monitor an Applications Heartbeat 59
Monitor an Applications Heartbeat

In this example, a rulebase is written that listens for an applications heartbeats
(status messages) and starts another application if a heartbeat is not received in a
specific timeframe.
A new parameter is added to control the expired agent kept in the system.
Parameter can be specified in w e b . x m l as: < i n i t - p a r a m >
<param-name>AgentExpiredRetentionPeriod</param-name><param-value>1
5</param-value></init-param>
If this parameter is not specified, default is 5 minutes.
Define the Subject and Timeout Interval

1. 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 G e t
Configuration>Rulebases.
The R u l e b a s e L i s t f o r A g e n t dialog displays. This dialog lists rulebases

loaded by the current agent and provides options for performing rulebase
operations.
3. Click the C r e a t e button.
60

4. Type M o n i t o r H e a r t b e a t D e m o in the R u l e b a s e
Name
field.
5. Click the C r e a t e button to display the R u l e E d i t o r dialog.

6. Click E d i t , opposite the D a t a
Source
field.
dialog displays:
7. Click the r v h m a . D e f a u l t : < n > microagent, then click the t i m e o u t T e s t

method.
8. In the S u b j e c t field, type M y H e a r t b e a t . t e s t . In the Timeout Interval field,
type 1 0 , then click O K .
Define the Test

The following test checks the T i m e o u t
value is set to T r u e .
Interval
variable and takes action if its
1. In the Rule Editor dialog, click the C r e a t e button to display the T e s t E d i t o r.
Monitor an Applications Heartbeat 61
The I f field is for the test expression, which you create in the T e s t
dialog.
Builder
The T h e n field is for one or more actions to take if the test evaluates to true.
For more information, see the TIBCO Hawk Administrators Guide.
2. Click the E d i t button next to the I f field.
The T e s t
Builder
dialog displays.
3. In P a r a m e t e r, click T i m e o u t .
4. In O p e r a t o r, click i s T r u e .
The dialog should look like the following:
5. Click O K to save the I f test.

6. In the T e s t E d i t o r dialog, click the C r e a t e button on the toolbar.
7. In A c t i o n T y p e , click M e t h o d . In M e t h o d , click the E d i t button to specify the
method information.
dialog displays.
8. Click the S e r v i c e s : 0 microagent, then click the s t a r t S e r v i c e method.

9. In the Service field, select I n s e r t > I n t e r n a l
Variable>Agent Name.
62

The display should look like:
10. Click O K to save the action information.

11. In the Action Editor, click the A d v a n c e d button.
By default, actions are performed only once. For this rule to retrieve data
periodically, you must modify the default action settings. For more
information on how actions are triggered and performed, see the TIBCO Hawk
Administrator's Guide.
12. Click the A l w a y s radio button to select it.
This setting triggers the action every time the associated test is performed, in
this case at every data collection interval.
13. Click O K to exit each of the editors.
The M o n i t o r H e a r t b e a t D e m o rulebase is included in the R u l e b a s e
A g e n t dialog on the adapter machine:
List For
14. Click Apply Changes to save the rulebase on the agent where the adapter is
running.
| 63
Chapter 6
Adapter Methods Reference
The TIBCO Hawk Rendezvous Messaging Adapter is represented by microagents

that communicate with TIBCO Hawk Agents. These microagents provide
methods for monitoring TIBCO Rendezvous messages, sending TIBCO
Rendezvous messages and getting information from microagents. This chapter
describes these methods, which you can invoke interactively or in a TIBCO Hawk
rulebase.
Topics
Methods Summary, page 64
64
| Adapter Methods Reference

Methods Summary
The following methods are exposed for monitoring and managing the adapter.
The adapter sample XML configuration files contain additional custom methods
that are documented in the online help.
Method
Description
shutdown
Shuts down the adapter and exits.
getReleaseVersion
Returns version information about the current

release of this microagent.
getTraceParameters
Gets the trace parameter values.
setTraceParameters
Sets the trace parameter values.
getTraceLevel
Gets the trace level settings.
setTraceLevel
Sets the trace level settings.
getMaxThreads
Returns the maximum number of AMI

invocation handling threads for the adapter.
setMaxThreads
Sets the maximum number of AMI invocation

handling threads for this session of the
adapter.
tibrvsend
Sends a TIBCO Rendezvous message.
tibrvlisten
Receives a TIBCO Rendezvous message.
tibrvecho
Echoes its message back to the sender.

(Primarily used for testing RPC methods)
dynamicSubscriber
Receives a TIBCO Rendezvous message and

converts message fields to strings and maps
them to separate columns.
_onUnsolicitedMsg
Returns any unsolicited notifications the

adapter sends to the TIBCO Hawk Agent.
shutdown 65
shutdown
Method
Shuts down the adapter and exits.

Type
SYNC, IMPACT_INFO
Arguments
None.
Returns
None.
Usage Notes
If the adapter process is running, invoking this method stops the adapter
gracefully.
66

getReleaseVersion
Method
Returns version information about the current release of this microagent.

Type
Arguments
Returns
Usage Notes
SYNC, IMPACT_ACTION_INFO
None.
Name
Type
Description
Name
String
The name of the application which

implements this microagent.
Version
String
The release version of the component, for

example, 1 . 0 . For the adapter
configuration file, this is the value of the
x m l _ v e r s i o n attribute in the file.
Date
Integer
The date and time this component was

last modified.
Major
Integer
The release version major number.
Minor
Integer
The release version minor number.
Update
Integer
The release version update number.
This method retrieves the release version of the current adapter.
getTraceParameters 67
getTraceParameters
Method
Gets the trace parameter values.

Type
Arguments
Returns
Usage Notes
SYNC, IMPACT_ACTION
None.
Name
Type
Description
Directory
String
Directory path for the trace log file. The

current directory is the default value.
File Name
String
Trace file name.
Max File Size
Integer
Trace file maximum size before it is

rolled over, in Kbytes.
Max Trace File
Integer
Maximum number of trace files to keep

in the trace directory.
This method returns log file parameter values.
68

setTraceParameters
Method
Sets the trace parameter values.

Type
SYNC, ACTION_INFO
Arguments
Returns
Usage Notes
Name
Type
Description
Directory
String
Directory path for the trace log file. The

current directory is the default value.
File Name
String
Trace file name.
Max File Size
Integer
Trace file maximum size before it is

rolled over, in Kbytes.
Max Trace File
Integer
Maximum number of trace files to keep

in the trace directory.
None.
This method modifies log file parameter values. To keep the current setting for
string parameters, use the string c u r r e n t . For integer parameters, use 0 .
getTraceLevel 69
getTraceLevel
Method
Gets the trace level settings.

Type
Arguments
Returns
Usage Notes
SYNC, IMPACT_INFO
None.
Name
Type
Description
Information
String
Information trace setting.
Warning
String
Warning trace setting.
Error
String
Error trace setting.
Debug
String
Adapter debug trace setting. This option

is for troubleshooting purposes only, and
under normal circumstances should not
be enabled.
AMI
String
AMI debug trace setting. This option is

for troubleshooting purposes only, and
be enabled.
RV
String
Adapter-related debug tracing. This

option is for troubleshooting purposes
only, and under normal circumstances
should not be enabled.
This method returns the current level of trace information written to the adapter
log file. For information on trace level usage, see the TIBCO Hawk Programmers
Guide.
70

setTraceLevel
Method
Sets the trace level settings.

Type
Arguments
Returns
Usage Notes
Name
Type
Description
Information
String
Information trace setting.
Warning
String
Warning trace setting.
Error
String
Error trace setting.
Debug
String
Adapter debug trace setting. This option

is for troubleshooting purposes only, and
be enabled.
AMI
String
AMI debug trace setting. This option is

for troubleshooting purposes only, and
be enabled.
RV
String
Adapter-related debug tracing. This

option is for troubleshooting purposes
only, and under normal circumstances
should not be enabled.
None.
This method allows you to set the level of trace information written to the adapter
log file. Specifying the string c u r r e n t preserves the current setting. For
information on trace level usage, see the TIBCO Hawk Programmers Guide.
getMaxThreads 71
getMaxThreads
Method
Returns the maximum number of AMI invocation handling threads for the
adapter.
Type
Arguments
Returns
Usage Notes
SYNC, IMPACT_INFO
None.
Name
Type
Description
Maximum Threads
Integer
The maximum number of AMI invocation

handling threads.
This method returns the number of method invocations that can run in parallel. If
more methods are simultaneously invoked than the M a x i m u m T h r e a d s value,
extra methods are delayed. This value should be high enough to accommodate
typical usage.
This method is available only if a m a x T h r e a d s value is specified for a microagent
in the adapter XML configuration file.
72

setMaxThreads
Method
Sets the maximum number of AMI invocation handling threads for this session of
the adapter.
Type
Arguments
Returns
Usage Notes
Name
Type
Description
Maximum Threads
Integer
The maximum number of AMI invocation

handling threads.
None.
This method sets the number of method invocations that can run in parallel. If
more methods are simultaneously invoked than the M a x i m u m T h r e a d s value,
extra methods are delayed. This value should be high enough to accommodate
typical usage.
This method is available only if a m a x T h r e a d s value is specified for a microagent
in the adapter XML configuration file.
tibrvsend 73
tibrvsend
Method
Sends a simple TIBCO Rendezvous message as a string.

Type
Arguments
Returns
SYNC, IMPACT_INFO
Name
Type
Description
Subject
String
TIBCO Rendezvous message subject.
Message
String
TIBCO Rendezvous message text.
None.
74

tibrvlisten
Method
Receives a TIBCO Rendezvous message.

Type
Arguments
Returns
SYNC, IMPACT_INFO
Name
Type
Description
Subject
String
Name
Type
Description
Subscription
Subject
String
TIBCO Rendezvous subscription subject.
Message Subject
String
TIBCO Rendezvous message subject

specified by the sender.
MSG_CONTENT
String
TIBCO Rendezvous message content.
dynamicSubscriber 75
dynamicSubscriber
Method
The dynamic subscriber method is similar to tibrvlisten except that message fields
are converted to strings and mapped to separate (up to 20) columns.
Type
SYNC, IMPACT_INFO
Arguments
Returns
Name
Type
Description
Subject
String
Name
Type
Description
Subscription
Subject
String
TIBCO Rendezvous subscription subject.
Message Subject
String
TIBCO Rendezvous message subject

specified by the sender.
FIELD n *
String
TIBCO Rendezvous message data for

each field (up to 20 fields).
where n = 1 to 20.
76

_onUnsolicitedMsg
Method
Returns any unsolicited notifications the adapter sends to the TIBCO Hawk
Agent.
Type
Arguments
Returns
ASYNC, IMPACT_INFO
None.
Name
Type
Description
TYPE
String
The notification type.

Must be one of the following: INFO,
WARNING or ERROR.
Usage Notes
TEXT
String
The text description of the message.
ID
Integer
A user defined number that is typically

used to assign an unique ID to each
message. this field makes monitoring
notifications more efficient. This
INBOX
String
Invoking this method returns the last unsolicited notification message that was
received (if any). Subscribing to the method receives all incoming unsolicited
messages.
| 77
Appendix A
Java Pattern Matching Syntax
This appendix describes the pattern matching syntax used for parsing and
converting method input and output parameters. When a pattern is specified in
the adapter configuration file, the adapter converts input text data to the specified
format.
Topics
Pattern Matching Syntax, page 78
78
| Java Pattern Matching Syntax

Pattern Matching Syntax
In parameter definitions, the adapter supports using the pattern matching syntax
defined by the j a v a . t e x t . M e s s a g e F o r m a t class specification. By referencing a
pattern in an input or output parameter definition, you can convert the input data
to various types and formats.
For more information on j a v a . t e x t . M e s s a g e F o r m a t , see:
<jdk_root>/docs/api/java/text/MessageFormat.html
Patterns are applied using argument placeholders, which have the following
form:
{
number, [ type] , [ format] }
The curly brackets and number argument are required. The number argument can be
from 0 to 9.
The type argument is optional, and indicates the argument data type. It can be one
of t i m e , d a t e , n u m b e r, or c h o i c e .
The format argument is also optional, and is a string that describes the argument
format. Possible format values depend on the specified type. For more
information on possible values for format, see the Java API documentation for the
C h o i c e F o r m a t , D a t e F o r m a t and N u m b e r F o r m a t classes.
You specify the argument placeholder in the p a t t e r n attribute of the
i n p u t P a r a m e t e r o r o u t p u t P a r a m e t e r element. Only the first argument
placeholder in the pattern is used and the others are ignored.
Table 15 Examples of using Argument{0} in Patterns
Text
Pattern
Result (Argument {0})
256 KB
{0,number}KB
256
xyz (5%)
{1}({0,number}%)
Host:smiles-no
response
{1):{0}-{2}
smiles
| 79
Appendix B
TIBCO Hawk Service Wrapper for Windows
This appendix describes the TIBCO Hawk Service Wrapper for the Windows
environment.
Topics
Installing the Adapter as a Windows Service, page 80
Uninstalling the Adapter as a Windows Service, page 83
Executing the Adapter as a Windows console application, page 83
Executing the Adapter as a Windows Service, page 84
80
| TIBCO Hawk Service Wrapper for Windows

Windows Wrapper
The TIBCO Hawk Rendezvous Messaging Adapter for the Windows platform is
packaged as a Windows service. The t i b h a w k r v h m a . e x e program, found in the
b i n directory of the TIBCO Hawk installation, implements this Windows service.
The t i b h a w k r v h m a . e x e program is a wrapper program that wraps the adapter
Java application allowing it to run as a Windows service. The t i b h a w k r v h m a . e x e
program can be used to perform the following functions:
Install the adapter as a Windows service
Uninstall the adapter as a Windows service
Execute the adapter as a Windows console application
Execute the adapter as a Windows service.
Installing the Adapter as a Windows Service

The ti b h a w k r v h m a . e x e program can be installed as an instance of the adapter
Windows service. As part of the install command processing, the
t i b h a w k r v h m a . e x e program registers itself as the Windows service executable.
For this reason, the install command should be executed from the directory where
the executable is present.
The syntax of the tibhawkrvhma.exe program install command is:
tibhawkrvhma.exe --install <options>
The following table describes the command lines options used:

Table 16 Command Line Options
Option
-name
Description
servicename
The given internal service name.

The default is T I B H a w k R V H m a .
-displayname
displayname
The given external service name.

The default is TIBCO Hawk RV Messaging
Adapter.
-manual
The service is configured for a manual start.
Windows Wrapper 81
Table 16 Command Line Options

Option
Description
-auto
The service is configured for a auto start.

Note: Either m a n u a l or a u t o should be
specified. If none is specified, then the
default is m a n u a l .
-account
accountname
The user account which runs the service.

The default is the System account.
password
-password
-params
(p1 p2 ...pN)
The account password.

The startup parameters for the service.
The parentheses are required to distinguish
startup parameters from other install
command line options and they must be
delimited by blanks.
-jvm11opts
(o1 o2 ...oN)
The Java 1.1 Virtual Machine options.

JVM parameters from other install
-jvmopts
(o1 o2 ...oN)
The Java 2 Virtual Machine options.

JVM parameters from other install
The - n a m e and - d i s p l a y n a m e options allow multiple instances of the adapter

Windows service to be installed. Each instance must have a unique -name and
should have a unique - d i s p l a y n a m e .
The - p a r a m s ( ) option allows for the specification of startup parameters for the
TIBCO Hawk Rendezvous Messaging Adapter. These startup parameters are
registered with the installation and become the default startup parameters for this
instance of the adapter Windows service. If startup parameters are specified when
this service is actually started they will completely override these default values.
82

The - j v m 1 1 o p t s ( ) option allows for the specification of Java 1.1 Virtual Machine
(JVM) options to be passed to the JVM at execution time. This option supports all
the Java 1.1 runtime options. These JVM options are platform specific. See the
Java runtime executable (j r e . e x e ) help for details on the options available on
your platform.
The - j v m o p t s ( ) option allows for the specification of Java 2 Virtual Machine
(JVM) options to be passed to the JVM at execution time. This option supports all
the Java 2 runtime options. These JVM options are platform specific. See the Java
runtime executable (j a v a . e x e ) help for details on the options available on your
platform. This option is only required if you wish to specify Java 2 specific
options.
The t i b h a w k r v h m a . e x e program automatically detects the version of the JVM at
execution time and uses the appropriate JVM options according to the following
table:
Table 17 JVM Options
JVM Options
Specified
Running Under JVM 1.1
Running Under
JVM 1.2 or 1.3
None
JVM defaults used
JVM defaults used
-jvm11opts
-jvmopts
only
only
-jvm11opts
and
-jvm11opts
used
JVM defaults used

-jvm11opts
used
-jvm11opts
used
-jvmopts
used
-jvmopts
used
-jvmopts
Java Classpath
The t i b h a w k r v h m a . e x e program automatically constructs the Java classpath for
the TIBCO Hawk Rendezvous Messaging Adapter Windows service. Assuming
that the t i b h a w k r v h m a . e x e program is located in directory c : \ t i b c o \ h a w k \ b i n ,
the constructed classpath will consist of the following in the specified order:
All . j a r files located in the c : \ t i b c o \ h a w k \ b i n \ . . \ a d a p t e r s \ r v h m a \ j a v a

directory.
The Java Runtime default classpath.
The CLASSPATH environment variable.
This classpath can be altered by specifying the -c p and -c l a s s p a t h options in the

-j v m 1 1 o p t s and -j v m o p t s . The classpath specified in the -c p option is used as a
prefix to the classpath described above. The classpath specified in the -c l a s s p a t h
option replaces (overrides) the classpath described above.
Windows Wrapper 83
There are additional classpath related properties that can be specified for the Java
2 platform. See the Java documentation for details. The t i b h a w k r v h m a . e x e
program passes the classpath described above, to the Java 2 virtual machine using
the - D j a v a . c l a s s . p a t h property. The user should not specify this property
directly but use the -c p and -c l a s s p a t h options to alter the classpath.
Since the detailed command for installing the adapter as a Windows service is
quite complicated. It is suggested you use the sample batch file such as
r v h m a S a m p l e 1 . b a t provided in the samples directory as a template to write
your own to start your custom adapters.
Uninstalling the Adapter as a Windows Service

An instance of the adapter Windows service can be removed using the remove
command line option. The syntax of the command is:
t i b h a w k r v h m a . e x e - - r e m o v e < options>
Where the <options> are:

-name <servicename>, which is the internal service name used when the service was
installed.
The -- r e m o v e command will automatically stop the Windows service if it is
running prior to uninstalling it.
Executing the Adapter as a Windows console application

The adapter can be executed as a Windows console application from the
command line using the ti b h a w k r v h m a . e x e program. Running the adapter as a
console application is useful when diagnosing problems or when using it with a
debugger. The command for executing the adapter is:
t i b h a w k r v h m a . e x e - - n a m e < servicename> - x m l _ f i l e < filename> [ - c h e c k _ o n l y ]
Where <servicename> is the internal service name used when the service is installed,
and <filename> is the complete pathname of the XML configuration file.
The command for specifying the -- h e l p option to display the command line
syntax for the adapter is:
tibhawkrvhma.exe --help/--h/--? <options>
The Windows service for the adapter with the specified <servicename> must be
installed before an adapter can be executed as a Windows console application.
84

Executing the Adapter as a Windows Service
To start the service:
Services.
Tools,
then open
2. Click <displayname> , then click S t a r t .

The <displayname> is the external name given to this instance of the adapter
when the service was installed.
The adapter service starts.
| 85
Index
adapter
starting 38
stopping 39
AMI Protocol
description 6
Architecture 3
array field 35
inputParameter attributes
fieldName 29
help 29
name 29
pattern 30
type 29
Installation steps
UNIX 14
Windows NT 10
installing a custom adapter 12
C
changing the service log on account on NT 41
configuration file
changing defaults 45
validating 36
configuring the adapter 20
constantParameter attributes
fieldName 31
help 31
name 31
type 31
customer support xiv
F
field
array 35
nested 34
repeating 34
functional components 5
L
legalValueChoices attribute
value 31
M
Method attributes
cmListenerList 28
handlerType 28
help 26
index 26
subject 27
timeout 27
useCM 28
86
|
methods
_onUnsolicitedMsg 76
dynamicSubscriber 75
getMaxThreads 71, 71
getReleaseVersion 66
getTraceLevel 69
getTraceParameters 67
setMaxThreads 72
setTraceLevel 70
setTraceParameters 68
shutdown 65
tibrvlisten 74
tibrvsend 73
Microagent attributes
cmLedger 25
cmName 25
displayName 24
help 24
maxThreads 25
name 24, 26
rvDaemon 25
rvNetwork 25
rvService 25
traceFile 26
traceFileMaxNumber 26
traceFileMaxSize 26
traceLevel 26
N
nested field 34
O
outputParameter attributes
fieldName 32
help 32
name 32
pattern 33
type 32
R
repeating field 34
S
shutdown 48
starting the adapter 38
UNIX 40
Windows NT 38
starting TIBCO Hawk Display 47
stopping the adapter 39
UNIX 40
Windows NT 39
support, contacting xiv
T
technical support xiv
TIBCO Hawk Display
starting 47
TIBCO_HOME xii
| 87
TIBHAWK AMI attribute
ami_rvd_daemon 22
ami_rvd_network 22
ami_rvd_service 22
cmLedger 22
cmName 22
dtd_type 21
dtd_version 21
ftActiveGoal 23
ftActiveInterval 23
ftGroupName 23
ftHeartbeatInterval 23
ftPrepInterval 23
ftWeight 23
rvAdvisoryForward 23
rvAdvisoryTraceLevel 23
rvDaemon 22
rvNetwork 22
rvService 22
traceFile 24
traceFileMaxNumber 24
traceFileMaxSize 24
traceLevel 24
xml_file_version 21
tibrvlisten 48
tibrvsend 48
U
Uninstalling the adapter
UNIX 17
Windows NT 11
V
validating configuration file 36
valueChoices attribute
value 30

Writing Custom Rules

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Writing Custom Rules

Transféré par

Droits d'auteur :

Formats disponibles

TIBCO Hawk Rendezvous

Chapter 3 Configuring the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

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

Chapter 4 Testing the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 5 Using Adapter Methods in a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Monitor an Applications Heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 6 Adapter Methods Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

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

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

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

TIBCO Rendezvous Features and TIBCO Hawk Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Supported UNIX PLatforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Download Sites for JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Commands to Remove the Adapter on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

TIBHAWK_AMI Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

microagent Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

method Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

inputParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

valueChoices Element Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

legalValueChoices Element Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

constantParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

outputParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Examples of using Argument{0} in Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Related Documentation, page x

Typographical Conventions, page xii

Connecting with TIBCO Resources, page xiv

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

TIBCO Hawk Documentation

TIBCO Hawk Administrators Guide This manual includes basic descriptions of

TIBCO Hawk Plug-in for TIBCO Administrator Contains detailed descriptions

TIBCO Hawk AMI C Reference Contains detailed descriptions of each datatype

TIBCO Hawk AMI C++ Reference Contains detailed descriptions of each

TIBCO Hawk Console API Reference Contains detailed descriptions of each

TIBCO Hawk Configuration Object API Reference Contains detailed descriptions

TIBCO Hawk Methods Reference A reference to the microagents and methods

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

TIBCO Hawk HTTP Adapter Users Guide Contains information about

TIBCO Hawk Enterprise Message Service Administrator Plug-in Microagent

Other TIBCO Product Documentation

TIBCO Enterprise Message Service

The Java Language Specification by Gosling, Joy, and Steele

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

A TIBCO configuration folder stores configuration data generated by TIBCO

Bold code font is used in the following ways:

In procedures, to indicate what a user types. For example: Type a d m i n .

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

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

Table 1 General Typographical Conventions (Contd)

Italic font is used in the following ways:

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

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

TIBCO Hawk Rendezvous Messaging Adapter Users Guide

| Connecting with TIBCO Resources

How to Join TIBCOmmunity

How to Access All TIBCO Documentation

How to Contact TIBCO Support

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