TIBCO Hawk AMI C++ Reference Iv | Contents

TIBCO Hawk® AMI C++ Reference

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 Hawk, TIBCO Designer, TIBCO Rendezvous, TIBCO Enterprise Message Service, TIBCO Runtime Agent, TIBCO Administrator, TIBCO ActiveEnterprise and TIBCO Repository 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 © 1996-2010 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information | iii Contents

Preface ...... vii Changes from the Previous Release of this Guide ...... viii Related Documentation ...... ix TIBCO Hawk Documentation ...... ix Other TIBCO Product Documentation ...... x Third-Party Documentation...... x Typographical Conventions ...... xi Connecting with TIBCO Resources ...... xiii How to Join TIBCOmmunity ...... xiii How to Access All TIBCO Documentation ...... xiii How to Contact TIBCO Support ...... xiii

Chapter 1 Introduction...... 1 The AMI Protocol ...... 2 TIBCO Hawk AMI C++ API ...... 3 AmiSession Class...... 3 AmiMethod Class ...... 3 AmiSyncMethod Class ...... 3 AmiAsyncMethod Class ...... 3 AmiParameter, AmiParameterIn and AmiParameterOut Classes...... 4 AmiParameterList, AmiParameterListIn and AmiParamterListOut Classes ...... 4 AmiStatus Class ...... 4 AmiSubscription Class ...... 4 AmiList and AmiLink Classes ...... 5 Error Logging ...... 5 C++ API Tracing ...... 5 Threading Model...... 5 AMI C++ API Sample Programs ...... 6

Chapter 2 C++ API Architecture ...... 7 Synchronous and Asynchronous Methods ...... 8 Auto-Invoke Methods ...... 9 AMI Internal Processes ...... 11 Optional Components...... 12 AMI Instrumentation without TIBCO Rendezvous ...... 12

TIBCO Hawk AMI C++ Reference iv | Contents

Chapter 3 C++ Programmer’s Checklist ...... 15 General Steps for Programmers ...... 16 Library Files ...... 17

Chapter 4 AMI Session Class ...... 19 AmiSession ...... 20 AmiSession() ...... 22 AmiSession::open() ...... 24 AmiSession::close() ...... 25 AmiSession::versionName() ...... 26 AmiSession::version() ...... 27 AmiSession::versionDate() ...... 28 AmiSession::banner() ...... 29 AmiSession::versionMajor() ...... 30 AmiSession::versionMinor() ...... 31 AmiSession::getTraceLevels() ...... 32 AmiSession::setTraceLevels() ...... 33 AmiSession::enableTraceLevels() ...... 34 AmiSession::disableTraceLevels() ...... 35 AmiSession::announce() ...... 36 AmiSession::get... Accessors ...... 37 AmiSession::sendUnsolicitedMsg() ...... 38 AmiSession::stop()...... 39

Chapter 5 AMI Methods Classes ...... 41 AmiMethod ...... 42 AmiMethod::setIndexName() ...... 43 AmiMethod::get...() Accessors...... 44 AmiMethod::onInvoke() ...... 45 AmiAsyncMethod ...... 46 AmiAsyncMethod()...... 47 AmiAsyncMethod::onStart()...... 48 AmiAsyncMethod::onStop() ...... 49 AmiAsyncMethod::onData()...... 50 AmiAsyncMethod::sendData() ...... 51 AmiAsyncMethod::sendError()...... 52 AmiSyncMethod ...... 53 AmiSyncMethod() ...... 54 AmiSubscription ...... 55 AmiSubscription::getUserData() ...... 56 AmiSubscription::setCallbackInterval() ...... 57 AmiSubscription::setUserData() ...... 58

TIBCO Hawk AMI C++ Reference Contents | v

AmiSubscription::getMethod() ...... 59 AmiSubscription::getArguments()...... 60

Chapter 6 AMI Parameter Classes ...... 61 AmiParameter ...... 62 AmiParameter::addChoice() ...... 63 AmiParameter::addLegal() ...... 64 AmiParameter::getStatus() ...... 65 AmiParameterIn ...... 66 AmiParameterIn() ...... 67 AmiParameterOut ...... 68 AmiParameterOut()...... 69 AmiParameterList ...... 70 AmiParameterListIn ...... 71 AmiParameterListIn::getValue() ...... 72 AmiParameterListOut ...... 73 AmiParameterListOut() ...... 74 AmiParameterListOut::newRow() ...... 75 AmiParameterListOut::setValue() ...... 76

Chapter 7 AMI Error Handling...... 77 AmiStatus ...... 78 AmiStatus()...... 80 AmiStatus::getAmiError() ...... 81 AmiStatus::setStatus() ...... 82 AmiStatus::setStatusV() ...... 83 AmiStatus::stamp() ...... 84 AmiStatus::getCode() ...... 85 AmiStatus::getText() ...... 86 AmiStatus::getThread() ...... 87 AmiStatus::getFile() ...... 88 AmiStatus::getLine() ...... 89

Index ...... 91

TIBCO Hawk AMI C++ Reference vi | Contents

TIBCO Hawk AMI C++ Reference | vii Preface

This manual describes the TIBCO Hawk® Application Programming Interface (API) for C++ programmers. The first part of this manual deals with the concepts involved in writing API programs for the TIBCO Hawk monitoring system, as well as use of the Application Management Interface (AMI). The following sections deal with the specific programming languages and their various components. This manual assumes you are familiar with TIBCO Rendezvous architecture and the concepts of system monitoring.

Topics

• Changes from the Previous Release of this Guide, page viii • Related Documentation, page ix • Typographical Conventions, page xi • Connecting with TIBCO Resources, page xiii

TIBCO Hawk AMI C++ Reference viii | Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide

This section itemizes the major changes from the previous release of this guide. Some sections have been updated with respect to TIBCO Hawk documentation defects.

TIBCO Hawk AMI C++ Reference Preface | ix

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 Administrator’s 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 Programmer’s Guide All programmers should read this manual. It covers the AMI protocol, AMI messages, the AMI Workbench development tool, and the TIBCO Hawk security framework and its classes. Programmers should then refer to the appropriate language reference for the AMI API. The TIBCO Hawk Application Management Interface (AMI) exposes internal application methods to TIBCO Hawk. • TIBCO Hawk AMI C Reference Contains detailed descriptions of each datatype and function in the TIBCO Hawk C AMI API. • TIBCO Hawk AMI C++ Reference Contains detailed descriptions of each datatype and function in the TIBCO Hawk C++ AMI API. • TIBCO Hawk AMI Java Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Java AMI API. • TIBCO Hawk Console API Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Console API, a set of Java interfaces that allow you to manage and interact with TIBCO Hawk agents and monitor alerts generated by these agents. • TIBCO Hawk Configuration Object API Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Configuration Object API. • TIBCO Hawk Methods Reference A reference to the microagents and methods used by a TIBCO Hawk Agent for system and application monitoring.

TIBCO Hawk AMI C++ Reference x | Related Documentation

• TIBCO Hawk HTTP Adapter User’s 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 User’s 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

TIBCO Hawk AMI C++ Reference Preface | xi

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions Convention Use Many TIBCO products CAN be installed within the same directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME 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 A TIBCO configuration folder stores configuration data generated by TIBCO products. Configuration data can include sample scripts, session data, configured binaries, logs, and so on. This folder is referenced in documentation as CONFIG_FOLDER. TIBCO Hawk installs into a directory within . This directory is HAWK_HOME referenced in documentation as HAWK_HOME. The value of HAWK_HOME depends on the operating system. For example on Windows systems, the default value is C:\tibco\hawk\4.9.

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

Use MyCommand to start the foo process.

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

• In procedures, to indicate what a user types. For example: Type admin. • In large code samples, to indicate the parts of the sample that are of particular interest. • In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]

TIBCO Hawk AMI C++ Reference xii | Typographical Conventions

Table 1 General Typographical Conventions (Cont’d) Convention Use

italic font Italic font is used in the following ways: • To indicate a document title. For example: See TIBCO BusinessWorks Concepts. • To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. • To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname

Key Key name separated by a plus sign indicate keys pressed simultaneously. For combinations 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.

TIBCO Hawk AMI C++ Reference Preface | xiii

Connecting with TIBCO Resources

How to Join TIBCOmmunity TIBCOmmunity is an online destinaton for TIBCO customers, partners, and resident experts—a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.

How to Access 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.

TIBCO Hawk AMI C++ Reference xiv | Connecting with TIBCO Resources

TIBCO Hawk AMI C++ Reference | 1

Chapter 1 Introduction

This manual describes the TIBCO Hawk Applications Management Interface (AMI) API for the C++ programming language.

Topics

• The AMI Protocol, page 2 • TIBCO Hawk AMI C++ API, page 3 • AMI C++ API Sample Programs, page 6

TIBCO Hawk AMI C++ Reference 2 | Chapter 1 Introduction

The AMI Protocol

The TIBCO Hawk Application Management Interface (AMI) protocol is a specification of TIBCO Rendezvous messages that define the interactions between an AMI manager and an AMI application. An AMI manager is any application that is monitoring and/or managing AMI applications via the AMI protocol. A TIBCO Hawk agent is an example of an AMI manager. An AMI application exposes internal methods that allow AMI managers to manage and monitor that application by exchanging data and events with it.

Note: You should first read and understand the discussion of the AMI protocol in the TIBCO Hawk Programmer’s Guide before attempting to use the AMI C++ API described in this manual.

TIBCO Hawk AMI C++ Reference TIBCO Hawk AMI C++ API | 3

