Index: /trunk/MagicSoft/Mars/Changelog
===================================================================
--- /trunk/MagicSoft/Mars/Changelog	(revision 7458)
+++ /trunk/MagicSoft/Mars/Changelog	(revision 7459)
@@ -18,4 +18,18 @@
 
                                                  -*-*- END OF LINE -*-*-
+
+  2006/01/10 Daniela Dorner
+
+     * datacenter/macros/buildsequenceentries.C, checkfileavail.C, 
+       checkstardone.C, doexclusions.C, fillcalib.C, filldotraw.C, 
+       filldotrbk.C, filldotrun.C, fillganymed.C, fillsignal.C, 
+       fillsinope.C, fillstar.C, findcacofiles.C, getdolist.C, 
+       insertcacofile.C, insertdataset.C, insertdate.C, 
+       insertsequence.C, resetallruns.C, resetcolumn.C, setstatus.C, 
+       setupdb.C, writesequencefile.C: 
+       - updated and added documentation
+
+
+
  2005/12/21 Thomas Bretz
 
@@ -28,5 +42,5 @@
    * mbase/MTime.[h,cc]:
      - added algorithm to calculate week
-     
+
 
 
Index: /trunk/MagicSoft/Mars/datacenter/macros/buildsequenceentries.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/buildsequenceentries.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/buildsequenceentries.C	(revision 7459)
@@ -30,10 +30,48 @@
 //
 // to group the runs of one night into sequences, this marco:
-// - reads the runinformation of one night from the database
-// - group the runs into sets of following runs with the same conditions
-// - groups the runs in this sets to sequences such that each run belongs
-//   to the nearest (in time) calibration run
-// - check if the runs with the same runtype have the same calibration script
-//   and the same trigger tables
+//  - reads the runinformation of one night from the database
+//  - group the runs into sets of following runs with the same conditions
+//  - groups the runs in this sets to sequences such that each run belongs
+//    to the nearest (in time) calibration run
+//  - check if the runs with the same runtype have the same calibration script
+//    and the same trigger tables
+//  if sequence is okay:
+//  - check if in the range of the runnumbers of this sequence other sequences
+//    exist in the database
+//  if there are no sequences, insert the new sequence, else:
+//  - delete overlaping sequences
+//  if there's only one sequence in the same runnumber range:
+//  - check if the new and the old sequence are identical
+//    if they are identical, do nothing, if not, delete the old sequence and
+//    insert the new one
+//
+// remark: deleting sequences includes the following steps:
+// - delete entries from the tables Sequences, SequenceProcessStatus,
+//   Calibration and Star
+// - updating the sequence number (fSequenceFirst) in the table RunData
+// - remove the Sequence File, the calibrated data and the image files from
+//   the disk
+//
+// the macro can be executed either for all nights or for one single night
+// .x buildsequenceentries.C+( "datapath", "sequpath", Bool_t dummy=kTRUE)
+// .x buildsequenceentries.C+( "night", "datapath", "sequpath")
+//
+// the Bool_t dummy:
+//  kTRUE:  dummy-mode, i.e. nothing is inserted into the database, but the
+//          commands, that would be executed are returned
+//  kFALSE: the information is inserted into the database and the files of
+//          removed sequences is deleted
+// be careful with this option - for tests use always kTRUE
+//
+// TString datapath, TString sequpath:
+//  datapath: path, where the processed data is stored in the datacenter
+//  sequpath: path, where the sequence files are stored in the datacenter
+// the datapath (standard: /magic/data/) and the sequencepath (standard:
+// /magic/sequences) have to be given, that the sequence file, the
+// calibrated data and the star files can be removed, when an old sequence
+// has to be removed from the database
+//
+// If nothing failes 1 is returned. In the case of an error 0 is returned.
+// This is needed for the scripts that execute the macro.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -63,4 +101,5 @@
 Bool_t DeleteSequence(MSQLServer &serv, TString datapath, TString sequpath, Int_t sequ, Bool_t dummy)
 {
+    //queries to delete information from the database
     TString query1(Form("DELETE FROM Calibration WHERE fSequenceFirst=%d", sequ));
     TString query2(Form("DELETE FROM Star WHERE fSequenceFirst=%d", sequ));
@@ -69,4 +108,5 @@
     TString query5(Form("DELETE FROM Sequences WHERE fSequenceFirst=%d AND fManuallyChangedKEY=1", sequ));
 
+    //commands to delete files from the disk
     TString fname(Form("%s/%04d/sequence%08d.txt", sequpath.Data(),sequ/10000, sequ));
     TString command(Form("rm -r %s/callisto/%04d/%08d/", datapath.Data(), sequ/10000, sequ));
@@ -148,4 +188,6 @@
 }
 
+
+//check values, that can be different for different runtypes
 Bool_t CheckRuns(MSQLServer &serv, Int_t from, Int_t to, Int_t type)
 {
@@ -497,4 +539,7 @@
 }
 
+//
+// Handling new sequence (checking runs; checking for old sequence; inserting sequence, if everything is okay)
+//
 Bool_t NewSequence(MSQLServer &serv, TString datapath, TString sequpath, Int_t from, Int_t to, TList &sequlist, Bool_t dummy)
 {
@@ -564,4 +609,7 @@
 }
 
+//
+// Build Sequences in range of runs
+//
 Bool_t Process(MSQLServer &serv, TString datapath, TString sequpath, Int_t from, Int_t to,  TList &sequlist, Bool_t dummy)
 {
@@ -735,4 +783,7 @@
 
 
+//
+// Build Sequences for the night given by TString day
+//
 int buildsequenceentries(TString day, TString datapath, TString sequpath, Bool_t dummy=kTRUE)
 {
@@ -757,4 +808,5 @@
                             day.Data(), day.Data()));
 
+    //get all values from the database, that are relevant for building sequences
     TString query(Form("SELECT fRunNumber, fSourceKEY, fProjectKEY, fHvSettingsKEY,  fLightConditionsKEY, fDiscriminatorThresholdTableKEY, fTriggerDelayTableKEY FROM RunData WHERE %s AND fExcludedFDAKEY=1 order by fRunNumber", cond.Data()));
 
@@ -763,4 +815,7 @@
         return 0;
 
+    //build blocks of runs, which have the same values
+    //for each block the first and the last run are stored in a TExMap
+    //the values are checked with the help of an array of TStrings
     TString keys[6]= { "NULL", "NULL", "NULL", "NULL", "NULL", "NULL" };
     TString stop     = "NULL";
