Using the ARM Interface | SAS 9.1.3 Language Reference: Concepts, Third Edition, Volumes 1 and 2

Overview

The SAS ARM interface provides the ability to monitor the performance of SAS applications. The interface consists of the implementation of the ARM API as an ARM agent. In addition, SAS supplies ARM macros, which generate calls to the ARM API function calls; and ARM system options, which manage the ARM environment and also enable you to log internal SAS processing transactions.

ARM System Options

SAS provides ARM system options, which are SAS system options that manage the ARM environment and provide the ability to log internal SAS processing transactions, such as file opening and closing and DATA step and PROC step response time.

The following ARM SAS system options are available:

ARMAGENT=

specifies another vendor's ARM agent, which is an executable module that contains a vendor's implementation of the ARM API. By default, SAS uses the SAS ARM agent.

ARMLOC=

specifies the location of the ARM log.

ARMSUBSYS=

initializes the SAS ARM subsystems, which determine the internal SAS processing transactions to be monitored . Each subsystem is a group of internal SAS processing transactions.

You can specify the ARM SAS system options

in a configuration file so that they are set automatically when you invoke SAS
on the command line when you invoke SAS
using the global OPTIONS statement either in the SAS program or in an autoexec file
from the System Options window.

See SAS system options in SAS Language Reference: Dictionary for details on each ARM system option.

See "Logging Internal SAS Processing Transactions" on page 231 for an example that sets the ARM system options.

ARM API Function Calls

The ARM API function calls are contained in the SAS ARM agent. Note that for the SAS implementation, you do not explicitly insert ARM API function calls in a SAS application; you insert ARM macros, which generate calls to the ARM API function calls.

These are the six ARM API function calls:

ARM_INIT

names the application and optionally the users of the application and initializes the ARM environment for the application.

ARM_GETID

names a transaction.

ARM_START

signals the start of a unique transaction.

ARM_UPDATE

provides information (optional) about the progress of a transaction.

ARM_STOP

signals the end of a transaction.

ARM_END

terminates the ARM environment and signals the end of an application.

ARM calls use numeric identifiers (IDs) to uniquely identify the ARM objects that are input and output from the ARM API function calls. The three classes of IDs are

application IDs
transaction class IDs
start handles (start time) for each instance of a transaction.

IDs are numeric, assigned integers. The agent usually assigns IDs. The scheme for assigning IDs varies from one vendor's agent to another, but, at a minimum, a unique ID within a single session is guaranteed . Some agents allow you to preassign IDs.

ARM Macros

The ARM macros provide an efficient method for you to identify which transactions in a SAS application you want to log. You insert the ARM macro calls in the SAS program code, which in turn generate calls to the ARM API function calls in order to log transaction information. The ARM macros automatically manage the returned IDs from the ARM API function calls.

The following table shows the relationship between the ARM API function calls and the ARM macros:

Table 15.1: Relationship Between ARM API Function Calls and ARM Macros
ARM API Function Calls	ARM Macro
ARM_INIT	%ARMINIT
ARM_GETID	%ARMGTID
ARM_START	%ARMSTRT
ARM_UPDATE	%ARMUPDT
ARM_STOP	%ARMSTOP
ARM_END	%ARMEND

The following ARM macros are available:

%ARMINIT

generates a call to ARM_INIT, which names the application and optionally the users of the application and initializes the ARM environment for the application. Typically, you would insert this macro in your code once.

%ARMGTID

generates a call to ARM_GETID, which names a transaction. Use %ARMGTID for each unique transaction in order to describe the type of transactions to be logged. A %ARMGTID is typically coded for each transaction class in an application.

%ARMSTRT

generates a call to ARM_START, which signals the start of an instance of a transaction. Insert %ARMSTRT before each transaction that you want to log. Whereas %ARMGTID defines a transaction class, %ARMSTRT indicates that a transaction is executing.

%ARMUPDT

is an optional macro that generates a call to ARM_UPDATE, which provides additional information about the progress of a transaction. Insert %ARMUPDT between %ARMSTRT and %ARMSTOP in order to supply information about the transaction that is in progress.

%ARMSTOP

generates a call to ARM_STOP, which signals the end of a transaction instance. Insert %ARMSTOP where the transaction is known to be complete.

%ARMEND

generates a call to ARM_END, which terminates the ARM environment and signals that the application will not make any more ARM calls.

The following post-processing ARM macros are also available. These macros are specific to the SAS ARM implementation; they are not part of the ARM API standard.

%ARMCONV

converts an ARM log created in SAS 9 or later, which uses a comma delimited format, into the ARM log format used in Release 8.2.

%ARMPROC

processes the ARM log and writes six SAS data sets that contain the information from the log.

%ARMJOIN