TIBCO Hawk AMI C++ API

The AMI C++ API facilitates the development of AMI applications written in the C++ programming language. This API makes AMI application development easier and more foolproof because it takes care of all the AMI and TIBCO Rendezvous protocol details for you. The API also ensures that your application will be compatible with future releases of TIBCO Hawk and AMI.

AmiSession Class An AMI application written with the AMI C++ API is centered on the AmiSession class. The AmiSession class encapsulates the entire interaction of your AMI application with an AMI manager. The AmiSession class provides an AMI session with methods to create, announce, and exchange data, events, and errors.

AmiMethod Class An AMI application consists of a set of AMI methods that can be invoked by an AMI manager. The AmiMethod class encapsulates the definition and processing of these AMI methods. The methods can be synchronous or asynchronous methods. The method objects are created and added to your AmiSession objects. The AmiSession announces AmiMethod objects by sending their descriptions to an AMI manager. The methods can then be monitored and invoked by the AMI manager.

AmiSyncMethod Class

The AmiSyncMethod class derives from AmiMethod and implements synchronous AMI methods. The methods allow your application to return data to an AMI manager when it polls for data by invoking a synchronous call to your methods.

AmiAsyncMethod Class

The AmiAsyncMethod class derives from AmiMethod and implements asynchronous AMI methods that allow your application to return data to an AMI manager the instant it becomes available. In a typical scenario, when an AMI manager requires data, it polls for data by making a synchronous call to your methods. The AmiAsyncMethod class allows data to be returned asynchronously, as well.

TIBCO Hawk AMI C++ Reference 4 | Chapter 1 Introduction

If the source of your method's data is truly event-driven, the AmiAsyncMethod class allows you to send the data as events occur. This eliminates polling and allows the manager to also be event driven with respect to this method's data. The manager must tell the AMI application when it has an interest in receiving data from one of your asynchronous methods and when it is no longer interested. The manager can have several subscriptions. Each subscription is represented by an unique context. The application receives this unique context along with the input parameters for each subscription. The tracking of each context and its associated input parameters is done by the AmiSession. The application is no longer responsible for tracking the context.

AmiParameter, AmiParameterIn and AmiParameterOut Classes

An AmiMethod object receives input parameters and returns output parameters during an invocation. The AmiParameter class encapsulates a single input or output parameter. The AmiParameter class provides methods to create and set or get the parameter's value. A method can also return multiple rows of data (tabular data) by specifying multiple instances of its output parameters during a method invocation. A method that returns tabular data must define one or more indexes to uniquely index each row. An index is specified by the name(s) of the output parameters whose values form the index.

The AmiParameterIn class is used for parameters that arrive from the TIBCO Hawk agent. The AmiParameterOut class is used to handle the returned results.

AmiParameterList, AmiParameterListIn and AmiParamterListOut Classes

The AmiParameterList classes are used to group AmiParameter objects to define an AmiMethod's complete set of input parameters, output parameters, or both. The AmiParameterListIn class lists the complete set of input parameters for an AmiMethod. The AmiParameterListOut class lists the complete set of output parameters for an AmiMethod.

AmiStatus Class

The AmiStatus class is used to encapsulate error conditions that support operations on ami_Error.

AmiSubscription Class

The AmiSubscription class encapsulates an asynchronous method subscription.

TIBCO Hawk AMI C++ Reference TIBCO Hawk AMI C++ API | 5

AmiList and AmiLink Classes These classes are internal and used by AMI object classes. You need not instantiate the classes to use the C++ API. These classes are not documented.

Error Logging All AMI C ++API functions can detect and return AMI errors. The AMI error is an object that identifies the specific error and contains handle-based functions that create, destroy, and file stamp AMI errors. The file stamp records a file name and line number in the AMI error to indicate the error source location. Functions are also provided to get the error code, error description, thread ID, file name, and line number associated with the specific AMI error. Any AMI error returned to your AMI application by the AMI C++ API must be destroyed or it will cause a memory leak. The AMI C API destroys any AMI error passed to an AMI C++ API function or returned from an AMI C++ API callback function.

C++ API Tracing The AMI C++ API can be dynamically configured to produce various levels of tracing information for diagnostic purposes. The various trace levels can be individually enabled and disabled. Initial settings are specified when an AMI session is created and can then be dynamically modified using the AMI C++ API trace functions. A tracing callback function can be defined for an AMI session. This function will be called for each trace message produced by the AMI C++ API that meets the current tracing level. The tracing callback is optional and, if omitted, will disable all tracing.

Threading Model The AMI C ++API is multi-thread safe and uses multiple threads internally, however, it does not impose a threading model on your AMI application. You are free to use the AMI C ++API in a single or multi-threaded application. The AMI C++ API uses multiple threads internally to optimize performance and to guarantee timely processing of AMI protocol related functions. The AMI C++ API will never call your application code on a thread that was not explicitly created by your application (i.e. will never call your code on an internal thread).

