DMDX Help.

Restore Counters Keyword

<RestoreCounters [text] [option]>
<LoadCounters [text] [option]>


    Switch to load counters from a file, as of version 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>;

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

    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.