Atomically adds (increments) a global variable by a numeric value. Note that increment is atomic, but the evaluation of the expression is not, unless inside a transaction (TStart/TCommit). The function also works on local variables, but has less benefit for locals as it does not (need to) provide ACID behavior.
The format of the $INCREMENT function is:
$INCREMENT(glvn[,numexpr])
$I, $INCR, $INCREMENT, $ZINCR, and $ZINCREMENT are considered as valid synonyms of the full function name.
$INCREMENT() returns the value of the glvn after the increment.
If not specified, numexpr defaults to 1. Otherwise, $INCREMENT() evaluates the "numexpr" argument before the "glvn" argument.
numexpr can be a negative value.
Since it performs an arithmetic operation, $INCREMENT() treats glvn as numeric value. $INCREMENT treats glvn as if it were the first argument of an implicit $GET() before the increment. If the value of glvn is undefined $INCREMENT treats it as having empty string , which means it treats it as a numeric zero (0) (even if glvn is a global variable that resides on a remote node and is accessed through a GT.CM GNP server).
If $INCREMENT() occurs inside a transaction ($TLevel is non-zero), or if glvn refers to a local variable, it is equivalent to SET glvn=$GET(glvn)+numexpr.
If $INCREMENT() occurs outside a transaction ($TLevel is zero) and glvn refers to a global variable, the function acts as a SET glvn=$GET(glvn)+numexpr performed as an Atomic, Consistent and Isolated operation. Note that $INCREMENT() performs the evaluation of numexpr before it starts the Atomic, Consistent, Isolated incrementing of the glvn. If the region containing the glvn is journaled, then the $INCREMENT() is also Durable. Only BG, MM (OpenVMS only) and GT.CM GNP access methods are supported for the region containing the global variable (glvn). GT.CM OMI and GT.CM DDP access methods do not support this operation and there are no current plans to add such support.
$INCREMENT() does not support global variables that have NOISOLATION turned ON (through the VIEW "NOISOLATION" command), and a $INCREMENT() on such a variable, triggers a GVINCRISOLATION run-time error.
The naked reference is affected by the usage of global variables (with or without indirection) in the glvn and/or numexpr components. The evaluation of "numexpr" ahead of "glvn" determines the value of the naked reference after the $INCREMENT. If neither glvn or numexpr contain indirection, then $INCREMENT sets the naked reference as follows:
glvn, if glvn is a global, or
the last global reference in "numexpr" if glvn is a local, or
unaffected if neither glvn nor numexpr has any global reference.
Example:
GTM>set i=1 GTM>write $increment(i) 2 GTM>write $increment(i) 3 GTM>write $increment(i) 4 GTM>write $increment(i) 5 GTM>write i 5 GTM>write $increment(i,-2) 3 GTM>write i 3 GTM>
This example increments the value of i by 1 and at the end decrements it by 2. Note that the default value for incrementing a variable is 1.