TIBCO Hawk AMI C++ Reference 6 | Chapter 1 Introduction

AMI C++ API Sample Programs

The TIBCO Hawk software distribution includes sample AMI C++ API programs that will help you to better understand how to use the API. These samples can be found in the directory /samples/ami_api/cpp. Refer to the TIBCO Hawk Programmer’s Guide for instructions on building and executing these sample applications.

TIBCO Hawk AMI C++ Reference | 7

Chapter 2 C++ API Architecture

This chapter discusses the C++ API architecture.

Topics

• Synchronous and Asynchronous Methods, page 8 • AMI Internal Processes, page 11

TIBCO Hawk AMI C++ Reference 8 | Chapter 2 C++ API Architecture

Synchronous and Asynchronous Methods

The AMI C++ API supports the use of both synchronous and asynchronous methods. A synchronous AMI method returns data only when invoked by an AMI manager. An asynchronous AMI method can return data whenever data becomes available.

Synchronous Methods Whenever an AMI manager invokes a synchronous AMI method, the AMI C++ API will call an invocation callback function. You define the invocation callback functions for the synchronous AMI methods. The AMI C++ API provides the callback function with the values of any input parameters and a mechanism for returning either output parameter values or an error. The invocation callback can return data, return no data, or return an error condition.

Asynchronous Methods For asynchronous AMI methods, an AMI manager informs the AMI method when it should start or stop sending data. The asynchronous AMI method can define callback functions that the AMI C++ API calls whenever an AMI manager has requested the AMI method to start or stop sending data. The AMI C++ API provides the start callback function with a unique context (a subscription object) which identifies the start request, the values of any input parameters, and a mechanism for returning an error. The start callback routine can attach user data to the subscription object. If the start callback function does not return an error then the subscription is in effect and the asynchronous AMI method is free to return data at any time. Using the subscription object, the asynchronous AMI method can return data or error notifications asynchronously to the AMI manager. If the start callback function returns an error the AMI manager cancels the subscription. The AMI C++ API provides the stop callback function with the subscription object and a mechanism for returning an error. The stop callback function can perform any necessary application cleanup. When the stop callback returns the AMI manager stops (cancels) the subscription. An asynchronous AMI method is typically used to represent an asynchronous data source. The asynchronous AMI method can return data whenever it becomes available retaining the true event-driven nature of the data. This allows the AMI manager to respond in real-time and eliminates the need for polling as in the case of synchronous methods.

TIBCO Hawk AMI C++ Reference Synchronous and Asynchronous Methods | 9

There are two techniques that you can use to implement asynchronous methods. One technique is calling AmiAsyncMethod::sendData() for a subscription whenever new data becomes available. The AMI method, AMI method input parameters and any attached user data can always be obtained from the subscription object and output parameters can be constructed using the AMI parameter functions discussed below. Using the start and stop callback functions you must keep track of subscriptions. There can be multiple simultaneous subscriptions to a single asynchronous AMI method, potentially, from multiple AMI managers. Subscription handles are guaranteed to be unique among active subscriptions within the same AMI session and can, therefore, be used as an index for tracking purposes. This technique is often used when a separate thread is created to service each subscription. The other technique is calling AmiAsyncMethod::onData() for a method whenever new data becomes available. This function will call the invocation callback function of the associated method once for each active subscription to that method. The invocation callback function is passed the subscription object allowing the callback to get any attached used data necessary to process the new data. This technique allows the AMI C++ API to do all the work of tracking subscriptions requiring your application to simply provide the invocation callback. The invocation callback can return data, return no data, or return an error condition. If data is returned, it is sent asynchronously to the AMI manager. If no data is returned then no action takes place. This allows the invocation callback function to decide whether the new data should be returned for the subscription. If an error is returned, then it is sent asynchronously to the AMI manager. Depending on your specific method, this technique may also eliminate the need to supply a start and stop callback. If the subscription object passed to the invocation callback function is null (zero), then the method is being called synchronously. You may return data or an error depending if synchronous invocation is supported by your asynchronous method.

Auto-Invoke Methods The AMI C++ API provides a mechanism for creating auto-invoke asynchronous methods. During the start asynchronous method callback, the application can set an auto-invoke callback interval for the subscription. If an auto-invoke callback interval is set, the AMI C++ API will call the invocation callback function repeatedly for the method at the specified interval until the subscription is stopped. This can be used to turn a synchronous method into a pseudo-asynchronous method, eliminating the need for the AMI manager to repeatedly invoke the synchronous method. Typically, a method argument is defined to allow the user to specify the interval.

TIBCO Hawk AMI C++ Reference 10 | Chapter 2 C++ API Architecture

