13.4. Saving and restoring state

13.4.1. Overview

One of the special behaviors of this GUI is that the state is always saved at the end of a session (i.e. at exit) to a configuration file. This saves the entire state of the GUI: channel names and device settings. At startup of the subsequent session, the configuration file is read and only the channel names are restored. In this way, the existing device state prior to startup is left unalterred. The details of saving and loading are described below.

13.4.2. Saving the state

The state of the GUI can always be saved to a file by means of the "File > Save as..." drop-down menu button. The same thing happens at exit. There difference between the drop-down menu button and the save on exit operation is which file is saved to. When the drop-down menu is used, the user specifies the file that will be written to. At exit, the value of the --configfile command-line option will be used.

Saving the state of the gui produces a tcl script that can be executed for configuring the device exactly as the GUI would display it. This will record the state of the device itself within the synchronization limitations of the application. To be more explicit, the only time the state written to file may not be identical to the device is if the user closes the GUI within the time window between the most recent change to the GUI and the time at which that most recent change would be communicated to the device. That is about a 300 ms time window. The best practice is therefore to allow the GUI to finish communicating prior to exiting.

The script produced by a save as operation is actually a TCL script. It can be sourced in a TCL shell to set the state of the device independent of the GUI. This will work so long as:

  1. The driver scripts are included in the TCLLIBPATH environment variable. These scripts should be usable if the user adds $DAQROOT/TclLibs to their TCLLIBPATH environment variable.

  2. The same settings for the communication protocol that were valid when the script was generated are still valid. In other words, if the GUI was launched with --serialfile set to /dev/ttyUSB0, then it must still be possible to write to the device through the /dev/ttyUSB0 file.

If those requirements are satisfied, the script can be fed to a tclsh program. That will transfer all of the state explicitly set in the script to the device. To illustrate this further, if the configuration file is named mysettings.tcl, one should execute the following at the command line,

        tclsh < mysettings.tcl

13.4.3. Restoring the state

Like saving, restoring implies that settings are loaded to the GUI. Because the device is tightly synchronized to the GUI, the loaded settings are immediately communicated to the device. For best results, the user should load a tcl script that was generated by the GUI through a save as operation or at exit. If one knows what they are doing, they can certainly write their own configuration script by simply calling the same types of API calls as the scripts generated by the GUI.

Loading the file causes the lines that are understood to be driver calls to be executed and loaded into the GUI. Furthermore, lines that set channel names (set ::MSCF16ChannelNames::chan0 name) are executed and read into the GUI. Other lines of code are not evaluated. This is actually very strict. For all of the parameters that are not set explicitly in the config file, the GUI will simply ignore them.

At startup, the state of only the channel names are restored from the file if it exists. The device state is only ever changed if the user explicitly uses the "Load settings..." menu button.