@@ -795,5 +850,5 @@
 
             keys[i-1]=value;
-            //hier einfuellen
+            //fill values into TExMap
             blocks.Add((ULong_t)blocks.GetSize(), (Long_t)runbegin, (Long_t)runend);
             runstart=(*row)[0];
@@ -806,5 +861,5 @@
     }
 
-    //und hier einfuellen (letzter wert)
+    //fill values into TExMap (last value)
     runbegin=atoi(runstart.Data());
     runend=atoi(runstop.Data());
@@ -812,8 +867,8 @@
 
 
+    //get list of current sequence of this night from the database and store it in sequlist
     TList sequlist;
     query=Form("SELECT fSequenceFirst FROM Sequences WHERE fManuallyChangedKEY=1 AND %s order by fSequenceFirst",
                cond.Data());
-
 //    cout << "Q: " << query << endl;
 
@@ -833,4 +888,5 @@
     Bool_t rc = kTRUE;
 
+    //build sequences in each block of runs
     Long_t key, val;
     TExMapIter nblocks(&blocks);
@@ -846,4 +902,7 @@
     }
 
+    //newly build or remaining sequences are removed from sequlist while building sequences
+    //delete sequences that remained in the list
+    //this is necessary if e.g. all runs of one old sequence have been excluded in the meantime
     TIter Next(&sequlist);
     TObject *obj = 0;
@@ -858,5 +917,7 @@
 }
 
-
+//
+// Build Sequences for all Nights
+//
 int buildsequenceentries(TString datapath, TString sequpath, Bool_t dummy=kTRUE)
 {
@@ -870,4 +931,5 @@
     }
 
+    //get all dates from the database
     TString query="SELECT fDate FROM SequenceBuildStatus";
 
@@ -876,4 +938,5 @@
         return 0;
 
+    //execute buildsequenceentries for all dates
     TString date;
     TSQLRow *row=0;
Index: /trunk/MagicSoft/Mars/datacenter/macros/checkfileavail.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/checkfileavail.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/checkfileavail.C	(revision 7459)
@@ -28,4 +28,19 @@
 // ================
 //
+// check the availability of the files of one sequence:
+// the script filesondisk has inserted the information (which files are on
+// disk into the database) and with this macro this information is checked
+// for the runs of one sequence
+//
+// executing the macro:
+//  .x checkfileavail.C+("sequencefile")
+// the sequencefile (including path) has to be given, as the macro retrieves
+// from there the runnumbers
+//
+// the macro returns 0, if a file is missing, and 1 if all files are there
+// the return value is checked by the script, that executes the macro
+//
+// this macro is very similar to the macro checkstardone.C
+//
 /////////////////////////////////////////////////////////////////////////////
 
@@ -43,4 +58,6 @@
 
 
+//check the value of a column for a run
+//if a file is not available, the column contains nothing (NULL) - this value is returned
 TString GetStatus(MSQLServer &serv, TEnv &rc, TString primary, TString table, TString column)
 {
@@ -89,6 +106,7 @@
     TEnv rc("steps.rc");
 
+    //reading runnumbers from Sequencefile
     TEnv sequ(sequencefile);
-
+    cout << "sequ file: " << sequencefile.Data() << endl;
     TString runs;
     runs = sequ.GetValue("Runs", "");
@@ -100,5 +118,6 @@
     }
 
-    cout << "sequ file: " << sequencefile.Data() << endl;
+    //getting runnumbers from database
+    //(not neccessary anymore -> can be changed)
     TString query(Form("SELECT fRunNumber FROM RunData WHERE fRunNumber in (%s)",
                        runs.Data()));
@@ -108,4 +127,8 @@
         cout << "Error - no run to check" << endl;
 
+    //check for each run the availability of files from the table RunProcessStatus
+    //the following columns have to be checked:
+    //fCCFileAvail, fCaCoFileAvail, fCaCoFileFound, fRawFileAvail, fTimingCorrection
+    //fTimingCorrection has to be checked, as only rawfiles with correct timing should be calibrated
     TSQLRow *row=0;
     while ((row = res->Next()))
@@ -113,4 +136,5 @@
         TString runno=(*row)[0];
         cout << "run#: " << runno << endl;
+        //if one value returns "" (i.e. column is NULL), 0 is returned
         if (GetStatus(serv, rc, runno, "RunProcessStatus", "fCCFileAvail")==""
             || GetStatus(serv, rc, runno, "RunProcessStatus", "fCaCoFileAvail")==""
@@ -121,4 +145,5 @@
             return 0;
     }
+    //if all values are okay (i.e. files are availabel), 1 is returned
     return 1;
 
Index: /trunk/MagicSoft/Mars/datacenter/macros/checkstardone.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/checkstardone.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/checkstardone.C	(revision 7459)
@@ -28,4 +28,18 @@
 // ===============
 //
+// check the availability of the star files for one sequence:
+// if star has been executed successfully, this information has been inserted
+// into the database (SequenceProcessStatus) with this macro this information
+// is checked 
+//
+// executing the macro:
+//  .x checkstardone.C+("sequencenumber")
+//
+// the macro returns 0, if for the sequence star is not done, and 1 if star
+// has been done
+// the return value is checked by the script, that executes the macro
+//
+// this macro is very similar to the macro checkfileavail.C
+//
 /////////////////////////////////////////////////////////////////////////////
 
