ARM - Application Response Measurement

%ARMSTRT

Signifies the start of a transaction instance

Type:

ARM macro

Syntax

%ARMSTRT<(options)>

Options

APPID=

is an application ID. The value must be a SAS numeric variable or constant.

Note: Replaced by APPIDVAR parameter for Release 9.0 and later.

Restriction: Use the APPID= only when using GETID=YES. See %ARMINIT for information on GETID=YES.

APPIDVAR=

is a SAS numeric variable that supplies the value of the application ID.

Restriction: Use the APPIDVAR= only when you use GETID=YES. See %ARMINIT for information on GETID=YES.

CORR= 0 | 1 | 2 | 3

is an option to define the type of parent and child transactions.
Note: CORR is valid for Release 9.0 and later.

Restriction: Use CORR= 2 | 3 with PARNTVAR

Default: 0

Correlator Value	Description
0	This transaction is not using correlators
1	This transaction is a parent transaction only
2	This transaction is a child transaction only
3	This transaction is both a parent and child transaction

GETID=NO | YES

is optional and denotes whether to generate a transaction class ID.

Requirement: TXNNAME= is required when you use GETID=YES.

Default: NO

LEVEL=

is a variable that specifies the conditional execution level. The value must be a numeric constant or variable.

MACONLY=NO | YES

allows the %ARMSTRT macro to be issued in open code, outside of a DATA step.
Note: MACONLY is experimental for Release 8.2.

Default: NO

METRVAL1-METRVAL7=

is the value of the user-defined metric. The value must correspond to user metrics defined on %ARMGTID
Note: METRVAL1-METRVAL7 is valid for Release 9.0 and later.

PARNTVAR=

is the name of a SAS numeric variable that contains the value of the parent transaction
start handle and is only used when defining a child transaction.
Note: PARNTVAR is valid for Release 9.0 and later.

Restriction: PARNTVAR= is used only when the CORR= option has a value of 2 or 3.

SCL=NO | YES

allows the %ARMSTRT macro to be issued in SCL environment.
Note: SCL is valid for Release 9.0 and later.

Default: NO

SHDLVAR=

is a SAS numeric variable that contains the value of the start handle.

TXNDET=

is a transaction detail that is a SAS character variable or quoted literal value.

Requirement: TXNDET= is used only with GETID=YES.

Restriction: The transaction detail has a 127 character limit.

TXNID=

is a transaction ID. The value must be a SAS numeric variable or constant.

Note: Replaced by TXNIDVAR parameter for Release 9.0 and later.

TXNIDVAR=

is a SAS numeric variable that contains the value of the transaction ID when GETID=NO.
It contains the value of the txn ID when GETID=YES.

TXNNAME=aname

is the transaction name that is a SAS character variable or quoted literal value.

Requirement: TXNNAME= is required only when you use GETID=YES.

Restriction: The transaction name has a 127 character limit.

Description

%ARMSTRT signals the start of a transaction, also known as a transaction instance. A transaction instance is an instantiation of a transaction class that was previously defined using %ARMGTID.

Input

The transaction class ID that is generated from a previous %ARMGTID call is the input. If TXNIDVAR= option is supplied, the supplied value is used as the transaction ID. Otherwise, the value of the global macro variable _ARMTXID is used.

If GETID=YES and APPID= or APPIDVAR= options are supplied, the supplied value is used as the application ID. Otherwise, the value of the global macro variable _ARMAPID is used.

Output

The _ARMSHDL variable, which is the start handle, is the output. If GETID=YES, then the _ARMTXID variable is updated also. The variables that TXNIDVAR= and SHDLVAR= point to are also updated if supplied.

Correlators

In the definition below, "transaction" means a unique start handle (SHDLVAR) as defined in %ARMSTRT. "Transaction class" refers to a TXNIDVAR value defined by %ARMGTID. Each transaction is an occurrence or instance of a transaction class.

"Many client/server transactions consist of one transaction visible to the user, and any number of nested component transactions that are invoked by the one visible transaction. These component transactions are the children of the parent transaction (or the child of another child component transaction). It's very userful to know how much each component transaction contributes to the total response time of the visible transaction. Similarly, a failure in one of the component transactions will often lead to a failure in the visible transaction, and this information is also very useful." ARM API Guide 2.0

The use of correlators REQUIRES that multiple transactions (start handles) are active simultaneously. This requires the use of the CORR and SHDLVAR parameters on the %ARMSTRT macro.
Each component (child) transaction is started AFTER the primary (parent) transaction is started.
Parent or child transactions can be of the same or different transaction classes. Use the appropriate TXNIDVAR value (defined by %ARMGTID) to assign the transaction to their class. Only one transaction class is used in the example below.
User metric values can be specified on %ARMSTRT if the metrics are defined in the corresponding transaction class (%ARMGTID).
All child transactions MUST be stopped before the parent transaction is stopped. The sibling transactions may be stopped in any order.
Primary or component transactions may have updates (%ARMUPDT) specified.

Examples

Example 1: Basic usage requires no parameters

data _null_;
   %arminit(appname='Forecast')';
   %armgtid(txnname='Txn 1A', txndet='Forecasting Txn Class');
   %armstrt(shdlvar=sh1);
run;

Example 2: Saving the start handle

data _null_;
   %arminit(appname=aname, appuser='sasxyz');
   %armgtid(txnname='txn OE', txndet= 'Order Entry txn class');
   %armstrt(shdlvar=sh1);
   put "start handle is " sh1;
run;

Example 3: Supplying the transaction ID using TXNIDVAR=

data _null_;
   %arminit(appname=aname, appuser='sasxyz');
   %armgtid(txnname='txn OE', txndet= 'Order Entry txn class'
            txnidvar=txnnum);

data _null_;
   %armstrt(txnidvar=txnname);
run;

Example 4: Correlator Usage

Transaction 100 consists of transactions 110, 120 and 130, each performing a different part of the unit of work represented by transaction 100.

Transaction 120 consists of transactions 121 and 122.

Transaction 200 does not have any component transactions.

Here is a code fragment used to create these relationships.

%arminit(appname='Application",appidvar=appid);
%armgtid(appidvar=appid,txnname='TranCls',txndet='Transaction Class Def',
         txnidvar=txnid);
%armstrt(txnidvar=txnid,corr=1,shdlvar=HDL100);
%armstrt(txnidvar=txnid,corr=0,shdlvar=HDL200<,...user metrics>);
%armstrt(txnidvar=txnid,corr=2,shldvar=HDL110,parntvar=HDL100);
%armstrt(txnidvar=txnid,corr=3,shldvar=HDL120,parntvar=HDL100);
%armstrt(txnidvar=txnid,corr=2,shldvar=HDL130,parntvar=HDL100);
%armstrt(txnidvar=txnid,corr=2,shldvar=HDL121,parntvar=HDL120);
%armstrt(txnidvar=txnid,corr=2,shldvar=HDL122,parntvar=HDL120);
...
%armstop(shdlvar=HDL200);
%armstop(shdlvar=HDL121);
%armstop(shdlvar=HDL122);
%armstop(shdlvar=HDL120);
%armstop(shdlvar=HDL130);
%armstop(shdlvar=HDL110);
%armstop(shdlvar=HDL100);

FOCUS AREAS

ARM - Application Response Measurement

%ARMSTRT

Syntax

Options

Examples

Example 1: Basic usage requires no parameters

Example 2: Saving the start handle

Example 3: Supplying the transaction ID using TXNIDVAR=

Example 4: Correlator Usage