This functionality is critical for synchronous methods that require some setup such as priming counters used to calculate averages, deltas, or percents. Synchronous methods are required to return data on each invocation, making it impossible to return correct data for return values requiring two or more samples on the first invocation. The auto-invoke asynchronous method can return data whenever it is ready. It also has a start and stop callback to perform setup and clean-up operations, respectively. Since the invocation callback function has the option of returning no data, it can skip invocations. This is useful when many data samples are required before accurate data can be returned, or when perhaps it is waiting for some required service to initialize.

TIBCO Hawk AMI C++ Reference AMI Internal Processes | 11

AMI Internal Processes

To establish an AMI protocol dialog with a TIBCO Hawk agent, the AMI C++ API uses: •TIBCO Rendezvous transport • TIBCO Rendezvous event listener • TIBCO Rendezvous queue Your application can provide the TIBCO Rendezvous transport, or it can supply the TIBCO Rendezvous daemon parameters and the AMI C++ API will automatically create the TIBCO Rendezvous transport. The AMI C++ API creates an internal thread that dispatches all AMI protocol TIBCO Rendezvous messages. This thread performs the AMI protocol functions that do not require the execution of your application code. This includes processing AMI protocol heartbeat, discovery, and describe methods requests—as well as various housekeeping tasks like asynchronous method subscription refresh and expiration handling. All this processing is done automatically and need not concern your application. By performing these tasks on a dedicated thread the handling of the AMI protocol is not affected by (is shielded from) your application code. When AMI protocol requests are received that require execution of your application code, these requests are sent to the TIBCO Rendezvous intra-process transport. The AMI C++ API automatically creates a TIBCO Rendezvous event listener that listens on the TIBCO Rendezvous intra-process transport and queues these AMI protocol messages to a TIBCO Rendezvous queue. Your application can provide this TIBCO Rendezvous queue or let the AMI C++ API automatically create this TIBCO Rendezvous queue. Your application thread or threads dispatch these AMI protocol messages from this TIBCO Rendezvous queue and are, therefore, the only threads that will execute your application code. The AMI protocol requests that require execution of your code are method invocation and start/stop asynchronous method subscription requests. If your application is single-threaded, the single thread will dispatch AMI protocol messages from the TIBCO Rendezvous queue and execute any AMI related code in your application. If your application is multi-threaded and these threads are used to dispatch AMI protocol messages from the TIBCO Rendezvous queue then any one of these threads may execute the AMI related code in your application. Your application has complete control of the thread model used.

TIBCO Hawk AMI C++ Reference 12 | Chapter 2 C++ API Architecture

Optional Components Both the TIBCO Rendezvous transport and the TIBCO Rendezvous queue are optional when running Hawk. You can set your application to provide a valid TIBCO Rendezvous transport. The TIBCO Rendezvous transport must be created with TIBCO Rendezvous daemon parameters compatible with those used by the TIBCO Hawk agent. Alternatively, your application can provide the TIBCO Rendezvous daemon parameters and let the AMI C++ API create the TIBCO Rendezvous transport. You can also set your application to provide any valid TIBCO Rendezvous queue. If your application does provide a TIBCO Rendezvous queue, you must ensure that the application properly dispatches the TIBCO Rendezvous queue. If your application provides the TIBCO Rendezvous queue, then the ami_SessionAnnounce() function does not block. If your application does not provide a TIBCO Rendezvous queue, then the AMI C++ API will automatically create and dispatch the TIBCO Rendezvous queue. The AMI C++ API perform the dispatching as part of its processing of the ami_SessionAnnounce() function. This turns the ami_SessionAnnounce() function into a blocking function that will not return until the ami_SessionStop() function is called.

AMI Instrumentation without TIBCO Rendezvous By allowing both the TIBCO Rendezvous transport and the TIBCO Rendezvous queue to be automatically created by the AMI C++ API, AMI applications can be created without the TIBCO Rendezvous development environment. This type of AMI application must use the dynamic-link AMI C++ API library because the static AMI C++ API libraries require the static TIBCO Rendezvous libraries. When automatically created by the AMI C++ API, the TIBCO Rendezvous transport provides the same TIBCO Rendezvous licensing as the TIBCO Hawk product while limiting your use of TIBCO Rendezvous strictly to AMI instrumentation. Most TIBCO Rendezvous applications will provide the TIBCO Rendezvous transport and the TIBCO Rendezvous queue in order to integrate the AMI instrumentation into the application. The primary reason the AMI C++ API makes these components optional is to allow applications to be AMI instrumented without requiring a separate TIBCO Rendezvous license.

TIBCO Hawk AMI C++ Reference AMI Internal Processes | 13

Figure 1 AMI C++ API Internal Architecture

TIBCO Hawk agent

TIBCO Rendezvous

AMI C API Application

TIBCO Rendezvous Trransport for AMI Protocol Messages (optional)

Application thread or threads TIBCO Rendezvous Event Listener AMI Protocol Message4s

TIBCO Redndezvous TIBCO Rendezvous Queue Queue for for AMI Application AMI Prorocol Messages

Messages

E L

Internal thread Send TIBCO Rendezvous dispatchs Message Intra-Process Transport messages

TIBCO Hawk AMI C++ Reference 14 | Chapter 2 C++ API Architecture

TIBCO Hawk AMI C++ Reference | 15

Chapter 3 C++ Programmer’s Checklist

Use the following procedures when implementing C++ API applications.

Topics

• General Steps for Programmers, page 16 • Library Files, page 17

TIBCO Hawk AMI C++ Reference 16 | Chapter 3 C++ Programmer’s Checklist

General Steps for Programmers

Make sure you perform the procedures listed. •Code Include the appropriate TIBCO Hawk header files. TIBCO Hawk C++ application programs must include these header files: — tibrvcpp.h — amicpp.h •Compile. Compile applications with an ANSI-compliant C++ compiler. •Link Link with the appropriate C++ library file (see Library Files, page 17). •Run Verify that the TIBCO Rendezvous daemon runs on each application host computer and that the TIBCO Hawk agent can communicate with it. The path must contain a version appropriate to the application’s host.

TIBCO Hawk AMI C++ Reference Library Files | 17

Library Files

TIBCO Hawk C++ programs must link the appropriate library files. Choose the appropriate files based on operating system platform. The table below lists the appropriate library files for the various TIBCO Hawk platforms.

Table 2 Libraries to be Linked OS platform Compilation Style Libraries to Link Microsoft /MD compiled console libtibhawkamicppmd.lib Windows application to be run with DLL tibhawkami.lib libtibrvcppmd.lib tibrv.lib

/MD compiled console libtibhawkamicppmd.lib application with static MD library libtibhawkamimd.lib libtibrvcppmd.lib libtibrvmd.lib wsock32.lib advapi32.lib

/MT compiled console application libtibhawkamicppmt.lib libtibhawkamimt.lib libtibrvcpp.lib libtibrv.lib wsock32.lib advapi32.lib

Solaris Static libtibhawkamicpp.a libtibrvcpp.a

Shared libraries libtibhawkamicpp.so libtibrvcpp.so

HP-UX Static libtibhawkamicpp.a libtibrvcpp.a

Shared libraries For PA-RISC: libtibhawkamicpp.sl libtibrvcpp.sl For IA64(Itanium): libtibhawkamicpp.so libtibrvcpp.so

TIBCO Hawk AMI C++ Reference 18 | Chapter 3 C++ Programmer’s Checklist

Table 2 Libraries to be Linked (Cont’d) OS platform Compilation Style Libraries to Link AIX Static tibhawkamicpp.a libtibrvcpp.a

Shared libraries libtibhawkami_shr.a libtibrv.so

Linux Static libtibhawkamicpp.a libtibrvcpp.a

Shared libraries libtibhawkamicpp.so libtibrvcpp.so

Solaris 8 and 9, AIX, and HPUX also include AMI C libraries for 64 bit platforms. These libraries have the suffix 64 appended to their names (for example, libtibhawkamicpp64.a and libtibhawkamicpp64.so).

TIBCO Hawk AMI C++ Reference | 19

Chapter 4 AMI Session Class

Each instance of the class AmiSession in the AMI represents an interface to the TIBCO Hawk agent and functions as a microagent. AmiSession handles all interactions with TIBCO Hawk agent and method invocations.

Topics

• AmiSession, page 20

TIBCO Hawk AMI C++ Reference 20 | Chapter 4 AMI Session Class

AmiSession Class

Declaration class AmiSession;

Purpose An instance of AmiSession represents an interface to the TIBCO Hawk agent and is treated as a microagent.

Remarks This class can be used as a base class for an application-specific AMI class. The user can inherit from this class and populate the AMI session with methods in the constructor.

The AmiSession class will establish point-to-point communication with a TIBCO Hawk agent.

Member Member Description Page Summary AmiSession() Constructor. 20

AmiSession::open() Initializes the AMI API 24

AmiSession::close() Terminates the AMI API 25

AmiSession::versionName() Returns current version name 26

AmiSession::version() Returns current version 27

AmiSession::versionDate() Returns current version date 28

AmiSession::banner() Returns product banner 29

AmiSession::versionMajor() Returns major version 30

AmiSession::versionMinor() returns minor version 31

AmiSession::getTraceLevels() Returns the current AMI 32 session trace level settings

AmiSession::setTraceLevels() Resets AMI session trace level 33 settings

AmiSession::enableTraceLevels() Enables levels of race output. 34

AmiSession::disableTraceLevels() Disables levels of trace output 35

AmiSession::announce() Announces existence of the 36 microagent.

TIBCO Hawk AMI C++ Reference AmiSession | 21