@@ -43,4 +57,5 @@
 
 
+//check the value of a column for a sequence
 TString GetStatus(MSQLServer &serv, TEnv &rc, TString primary, TString table, TString column)
 {
@@ -55,5 +70,5 @@
     if (!res)
     {
-        cout << "Error - no run to check" << endl;
+        cout << "Error - no sequence to check" << endl;
         return "";
     }
@@ -84,4 +99,5 @@
     TEnv rc("steps.rc");
 
+    //check if fStar not NULL for sequence 
     if (GetStatus(serv, rc, datasetno, "SequenceProcessStatus", "fStar")=="")
         return 0;
Index: /trunk/MagicSoft/Mars/datacenter/macros/doexclusions.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/doexclusions.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/doexclusions.C	(revision 7459)
@@ -29,4 +29,28 @@
 // ==============
 //
+// this macro sets the ExcludedFDA flag for runs, that can be excluded
+// automatically
+// the information which runs have to be excluded is retrieved from the
+// resource file automatic-exclusions.rc
+//
+// the macro can be executed either for a night or for a range of runnumbers
+// or for all nights
+// .x doexclusions.C+("night")
+// .x doexclusions.C+(startrun,stoprun)
+// .x doexclusions.C+
+//
+// resource file: automatic-exclustions.rc
+// for each exclusion-reason there is one block of 6 lines in this file:
+// example for one exclusion-reason:
+//  #NumEventsSmaller10:                   (name of exclusion)
+//  key15.Column: fNumEvents               (name of the affected column)
+//  #key15.Join1:                          (name of column that has to 
+//  #key15.Join2:                                             be joined)
+//  key15.Cond: fNumEvents between 2 and 9 (condition that fulfils exclusion)
+//  #key15.SpecialRunCond:                 (special condition, if exclusion
+//                                          is needed only for certain runs)
+// if a value is not needed for an exclusion (like the joins and the special
+// condition in this example), the line is commented out
+//
 /////////////////////////////////////////////////////////////////////////////
 #include <iostream>
@@ -43,4 +67,5 @@
 using namespace std;
 
+//get minimum or maximum runnumber of the runs of a night
 int GetRunNumber(MSQLServer &serv, TString date, TString value)
 {
@@ -75,4 +100,5 @@
 }
 
+//get part of a query (left join of tables)
 TString GetJoin(TString table)
 {
@@ -99,4 +125,7 @@
     cout << "Connected to " << serv.GetName() << endl;
 
+    //if neither start- nor stoprun is given, the minimum and maximum runnumber
+    // is queried from the database to do the exclusions for all runs
+    // if a night is given for all runs of this night
     if (startrun==0 && stoprun==0)
     {
@@ -104,4 +133,5 @@
         stoprun=GetRunNumber(serv, date, "max");
     }
+    //check format of start- and stoprun
     if (startrun<0 || stoprun<0)
     {
@@ -112,6 +142,11 @@
         return 1;
 
+    //get the condition for the runnumber range
     TString runcond(Form("AND fRunNumber BETWEEN %d AND %d ", startrun, stoprun));
 
+    //get exclusions-reasons (stored in the table ExcludedFDA) from the database
+    //the exclusions which can be done automatically are marked with the flag fExcludedFDAAutomatic='yes'
+    //and with an importance (one run may be excluded for several reasons,
+    //the reason is chosen according to the importance)
     TString query="SELECT fExcludedFDAKEY from ExcludedFDA where fExcludedFDAAutomatic='yes'";
     TSQLResult *res = serv.Query(query);
@@ -122,7 +157,9 @@
     }
 
+    //update the exclusion-reasons for all runs
     TSQLRow *row=0;
     while ((row = res->Next()))
     {
+        //read in values from the resource file automatic-exclusions (explanation see above)
         TString key=(*row)[0];
         TString column=rc.GetValue("key"+key+".Column", "");
@@ -131,4 +168,5 @@
         TString border=rc.GetValue("key"+key+".SpecialRunCond", "");
 
+        //get importance of exclusion-reason from database
         TString query(Form("SELECT fExcludedFDAImportance from ExcludedFDA where fExcludedFDAKEY=%s ", key.Data()));
         TSQLResult *res = serv.Query(query);
@@ -143,4 +181,6 @@
         delete res;
 
+        //get current importance from database
+        //for the runs which match the exclusion-reason
         query="SELECT fRunNumber, fExcludedFDAImportance ";
         if (!column.IsNull())
@@ -173,8 +213,11 @@
         }
 
+        //compare new and old importance
+        //change or keep the exclusion-reason accordingly
         while ((row2 = res->Next()))
         {
             if (TString((*row2)[1]).IsNull() || atoi((*row2)[1])>newimp)
             {
+                //change exclusion-reason
                 TString query(Form("UPDATE RunData SET fExcludedFDAKEY=%s WHERE fRunNumber=%s",
                                    key.Data(), (*row2)[0]));
@@ -189,4 +232,5 @@
                 continue;
             }
+            //keep exclusion-reason
             cout << "run#: " << (*row2)[0] << " reason for exclusion is still the same" << endl;
         }
@@ -197,4 +241,5 @@
 }
 
+//run doexclusions for one night
 int doexclusions(TString date="NULL")
 {
Index: /trunk/MagicSoft/Mars/datacenter/macros/fillcalib.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/fillcalib.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/fillcalib.C	(revision 7459)
@@ -34,14 +34,16 @@
 // From this file the MBadPixelsCam and the MGeomCam is extracted. If
 // the geometry isn't found MGeomCamMagic is used as a default.
+// The bad pixel information and other information, extracted from the status
+// display, is inserted into the database in the table Calibration, which
+// stores the results from the calibration.
+// The corresponding sequence number is extracted from the filename...
+// FIXME: MSeqeuence should be stored in the calib-file?
 //
 // Usage:
-//   .x fillcalib.C("/data/MAGIC/Period014/calib00000.root", kTRUE)
+//  .x fillcalib.C("/magic/data/callisto/0004/00047421/calib00047421.root", kTRUE)
 //
 // The second argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
 // switched on and nothing will be written into the database. This is usefull
 // for tests.
-//
-// The corresponding sequence number is extracted from the filename...
-// FIXME: MSeqeuence should be stored in the calib-file?
 //
 // The macro can also be run without ACLiC but this is a lot slower...
@@ -106,4 +108,5 @@
 int Process(MSQLServer &serv, TString fname, Bool_t dummy)
 {
+    //getting number of unsuitable, unreliable and isolated pixel
     MBadPixelsCam badpix;
 
@@ -234,4 +237,5 @@
     cout << "  Mean Conv outer:   " << meanconvouter << endl;
 
+    //inserting or updating the information in the database
     TString query;
     if (!ExistStr(serv, "fSequenceFirst", "Calibration", seq))
Index: /trunk/MagicSoft/Mars/datacenter/macros/filldotraw.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/filldotraw.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/filldotraw.C	(revision 7459)
@@ -72,4 +72,5 @@
 using namespace std;
 
+//get key for a magic number
 Int_t MagicNumber(MSQLServer &serv, const MRawRunHeader &h)
 {
@@ -137,4 +138,5 @@
     MRawRunHeader h;
 
+    //read header either from root or from raw file
     if (fname.EndsWith(".root"))
         ReadRoot(fname, &h);
@@ -148,4 +150,5 @@
     }
 
+    //get key for the magic number
     const Int_t key = MagicNumber(serv, h);
     if (key<0)
@@ -204,4 +207,5 @@
     cout << endl;
 
+    //get date for the run to build path of the file
     TString query(Form("SELECT DATE_FORMAT(ADDDATE(fRunStart, Interval 13 HOUR), '%%Y/%%m/%%d') FROM RunData WHERE fRunNumber=%d",
                        runno));
@@ -239,4 +243,5 @@
     }
 
+    //check if there's only one file with this runno
     if (count!=1)
     {
Index: /trunk/MagicSoft/Mars/datacenter/macros/filldotrbk.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/filldotrbk.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/filldotrbk.C	(revision 7459)
@@ -32,13 +32,14 @@
 //
 // Usage:
-//   .x filldotrbk.C("/data/MAGIC/Period014", kTRUE)
-//
-// While the first argument is the directory in which all subdirectories where
-// searches for CC_*.rbk files. All these files were analysed and the runbook
+//   .x filldotrbk.C("/magic/subsystemdata/cc/", kTRUE)
+//
+// The first argument is the directory in which all subdirectories are
+// searched for CC_*.rbk files. All these files are analysed and the runbook
 // entries will be put into the DB, eg:
-//   "/data/MAGIC"                              would do it for all data
-//   "/data/MAGIC/Period019/ccdata"             would do it for one Period
-//   "/data/MAGIC/Period019/ccdata/2004_05_17"  would do it for a single day
-//   "/data/MAGIC/Period019/ccdata/file.rbk"    would do it for a single file
+//  "/magic/subsystemdata/cc"                  would do it for all data
+//  "/magic/subsystemdata/cc/2005"                  for one year
+//  "/magic/subsystemdata/cc/2005/11"               for one month
+//  "/magic/subsystemdata/cc/2005/11/11"            for a single day
+//  "/magic/subsystemdata/cc/2005/11/11/file.rbk"   for a single file
 //
 // The second argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
@@ -46,6 +47,6 @@
 // for tests.
 //
-// Before an antry is added its existance is checked... if it is added already
-// it is ignored.
+// Before an entry is added, its existance is checked... if it is already
+// in the database, it is ignored.
 //
 // The macro can also be run without ACLiC but this is a lot slower...
@@ -96,7 +97,5 @@
         }
     }
-
     delete res;
-
     return rc;
 }
