Pure Virtual Base Class.
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:
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.
For backward compatibility, TupleManager.h is also provided.
The user constructs an instance of a specific subclass. These constructors all have available the generic signature shown above.
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:
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.
- 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.
newManagerA 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:
A related method (another free function) is
The header hepTupleFileType.h defines the HepTupleFileFormat, an with values such as
- HepTupleFileFormat hepTupleFileType (const string& fileName);
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();
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)
Make a new directory
Remove contents from the current working directory:
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.
Supplies the name of the current working directory.
HepFileManager has a sub-class Item defined as follow:
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
For the ls() and list() member functions, if the options string contains one or more characters among
1, 2, P, N, D}
Provide a string listing of the contents of a directory -- absolute, relative or "" for working directory:
Provide a list of the items in a directory -- absolute, relative or "" for working directory:
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.
General Ntuple allowing multiple and/or inhomogenous blocks of columns
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.
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.
Write the data into the managed file. These return 0 if successful.
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.
Clear data for the current row for all Ntuples.
Shut down an output file and continue on a new one (Root manager only)