%ARMSTRT Macro

Specifies the start of a unique transaction and returns a handle that is passed to the %ARMUPDT and %ARMSTOP macros.

Category:

ARM Macro

Example 1: Basic Usage

Example 2: Supplying the Transaction ID Using TXNIDVAR=

Example 3: Generating an ARM_GETID Call and an ARM_START

Syntax

%ARMSTRT (< option-1 <, option-2, ...>>);

Optional Arguments

APPID=numeric variable or constant

is the application ID to use on the ARM_GETID function call. The value must be a numeric variable or constant.

Restriction	Use APPID= only when you use GETID=YES. See the %ARMINIT macro for information about GETID=YES.
Note	Use APPIDVAR= instead of APPID= in new applications. APPID= is obsolete.

APPIDVAR=numeric variable

is the application ID. The value must be a numeric variable.

Restriction

Use APPIDVAR= only when you use GETID=YES. See the %ARMINIT macro for information about GETID=YES.

CORR=n

defines the type of parent and child transactions.

Default	0
Requirement	Use CORR= only when you use correlators.

GETID=NO | YES

is optional and denotes whether to generate an ARM_GETID function call before ARM_START. If the value is YES, you can define the user metrics.

Default	NO
Requirement	TXNNAME= is required when you use GETID=YES.

LEVEL=numeric constant or variable

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

MACONLY=NO | YES

enables the %ARMSTRT macro to be issued in open code. You set the value to YES if the macro can be issued in open code and NO if it can be issued only in a DATA step.

Default

METRVAL1–7='name'

is the value of the user-defined metric. The value must be a SAS character variable or a quoted literal. The value can be up to eight characters in length.

Requirement

The value of the user-defined metric must correspond to the user metric defined in the %ARMGTID macro.

PARNTVAR=numeric variable

is a numeric variable that contains the value of the parent transaction start handle. Use PARNTVAR= only when you define a child transaction and only when the CORR= option has a value of 2 or 3.

SCL=NO | YES

is used only in SCL programs and specifies whether the macro is in an SCL environment. Set the value to YES if the macro is in an SCL environment and NO if it is not.

Default

SHDLVAR=numeric variable

is a numeric variable that contains the value of the start handle. SHDLVAR= is required when you use correlators to define parent and child transactions.

TXNDET='name'

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

Restriction	The transaction detail has a 127-character limit.
Requirement	Use TXNDET= only when you use GETID=YES.

TXNID=numeric variable or constant

is the transaction ID to use in the ARM_START function call. The value must be a numeric variable or constant.

Note	Use TXNIDVAR= instead of TXNID= in new applications. TXNID= is obsolete.

TXNIDVAR=numeric variable

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

TXNNAME='transaction-name'

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

Restriction	The transaction name has a 127-character limit.
Requirement	TXNNAME= is required only when you use GETID=YES.

Details

The %ARMSTRT macro signals the start of a unique transaction, also known as a transaction instance. A transaction instance is an instantiation of a transaction class that was previously defined by the %ARMGTID macro. If user metrics are defined for a transaction class using the %ARMGTID macro, the values for the user metrics begin with the METRVAL1–7= option.

The CORR= option defines the type of parent (primary) and child (component) transactions using the following values:

not part of a related group

parent transaction

child transaction

child of one transaction and parent of another

Note: You use CORR= only when you use correlators.

Each child start handle variable must be defined with a parent start handle variable. Here is a code fragment that shows the use of correlator types and the SHLDVAR= and PARNTVAR= options:

%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);

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

If GETID=YES and the 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.

The output is the _ARMSHDL variable, which is the start handle that was returned from the ARM_START function call. If GETID=YES, then the _ARMTXID variable is updated. Any variables for TXNIDVAR= and SHDLVAR= are updated.

Examples

Example 1: Basic Usage

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

Example 2: Supplying the Transaction ID Using TXNIDVAR=

%let _armexec=1;
%let _armacro=1;
data _null_;
  %arminit(appname=application-name, appuser='sasxyz');
  %armgtid(txnname='txn OE', txndet= 'Order Entry txn class'
           txnidvar=txnnum);
data _null_;
  %armstrt(txnidvar=txnname);
run;

Example 3: Generating an ARM_GETID Call and an ARM_START

%let _armexec=1;
%let _armacro=1;
data _null_;
  %arminit(appname='Forecast', appidvar=savapp);
run;
data _null_;
  %armstrt(getid=YES, txnname='Txn 1A',
           txndet='Forecasting Txn Class',
           appidvar=savapp);
run;