@@ -105,4 +104,5 @@
 {
 
+    //check if entry is already in database
     if (ExistStr(serv, "fRunBookDate", "RunBook", date))
         return 0;
@@ -116,4 +116,5 @@
             entry.Remove(i--);
 
+    //insert entry into the database
     TString query("INSERT RunBook (fRunBookDate, fRunBookText) VALUES (\"");
     query += date;
@@ -178,4 +179,6 @@
         }
 */
+
+        //skip run statistics from old runbooks
         if (entry.Contains("MAGIC ELECTRONIC RUNBOOK")   ||
             entry.Contains("DATA RUN STATISTICS")        ||
@@ -220,7 +223,9 @@
     cout << endl;
 
+    //get all runbook files in path
     if (path.EndsWith(".rbk"))
         return process(serv, dummy, path);
 
+    //fill entries for each runbook file
     MDirIter Next(path, "CC_*.rbk", -1);
     while (1)
Index: /trunk/MagicSoft/Mars/datacenter/macros/filldotrun.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/filldotrun.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/filldotrun.C	(revision 7459)
@@ -46,8 +46,9 @@
 // searches for CC_*.run files. All these files were analysed and the run
 // info will be put into the DB, eg:
-//   "/data/MAGIC"                              would do it for all data
-//   "/data/MAGIC/Period019/ccdata"             would do it for one Period
-//   "/data/MAGIC/Period019/ccdata/2004_05_17"  would do it for a single day
-//   "/data/MAGIC/Period019/ccdata/file.run"    would do it for a single file
+//  "/magic/subsystemdata/cc"                  would do it for all data
+//  "/magic/subsystemdata/cc/2005"                  for one year
+//  "/magic/subsystemdata/cc/2005/11"               for one month
+//  "/magic/subsystemdata/cc/2005/11/11"            for a single day
+//  "/magic/subsystemdata/cc/2005/11/11/file.run"   for a single file
 //
 // The second argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
@@ -104,4 +105,6 @@
 }
 
+//get key for the value
+// if value is not existing, insert value and get key
 Int_t QueryNameKEY(MSQLServer &serv, Bool_t dummy, const char *col, const char *name, Bool_t insert=kTRUE)
 {
@@ -125,4 +128,5 @@
         return -1;
 
+    //insert new value
     query = Form("INSERT %s (f%sName) VALUES (\"%s\");", col, col, name);
 
Index: /trunk/MagicSoft/Mars/datacenter/macros/fillganymed.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/fillganymed.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/fillganymed.C	(revision 7459)
@@ -30,4 +30,18 @@
 // This macro is used to read the ganymed-output files.
 // These files are automatically called ganymed00000.root.
+// From MAlphaFitter and the Status Display the results from ganymed are
+// extracted an inserted into the database, where they are stored in the table
+// Ganymed.
+// The dataset number is extracted from the filename.
+//
+// Usage:
+//  .x fillganymed.C("/magic/data/ganymed/0000/0001/ganmymed0001.root", kTRUE)
+//
+// The second argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
+// switched on and nothing will be written into the database. This is usefull
+// for tests.
+//
+// Remark: Running it from the commandline looks like this:
+//   root -q -l -b fillganymed.C+\(\"filename\"\,kFALSE\) 2>&1 | tee file.log
 //
 // Make sure, that database and password are corretly set in a resource
@@ -96,4 +110,5 @@
     }
 
+    //get excess, signal, background events and the scale factor from MAlphaFitter
     MAlphaFitter *fit;
     file.GetObject("MAlphaFitter", fit);
@@ -113,4 +128,5 @@
     TString scale = Form("%5.2f", f);
 
+    //get effective ontime from the status display
     MStatusArray arr;
     if (arr.Read()<=0)
@@ -130,4 +146,5 @@
     Int_t tm = (Int_t)vstime->Integral();
 
