1#!F-adobe-helvetica-medium-r-normal--18* 2#!N 3#!CNavyBlue #!N 4 #!Rstates Preserving Explicit State #!N #!EC #!Cbrown #!N #!F-adobe-times-medium-r-normal--18* #!Rxmodx641 #!N 5Graphics omitted from Online Documentation. Please see the manual. #!N #!N 6Figure 41. Example 5 #!EF #!N #!EC #!N #!N Some visualization 7applications require the retention of state from one execution to the 8next, which as discussed earlier, cannot be supported within the context 9of pure data flow. Consider, for example, the creation of a 10plot of data values at a given point while sequencing through 11a time series. The state of the plot from the prior 12execution is retrieved. It is updated by appending the new time-step 13information, and the result is then preserved by resaving the state 14of the plot for the next execution. Data Explorer provides two 15sets of tools for preserving state depending on whether the state 16needs to be preserved over one execution of the network or 17over multiple executions of the network. The tools for preserving state 18are GetLocal, SetLocal, GetGlobal, and SetGlobal. The Set tools enable you 19to save an object (in Data Explorer's cache) for access in 20a subsequent execution or iteration. The Get tools enable you to 21retrieve the object saved by the Set tools. #!N #!N You 22pair a GetLocal and SetLocal in a visual program by creating 23an arc from GetLocal's #!F-adobe-times-bold-r-normal--18* link #!EF output parameter to SetLocal's 24 #!F-adobe-times-bold-r-normal--18* link #!EF input parameter. In a visual program a GetLocal 25typically appears logically above a SetLocal. When GetLocal runs, it checks 26if an object has been saved in the cache. If no 27object was saved (as would be the case if SetLocal has 28not yet run) or the #!F-adobe-times-bold-r-normal--18* reset #!EF parameter to GetLocal 29is set, GetLocal outputs an initial value that you can set 30using the #!F-adobe-times-bold-r-normal--18* initial #!EF parameter. Otherwise, GetLocal retrieves the saved 31object from the cache and outputs it. When SetLocal runs, it 32saves its input object in the cache and then indicates that 33its paired GetLocal should simply be scheduled during the next iteration 34of a loop or the next time an execution is called 35for. (Note that if GetLocal is inside a macro, it will 36be executed only if the macro needs to be executed; that 37is, if the macro's inputs have changed or there is a 38side effect module in the macro.) #!N #!N GetGlobal and SetGlobal 39are paired in the same way as GetLocal and SetLocal. They 40also save and retrieve items from the cache. The main difference 41is that GetGlobal and SetGlobal will preserve state over more than 42one execution of a program. (However, recall that a complete loop 43takes place within a #!F-adobe-times-medium-i-normal--18* single #!EF execution.) #!N #!N Using 44GetGlobal and SetGlobal is comparable to using a static variable in 45C-language programming. GetLocal and SetLocal are good for saving state inside 46of a looping construct. Once the loop is terminated, the state 47is reset for the next execution of the loop. To save 48state in a program that uses a Sequencer module, you should 49use GetGlobal and SetGlobal, since each iteration of the Sequencer is 50a separate execution of the program as described in #!Lloop,dxall268 h Iteration using Looping #!EL . 51#!N #!N #!N #!N Illustrated in #!Lxmodx641,dxall269 f Figure 41 #!EL is a simple macro 52that sums the numbers from 1 to N, where N is 53an input parameter. The #!F-adobe-times-bold-r-normal--18* start #!EF parameter to ForEachN has 54been set to 1. GetLocal and SetLocal are used to accumulate 55the sum. Sum is a trivial macro consisting of a Compute 56where the expression is "a+b." On the first iteration of the 57loop, GetLocal will output its #!F-adobe-times-bold-r-normal--18* initial #!EF value, which has 58been set to 0. On subsequent iterations GetLocal will output the 59accumulated value SetLocal saved during the previous iteration. When the loop 60terminates the final accumulated value is the output of the macro. 61This macro is roughly equivalent to the following C-language statements: #!CForestGreen 62#!N #!N #!F-adobe-courier-bold-r-normal--18* #!N b = 0; #!N for (a=1; a<=10; 63a++) #!N b = b+a; #!EF #!N #!N #!EC #!N #!N 64If the macro were run again, on the first iteration of 65the loop GetLocal would again output its #!F-adobe-times-bold-r-normal--18* initial #!EF value. 66(Note that the macro will only run again if the input 67to the macro changes or the output of the macro has 68been removed from cache.) #!N #!N If you replaced the GetLocal 69and SetLocal in #!Lxmodx641,dxall269 f Figure 41 #!EL with GetGlobal and SetGlobal it would be 70equivalent to the following C-language statements: #!CForestGreen #!N #!N #!F-adobe-courier-bold-r-normal--18* #!N 71int a; #!N static int b = 0; #!N for (a=1; 72a<=10; a++) #!N b = b+a; #!EF #!N #!N #!EC While 73when SetLocal is used, the sum is reset each time the 74macro is run, if SetGlobal is used, the sum of a 75previous execution is added to the sum of the current execution. 76For example, let macro_local be the macro shown in #!Lxmodx641,dxall269 f Figure 41 #!EL and 77macro_global be the same macro but with SetGlobal and GetGlobal substituted 78for SetLocal and GetLocal. If the input to both macros is 7910 then both macros will output 55 (the sum of numbers 801 to 10) the first time they are run. If an 81execution takes place without the input to the macros changing then 82neither macro will run again and the value 55 will be 83used as the output again. If you change the input to 843 then macro_local will output 6 and macro_global will output 61 85(55+6). #!N #!N Illustrated in #!Lxmodx742,dxall269 f Figure 42 #!EL is a macro that returns 86the accumulated volumes of the members of a group and the 87number of members in the group. ForEachMember is used to iterate 88through the group. Measure is used to determine the volume of 89a member and the GetLocal and SetLocal pair on the left 90side of the macro is used to accumulate the volumes. For 91illustrative purposes, a loop containing GetLocal, SetLocal, and Increment is used 92to count the number of members in the group. (Inquire also 93provides this function, as does the #!F-adobe-times-bold-r-normal--18* index #!EF output of 94ForEachMember.) Increment is a trivial macro consisting of a Compute where 95the expression is set to "a+1." The #!F-adobe-times-bold-r-normal--18* initial #!EF values 96to both GetLocal tools are 0. #!Cbrown #!N #!F-adobe-times-medium-r-normal--18* #!Rxmodx742 #!N 97Graphics omitted from Online Documentation. Please see the manual. #!N #!N 98Figure 42. Example 6 #!EF #!N #!EC #!N #!N Illustrated in 99 #!Lxmodx1343,dxall269 f Figure 43 #!EL is a visual program that saves the current camera settings 100for use in the next execution of the program. The initial 101value of GetGlobal is NULL. The Inquire module checks to see 102that the output of GetGlobal is a valid camera object. If 103it's not a camera object, then Route is used to ensure 104that the Display module is not scheduled to run. When a 105new camera is chosen (for example by rotating the object in 106the Image window) the Display window will show the image using 107the previous execution's camera settings. #!Cbrown #!N #!F-adobe-times-medium-r-normal--18* #!Rxmodx1343 #!N Graphics 108omitted from Online Documentation. Please see the manual. #!N #!N Figure 10943. Example 7 #!EF #!N #!EC #!N #!N As mentioned previously, 110in a true data-flow implementation, all modules are pure functions (i.e. 111their outputs are fully defined by their inputs). Hence, processes are 112stateless with no side effects. A macro in Data Explorer is 113considered to be a function, with its outputs being fully defined 114by its inputs. This is no longer true when a GetGlobal 115module is added to a macro. GetLocal maintains state information only 116within one execution of the macro. GetGlobal maintains state information between 117executions, and therefore the outputs of a macro containing GetGlobal are 118no longer entirely defined by the inputs. The outputs from macros 119with state (containing a GetGlobal module) are guaranteed to stay in 120the cache until the inputs for that macro change. At that 121point, the results of the previous execution are discarded to make 122room for the new results. This is equivalent to setting the 123cache attribute of the macro to #!F-adobe-times-bold-r-normal--18* cache last #!EF for 124each of the outputs. These cache settings cannot be overwritten by 125the user. This guarantees coherency when executing macros with state. #!N 126#!N #!N #!F-adobe-times-medium-i-normal--18* Next Topic #!EF #!N #!N #!Lall269,dxall270 h Advanced Looping Constructs #!EL #!N #!F-adobe-times-medium-i-normal--18* 127#!N 128