Copyright © Cloud Software Group, Inc. All Rights Reserved

AMI API Sample Programs

The TIBCO Hawk software distribution includes sample AMI Java, C++, and C API programs that will help you to better understand how to use the API. These samples can be found in the following directories:

•	For Java: HAWK_HOME/examples/ami_api/java

•	For C++: HAWK_HOME/examples/ami_api/cpp

•	For C: HAWK_HOME/examples/ami_api/c.

The Sample AMI API Applications

The TIBCO Hawk AMI API sample applications can be found in the directory:

HAWK_HOME/examples/ami_api directory

This directory contains three sub-directories c, cpp, and java that contain sample applications for the C, C++, and Java TIBCO Hawk AMI APIs, respectively. These applications are discussed in the following sections.

TIBCO Hawk AMI C API Sample Applications

To pass the parameters for executing AMI program, use the properties file hawk_example.props available at HAWK_HOME/examples/hawk_example.props. This properties file defines the transport to be used (TIBCO Rendezvous or TIBCO DataGrid) and the parameters required to establish the transport session.

The TIBCO Hawk AMI C API sample directory contains five sample applications. They have the following filenames and AMI application names, with the numbers 1-5 substituted for the x:

TIBCO Hawk AMI C API sample x:

−	Filename: ami_samplex.c

−	Display name: ami_samplex

−	Internal name: COM.TIBCO.hawk.ami_api.c.ami_samplex

The five sample applications can be built by following the instructions in the Makefile.sample file, which is also located in the sample directory.

•	ami_sample1.c

This sample shows how to AMI instrument a user application. The AMI API does all the TIBCO Rendezvous and TIBCO DataGrid work under the covers.

This method limits the number of dispatching threads to one thread. This is the only thread which will call the user applications AMI API callback functions. As a result, the users application can be single threaded. If the users application is to be multi-threaded then the code in this sample would run on a dedicated thread. The users application would be responsible for thread safety regarding any of its own data structures.

•	ami_sample2.c

This sample shows how to AMI instrument a Rendezvous application. The users application creates a Rendezvous transport and queue and is responsible for dispatching that queue.

The users application is free to be single or multiple threaded. The users application is responsible for synchronizing access to user application data in the multi-threaded case.

•	ami_sample3.c

This sample is identical to ami_sample1.c except that it demonstrates how to create methods that return tabular data.

•	ami_sample4.c

This sample shows how to create an asynchronous AMI method for a synchronous data source. This technique is used when synchronous data needs to be polled at a certain rate, possibly calculations performed on the data across samples, and the results returned at that rate or another rate. This technique makes use of the auto-invoke feature of the AMI C API.

•	ami_sample5.c

This sample shows how to create asynchronous AMI method for a asynchronous data source. The data source sends data using ami_SessionOnData API to send data asynchronously to every subscriber.

Executing Sample Programs

•	To execute, for example, ami_samplex program, use the following command line:

ami_samplex hawk_example.props

Using Sample Applications on IBM i5/OS

The names of the TIBCO Hawk AMI C API sample programs have been truncated to fit the IBM i5/OS name limit. On IBM i5/OS, the sample programs have the following names, with the numbers 1-4 substituted for the x:

ami_samplex.c

A sample CL program is provided to compile the sample programs. This sample CL program is included with the HAWKAMI library in QCSRC. The sample CL program assumes the source for the sample programs is present in TIBHAWK/QCSRC.

To compile the sample programs, execute the following command:

CALL TIBHAWK/AMICMP AMI_SAMPL1

You can execute the TIBCO HAWK AMI C sample programs as a job or from qsh.

To submit a job, execute the following command:

SBMJOB CMD(CALL PGM(TIBHAWK/AMI_SAMPL1)) JOBQ(QUSRNOMAX) MSGQ(*USRPRF) ALWMLTTHD(*YES)

TIBCO Hawk AMI C++ API Sample Application

The TIBCO Hawk AMI C++ API sample directory contains one sample application, which has the following filename and AMI application names:

•	AmiSample1.cpp

Filename: AmiSample1.cpp

Display name: AmiSample1

Internal name: COM.TIBCO.hawk.ami_api.cpp.AmiSample1

This sample creates an AMI session to support methods that demonstrate how to:

−	pass data to an instrumented application,

−	receive data from an instrumented application,

−	return tabular data,

−	return data asynchronously, and

−	shutdown an application.

The sample application can be built by following the instructions in the Makefile.sample file, also located in the sample directory.

Executing the Sample Program

•	To execute AmiSample1 program, use the following command line:

AmiSample1 hawk_example.props

TIBCO Hawk AMI Java API Sample Application

The TIBCO Hawk AMI Java API sample directory contains the following files:

•	AmiSample.Java:a sample application designed to illustrate how to instrument a Java application using the TIBCO Hawk AMI API for Java.

•	Spot.java: a simple GUI application using TIBCO Hawk AMI API for Java.

•	SpotAmi.java: AMI Java API instrumentation for the Spot application.

This sample demonstrates how an existing application, Spot.java, can be instrumented with the AMI Java API.

The AMI sample spot.java has the following AMI application names:

•	Display name: Spot

•	Internal name: COM.TIBCO.hawk.ami_api.java.Spot

Executing the Sample Program

In order to compile and execute this sample, the following must be in your Java CLASSPATH:

•	ami.jar and util.jar from the TIBCO Hawk java directory

•	tibrvj.jar from the TIBCO Rendezvous java directory

It is recommended that you use Java 1.7 or higher. For TIBCO DataGrid transport, • On Windows, path to as-common.dll is required in the PATH environment variable. • On Unix/Linux, modify LD_LIBRARY_PATH to include ascommon.so as follows: − LD_LIBRARY_PATH=$TIBCO_HOME/as/2.0/lib:$LD_LIBRARY_PATH − export LD_LIBRARY_PATH

The Spot application is executed with the following command:

java Spot -rvd_session <service> <network> <daemon> hawk_example.props

Using the Sample Programs

Each sample program represents a separate application. Compile and link them using your C/C++ development environment.

Do not use any class libraries (such as MFC) in your build; make the application a console application only.

 

Copyright © Cloud Software Group, Inc. All Rights Reserved