+    //get dataset number from filename
     TString dataset = fname(TRegexp("ganymed[0-9]+[.]root$"));
     if (dataset.IsNull())
@@ -135,5 +152,4 @@
         cout << "WARNING - Could get dataset# from filename: " << fname << endl;
         return 0;
-    }
 
     Int_t ds = atoi(dataset.Data()+8);
@@ -152,4 +168,7 @@
 
 
+    //build query, insert information into the DB
+    //if entry is already existing: update query
+    //else: insert query
     TString query;
     if (!ExistStr(serv, "fDataSetNumber", "Ganymed", ds))
@@ -212,4 +231,5 @@
     cout << endl;
 
+    //process file
     return Process(serv, fname, dummy);
 }
Index: /trunk/MagicSoft/Mars/datacenter/macros/fillsignal.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/fillsignal.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/fillsignal.C	(revision 7459)
@@ -32,8 +32,11 @@
 // signal00000.root.
 //
-// From this file the Mean PedRms for the inner and outer camera is extracted.
+// From this file the mean pedrms, the mean signal and the pulse position
+// for the inner and outer camera is extracted and inserted into the database
+// in the table Calibration, where the results of callisto are stored.
+// The sequence number is extracted from the filename.
 //
 // Usage:
-//   .x fillsignal.C("/data/MAGIC/Period014/signal00000.root", kTRUE)
+//   .x fillsignal.C("/magic/data/callisto/0004/00047421/signal00047421.root", kTRUE)
 //
 // The second argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
@@ -171,4 +174,5 @@
     rmspul  = TMath::Nint(rmspul*100)/100.;
 
+    //get sequence number from the filename
     TString sequence = fname(TRegexp("signal[0-9]+[.]root$"));
     if (sequence.IsNull())
@@ -205,4 +209,8 @@
     cout << "  Rms  extracted  PulsePos " << rmsextpulpos    << endl;
 
+    //build query and insert information into the database
+    // here only a update query is built, as this macro is exexuted after
+    // the macro fillcalib.C in the script fillcallisto
+    // and so the table Calibration is always updated
     TString query = Form("UPDATE Calibration SET "
                          " fMeanPedRmsInner=%s,   fMeanPedRmsOuter=%s, "
@@ -248,4 +256,5 @@
     cout << endl;
 
+    //process file
     return Process(serv, fname, dummy);
 }
Index: /trunk/MagicSoft/Mars/datacenter/macros/fillsinope.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/fillsinope.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/fillsinope.C	(revision 7459)
@@ -30,4 +30,13 @@
 //
 // This macro is used to read the sinope output files sinope*.txt
+// For each run sinope is run twice: once for the data events and once for the
+// calibration events. The pulse position and height is checked. The output is
+// stored in a sinope*.root and a sinope*.txt file. The files for data events
+// are marked with -dat and the ones for calibration events with -cal.
+// From the txt files the result is extracted and inserted into the database
+// in the table DataCheck, which stores the datacheck results.
+// As the column names in the database differ only by the addition 'Interlaced'
+// which is given to columns corresponding to the calibration events, the
+// files can be processed with the same function.
 //
 // Usage:
@@ -87,8 +96,11 @@
     TEnv env(fname);
 
+    //build query
     TString query="UPDATE DataCheck SET ";
 
+    //array with part of column names
     TString values[9] = { "Events" , "HasSignal" , "HasPedestal" , "PositionSignal" , "PositionFWHM" , "PositionAsym" , "HeightSignal" , "HeightFWHM" , "HeightAsym" };
 
+    //get values from the file add them to query
     TString str;
     for (Int_t i=0 ; i<9 ; i++)
@@ -118,4 +130,5 @@
 
     cout << "Q: " << query << endl;
+    //insert information into db
     TSQLResult *res = serv.Query(query);
     if (!res)
@@ -146,4 +159,5 @@
     cout << endl;
 
+    //get date of run from database
     TString query(Form("SELECT DATE_FORMAT(ADDDATE(fRunStart, Interval 13 HOUR), '%%Y/%%m/%%d') FROM RunData WHERE fRunNumber=%d",
                        runno));
@@ -162,9 +176,9 @@
     delete res;
 
+    //insert entry for the run into the database in the table DataCheck, if it is not yet existing
     if (!ExistStr(serv, "fRunNumber", "DataCheck", Form("%d", runno)))
     {
         query=Form("INSERT DataCheck SET fRunNumber=%d", runno);
 
-        cout << "U:" << query << endl;
         res = serv.Query(query);
         if (!res)
@@ -175,4 +189,5 @@
     }
 
+    //get filenames of sinope output files
     TString fname(Form("%s/sinope/%s/sinope-dat%08d.txt",
                        datapath.Data(), date.Data(), runno));
@@ -183,8 +198,10 @@
 
     Int_t rc=0;
+    //process dat-file
     rc=Process(serv, fname, runno, kFALSE, dummy);
     if (rc==0)
         return rc;
 
+    //process cal-file
     rc=Process(serv, fnamecal, runno, kTRUE, dummy);
     return rc;
Index: /trunk/MagicSoft/Mars/datacenter/macros/fillstar.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/fillstar.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/fillstar.C	(revision 7459)
@@ -30,5 +30,22 @@
 //
 // This macro is used to read the star-output files.
-// These files are automatically called star00000.root.
+// These files are automatically called star00000000.root.
+// From these files the muon parameters (psf, muon number, ratio, muon rate),
+// the  rate, the number of islands, the effective ontime, the maximum
+// humidity and a parameter describing the inhomogeneity are extracted from
+// the status display.
+// The sequence number is extracted from the filename.
+//
+// Usage:
+//   .x fillstar.C("/magic/data/star/0004/00047421/star00047421.root", kTRUE)
+//
+// The second argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
+// switched on and nothing will be written into the database. This is usefull
+// for tests.
+//
+// The macro can also be run without ACLiC but this is a lot slower...
+//
+// Remark: Running it from the commandline looks like this:
+//   root -q -l -b fillstar.C+\(\"filename\"\,kFALSE\) 2>&1 | tee fillstar.log
 //
 // Make sure, that database and password are corretly set in a resource
Index: /trunk/MagicSoft/Mars/datacenter/macros/findcacofiles.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/findcacofiles.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/findcacofiles.C	(revision 7459)
@@ -25,6 +25,29 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// FindCaCoFiles.C
+// findcacofiles.C
 // ===============
