When running in User and respectively in Kiosk Mode, an e:cue Programmer show is considered as persistent with unchangeable data. This is for safety reasons, in case that you want to grant users limited control over a lighting installation (in most cases via the Action Pad) but nothing more than that. Nevertheless, there might be the need to save some status information even in User/Kiosk Mode. As an example you control several rooms using Action Pad faders and you want the lighting values to persist after system shutdown/reboot without making changes to the show file itself.
The e:script language features a set of commands to write variables into an XML file for later use. First, you have to use XmlBegin to specify a filename and if you want to read from or write into the particular file. The next step is to use the command XmlExchange to read/write certain variables (this depends on what you specified with XmlBegin). To close the file operation, call XmlEnd. You can use XmlExchange multiple times inside such an XmlBegin-/XmlEnd block to read or write multiple variables from or into one file.
Please note that a write operation will completely erase the previous contents of the given file. So be careful to use the correct filename. If no file with the given name exists, a new file will be created.
As a filename, you can either specify a simple filename (in that case the file will take its place in the Programmer’s main directory) or a complete path along with the name of the file. To use the My Documents folder of the current Windows user you can write $(MyFiles) followed by subfolders and the filename. When specifying a complete path, you must not use single backslashes as a separator because these are interpreted as control characters. You can either use a double backslash or a single slash as a separator.
Masters as XML
Fader values exist in the file and of course, are already declared inside the macro. In the special case when you read out an array, the array that was declared has also to be of exactly the same size as the array that was saved into the file before.
When you write a variable into a file, the particular variable must exist, of course. The command XmlEnd finishes a read/write operation. Please note that a write operation will only occur when you use XmlEnd.
When saving masters as values, 4096 relates to 100% and indices of masters begin with 0.
Example: Saving and recalling fader values
To save the position of Action Pad faders we have to query the status of the associated Versatile Masters and save the particular values into a file.
Assume that for our purpose it is sufficient to save the values of the first 12 Versatile Masters. The corresponding code is very short and easy:
for (i = 0; i < 12; i++)
vmaster[i] = GetSpeedMaster(i);
As you can see, an array named vmaster is declared in order to hold the values of the Versatile Masters. The values are received using the command GetSpeedMaster inside a for loop. The contents of our array are then all together written into the file vmasters.xml inside the current users My Documents directory. What we have to do now is to write a macro that restores the Fader values from the XML file. This is quite as easy and looks very similar to our previous code snippet:
for (i = 0; i < 12; i++)
We first read out the contents of our XML file (note the 0 as parameter for XmlBegin) into the array. These values are then applied to the particular Versatile Masters using the command SetSpeedMaster.
Using a function for complex data exchange
For simple variable storage and restore operations involving only a few variables, the example above works just fine. However, if you want to exchange a big set of variables, maybe even several times, it comes in very handy to write a function for the data exchange operation. This simplifies the code and prevents errors like forgetting a variable in an exchange operation as well. The following macro code shows an example function exchanging some sample variables:
function DataExchange(int do_save)
The above function DataExchange has one parameter named do_save. This parameter specifies if you want to save or load the particular variables. As for both kinds of operation the same function is used, it can never occur that a variable is forgotten. To save the set of variables specified inside the function, call the function as follows:
To restore a set of saved variables, write: