Introduction
Versions for UNIX machines, for MacOS and for Windows95 or WindowsNT are available. Most of the source code is identical for all platforms, only the directory srgp contains machine specific files, which are indicated either with _MAC, _Win , _X, or in one case _MAC_X. All programs use a modified version of SUIT (the "Simple User Interface Toolkit" from the University of Virginia) as GUI. SUIT has been ported to Windows95/Windows NT, but has still a problem with the handling of color, which results in a display that is less pleasing than that at the other platforms.
Directory structure
The source directory structure is similar for the different platforms. All files are stored in a single directory : simdaq3. The sources are in the following subdirectories :
Includes : common include files
SimdaqCplus : SIMDAQ-C++ source
srgp : SRGP library, low level graphics
suit : SUIT library : GUI
histo : histogram display routines
Histoview (UNIX : histoviewdir) : histogram dump file viewer
Histodemo (UNIX : histodemodir) : program demonstrating usage of histogramming
ROBsPerRoI (UNIX : ROBsPerRoIdir) : program for a/o computing look-up
tables
TrigDump2New : Tdumpparser program for conversion of "TrigDump" files
into the format required for SIMDAQ-C++
The TrigDump2New directory and its contents are not supplied in the simdaq3.tar.Z, simdaq3.sea.hqx or simdaq3.zip file, but in TrigDump2New.tar.Z, TrigDump2New.sea.hqx or TParser.zip. For the MacOS and Windows platforms the project files for the Tdumpparser program are also contained in the separate file. The directory needs to be placed in the simdaq3 directory.
The file name extensions for C++ code are different for the three platforms : for UNIX .C is required, for MacOS .Cp is used, while for Windows .Cpp is used (with the UNIX shell scripts domv... the extensions can be modified)
Names of input and output files
The configuration file name is assumed to be "config.new" for simdaq and "config-tdump.new" for Tdumpparser, the name of the input physics file to be "physics.new" in the case of simdaq and "tdump_I28351.data" in the case of Tdumpparser, while the name of the template file is assumed to be "physevents.tmpl". The histoview program assumes the availability of an input file with the name "results.dmp". When internal physics event generation is used simdaq reads the look-up table, relating RoI position and type to ROBs, from a file with the name "ROBHitFile". The trigger menu data comes from a file with a name specified in the configuration file. Some of the file names can be specified as command line arguments in the UNIX version (see below). The name of the physics file can also be specified in the configuration file.
Lay-out graphical user interface
The lay-out of the graphical user interface (implemented with SUIT) can be changed interactively during run-time and is stored in a file with a name equal to the name of the program with the extension ".sui".
For all programs .sui files have been supplied. The size of the window is relatively small, and can be changed by modifying the two lines in the beginning of the .sui file specifying the size. Note that when no .sui file is found the various objects ("widgets") are placed at random positions and with default sizes in the window.
A widget can be selected or deselected by clicking it while at the same time pressing the control and shift keys. The widget can then be moved by dragging or resized by dragging one of the handles it while pressing the control and shift keys.
These are the command keys that are available (list taken from the SUIT manual) :
shift-ctrl-M invokes the SUIT menu, which contains
most of the functions below
shift-ctrl-C change a widget's display style
shift-ctrl-A lines up selected widgets by tops,
bottoms, etc.
shift-ctrl-B selected widget goes behind all
others
shift-ctrl-F selected widget goes in front of
all others
shift-ctrl-S selects all widgets if cursor is
over no widget
shift-ctrl-R redraw repaints all widgets
shift-ctrl-E examine and alter a widget's properties
shift-ctrl-I prints information about a widget
in a dialog
shift-ctrl-O opens up a parent widget so that
the children may be accessed
shift-ctrl-K closes a parent widget that was
opened with shift-ctrl-O
shift-ctrl-N creates a new SUIT object on the
fly
shift-ctrl-X destroys a SUIT widget
shift-ctrl-V prints the version of SUIT you are
using
shift-ctrl-D creates a copy of a SUIT widget
shift-ctrl-Q save the ".sui" file and leave the
application
shift-ctrl-W write the ".sui file" without exiting
SUIT has very complete documentation, which is available via :
ftp://uvacs.cs.virginia.edu/pub/suit/distribution/JustDocs
UNIX version
The programs function as they should when compiled with gcc for HP-UX A.09.01, HP- UX B.10.20 A, SUNOS 4.1.2 and on MachTen 4.0.3 (UNIX for Apple Macintosh from Tenon) UNIX systems (with an older version of gcc (version 2.6.3) a problem was found with incorrect inialization of a static data member, in this case with the result of calling "new". By setting the variable to NULL and calling "new" in the constructor when the data member equals NULL the problem seems to have disappeared).
Each source directory either contains a makefile or a shell script (with name domake) for compilation of the sources and linking of the object code or building of a library. Three libraries need to be built : libsrgp.a, libSUIT.a and libhisto.a.
The makefiles probably can be used without modification on most UNIX machines, although on some UNIX installations it may be necessary to add new paths for the search for include files and for library files. The simdaq3 directory contains the following shell scripts :
domake : build libraries and simdaq, compilation with -g option (debugger
can be used)
domakeopt : build optimized versions of libraries and simdaq, compilation
with -O3 option
domkall : build all programs. compilation with -g option
rmobjects : remove all .o files in the srgp, suit, histo and simdaqCplus
directories
rmbins : remove all libraries and executables
dodebug : start mxgdb (public domain graphical front-end for gdb) and
load simdaq
The simdaq and Tdumpparser programs accept command line arguments :
simdaq -c "name of configuration file" -p "name of physics file",
Tdumpparser -c "name of configuration file" -p "name of physics file" -t "name of template file"
MacOS version
For the MacOS version the Metrowerks Codewarrior CW Pro 1 development environment is used. The self-extracting and binhexed archive, that can be unpacked with Stuffit Expander, contains sources, ".sui" files, example input files and projects for PowerPC based machines (on demand projects for 68k based machines can be supplied). The archive also contains projects for Windows95 or WindowsNT machines for cross-compilation on a MacOS machine and ".sui" files and example input files in PC format .
Windows95 / WindowsNT version
The zip archive contains sources, ".sui" files, example input files and project files for Microsoft Visual C++ version 4.01 and Codewarrior CW Pro 1 (Windows version).
Documentation
Documentation is a "work in progress". The latest version will be available via the web soon. It is is intended to make the documentation also available as tar file with all relevant html files and as Postcript file.
Further remarks
File and terminal I/O are done with the standard "C" functions, as defined in the stdio.h and stdlib.h files. The STL (Standard Template Library) is not used, although it could have been applied e.g. for the list management required. This approach is due to the use of the ThinkC development environment on the Macintosh in the initial phase of the program development 5 years ago. However, this has resulted in source code that can be used on all platforms without modification and that compiles quickly, in particular on non-UNIX platforms. Furthermore run-time efficiency is a major concern and list management is a critical part of SIMDAQ-C++ in that respect. It is judged that private solutions are to be preferred, the more so as they are straightforward to implement.
At several places in the programs more elegant solutions are possible than the choices made for the current implementations. However, speed of coding and understandability of the code has been given priority. This has resulted in lengthy code at some places and also in accessing variables ("fields") of objects directly in stead of the use of (inline) "Get" and "Set" methods.
Some header and source files contain code for
more than one object, and hence the location of the code of these objects
cannot be found immediately from the filenames. Some cleaning up is possible,
but has not been given priority, as the code with a browser easily can
be located. Visual C++ and Metrowerks CodeWarrior both feature a built-in
browser.