class HepFileManager

Pure Virtual Base Class.

Users will create instances of derived classes -- managers based on specific underlying histogram packages such as:
• HepHBookFileManager (available now),
• HepHistoFileManager (available now),
• HepRootFileManager (available now).
A HepHBookFileManager, for example, is associated with one HBook file, which may contain multiple histograms and Ntuples.

While the user would not instantiate a generic HepFileManager, the basic methods for each type of activity are present in this base class. These include:

Constructors

Navigating the Internal Hierarchy

Creating Histograms and Ntuples

Referencing existing Histograms and Ntuples

Dealing with Data for Multiple Collections

It is also valid to open a HepTuple file of arbitrary type of manager, receiving a pointer to the base class HepFileManager* by calling newManager. Since this base class contains the basic methods for each type of activity, a progam can treat the various types of files the without specific code for each type.

#include "HepTuple/HepFileManager.h"

For backward compatibility, TupleManager.h is also provided.

#include "HepTuple/HepFileManager.h"
(or whichever specific manager is used)

Constructors

Create a manager -- pure virtual in this base class.
• virtual HepFileManager( const string& fileName, const string& dirName );

  The user constructs an instance of a specific subclass. These constructors all have available the generic signature shown above.

  • HepHBookFileManager( const string& fileName, const string& dirName );
  • HepHistoFileManager( const string& fileName, const string& dirName );
  • HepRootFileManager ( const string& fileName, const string& dirName );
    For backward compatibility, HBookTupleManager is also provided, as an alias for HepHBookFileManager.

  All managers support a constructor with an optional argument that specifies a requested file opening mode. The allowed values are defined via an enumeration in the file HepFileManager.h and should be referenced by name. Those names, and their meanings are

  • HEP_READONLY opens the file in read-only mode
  • HEP_UPDATE opens the file for write, assuming it already exists
  • HEP_REFRESH insures that any updated histogram objects are overwritten rather that using the default mechanism of creating a new cycle or version. This only works for the Root manager and is simply ignored by the others.
  • As of 26 March, 2001, HEP_REMOVE is available. This signals the file manager that it should look for a file with the same name as the one given as the first constructor argument and, subject to the usual permission requirements, silently delete it. This option is dangerous and should be used only with the brain fully switched on.
  • As of 29 March, 2001, HEP_RENAME is available. This signals the file manager that it should look for a file with the same name as the one given as the first constructor argument and rename it to something recognizable but unique in its directory by having six random characters appended to its original name. This is considerable less drastic than outright deletion a la HEP_REMOVE.

  It is allowed to logically OR - in the sense of (A | B) - any two of these file open mode options. However, some of the possible combinations are silly or outright meaningless. These will provoke a warning level ZMxIncompatible exception and the option will be replaced with a related and meaningful alternative as reported in the text of the exception message. Since no triple combination represents a sensible option, presenting the logical OR of more than two of these basic options will result in a ZMxUnsupported exception, which is normally fatal.

  The recognized two-fold options are summarized in the following matrix, where, for brevity, we omit the prefix HEP_.

  	READONLY	UPDATE	REFRESH	REMOVE	RENAME
  READONLY	-	no	no	no	no
  UPDATE	no	-	yes	no	no
  REFRESH	no	yes	-	yes	yes
  REMOVE	no	no	yes	-	no
  RENAME	no	no	yes	no	-

  If it is possible and the user does not intervene by requesting a particular file opening mode, the file is opened in update mode. If it is not, for example if the file resides in a read-only file system, it is opened in read-only mode.
  After the file has been opened, the user can requests a read-only or update mode:

  • bool forReadOnly(); // Set the manager as read only
  • bool forUpdate(); // Verify that the file can be updated
  • bool isReadOnly() const; // When true no update or addition are allowed.

  However, once in read-only mode, either because the constructor could not open the file in update mode, either because of a user request, any call to forUpdate() will throw an ZMxHepCantWriteFile exceptions.

  newManager

  A function is provided to open an existing file written by HepTuple, without having to know which type of manager was used. Of course, it returns a pointer to the base class -- a generic HepFileManager.

  • HepFileManager * newManager(const string& fileName, HepFileManager::mode req_mode);

  
  The semantics are as if the user explicitly said new HepFileManager: In particular, the second argument may be omitted in which case it defaults to HEP_UPDATE. The user code is responsible for deleting the returned pointer when it is no longer needed.

  Since newManager() is capable of opening HBook, Histoscope, or Root managers, by default code using newManager() needs to link with all three of those HepTuple libraries. However, the need for linking in one of those libraries can be eliminated if (when newManager.h is included) one of the following symbols is defined:

  • DONT_LINK_HBOOK
  • DONT_LINK_HISTO
  • DONT_LINK_ROOT

  A related method (another free function) is

  • HepTupleFileFormat hepTupleFileType (const string& fileName);

  The header hepTupleFileType.h defines the HepTupleFileFormat, an with values such as

  • HEPTUPLE_HBOOK
  • HEPTUPLE_ROOT
  • HEPTUPLE_HISTOSCOPE

  These same values may be obtained by a query method of any open HepFileManager:

  HepFileManager* m_ptr; // which was opened earlier
  HepTupleFileFormat type = m_ptr-> hepFileFormat();

