DMDX
Help.
Restore Counters Keyword
<RestoreCounters
[text] [option]>
<LoadCounters [text] [option]>
option:
silent
Switch to load counters from a file,
as of version 5.3.1.8 if macros were saved as well they'll be loaded too (note
macro body limit is 517 characters less the length of the macro's name).
See
<SaveCounters>
for filename details and examples. All counters and macros that were previously saved for this
subject ID will be loaded, existing counters and macros will not be affected unless their counter
number or macro name happens to be in use in which case the counter or macro will get the value in
the file. If the counter data file doesn't exist a job error will be
thrown unless the
silent option has been used. Counter
and macro values are loaded as the item is parsed, not at the end of the
item or when the frame containing the keyword is displayed.
The
silent option allows a script to become
reentrant after chaining to another item file by attempting to load counters
without actually knowing whether they exist or not. To wit it can save a counter with
an item number to resume execution at, the trick being detecting when the script
is initially run verses being reentered. Here you can set a counter to a
value that wouldn't be used for resuming execution, do a silent load of the
counters and then check if the counter has a different value and branch to it if
so. Gets more entertaining if you want to stop aborts of the run from
resuming where the last run resumed, here one has to save the invalid value of
the counter when one has resumed execution as well as in the chained to item
file and restoring it before the chained item file chains back to the main one
meaning any time either item file is aborted the saved resumption counter will
contain and invalid resumption item number.
So first the
calling reentrant item file has a sequence like this in it that if not used reentrantly
the indexed branch will just branch to item zero doing nothing otherwise it
would branch to whatever item had been set up in counter 333 in the bit that
comes after this:
~3 <set c333 = 0> <loadcounters
reentrant silent> <set c334 = c333> <set c333 = 0> <savecounters
reentrant macrostoo> <ib
c334>;
~0;
You'll notice it saves counter 333 as zero so that if the
run is aborted it won't resume operation twice at the stored location.
Next when that item file wants to chain to another it loads counter 333 with the
item number to resume execution at, here it's item 1115 and stores that:
~1 <set c333 = 1115> <savecounters reentrant
macrostoo> <chain preservevm destination> <lastframe>;
~1115;
Next our destination item file picks up the counters
saved by the reentrant item file with a fail safe if the file wasn't chained to
(by making sure 333 already exists if the load doesn't set it up otherwise the
when counter 334 is set to 333's value you'd get a use of an uninitialized
counter if it wasn't actually chained) and also
making sure it's zero in the saved counter file so an abort doesn't resume the
reentrant one incorrectly:
~1 <set c333 = 0> <loadcounters reentrant
silent> <set c334 = c333> <set c333 = 0> <savecounters reentrant macrostoo>;
Lastly our destination item file finishes by restoring
the item number in the re-entrant counters so it resumes at the right location
in the reentrant item file
(this would be it's last item, if not you'd want to use a skip display CR
indicator and you'd want to use <lastframe>:
0 <set c333 = c334> <savecounters reentrant
macrostoo> <chain preservevm reentrant>;
Note the subject data here will be spread over two item files'
data files but in
addition the data will be saved as two subjects in the reentrant item file's
data file as when
it chains to the destination file the data will be saved and then when it's
chained back to and finishes the second portion of it's data will be saved again
so the use of subject IDs becomes all but essential in tracing where the data
went (you could reconstruct it from the times the files were run but use of the
subject ID is going to be easier).
DMDX Index.