FOCUS AREAS

ARM API

API Objects | API Calls | Implementing the SAS Interface to the ARM API

ARM - Using ARM API Objects and Calls

ARM API Objects

The following three classes of objects are specified in the ARM API:

There are no preset definitions for ARM objects within an application. The application instrumentor decides how to model the business objects into these three classes.

The ARM API uses numeric identifiers or IDs to uniquely identify the ARM objects that are input and output from the API calls. The three different classes of IDs that correspond to the three ARM classes are

IDs are numeric, signed integers. The Measurement Agent usually assigns IDs. The scheme for assigning IDs varies from one vendor's agent to another, but, at a minimum, uniqueness within a single session is guaranteed. Some Measurement Agents allow you to pre-assign IDs.

ARM API Calls

The following six calls are used in the ARM API:

arm_init
initializes the ARM environment and names the application and optionally the user of the application. An application ID is returned to the calling program. This ARM API call is typically coded once during application initialization.
arm_getid
accepts an application ID as input and names a transaction class. A transaction class ID is returned to the calling program. Several arm_getid calls are typically coded during application initialization after the arm_init call in order to describe the type of transactions that the application will utilize.
arm_start
signals the start of a transaction instance. An input transaction class ID is used to identify the transaction class that is associated with this transaction instance. A start handle is returned to the calling program. An arm_start call is inserted before every transaction you want to measure.
arm_update
specifies an optional function that you can use between an arm_start and arm_stop in order to supply information about the transaction that is in progress. An input start handle is used to identify the transaction instance and an output return code is returned to the calling program.
arm_stop
signals the end of a transaction. You can supply an optional transaction status code as input to the call that describes the success or failure of the transaction. An input start handle is used to identify the transaction instance and an output return code is returned to the calling program. An arm_stop call is placed in the code where the transaction is known to be complete.
arm_end
terminates the ARM environment and signals the end of an application. Its primary purpose is to free any memory that is associated with the application and to log any final application statistics. An input application ID is used to identify the application and an output return code is returned to the calling program.

ARM - Implementing the SAS Interface to the ARM API

The ARM API calls are implemented in SAS software with SAS macros and provide a way to measure the performance of SAS applications as they are running. For each call in the ARM API standard, there exists a corresponding SAS macro. The following table shows the relationship between the ARM API calls and SAS macros:

ARM API call

SAS Macro

arm_init %arminit
arm_getid %armgtid
arm_start %armstrt
arm_update %armupdt
arm_stop %armstop
arm_end %armend

The macros provide the most efficient method for invoking the ARM API calls, and it is recommended that you use these macros. The primary advantage of using the macros is that they manage the returned IDs automatically. 

The ARM macros use variables to pass IDs and other information. Because the macros must function within the same DATA step as well as across DATA steps, variables that are used by the  macros might take the form of DATA step variables or of macro variables. As a general rule, the macros store the returned IDs as

In the DATA step environment, but not the SCL environment, DROP statements are generated for variables so that they are not included in any output datasets.

Some important information about the ARM macros follows:

The following SAS and macro variables are used internally by the ARM macros:

Variable

Description

Set by

Used as input by

_armapid application ID %arminit %armgtid %armend
_armtxid transaction class ID %armgtid %armstart
_armshdl start handle %armstrt %armupdt,
%armstop
_armrc error status %armupdt,
%armstop,
%armend
none
_armglvl global level indicator calling program all
_armtlvl target level indicator calling program all
_armexec global enablement calling program all
_armacro open code enablement calling program all
_armscl SCL code enablement calling program all

As long as values for these variables are not changed outside of the ARM  macros, then the macros will function in a self-contained manner and not affect any surrounding code.

Parameters for the ARM macros are very similar to the parameters in the ARM API calls. However, the macros support the following additional parameters to control: