Chapter 11
Framework services

11.2.1  Job options file format

The job options file has a well-defined syntax (similar to a simplified C++-Syntax) without datatypes. The datatypes are recognised by the "Job Options Compiler", which interprets the job options file according to the syntax (described in Appendix Appendix C together with possible compiler error codes).

The job options file is an ASCII-File, composed logically of a series of statements. The end of a statement is signaled by a semicolon (';') - as in C++.

Comments are the same as in C++, with '//' until the end of the line, or between '/*' and '*/'.

There are three constructs which can be used in a job options file:

• Assignment statement
• Append statement
• Include directive

 
<Object / Identifier> . < Propertyname > = < value >;

 
<Object / Identifier> . < Propertyname > += < value >;

 
#include "filename.ext"

 
//************************************************************** 
// 
// Win32 standard job options file 
// 
//============================================================== 
 
 
//-------------------------------------------------------------- 
// General Application Configuration options 
//-------------------------------------------------------------- 
 
ApplicationMgr.ExtSvc = { "SicbEventCnvSvc",  
                          "SicbEventSelector/EventSelector" }; 
 
ApplicationMgr.DLLs = { "S:\LHCb\LHCBSoft\SicbCnv\v6\Win32Debug\SicbCnvshr",  
"S:\LHCb\LHCBSoft\HbookCnv\v5\Win32Debug\HbookCnvshr" };  
 
//-------------------------------------------------------------- 
// Persistency services 
//-------------------------------------------------------------- 
 
EventPersistencySvc.CnvServices     = { "SicbEventCnvSvc" };   
 
 
//-------------------------------------------------------------- 
// Detector related parameters 
//-------------------------------------------------------------- 
// We use CDF_StorageType 0x5 
//ApplicationMgr.DetStorageType = 5; 
 
// Detector description input file 
//CdfCnvSvc.cdfDbFile = "DDDB.txt"; 
 
// Persistency service setup:  
//DetectorPersistencySvc.CnvServices = { "CdfCnvSvc " }; 
 
 
//-------------------------------------------------------------- 
// Bookkeeping database file 
//-------------------------------------------------------------- 
 
// For Windows/NT: 
EventSelector.TapesDataBase = "F:\cern.ch\lhcb\mcdbase\mcmain.db"; 
 
//============================================================== 
// 
// End of Win32 standard job options file 
// 
//**************************************************************

 
//************************************************************** 
// 
// Unix standard job options file 
// 
//============================================================== 
 
 
//-------------------------------------------------------------- 
// General Application Configuration options 
//-------------------------------------------------------------- 
 
ApplicationMgr.ExtSvc = { "SicbEventCnvSvc",  
                          "SicbEventSelector/EventSelector" }; 
 
 
//-------------------------------------------------------------- 
// Persistency services 
//-------------------------------------------------------------- 
 
EventPersistencySvc.CnvServices     = { "SicbEventCnvSvc" };   
 
 
//-------------------------------------------------------------- 
// Detector related parameters 
//-------------------------------------------------------------- 
// We use CDF_StorageType 0x5 
//ApplicationMgr.DetStorageType = 5; 
 
// Detector description input file 
//CdfCnvSvc.cdfDbFile = "DDDB.txt"; 
 
// Persistency service setup:  
//DetectorPersistencySvc.CnvServices = { "CdfCnvSvc " }; 
 
 
//-------------------------------------------------------------- 
// Bookkeeping database file 
//-------------------------------------------------------------- 
 
EventSelector.TapesDataBase = "/afs/cern.ch/lhcb/mcdbase/mcmain.db"; 
 
//============================================================== 
// 
// End of Unix standard job options file 
// 
//**************************************************************

11.3.1  The MsgStream utility

The MsgStream class is responsible for constructing a Message object which it then passes onto the message service. Where the message is ultimately sent to is decided by the message service.

In order to avoid formatting messages which will not be sent because the verboseness level is too high, a MsgStream object first checks to see that a message will be printed before actually constructing it. However the threshold for a MsgStream object is not dynamic, i.e. it is set at creation time and remains the same. Thus in order to keep synchronized with the message service, which in principle could change its printout level at any time, MsgStream objects should be made locally on the stack when needed. For example, if you look at the listing of the HistoAlgorithm class (see also Listing 31 below) you will note that MsgStream objects are instantiated locally (i.e. not using new) in all three of the IAlgorithm methods and thus are destructed when the methods return. If this is not done messages may be lost, or too many messages may be printed.

The MsgStream class has been designed to resemble closely a normal stream class such as std::cout, and in fact internally uses an ostrstream object. All of the MsgStream member functions write unformatted data; formatted output is handled by the insertion operators.

An example use of the MsgStream class is shown below.

When using the MsgStream class just think of it as a configurable output stream whose activation is actually controlled by the first word (message level) and which actually prints only when "endreq" is supplied. For all other functionality simply refer to the C++ ostream class.