+//
+// Macro to get from the database the number of the runs, for which no caco
+// file is available.
+//
+// Sometimes the DAQ aborts a run and starts itself a new one. In this cases
+// there's the camera controll doesn't start a new file, as the command to
+// start a new run was not sent by the central control. So the caco
+// information is stored in the previous caco file, which has a different
+// runnumber. To be able to merpp the information into the calibrated data
+// file, the runnumber of the file containing the information has to be found.
+// This is done by a script.
+// findcacofiles.C produces the input for this script. It queries from the
+// database, for which runs no caco file with the same runnumber is available
+// and writes the runnumbers into an txt file.
+//
+// Usage:
+//   .x findcacofiles.C+("date", "logpath")
+// date and logpath are needed only for the output file
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -60,4 +83,5 @@
     cout << endl;
 
+    //get runnumbers from database
     TString query="SELECT RunProcessStatus.fRunNumber FROM RunProcessStatus ";
     query+=" LEFT JOIN RunData on RunData.fRunNumber=RunProcessStatus.fRunNumber ";
@@ -72,4 +96,5 @@
     }
 
+    //create output file
     TString filename(Form("%s/findcacofiles-%s.txt", logpath.Data(), date.Data()));
     ofstream fout(filename, ios::app);
@@ -80,4 +105,5 @@
     }
 
+    //write runnumbers into output file
     TSQLRow *row=0;
     while ((row = res->Next()))
Index: /trunk/MagicSoft/Mars/datacenter/macros/getdolist.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/getdolist.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/getdolist.C	(revision 7459)
@@ -25,6 +25,35 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// GetDoList.C
+// getdolist.C
 // ===========
+//
+// This macro is a key part of the automation concept.
+// It queries from the database, for which dates/runs/sequences/datasets a
+// certain step has to be done and writes the todo-files.
+//
+// Usage:
+//  .x getdolist.C+("table", "column", "date", "listpath")
+// The first and second argument give the table and column in the database
+// and specify like this the primary (date/run/sequenc/dataset) and the
+// step.
+// The third argument specifies the date, for which the macro has to be
+// executed. This is currently not used in the automatic analysis. It was
+// forseen to give the possibility to process the data night by night. By
+// giving date='NULL' the macro is executed for all dates.
+// The forth argument gives the path, where teh todo-file is stored.
+//
+// The macro needs apart from sql.rc the resource file steps.rc
+// In this files the interdependencies of the analysis steps are given: To
+// execute a certain step other steps have to be executed first and each
+// step also influences othere steps - this information is stored in steps.rc
+//   example:
+// To execute the calibration, all files have to be available on disk (needs).
+// And if the calibration is done, fillcallisto and star can be executed
+// (influences).
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -64,9 +93,9 @@
     TEnv rc("steps.rc");
 
+    //read in needs
     TString needs  = rc.GetValue(table+"."+column+".Needs", "");
     cout << "Needs: " << needs  << endl;
 
     TList l;
-
     while (!needs.IsNull())
     {
@@ -82,8 +111,17 @@
     }
 
+    //build query
+    // this forms a query like e.g.
+    //SELECT SequenceProcessStatus.fSequenceFirst FROM SequenceProcessStatus
+    // WHERE ISNULL(fCallisto)
+    // AND NOT ISNULL(fAllFilesAvail) AND NOT ISNULL(fSequenceFileWritten)
+    //which would query all sequences for which Callisto has to be done.
     TString query(Form("SELECT %s.%s FROM %s",
                        table.Data(), rc.GetValue(table+".Primary", ""),
                        table.Data()));
 