Navigating the Internal Hierarchy

Within the managed collection of histograms and ntuples, there is a hierachical organization. This is patterned after a file system, though typically multiple histograms and/or ntuples are placed in a single actual file managed by the HepTupleManager.

There is an internal current or "working" directory, and each histogram or ntuple will reside in the working directory which was current when the histrogram or ntuple was instantiated. The following methods manipulate and navigate that internal hierarchy:
Note that a set of methods analogous to the Unix filesystem utilities is provided. As of release 1.5.3, the standard Unix symbol ".." may be used as an argument to cd with the traditional meaning - go up one directory.

Change to a different directory (absolute or relative)

• virtual void cd( const string & path );
  

  Make a new directory

• virtual void mkdir( const string & path );
  

  Remove contents from the current working directory:

• virtual void rm( const string & name );
  
• virtual void rm( const int id=0 );
  
  This removes the Ntuple(s) or histogram(s) with the specified name or implementation id.

  Removes the named directory, if it exists. If recursive is true it will also remove any and all entries in that directory and any sub-directory.

• virtual void rmdir( const string & path, bool recursive = false );

  Supplies the name of the current working directory.

• inline string pwd() const;

  HepFileManager has a sub-class Item defined as follow:

  class Item
  public:
  HepFileManager * mgr; // pointer to desired manager
  string title; // object's title
  int id; // optional unique object ident
  string dir; // object's directory
  char type; // object type identification
  Item(const HepObj&);
  Item();
  };
  type is one of
  HepHist1D::typeId = "1"
  HepHist2D::typeId = "2"
  HepHistProf::typeId = "P"
  HepNTuple::typeId = "N"
  HepDir::typeId = "D"

  For the ls() and list() member functions, if the options string contains one or more characters among

  {1, 2, P, N, D}
  the result will contains information only on the types contained in that string (see examples). If, however, the options string contains none of these characters, then it will respond to all five as if the string were "12PND".

  Provide a string listing of the contents of a directory -- absolute, relative or "" for working directory:

• virtual string ls( const string & path = "", const string & options = "" ) const;
  The resulting string contains the directory contents, each entry having the form: id \t title \n
  If options contains a 'l' the resulting string has the following format id \t type \t title \n
  If options contains a 'r' the content of all subdirectory is append to the resulting string.
  
  

  Provide a list of the items in a directory -- absolute, relative or "" for working directory:

• virtual ItemList list( const string & path = "", const string & options = "" ) const;
  HepFileManager::ItemList is defined as a vector < HepFileManager::Item >
  If options contains a 'r' the result is a list of the content of the directory and all its subdirectory.

  HepFileManager::ItemList l = mgr->list("","1P");

  will return only the 1D Histogram and the Histogram Profiles in the current directory.

  HepFileManager::ItemList l = mgr->list("//FILENAME.RZ","r12PND");

  is equivalent to

  HepFileManager::ItemList l = mgr->list("//FILENAME.RZ","r");

  and returns a list of all the items in the file.

Creating Histograms and Ntuples

Individual histograms or Ntuples must be created directly created via these manager methods:

1-D Histogram

• virtual HepHist1D & hist1D(
  const string& title,
  const int nbins, const float low, const float high,
  const int id = 0 );

  2-D Histogram

