Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Tools : $RULENAME

$RULENAME
Retrieves the name of a rule from the current execution stack. (F)
Invocation
result = $RULENAME(level, transactioncount)
 
The rule nesting level in relation to the current rule. For example, the rule that calls $RULENAME is at level 0. In other words, if RuleA calls RuleB and RuleB calls $RULENAME, then, in RuleB, to learn the name of the rule that called $RULENAME (RuleB), use a level value of 0; and to learn the name of the rule that called RuleB (RuleA), use a level value of 1 because it is 1 level higher than RuleB. A value of -1 indicates the maximum value.
The transaction nesting level in relation to the current transaction. For example, the transaction that contains the rule that calls $RULENAME is at transaction level 0, for the purposes of this tool. In other words, if RuleA of TransactionA starts TransactionB and RuleB of TransactionB calls $RULENAME, then, in RuleB, to learn the name of the rule that called $RULENAME (RuleB), use a transaction value of 0; and to learn the name of the rule that started TransactionB (RuleA), use a transaction value of 1 because it is 1 level higher than TransactionB. A value of -1 indicates the maximum value.
Usage Note
$RULENAME first locates the transaction level specified by transactioncount and then locates the rule specified by level.

Exceptions
 
In our example below, a transactioncount of 2 with a level of 2 would signal a RANGERROR exception because there are not two rules in the transaction two up from the one where $RULENAME is called.
Examples
Rules
A new transaction starts and this is the first rule:

 
RULE EDITOR ===> SCROLL: P
TOP_TOP_RULE;
_
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ ... |
_ EXECUTE PREV_TOP_RULE; | 1
_ ... |

 
That first rule starts a new transaction and this is its first rule:

 
RULE EDITOR ===> SCROLL: P
PREV_TOP_RULE;
_
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ ... |
_ CALL PREV_RULE1; | 1
_ ... |

 
These are the second and third rules in this transaction:

 
RULE EDITOR ===> SCROLL: P
PREV_RULE1;
_
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ ... |
_ CALL PREV_RULE2; | 1
_ ... |

 
 
RULE EDITOR ===> SCROLL: P
PREV_RULE2;
_
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ ... |
_ EXECUTE TOP_RULE; | 1
_ ... |

 
That third rule starts a third transaction and this is its first rule:

 
RULE EDITOR ===> SCROLL: P
TOP_RULE;
_
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ ... |
_ CALL RNAME_CALLER; | 1
_ ... |

 
These are the second and third rules of this last transaction:

 
RULE EDITOR ===> SCROLL: P
RNAME_CALLER;
_
LOCAL LEVEL, TRAN, DESC;
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ DESC = ' IS THE NAME OF THIS RULE'; ¦ 1
_ CALL RNAME(0, 0, DESC); ¦ 2
_ DESC = ' IS WHO CALLED THIS RULE'; ¦ 3
_ CALL RNAME(1, 0, DESC); ¦ 4
_ DESC = ' IS THE TOP RULE FOR THIS TRANSACTION'; ¦ 5
_ CALL RNAME(-1, 0, DESC); ¦ 6
_ DESC = ' IS THE TOP RULE FOR THE PREVIOUS TRANSACTION'; ¦ 7
_ CALL RNAME(-1, 1, DESC); ¦ 8
_ DESC = ' IS THE SECOND LAST RULE FOR THE PREV. TRANS.'; ¦ 9
_ CALL RNAME(1, 1, DESC); ¦ A
_ DESC = ' IS THE TOP RULE FOR THE TOP TRANSACTION'; ¦ B
_ CALL RNAME(-1, -1, DESC); ¦ C
_ ---------------------------------------------------------------------------

 
 
RULE EDITOR ===> SCROLL: P
RNAME(LEVEL, TRAN, DESC);
_
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ CALL MSGLOG($RULENAME(LEVEL, TRAN) || DESC); | 1
_ ---------------------------------------------------------------------------
_ ON RANGERROR :
_ CALL MSGLOG('RANGERROR LEVEL ' || LEVEL || ' ' || TRAN
_ || ' IS INVALID');

 
Output

 
--------------------------- INFORMATION LOG ----------------------------
COMMAND ===> SCROLL ===> P
RNAME IS THE NAME OF THIS RULE
RNAME_CALLER IS WHO CALLED THIS RULE
TOP_RULE IS THE TOP RULE FOR THIS TRANSACTION
PREV_TOP_RULE IS THE TOP RULE FOR THE PREVIOUS TRANSACTION
PREV_RULE1 IS THE SECOND LAST RULE FOR THE PREV. TRANS.
SESSMGR IS THE TOP RULE FOR THE TOP TRANSACTION
 
 
 
 
 
 
 
 
PFKEYS: 2=NEXT LOG 3=EXIT 5=REPEAT FIND 12=EXIT 13=PRINT 9=RECALL

 
Explanation
$RULENAME(0,0) returns the name of the rule invoking $RULENAME.
$RULENAME(1,0) returns the name of the rule calling the rule invoking $RULENAME. If this is issued in the first rule in a trigger, it returns the name of the rule causing the trigger to be entered.
$RULENAME(-1,0) returns the name of the top rule at the current transaction level.
$RULENAME(-1,1) returns the top rule at the previous transaction level.
$RULENAME(1,1) returns the first rule up the call stack for the previous transaction.
$RULENAME(-1,-1) returns the name of the top rule at the top transaction level.
See Also
TIBCO Object Service Broker Programming in Rules for information about transaction processing. (Levels as used in TIBCO Object Service Broker Programming in Rules are different from the use of the levels argument for this tool.)

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved