1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<!-- $Id: moodss.htm,v 1.107 2005/02/22 18:41:58 jfontain Exp $ -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Jean-Luc Fontaine">
<meta name="Description" content="user manual for using moodss">
<title>moodss (Modular Object Oriented Dynamic SpreadSheet)</title>
</head>
<body bgcolor="#FFFFFF" style="font-family: helvetica, verdana, arial">
<center><h1>moodss</h1></center>
<center><h2>(Modular Object Oriented Dynamic SpreadSheet)</h2></center>
<h3>Contents:</h3>
<!-- beginning of contents -->
<ul>
<li><a href="#about">1. About this document</a>
<li><a href="#introduction">2. Introduction</a>
<li><a href="#required">3. Installation</a>
<li><a href="#architecture">4. Architecture</a>
<li><a href="#userinterface">5. User interface</a><ul>
<li><a href="#tables">5.1. Tables</a>
<li><a href="#viewers">5.2. Viewers</a><ul>
<li><a href="#viewers.graphs">5.2.1. Graphs</a>
<li><a href="#viewers.bars">5.2.2. Bars</a>
<li><a href="#viewers.pies">5.2.3. Pies</a>
<li><a href="#viewers.tables">5.2.4. Tables</a>
<li><a href="#viewers.text">5.2.5. Text</a>
<li><a href="#viewers.iconic">5.2.6. Iconic</a>
<li><a href="#viewers.formulas">5.2.7. Formulas</a><ul>
<li><a href="#viewers.formulas.expressions">5.2.7.1. Expressions</a>
<li><a href="#viewers.formulas.editing">5.2.7.2. Editing</a>
<li><a href="#viewers.formulas.tables">5.2.7.3. Tables</a>
</ul>
<li><a href="#viewers.examples">5.2.8. Examples</a>
</ul>
<li><a href="#titlebar">5.3. Title bar</a>
<li><a href="#menus">5.4. Menu bar</a><ul>
<li><a href="#menus.file">5.4.1. File</a><ul>
<li><a href="#menus.file.new">5.4.1.1. New</a>
<li><a href="#menus.file.open">5.4.1.2. Open</a>
<li><a href="#menus.file.save">5.4.1.3. Save</a>
<li><a href="#menus.file.saveas">5.4.1.4. Save as</a>
<li><a href="#menus.file.modules">5.4.1.5. Modules</a><ul>
<li><a href="#menus.file.modules.load">5.4.1.5.1. Load</a>
<li><a href="#menus.file.modules.manage">5.4.1.5.2. Manage</a>
<li><a href="#menus.file.modules.loaded">5.4.1.5.3. Loaded</a>
</ul>
<li><a href="#menus.file.database">5.4.1.6. Database</a><ul>
<li><a href="#menus.file.database.load">5.4.1.6.1. Load</a>
<li><a href="#menus.file.database.start">5.4.1.6.2. Start</a>
<li><a href="#menus.file.database.stop">5.4.1.6.3. Stop</a>
</ul>
<li><a href="#menus.file.print">5.4.1.7. Print</a>
<li><a href="#menus.file.exit">5.4.1.8. Exit</a>
</ul>
<li><a href="#menus.edit">5.4.2. Edit</a><ul>
<li><a href="#menus.edit.thresholds">5.4.2.1. Thresholds</a><ul>
<li><a href="#menus.edit.thresholds.types">5.4.2.1.1. Types</a>
<li><a href="#menus.edit.thresholds.color">5.4.2.1.2. Color</a>
<li><a href="#menus.edit.thresholds.script">5.4.2.1.3. Script</a>
<li><a href="#menus.edit.thresholds.dragging">5.4.2.1.4. Dragging</a>
<li><a href="#menus.edit.thresholds.notes">5.4.2.1.5. Notes</a>
</ul>
<li><a href="#menus.edit.configuration">5.4.2.2. Dashboard configuration</a>
<li><a href="#menus.edit.newpage">5.4.2.3. New page</a>
<li><a href="#menus.edit.newviewer">5.4.2.4. New viewer</a>
<li><a href="#menus.edit.database">5.4.2.5. Database</a>
<li><a href="#menus.edit.preferences">5.4.2.6. Preferences</a>
</ul>
<li><a href="#menus.view">5.4.3. View</a><ul>
<li><a href="#menus.view.refresh">5.4.3.1. Refresh</a>
<li><a href="#menus.view.polltime">5.4.3.2. Poll Time</a>
<li><a href="#menus.view.database.range">5.4.3.3. Database range</a>
<li><a href="#menus.view.trace">5.4.3.4. Trace</a>
<li><a href="#menus.view.toolbar">5.4.3.5. Tool bar</a>
</ul>
<li><a href="#menus.help">5.4.4. Help</a><ul>
<li><a href="#menus.help.global">5.4.4.1. Global</a>
<li><a href="#menus.help.modules">5.4.4.2. Modules</a>
<li><a href="#menus.help.about">5.4.4.3. About</a>
</ul>
</ul>
<li><a href="#toolbar">5.5. Tool bar</a>
<li><a href="#canvasarea">5.6. Canvas area</a>
<li><a href="#pagetabs">5.7. Page tabs</a>
<li><a href="#message">5.8. Message</a>
<li><a href="#messagesarea">5.9. Messages area</a>
<li><a href="#draganddrop">5.10. Drag and drop</a><ul>
<li><a href="#dropsites">5.10.1. Drop sites</a>
<li><a href="#dragsites">5.10.2. Drag sites</a>
</ul>
<li><a href="#internationalization">5.11. International languages</a>
</ul>
<li><a href="#commandline">6. Command line</a><ul>
<li><a href="#mainarguments">6.1. Main arguments</a>
<li><a href="#modulearguments">6.2. Module arguments</a>
</ul>
<li><a href="#core.configuration">7. Dashboard configuration</a><ul>
<li><a href="#configuration.application">7.1. Application</a><ul>
<li><a href="#configuration.application.size">7.1.1. Size</a>
<li><a href="#configuration.application.background">7.1.2. Background</a>
</ul>
<li><a href="#configuration.viewers">7.2. Viewers</a><ul>
<li><a href="#configuration.viewers.colors">7.2.1. Colors</a>
<li><a href="#configuration.viewers.graphs">7.2.2. Graphs</a>
<li><a href="#configuration.viewers.pies">7.2.3. Pies</a>
<li><a href="#configuration.viewers.tables">7.2.4. Tables</a>
<li><a href="#configuration.viewers.cells">7.2.5. Cells</a>
</ul>
</ul>
<li><a href="#core.preferences">8. Preferences</a><ul>
<li><a href="#preferences.application">8.1. Application</a><ul>
<li><a href="#preferences.application.size">8.1.1. Size</a>
<li><a href="#preferences.application.colors">8.1.2. Colors</a>
<li><a href="#preferences.application.fonts">8.1.3. Fonts</a>
<li><a href="#preferences.application.printing">8.1.4. Printing</a>
<li><a href="#preferences.application.pages">8.1.5. Pages</a>
<li><a href="#preferences.application.database">8.1.6. Database</a>
<li><a href="#preferences.application.trace">8.1.7. Trace</a>
</ul>
<li><a href="#preferences.viewers">8.2. Viewers</a><ul>
<li><a href="#preferences.viewers.colors">8.2.1. Colors</a>
<li><a href="#preferences.viewers.graphs">8.2.2. Graphs</a>
<li><a href="#preferences.viewers.pies">8.2.3. Pies</a>
<li><a href="#preferences.viewers.tables">8.2.4. Tables</a>
<li><a href="#preferences.viewers.cells">8.2.5. Cells</a>
</ul>
<li><a href="#preferences.thresholds">8.3. Thresholds</a><ul>
<li><a href="#preferences.thresholds.email">8.3.1. Email</a>
<li><a href="#preferences.thresholds.trace">8.3.2. Trace</a>
</ul>
<li><a href="#preferences.moomps">8.4. Daemon (moomps)</a>
</ul>
<li><a href="#future">9. Future developments</a>
<li><a href="#support">10. Support</a>
<li><a href="#misc">11. Miscellaneous information</a>
</ul>
<!-- end of contents -->
<h3><a name="about"></a>1. About this document</h3>
<p>This document contains general information, reference information and examples designed to help the user understand the moodss application.
<h3><a name="introduction"></a>2. Introduction</h3>
<p>Quite often, one needs to monitor changing data, whether it comes from a system, such as the different processes running on a UNIX server, or from a network, such as the volume and distribution of traffic that runs through it.
<p>Most often, such data can be organized in a table with rows of information, each column representing a different kind of data. For example, in the case of processes running on a computer system, rows might be sorted according to their unique process identifier, with columns containing values such as CPU usage, memory usage, owner's name, time of creation, ...
<p>The software used to view this type of information comes in different forms and shapes. UNIX users might be familiar with the <i>top</i> application which presents rows of process data as lines of text, whereas RMON (Remote MONitoring) SNMP software usually uses multiple windows with graphical displays, curves, pie charts, multiple configuration dialog boxes, even 3D visualization modules to visualize network traffic, connection matrices, ...
<p>In most cases, data comes from one or more tables. A common interface, graphical with menus, drag'n'drop capability, table widgets, textual and graphical data viewers such as multiple line graphs, bar and pie charts, could be used. The user could then sort table rows, select one or more cells, rows, columns, create views such as other tables, charts, ... best suited to the way data should be presented. Once optimized, the data viewers layout and configuration could be saved for later reuse as a dashboard. In effect, what is needed is a spreadsheet tailored to dynamic data processing.
<p>Moodss (Modular Object Oriented Dynamic SpreadSheet) is an attempt at filling these needs. It is composed of a main part (the core) and an unlimited number of modules, loaded as the application is launched or while it is running, each module interfacing to a specific type of data. The core is written in the Tcl language (at <a href="http://www.tcl.tk/">http://www.tcl.tk/</a>) using object oriented techniques thanks to the stooop package (at <a href="http://jfontain.free.fr/">http://jfontain.free.fr/</a>). The module function is to describe the data that it is also in charge of retrieving and formatting. Modules can be written in a scripting language (Tcl, Perl or Python) or use dynamically linked libraries written in the C language (modules are packages in the Tcl sense, so any language that can interface with Tcl is supported).
<p><b>Main features</b>:<ul>
<li>modular architecture: any number of modules can be concurrently loaded to monitor any sort of data (<i>system</i>, <i>database</i> (<i>MySQL</i>), <i>network</i>, <i>hardware</i>, ...) on local or remote systems
<li>user friendly graphical interface with full drag'n'drop functionality and complete context sensitive help
<li>powerful threshold functionality: no limits on the number of thresholds, email alerts with screen shots and multiple SMTP servers, user script launching, importance level compatible with the UNIX syslog facility
<li>powerful formula facility: mathematical formulas can be constructed using data cells from any module, even from other formulas, and can be used as any other data, in graphical viewers, archived in database, ...
<li>very flexible display organization with unlimited number of notebook type pages
<li>dashboards can be constructed from any number of modules, with graphical viewers (<i>graphs</i>, <i>bar charts</i>, <i>pies</i>, ...) and thresholds easily created by drag'n'drop, all saved in a loadable file
<li>specific modules can easily be developed using a scripting language (<i>Tcl</i>, <i>Perl</i> or <i>Python</i>) or in <i>C</i>
<li>saved dashboards are fully compatible with the associated <i>moomps</i> daemon for background monitoring
<li>any number of data cells histories over time can be stored in a SQL database
<li>multiple platforms support: all <i>UNIX</i>, <i>Linux</i>, <i>BSD</i> based machines and <i>Windows</i>
<li>threshold alerts forwarded by email to one or more administrators
<li>modules for the <i>MySQL</i> database server feature:<ul>
<li>monitor as many servers (such as replicated) as you wish, on the same dashboard
<li>native connection to the database servers or via <i>ODBC</i>
<li>performance, statistics and errors monitoring
<li>monitor servers residing on any <i>MySQL</i> supported platforms (<i>UNIX</i>, <i>Windows</i>, ...) can be combined with host system monitoring (<i>cpustats</i>, <i>memstats</i>, <i>mounts</i>, ...), network monitoring (<i>snmp</i>, <i>snmptrap</i>, ...) and web server monitoring (<i>apache</i>, <i>apachex</i>, ...) to construct a site wide monitoring station
</ul>
</ul>
<p>Modules are loaded when moodss is started or dynamically at a later time, and can be unloaded at any time. Any number of modules can be handled concurrently. This way, you may monitor data coming from any number of heterogeneous sources.
<p>Since module data access is entirely customizable (through C code, Perl, Python, Tcl, HTTP, ...) and since several modules can be loaded at once, applications for moodss become limitless. For example, comparing a remote database server CPU activity and traffic load from a network probe on the same graph becomes possible.
<p>As features are added to moodss, different ways of viewing data will be made available while the module structure will stay the same. The goal of moodss is to become a nice feature packed generic way of monitoring any device. Moodss can be used to monitor any type of data, since the simplest cases can fit in one table with a single row, with the most complicated requiring loading several multiple table modules.
<p>As moodss is written in Tcl and uses well supported extensions (Tktable and BLT), it will run on Tcl/Tk supported platforms: UNIX type, Windows (with less features, such as the moomps daemon) and Apple OS/X (not tested yet). Obviously, some modules may be specific to a platform, but the core is guaranteed to run on them all.
<p>After reading and understanding this document, you should be able to build your own dashboards in order to monitor the data that you are interested in.
<p>Moodss is free software. You can redistribute it and modify it under the terms described in the COPYRIGHT file.
<h3><a name="required"></a>3. Installation</h3>
<p>For a quick, hassle-free try, if you are using a Linux system, download and install the standalone <a href="http:/jfontain.free.fr/moodss-19.7.i386.tar.bz2">binary</a>, complete with all required software, which installs in a sub-directory:
<pre>$ tar -xjf moodss-19.7.i386.tar.bz2 # unpack it
$ moodss-19.7/moodss.sh cpustats memstats # now use it
$ rm -rf moodss-19.7/ # remove it</pre>
<p>For a permanent installation, if you are using a Linux Red Hat or Fedora system (7.0 or above), then use the moodss rpm file (available at <a href="http://moodss.sourceforge.net/">http://moodss.sourceforge.net/</a>) for installation. It requires the tcl, tk, blt, tktable and sqlite rpms also referenced at the same location.
<br>In any case, for UNIX type platforms, read the INSTALL file, included in the distribution tarball.
<p>For Windows platforms, read the install.txt file, included in the zip distribution.
<p>For the current version (19.7), the following packages must be installed before attempting to install moodss:<ul>
<li>Tcl/Tk version 8.3.1 or above (at <a href="http://tcl.sourceforge.net/">http://tcl.sourceforge.net/</a>)
<li>tkTable version 2.7 or above (at <a href="http://tktable.sourceforge.net/">http://tktable.sourceforge.net/</a>)
<li>the latest BLT library version 2.4z or above (at <a href="http://sourceforge.net/projects/blt/">http://sourceforge.net/projects/blt/</a>)
</ul>
<p>If you want to use the optional database archiving and history browsing features, one or more of the following packages can be used:<ul>
<li>mysqltcl package (at <a href="http://www.xdobry.de/mysqltcl/">http://www.xdobry.de/mysqltcl/</a>) for the MySQL database with connection via the native MySQL protocol
<li>sqlite file based SQL library at <a href="http://www.hwaci.com/sw/sqlite/">http://www.hwaci.com/sw/sqlite/</a>
<li>tclodbc package (at <a href="http://tclodbc.sourceforge.net/">http://tclodbc.sourceforge.net/</a>) for MySQL, PostgreSQL, Oracle, DB2, ... with connection via ODBC (Open DataBase Connectivity)
</ul>
<p>The XML, DOM, BWidget, pie widgets, stooop and scwoop libraries are included in the self contained <i>moodss</i> application file. Therefore, it is not required to install the tclXML, tclDOM, BWidget, stooop, scwoop and tkpiechart packages, unless you want to work on the moodss source code itself. However, should you want to get more information on those extensions, you will find the latest versions:<ul>
<li>stooop version 4.1 or above
<li>switched version 2.2 or above (included in the stooop distribution)
<li>scwoop version 4.0 or above
<li>tkpiechart version 6.1 or above
</ul>
at <a href="http://jfontain.free.fr/">http://jfontain.free.fr/</a>:<ul>
<li>BWidget version 1.7 or above
</ul>
at <a href="http://tcllib.sourceforge.net/">http://tcllib.sourceforge.net/</a>, and:<ul>
<li>tclXML version 2.6 or above
<li>tclDOM version 2.6 or above
</ul>
at <a href="http://tclxml.sourceforge.net/">http://tclxml.sourceforge.net/</a>.
<p>Finally, if you want to develop your own modules in a language other than Tcl, such as Perl or Python, you will need:<ul>
<li>tclperl library
<li>tclpython library
</ul>
also at <a href="http://jfontain.free.fr/">http://jfontain.free.fr/</a>.
<h3><a name="architecture"></a>4. Architecture</h3>
<p>The moodss application is composed of the core software and one or several modules.
<p>The core loads one or more modules, whose names are passed as command line parameters, come from a dashboard file or are dynamically loaded, and starts displaying module data in one or more tables. The tables are then updated at the frequency defined by the poll time, which the user may change, or asynchronously for the relevant modules. For example, to launch moodss with the random module, just type (on a UNIX machine):
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ moodss random
</pre></td><tr></table>
<p>The initial data tables represent the first data views, from which any number of cells can be selected. Data viewers can be created by dragging and dropping cells into a graph, bar chart, pie chart, statistics and values tables, free text or thresholds sites. In turn, these viewers can display more table cells, which when dropped into the viewer, result in the creation of corresponding data graph lines, chart bars, pie slices, table rows or text cells. Cells or rows can be removed from existing viewers, by simply selecting them and dropping them in the eraser iconic site (in the shape of a pencil eraser).
<p>Formulas tables are a special kind of viewer. They are created from the <a href="#menus.edit.newviewer">Edit/New viewer</a> menu and a specific dialog box. Once created though, they behave as other viewers, and allow dragging formula cells (the result of the formula represented as a single value) into any other viewer or drop site.
<p>Any viewer can be mutated (its type changed) by dragging from a viewer icon and dropping into it. For example, create a stacked data bar viewer from several cells, then drag the 3D pie icon into it. Any viewer can also be destroyed in one shot by dropping the eraser icon into it.
<p>Any draggable data can be dropped in any valid drop site at any time. It is thus possible to drag several data cells from any table or any viewer into other ones, the thresholds interface, the eraser, ... even if the data comes from different modules.
<p>All data viewers can be moved and resized at will with the help of a simple internal window manager.
<p>The current configuration (existing pages, loaded modules, tables and viewers coordinates, sizes, poll time, main window size, ...), whether in real time mode or database mode, can be saved in a file at any time, so that an identical dashboard can be relaunched at will.
<p>Note that all configuration and preferences data is written to disk in XML 1.0 format, to follow standards, and so it is possible to edit (carefully) using a plain text or specialized editor.
<h3><a name="userinterface"></a>5. User interface</h3>
<p>Immediately after launch, module(s) is(are) loaded and initialized, with corresponding messages displayed in the message area, as follows:
<p><center><img src="moodss5.gif" alt="moodss window view in load mode"></center>
<p>Soon after, tabular data is displayed in one or more tables, between the menu bar, the tool bar, the drop sites with graphical viewers, statistics and values tables, free text, thresholds and eraser icons, pages tabs and a message area, as one can see below:
<p><center><img src="moodss1.gif" alt="moodss initial main window view"></center>
<p>If there are several pages (views), notebook tabs appear below the canvas area (see above).
<p>The message area is used to display status information, such as when the data is being updated, and help information, as the user moves the mouse pointer over sensitive areas, such as table column headers. Contextual help on all menu items is also activated as traversal occurs, either using the mouse or the keyboard, resulting in a short explicative string appearing in the message area and related to the active (highlighted) menu item. Further help is provided through widget tips (also known as balloons) when appropriate (on data table column headers, for example), and of course the Help menu.
<br>The message area header label also serves as a thresholds indicator for all the thresholds activated in the application. The label takes the color of the most important active threshold (according to its importance level). If there are several active thresholds of the same most important level, but with different colors, then the colors are shown in sequence, 1 per second. A widget tip also shows the most important thresholds summaries (also see <a href="#pagetabs">page tabs</a> and <a href="#message">message</a>).
<p>The window title shows the name of the loaded module(s) along with the poll time, if not in database mode.
<p>Various thresholds can also be set on any data cells, as documented in the <a href="#menus.edit.thresholds">thresholds</a> section.
<h4><a name="tables"></a>5.1. Tables</h4>
<p>Tables contain module data and feature the module identifier as title. Scroll bars are displayed when data is not wholly visible.
<p>When several modules of the same type are loaded (for example, CPU statistics on a group of servers), the initial data tables feature the module name followed by an instance number (<i>module<N></i>), or the module identifier generated from the module code (<i>cpustats(host.domain.org)</i> for example). A lone module keeps his unmodified name as table titles.
<p>Note that the title bar changes color to reflect the state of the corresponding module (<i><b>note</b>: feature not yet available for modules written in the Python programming language</i>):<ul>
<li>gray: the module is currently in the process of updating its data (for example, data was requested from a remote machine but has not come back yet).
<li>grayish <font color="green">green</font>: the displayed module data is valid.
<li>grayish <font color="red">red</font>: there was an error during the last update, which may not mean that the data is invalid, as this depends on the module implementation. A corresponding message is available in the <a href="#menus.view.trace">trace</a> window. This color remains displayed until the next update.
</ul>
If a table is minimized, then its icon changes color instead of the title bar, obviously invisible in such a case.
<p>Any data displayed in a table can be sorted (provided that the related module allows it) at any time by simply clicking on a column title. Clicking on the same column title again sorts the data in the opposite order, thus toggling between increasing and decreasing orders.
<br>When sorting, the selected column is used as a reference, meaning that all rows will be rearranged so that the selected column appears sorted, with values either increasing or decreasing.
<br>A little triangular indicator is placed to the right of the reference column title label, pointing up or down depending on whether the sorting order is decreasing or increasing.
<p>If the module allows it (most modules use automatic column sizing), table columns can be interactively resized by holding the first mouse button down on a column border. The mouse cursor is changed to an horizontal double arrow on column borders to show this capability.
<p>Sometimes, data does not completely fit in the cells of the rightmost column of a displayed data table. For example, this often happens when using the <i>log</i> module, where some messages in a UNIX log spool can be very long. In such cases, when the text of the data cell is clipped, moving the mouse cursor over that cell results in a widget tip (balloon), containing the whole cell data, being displayed next to the cell.
<h4><a name="viewers"></a>5.2. Viewers</h4>
<p>Aside from the main tables, graphical and textual viewers can be created for monitoring table cells in real time or deferred time, when in database mode. Viewers can be deleted, data elements (such as pie slices, curves, ...) can be added or removed from existing viewers, ... These functions are all implemented using <a href="#draganddrop">drag and drop</a>.
<p>For all viewers, if a module identifier string is required (provided by the module, several instances of the same module, ...) for proper cell identification, that string will be placed first in the label. For example, data cells originating from the third instance of the random module would be labeled: "<i>random<3>: data cell label</i>".
<p>For graphical viewers (<a href="#viewers.graphs">graphs</a>, <a href="#viewers.bars">bars</a> and <a href="#viewers.pies">pies</a>), it is possible to change the displayed color of the graphical element (curve, bar or slice) used to display the cell data, by clicking with the mouse button 3 on the data cell label. A popup menu is then displayed, containing a set of color choices corresponding to the current viewers <a href="#configuration.viewers.colors">colors</a> configuration.
<br>Picking a color instantaneously changes the color of the displayed element. Such user defined colors are saved in the configuration file and properly restored.
<h5><a name="viewers.graphs"></a>5.2.1. Graphs</h5>
<p>Graph viewers display the history of one or more data cells over some period of time (depending on the poll time and the number of samples, set in <a href="#configuration.viewers.graphs">configuration</a>). In the simple graph viewer, cells data is displayed as curves of different colors, whereas in the stacked graph case, values for each data cell are added to each other and the areas below the curves filled with color (see images below).
<p>When displaying database history data, the graph viewers display all data samples for the selected time range (see <a href="#menus.file.database">database</a> section).
<p>Graph viewers feature an automatic cross hair which follows the mouse pointer movements inside the plotting area. Corresponding coordinates are displayed in the main window message area.
<p><center><table cols=2 width="100%">
<tr align=center valign=center>
<td><img src="hgraph.gif" alt="graph viewer sample"></td>
<td><img src="hstackgr.gif" alt="stacked graph viewer sample"></td>
</tr>
</table></center>
<p>It is possible to set the Y axis (ordinate) maximum value, and also minimum value in the case of the simple graph viewer. These limits can either be fixed or dynamically follow the value of any data cell.
<p>To set a fixed value, click with the mouse button 3 on any part of the viewer to display a popup menu. After selection of the limit type (minimum or maximum), a limit entry zone is created in the upper left corner of the viewer for a maximum value (see pictures above), or in the lower left corner of the plot area for a minimum value.
<br>Just type in the new value, or an empty string if you want to remove the limit value and to restore the default behavior.
<br>By default, the Y axis of a graph automatically scales based on the displayed data values.
<br>Once the limit entry is visible, use the <b>Enter</b> key to validate your choice or the <b>Escape</b> key to cancel the operation.
<br>A small red arrow next to the limit value is used as an indicator that the limit value has been set (see pictures above).
<p>Note that in the case of the fixed minimum, the default for all simple graph viewers can be set to <i>0</i> in the dashboard <a href="#configuration.viewers.graphs">configuration</a> or <a href="#core.preferences">preferences</a> dialog boxes.
<p>To set a dynamic value, drop any data cell in the upper left corner of the viewer for a maximum value, or in the lower left corner of the plot area for a minimum value. The drop area then materializes a small rectangle with black borders. Drop the data cell and from then on, its value is used as the dynamic limit of the viewer.
<br>To change the dynamic value, you may drop another data cell as a replacement, or change to a fixed value as described above, or delete the dynamic limit data cell by entering an empty fixed value.
<p>If the minimum and maximum limits are incompatible (with for example the minimum value being greater than the maximum value), both limit values are displayed in red, and the limits remain as previously available.
<p>When placing the mouse cursor in the upper or lower left corner of the viewer, a help tip is displayed showing the current state of the limit for the viewer (either none set, fixed value set or dynamic value with the name of the data cell used).
<p>Also available in the popup menu is the ability to choose the position of labels of data cells, from the <b>Labels</b> sub-menu. The available positions are <b>Right</b>, <b>Bottom</b>, <b>Left</b> and <b>Top</b>, all relative to the graphical part of the viewer.
<br>The default position can be set from the <a href="#configuration.viewers.graphs">configuration</a> or <a href="#core.preferences">preferences</a> dialog boxes.
<p>It is possible, from the popup menu, to toggle the display of a <b>grid</b> in the plot area, with the default state being set from the <a href="#configuration.viewers.graphs">configuration</a> or <a href="#core.preferences">preferences</a> dialog boxes, where it is also possible to choose a background color for the plot area, or set the angle of the X axis labels (from 45 degrees to the default 90 degrees).
<h5><a name="viewers.bars"></a>5.2.2. Bars</h5>
<p>Bar chart viewers available at this time are side-by-side bars charts, overlapped bars charts and stacked bars charts. In the stacked bars charts case, cells data values are added to each other, whereas in the others, they are displayed next to each other, overlapping or not (see pictures below).
<p>When displaying database history data, the bar chart viewers display the values at the time selected by the right side cursor in the database module instances viewer (see <a href="#menus.file.database">database</a> section).
<p><center><table cols=2 width="100%">
<tr align=center valign=center>
<td><img src="hoverbar.gif" alt="overlap bar chart viewer sample"></td>
<td><img src="hsidebar.gif" alt="side bar chart viewer sample"></td>
<td><img src="hstackbr.gif" alt="stacked bar chart viewer sample"></td>
</tr>
</table></center>
<p>Just as in the graph viewers, it is possible to set the Y axis (ordinate) maximum and minimum (except in the stacked bars chart case) value and the position of the labels of data cells.
<h5><a name="viewers.pies"></a>5.2.3. Pies</h5>
<p>Pie viewers come in 2 types: 2D or 3D. The data cells values can either be placed around the pie area or next to the labels (see <a href="#configuration.viewers.pies">configuration</a>).
<p>In database browsing mode, dynamic values take the values at the latest of the 2 times defined by the cursors (see the <a href="#menus.view.database.range">database range</a> section).
<p><center><table cols=2 width="100%">
<tr align=center valign=center>
<td><img src="h2dpie.gif" alt="2D pie chart viewer sample"></td>
<td><img src="h3dpie.gif" alt="3D pie chart viewer sample"></td>
</tr>
</table></center>
<p>It is possible to fix the total value (corresponding to 100 % of the pie). This limit can either be fixed or dynamically follow the value of any data cell.
<p>To set a fixed value, click with the mouse button 3 on any part of the viewer to display a popup menu. After selection, an entry zone is created in the upper left corner of the viewer (see pictures above).
<br>Just type in the new value, or an empty string if you want to remove the total value and to restore the default behavior.
<br>By default, the slices of a pie automatically scales based on the displayed data values, so that their total always match 100 %.
<br>Once the total entry is visible, use the <b>Enter</b> key to validate your choice or the <b>Escape</b> key to cancel the operation.
<br>A small red arrow next to the total value is used as an indicator that the total value has been set (see pictures above).
<p>To set a dynamic value, drop any data cell in the upper left corner of the viewer. The drop area then materializes a small rectangle with black borders. Drop the data cell and from then on, its value is used as the dynamic total of the viewer.
<br>To change the dynamic value, you may drop another data cell as a replacement, or change to a fixed value as described above, or delete the dynamic limit data cell by entering an empty fixed value.
<p>When placing the mouse cursor in the upper left corner of the viewer, a help tip is displayed showing the current state of the limit for the viewer (either none set, fixed value set or dynamic value with the name of the data cell used).
<h5><a name="viewers.tables"></a>5.2.4. Tables</h5>
<p>The statistics table displays, for each row, the cell label, the current, average, minimum, maximum and standard deviation values, either since the row was created in real-time mode, or over the period delimited by the 2 times defined by the cursors in database mode. (see the <a href="#menus.view.database.range">database range</a> section).
<br><i><b>Note</b>: the <b>standard deviation</b> caracterizes the degree of variance of the data (the standard deviation is defined as the square root of the <b>variance</b>).</i>
<p>Data cells can be inserted one or several at a time through a simple drop. Rows can be deleted by selecting any cell in the row then dropping any number of them into the eraser drop site. Data cells with missing data (could be no longer available if coming from a vanished process, for example) display the ? character. When displaying database history data, the average, minimum, maximum and standard deviation values are calculated for the selected time range.
<p><center><table width="100%">
<tr align=center valign=center>
<td><img src="hsumtbl.gif" alt="statistics table viewer sample"></td>
<td><img src="valuetab.gif" alt="values table viewer sample"></td>
</tr>
</table></center>
<p>The values table displays for each row the cell label and the current values of the cell data. It behaves exactly as the statistics table, but without the average, minimum, maximum and standard deviation columns. It can be used in dashboards to display cells that are hidden when the corresponding module tables are iconified.
<br>In <a href="#menus.file.database.load">database browsing mode</a>, the values table behaves differently: it displays the history of the dropped data cell (there can be only one), which is all the values archived for that data cell within the <a href="#menus.view.database.range">database time range</a>. The number or displayed rows is limited (see <a href="#configuration.viewers.tables">tables configuration</a>). If the data is so truncated, an initial blank row is displayed as an indicator:
<p><center><img src="valuetab2.gif" alt="values table viewer sample in history mode, with data truncation"></center>
<p>Formulas tables are described in the <a href="#viewers.formulas">formulas</a> section.
<h5><a name="viewers.text"></a>5.2.5. Text</h5>
<p>The free text viewer is an editable Tk text widget with any number (including zero) of embedded data cell windows. Data cells can be inserted one or several at a time through a simple drop, as with the other viewers. New data cell windows are inserted at the current insertion cursor position. Data cells can be deleted by selecting then dropping any number of them into the eraser drop site. They can also be deleted using the keyboard Delete and Backspace keys, which also work on the regular text, as well as the expected other key bindings. When dropping data cells, each data cell window is preceded by a relevant label text for the cell, which can later be edited at any time.
<p><center><table width="100%">
<tr align=center valign=center>
<td><img src="hfreetxt.gif" alt="free text viewer sample"></td>
</tr>
</table></center>
<p>When displaying database history data, the displayed values are at the time selected by the right side cursor in the database module instances viewer (see <a href="#menus.file.database">database</a> section).
<h5><a name="viewers.iconic"></a>5.2.6. Iconic</h5>
<p>An iconic viewer is an icon associated with a single data cell, the label and the value of which are displayed underneath the icon, a graphical image in the GIF format, chosen the by user at creation time, and later optionally changed using a popup menu traditionally activated by mouse button 3.
<br>The background color may change according to the thresholds set on the data cell. For example, as shown in the following screen shot, a threshold was set on the hard disk drive temperature, with an orange color when the temperature goes over 40 degrees Celsius.
<p><center><table width="100%">
<tr align=center valign=center>
<td><img src="iconic.gif" alt="iconic viewer sample"></td>
</tr>
</table></center>
<p>Note that, due to the internal implementation, iconic viewers always appear below ant other objects in the work area, such as tables and other viewers. Consequently, when a new iconic viewer is created, it may be hidden by other objects in the upper left corner of the window. However, a black rectangle, of the size of the new viewer, flashes for a brief moment to help spot the location of the new viewer.
<p>An iconic viewer otherwise behaves as other viewers, and may be dragged and dropped, as well as mutated. When it is dropped in another viewer, it snaps back to its original location, once the drop operation is complete. Also note that it is impossible to drop an iconic viewer into another iconic viewer.
<h5><a name="viewers.formulas"></a>5.2.7. Formulas</h5>
<p>Formulas are mathematical expressions that include data cells from any module, and even other formulas tables. For example, the memory usage of a computer in percent can be obtained by dividing the used memory by the available memory and multiplying the result by 100.
<p>Formulas are organized in tables, created via the <a href="#menus.edit.newviewer">Edit/New viewer</a> menu, which triggers the display of the formulas dialog box, also used for editing existing formulas from a formulas table (see <a href="#viewers.formulas.editing">editing</a> below).
<h6><a name="viewers.formulas.expressions"></a>5.2.7.1. Expressions</h6>
<p><b>Note</b>: use the <a href="formulas.htm">formulas documentation</a> for a complete reference on expressions.
<h6><a name="viewers.formulas.editing"></a>5.2.7.2. Editing</h6>
<p>The formulas dialog box (see screen shot below) allows the user to name, document, create and test formulas made from a mathematical expression and several data cells from any loaded module.
<br>The dialog box is displayed at the time the user decides to create a new formulas table, via the <a href="#menus.edit.newviewer">Edit/New viewer</a> menu, or via a popup menu in an existing formulas table.
<p><center><img src="moodss11.gif" alt="formulas dialog box"></center>
<p>Starting from the top, when a formulas table is first created, the user should enter at least the <b>Object</b> that the formulas relate to (for example, a computer name, a network service such as a web site, a database, ...) and possibly the <b>Category</b> of the formulas (system, statistics, errors, network, ...).
<br>These 2 important pieces of information should be as short as possible, and carefully named, as they are used in the title of formulas tables, formulas tables data cells identifiers, and as keywords for archiving formulas results in a <a href="#menus.edit.database">database</a>.
<br>These 2 fields are no longer editable once the formulas table has been created (by validating the contents of the dialog box).
<br><i><b>Note</b>: you can however create another formulas table with modified object and category fields, and transfer the existing formulas to this new table, by drag and drop.</i>
<p>To create a formula, press the <b>New</b> button. A new entry is created in the formulas list and is automatically selected.
<br>Fill in the <b>name</b> of the formula. Carefully choose it as short as possible while remaining meaningful. It is used as the name of the data cell of the result of the formula, which you will be able to drag and drop into viewers, for example (see formulas <a href="#viewers.formulas.tables">tables</a> section below).
<br>Note: the result, or value, or the formula is displayed as <b>?</b> for now, until the expression of the formula is input and eventually tested.
<p>Once the name is determined, you can enter help or comments on the new formula in the <b>Comment</b> section below the current list of formulas. This information will be displayed as a widget tip (or help balloon) when the mouse cursor is left over the formula name in the formulas table (see formulas table screen shot below). You may format the text to your liking and use several lines. This help text can be changed at any time once the formula has been created.
<p>It is now time to create the most important part of the formula: its actual mathematical expression. Go ahead and type <b>1 + 2</b> in the <b>Expression</b> input area, press the <b>Test</b> button at the bottom of the dialog box: the result (<b>3</b>) should appear in the <b>Test trace</b> area below the expression.
<br>The test trace reports valid results as well as error messages as appropriate.
<br>Now erase the expression using the <Backspace> or <Delete> keys as you would normally do in a common text editor. Now drag a data cell from any displayed module table in the main application window and drop it into the expression area, hit the test button: the current value of the data cell should appear as the result of the formula in the test trace.
<p>You may now combine any number of data cells, constant numbers, mathematical operators and functions in real formulas. You may, and should, use the test feature as many times as required until you are satisfied with the results of the expression.
<p>For all data cells composing an expression, moving the mouse cursor over a cell displays a widget tip bearing the data cell label (see screen shot above), allowing the user to check the components of a formula at any time.
<p>Once all the formulas have been created, press <b>OK</b>: a formulas table appears in the main window. You may edit the formulas, add new formulas or delete existing ones at any time by using a popup menu in the formulas table, which will result in the formulas dialog box to be displayed.
<h6><a name="viewers.formulas.tables"></a>5.2.7.3. Tables</h6>
<p>A table of formulas displays the names and values of expressions of a list of formulas, belonging to an object and possibly a category for that object (see formulas <a href="#viewers.formulas.editing">editing</a> section above).
<p><center><img src="moodss12.gif" alt="formulas table"></center>
<p>A formulas table is a viewer, albeit with a title (bearing the object and the category if any), which makes it an exception among the viewers.
<br><i><b>Note</b>: it is also an exception in the sense that each formulas table is associated with an internal formulas module instance, which you may find hints of when recording formulas data cells history in a database and then browsing the database.</i>
<p>Note that, contrary to a module table, the title bar of a formulas table never changes color.
<p>In the <b>value</b> column, you will find data cells that show the result of the corresponding formulas (result of expressions actually). Each value is updated every time any of its contained data cell is updated. For example, if a formula contains cells from the <i>netdev</i> module and cells from the <i>diskstats</i> module, the value of the formula will be updated if either of the <i>netdev</i> and <i>diskstats</i> module data is updated. Generally speaking, the formulas tables are updated at the same time as the modules data tables.
<p>Clicking the third mouse button anywhere in the table displays a popup menu, which in turn can be used to display the formulas dialog box, in which you may edit the formulas. If you clicked on a specific formula, it is automatically selected in the formulas dialog box.
<p>Formulas tables data cells can of course be dropped into any viewer, thresholds dialog box, ..., as can be generally be done with data cells displayed in a dashboard. They also allow copying formulas: dragging a data cell in another formulas table results in the formula being copied (dropped) in the other formulas table.
<br>You may also drag a formula value data cell into another formula expression within the formulas dialog box, thus achieving formulas composition. Be careful to thoroughly comment the resulting formula, as it may significantly increase the complexity of the dashboard.
<p>Formulas tables data cells can also be dropped in the database dialog box, so that their history over time is recorded in the database. When browsing the database, each table appears in the <b>formulas</b> section, and is separately classified using its object and category, as the screen shot of the database instances dialog box shows below:
<p><center><img src="moodss13.gif" alt="formulas in a database instances dialog box"></center>
<p>Note that in database history mode, formulas can also be created, but their results depend on whether the composing data cells have a valid value at the latest time defined in the database range (see <a href="#menus.view.database.range">database range</a>).
<p>To delete formulas from a table, just select one or several formulas by either the name or value column, and drop them into the eraser.
<br>To delete whole formulas tables, drop them into the eraser by dragging the title area and dropping into te eraser, or drop the eraser into the table, as it is done with other viewers.
<h5><a name="viewers.examples"></a>5.2.8. Examples</h5>
<p>Here is a screen shot of loaded <i>ps</i> and <i>cpustats</i> modules with several graphical viewers:
<p><center><img src="moodss3.gif" alt="moodss window with graph data viewers"></center>
<p>Here is another shot featuring a free text viewer with loaded <i>cpustats</i> and <i>memstats</i> modules:
<p><center><img src="moodss4.gif" alt="moodss window with free text data viewer"></center>
<h4><a name="titlebar"></a>5.3. Title bar</h4>
<p>When not in database mode, the title bar shows the currently loaded modules and the current poll time, if any (there could be only asynchronous modules loaded), as the following image shows:
<p><center><img src="titlebar.gif" alt="title bar"></center>
<h4><a name="menus"></a>5.4. Menu bar</h4>
<p><center><img src="menubar.gif" alt="menu bar"></center>
<h5><a name="menus.file"></a>5.4.1. File</h5>
<h6><a name="menus.file.new"></a>5.4.1.1. New</h6>
<p>As in the <a href="#menus.file.exit">exit</a> menu, if there are unsaved changes, the user is given the opportunity to save them to a dashboard file before all existing modules are unloaded, along with any viewers.
<h6><a name="menus.file.open"></a>5.4.1.2. Open</h6>
<p>This menu entry allows the user to open an existing dashboard file (also useful for editing moomps dashboard files) to replace the currently loaded modules and viewers with those described in the file to open.
<p>As in the <a href="#menus.file.exit">exit</a> menu, if there are unsaved changes, the user is given the opportunity to save them to a file before opening the new file.
<p>Note that all existing modules will be unloaded, along with any viewers, prior to loading the configuration from the chosen file, thus acting as if the dashboard file was directly and initially loaded when moodss was started.
<h6><a name="menus.file.save"></a>5.4.1.3. Save</h6>
<p>The current application configuration (including existing data viewers), whether in real time mode or database mode, can be saved in a file, which achieves a dashboard functionality. The format used for saving is XML, as the following dashboard file extract shows:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
<?xml version='1.0'?>
<!DOCTYPE moodssConfiguration>
<moodssConfiguration>
<version>16.8</version>
<date>12/26/02</date>
<time>21:29:38</time>
<configuration graphNumberOfIntervals="100" canvasBackground="#fff4ff" canvasWidth="1152" pieLabeler="peripheral" canvasHeight="864" graphMinimumY="">
<viewerColors>
<item>#feffff</item>
...
</pre></td><tr></table>
<p>Once moodss has been launched with one or several modules and tables have been moved, resized, viewers created, moved and resized, the current configuration can be saved in a dashboard file (with a <i>.moo</i> extension), and later reused by passing the corresponding file name with the <i>-f (--file)</i> command line switch, or by using the <a href="#menus.file.open">File Open</a> menu.
<p>The following information is saved in the file (which is human readable):<ul>
<li>moodss version
<li>date and time
<li>application window size
<li>poll time
<li>modules
<li>tables positions and sizes
<li>viewers types, positions, sizes and specific data
<li>table viewers column widths
<li>viewers stacking order (for internal window manager)
<li>global configuration (such as canvas color, sizes, ...) (see <i>Edit</i> menu)
<li>pages tab labels
</ul>
<p>When using this menu for the first time, and if a dashboard file name was not specified in the command line, the file selector dialog box appears so that the user may choose a file name (with a <i>.moo</i> extension).
<p>Once a file name has been specified (either through the command line or the file selector dialog box), that file name is reused whenever the <i>File Save</i> menu is used.
<h6><a name="menus.file.saveas"></a>5.4.1.4. Save as</h6>
<p>This menu behaves as expected, with the user always having to choose a file name using the file selector dialog box (see <i>Save</i> menu above).
<br>This menu may be used at any time to change the current dashboard file name.
<h6><a name="menus.file.modules"></a>5.4.1.5. Modules</h6>
<h6><a name="menus.file.modules.load"></a>5.4.1.5.1. Load</h6>
<p>You can dynamically load a module by simply selecting its name from the available list discovered when the selection window opens. When the module is selected, its options appear and any number of them can be filled (options ending with <i>password</i> show <i>*</i> characters when the user types in the option value). The module documentation can be simply accessed by clicking on the <i>Help</i> button.
<p>Note that, during the lifetime of the application, if there was an attempt to load an instance of the selected module, the values used at that time for the module options are reused.
<p>Once the new module, or new instance of an already loaded module, is loaded, the application behaves as if the module had been loaded from the start. Use the <i>Close</i> button when done loading modules.
<h6><a name="menus.file.modules.manage"></a>5.4.1.5.2. Manage</h6>
<p>This dialog box allows the user to:<ul>
<li>view a list of the currently loaded modules
<li>select a module and view its configuration (command-line options and their values)
<li>get <b>help</b> on a loaded module
<li>change the configuration of a module and <b>reload</b> it
<li>change the configuration of a module and launch a <b>new</b> instance
<li><b>unload</b> a module
</ul>
<p>Once a module is unloaded, the module data tables disappear, but the viewers containing cells pointing to the module data remain, simply showing that the data is now invalid.
<p><i>Note</i>: if a module is reloaded, or unloaded then loaded again, viewers that monitored the unloaded module data will not resume monitoring the newly loaded module data since internally Tcl traces on variables were removed.
<p>When selected, the module current options appear (options ending with <i>password</i> show <i>*</i> characters in the option value). The selected module documentation can be simply accessed by clicking on the <i>Help</i> button.
<p>Use the <i>Close</i> button when done.
<h6><a name="menus.file.modules.loaded"></a>5.4.1.5.3. Loaded</h6>
<p>View the loaded modules and their options, without the possibility of unloading a module. This menu entry is available for example when moodss is started in read-only mode (see <a href="#commandline">Command line</a>).
<p>A module can be picked from a list of the currently loaded modules. If any, the module current options appear (options ending with <i>password</i> show <i>*</i> characters in the option value). The selected module documentation can be simply accessed by clicking on the <i>Help</i> button. Use the <i>Close</i> button when done.
<h6><a name="menus.file.database"></a>5.4.1.6. Database</h6>
<p>Both the moodss GUI application and the moomps daemon have the capability of recording history over time of any module data cells, by saving their values in a database (also see the preferences <a href="#preferences.application.database">database</a> and <a href="#preferences.moomps">moomps</a> sections, and the <a href="FAQ.htm">frequently asked questions</a> document).
<p>From this menu, it is possible to thoroughly browse the history database, while keeping a user interface (drag'n'drop, viewers, help, ...) behaving as in real time monitoring.
<p>When any database related error occurs, the <a href="#menus.view.trace">trace</a> window is automatically opened and displays the related error messages.
<h6><a name="menus.file.database.load"></a>5.4.1.6.1. Load</h6>
<p>This menu (or its associated button in the <a href="#menus.view.toolbar">tool bar</a>) opens the database instances dialog box (provided database access is properly configured), and shows (with possibly a small delay depending on the speed of the database used) all the module instances, as the following screen shot shows:
<p><center><img src="dbgui.gif" alt="database instances dialog box"></center>
<p>Note that you will be given the opportunity to save your configuration in a dashboard file if you were monitoring in real time with some loaded modules, prior to switching to database mode (deferred time).
<p>A tree shows all the module names, with instances containing data cells stored in the database (also see the <a href="#menus.edit.database">database</a> edit menu). Below each module name, all the instances for that module are shown when clicking on the <b>+</b> tiny icon. Finally, below each instance, all the data cells can be found, with their comments in parentheses, if any.
<p>Clicking on any tree node displays, possibly after a small delay, the time range in the database for that item. For example, clicking on a module name would show the date and time of the oldest cell data sample for all instances of that module, along with the date and time of the most recent sample, at the time the dialog box was opened.
<p>Clicking on the <b>SQL</b> button while a data cell is selected show the SQL query that can be used to retrieve all the data samples for that cell. For example, that can help when developing an external application accessing the database.
<p>To actually load an instance into the moodss GUI, either select the desired instance and then click the <b>OK</b> button (which closes the dialog box), or drag any number of instances (but one at a time) into the database module instances viewer (as seen in the picture below) while keeping the dialog box opened.
<p><center><img src="database.gif" alt="moodss window view in database mode"></center>
<p>For each instance, the available extent of time for all data cells histories for that instance is shown on the time scale of the database module instances viewer. If an instance contains only data cells with empty histories, an endless dotted line is shown (as seen above for the <i>random</i> module). The module options for each instance can be displayed in a widget tip by keeping the mouse pointer over an instance name.
<p>For each displayed instance, a corresponding data table is also displayed (see the <i>snmp</i> data table in the screen shot above). For each data cell, the corresponding comment (if it exists, see the <a href="#menus.edit.database">database</a> edit menu) or the data cell name is displayed in the left column, while the last values are displayed on the right side. The original module help for data is preserved and can be accessed via a widget tip, which appears when the mouse pointer is placed on top of a data cell label.
<p>From then on, all the functionality that you are used to in real time mode is available to you (expect for the thresholds settings which only make sense while monitoring in real time). As an example, in the screen shot above, the <i>WAN input</i> and <i>output</i> traffic cells were dropped in a stacked graph viewer, which after a delay depending on the database engine speed and the amount of stored history data, displayed the complete history for both cells.
<p>A specific range within the time extent can be set using the blue cursors in the database module instances viewer (just drag them with the mouse and refresh the display by clicking on the refresh button or using the <a href="#menus.view.refresh">refresh</a> view menu).
<br>Alternately, the <a href="#menus.view.database.range">View Database range</a> menu can be used to precisely set the date and time limits from a dialog box. Note that the cursors and the database range dialog box are synchronized: moving a cursor results in the date and time values being updated in the dialog box.
<br>All the views are then updated, with the viewers either showing the complete history or the value at the right cursor, depending on their type (the statistics table viewer shows the average, minimum, maximum, ... values for the selected time range).
<br>Finally, in any displayed graph data viewers, you may drag a time value directly from the cross hair (see <a href="#userinterface.crosshairs">user interface</a>) and drop it into the database instances viewer: the closest blue cursor will move to the time value. Then hit the refresh button to update the display. This technique allows fine tuning of the display to a specific time range, directly from any graph viewer.
<p>Module instances can be unloaded by dragging from their name in the database module instances viewer into the eraser drop site.
<p>Saving the display layout in a dashboard file is also possible in this database mode.
<p><i><b>Note</b>: when data history is being displayed, if the tool bar is visible, the center part of the play button is lit in green.</i>
<h6><a name="menus.file.database.start"></a>5.4.1.6.2. Start</h6>
<p>Starts recording data history over time in the database (defined in <a href="#preferences.database">preferences</a>) for the cells specified in the <a href="#menus.edit.database">database interface</a>.
<br>You may also use the associated button in the <a href="#menus.view.toolbar">tool bar</a>.
<br>Archiving can be stopped at any time using the <a href="#menus.file.database.stop">Stop</a> menu. Then data history can be displayed and manipulated using the <a href="#menus.file.database.load">Load</a> menu.
<p>While recording, errors, such as disconnections when the database server becomes unreachable, are handled by gracefully disconnecting and retrying to connect at each update, thus greatly enhancing reliability.
<p><i><b>Note</b>: when data history is being recorded, if the tool bar is visible, the center part of the stop button is lit in red (see <a href="#menus.view.toolbar">tool bar</a> screen shot).</i>
<h6><a name="menus.file.database.stop"></a>5.4.1.6.3. Stop</h6>
<p>Stops recording data history in the database, process started using the <a href="#menus.file.database.start">Start</a> menu.
<br>You may also use the associated button in the <a href="#menus.view.toolbar">tool bar</a>.
<h6><a name="menus.file.print"></a>5.4.1.7. Print</h6>
<p>You can print the canvas area in postscript to a printer or a file, which you may choose using the classical file browser. Please note that only the strictly visible area, without the scrollbars, will be printed.
<p>You can choose the printout orientation (portrait or landscape), palette (color, gray scale or monochrome) and the paper size.
<p>Due to widget and architecture limitations, the printout is pixel based. As a benefit, it is extremely WYSIWYG :-).
<br>Also, because of design limitations, printing is disabled on Windows platforms.
<p>The printout is sized according to the following rules:<ul>
<li>empty space, around tables or data viewers, is not included (the area is cropped)
<li>a margin of 0.5 inch (12.7 millimeters) is used both horizontally and vertically on all sides
<li>size reduction occurs equally horizontally and vertically (aspect ratio is preserved) only when necessary so that all tables and data viewers are visible on the printout
</ul>
<p>When the print menu entry is selected, a dialog box appears, as can be seen in the screen shot below (which also shows the preview window in the background):
<p><center><img src="moodss7.gif" alt="print dialog box with preview window"></center>
<br>You can choose to send the postscript data to a printer or to the screen for previewing.
<p>Depending on the print configuration (see <a href="#core.preferences">Preferences</a>), either a print command line entry or a printer selection list appears below the informational message (<i>note: successfully tested against the Berkeley LPR print spooler and the Common UNIX Printing System (CUPS)</i>). Hitting the OK button sends the data to the selected printer or through the specified command line.
<p>The preview functionality uses <em>gs</em> (also known as ghostscript), which must be installed (<i>note</i>: version 5.50 or above is required, as 5.10 is buggy). If gs cannot be found or executed, the preview button is grayed. If the gs version is below 5.20, the button is also grayed and a window tip explaining the cause is displayed when the mouse pointer is located above the button.
<p>When the gs utility is available and of the correct version, the preview button can be depressed, in which case the print dialog temporarily disappears (so that the application main window is not obscured), and reappears along with the preview window, once the printout view has been calculated.
<br>The preview window also features a zoom menu for resizing. If the user so desires, one or more printing parameters, such as page size, orientation, ... can be changed while the preview window remains visible. Hitting the preview button then results in both the print dialog box and the preview window to temporarily disappear while the new page look is calculated. After a short while, they both reappear with the preview updated accordingly, and having kept the same zoom ratio.
<p>Also note that due to the implementation of the graphical layer on UNIX systems, any window or object obscuring the canvas area will also be printed, but this is unlikely, as the moodss application window will be in front when the print menu item is selected.
<h6><a name="menus.file.exit"></a>5.4.1.8. Exit</h6>
<p>Use this menu to gracefully quit the moodss application. You may also use the window manager to close the application.
<p>If there are unsaved changes (configuration, viewers created, tables or viewers moved, stacked, ...), the user is given the opportunity to save them to file (see <a href="#menus.file.save">File Save</a> menu). The file selector dialog box is used if no save file name is currently known by the application.
<h5><a name="menus.edit"></a>5.4.2. Edit</h5>
<h6><a name="menus.edit.thresholds"></a>5.4.2.1. Thresholds</h6>
<p>Using this menu or dropping cells into the thresholds drop site in the main window results in the following dialog box being displayed. While displayed, user interaction with other parts of the user interface remains possible, so that more cells can be dropped into the thresholds dialog box table itself.
<p><center><img src="moodss8.gif" alt="thresholds user interface"></center>
<p>A list of threshold entries is displayed in a table with the following columns:
<ul>
<li><b>active</b>: Clicking on the check button toggles the state of the entry between active and not. When active, the shell script is invoked when and if the threshold condition occurs. For example, if the threshold type is <i>up</i> and the data cell value goes above the threshold value.
<li><b>type</b>: Clicking on the entry icon toggles the threshold type between <i>differ</i>, <i>down</i>, <i>equal</i>, <i>unknown</i> and <i>up</i> (see threshold types below).
<li><b>once</b>: Whether actions (email and script) will be invoked only once after the threshold condition is met, with the related internal state being reset when the threshold condition is no longer met. For example, if the threshold type is <i>up</i>, and email will be sent at the time the data value goes above the threshold, but not while it stays above. If the value goes below the threshold, then another email will be sent once the threshold is crossed again. <i>Note: not checked by default for backward compatibility.</i>
<li><b>level</b>: Importance level settable using a pop-up selector. When a cell has several thresholds active, it will take the color of the most important threshold. It is also be included in the email alert message and is used by moomps to set the system logging importance level for the threshold log entry. Defaults to <i>notice</i>. Possible values are, in increasing importance order: <i>debug</i>, <i>info</i>, <i>notice</i>, <i>warning</i>, <i>error</i>, <i>critical</i>, <i>alert</i>, <i>emergency</i>.
<br>Changing the level may also automatically change the color to be displayed in source cell(s) (see below).
<li><b>color</b>: Selects the color to be displayed in source cell(s) when the threshold condition occurs. Clicking on the menu button drops a menu window with predefined color buttons, the last of which, with 3 dots as a label, if selected, opens a custom color selection dialog box. The menu button color reflects the currently selected threshold color. The <b>?</b> entry stands for transparency, that is there will be no color change in the monitored cell displays when the threshold condition occurs. Note that this color is automatically updated when the importance level is changed (see above), provided the color was not previously set to a custom value by the user.
<li><b>actions</b>: a small envelope icon (<img src="mail.gif" alt="mail">) is displayed when there is at least one email recipient specified in the list of email addresses (see below), with a yellow tint (<img src="maily.gif" alt="custom mail">) when the mail message is not the default (see below), and a small gear icon (<img src="gear.gif" alt="gear">) is displayed when the threshold script (see below) is not empty.
<li><b>value</b>: The threshold value, used as reference when comparing with the data cell current value. When changed, the threshold condition is checked as the user confirms when closing the dialog window.
<li><b>source</b>: Initially, when the threshold entry is created, the data cell label, as it would be displayed in a data viewer. This column is editable so that the user may input a more meaningful description.
</ul>
<p>Additionally, when a row is selected, the following fields become available in the lower area of the dialog box:<ul>
<li><b>Initial condition</b>: if the threshold condition is met most of the time, such as an initial condition, you can disable acting at application start by checking this button (see example in <a href="#menus.edit.thresholds.notes">notes</a>).
<li><b>Emails</b>: an editable list of email addresses. To enter a new address, simply hit the <Return> of <Enter> key in any filled cell. An empty cell is then created at the bottom of the list. To delete an address, simply empty it using the usual <Backspace> or <Delete> editing keys.
<br>When a threshold event occurs, an alert message will be sent to each recipient (also see <a href="#preferences.thresholds.email">preferences</a>). Any error occurring when attempting to send mail will be visible in the <a href="#menus.view.trace">trace</a> module. See below for more information on email messages.
<li>The <b>Original cell</b> label.
<li>The corresponding data cell <b>Current value</b>.
<li>Whether the <b>default</b> mail message is used (as set in the preferences <a href="#preferences.thresholds.email">email</a> section).
<li>The custom <b>Mail message</b> section (which is hidden or displayed by clicking on the little arrow button), and becomes available if the <b>default</b> button is not checked:<ul>
<li>The mail <b>Subject</b> line (may include % substitutions, see below).
<li>The mail <b>Body</b> text (may also include % substitutions, see below).
<li>You may also include a screen shot (in JPEG format) of the moodss window at the time the threshold occurred, by ticking the check button, next to the little <b>camera</b> icon.
<br><i><b>Note</b>: the screen shot may turn out to be black, depending on whether the moodss window was visible when the threshold occurred, due to the X Window System implementation. More work needs to be done in that area to solve that problem.</i>
</ul>
<li>The <b>Script</b> section (which is hidden or displayed by clicking on the little arrow button):<ul>
<li>An editable text area can be used to enter a UNIX <b>script</b> or Windows command script, invoked when the threshold is crossed. See script section below for passing arguments to the script.
<li>The <b>Test trace</b> area, which displays the output of the script (if any and including errors), when the <b>Test</b> button is clicked. Errors are always visible in the trace module data table if displayed.
</ul>
<li><b>Test</b> button (at the bottom of the dialog box): simulates a threshold condition. The shell script is then invoked as if the real threshold was crossed, the cell value being artificially generated. Any output generated by the shell script is displayed in the test trace area. A mail message, default or custom, is sent to the specified email addresses. Displayed source cell(s) in the main application window remain unaffected color-wise.
<li><b>Delete</b> button (at the bottom of the dialog box): removes the selected threshold entry (row). All related displayed source cells are reset to their original (transparent) color.
</ul>
<p>Sample threshold email message (the default):
<pre>From: moomps@localhost.localdomain
To: jfontain@localhost.localdomain
Subject: moodss threshold warning message
warning: "random: Robert top disk" data value is now "11",
which triggered the "up" threshold of "10".</pre>
<p>Selecting a row is done by clicking on any cell of the row. The row is then highlighted.
<br>When selecting another row in the thresholds table, or closing the dialog box using the OK button, the syntax of the displayed emails is checked and errors, if any, reported in a message box. It is then recommended to test that emails actually get sent and to the right recipients, using the test functionality described below.
<p>Help is provided through widget tips on the table title cells, and a help button, which directly opens the main help window at the relevant section.
<p>Creating threshold entries is done through the drag'n'drop mechanism by dropping data cells into the thresholds drop icon or into the thresholds dialog box table itself (provided it is open, of course). Any number of thresholds can be set on the same data cell.
<h6><a name="menus.edit.thresholds.types"></a>5.4.2.1.1. Types</h6>
<p>The following threshold types are supported:<ul>
<li><img src="differ.gif" alt="differ"> : threshold and cell value must differ.
<li><img src="down.gif" alt="down"> : cell value must be less than threshold.
<li><img src="equal.gif" alt="equal"> : threshold and cell value must be equal.
<li><img src="unknown.gif" alt="unknown"> : cell value must be unknown (void).
<li><img src="up.gif" alt="up"> : cell value must be more than threshold.
</ul>
<p>Depending on the source data cell type, specific internal comparison techniques are used.
<p>For the ASCII type, the current cell value can be lexicographically less than, equal to, or greater than the threshold value. Empty threshold values are allowed. The strings are compared in a case-insensitive manner.
<p>The dictionary type is handled as the ASCII type, with case ignored except as a tie-breaker and if there are embedded numbers, the numbers compare as integers, not characters.
<p>For the clock type, the cell and threshold values are first converted to seconds, then compared.
<p>When the threshold type is <img src="unknown.gif" alt="unknown">, the condition occurs when the data cell value cannot be determined, and only in such a case. It is the only type of threshold that can be triggered by the void nature of a data cell.
<br>This condition can happen when a data cell (of any type) no longer exists (for example, when its row has disappeared), or the data cell is of numeric type, still exists but contains void data (displayed as <i>?</i>).
<br>For other types of data cells, the displayed value when the data cell becomes void should be documented in the module help, and setting a threshold on such a cell being void should instead be done using the equal (<img src="equal.gif" alt="equal">) threshold type on the specified value.
<p>Note that for each type, you may choose for the thresholds actions to be taken only once by checking the <i>once</i> column.
<h6><a name="menus.edit.thresholds.color"></a>5.4.2.1.2. Color</h6>
<p>If a non-transparent color has been selected (see previous section), whenever the threshold condition occurs, all displays of the monitored data cell change color (in data tables or in viewers), and return to their normal color when the threshold condition no longer exists.
<p>When several thresholds are placed on the same data cell with different colors, and they all trigger, the behavior is undefined at this time (but the most recent threshold is likely to prevail).
<h6><a name="menus.edit.thresholds.script"></a>5.4.2.1.3. Script</h6>
<p>Whenever a threshold is triggered (the manner of which depends on the type), the corresponding script is passed to the UNIX shell interpreter (the <i>sh</i> UNIX command), after variable substitution.
<p>Substitution occurs prior to script invocation if the script contains any % characters. Each % and the character following it is replaced with information from the threshold occurrence. The replacement depends on the character following the %, as defined in the following list:<ul>
<li><b>%%</b>: replaced by a single %.
<li><b>%A</b>: the name of the application (either <i>moodss</i> or <i>moomps</i>).
<li><b>%c</b>: replaced by the original data cell string (as would be displayed in any data viewer).
<li><b>%l</b>: replaced by the importance level string (<i>alert</i>, <i>warning</i>, ...)
<li><b>%s</b>: replaced by the contents of the source column from the thresholds table.
<li><b>%t</b>: the threshold value
<li><b>%T</b>: the threshold type (<i>differ</i>, <i>down</i>, <i>equal</i>, <i>unknown</i>, <i>up</i>, ...)
<li><b>%v</b>: the data cell value responsible for triggering the threshold
</ul>
<p>Any error returned by the script is visible in the <a href="#menus.view.trace">trace</a> module.
<h6><a name="menus.edit.thresholds.dragging"></a>5.4.2.1.4. Dragging</h6>
<p>When a row is selected, it is possible to drag from the current cell value display, into the thresholds table itself to create a new entry for the same cell, or into any viewer icon or existing viewer.
<h6><a name="menus.edit.thresholds.notes"></a>5.4.2.1.5. Notes</h6>
<p>When the dialog box is displayed, existing thresholds are sorted according to their importance level with the most important on top. If several thresholds of the same type and same importance level are set on the same cell, the highest (according to the cell data type) threshold is displayed first.
<br>When new thresholds are interactively added to the dialog box, they are displayed at the bottom of the thresholds table, but will be sorted as the others the next time the dialog box is opened.
<p>While the thresholds dialog box is visible, threshold conditions are not checked by the software, which means no cell color changes, no email alerts, ... can occur.
<p>Internally, threshold conditions are checked in reverse order compared to the displayed order, that is the most important thresholds last. As a consequence, color gradients on a cell are automatically achieved.
<br>For example, if you set the 3 following <i>up</i> thresholds of the same importance level (does not matter in this case, say <i>info</i>) on the same cell:<ul>
<li>color: <i><font color="yellow">yellow</font></i>, value: <i>80</i>
<li>color: <i><font color="orange">orange</font></i>, value: <i>90</i>
<li>color: <i><font color="red">red</font></i>, value: <i>95</i>
</ul>
<p>you will get a color gradient effect, as the cell value approaches 100, it will turn <i><font color="yellow">yellow</font></i>, <i><font color="orange">orange</font></i> then <i><font color="red">red</font></i>.
<p>You can also force color gradients on a cell by combining importance levels and colors.
<br>For example, if you set the 3 following <i>up</i> thresholds on the same cell:<ul>
<li>level: <i>notice</i>, color: <i><font color="yellow">yellow</font></i>, value: <i>80</i>
<li>level: <i>warning</i>, color: <i><font color="orange">orange</font></i>, value: <i>90</i>
<li>level: <i>alert</i>, color: <i><font color="red">red</font></i>, value: <i>95</i>
</ul>
<p>you will get an importance color gradient effect as the cell value approaches 100.
<p>If the threshold condition is met most of the time, such as an initial condition, you can disable acting at application start by checking the <b>initial condition</b> button (see example in <a href="#menus.edit.thresholds.notes">notes</a>).
<p>The <b>initial condition</b> button, when checked, prevents any action from being taken when the application (moodss or moomps) is started.
<br>It is useful when the threshold condition is "normal". For example, when monitoring a network link, you want to be warned when it goes down (for example by checking that the <i>ifOperStatus</i> is <i>down</i> using the <i>snmp</i> module), but you also need the information that the link is back up (by checking that the <i>ifOperStatus</i> is <i>up</i>). Unfortunately, using this technique, you would get an email stating that the link is up every time the application is started. Checking the <b>initial condition</b> button prevents it.
<p><i>There are still a lot of features to implement: please see the TODO file.</i>
<h6><a name="menus.edit.configuration"></a>5.4.2.2. Dashboard configuration</h6>
<p>When selected, this menu launches the dashboard configuration dialog box, as described in <a href="#core.configuration">Configuration</a>.
<h6><a name="menus.edit.newpage"></a>5.4.2.3. New page</h6>
<p>Creates a new page after the existing pages. If there are no pages, that is all modules are displayed in the sole main window canvas, those contents are placed in the first page just created. The page is then displayed, its tab opened in editing mode so the label can be immediately set by the user.
<p>To delete a page, just grab its tab and drop it in the eraser drop site. Note that a page must be empty of any table of viewer before it can be deleted, except for the last remaining page, the deletion of which results in only its tab being removed.
<h6><a name="menus.edit.newviewer"></a>5.4.2.4. New viewer</h6>
<p>Allows the creation of empty viewers of any type (graph chart, stacked graph chart, overlap bar chart, side bar chart, stacked bar chart, 2D pie chart, 3D pie chart, statistics table, values table, free text, iconic and formulas tables).
<br>This menu is only visible when not running in read-only mode (see <a href="#commandline">Command line</a>).
<h6><a name="menus.edit.database"></a>5.4.2.5. Database</h6>
<p>Opens the database dialog box, a drop site for modules data cells. The cells dropped in the database dialog box will be monitored by moodss (see the <a href="#menus.file.database.start">Database Start</a> menu) or the moomps daemon (provided of course that the configuration file (see <a href="#menus.file.save">Save</a> menu) is used by the moomps service).
<p>The dialog box displays a table, the drop site, with the following columns:<ul>
<li>The data cell <b>label</b>, as it would be displayed in a data viewer
<li>Whether archiving is <b>active</b>, which is whether the data cell history should be stored in the database
<li>The <b>current</b> value of the data cell (useful to see if the data is currently valid)
<li>A <b>comment</b> to be stored in the database for that specific cell
</ul>
<p>When the moomps service is running, any number of data cells can be monitored over time, using a SQL database as storage mean. The cells values are stored in the database, which can then be used from, for example, a spreadsheet software. Using such tools, it becomes possible, for example, to create history graphs, presentations, ... using the moodss database as data source. (more information can be found in the <a href="moomps.htm">moomps documentation</a>).
<p>For example, if you want to monitor CPU usage over time on a Linux server, load the <i>cpustats</i> module, open the database dialog box, drag and drop the <i>user</i>, <i>system</i> and <i>nice</i> cells in the database interface and finally save the configuration in a <i>.moo</i> file within the moomps configuration directory.
<p>Note that only cells coming from an original module table can be dropped in the database window. If you attempt to drop a cell from say a statistics table, the cell will not appear in the database window and an error message will be displayed in the main application window message area.
<h6><a name="menus.edit.preferences"></a>5.4.2.6. Preferences</h6>
<p>When selected, this menu launches the preferences dialog box, as described in <a href="#core.preferences">Preferences</a>.
<br>The format used for saving the preferences is XML, as the following preferences file extract shows:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
<?xml version='1.0'?>
<!DOCTYPE moodssPreferences>
<moodssPreferences>
<version>16.8</version>
<date>12/26/02</date>
<time>21:29:31</time>
<traceNumberOfRows>20</traceNumberOfRows>
<printToFile>0</printToFile>
...
</pre></td><tr></table>
<p>On UNIX platforms, the preferences file is named <i>.moodssrc</i> and is saved in the current user home directory, with write and read rights strictly restricted to the current user, as sensitive information, such as database passwords, can be stored in the preferences file.
<h5><a name="menus.view"></a>5.4.3. View</h5>
<h6><a name="menus.view.refresh"></a>5.4.3.1. Refresh</h6>
<p>Immediately refreshes display of all loaded asynchronous modules.
<h6><a name="menus.view.polltime"></a>5.4.3.2. Poll Time</h6>
<p>The <i>View</i> menu (may not exist, see below) contains the <i>Poll Time</i> entry which when selected launches the corresponding dialog box, as shown below:
<p><center><img src="moodss2.gif" alt="poll time dialog box"></center>
<p>The user can select a new poll time among the module choices from a spin entry widget, or directly type in a new value, as long as it is not smaller than the module minimum poll time, in which case a warning message is displayed.
<p>When several modules are used, the minimum poll time is the greater of the minimum poll times of all modules. The default poll time (used when moodss is started) is the greater of the default poll times of all modules. The available choices in the poll time dialog box is the combination of all modules poll times.
<p>The <i>Poll time</i> menu entry is available only when needed, which is not the case if all the loaded modules are asynchronous. If this case, the <i>Options</i> menu itself is not displayed.
<br>This menu is only visible when not running in read-only mode (see <a href="#commandline">Command line</a>).
<h6><a name="menus.view.database.range"></a>5.4.3.3. Database range</h6>
<p>Allows the specification of precise date and time limits for database views, loaded using the <a href="#menus.file.database.load">File Database Load menu</a>.
<p><center><img src="dbrange.gif" alt="database range dialog box"></center>
<p>Note that once you have validated your choice (using either the <b>OK</b> button or the <b>Apply</b> button, the latter keeping the dialog box opened), the dialog box closes and all database related views are automatically refreshed (it is not necessary to manually use the <a href="#menus.view.refresh">refresh</a> view menu or button).
<br>Also note that the blue cursors in the database module instances viewer are updated in real-time as the values in the dialog box are changed.
<h6><a name="menus.view.trace"></a>5.4.3.4. Trace</h6>
<p>Opens a separate window containing the <i>20</i> latest informational, error, ... messages (if any) internally generated by the loaded modules. This menu entry when selected again closes the window.
<p>A resident <a href="#trace">trace</a> module is actually used to fill the contents of that window, which does not prevent loading other instances of the <i>trace</i> module in the main window, as can be done with any other module.
<h6><a name="menus.view.toolbar"></a>5.4.3.5. Tool bar</h6>
<p>Shows or hides the tool bar.
<h5><a name="menus.help"></a>5.4.4. Help</h5>
<h6><a name="menus.help.global"></a>5.4.4.1. Global</h6>
<p>This menu launches an embedded HTML viewer with this very document minus the sections related to module development.
<h6><a name="menus.help.modules"></a>5.4.4.2. Modules</h6>
<p>This menu features one sub menu per module, which when selected displays the module's help data.
<h6><a name="menus.help.about"></a>5.4.4.3. About</h6>
<p>Displays version, author, extension authors, license and basic information about moodss.
<h4><a name="toolbar"></a>5.5. Tool bar</h4>
<p>This common user interface part makes some menu actions direct by using buttons with embedded icons. Help is provided through widget tips (balloons).
<p><center><img src="toolbar.gif" alt="tool bar in database recording mode"></center>
<p>The contents of the tool bar change depending on whether a module is loaded, a save file has been used, ... and always fit to the current context. The tool bar can be hidden or displayed at the user convenience using the <a href="#menus.view.toolbar">Tool bar</a> menu.
<h4><a name="canvasarea"></a>5.6. Canvas area</h4>
<p>The largest part of the main window is the canvas area, used to display and manage data tables, viewers and icons. Its background color can be changed in <a href="#menus.edit.configuration">configuration</a> and <a href="#menus.edit.preferences">preferences</a>. An internal window manager handles all the operations within the canvas.
<p>All data viewers can be moved and possibly resized thanks to handling areas in the data viewer borders. When moving the mouse pointer over these areas, the mouse cursor changes to indicate the possible action. Corner handles allow resizing in both X and Y axis. Handles in the middle of the sides allow resizing in either the X or Y axis direction. All other areas can be used for moving the data viewer as shown by the quadruple arrow cursor.
<br>For tables and viewers with borders, clicking on any part of the border changes the stacking order: the viewer being clicked on either goes below (possibly becomes hidden) the other viewers, or becomes fully visible (on top, possibly hiding other viewers). If you want to avoid moving the viewer while attempting to change its stacking order, you may use the second mouse button (in the middle on a 3 button mouse) instead of the first mouse button.
<br>Iconic viewers and minimized tables (displayed as icons) can only be moved, and, due to the internal implementation, can be hidden by other viewers. However, they still can be detected by circulating between the viewers as described below.
<p>You can circulate between tables, icons and viewers by using the <i>Tab</i> (forward) and <i>Shift-Tab</i> (backward) keystrokes, which successively bring the next object to the top in the stacking order, in the case of tables and viewers with borders. Minimized tables (icons) and iconic viewers are highlighted for a short time using a black border, which shows even if the object is hidden by other viewers.
<p>When moving or resizing a table or a viewer, its window or its borders will snap, as if attracted by a magnet, when getting close to another window or the canvas borders. This makes aligning a large number of windows convenient (<i>note: this feature was designed by somewhat copying the KDE window manager behavior</i>).
<br><b>Note</b>: for more precise placement, it is possible to disable the magnet effect by holding down the <i>Control</i> key while moving or resizing objects.
<br>When moving or resizing, the message area displays the current coordinates or size in real time as the mouse is being moved.
<p>Further description of this small window manager functionality is useless, as it behaves like a basic window manager (let me know if it does not).
<p>Module tables can be minimized by clicking on the down arrow button of the right side of a table title area. The resulting icons are arranged at the bottom left of the canvas area, from left to right. Icons can be moved simply by clicking and holding the left mouse button. Double clicking on an icon results in the corresponding table to become visible again at its original position.
<br>Once moved by the user, a table icon icon will remember its coordinates. That is if the table is restored then minimized again, the icon will be placed at its latest position.
<h4><a name="pagetabs"></a>5.7. Page tabs</h4>
<p>If there are several pages displayed (see <a href="#menus.edit.newpage">New page</a> menu for creating pages), the pages tabs are visible near the bottom of the main window (by default, but the tabs can also be placed on top using the <a href="#preferences.application.pages">pages</a> section in preferences).
<p>A page tab label can be changed at any time while the application is running. <i>Double-click</i> or click with the <i>third</i> mouse button on the chosen tab, the text background then changes and the insertion cursor is displayed. Note that the whole text is initially selected to make it easy to replace the label by immediately typing. Once done, press the <b>Return</b> key to confirm or the <b>Escape</b> key to abort editing the tab label, in which case it returns to its previous value.
<p>Viewers and tables can easily be moved across pages by using the internal window manager. Move the table or viewer as you normally would but keep going into the destination page tab until the black drop border appears around the tab label, then drop. The table or viewer is placed at the upper left corner of the destination page.
<p><center><img src="pagetabs.gif" alt="page tabs with thresholds summaries"></center>
<p>If a page contains any table or viewer containing data cells with active thresholds, then the page tab background takes the color of the most important threshold (according to its importance level). If there are several active thresholds of the same most important level, but with different colors, then the colors are shown in sequence, 1 per second, as the page tab background.
<br>Additionally, up to 3 of the most important threshold summaries are displayed in a widget tip (or balloon) when the mouse cursor lies over the page tab (see picture above).
<h4><a name="message"></a>5.8. Message</h4>
<p>The message area header label also serves as a thresholds indicator, just like a page tab, but for all the thresholds activated in the application.
<p>The behavior is identical to a page tab, with the most important thresholds colors displayed in sequence if necessary, and a widget tip showing the most important thresholds summaries.
<h4><a name="messagesarea"></a>5.9. Message area</h4>
<p>At the bottom of the main window, the message area is used to display various help and information strings for the user. For example, every time that a module is updated, when a menu entry is being activated, or to instruct the user on how to edit a page tab.
<p><center><img src="messagesarea.gif" alt="messages area"></center>
<h4><a name="draganddrop"></a>5.10. Drag and drop</h4>
<p>Drag and drop in moodss tries to behave as in popular GUIs. For example, to create a graphical plot, one must first select one or more data cells in a data table, hold down the first mouse button (the left one for a right handed user) while dragging over to the left-most icon below the menu bar (when dragging an object, as the mouse pointer passes over possible drop sites, they are highlighted with a thin black border for user feedback). Releasing the mouse button at this time results in the creation of a BLT graph viewer.
<p>Only valid drop sites for the data being dragged are highlighted when the mouse cursor passes over them, thus guaranteeing error free operations (if there are no bugs, that is :).
<p>In summary, data cells can be dragged from any table or any viewer into any viewer drop site icon, any viewer or the eraser.
<h5><a name="dropsites"></a>5.10.1. Drop sites</h5>
<p>All icons right below the menu bar are valid drop sites for data cells (several may be dropped at the same time). From left to right:<ul>
<li>graph viewer with one or more data curves created at once
<li>stacked graph viewer with one or more data filled curves created at once
<li>side by side bar chart with one or more data bars created at once
<li>stacked bar chart with one or more data bars created at once
<li>2D pie chart with one or more data slices created at once
<li>3D pie chart with one or more data slices created at once
<li>values table with one or more data rows created at once
<li>statistics table with one or more data rows created at once
<li>free text with one or more labeled data cell windows created at once
<li>thresholds with one or more entries created at once
<li>object eraser with one or more data viewer elements deleted at once
</ul>
<p>For example, a graph viewer with 1 curve is created by dropping 1 data cell into the graph viewer icon.
<p>Once a viewer exists, it also acts as a drop site for data cells, which may be dragged from any table or other viewers. Dropping one or more cells directly in the viewer results in corresponding lines, bars, slices or rows being created and automatically updated. Each new graphical element is assigned a new and different color.
<p>You may delete one or more viewer elements (graph lines, bar chart bars, pie charts slices, statistics or values table rows or free text cell window) from a viewer by selecting them (using the first mouse button) through their labels. Several elements can be selected by depressing the control key as the first mouse button is pressed. The selection can also be extended by depressing the shift key along with the first mouse button. The pie slices can also be directly selected by clicking on the slices themselves.
<br>Then dragging from the viewer to the eraser drop site (the pencil eraser) on the upper right side of the main window and releasing the first mouse button result in the corresponding viewer elements to be destroyed. When there are no remaining elements, the viewer itself (graph, bar chart, pie, values or statistics table) can be destroyed by dropping it into the eraser site. The free text viewer can only be deleted this way when completely emptied of any text and data cell window.
<p>Any viewer can be deleted in one shot by dropping from the eraser icon into it.
<br>Yet another way is to move the viewer (as usual, using the internal window manager handles) into the eraser.
<p>Any viewer also acts as a drop site for viewer type data, which allows viewer mutation by just dropping from the new viewer type icon into the existing viewer. It is much quicker than destroying the existing viewer and create a new one of the new type, while remembering which data cells were monitored by the viewer of the old type.
<br>When mutating, if some cells in the current viewer no longer exist (they may belong to a disappeared statistics table), they are not made a part of the new viewer, and a warning message is flashed to the user in the message area.
<p>A page tab is a drop site for any table or viewer, which allows transferring them between pages. Proceed by moving the table or viewer (as usual, using the internal window manager handles) into another page tab (wait until you see the drop black outline around the tab label to release the mouse button). The viewer can then be found in the upper left corner of the target page.
<p>A formulas table is a drop site for any formula, coming from other formulas tables.
<h5><a name="dragsites"></a>5.10.2. Drag sites</h5>
<p>A table is obviously a drag site. One or more cells can be dragged at once after selection, using the traditional single/shift/control mouse click technique.
<p>Any viewer is also a drag site. It requires selecting one or more viewer elements before initiating the drag operation from any selected element in the viewer. If there are no selected elements, dragging is impossible: the mouse cursor is not changed into the drag circular cursor.
<p>If a viewer contains no elements, then the viewer itself can be dragged and dropped into the eraser.
<p>All viewer icons (below the menu bar) are drag sites for viewer type data, which allows quick viewer mutation (see mechanism description in <a href="#dropsites">Drop sites</a>).
<p>Note that formulas tables are special kinds of viewers, as they also allow copying formulas: dragging a data cell in another formulas table results in the formula being copied (dropped) in the other formulas table.
<p>The eraser icon is also a drag site of the killing action type, which allows viewer destruction in one shot.
<p>A viewer or a table is also a drag site when being moved via its window manager handles:<ul>
<li>a viewer can be moved into the eraser for deletion
<li>a table or a viewer can be moved into a page tab text area for transfer to another page
</ul>
<h4><a name="internationalization"></a>5.11. International languages</h4>
<p>Moodss supports localization of the user interface for the following languages:<ul>
<li>English (US)
<li>French (not including global help)
<li>Japanese (see <a href="FAQ.htm">FAQ</a> for more information)
</ul>
<p>Support for international languages has only been tested on Linux so far, but should work well in other environments.
<br>All that is needed is checking that the proper environment variable is set. For example, for a French GUI:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ echo $LC_ALL
fr
</pre></td><tr></table>
or
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ echo $LANG
fr
</pre></td><tr></table>
<p>Except for the <i>random</i> module, which supports Japanese, all the help for modules is available in English only.
<p><i><b>Note</b>: if you need support for other languages, please contact <a href="mailto:jfontain@free.fr">me</a>.</i>
<h3><a name="commandline"></a>6. Command line</h3>
<h4><a name="mainarguments"></a>6.1. Main arguments</h4>
<p>Launching moodss is very simple:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ moodss
</pre></td><tr></table>
<p>or
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ wish moodss
</pre></td><tr></table>
<p>if the Tcl/Tk wish interpreter is not found in your PATH. You can then dynamically load modules from the File menu.
<p>You can also just pass one or more data module names as parameters, as in:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ wish moodss random
</pre></td><tr></table>
<p>or, for 2 modules at once:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ wish moodss ps cpustats
</pre></td><tr></table>
<p>You can specify the same module more than once and with different arguments in the command line:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ wish moodss ps -r host.domain ps -r otherhost.domain
</pre></td><tr></table>
<p>When several modules of the same type are passed as argument, the initial data tables feature the module name followed by a number as title. For example <i>"ps<2>"</i>. If the module provides an identifier string, that text will be used instead, as in <i>"ps(host.domain)"</i>. Data cell labels include the module identifier or numbered module name as well, for proper identification.
<p>You may optionally specify a poll time in seconds using:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ wish moodss -p 25 random
</pre></td><tr></table>
<p>Note that when all the specified modules are asynchronous, the poll time option specifies the preferred interval for graph viewers.
<p>Once saved through the File Save menus (for example in dashboard.moo), the dashboard can be retrieved and loaded using:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ wish moodss -f save.moo
</pre></td><tr></table>
<p>which would result in the same modules being loaded, the same viewers displayed at the same positions and sizes, the same poll time being used, as well at the same application window size. New modules data displays can be added at any latter time to existing dashboards by specifying modules on the command line after the -f (--file) switch / value pair.
<p>Command line options include:<ul>
<li><b>--debug</b>: set verbose reporting when module errors occur
<li><b>-f</b> (or <b>--file</b>): specify a dashboard file name
<li><b>-h</b> (or <b>--help</b>): display some help text and exit
<li><b>-geometry</b>: set the initial geometry of the main window (a la X window)
<li><b>-p</b> (or <b>--poll-time</b>): specify a poll time in seconds
<li><b>-r</b> (or <b>--read-only</b>): disable viewer creation, editing, ...
<li><b>-S</b> (or <b>--static</b>): disable internal window manager sizing and moving
<li><b>--show-modules</b>: discover valid moodss modules, show their directory location(s) and exit
<li><b>--version</b>: output version information and exit
</ul>
<p>Moodss command line options must appear before any module name appears on the command line, so as not to interfere with the module options.
<p>In debug mode, when errors occur within the module namespace body or initialize procedure, the error message (either in text output when loading the module from the command line, or in a message window when dynamically loading the module) is followed by a Tcl stack trace of what was in progress when the error occurred (see the Tcl <i>error</i> manual page for further information).
<h4><a name="modulearguments"></a>6.2. Module arguments</h4>
<p>Module themselves can take options (if programmed to do so, see <a href="#initialization">module initialization</a>), through command line arguments placed right after the module name and before the next module name, if any.
<p>For example, the following command:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ moodss -p 15 random --asynchronous arp --remote jdoe@foo.bar --numeric route --numeric
</pre></td><tr></table>
<p>causes the <i>random</i> module to update asynchronously, the <i>arp</i> module to collect data from the <i>foo.bar</i> host under the <i>jdoe</i> login name and not attempt to lookup symbolic names for hosts, with the last module <i>route</i> doing the same.
<p>Note the setting the application poll time to 15 seconds does not interfere with the module options.
<p>The moodss core checks the validity of module options according to the information provided by the module programmer. Any invalid option / value combination for the module is detected, reported on the standard error channel before the application exits.
<p>Finally, it is always possible to determine the valid options for a module, using the following command:
<table bgcolor="#DFDFDF" width="100%"><tr><td><pre>
$ moodss module --help
</pre></td><tr></table>
<h3><a name="core.configuration"></a>7. Dashboard configuration</h3>
<p>All configuration parameters of a dashboard can be set using the following interface:
<p><center><img src="moodss6.gif" alt="configuration dialog box"></center>
<p>The dashboard configuration dialog box allows the user to change global settings for the current dashboard. This data is stored along when saving the configuration to a dashboard file (see <a href="#menus.file.save">Save</a> menu).
<p>Changing configuration choices do not affect the <a href="#core.preferences">Preferences</a> choices, which are used as initial values the first time the user modifies the configuration. Configuration settings have a higher priority than preferences settings, but are lost when not saved in a dashboard.
<p>Configuration entry is done through pages organized in a browsable hierarchical tree, always visible on the left side of the configuration dialog box (see picture above).
<p>After selection of the category from the tree on the left, a related dialog interface appears, which may or may not allow immediately applying new data values.
<br>Clicking on the OK button results in the current configuration data to be saved in memory. It will be stored in the dashboard file when requested (see File <a href="#menus.file.save">Save</a> and <a href="#menus.file.saveas">Save as</a> menus).
<p>Specific help can always be accessed by clicking on the bottom <b>Help</b> button when in a configuration page.
<h4><a name="configuration.application"></a>7.1. Application</h4>
<p>The canvas is the data viewers background area, and its configuration (size, color, ...) can be changed as described below.
<h5><a name="configuration.application.size"></a>7.1.1. Size</a></h5>
<p>The canvas width and height can be changed so that all the different tables and viewers that the dashboard comprises can fit nicely within the viewing space.
<br>It is also possible to make the canvas size automatically scale as the main window is resized by the user. In this case, scrollbars are displayed only when necessary, so that all displayed objects (tables, viewers, ...) can always be reached.
<p>The default is automatic scaling.
<p>The size is immediately updated when clicking on the <b>Apply</b> button.
<h5><a name="configuration.application.background"></a>7.1.2. Background</a></h5>
<p>The dashboard background color can be changed, either globally or per page if there are any. Similarly, a background image can also be used as background, globally or per page.
<br><i><b>Note</b>: the only format supported at this time for background images is GIF (with transparency).</i>
<p>If the current dashboard includes pages, there are displayed in the right side of the configuration dialog box, with the current page selected (see screenshot above for an example).
<p>When clicking of the <b>Color</b> button, a new dialog box opens, which allows the choice of a new color. If the image file option is selected, clicking the <b>Choose</b> button opens a file selector dialog box, where an image file can be picked. The image can either be centered in the display or placed at the top left corner.
<br><i><b>Note</b>: when the image is centered, its position is automatically updated every time the dashboard is resized.</i>
<p>The small display of the right side is a scaled-down view of the current application window. It gives an idea of the appearance of the display using selected background color, image and position.
<p>The background color, image and position are immediately updated when clicking on the <b>Apply</b> button.
<h4><a name="configuration.viewers"></a></a>7.2. Viewers</h4>
<p>The viewers are used for viewing table data, and their configuration (colors, ...) can be changed as described below.
<h5><a name="configuration.viewers.colors"></a>7.2.1. Colors</a></h5>
<p>These are the colors of viewer elements. For each viewer that needs different colors for displaying data cell elements (such as graphs, pie charts, ...), each new element uses the next color in the sequence (wraps around if necessary).
<p><i>Advice</i>: adjacent colors should be very different, colors should be visible on a black background.
<p><i>Note</i>: in a future version, creating, deleting and moving colors in the sequence will be possible.
<h5><a name="configuration.viewers.graphs"></a>7.2.2. Graphs</a></h5>
<p>The number of samples (on the X axis) can be changed for data graph viewers. The more samples, the wider the X axis and thus the longer the visible data time span.
<p>By default, the Y axis scales automatically with its minimum and maximum values set to those of all plotted data points, for maximum precision. Optionally, a value of <b>0</b> can be fixed for the Y axis minimum.
<p>It is also possible to set the angle of the X axis (date and time) labels (from the slanted 45 degrees to the default vertical 90 degrees).
<p>The background color of the plot area can be chosen for all graph viewers in the dashboard, so that, for example, a printed version looks better (also see the <a href="#configuration.viewers.colors">colors</a> configuration for setting the color choices for the displayed elements).
<p>It is possible to display or hide a grid in the plot area for all graph viewers in the dashboard, state which can be independently overridden from the popup menu in a graph viewer.
<p>Finally, the position of labels of data cells, in graph and bar chart viewers, can be set. This will be the default position for newly created viewers, although the position can be overridden per viewer from a popup menu. The available positions are <b>right</b> (the default), <b>bottom</b>, <b>left</b> and <b>top</b>, all relative to the graphical part of the viewer.
<p>These settings can be immediately applied to existing graphs by clicking the <b>Apply</b> button.
<h5><a name="configuration.viewers.pies"></a>7.2.3. Pies</a></h5>
<p>The labeler type for data pie viewers can be changed as follows:<ul>
<li>current value labels can be displayed next to corresponding slices (<b>peripheral</b> style)
<li>or next to the corresponding text labels (<b>box</b> style)
</ul>
<p>The selected type will not be used for existing pies but for newly created ones.
<h5><a name="configuration.viewers.tables"></a>7.2.4. Tables</a></h5>
<p>In database history mode, set the maximum number of displayed rows (see <a href="#viewers.tables">tables</a>).
<h5><a name="configuration.viewers.cells"></a>7.2.5. Cells</a></h5>
<p>One can choose whether module names or identifiers are displayed in cell labels in viewers (such as graphs, pies, tables, ...).
<br>For example, when there is only one module loaded, or several modules but with specific and easily recognizable data cell labels, it may not be necessary for data cell labels to be prefixed with the module name in viewers.
<h3><a name="core.preferences"></a>8. Preferences</h3>
<p>The preferences dialog box is used to set application-wide settings for the current user, and is also used to preset default configuration values for dashboards.
<br>It is very similar to the <a href="#core.configuration">dashboard configuration</a> dialog box, except that it includes more categories.
<br>The settings are saved in a global file (known as an <i>rc</i> file to UNIX people), used to initialize global configuration variables when the application is started. Since this file is stored in the user home directory (on a UNIX system), it provides a way for a user to customize the look, behavior, ... of the moodss application in a permanent manner.
<p>Some preferences choices, when validated, are not immediately taken into account: the application needs to be restarted for changes to take effect.
<br><i><b>Note</b>: this is a new behavior since moodss version 18.4.</i>
<p>On UNIX systems, preferences data is saved in each user home directory under the <i>rc</i> file named <i>.moodssrc</i>.<br>
On Windows, data is saved in <i>C:\.moodssrc</i> (by default, but depends on the <i>HOME</i> variable).
<p>After selection of the category from the tree on the left, a related dialog interface appears on the right side of the dialog box.
<br>Help is provided for each interface.
<br>Clicking on the <b>OK</b> button results in the preferences data to be written to the <i>rc</i> file.
<h4><a name="preferences.application"></a>8.1. Application</h4>
<h5><a name="preferences.application.size"></a>8.1.1. Size</a></h5>
<p>Sets the default size for dashboards (see configuration <a href="#configuration.application.size">size</a> section).
<h5><a name="preferences.application.colors"></a>8.1.2. Colors</a></h5>
<p>Sets the default background color for dashboards (also see configuration <a href="#configuration.application.background">background</a> section).
<h5><a name="preferences.application.fonts"></a>8.1.3. Fonts</a></h5>
<p>You can choose the font family and its size, to be used globally in the user interface, for menus, viewers, ... Every time another family or size is selected, the text area below the drop down menus is updated using the new font, so that the user can evaluate the change.
<h5><a name="preferences.application.printing"></a>8.1.4. Printing</a></h5>
<p>The canvas area can be printed in the Postscript data format.<br>
The default behavior when printing can be set to either a printer or a file, but can always be overridden in the print dialog box launched when actually printing.
<br>Various parameters, such as orientation, palette and paper size can be set.
<p>The print command typically reads the Postscript data from its standard input and redirects it to the specified printer (for example, on UNIX, 'lpr -Pacme' will print the canvas area on the "acme" printer.
<br>By default, the command is set to 'lpr -P%P', which by including the <em>%P</em> generic printer name tag allows the user to pick the printer from a list (drawn from the <i>/etc/printcap</i> database) at printing time.
<p>When printing to a file, you may choose its default location and name with the file browser. Note that it can be overridden in the print dialog box launched when actually printing.
<h5><a name="preferences.application.pages"></a>8.1.5. Pages</a></h5>
<p>When pages are used (see <a href="#menus.edit.newpage">New page</a> menu), the user can choose whether the pages tabs are positioned on the <i>top</i> or the <i>bottom</i> side of the pages.
<h5><a name="preferences.application.database"></a>8.1.6. Database</h5>
<p>If you want the moodss application or the moomps daemon to record data cell values in a history database, set the following options:
<!-- the following list is the same as in the database HTML documentation -->
<ul>
<li><b>file</b>: the single file holding complete data accessed by the SQLite library (that is the only parameter needed by the SQLite library). By default, it is <i>moodss.dat</i> in the home directory of the current user.
<li><b>dsn</b>: Data Source Name, if specified, means that database access is done via ODBC, which requires the <i>tclodbc</i> package to be installed. If not specified, native MySQL database access is used, which requires the <i>mysqltcl</i> package library to be installed.
<li><b>host</b>: the database server host name, or IP address <i>(not allowed in ODBC mode)</i>. Use <i>localhost</i> for socket based access (also see MySQL documentation).
<li><b>password</b>: the password used to connect to the database (also see <i>user</i>). <i><b>Note</b>: it is stored in clear, so only allowing access to the moomps <b>preferences</b> file from the <b>root</b> account is highly recommended.</i>
<li><b>port</b>: the port number corresponding to the database service <i>(not allowed in ODBC mode)</i>.
<li><b>user</b>: the user name used to connect to the database (also see <i>password</i>).
<li><b>database</b>: the MySQL database name for the MySQL native driver <i>(<b>moodss</b> by default, not allowed in ODBC mode)</i>.
<li><b>SQL trace</b>: when set, all SQL statements and queries are either printed on the terminal where moodss was launched, or in the system log, for the moomps daemon (<i>off by default, available on UNIX platforms only</i>).
</ul>
<p>Note that no changes are allowed if there is a current connection to the database (storing some data cells history). Also the <b>moomps</b> daemon, if running, must be restarted to take any change into account (also see its <a href="#preferences.moomps">configuration</a>).
<h5><a name="preferences.application.trace"></a>8.1.7. Trace</h5>
<p>The number of rows in the <a href="#menus.view.trace">trace</a> window can be set (it is <i>20</i> by default).
<br><i>Note</i>: the new value will not be taken into account immediately but the next time the application is started.
<h4><a name="preferences.viewers"></a></a>8.2. Viewers</h4>
<p>Sets the default configuration for viewers (see configuration <a href="#configuration.viewers">viewers</a> section).
<h5><a name="preferences.viewers.colors"></a>8.2.1. Colors</a></h5>
<p>See configuration <a href="#configuration.viewers.colors">colors</a> section.
<h5><a name="preferences.viewers.graphs"></a>8.2.2. Graphs</a></h5>
<p>See configuration <a href="#configuration.viewers.graphs">graphs</a> section.
<h5><a name="preferences.viewers.pies"></a>8.2.3. Pies</a></h5>
<p>See configuration <a href="#configuration.viewers.pies">pies</a> section.
<h5><a name="preferences.viewers.tables"></a>8.2.4. Tables</a></h5>
<p>See configuration <a href="#configuration.viewers.tables">tables</a> section.
<h5><a name="preferences.viewers.cells"></a>8.2.5. Cells</a></h5>
<p>See configuration <a href="#configuration.viewers.cells">cells</a> section.
<h4><a name="preferences.thresholds"></a>8.3. Thresholds</h4>
<h5><a name="preferences.thresholds.email"></a>8.3.1. Email</h5>
<p>When a threshold event occurs, an email alert message can be sent (see <a href="#menus.edit.thresholds">thresholds</a>).
<p>Proper identification is required so that the originator of the message (the <i>From</i> address field in an email message) is known. Use your own email address or another email address (such as <i>moodss@your.domain.com</i>) that you control.
<br>In any case, the <b>From address</b> field must contain a valid email address.
<br>Your user name is used by default.
<br>When closing the dialog box or moving to another section, the syntax of the email address is checked and errors, if any, reported in a message box.
<p>Sending email requires at least one <b>Outgoing mail SMTP server</b>. Input the one that you use for sending your emails (check your browser or email software current configuration), or any other valid SMTP address (consult your system administrator in case of doubt).
<br>You may enter additional servers that will be used as backups of the main server in case it fails. Keep pressing the <Enter> key to append servers to the list. To remove a server from the list, simply empty its list cell using the usual editing keys.<br>
The local host (<i>127.0.0.1</i> address) is used by default as the main SMTP server.
<p>The mail message is built with a default <b>subject</b> and <b>body</b>, used for all thresholds for which the message has not been customized (see <a href="#menus.edit.thresholds">thresholds</a> dialog box). The subject line and body text can include % substitutions, as described in the thresholds <a href="#menus.edit.thresholds.script">script</a> section.
<br>Depressing the <b>default</b> button restores the subject and boby to their application hard coded default.
<h5><a name="preferences.thresholds.trace"></a>8.3.2. Trace</h5>
<p>When a threshold condition occurs, a summary is sent to the trace module (visible via its window if it is displayed or by its table(s) if it is loaded as a module). This is the behavior by default, which can be turned off from this preferences page.
<h4><a name="preferences.moomps"></a>8.4. Daemon (moomps)</h4>
<p><i>(only available on UNIX platforms)</i>
<p>The moomps daemon preferences file location can be changed from the <i>/etc/moomps/rc</i> default value. You must have write rights to the chosen file and its directory, as determined for the current user (generally <i>root</i> as traditionally used for configuring daemons). Error messages are appropriately displayed when this is not the case.
<p>When the preferences are validated, all moomps relevant data will be written to the chosen file in XML format. You may enter no file name by clearing the textual entry space.
<p>The daemon preferences file is saved with write and read rights strictly restricted to the current user, as sensitive information, such as database passwords, can be stored in it.
<h3><a name="future"></a>9. Future developments</h3>
<p>Please look at the TODO file (at least present in the source distribution).
<p>I welcome any suggestion for new features that you may need in your specific use of moodss.
<h3><a name="support"></a>10. Support</h3>
<p>Bugs, questions, patches, ... should be reported using the SourceForge interface to the moodss project, at <a href="http://sourceforge.net/projects/moodss/">http://sourceforge.net/projects/moodss/</a>. This is the most efficient way to get your request processed, tracked, recorded, and made available to other moodss users.
<p>Alternately, you may post requests on the <a href="news:comp.lang.tcl">comp.lang.tcl</a> newsgroup or email <a href="mailto:jfontain@free.fr">jfontain@free.fr</a>.
<h3><a name="misc"></a>11. Miscellaneous information</h3>
<p>For downloading Tcl software (such as stooop, scwoop, tkpiechart, ...), many Red Hat rpm packages, visit my home page at <a href="http://jfontain.free.fr/">http://jfontain.free.fr/</a>.
<p>You may also find more information, such as reviews, links, examples, ... in the moodss (<a href="http://moodss.sourceforge.net/">http://moodss.sourceforge.net/</a>) and MySQL (<a href="http://jfontain.free.fr/mysql/">http://jfontain.free.fr/mysql/</a>) pages.
</body>
</html>
|
