1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>The Table Visualizer</title>
27
<prepared>EPK/TK Fredrik Gustafson</prepared>
28
<responsible></responsible>
30
<approved>EPK/TK (Fredrik Gustafson)</approved>
32
<date>1998-01-19</date>
34
<file>table_visualizer.sgml</file>
36
<p>The TV, TV, is a tool that enables the user to examine
37
ETS and Mnesia tables on any (connected) node in the currently running Erlang
38
system. Once a certain table has been opened in the tool, the content may be
39
viewed in various levels of detail. The content may also be edited, as well as
40
sorted, using any element as key. It is also possible to search for a specified object or
41
element. The table may be polled anytime, either regularly, at specified
42
intervals, or manually. New and deleted objects, as well as those altered, are
43
marked with characteristic colours.</p>
44
<p>Information about the table itself (permissions, storage type, and so on) may
49
<title>Terminology and Background</title>
50
<p>To avoid confusion, we have to distinguish between the <em>actual table</em>, i.e.,
51
the data stored in ETS or Mnesia, and the <em>image of the table</em>, i.e., the
52
data shown in the TV. The <em>image of the table</em> is simply a copy
53
of the <em>actual table</em>, and can be manipulated in a number of ways, for example
54
sorted. It follows that these manipulations in no way affects the <em>actual table</em>!</p>
55
<p>The expression <em>poll the table</em> is used for the operation of scanning through the
56
content of the actual table (in order to keep the image of the table consistent with the
58
<p>The ETS and Mnesia modules provides the user with the ability to store vast quantities
59
of data in, the data organized as dynamic, unordered tables. The ETS
60
facility stores <em>tuples</em>, while Mnesia stores <em>records</em>.
61
Each tuple consists of one or more <em>elements</em>; each record consists of one or
62
more <em>fields</em>. It should be noted that, since records are implemented as tuples,
63
with the record name as the first element, the first field of a record becomes the second
64
element in the corresponding tuple!
67
In the following, all table objects are mainly referred to as tuples, regardless of the
69
<p>For further information about ETS and Mnesia, please see the manual pages and Mnesia User's Guide.</p>
73
<title>Starting the TV</title>
74
<p>The TV tool is started by giving the command</p>
78
<p>The window that appears, is hereafter referred to as <em>the TV main window</em>. It consists of:</p>
79
<list type="bulleted">
81
<p>a <em>menubar</em>.</p>
84
<p>a <em>grid</em>, i.e., a multicolumnar array, where tables existing on
85
the current node is shown. Each square in the grid is called a <em>cell</em>.</p>
88
<image file="tv_start">
89
<icaption>The TV Main Window at startup.</icaption>
91
<p>For each table, the following information is shown, in order:
93
<list type="bulleted">
95
<p>the <em>table name</em>. If the table is accessible through this name, as is the
96
case with Mnesia tables and named ETS tables, the table name is shown in
97
black, otherwise in medium grey.</p>
100
<p>the <em>table identifier</em>, if there is one; since Mnesia tables are accessed
101
solely through the table name, this cell will in those cases be blank.</p>
104
<p>the <em>process identifier (PID) of the process owning the table</em>.</p>
107
<p>the <em>name of the process owning the table</em>, provided the process
111
<p>the <em>table size</em>, i.e., the number of objects currently stored in
118
<title>Changing View</title>
119
<p>The TV will by default show currently existing ETS tables,
120
but the user may easily switch to a Mnesia table view, by choosing the
121
<em>Mnesia Tables</em> option in the <em>View</em> menu:
123
<image file="tv_start_mnesia">
124
<icaption>The TV Main Window, showing Mnesia tables.</icaption>
126
<p>Normally, system tables (i.e., tables used by system applications) and unreadable
127
tables are not shown. The menu option <em>System Tables</em>, in the <em>Options</em>
128
menu, makes the system tables visible:
130
<image file="tv_start_system">
131
<icaption>The TV Main Window, showing readable user and system tables.</icaption>
133
<p>Still unreadable tables are hidden, but the menu option <em>Unreadable Tables</em>,
134
also in the <em>Options</em> menu, makes even those tables visible. It shall be noted
135
that rows containing unreadable tables are shaded, using a grey colour:
137
<image file="tv_start_system_unreadable">
138
<icaption>The TV Main Window, showing both readable and unreadable user and system tables.</icaption>
140
<p>Once a table view has been opened, the user may choose how to view it: it may be sorted
141
by the table names, by the table identifiers, by the process identifiers of the owner
142
processes, or by the names of the owning processes. These sorting options are found in the
143
<em>Options</em> menu.
145
<image file="tv_start_pid_sorted">
146
<icaption>The TV Main Window, tables sorted by owner PID.</icaption>
151
<title>Changing the Current Node</title>
152
<p>By default, the Table Vizualizer will show tables residing on the node
153
it was started from. However, the user may easily view tables on other nodes.
154
By choosing the <em>Nodes</em> option, in the <em>File</em> menu, a window showing
155
all connected nodes will appear. Clicking on any of the nodes in the list will cause
156
the main window to immediately show the tables residing on the specified node:
158
<image file="tv_start_other_node">
159
<icaption>The Connected Nodes window, and the TV Main Window, showing tables on the selected node.</icaption>
164
<title>Opening a Table in the Table Browser</title>
165
<p>Whenever a table shall be opened, the first step is to choose the corresponding
166
<em>Table Name</em> or <em>Table ID</em> cell. Secondly, the <em>Open Table</em>
167
menu item, in the <em>File</em> menu, has to be chosen. (Or, one may directly
168
double-click on a <em>Table Name</em> or <em>Table Id</em> cell.)</p>
169
<p>If the table selected table is readable, a window will appear after a short delay. This new
170
window is hereafter denoted the <em>Table Browser</em> window. Should the table be
171
unreadable, the Table Information window will appear instead (see further description
176
<title>The Table Browser Window</title>
177
<p>The Table Browser window consists of:</p>
178
<list type="bulleted">
180
<p>a <em>menubar</em>.</p>
183
<p>a <em>toolbar</em> with buttons providing shortcuts to the menubar options. If the
184
cursor rests on any button, a so-called toolbar tip, explaining the button,
185
will appear. <br></br>
187
(In the picture below, the cursor has lingered on the <em>Open Table</em>
188
button for a while.)</p>
191
<p>a <em>content and edit field</em>, showing the content of a specified row or cell.
192
Through this field the row, or cell, may also be edited (see below for a detailed
196
<p>a <em>grid</em>, i.e., a multicolumnar array, where the content of the
197
opened table will be shown. (As above, each square in the grid is called a cell.</p>
200
<image file="tv_table_browser">
201
<icaption>The Table Browser Window.</icaption>
203
<p>The successful appearance of the Table Browser window means that an image of
204
the selected table has been created in the TV. It is this image
205
that is shown in the Table Browser.
209
<title>How Table Data Is Presented</title>
210
<p>Each object in the table is presented on a row of its own in the grid.
211
Each element in the object is presented in a cell of its own. <br></br>
213
The colours on the <em>vertical</em> buttons to the left of the grid show the status
214
of the object on that very row: a bright red colour indicates that the object just
215
has been inserted (when the table is opened, all objects are regarded as being
216
just inserted), while a bright green colour indicates that the object has been
217
changed. The colour fades away, shade by shade, every time the actual table is polled,
218
until the normal background colour is encountered. <br></br>
220
When an object has been deleted, the colour of the corresponding
221
<em>vertical button</em> turns to black. The next time the table is polled, the
222
object will be removed from the grid.</p>
223
<image file="tv_table_browser_updated">
224
<icaption>The Table Browser Window, with new, changed, and deleted objects.</icaption>
226
<p>Normally, new objects are placed at the end of the grid, while all other objects
227
maintain their positions between successive polls. However, when sorting mode has
228
been ordered, all objects, even new ones, are placed at the correct position
229
according to the sorting ordered (see also below).</p>
230
<p>Immediately above the <em>horizontal buttons</em>, one or more <em>keys</em> may
231
appear. These keys indicates which elements that are used as indices in the
232
ETS/Mnesia table, i.e., which fields that are used by ETS/Mnesia as search keys when
234
<p>The grid columns may be resized, by clicking and dragging on the small black <em>resize areas</em> between any two horizontal buttons.</p>
235
<p>The rows are enumerated, as a help when navigating through the table. Note: it shall
236
not be assumed that these numbers correspond to the placement of the objects in the
237
<em>actual table</em>! The row numbers, as presented in the TV, are
238
only temporary, and only valid within the TV!
241
The number on the <em>vertical scrollbar</em> corresponds to the number the
242
uppermost row has (or will have).</p>
243
<p>The number shown on the horizontal scrollbar relates to the leftmost column shown.</p>
247
<title>How to Poll the Table</title>
248
<p>The table is polled whenever the <em>Poll Table</em> option in the <em>Options</em>
249
menu is chosen (or the <em>Poll Table</em> toolbar button is pressed). <br></br>
251
The user may also choose to let the TV poll the table at regular
252
intervals. This is done via the <em>Set Poll Interval...</em> option in the
253
<em>Options</em> menu, which causes the <em>Set Poll Interval window</em> to appear. </p>
254
<p>In the Set Poll Interval window the user selects whether manual or automatic
255
polling shall be used, and, in the automatic polling case, the poll interval.</p>
256
<image file="set_poll_int">
257
<icaption>The Set Poll Interval Window.</icaption>
259
<p>It shall be noted that, in the case of a large table (or a slow computer/operating
260
system), a short poll interval may cause the TV to be flooded, i.e., the
261
data resulting from one poll has not been fully treated and presented when the data from
262
the next poll arrives. The user is therefore kindly requested to use the automatic
263
polling facility with care!</p>
267
<title>How to Edit Objects in the Table</title>
268
<p>Provided that the table is writable for other processes than the owning process,
269
the user may insert, change and delete objects.</p>
270
<p>To <em>delete</em> an object, the corresponding row, or a single cell in the
271
corresponding row, has to be chosen, by clicking either on the vertical button
272
to the left of the row, or on a cell. Thereafter the <em>Delete Object</em>
273
option in the <em>Edit Menu</em>
274
is chosen. (Should the user regret the delete operation, the row may once again
275
be selected, whereupon the <em>Return</em> button simply is pressed.)</p>
276
<p>To <em>insert</em> an object, the user may use the <em>Record Editor</em>, or simply
277
enter the object in the content and edit field, and then press the <em>Return</em>
280
The <em>Record Editor</em> is started via the <em>Edit Object</em> option in the
281
<em>Edit</em> menu, or via the <em>Edit Object</em> toolbar button. The editor that
282
appears looks different depending on the kind of table: for Mnesia tables,
283
a writable field is shown for each record entry, as well as the name of the entry.
284
For ETS tables, only a writable field is shown; this is due to the fact that the
285
size of the tuples inserted in ETS tables may vary, whereas the size of the records
286
inserted in a Mnesia table (more or less) is fixed.
287
One may select the next field in the record editor by pressing
288
the 'Tab' (or 'Arrow Down') button, and select the previous field by pressing
289
'Shift'+'Tab' (or 'Arrow Up'). <br></br>
291
When the editing is finished, the <em>OK</em> button may be clicked, or
292
'Return' pressed. The TV will then try to insert the new object.
294
<image file="tv_record_editor_mnesia">
295
<icaption>The Record Editor (shown for a Mnesia table).</icaption>
297
<p>To <em>change</em> an already existing object, the corresponding row, or a single cell
298
in the corresponding row, has to be selected first (see below). Then one may edit the
299
whole object (or the selected field in the object), either using the record editor
300
or the content and edit field, whereupon 'Return' may be pressed (or the 'OK' button
303
<p>It shall be noted that it is hard to edit objects containing
304
<em>process identifiers</em>, <em>references</em>, <em>binaries</em> and <em>ports</em>,
305
since it is only a textual representation of these terms that is shown on the screen.
306
It is in the general case impossible for the TV to correctly
307
convert this textual representation back to the original term. As a courtesy to
308
the user, an attempt to do this will nevertheless be done if the edited field
309
consists of a single process identifier; however, this conversion will only be
311
that the process identifier originates from the current Erlang session. (On
312
the other hand, why on earth should any user want to store old process identifiers?)
314
<p>It shall also be noted that it may be more or less confusing to edit the table,
315
depending on whether the table type is <em>set</em>, <em>bag</em>, or
316
<em>duplicate_bag</em>, i.e., depending on whether or not objects having the
317
same key (or even duplicate objetcts) are allowed. Please study the ETS or Mnesia
318
manual pages, should confusion arise!
323
<title>How to Search For Objects</title>
324
<p>One may search for an object, by choosing the <em>Search Object</em>
325
option in the <em>Options</em> menu (or by pressing the <em>Search Object</em>
326
toolbar button). In the <em>Search Object window</em> that appears, any valid
327
Erlang term or regular expression may be entered, whereupon all objects
328
containing (or consisting of) this term, or matching the regular expression,
330
<image file="tv_search_window">
331
<icaption>The Search Object Window.</icaption>
333
<p>In the search result list, by clicking on any object, the Table Browser will
334
immediately scroll to the corresponding row in the table shown. This enables
335
the user to in a very powerful way quickly find the objects he's interested in.</p>
336
<image file="tv_search_result">
337
<icaption>The Search Object Window interworking with the Table Browser.</icaption>
342
<title>How to Mark Table Data</title>
343
<p>One may mark a row or a column by clicking on the buttons to the left and above
344
the grid, respectively. A single cell is marked by clicking on it. Even empty
345
rows and columns may be marked; an empty cell cannot be marked - on the contrary,
346
by clicking on an empty cell, all marks are removed.</p>
347
<p>Marks are indicated by a cyan blue colour.</p>
348
<image file="tv_row_marked">
349
<icaption>The TV Main Window: a row has been marked.</icaption>
351
<p>When a row or a cell has been marked, the content will be shown in the content field,
352
together with an indication of the row (and column when applicable) the marked area
353
corresponds to. Should the object be very big, only a fraction of it may be shown in
354
this field. By clicking on the down-arrow button to the right of the content and
355
edit field, a pop-up content field will be shown, where the whole marked object
356
may be viewed. The content of this pop-up field may be marked and copied to
357
other windows; however, this field cannot be edited.</p>
358
<image file="tv_row_marked_popup">
359
<icaption>The Table Browser: the pop-up content field.</icaption>
361
<p>It shall be noted that the user may choose whether lists shall be shown as
362
strings or lists; this is done via the <em>View</em> menu.
364
<p>A marked column may be subject to sorting, see below. When sorting is ordered,
365
marks are removed at each polling of the table (because of the difficulties to
366
keep track of a certain object, or element, in this case).</p>
370
<title>How to Sort Table Data</title>
371
<p>The image of the table may be sorted in rising or falling order, using any element as
372
sorting key. The element desired is chosen by marking the corresponding column, and
373
then choose (either via the <em>Options</em> menu, or via the toolbar buttons) any
374
of the sorting options available, i.e., sorting in ascending or descending order.
375
The colour of the column button will then change to gold, to indicate that this
376
column is the basis for the sorting currently chosen.</p>
377
<p>Should no column have been marked, when sorting is ordered, the first element in each
378
object (i.e, tuple) will be used as sorting key if the table is an ETS table; the
379
second element (i.e., the first field in the record) will be used if the table is a
381
<p>Even columns with no elements in them may be subject to sorting. In this case the
382
whole object is used as the sorting key.</p>
383
<p>When sorting is ordered, new elements will be inserted according to the current
384
sorting mode. When the sorting is interrupted (via the <em>No Sorting</em> option),
385
the current image of the table keep the current order, but new elements will from
386
now on once again be inserted at the end of the image of the table.</p>
390
<title>How to Obtain Table Information</title>
391
<p>Information about the actual table is obtained via the <em>File</em> menu (or via the
392
<em>Table Info</em> toolbar button). The information is printed in a separate window,
393
with similar pieces of information grouped together on "flap cards" of their own.
394
By clicking on a flap, the information on the corresponding card is made visible.</p>
395
<image file="info_window">
396
<icaption>The Table Information Window, showing information about a Mnesia table.</icaption>
398
<p>The Table Information window may also be opened from the TV Main
399
Window, by selecting a table and then choose the <em>Table Info</em> option
400
in the <em>File</em> menu (or by double-clicking on the <em>Table Size</em>
402
<p>Note: The Table Information window will automatically be opened if the user tries
403
to open an unreadable table, since this is the only information available in this
409
<title>The Table Browser Menus</title>
410
<p>The Table Browser offers the following menus:</p>
414
<title>The File Menu</title>
416
<tag><em>Table Info</em></tag>
418
<p>Opens the Table Information window, which shows the available information
419
about the current table. </p>
421
<tag><em>Close</em></tag>
423
<p>Closes the Table Browser window.</p>
429
<title>The Edit Menu</title>
431
<tag><em>Edit Object...</em></tag>
433
<p>Opens the Record Editor. If an object is marked, it will be shown in
434
the Record Editor.</p>
436
<tag><em>Delete Object</em></tag>
438
<p>Deletes a marked object.</p>
444
<title>The View Menu</title>
446
<tag><em>Lists As Lists</em></tag>
448
<p>Causes lists in the table to be shwon as lists.</p>
450
<tag><em>Lists As Strings</em></tag>
452
<p>Causes lists in the table to be shown as strings.</p>
458
<title>The Options Menu</title>
460
<tag><em>Poll Table</em></tag>
462
<p>An explicit order to poll the table, i.e., to scan the content.</p>
464
<tag><em>Poll Interval...</em></tag>
466
<p>Choose between manual and automatic polling. In the case of automatic
467
polling, the user gets the opportunity to choose the polling interval.</p>
469
<tag><em>Search Object</em></tag>
471
<p>Enables search for objects containing (or consisting of) a specified
472
Erlang term, or matching a regular pattern. The search result may be used
473
for quick navigation in the table.</p>
475
<tag><em>Sort Ascending Order</em></tag>
477
<p>Shows the table content sorted in ascending (i.e., rising) order.
478
New objects will be shown with correct placement as long the as the sorting
479
is going on. <br></br>
481
Please note that it is only the image of the table that is affected,
482
<em>not</em> the table itself!</p>
484
<tag><em>Sort Descending Order</em></tag>
486
<p>Shows the table content sorted in descending (i.e., falling) order.
487
New objects will be shown with correct placement as long the as the
488
sorting is going on.</p>
490
<tag><em>No Sorting</em></tag>
492
<p>Sorting mode is left. New objects will be shown last in the
493
table. However, older objects will remain in the position they had when
494
the sorting mode was left, i.e., their placement will not reflect their
495
actual placement in the ETS/Mnesia table.</p>
501
<title>The Help Menu</title>
503
<tag><em>Help</em></tag>
505
<p>Shows the help (about TV usage) that is available.
506
(The help will be shown in the Netscape Internet browser, if available.)</p>
508
<tag><em>OTP Documentation</em></tag>
510
<p>Shows the Documentation about all OTP components that is available
511
in the local installation of OTP.</p>
519
<title>Tracing the Owner Process</title>
520
<p>The process owning the table may easily be traced, by selecting either
521
the <em>Owner Pid</em> or the <em>Owner Name</em> field, and then choosing
522
the <em>Trace Process</em> option in the <em>File</em> menu. <br></br>
524
(It is also possible to double-click on any of these fields.)</p>
528
<title>Creating a New Table</title>
529
<p>A new table may easily be created using the <em>New Table window</em>.
530
Currently only ETS tables may be created. Since ETS tables
531
dies together with the parent process, a special process, registered
532
as <em>tv_table_owner</em>, will be the owner of tables created this way.
533
This process will not be affected by any termination of the TV,
534
i.e., the ETS tables created will live on until they are explicitly killed.
536
<image file="tv_create_table">
537
<icaption>The New Table Window, enabling easy creation of ETS tables.</icaption>
539
<p>Note: the <em>tv_table_owner</em> is local to each node, meaning
540
that the creation of a table on a new node also will start such a process
541
on that node. This way only the tables on a specific node dies, should that
542
specific node crash.</p>
546
<title>The TV Main Window Menus</title>
547
<p>The Main Window offers the following menus:</p>
551
<title>The File Menu</title>
553
<tag><em>Open Table</em></tag>
555
<p>Open a selected table in a new Table Browser.</p>
557
<tag><em>New Table</em></tag>
559
<p>Open the New Table window, enabling easy creation of ETS tables.</p>
561
<tag><em>Table Info</em></tag>
563
<p>Opens the Table Information window, showing the available
564
information about a selected table. </p>
566
<tag><em>Nodes...</em></tag>
568
<p>Open the Connected Nodes window, enabling the user to view
569
tables residing on remote nodes.</p>
571
<tag><em>Trace Process</em></tag>
572
<item>Opens a trace window, where the process owning a selected table can
574
<tag><em>Exit</em></tag>
576
<p>Terminates the TV.</p>
582
<title>The View Menu</title>
584
<tag><em>ETS Tables</em></tag>
586
<p>Shows ETS tables on the current node.</p>
588
<tag><em>Mnesia tables</em></tag>
590
<p>Shows Mnesia tables on the current node.</p>
596
<title>The Options Menu</title>
598
<tag><em>Refresh</em></tag>
600
<p>An explicit order to once again check the current node for existing
601
tables, and list them.</p>
603
<tag><em>Unreadable Tables</em></tag>
605
<p>Option to choose whether or not unreadable tables shall be shown.</p>
607
<tag><em>System Tables</em></tag>
609
<p>Option to choose whether or not system tables shall be shown.</p>
611
<tag><em>Sort by Name</em></tag>
613
<p>Shows the tables sorted by their names.</p>
615
<tag><em>Sort by Id</em></tag>
617
<p>Shows the tables sorted by their table identifiers.</p>
619
<tag><em>Sort by Owner PID</em></tag>
621
<p>Shows the tables sorted by the process identifiers of the owning
624
<tag><em>Sort by Owner Name</em></tag>
626
<p>Shows the tables sorted by the registered names of the owning processes.</p>
628
<tag><em>Error Messages in Haiku</em></tag>
630
<p>Option to choose whether or not error messages shall be shown
631
in the Japanes poetry style called <em>Haiku</em>.</p>
637
<title>The Help Menu</title>
639
<tag><em>Help</em></tag>
641
<p>Shows the help (about TV usage) that is available.
642
(The help will be shown in the Netscape Internet browser, if available.)</p>
644
<tag><em>OTP Documentation</em></tag>
646
<p>Shows the Documentation about all OTP components that is available
647
in the local installation of OTP.</p>
added
removed
lib/tv/doc/src/table_visualizer_chapter.xml
