DHIST Plotting Package for RCS
    ==============================

 R. Michaels,   Nov, 2001

 I. PURPOSE
 ~~~~~~~~~~~

     To make a series of plots of histograms or graphs that 
  exist in a TMapFile.  To allow the user to easily turn on and
  off which histgrams to display.  Using an ``expert mode''
  one also has control over how many histograms are put in
  a canvas, whether they are linear or log scale, and the
  update frequency of the display.
     Note, this code does not produce the histogram.  The
  producer must be a seperate code that makes the TMapFile.

 
 II. USAGE
 ~~~~~~~~~~
 
     First the expert should setup the file 'hist_opt', this
  is described below.
     Next one uses the shell script ./dhist.  This launches
  two codes: 1) 'dhistgui', which is a compiled executible that
  provides a simple non-expert interface, and 2) root macro 
  'dhist.macro' is launched using rootn.exe.  If using root version
  3 or higher, one must use rootn.exe.  For earlier versions of
  root, use 'root' instead of rootn.exe
     The dhist.macro loops over the contents of the TMapFile
  and displays the histograms, under the control of the hist_opt
  file.  The dhistgui will over-write the hist_opt file if it's
  buttons are clicked.
     The dhistgui interface is fairly obvious.  Clicking on and
  off the check buttons will enable and disable the pages of 
  histograms.  The characters displayed are the names of the 
  histograms (first call argument in TH1F c'tor).  Note, the
  objects that are plotted only need to derive from TH1F, so
  this means also TH2F can be plotted.  Pressing "Quit" button
  in dhistgui will make dhistgui and will tell the dhist.macro
  to quit at the end of its current cycle.  One must then type
  ".q" in the rootn.exe shell, in the window where on originally
  typed ./dhist, to quit.
      If you want to test this code, use the executible 'testin',
  which produces a map file "histo.map" in the same directory.
  If you use 'testin', I suggest you wait until I prints out
  the first time before starting dhist, i.e. wait until it writes
  out histo.map (about 20 seconds).


 III. hist_opt CONTROL
 ~~~~~~~~~~~~~~~~~~~~~

  Experts only need to know this.
  dhist.macro uses 'hist_opt' file to define the objects to plot, 
  and layout properties.
  hist_opt syntax:
  First two lines control the flow.  Reads one integer and ignores 
  rest of line
  1st line = on/off flag.  1 = on,  0 = quit
  2nd line = wait interval, time to wait between plots (approx seconds)
  Next N lines are histograms or TGraphs with the syntax:
  First entry = name of object (first parameter of TH1F or TH2F c'tor)
  (NOTE: For TGraphs the first character of the object must be 'g'.
  All other objects are assumed to be histograms, i.e. derived from TH1F.
  Example:  'gMyPlot' is a TGraph, while 'h441' is a histogram.)
  2nd entry = flag to decide if linear or log scale. 
       0 = lin (default), 1 = log
  3rd entry = page-layout  
      1 = 1 plot on canvas, 2 = 1x2, 3 = 1x3, 4 = 2x2, 6 = 2x3
  4th entry = flag to turn on(1) or off(0) the page.
  Example of hist_opt file:
    1       <- 1(0) means continue(quit)
    4        approx seconds to wait in display
    h4      0   1   1  object name, log(1)/lin(0), page-layout, page-on/off
    h21     0   1   0  <- h21 on one page which is turned off 
    h24     1   2   1  <- this page has 2 histograms, each log scale.
    h25     1          


 IV.  CONTENTS
 ~~~~~~~~~~~~~~~
 
     The contents of this directory are shown below.  Feel
  free to modify these things, but keep backups.  I also have
  backups.  Let me know if you make a substantial change, or
  if you have a problem

    Makefile   -- to compile the dhistgui and testin executibles

    rcs_dhist.C      -
    THaDhistCtl.C      -  These 3 comprise the dhistgui code.
    THaDhistCtl.h    -

    test_input.C  -- source code for 'testin'

    dhist  -- shell script to launch everything.

    dhist.macro  -- root macro that does the plotting
 
    hist_opt  -- control file to setup up and control the
                 dhist.macro
    hist_opt_save1 - a backup of hist_opt.  Good idea to
               keep a backup since various mistakes can
               ruin hist_opt


 V. APPENDIX - notes
 ~~~~~~~~~~~~~~~~~~~~

 Ting's prescription 
 see jlabs1:/home/rom/rcs/decode_roc4_onl.cpp
 You must get the Mapped Memory region correct.  It changes, I don't 
 know why.


// setting up ROOT

   TROOT simple("simple","Test of online histogramming");

// Create a new memory mapped file. The memory mapped file
// can be opened in another process on the same machine and
// the objects stored in it can be accessed.

// For this technique to work, you will need to find the ROOT-preferred
// map address. Start a ROOT session:
//
// shell> root
// root> m = TMapFile::Create("dummy.map","RECREATE", 10000000)
// root> m->Print()
// Memory mapped file:     dummy.map
// Title:
// Option:                 CREATE
// Mapped Memory region:   0x40c2b000 - 0x415b5000 (9.54 MB)
// Current breakval:       0x40c32000
// root> .q
// shell> rm dummy.map

// 10000000 is the map size in byte you want to create. Then you set
// map address starting from what the Mapped Memory region tells you.

   TMapFile::SetMapAddress(0x40c2b000);
   TMapFile *mfile = TMapFile::Create("hadc.map","RECREATE", 10000000,
                     "memory mapped file with histograms");