• support.sas.com

• Knowledge Base

• Support

• Training & Bookstore

• Happenings

• Support Communities

FOCUS AREAS

• Base SAS
• Graphics
• Enterprise Management Integration
• Migration
• Scalability & Performance
  • Papers
  • Grid Computing
  • Scheduling
  • Platform Suite for SAS
  • SAS/ACCESS Software
  • SAS/CONNECT Software
  • SAS Metadata Server
  • SAS OLAP Server
  • Scalable SAS Procedures
  • SPD Engine
  • SPD Server
  • ARM Tools
    • - SAS Notes
    • - SAS Interface
    • - Instrumenting SAS Applications
    • - SAS ARM Macros
    • - ARM API
    • - Gathering Performance Data
    • - Reporting on Performance Data
    • - ARM Documents
    • - Examples
  • FULLSTIMER Option
• Statistics & Operations Research
• SAS AppDev Studio

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:

• applications represent the systems that you are instrumenting, for example, an inventory or order entry application. Because the SAS interface to the ARM API provides totals on a per application basis, you might want  to consider this when you define the scope of your application.

• transaction classes specify a unit of work. For example, "Check Account Balance" and  "Update Customer Database" are classes of transactions. You should create a transaction class for each major type of work that you want to instrument within an application.

• transaction instance specifies the actual start time for a unit of work. Transaction instances have response time information that is associated with them.

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

• application IDs
• transaction class IDs
• start handles for transaction instances.

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

• temporary SAS variables if the ARM calls are in the same DATA step
• global SAS macro variables to pass ID values between separate DATA steps
• SCL variables if within an SCL program.

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:

• In the calling program, avoid using either macro variables or SAS variables that begin with the letters "_ARM".
• You can invoke multiple  macros within the same DATA step or across separate DATA steps or SCL programs.
• All macro parameters are keyword parameters. There are no positional parameters. Values for the macro parameters should be valid SAS values, for example, a SAS variable, quoted character string, numeric constant, and so on.
• Normally, you must place all ARM macros within a DATA step or an SCL program.

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:

• identifier passing for more complex environments
• macro enablement/disablement
• combining multiple ARM calls
• running in an SCL environment.

Contact Us | Sitemap | RSS Feeds | www.sas.com | Terms of Use & Legal Information | Privacy Statement