ARM API Function Calls

Overview

When the ARM API function calls are included in an application, the performance of that application can be monitored by the agents that implement the shared library. The advantage of this approach is that it allows the user to select a measurement agent that best meets their needs without requiring any change to the application.

The set of ARM function calls is summarized below, in the logical order in which they may expect to be used:

arm_init()

During the initialization of your application, call arm_init() which names your application and optionally the users, and initializes the ARM environment for your application. A unique identifier is returned that must be passed to arm_getid().

arm_getid()

Use arm_getid() to name each transaction class you use in your application. This is often done during the initialization of your application. A transaction class is a description of a unit of work, such as Check Account Balance. In each program, each transaction class may be executed once or many times. Call arm_getid() returns a unique identifier that must be passed to arm_start().

arm_start()

Each time a transaction class is executed, this is a transaction instance. Call arm_start() signals the start of execution of a transaction instance and returns a unique handle to be passed to arm_update() and arm_stop().

arm_update()

This is an optional function call that can be made any number of times after arm_start() and before arm_stop(). Call arm_update() gives information about the transaction instance, such as a heartbeat after a group of records has been processed.

arm_stop()

Call arm_stop() signals the end of the transaction instance.

arm_end()

At termination of the application, call arm_end() cleans up the ARM environment for your application. There should be no problem if this call is not made, but if it is not used then memory may be wasted because it is allocated by the agent even though it is no longer needed.

The workhorse functions are arm_start() and arm_stop(), which are called at the beginning and end of each executing transaction. There are two administrative calls used to define the application and transactions: arm_init() and arm_getid(). Call arm_update() is an optional call that can be used with long running transactions to provide an I'm alive heartbeat and a progress indicator. Call arm_end() is used when an application is shutting down, which allows an agent to release any storage used for monitoring this application.

Valid Call Sequences

The following gives an example in an imaginary language showing the API calls:

 

arm_init ("Application Name", "User Name")
    arm_getid ("Transaction A")
    arm_getid ("Transaction B")
    arm_getid ("Transaction C")

        loop until program ends
            arm_start (A)

                arm_start (B)
                do some work
                arm_stop (B, status)

                arm_start (C)
            loop until transaction ends
                do some work
                arm_update (C)
            end loop
                arm_stop (C, status)

        arm_stop (A,status)
    end loop
arm_end

ARM API Function Call Parameters

Definition of Data Type Terminology

Standard API Calls

int32

A signed 32-bit integer.

char*

A 32-bit or 64-bit pointer to a character string or data structure depending upon the operating system and/or the application mode of operation. Strings must be NULL terminated unless specified otherwise. Strings are expected to be displayed, put in reports, and so on, so appropriate characters should be chosen.

More Advanced Functions

int64

A signed 64-bit integer.

unsigned32

An unsigned 32-bit integer.

unsigned64

An unsigned 64-bit integer.

bit8

A byte containing 8 single-bit flags. In this document, when a bit8 is represented as eight flags using the notation abcdefgh, a is the most significant bit, and h is the least significant bit.

unsigned16

An unsigned 16-bit integer.

unsigned8

An unsigned 8-bit integer.

These formats are in the native format of the hardware platform. This accommodates the difference between Big-Endian and Little-Endian systems, that is, the difference between hardware architectures in which the most significant bit position is on the left as opposed to the right.

Function Call Reference Pages

• arm_end()

• arm_getid()

• arm_init()

• arm_start()

• arm_stop()

• arm_update()