Systems Management: Application Response Measurement (ARM) API
Copyright © 1998 The Open Group
ARM API Function Calls
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:
- During the initialization of your application, call
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
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,
Check Account Balance.
In each program, each transaction
class may be executed once or many times.
returns a unique identifier that must be passed to
- Each time a transaction class is executed, this is a transaction
signals the start of execution of a transaction
instance and returns a unique handle to be passed to
- This is an optional function call that can be made any number of times
about the transaction instance, such as a
after a group of records has been processed.
signals the end of the transaction instance.
- At termination of the application, call
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
which are called
at the beginning and end of each executing transaction. There are two
administrative calls used to define the application and transactions:
is an optional call that can be
used with long running transactions to provide an
heartbeat and a progress indicator. Call
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
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
arm_init ("Application Name", "User Name")
arm_getid ("Transaction A")
arm_getid ("Transaction B")
arm_getid ("Transaction C")
loop until program ends
do some work
arm_stop (B, status)
loop until transaction ends
do some work
arm_stop (C, status)
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
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
- A signed 32-bit integer.
- 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:
- A signed 64-bit integer.
- An unsigned 32-bit integer.
- An unsigned 64-bit integer.
- 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.
- An unsigned 16-bit integer.
- An unsigned 8-bit integer.
These formats are in the native format of the hardware platform. This
accommodates the difference between
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.