PureAPI for Dot Net and Java.

PureAPI for Dot Net and Java. 1

1. Introduction: 1

2. PureAPI functionality. 1

3. Using PureAPI with Sun JVM. 2

4. Using PureAPI with MS Dot Net 2

Appendixes. 2

App 1. Java example. 2

App 2. C# example. 5

 

1. Introduction:

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.

 

2. PureAPI functionality

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.

 

 

3. Using PureAPI with Sun JVM.

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

 

4. Using PureAPI with MS Dot Net

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.

 

 

Appendixes

App 1. Java example

//==============================================================================

// 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 ====================================================

 

App 2. C# example

 

//==============================================================================

// 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 ======================================================