• virtual HepHist2D & hist2D(
  const string& title,
  const int nbinsX, const float lowX, const float highX,
  const int nbinsY, const float lowY, const float highY,
  int id = 0 );

  Profile Histogram

• virtual HepHistProf & histProf(
  const string& title,
  const int nbinsX, const float lowX, const float highX,
  const int nbinsX, const float lowY, const float highY,
  const string& errorMethod, const int id = 0 );
• virtual HepHistProf & histProf(
  const string& title,
  const int nbinsX, const float lowX, const float highX,
  const int nbinsX, const float lowY, const float highY,
  const int id=0 );
  errorMethod for Profile histograms is HBook's chopt:
  The default is S/sqrt(N) errors;
  "S" uses the full RMS spread instead;
  "I" uses a computation suitable for Y-value that have been rounded to integers.

  General Ntuple allowing multiple and/or inhomogenous blocks of columns

• virtual HepNtuple & ntuple(
  const string& title,
  const int id = 0 );
  Subsequent calls to methods of the Ntuple must be made, to define the block and column structure of this Ntuple, and to control storage strategy.

Copying and Cloning

Create a object of that a clone or copy of the argument in the current directory. A Copy in an exact replication of the argument. A clone is an object of the same type and characteristic (e.g number of bins) but without any data entered.

• virtual HepObj& makeClone( const HepObj& original, const string& new_title, int new_id = 0 );
• virtual HepObj& makeEmpty( const HepObj& original, const string& new_title, int new_id = 0 );

• virtual bool copyClone( HepFileManager* original, const string& options = "");
• virtual bool copyClone( HepFileManager* original, const string& path, const string& options );
• virtual bool copyEmpty( HepFileManager* original, const string& options = "");
• virtual bool copyEmpty( HepFileManager* original, const string& path, const string& options );

Referencing existing Histograms and Ntuples

• virtual HepHist1D & retrieveHist1D( const string& title, int id = 0 );
• virtual HepHist2D & retrieveHist2D( const string& title, int id = 0 );
• virtual HepHistProf & retrieveHistProf( const string& title, int id = 0 );
• virtual HepNtuple & retrieveNtuple( const string& title, int id = 0 );

With release 1.7.5 in March of 2001, functionality was added to combine multiple collections of HepHistogram objects. For details, see the separate note.

Writing (flushing) Multiple Histograms and Ntuples

These routines facilitate operations pertaining to either every Ntuple, FlatNtuple, and histograms of all types associated with this manager, or every one of those in the current working directory.

Write the data into the managed file. These return 0 if successful.

• virtual int write();
  write() implies sending the contents of all buffers to the disk for an Ntuple, or writing a histogram to the disk file. Do so for every collection managed by this manager.
  
  
• virtual void writeDirectory();
  Invoke write() for each Ntuple or histogram in the current working directory.

Accumulating or Clearing Multiple Ntuples

These routines facilitate operations pertaining to either every Ntuple associated with this manager, or every Ntuple in the current working directory. They do not apply to Histograms or FlatNtuples.

Note that none of these methods have been implemented yet and are therefore virtual in at least two ways.

Accumulate data for the current row for all Ntuples.

• virtual void captureThenStoreAllData();
  capture the data in the designated variables, then store() to advance the row counter. Do so for every Ntuple managed by this manager.
  
  
• virtual void captureThenStoreAllDirectory(const string& path=".");
  Invoke captureThenStore for each Ntuple in the named directory or the current working directory.

  Clear data for the current row for all Ntuples.

• virtual void clearAllData();
  clear() marks blocks as not having been filled. It can be used when a partially captured event is rejected for inclusion in an Ntuple. Do so for every Ntuple managed by this manager.
  
  
• virtual void clearAllDirectory(const string& path=".");
  Invoke clear() for each Ntuple in the current working directory.

  Shut down an output file and continue on a new one (Root manager only)

• virtual bool switchFile( const string& newFileName, const bool resetHists );
  transparently flush and close the current output file and open a new one with the specified name. Continue to accumulate data, resetting (i. e., zeroing) all histogram objects or not depending on the value of bool resetHists.
  
  

  ---

  Related Classes

  Histograms and Ntuples managed by a HepTupleManager:
  • HepHist1D
  • HepHist2D
  • HepHistProf
  • HepNtuple

  ---

  (Last updated October 14, 2002.)
  Return to Zoom HepTuple Package Documentation