3. Using PureAPI with Sun JVM.
4. Using PureAPI with MS Dot Net
PureAPI is an API exposed by Rational PQC runtime system and gives the monitored program ability to control the profiling process. You should use this API if you want the monitored code to clear data recorded before certain point, take a snapshot in the predefined line of code or pause/resume data recording. Although the functionality is pretty similar to one implemented for the instrumented binary code, it is used in a bit different way in the event monitored environment (such as Java or MS Dot Net). This document describes how to use this API in the currently supported environments.
PureAPI functionality is the same for all programming environments mentioned above.
Following is the list of methods supported by appropriate PureAPI implementation (see pp 3,4)
int IsRunning(void)
Check if runtime is running.
Input: -
Output: -
Returns:
1
if underlying runtime is active
0 otherwise
int DisableRecordingData(void)
Disables data recording after the call.
Input: -
Output: -
Returns:
0
if already disabled
1 if was not disabled
int StopRecordingData(void)
Use this call to stop data recording until subsequent
StartRecordingData() call
Input: -
Output: -
Returns:
int ClearData(void)
Clears dataset recorded before this call.
May be useful when you need to eliminate extra noise created by unwanted code (System initialization etc.)
Input: -
Output: -
Returns:
int IsRecordingData(void)
Check if runtime is recording data
Input: -
Output: -
Returns:
1
if runtime is currently recording data
0 if not
Input: s - String with the
annotation text
Output: -
Returns:
int AddAnnotation(char* s)
Adds the input string to the list of annotations recorded in
the
application log. (Run Summary/Details)
Input: s -
String with the annotation text
Output: -
Returns:
int SaveData(void)
Create a snapshot
Input: -
Output: -
Returns:
1 if data is successfully saved.
PureAPI works with Sun JVM version 1.2.2 and above. You can import the PureAPI class from the Rational package that is normally installed in the (JRE folder)\lib\ext\Rational.jar. Note that content of this folder is exposed by JRE by default, so you don’t have to add it to your CLASSPATH variable to use it. To import the PureAPI class use the following code:
import Rational\PureAPI
All methods in the PureAPI class are static so you don’t need an instance of the PureAPI class to invoke them.
App. 1 contains the example of using PureAPI in a Java program
Using PureAPI.net is straight forward. You should add a reference to PureAPI.dll to your project and specify namespace ‘Rational’ in your source. PureAPI functionality is implemented in this namespace in the managed class PureAPI. Note that all methods in this class are static.
App 2. contains the example of using PureAPI from a C# application.
//==============================================================================
// TestPureAPI.java
//------------------------------------------------------------------------------
// PureAPI functionality test
//
// PureAPI interface is implemented as part of the Rational
package and
// lets you control the performance/coverage data collection
process.
// This test verifyes the following functions of PureAPI:
// * qprofIsRunning() - Check if Quantify or Covreage
runtime is running
// * qprofClearData() - Discard all data recorded before
this call
// * qprofStopRecordingData() - Stop recording untill
qprofStartRecordingData
// * qprofStartRecordingData() - resume data recording
// * qprofSaveData() - Take a snapshot
// * qprofAddAnnotation() - Add an annotation to the Run
Summary/Details
//
// Usage:
// The program doesn't take any command line arguments.
// When started without event monitoring, will give this
message:
// "PureAPI is
not running. The test will terminate"
// When started with the event monitoring enabled, should
output this sequence:
// "PureAPI
is running"
// "beforeClearData"
// "afterStopRecordingData"
// "beforeSaveData"
// "afterSaveData"
// "Done"
//
// The single run of this program should result in one
dataset and one snapshot.
// For the detailed PureAPI information see the online help
(keyword PureAPI).
//==============================================================================
import Rational.PureAPI;
class TestPureAPI
{
public
static void main(String args[])
{
if(0
== PureAPI.IsRunning())
{
msg("PureAPI
is not running. The test will terminate");
return;
}
msg("PureAPI
is running");
beforeClearData();
//
Everything above this line will be cleared.
//
Counters should be zeroed.
PureAPI.ClearData();
beforeStopRecordingData();
PureAPI.StopRecordingData();
//
The next line will not be recorded
afterStopRecordingData();
//
After this line everything is back to normal
PureAPI.StartRecordingData();
afterStartRecordingData();
PureAPI.AddAnnotation("PureAPI.AddAnnotation
invoked from TestPureAPI");
beforeSaveData();
PureAPI.SaveData();
//
Everything after this line shouldn't appear in the snapshot
afterSaveData();
msg("Done");
}
//--------------------------------------------------------------------------
// Since
this method is called before PureAPI.qprofClearData()
// this
call will not appear in the call graph and all
// counters
on the annotated source will be zeroed.
private
static void beforeClearData()
{
msg("\tbeforeClearData");
}
//--------------------------------------------------------------------------
// This
method is invoked before PureAPI.qprofStopRecordingData()
// so it
should be measured as necessary
private
static void beforeStopRecordingData()
{
msg("\tbeforeStopRecordingData");
}
//--------------------------------------------------------------------------
// Since
this method is called after PureAPI.qprofStopRecordingData()
// this
call will not appear in the call graph and all
// counters
on the annotated source will be zeroed.
private
static void afterStopRecordingData()
{
msg("\tafterStopRecordingData");
}
//--------------------------------------------------------------------------
// This
method is invoked after PureAPI.qprofStopRecordingData()
// so it
should appear in the call graph as usual.
private
static void afterStartRecordingData()
{
msg("\tafterStartRecordingData");
}
//--------------------------------------------------------------------------
// This
method will appear in the main dataset and the snapshot
//
private
static void beforeSaveData()
{
msg("\tbefoeSaveData");
}
//--------------------------------------------------------------------------
// This
method will appear in the main dataset but not in the snapshot
private
static void afterSaveData()
{
msg("\tafterSaveData");
}
//--------------------------------------------------------------------------
// Write a
message to the screen
//
private
static void msg(String i_msg)
{
System.out.println(i_msg);
}
}
//= End of TestPureAPI.java ====================================================
//==============================================================================
// PureAPITest.cs
//
using System;
using Rational;
namespace PureAPITest
{
///
<summary>
//==========================================================================
// PureAPI
functionality test
//
// PureAPI
interface is implemented as part of the Rational package and
// lets you
control the performance/coverage data collection process.
// This
test verifyes the following functions of PureAPI:
// *
qprofIsRunning() - Check if Quantify or Covreage runtime is running
// *
qprofClearData() - Discard all data recorded before this call
// *
qprofStopRecordingData() - Stop recording untill qprofStartRecordingData
// *
qprofStartRecordingData() - resume data recording
// *
qprofSaveData() - Take a snapshot
// *
qprofAddAnnotation() - Add an annotation to the Run Summary/Details
//
// Usage:
// The
program doesn't take any command line arguments.
// When
started without event monitoring, will give this message:
// "PureAPI is not running. The test will
terminate"
// When
started with the event monitoring enabled, should output this sequence:
// "PureAPI is running"
// "beforeClearData"
// "afterStopRecordingData"
// "beforeSaveData"
// "afterSaveData"
// "Done"
//
// The
single run of this program should result in one dataset and one snapshot.
//
// For the
detailed PureAPI information see the online help (keyword PureAPI).
//==========================================================================
///
</summary>
class
PureAPITest
{
public
static void Main()
{
if(0
== PureAPI.IsRunning())
{
msg("PureAPI
is not running. The test will terminate");
return;
}
msg("PureAPI
is running");
beforeClearData();
//
Everything above this line will be cleared.
//
Counters should be zeroed.
PureAPI.ClearData();
beforeStopRecordingData();
PureAPI.StopRecordingData();
//
The next line will not be recorded
afterStopRecordingData();
//
After this line everything is back to normal
PureAPI.StartRecordingData();
afterStartRecordingData();
PureAPI.AddAnnotation("PureAPI.AddAnnotation
invoked from TestPureAPI");
beforeSaveData();
PureAPI.SaveData();
//
Everything after this line shouldn't appear in the snapshot
afterSaveData();
msg("Done");
}
//----------------------------------------------------------------------
//
Since this method is called before PureAPI.qprofClearData()
//
this call will not appear in the call graph and all
//
counters on the annotated source will be zeroed.
private
static void beforeClearData()
{
msg("\tbeforeClearData");
}
//----------------------------------------------------------------------
//
This method is invoked before PureAPI.qprofStopRecordingData()
//
so it should be measured as necessary
private
static void beforeStopRecordingData()
{
msg("\tbeforeStopRecordingData");
}
//----------------------------------------------------------------------
//
Since this method is called after PureAPI.qprofStopRecordingData()
//
this call will not appear in the call graph and all
//
counters on the annotated source will be zeroed.
private
static void afterStopRecordingData()
{
msg("\tafterStopRecordingData");
}
//----------------------------------------------------------------------
//
This method is invoked after PureAPI.qprofStopRecordingData()
//
so it should appear in the call graph as usual.
private
static void afterStartRecordingData()
{
msg("\tafterStartRecordingData");
}
//----------------------------------------------------------------------
//
This method will appear in the main dataset and the snapshot
//
private
static void beforeSaveData()
{
msg("\tbefoeSaveData");
}
//----------------------------------------------------------------------
//
This method will appear in the main dataset but not in the snapshot
private
static void afterSaveData()
{
msg("\tafterSaveData");
}
//----------------------------------------------------------------------
//
Write a message to the screen
//
private
static void msg(String i_msg)
{
System.Console.WriteLine(i_msg);
}
}
}
//= End of PureAPITest.cs ======================================================