Using the ARM Interface


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 call identifier 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)
start example
 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 
end example
 

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 .




SAS 9.1 Language Reference. Concepts
SAS 9.1 Language Reference Concepts
ISBN: 1590471989
EAN: 2147483647
Year: 2004
Pages: 255

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net