The "activation level" of the MsgStream object is controlled by the first expression, e.g. MSG::ERROR or MSG::DEBUG in the example above. Possible values are given by the enumeration below:

 
enum MSG::Level { VERBOUS, DEBUG, INFO, WARNING, ERROR, FATAL };

Thus the code in Listing 31 will produce NO output if the print level of the message service is set higher than MSG::ERROR. In addition if the service's print level is lower than or equal to MSG::DEBUG the "Finalize completed successfully" message will be printed (assuming of course it was successful).

11.4.1   Initialising and Accessing the Service

This service is created by default by the application manager, with the name "ParticlePropertySvc."

In order to use the service, a client must access its interface, IParticlePropertySvc . From an algorithm this is done as follows:

 
#include "Gaudi/Interfaces/IParticlePropertySvc.h" 
... 
IParticlePropertySvc* m_ppSvc; 
StatusCode sc = serviceLocator()->getService( 
"ParticlePropertySvc", 
IID_IParticlePropertySvc, 
reinterpret_cast<IInterface*&>( m_ppSvc )); 
 
if ( sc.isFailure) { 
...

11.4.2  Service Properties

The Particle Property Service currently only has one property: ParticlePropertiesFile . This string property is the name of the database file that should be used by the service to build up its list of particle properties. The default value of this property, on all platforms, is $LHCBDBASE/cdf/particle.cdf

11.4.3  Service Interface

As mentioned earlier, the service implements the IParticlePropertySvc interface which must be included when a client wishes to use the service - the file to include is Gaudi/Interfaces/IParticlePropertySvc.h

The service itself consists of one STL vector to access all of the existing particle properties, and three STL maps, one to map particles by name, one to map particles by Geant3 ID and one to map particles by stdHep ID.

Although there are three maps, there is only one copy of each particle property and thus each property must have a unique particle name and a unique Geant3 ID. The third map does not contain all particles contained in the other two maps; this is because there are particles known to Geant but not to stdHep, such as Deuteron or Cerenkov. Although retrieving particles by name should be sufficient, the second and third maps are there because most of the data generated by SICb stores a particle's Geant3 ID or stdHep ID, and not the particle's name. These maps speed up searches using the IDs.

The IParticlePropertySvc interface provides the following functions:

 
// IParticlePropertySvc interface: 
// Create a new particle property. 
// Input: particle, String name of the particle. 
// Input: geantId, Geant ID of the particle. 
// Input: jetsetId, Jetset ID of the particle. 
// Input: type, Particle type. 
// Input: charge, Particle charge (/e). 
// Input: mass, Particle mass (GeV). 
// Input: tlife, Particle lifetime (s).    
// Return: StatusCode - SUCCESS if the particle property was added. 
virtual StatusCode push_back( const std::string& particle, 				int geantId, int jetsetId, int type, double charge, double mass, double tlife ); 
 
// Create a new particle property. 
// Input: pp, a particle property class. 
// Return: StatusCode - SUCCESS if the particle property was added. 
virtual StatusCode push_back( ParticleProperty* pp ); 
   
// Get a const reference to the begining of the map. 
virtual const_iterator begin() const; 
   
// Get a const reference to the end of the map. 
virtual const_iterator end() const;   
 
// Get the number of properties in the map. 
virtual int size() const; 
 
// Retrieve a property by geant id. 
// Pointer is 0 if no property found. 
virtual ParticleProperty* find( int geantId ); 
 
// Retrieve a property by particle name. 
// Pointer is 0 if no property found. 
virtual ParticleProperty* find( const std::string& name ); 
 
// Retrieve a property by StdHep id 
// Pointer is 0 if no property found. 
virtual ParticleProperty* findByStdHepID( int stdHepId ); 
 
// Erase a property by geant id. 
virtual StatusCode erase( int geantId ); 
 
// Erase a property by particle name. 
virtual StatusCode erase( const std::string& name ); 
 
// Erase a property by StdHep id 
virtual StatusCode eraseByStdHepID( int stdHepId );

The IParticlePropertySvc interface also provides some typedefs for easier coding:

 
typedef ParticleProperty* mapped_type; 
typedef std::map< int, mapped_type, std::less<int> > MapID; 
typedef std::map< std::string, mapped_type, std::less<std::string> > MapName; 
typedef std::map< int, mapped_type, std::less<int> > MapStdHepID; 
typedef IParticlePropertySvc::VectPP VectPP; 
typedef IParticlePropertySvc::const_iterator const_iterator; 
typedef IParticlePropertySvc::iterator iterator;

11.4.4  Examples

Below are some extracts of code from the example in GaudiExamples/ParticleProperties, to show how one might use the service:

 
 // Try finding particles by the different methods 
  log << MSG::INFO << "Trying to find properties by Geant3 ID..." << endreq; 
  ParticleProperty* pp1 = m_ppSvc->find( 1 ); 
  if ( pp1 ) log << MSG::INFO << *pp1 << endreq;  
  log << MSG::INFO << "Trying to find properties by name..." << endreq; 
  ParticleProperty* pp2 = m_ppSvc->find( "e+" ); 
  if ( pp2 ) log << MSG::INFO << *pp2 << endreq;  
  log << MSG::INFO << "Trying to find properties by StdHep ID..." << endreq; 
  ParticleProperty* pp3 = m_ppSvc->findByStdHepID( 521 ); 
  if ( pp3 ) log << MSG::INFO << *pp3 << endreq;  

 
// List all properties  
log << MSG::DEBUG << "Listing all properties..." << endreq; 
for( IParticlePropertySvc::const_iterator i = m_ppSvc->begin();  
i != m_ppSvc->end(); i++ ) { 
if ( *i ) log << *(*i) << endreq; 
}

11.5.1  The Service base class

Within Gaudi we use the term "Service" to refer to a class whose job is to provide a set of facilities or utilities to be used by other components. In fact we mean more than this because a concrete service must derive from the Service base class and thus has a certain amount of predefined behaviour; for example it has intialize() and finalize() methods which are invoked by the application manager at well defined times.

Figure 15 Implementation of a concrete service class. Though not shown in the figure, both of the IConcreteSvcType interfaces are derived from IInterface.

Figure 15 shows the inheritance structure for an example service called SpecificService (!). The key idea is that a service should derive from the Service base class and additionally implement one or more pure abstract classes (interfaces) such as IConcreteSvcType1 and IConcreteSvcType2 in the figure.

As discussed above, it is necessary to derive from the Service base class so that the concrete service may be made accessible to other Gaudi components. The actual facilities provided by the service are available via the interfaces that it provides. For example the ParticleProperties service implements an interface which provides methods for retrieving, for example, the mass of a given particle. In figure 15 the service implements two interfaces each of two methods.

A component which wishes to make use of a service makes a request to the application manager. Services are requested by a combination of name, and interface type, i.e. an algorithm would request specifically either IConcreteSvcType1 or IConcreteSvcType2.

The identification of what interface types are implemented by a particular class is done via the queryInterface method of the IInterface interface. This method must be implemented in the concrete service class. In addition the initialize() and finalize() methods should be implemented. After initialization the service should be in a state where it may be used by other components.

The service base class offers a number of facilities itself which may be used by derived concrete service classes:

• Properties are provided for services just as for algorithms. Thus concrete services may be fine tuned by setting options in the job options file.
• A serviceLocator method is provided which allows a component to request the use of other services which it may need.
• A message service.

11.5.2  Implemention details

The following is essentially a checklist of the minimal code required for a service.

1. Define the interfaces:

 
#include "Gaudi/interfaces/IInterface.h" 
 
class IConcreteSvcType1 : virtual public IInterface { 
public: 
  void method1() = 0; 
  int method2() = 0; 
} 

 
#include "IConcreteSvcType1.h" 
 
const IID& IID_IConcreteSvcType1 = 143; // UNIQUE within LHCb !!

1. Derive the concrete service class from the Service base class.
2. Implement the queryInterface() method.
3. Implement the initialize() method. Within this method you should make a call to Service::initialize() as the first statement in the method and also make an explicit call to setProperties() in order to read the service's properties from the job options (note that this is different from Algorithms, where the call to setProperties() is done in the base class).

 
#include "Gaudi/Kernel/Service.h" 
#include "IConcreteSvcType1.h" 
#include "IConcreteSvcType2.h" 
 
class SpecificService : public Service,  
                        virtual public IConcreteSvcType1, 
                        virtual public IConcreteSvcType2 { 
public: 
  // Constructor of this form required: 
  SpecificService(const std::string& name, ISvcLocator* sl); 
 
  queryInterface(constIID& riid, void** ppvIF); 
}; 

 
// Factory for instantiation of service objects 
static SvcFactory<SpecificService> s_factory; 
const ISvcFactory& SpecificServiceFactory = s_factory; 
 
// UNIQUE Interface identifiers defined elsewhere 
extern const IID& IID_IConcreteSvcType1; 
extern const IID& IID_IConcreteSvcType2; 
 
// queryInterface 
StatusCode SpecificService::queryInterface(const IID& riid, void** ppvIF) { 
  if(IID_IConcreteSvcType1 == riid) { 
    *ppvIF = dynamic_cast<IConcreteSvcType1*> (this); 
    return StatusCode::SUCCESS; 
  } else if(IID_IConcreteSvcType2 == riid) { 
    *ppvIF = dynamic_cast<IConcreteSvcType2*> (this); 
    return StatusCode::SUCCESS; 
  } else { 
    return Service::queryInterface(riid, ppvIF); 
  } 
} 
 
StatusCode SpecificService::initialize() { ... } 
StatusCode SpecificService::finalize() { ... } 
 
// Implement the specifics ... 
SpecificService::method1() {...} 
SpecificService::method2() {...} 
SpecificService::method3() {...} 
SpecificService::method4() {...}