+    //get joins
+    //if a date is given, the tables, which contain the information about the
+    // date (given in step.rc as TimerTable), have to be joined
     if (date!="NULL" && rc.GetValue(table+".TimerTable", "")!="")
         query+=Form(" left join %s on %s.%s=%s.%s ",
@@ -99,4 +137,5 @@
         query+=Form(" AND NOT ISNULL(%s)", o->GetName());
 
+    //if a date is given another condition is added to the query
     if (date!="NULL")
     {
@@ -111,6 +150,10 @@
     }
 
+    //to process the newest data first, the results are ordered descending by the primary
     query+=Form(" ORDER BY %s.%s DESC ", table.Data(), rc.GetValue(table+".Primary", ""));
 
+    //this part of the query is needed, if there are more than 512 results and single
+    //todo files are written, as shell scripts have a limitation for arrays
+    // this is currently only the case, if runs are processed, i.e. for the table RunProcessStatus
     if (table=="RunProcessStatus")
         query+="LIMIT 0, 500";
@@ -126,4 +169,12 @@
 
 
+    //write todo-file
+    //depending on the kind of step and primary, this looks different
+    //for steps, which do not take much time and can thus be executed
+    // for all data at once (e.g. buildsequenceentries) only one todo
+    // file is written
+    //for steps, which take quite long for one primary (e.g. calibration)
+    // or of which a large number has to be executed (e.g. datacheck)
+    // one todo-file per primary is written
     TString filename;
     TSQLRow *row=0;
@@ -137,4 +188,6 @@
         {
             filename=Form("%s/ToDo-%s-%s-%s.txt", listpath.Data(), table.Data(), column.Data(), (*row)[0]);
+            //remove file, if it is already existing
+            // this is needed, that the same step is not executed several times
             gSystem->Unlink(filename);
             ofstream fout(filename, ios::app);
Index: /trunk/MagicSoft/Mars/datacenter/macros/insertcacofile.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/insertcacofile.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/insertcacofile.C	(revision 7459)
@@ -25,6 +25,29 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// InsertCaCoFiles.C
+// insertcacofiles.C
 // =================
+//
+// Macro to insert runnumber of the caco files, which contain the information
+// for a run, for which no caco file is available.
+//
+// Sometimes the DAQ aborts a run and starts itself a new one. In this cases
+// there's the camera controll doesn't start a new file, as the command to
+// start a new run was not sent by the central control. So the caco
+// information is stored in the previous caco file, which has a different
+// runnumber. To be able to merpp the information into the calibrated data
+// file, the runnumber of the file containing the information has to be found.
+// This is done by a script.
+// insertcacofiles.C inserts the runnumber of the file, that has been found,
+// into the column CaCoFileFound. 
+//
+// Usage:
+//   .x insertcacofile.C+("runnumber", "newrunnumber")
+// The first is the runnumber of which the cacofile is missing, the second is
+// the runnumber of the file in which the information probably can be found.
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -42,5 +65,4 @@
 
 using namespace std;
-
 
 int insertcacofile(TString runnumber, TString newrunnumber)
@@ -60,5 +82,7 @@
     cout << endl;
 
+    //get new runnumber
     Int_t newrunno=atoi(newrunnumber.Data());
+    //build query and insert information
     TString query(Form("UPDATE RunProcessStatus SET fCaCoFileAvail=Now(), fCaCoFileFound=%d WHERE fRunNumber=%s ",
                        newrunno, runnumber.Data()));
Index: /trunk/MagicSoft/Mars/datacenter/macros/insertdataset.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/insertdataset.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/insertdataset.C	(revision 7459)
@@ -25,6 +25,27 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// InsertDataset.C
+// insertdataset.C
 // ===============
+//
+// This macro inserts datasets into the database.
+// If a new dataset file has been stored in the dataset directory, the
+// information file is read by a script and the information is inserted with
+// this macro into the database in the tables DataSets and
+// DataSetProcessStatus, where in the information about datasets is stored.
+//
+// Usage:
+//   .x insertdataset.C+("number","source,"wobble","comment",kTRUE)
+// The first argument is the dataset number, the second is giving the source
+// name, the third the observation mode (wobble/on-off), the fourth a comment
+// about the dataset. This arguments are extracted by a script from the
+// dataset file.
+// The last argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
+// switched on and nothing will be written into the database. This is usefull
+// for tests.
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -59,4 +80,6 @@
 }
 
+//get key of a name
+// insert value, if it is not yet existing
 Int_t QueryNameKEY(MSQLServer &serv, Bool_t dummy, const char *col, const char *name, Bool_t insert=kTRUE)
 {
@@ -121,4 +144,5 @@
     cout << endl;
 
+    //get source key
     Int_t sourcekey = QueryNameKEY(serv, dummy, "Source", source.Data(), kFALSE);
     if (sourcekey<0)
@@ -131,4 +155,5 @@
     cout << "no:" << number << endl;
 
+    //if dataset is not yet in database, insert the information
     if (!ExistStr(serv, "fDataSetNumber", "DataSets", number.Data())) // Form("%d", number)
     {
@@ -151,5 +176,5 @@
         delete res;
 
-
+        //add also entry in the table DataSetProcessStatus
         query=Form("INSERT DataSetProcessStatus SET fDataSetNumber='%s', "
                    " fDataSetInserted=Now() ",
Index: /trunk/MagicSoft/Mars/datacenter/macros/insertdate.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/insertdate.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/insertdate.C	(revision 7459)
@@ -25,6 +25,19 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// InsertDate.C
+// insertdate.C
 // ============
+//
+// This macro is inserting a date into the table SequenceBuildStatus.
+// It is executed by the script copyscript, which copies the slow control
+// data to the appropriate directory and inserts the information into the
+// database.
+//
+// Usage:
+//  .x insertdate.C+("date")
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -79,4 +92,6 @@
     cout << endl;
 
+    //insert entry for date into the table SequenceBuildStatus,
+    // if entry is not yet existing
     if (!ExistStr(serv, "fDate", "SequenceBuildStatus", date))
     {
Index: /trunk/MagicSoft/Mars/datacenter/macros/insertsequence.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/insertsequence.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/insertsequence.C	(revision 7459)
@@ -25,6 +25,23 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// InsertSequence.C
+// insertsequence.C
 // ================
+//
+// This macro inserts a sequence into the database. It extracts the
+// information from a sequence file.
+// This macro is not used by the automatic analysis. It is needed to insert
+// manually built sequences into the database.
+//
+// Usage:
+//  .x insertsequence.C+("filename", kTRUE)
+// The first argument is the filename of the manual written sequencefile.
+// The second argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
+// switched on and nothing will be written into the database. This is usefull
+// for tests.
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -125,8 +142,10 @@
     cout << endl;
 
+    //get sequence number from file
     TString sequnum;
     sequnum=sequ.GetValue("Sequence", "");
     Int_t seq=atoi(sequnum.Data());
 
+    //get runs from sequence file
     TString runs;
     runs = sequ.GetValue("Runs", "");
@@ -138,7 +157,9 @@
     }
 
+    //get source key
     TString sourcename = sequ.GetValue("Source", "");
     Int_t sourcekey = QueryNameKEY(serv, dummy, "Source", sourcename.Data());
 
+    //get values for the sequence
     TString query="SELECT max(fRunNumber), min(fRunStart), ";
     query +="sum(time_to_sec(fRunStop)-time_to_sec(fRunStart)), ";
@@ -218,4 +239,5 @@
     cout << "  l2tt      " << l2tt      << endl;
 
+    //build queries
     TString query1="INSERT Sequences SET fManuallyChangedKEY=2, ";
     query1 +=Form("fSequenceFirst=%d, fSequenceLast=%s, "
@@ -232,4 +254,5 @@
                   l1tt.Data(), l2tt.Data());
 
+    //the time of the column fSequenceFileWritten is set to 'not to be done'
     TString query2=Form("INSERT SequenceProcessStatus SET "
                         "fSequenceFirst=%d, fSequenceFileWritten='1970-01-01 00:00:00'",
Index: /trunk/MagicSoft/Mars/datacenter/macros/resetallruns.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/resetallruns.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/resetallruns.C	(revision 7459)
@@ -25,6 +25,21 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// ResetAllRuns.C
+// resetallruns.C
 // ==============
+//
+// This macro resets the values of a column in the table RunProcessStatus. It
+// is used by the script filesondisk to reset the values for the columns,
+// which indicate the availability of the files.
+//
+// Usage:
+//   .x resetallrun.C+("filename", "column")
+// The first argument is giving a file, in which a list of runs can be found
+// for which the column will be set to Now() by this macro. The second
+// argument is giving the column, which has to be reset.
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -59,9 +74,10 @@
     cout << endl;
 
+    //reset column to NULL
     TString query(Form("UPDATE RunProcessStatus SET %s=NULL",
                        column.Data()));
+    //if the column is fCaCoFileAvail, reset also the column fCaCoFileFound
     if (column.Contains("CaCo"))
         query+=", fCaCoFileFound=NULL";
-
 
     cout << "q: " << query << endl;
@@ -76,4 +92,5 @@
 
 
+    //read in file
     ifstream fin(filename);
     if (!fin)
@@ -82,7 +99,7 @@
         return 0;
     }
-
     while (1)
     {
+        //get runnumber
         TString runnumber;
         runnumber.ReadLine(fin);
@@ -90,4 +107,5 @@
             break;
 
+        //build query and set status for this run to Now()
         TString query(Form("UPDATE RunProcessStatus SET %s=Now()", column.Data()));
 
Index: /trunk/MagicSoft/Mars/datacenter/macros/resetcolumn.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/resetcolumn.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/resetcolumn.C	(revision 7459)
@@ -25,5 +25,5 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// ResetColumn.C
+// resetcolumn.C
 // =============
 //
@@ -34,5 +34,5 @@
 //
 // As arguments you have to give the column, the table and from which
-// to which Date/Sequence/Run you want to reset the value.
+// to which Date/Sequence/Run/Dataset you want to reset the value.
 //
 // The last argument is the 'dummy-mode'. If it is kTRUE dummy-mode is
@@ -40,6 +40,11 @@
 // for tests (i.e. if you want to see if the query is correct).
 //
-// usage:
+// Usage:
 //   .x resetcolumn.C("fStar","SequenceProcessStatus","45114","49329",kTRUE)
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -77,4 +82,5 @@
 
     TEnv rc("steps.rc");
+    //get steps which are influenced by the step, which is resetted
     TString influences  = rc.GetValue(table+"."+column+".Influences", "");
 
@@ -97,4 +103,5 @@
     }
 
+    //build query and reset columns
     TString query(Form("Update %s SET %s=NULL ", table.Data(), column.Data()));
 
@@ -112,5 +119,4 @@
     }
 
-
     TSQLResult *res = serv.Query(query);
     if (!res)
Index: /trunk/MagicSoft/Mars/datacenter/macros/setstatus.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/setstatus.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/setstatus.C	(revision 7459)
@@ -25,6 +25,24 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-// SetStatus.C
+// setstatus.C
 // ===========
+//
+// This macro is a key part of the automation concept.
+// It sets the status for dates/runs/sequences/datasets in the database, if a
+// certain step has been done.
+//
+// Usage:
+//   .x setstatus.C+("primary","table","column","value",kTRUE)
+// The first argument is the primary (date/run/sequence/dataset), the second
+// and third argument give the table and column of the step. The fourth
+// column is giving the value, to which the column has to be set. The last
+// argument is indicating if the columns of all influenced steps shall be
+// reset to NULL. The default is kTRUE, which means, that the columns are
+// reset.
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -53,4 +71,5 @@
     }
 
+    //some columns can't be reseted, this is given in steps.rc
     TString reset=rc.GetValue(table+"."+column+".Reset", "no");
     if (reset.Contains("no"))
@@ -66,4 +85,5 @@
 TString CheckDefault(MSQLServer &serv, TEnv &rc, TString primary, TString table, TString influence)
 {
+    //check if the value in the database is the default
     TString query(Form("SELECT %s FROM %s WHERE %s=%s",
                        influence.Data(), table.Data(),
@@ -97,4 +117,5 @@
     cout << "set influenes for " << table << "." << column << endl;
 
+    //build query and set step and influences for the step
     TString influences  = rc.GetValue(table+"."+column+".Influences", "");
 
@@ -115,7 +136,10 @@
         TString deflt  = rc.GetValue(influence+".Default", "");
 
+        //for some columns there may be a different default
+        // in the file steps.rc they are marked with Default: check
+        // in this case, the value in the database has to be checked
         if (deflt=="check")
             deflt=CheckDefault(serv, rc, primary, table, influence);
-
+        //if it is the default value (1970-01-01 00:00:00), nothing is inserted into the database
         if (deflt=="yes")
             continue;
@@ -125,6 +149,4 @@
 
     query+=Form(" WHERE %s='%s'", rc.GetValue(table+".Primary", ""), primary.Data());
-
-//    cout << "query: " << query << endl;
 
     TSQLResult *res = serv.Query(query);
@@ -153,4 +175,5 @@
     TEnv rc("steps.rc");
 
+    //if reset is needed and/or can be done, set new values
     return !CheckReset(rc, table, column, value) ? 0 : SetInfluences(serv, rc, primary, table, column, value, resetall);
 
Index: /trunk/MagicSoft/Mars/datacenter/macros/setupdb.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/setupdb.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/setupdb.C	(revision 7459)
@@ -1,2 +1,5 @@
+// This macro is a macro to create the Magic Database.
+// It is kept up to date, if any changes in the database are made.
+
 #include <iomanip.h>
 /*
Index: /trunk/MagicSoft/Mars/datacenter/macros/writesequencefile.C
===================================================================
--- /trunk/MagicSoft/Mars/datacenter/macros/writesequencefile.C	(revision 7458)
+++ /trunk/MagicSoft/Mars/datacenter/macros/writesequencefile.C	(revision 7459)
@@ -29,6 +29,14 @@
 // ===================
 //
-// reads the sequence information from the database
-// and writes it into a txt file
+// reads the sequence information from the database and writes it into a
+// txt file
+//
+// Usage:
+//  .x writesequencefile.C+(sequno,"sequpath")
+//
+// Make sure, that database and password are corretly set in a resource
+// file called sql.rc and the resource file is found.
+//
+// Returns 0 in case of failure and 1 in case of success.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -257,4 +265,5 @@
         return kFALSE;
 
+    //create sequence file
     TString fname(Form("%s/%04d/sequence%08d.txt", sequpath.Data(), atoi(data[0])/10000, atoi(data[0])));
     cout << "Creating " << fname << "..." << flush;
@@ -267,4 +276,5 @@
     }
 
+    //write information into file
     fout << "Sequence:        " << data[0]  << endl;
     fout << "Period:          " << period   << endl;
@@ -289,4 +299,5 @@
                        data[0]));
 
+    //write runs into sequence file
     if (!GetAllRuns(serv, fout, query))
         return kFALSE;
@@ -327,4 +338,5 @@
     cout << endl;
 
+    //get sequence information from database
     TString query(Form("SELECT fSequenceFirst, fSequenceLast, fProjectKEY, fSourceKEY,"
                        " fL1TriggerTableKEY, fL2TriggerTableKEY, fHvSettingsKEY, "