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