DMDX Help.


Set Counter Keyword

<SetCounter CounterN=expression>
<set CounterN=expression>
<SetCounter cN=expression>
<set cN=expression>

deprecated usages:
<SetCounter N1,N2>
<set N1,N2>
<SetCounter N,text>
<set N,text>


    Preferred usage evaluates expression using a modified and significantly expanded version of CALC.C that Bob Brodt wrote in 1985 and assigns the result to CounterN.   First deprecated usage sets Counter N1 to value N2, second deprecated usage sets counter N to some value depending on the string text.   Counters are used to control branching in DMDX, more specifically for building looping mechanisms.   Before a counter can be used it must be setup at least once with a <SetCounter> keyword, after that it can be incremented or decremented, conditionally incremented or decremented depending on the subjects response (see the Branching keywords for a full list of possibilities), emitted into the output file, tested against with the Branching keywords or set to another value with <SetCounter> again.   Counter's values are signed 32 bit integers.  
    A counter's value can be stored in the output data file with <EmitCounter> and can be displayed with <AppendCounter>. (not recommended) or the <sprintf> keyword (recommended).

    Possible tokens in expression and values for text are:
CounterN The value of counter N, for example <set 3,counter2> would set (and create if necessary) counter 3 to the value counter 2 had when this keyword is parsed.
cN Synonym for CounterN
LastRT Absolute value of the last Reaction Time gathered in whole milliseconds (rounded down).   Because expressions are evaluated as the item is parsed this RT is the previous item's RT, not the RT that might be gathered by the item the expression is in.
LastXT Last Reaction Time (previous item) gathered in whole milliseconds (rounded down).   This will be negative if the response was incorrect.
ErrorRate The error rate at the end of the previous item (useful for multiple tests against the error rate as a branch on the error rate will reset it).
ClockOnTime The millisecond time that the clock was last turned on.  This has two possible values depending on whether <RecordClockOnTime> is turned on.  If <rcot> is on then loading a counter with clockontime will return the time the most recent clock on occurred since the first clock on in the item file, otherwise it is since the item file commenced execution.
MillisecTime The millisecond time when the expression is evaluated (usually the time the item is parsed but it can be later with <AbortItemExpression>) since the item file commenced execution.
VideoTime The current video retrace count when the expression is evaluated since the item file commenced execution.
atoizilliontext The integer value of the previous item's text string entered with <ZillionTypedResponses>.
jobstatus The value of the job status variable that tracks the job state at the time of parsing.  Only useful for the  <AbortItemExpression>.

    Rules regarding evaluation of expression are as follows:

* Calculator program - 9 May 1985
*     Bob Brodt
*     34 Mehrhof Rd.
*     Little Ferry, NJ 07643
*     (201)-641-9582
*
* This is a simple integer arithmetic calculator program. It uses infix
* notation, i.e. 1+2*3 as opposed to "reverse polish" notation: 1 2 3 * +.
*
* CONSTANTS:
*     Numbers may be input as in C using 0x notation for hex, and a
*     leading zero for octal, everything else is assumed to be decimal.
*     DMDX constants at time of evaluation:
            lastrt
            lastxt
            errorrate
            clockontime
            millisectime
            videotime
            atoizilliontext
            jobstatus
* VARIABLES:
*     DMDX counters referenced by counterN or cN
* OPERATORS:
*     The following operators are supported (from highest precedence to lowest):
*
*     ( )             associativity
*     ~ !             one's complement, logical NOT
*     * / %             multiply, divide and modulo
*     + -             unary and binary add & subtract
*     .SHL. .SHR.         shift left and right
*     .LT. .GT. .LE. .GE.     less than, greater than, less than or equal to and
*                     greater than or equal to
*     .EQ. .NE.         equal to and not equal to
*     &             bitwise AND
*     ^             bitwise exclusive OR
*     |             bitwise inclusive OR
*     .AND.               logical AND
*     .OR.             logical OR
*     =             assignment
*     ,             comma - separates function arguments
*
*     All operators associate from left to right with the exception of
*     the assignment (=) operator.   Logical operations resolve to 1 if true and 0
*     if false.
* FUNCTIONS:
*     The calculator also has built-in function capabilities:
*     max(a, b) - larger of a or b
*     min(a, b) - smaller of a or b
*     abs(a) - absolute value of a
*     random(a) - random number between 0 and a-1 (a should be less than 32768)
*  Precedence of functions is a little weird, currently random(a) + b evaluates to random(a + b) because
*  function call brackets are just brackets, so random a + b is valid syntax with + having the higher
*  precedence.  So the safe use of functions is currently (random(a)) + b.

    Typical use of a counter involves setting it to some initial value and decrementing it and using one of the counter branching keywords <bicGT> till the counter reaches 0.   In the following item 10 will be displayed five times:

0 "looping demo" <set c1 = 5>;
+10 * "display" <dec 1> <bicGT 1,0,-10>;
0 "end";

    Possible things to be aware of are that expressions (both in <SetCounter> and <BranchIf> keywords), non conditional arithmetic (<inc> and <dec>) and most other actions in counter related keywords are performed as the item is parsed before display so multiple uses of those keywords in the same item are possible.   Whereas conditional arithmetic keywords (<incic>, <inciw>, <incinr>, <decic>, <deciw>, <decinr>) are evaluated after the item is displayed and the RT gathered (thus necessitating special control structures within DMDX) and are limited to one operation per counter per item, in the case of multiple uses only the last will have any effect.   Branches other than <BranchIf> (<bicGT> and <bicLE>) are evaluated at the beginning of the next item after everything else.

    Another typical use of counters involves tracking multiple error rates and branching if the error rates are too high.  In the following each class of test needs an 80% or higher success rate:
 

100 "start" <set c10=0> <set c11=0>

            <set c20=0> <set c21=0>

            <set c30=0> <set c31=0>;

 

+1000 "class 1 test" * <incic 10> <inc 11>;

+2000 "class 2 test" * <incic 20> <inc 21>;

+3000 "class 3 test" * <incic 30> <inc 31>;

! repeat items 1000, 2000 and 3000 as needed;

 

~200 <emit 10> <emit 11>

     <emit 20> <emit 21>

     <emit 30> <emit 31>

  <bi 100, (c10 * 100 / c11 .lt. 80) .or.

             (c20 * 100 / c21 .lt. 80) .or.

             (c30 * 100 / c31 .lt. 80)>;

 

0 "end";


    See the <ZillionTypedResponses> keyword for a fairly complex counter using example.

    See the <MacroDefinition> keyword for neat subroutine to assign a macro to the ascii value of a counter which will then allow you to use a counter's value for setting parameters DMDX doesn't otherwise allow counters to be used for.

DMDX Index.