processes the six SAS data sets that are created by %ARMPROC and creates data sets that contain common information about applications and transactions.

For more information, see SAS ARM macros in SAS Language Reference: Dictionary . See "Using ARM System Options and ARM Macros to Log Performance Statistics" on page 233 for an example of inserting ARM macros in SAS code.

Logging the Transaction Records: the ARM Log

The SAS ARM agent supplies a basic logger that captures response time and CPU time statistics and handles logging the information. By default, the logger runs in the same session as your application and logs all ARM data synchronously to the external file that is specified with the ARMLOC= SAS system option.

All information that is passed by the application during ARM calls is written to the log, as well as other calculated statistics.

All ARM records are routed to the file to which the fileref points. Note that in Release 8.2, the ARM records were either written to the SAS log or to a specified external file. For SAS 9 or later, all ARM records are written to an external file. To specify the external output file, use the ARMLOC= SAS system option.

For SAS 9 or later, the format of the log records is comma delimited, which consists of columns of data separated by commas. The format of the ARM log that is written to by the logger was designed to be easily readable. The date/time stamp and the callidentifier always appear in the same column location. Subsequent information appears as a name =value pair.

Here is a sample of an ARM log:

Output 15.1: ARM Log (SAS 9 or Later Format)

 I,1320332339.838000,1,2.814046,5.988611,SAS,xxxxxx   G,1320332339.858000,1,1,MVA_DSIO.OPEN_CLOSE,DATA SET OPEN/CLOSE,LIBNAME,      ShortStr,MEMTYPE,ShortStr,MEMNAME,LongStr   S,1320332347.549000,1,1,1,2.914190,6.669590,WORK    ,DATA    ,ONE   S,1320332348.390000,1,1,2,2.934219,6.729676,WORK    ,DATA    ,TWO   P,1320332348.410000,1,1,1,2.954248,6.729676,0,WORK    ,DATA    ,ONE   P,1320332348.420000,1,1,2,2.964262,6.729676,0,WORK    ,DATA    ,TWO   S,1320332348.490000,1,1,3,2.994305,6.739691,WORK    ,DATA    ,THREE   P,1320332348.530000,1,1,3,3.14334,6.749705,0,WORK    ,DATA    ,THREE   S,1320332359.216000,1,1,4,3.224636,7.661016,WORK    ,DATA    ,THREE   P,1320332360.948000,1,1,4,3.254680,7.851289,0,WORK    ,DATA    ,THREE   S,1320332362.170000,1,1,5,3.304752,7.951433,WORK    ,DATA    ,THREE   P,1320332367.358000,1,1,5,3.334795,8.51577,0,WORK    ,DATA    ,THREE   S,1320332367.388000,1,1,6,3.354824,8.61592,WORK        ,DATA ,THREE   P,1320332367.398000,1,1,6,3.364838,8.61592,0,WORK    ,DATA    ,THREE   S,1320332367.428000,1,1,7,3.384867,8.71606,WORK     ,DATA   ,ONE   S,1320332367.438000,1,1,8,3.394881,8.71606,WORK     ,DATA   ,TWO   P,1320332372.655000,1,1,8,3.424924,8.131692,0,WORK     ,DATA   ,TWO   P,1320332372.665000,1,1,7,3.424924,8.141707,0,WORK     ,DATA   ,ONE   S,1320332375.970000,1,1,9,3.454968,8.392067,WORK     ,DATA   ,THREE   P,1320332377.282000,1,1,9,3.515054,8.562312,0,WORK   ,DATA ,THREE   S,1320332377.302000,1,1,10,3.525068,8.572326,WORK     ,DATA ,THREE   P,1320332377.923000,1,1,10,3.575140,8.632412,0,WORK     ,DATA ,THREE   S,1320332377.953000,1,1,11,3.585155,8.652441,WORK     ,DATA ,THREE   P,1320332383.521000,1,1,11,3.655256,8.832700,0,WORK     ,DATA ,THREE   S,1320332389.89000,1,1,12,3.715342,8.912816,WORK     ,DATA  ,THREE   S,1320332389.159000,1,1,13,3.725356,8.922830,SASUSER  ,DATA  ,THREE   P,1320332391.182000,1,1,12,3.765414,9.32988,0,WORK     ,DATA  ,THREE   P,1320332391.192000,1,1,13,3.775428,9.32988,0,SASUSER ,DATA ,THREE   E,1320336057.253000,1,4.105904,10.194659

To convert the SAS 9 or later log format into the Release 8.2 format, use the SAS macro %ARMCONV. For example, you might want to convert SAS 9 or later format to the Release 8.2 format if you have an application that analyzes the output in Release 8.2 format.

Note	The record layout is described in the ARMSUBSYS= SAS system option in SAS Language Reference: Dictionary .