Previous section.

Systems Management: Application Response Measurement (ARM) API
Copyright © 1998 The Open Group

ARM API Function Calls

Overview

The ARM API is made up of a set of function calls that will normally be contained in a shared library. All the performance measurement agents that support the ARM API then provide their own implementation of the shared library.

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 diagram illustrates the valid call sequences for the ARM API. The dotted box encloses the call sequences valid for a specific transaction defined by a call to arm_getid(). This set of calls may be replicated for each defined transaction.

Figure: Valid Call Sequences for ARM API Functions

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

The following table shows which parameters are used in each of the ARM API function calls and what is passed on from one function call to another.

Definition of Data Type Terminology

The API calls use the terminology described in this section, to define each of the parameters.

Standard API Calls

The standard API calls use the following terminology to define each of the parameters:

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

The more advanced functions in the API use the following terminology to define each of the parameters:

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

The ARM 2.0 function calls are defined in alphabetical order in the remainder of this Chapter:


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index