1Summary of commands 2=================== 3 4Value of terms shown in each cell. Right-click and hold for pop-up menu. 5Double-left click to invoke inspector on cell. 6Updates: light-pink for backtracking, light yellow for forward execution. 7Continue button continues execution after stopping at a break-point 8 9Summary of function 10=================== 11 12This tool is used to monitor ECLiPSe terms during the execution of a 13program. In particular, it can track the changes on the attributes of 14attributed variables. Break-points can be set to stop execution on such 15changes. 16 17A display matrix window can be set up by the make_display_matrix predicates 18in ECLiPSe. See the descriptions of these predicates for more details on 19them. In addition, the user can interactively set up display matricies when 20the tracer is active, using the observe term facility. 21 22Layout 23====== 24 25A display matrix window consists of: 26 27Term matrix - a matrix of ECLiPSe term supplied by the 28make_display_matrix predicate. These terms are monitored in that value 29changes in these terms are printed here. 30 31Continue button - continue the execution of the program after a 32break-point. 33 34stop none button - unset break-points on all display matrix cells. 35 36stop all button - set break-points on all display matrix cells. 37 38Update on ground button - if set, cells are updated only when the term 39becomes ground. 40 41Kill display button - press to kill the display matrix. 42 43Interactive Creation of Display Matrix 44====================================== 45 46A display matrix can be created interactively when the tracer is active. 47Terms can be selected for observation while the tracer is at a debug port 48and if execution is continued. Individual terms can be selected from within 49the inspector, or the user can select whole goals from the tracer's call 50stack or the delay goals tool. The observed terms will be displayed with a 51pair of cells: a label identifying the term, and the term itself. For the 52individual terms selected from the inspector, the user supplies the 53label. For the goals, the invocation number is used as the label. 54 55The display matrix is created when ECLiPSe execution is continued from the 56debug port. The effect is equivalent to inserting a call to 57display_matrix/2 with the selected terms immediately after the debug port 58call. It is thus limited to displaying the changes in terms forward of this 59point. If the system backtracks pass the call, then the selected terms will 60no longer be tracked by the display matrix (the display matrix will remove 61itself when it is backtracked over. However, if it was in the scope of a 62cut, then the automatic removal will not occur and the user has to manually 63remove the window). 64 65 66Functionality 67============= 68 69The display matrix window consists of a term matrix of ECLiPSe terms. Each 70cell of this matrix represent an ECLiPSe term. The matrix is set up by 71calling either make_display_matrix/2 or make_display_matrix/5 predicate in 72ECLiPSe. See the description of these predicates for more details. The 73predicates specifies which terms would be in the matrix, along with how 74the value displayed in the cell will be updated. 75 76In general, the window is used to track changes in the attributes of the 77variables in a displayed term by displaying the new value of the attribute. If 78such a term is a compound term, then all variable in the term will be 79tracked. How often such changes are tracked is controlled by the 80specifications of the make_display_matrix predicate. With this tool, 81break-points can be set on each displayed term so that execution stops when 82its value is updated. 83 84Pressing and holding the right mouse-button on each cell of the matrix will 85cause a pop-up menu to appear. The menu applies to the term displayed in 86the cell, and consists of the following: 87 88 Current value: the value of a term printed in a cell may be truncated 89 if insufficient space is available in the cell to display it. Here 90 the term will not be truncated, although print-depth still applies. 91 92 Previous value: the previous value displayed in the cell before it was 93 updated. This allows the user to see how the value has been 94 changed. This value can be "-- unknown --" if the previous value is 95 not known (e.g. at the start). 96 97 Break on updates: set or unset a break-point. If set, execution will 98 stop when the term displayed is updated. In such cases, the 99 background colour of the cell will indicate how the update came 100 about: 101 102 Light pink -- the update is due to backtracking, i.e. the 103 previous value was backtracked, restoring the variable to an 104 older value. 105 106 Light yellow -- the update is due to forward execution. 107 108 Inspect this term: inspect the term using the term inspector. Note that 109 because the frequency of updates is controlled by the 110 make_display_matrix predicates, the actual value of the term may 111 not be the same as that shown in the cell. The inspector will 112 always examine the actual current value of the term. Note also that 113 because the update due to backtracking occurs just before the actual 114 backtracking, inspection is unavailable for a term when it has just 115 been backtracked (i.e. background in light-pink). 116 117Double left-clicking on a cell will invoke the inspector on that cell. 118 119The display matrix can be used independently of, or in conjunction with, 120the tracer. Note that the tracer needs to be active if the user want to 121create display matricies interactively. Once a matrix is created, the 122execution suspends with the initially supplied values of the terms 123displayed. The user can then set the appropriate break-points before 124continuing the execution. The default setting is that no break-points are 125set on any of the terms. 126 127A display matrix can be killed from the GUI level by clicking on the 128`Kill Display' button, or by closing or killing the window. It can also be 129killed from ECLiPSe using the kill_display_matrix/1 predicate if the 130predicate is issued within the `logical scope' of the display matrix. Note 131that killing the display matrix from the GUI level is done independently of 132the ECLiPSe level -- updates for the display matrix are still sent to the 133GUI, where they are simply ignored. 134 135Continue button 136--------------- 137 138Clicking this button causes the execution to continue after stopping at a 139break-point. Note that it will only continue execution from stops due to a 140break-point. Execution can be stopped for other reasons, e.g. at a 141trace-line in the tracer, or because a solution to the query has been 142returned. 143 144Stop none button 145---------------- 146 147Removes all break-points from the matrix. In this cases, updates to the 148cells will be shown without stopping. 149 150Stop all button 151--------------- 152 153Set break-points on all cells in the matrix. 154 155Update on ground 156---------------- 157 158This will cause updates to be shown only when the term in the cell becomes 159ground. This applies to cell with break-points as well: the execution will 160only stop in this case when the value becomes ground. 161 162Kill Display 163------------ 164 165Clicking on this button will kill the display matrix. 166 167