Member (Cont’d) Description (Cont’d) Page AmiSession::get... Accessors() Returns AmiSession 37 accessors.

AmiSession::sendUnsolicitedMsg() Sends unsolicited message to 38 the monitoring agent.

AmiSession::stop() Stops the AMI session 39

TIBCO Hawk AMI C++ Reference 22 | Chapter 4 AMI Session Class

AmiSession() Constructor

Declaration AmiSession(ami_TraceCode traceLevel, const char * service, const char * network, const char * daemon, unsigned int rvTransport, unsigned int rvQueue, const char * name, const char * display, const char * help, ami_TraceHandler traceHandler, const void * userData );

Purpose This constructor creates an instance of AmiSession. Each instance corresponds to an independent microagent.

Parameters Parameter Description traceLevel AMI trace levels for this AMI session. Levels can be: AMI_ALL. Turns on all trace code levels. AMI_AMI. Indicates AMI level trace message. AMI_DEBUG. Logging statement are written into the trace file if, and only if, the trace level set in the current ami_Session object has the AMI_DEBUG bit mask turned on. AMI_ERROR. Logging statement are written into the trace file, regardless of whether the AMI_ERROR bit mask is turned on in the current ami_Session object. AMI_INFO. Logging statements are written into the trace file if, and only if, the trace level set in the current ami_Session object has the AMI_INFO bit mask turned on. AMI_STAMP. Adds source file name and line number to all messages. AMI_WARNING. Logging statement are written into the trace file if, and only if, the trace level set in the current ami_Session object has the AMI_WARNING bit mask turned on.

service TIBCO Rendezvous service, network and daemon network parameters. For information about setting these parameters, see your TIBCO Rendezvous documentation. daemon

rvTransport C handle for TIBCO Rendezvous tibrvTransport.

rvQueue C handle for TIBCO Rendezvous tibrvQueue handle.

TIBCO Hawk AMI C++ Reference AmiSession() | 23

Parameter (Cont’d) Description (Cont’d) name Internal name of the microagent. display User friendly name for the microagent. This name appears in the TIBCO Hawk Display. help Help text for describing the functions of this microagent. traceHandler Error callback function used for this AMI session. userData User data for this AMI session.

TIBCO Hawk AMI C++ Reference 24 | Chapter 4 AMI Session Class

AmiSession::open() Method

Declaration static AmiStatus open();

Purpose Initializes the AMI API.

TIBCO Hawk AMI C++ Reference AmiSession::close() | 25

AmiSession::close() Method

Declaration static AmiStatus close();

Purpose Terminates the AMI C++ API and releases associated resources.

TIBCO Hawk AMI C++ Reference 26 | Chapter 4 AMI Session Class

AmiSession::versionName() Method

Declaration static const char * versionName();

Purpose Returns the release name of the application.

TIBCO Hawk AMI C++ Reference AmiSession::version() | 27

AmiSession::version() Method

Declaration static const char * version();

Purpose Returns the release version of the application.

TIBCO Hawk AMI C++ Reference 28 | Chapter 4 AMI Session Class

AmiSession::versionDate() Method

Declaration static const char * versionDate();

Purpose Returns the version date of the application.

TIBCO Hawk AMI C++ Reference AmiSession::banner() | 29

AmiSession::banner() Method

Declaration static const char * banner();

Purpose Returns the application banner.

TIBCO Hawk AMI C++ Reference 30 | Chapter 4 AMI Session Class

AmiSession::versionMajor() Method

Declaration static int versionMajor();

Purpose Returns the major version.

TIBCO Hawk AMI C++ Reference AmiSession::versionMinor() | 31

AmiSession::versionMinor() Method

Declaration static int versionMinor();

Purpose Returns the minor version.

TIBCO Hawk AMI C++ Reference 32 | Chapter 4 AMI Session Class

AmiSession::getTraceLevels() Method

Declaration AmiStatus getTraceLevels(ami_TraceCode * inpTraceLevel) const;

Purpose Returns the current AMI session trace level settings.

TIBCO Hawk AMI C++ Reference AmiSession::setTraceLevels() | 33

AmiSession::setTraceLevels() Method

Declaration AmiStatus setTraceLevels(amiTraceCode inTraceLevel);

Purpose Resets all AMI Session trace level settings to the specified settings.

TIBCO Hawk AMI C++ Reference 34 | Chapter 4 AMI Session Class

AmiSession::enableTraceLevels() Method

Declaration AmiStatus enableTraceLevels(amiTraceCode inTraceLevel);

Purpose Enables the specified level(s) of trace output. All other trace levels settings are unaffected.

TIBCO Hawk AMI C++ Reference AmiSession::disableTraceLevels() | 35

AmiSession::disableTraceLevels() Method

Declaration AmiStatus disableTraceLevels(amiTraceCode inTraceLevel);

Purpose Disables the specified level(s) of trace output. All other trace level settings are unaffected.

TIBCO Hawk AMI C++ Reference 36 | Chapter 4 AMI Session Class

AmiSession::announce() Method

Declaration AmiStatus announce(void) const;

Purpose Announces the existence of the microagent to the TIBCO Hawk agent.

TIBCO Hawk AMI C++ Reference AmiSession::get... Accessors | 37

AmiSession::get... Accessors Method

Declarations AmiStatus getName(const char ** name) const;

AmiStatus getDisplayName(const char ** displayName) const;

AmiStatus getHelp(const char ** help) const;

AmiStatus getUserData(void ** userData) const;

AmiStatus& getStatus();

Purpose Accessors for AmiSession objects.

Methods The following table lists the get accessors for AmiSession objects.

Method Description getName() Gets the name of this microagent. This name can be different from the display name, as this is the actual name by which the microagent is identified in the TIBCO Hawk system.

getDisplayName() Gets the display name of the microagent. This is the name as it appears and can be different from the actual name of the microagent. The display name is the user-friendly name by which this interface is to be known, as opposed to the internal interface identifier. The TIBCO Hawk Display shows the display name in the list of discovered microagents/AMI applications.

getHelp() Gets the help text of this microagent. The returned help text is the optional help text that is displayed to the user.

getUserData() Returns the user data in the specified AMI session.

getStatus() Used to check that the session has been created correctly.

TIBCO Hawk AMI C++ Reference 38 | Chapter 4 AMI Session Class

AmiSession::sendUnsolicitedMsg() Method

Declaration AmiStatus sendUnsolicitedMsg( ami_AlertType type, const char * text, int id) const;

Purpose Sends an unsolicited message to the monitoring agent.

Remarks An unsolicited message is an application information, warning, or error message that is sent from the managed application directly to the manager (TIBCO Hawk agent).

Parameters Parameter Description type Alert message type (information, warning, or error).

text A text message describing the alert condition.

id An arbitrary identification number defined by the application.

TIBCO Hawk AMI C++ Reference AmiSession::stop() | 39

AmiSession::stop() Method

Declaration AmiStatus stop(void) const;

Purpose Stops the AMI session.

TIBCO Hawk AMI C++ Reference 40 | Chapter 4 AMI Session Class

TIBCO Hawk AMI C++ Reference | 41

Chapter 5 AMI Methods Classes

The methods define the application interface to the TIBCO Hawk agent. When AmiSession announces itself to the TIBCO Hawk agent, the agent queries for a description of the available methods. AmiSession creates a description of available AMI method objects based on implementations of AmiMethod.

AmiMethod class provides a foundation for classes that describe synchronous, and asynchronous AMI methods.

The AmiAsyncMethod class extends the AmiMethod class to send data whenever it becomes available. This allows the AMI-instrumented application to actively publish data whenever data becomes available.

The AmiSyncMethod class extends the AmiMethod class to return synchronous data. With AmiSyncMethod class, the method returns data only upon request.

The AmiSubcription class encapsulates an asynchronous method subscription.

Topics

• AmiMethod, page 42 • AmiAsyncMethod, page 46 • AmiSyncMethod, page 53 • AmiSubscription, page 55

TIBCO Hawk AMI C++ Reference 42 | Chapter 5 AMI Methods Classes

AmiMethod Class

Declaration class AmiMethod

Purpose This class implements methods.

Remarks Classes derived from AmiMethod can be registered with AmiSession. The AmiSyncMethod class extends the AmiMethod class to implement synchronous methods. The AmiAsyncMethod class extends the AmiMethod class to implement asynchronous methods.

Member Member Description Page Summary AmiMethod::setIndexName() Sets the index name for this 43 AmiMethod.

AmiMethod::get...() Retrieves information from this 44 Accessors AmiMethod instance. getStatus() getName() getHelp() getSession()

AmiMethod::onInvoke() Callback on arrival of a method 45 invocation method from the monitoring agent. See AmiParameter, page 62.

TIBCO Hawk AMI C++ Reference AmiMethod::setIndexName() | 43

AmiMethod::setIndexName() Method

Declaration AmiStatus setIndexName(const char * index);

Purpose Sets the index field when this AmiMethod is to return tabular data. The method can be invoked multiple times to establish the composite index.

Parameters Parameter Description index The index name to be set.

TIBCO Hawk AMI C++ Reference 44 | Chapter 5 AMI Methods Classes

AmiMethod::get...() Accessors Accessors

Declaration AmiStatus getHelp(const char ** help) const;

AmiStatus getName(const char ** name) const;

AmiSession * getSession(void) const;

AmiStatus& getStatus();

Purpose Accessors for retrieving information from an AmiMethod instance.

Method Description getHelp() Gets the help text for the method.

getName() Gets the name of the method.

getSession() Gets the AmiSession object this method belongs to.

getStatus() Used to check if the method object has been created correctly.