---

CdbBdbObjectVisitorUserAction.cc

Go to the documentation of this file.

// File and Version Information:
//      $Id: CdbBdbObjectVisitorUserAction.cc,v 1.5 2004/08/06 05:54:18 bartoldu Exp $

/// The implementation of the CdbBdbObjectVisitorUserAction.
/**
  * @see CdbBdbObjectVisitorUserAction
  */

#include "BaBar/BaBar.hh"

#include "CdbBdb/CdbBdbObjectVisitorUserAction.hh"
#include "CdbBdb/CdbBdbObjectVisitorContext.hh"

#include "BbrStdUtils/Tokenize.hh"
#include "BbrStdUtils/String.hh"
using namespace babar::String;

#include "ErrLogger/ErrLog.hh"

#include <fstream>
#include <iostream>
#include <iomanip>

#include <stdio.h>
#include <assert.h>
using std::cout;
using std::endl;
using std::fstream;
using std::ifstream;
using std::setfill;
using std::setw;

namespace {

  ////////////////////////////////
  // Internal utility functions //
  ////////////////////////////////

  /// Try to match specified pattern with the current context
  /**
    * Note the following semantical differences between the context and teh pattern
    * (they both use the same class):
    *
    *   - a context is a current path of the visitor
    *   - a pattern is a class of paths.
    *   - the fields in patterns may represent a spectrum of possible values. Here are
    *     the conventions:
    *
    *     -- text:  "*" means any value
    *     -- index: 0xFFFFFFFF means any number
    *     -- ooRef: 0xFFFF-0xFFFF-0xFFFF-0xFFFF means any reference
    *
    * The matching algorithm would try to match the whole pattern starting
    * from the end of the context. The definition of success is when the whole
    * pattern fits into the end of context.
    */
    bool match_pattern( const CdbBdbObjectVisitorContext* theContext,
                        const CdbBdbObjectVisitorContext* thePattern );

  /// Print A context onto the standard output
  /**
    * More info...
    */
    void print_context(            const ooHandle(ooObj)& theInputH,
                        const CdbBdbObjectVisitorContext* theContext );

  /// Print a pattern onto the standard output
  /**
    * The pattern is printed in a waywhich is compatible with pattern translator.
    * So that these printed patterns could be loaded back and used for filtering.
    */
    void print_pattern( const CdbBdbObjectVisitorContext* theContext );

  /// Load patterns from the input file
  /**
    * The patterns have the same format the output of the above defined
    * method 'print_context' looks alike.
    */
    bool load_patterns( std::vector<CdbBdbObjectVisitorContext*>& theRepository,
                                                      const char* theFileName,
                                                             bool verboseMode,
                                                             bool debugMode );

  /// Extract a pair of a key and its value only from a string
  /**
    * The procedure gurantees (if successful) that only  avalid pair of key/value
    * is found in the stream.
    */
    bool extract_pair( const std::string& theExpectedKey,
                             std::string& theValue,
                                ifstream& theStream,
                                     bool verboseMode,
                                     bool debugMode );

    /// Extract a pair of a key and its value or a pattern delimiter from a string

    bool extract_pair_or_delimiter( const std::string& theExpectedKey,
                                          std::string& theValue,
                                                 bool& isEndOfFile,
                                                 bool& isBegin,
                                                 bool& isEnd,
                                             ifstream& theStream,
                                                  bool verboseMode,
                                                  bool debugMode );

  /// Extract the value of an index
  /**
    * This procedure is used when reading and translating patterns from
    * an input file. Normally indeces are treated as plain numbers of 'size_t'
    * type unless the input string has '*' meaning "don't care about a concrete value".
    * In this case 0xFFFFFFFF is returned as an index's value.
    */
    bool extract_index(            size_t& theIndex,
                        const std::string& theStr,
                                      bool verboseMode,
                                      bool debugMode );

  /// Translate an OID string into an object of ooId class
  /**
    * Depending on a value of the last ('useHash'_ parameter the function
    * may also be tolerant to the '#' symbol preceeding OID-s.
    */
    bool translate_OID(       ooId& theId,
                        const char* theString,
                       bool useHash = false );

};

CdbBdbObjectVisitorUserAction::CdbBdbObjectVisitorUserAction(                const char* theSupressFile,
                                                              const std::list<d_UShort>* theDatabasesToIgnore,
                                                                                    bool verboseMode,
                                                                                    bool debugMode ) :
    _verboseMode   (verboseMode),
    _debugMode     (debugMode),
    _totalObjects  (0),
    _invalidObjects(0)
{
    if( _debugMode ) _verboseMode = true;

  // Trunslate the list of patterns to be supressed (if any)

    if( 0 != theSupressFile ) {

        if( !load_patterns( _patternsToIgnore,
                            theSupressFile,
                            _verboseMode,
                            _debugMode )) {

            ErrMsg(fatal) << "failed to translate patterns to be ignored from the input file \"" << theSupressFile << "\"." << endmsg;
        }
        if( _verboseMode ) {

            cout << "PATTERNS TO BE IGNORED:" << endl;

            size_t num = _patternsToIgnore.size( );
            for( size_t i = 0; i < num; ++i )
                print_pattern( _patternsToIgnore[i] );

            cout << "END OF PATTERNS." << endl;
        }
    }

  // Load a list of databases (by DBID-s) not to touch

    for( size_t db = 0; db <= MAX_DATABASE; ++db )
        _databasesToIgnore[db] = false;

    if( 0 != theDatabasesToIgnore ) {
        std::list<d_UShort>::const_iterator itr = theDatabasesToIgnore->begin( );
        while( theDatabasesToIgnore->end( ) != itr ) {
            _databasesToIgnore[*itr] = true;
            ++itr;
        }
    }

  // Clear statistics

    for( size_t db = 0; db <= MAX_DATABASE; ++db ) {
        _missingDatabase         [db] = 0;
        _clientsOfMissingDatabase[db] = 0;
        _dbidToName              [db] = "";
    }
}

CdbBdbObjectVisitorUserAction::~CdbBdbObjectVisitorUserAction( )
{
    size_t num = _patternsToIgnore.size( );
    for( size_t i = 0; i < num; ++i ) delete _patternsToIgnore[i];
    _patternsToIgnore.clear( );

    for( size_t db = 0; db <= MAX_DATABASE; ++db )
        if( _missingDatabase[db] ) delete _clientsOfMissingDatabase[db];
}

CdbBdbObjectVisitorUserAction::ActionType
CdbBdbObjectVisitorUserAction::action(            const ooHandle(ooObj)& theInputH,
                                       const CdbBdbObjectVisitorContext* theContext )
{
    ooId     id = theInputH;
    d_UShort db = id.get_DB( );

  // FILTER #1 STEP

  // Skip the known databases

    if( _databasesToIgnore[db] ) {

//////////////////////////////////////////////////////////////////////////////////////////
if( _debugMode ) {
    cout << "STOPPING AT THE OBJECT (ITS DATABASE IS IN \"TO BE IGNORED\" LIST)." << endl;
    print_context( theInputH,
                   theContext );
}
//////////////////////////////////////////////////////////////////////////////////////////

            return ACTION_STOP;
    }

  // EVALUATION STEP : propagate the further decision to a user supplied
  //                   method if the passed object is valid.

    ++_totalObjects;

    if( theInputH.isValid( )) return userAction( theInputH,
                                                 theContext );
    ++_invalidObjects;

  // FILTER #2 STEP

  // Try known patterns to see if they could match the current context.
  // Note that matched cases do not contribute into the "missing/corrupted"
  // statistics.

    size_t num = _patternsToIgnore.size( );
    for( size_t i = 0; i < num; ++i ) {
        if( match_pattern( theContext, _patternsToIgnore[i] )) {

////////////////////////////////////////////////////////////////////////////////
if( _debugMode ) {
    cout << "STOPPING AT THE OBJECT (MATCHED the PATTERN #" << i << ")" << endl;
    print_context( theInputH,
                   theContext );
}
////////////////////////////////////////////////////////////////////////////////

            return ACTION_STOP;
        }
    }

  // STATISTICS STEP

  // For now just assume that object is not valid due to missing database.
  // In reality an existing database may also be corrupted. Therefore they
  // should be reported into a separate list.

    _missingDatabase[db]++;
    if( !update_missing_database_clients_list( _clientsOfMissingDatabase[db],
                                               theContext )) return ACTION_ERROR;

  // Simply print the current contex and report the problem upstream

    if( _verboseMode )
        print_context( theInputH,
                       theContext );

    return ACTION_STOP;
}

void
CdbBdbObjectVisitorUserAction::print_statistics( ) const
{
    cout << endl
         << "  *** VISITED OBJECTS REPORT ***" << endl
         << endl
         << "  ------------------------+-----------------------" << endl
         << "    TOTAL OBJECTS VISITED : INVALID OBJECTS FOUND " << endl
         << "  ------------------------+-----------------------" << endl
         << endl
         << "    "
         << setw( 21 ) << setfill( ' ' ) << _totalObjects
         << " : "
         << setw( 21 ) << setfill( ' ' ) << _invalidObjects << endl
         << endl
         << "  *** MISSING DATABASES REPORT ***" << endl
         << endl
         << "  ----------+------------+------" << endl
         << "   DATABASE : REFERENCES : FROM " << endl
         << "  ----------+------------+------" << endl;

    for( size_t db = 0; db <= MAX_DATABASE; ++db ) {
        if( _missingDatabase[db] ) {

            cout << "   "
                 << setw( 8 ) << setfill( ' ' ) << db
                 << " : "
                 << setw( 10 ) << setfill( ' ' ) << _missingDatabase[db]
                 << " : ";

            std::map<d_UShort,std::string>::iterator itr =  _clientsOfMissingDatabase[db]->begin( );
            while( itr != _clientsOfMissingDatabase[db]->end( )) {
                cout << (*itr).second.c_str( ) << " ";
                ++itr;
            }
            cout << endl;
        }
    }
    cout << "  ----------+------------+------" << endl;
}

unsigned int
CdbBdbObjectVisitorUserAction::missedCounters( d_UShort theDatabaseId ) const
{
    if( theDatabaseId > MAX_DATABASE )
        ErrMsg(fatal) << "an out-of-range database number " << theDatabaseId << " passed" << endl
                      << "into the method. The allowed range is between 0 and " << MAX_DATABASE << endl;

    return _missingDatabase[theDatabaseId];
}

const std::map<d_UShort,std::string>*
CdbBdbObjectVisitorUserAction::missedDatabaseClients( d_UShort theDatabaseId ) const
{
    if( theDatabaseId > MAX_DATABASE )  
        ErrMsg(fatal) << "an out-of-range database number " << theDatabaseId << " passed" << endl
                      << "into the method. The allowed range is between 0 and " << MAX_DATABASE << endl;

    return _clientsOfMissingDatabase[theDatabaseId];
}

CdbBdbObjectVisitorUserAction::ActionType
CdbBdbObjectVisitorUserAction::userAction(            const ooHandle(ooObj)& theInputH,
                                           const CdbBdbObjectVisitorContext* theContext )
{
    return ACTION_PROCEED;
}

bool
CdbBdbObjectVisitorUserAction::update_missing_database_clients_list(  std::map<d_UShort,std::string>*& theClients,
                                                                     const CdbBdbObjectVisitorContext* theContext )
{
    if( 0 == theClients ) theClients = new std::map<d_UShort,std::string>( );

  // Find the direct client of the missing database by browsing
  // the current context from its last element.

  // Note, 'signed int' rather than 'unsigned int' should always be used
  // in decrement loops to prevent going through 0 to the upper numbers.

    size_t contextSize = theContext->size( );
    for( int i = contextSize - 1; i >= 0; --i ) {

        const CdbBdbObjectVisitorContext::Element& context = (*theContext)[i];

        if( CdbBdbObjectVisitorContext::Element::OBJECT == context.type( )) {

            const ooId     id = context.ref( );
            const d_UShort db = id.get_DB( );

          // Proceed with obtaining the database name only if this database identifier
          // is not in the list of clients yet.

            if( theClients->end( ) == theClients->find( db )) {
                if( "" == _dbidToName[db] )
                    _dbidToName[db] = context.ref( ).containedIn( ).containedIn( ).name( );

                (*theClients)[db] = _dbidToName[db];
            }
            return true;
        }
    }

 // The failure to find an object is considered a error.

    ErrMsg(error) << "failed to find the cleint object." << endmsg;

    return false;
}

//////////////////////////////////////////////////
// Implementation of internal utility functions //
//////////////////////////////////////////////////

namespace {

bool
match_pattern( const CdbBdbObjectVisitorContext* theContext,
               const CdbBdbObjectVisitorContext* thePattern )
{
    ooId anyId;
    anyId.set_DB  ( 0xFFFF );
    anyId.set_OC  ( 0xFFFF );
    anyId.set_page( 0xFFFF );
    anyId.set_slot( 0xFFFF );

    const  std::string anyName  = "*";
    const       size_t anyIndex = 0xFFFFFFFF;
    const ooRef(ooObj) anyRef   = anyId;

    size_t contextSize = theContext->size( );
    size_t patternSize = thePattern->size( );

  // The context should be at least of the same length...

    if( patternSize > contextSize ) return false;

  // Note, 'signed int' rather than 'unsigned int' should always be used
  // in decrement loops to prevent going through 0 to the upper numbers.

    for( int i = patternSize - 1; i >= 0; --i ) {

        const CdbBdbObjectVisitorContext::Element& context = (*theContext)[ i + contextSize - patternSize ];
        const CdbBdbObjectVisitorContext::Element& pattern = (*thePattern)[ i ];

        if( pattern.type( ) != context.type( )) return false;

        switch( pattern.type( )) {

        case CdbBdbObjectVisitorContext::Element::OBJECT :

            if(     pattern.ref( ) != anyRef )
                if( pattern.ref( ) != context.ref( )) return false;

            if(     pattern.name( ) != anyName )
                if( pattern.name( ) != context.name( )) return false;

            break;

        case CdbBdbObjectVisitorContext::Element::EMBEDDED_OBJECT :

            if(     pattern.name( ) != anyName )
                if( pattern.name( ) != context.name( )) return false;

            if(     pattern.name_2( ) != anyName )
                if( pattern.name_2( ) != context.name_2( )) return false;

            if(     pattern.index( ) != anyIndex )
                if( pattern.index( ) != context.index( )) return false;

            break;


        case CdbBdbObjectVisitorContext::Element::REFERENCE :

            if(     pattern.name( ) != anyName )
                if( pattern.name( ) != context.name( )) return false;

            if(     pattern.index( ) != anyIndex )
                if( pattern.index( ) != context.index( )) return false;

            break;

        case CdbBdbObjectVisitorContext::Element::BASE_CLASS :
        case CdbBdbObjectVisitorContext::Element::MAP_ELEMENT :
        case CdbBdbObjectVisitorContext::Element::MANY_RELATIONSHIP :
        case CdbBdbObjectVisitorContext::Element::ONE_RELATIONSHIP :

            if(     pattern.name( ) != anyName )
                if( pattern.name( ) != context.name( )) return false;

            break;

        default:

            return false;
        }
    }
    return true;
}

void
print_context(            const ooHandle(ooObj)& theInputH,
               const CdbBdbObjectVisitorContext* theContext )
{
    cout << "VISITOR CONTEXT FOR " << theInputH.sprint( ) << " IS" << endl;
    print_pattern( theContext );
}

void
print_pattern( const CdbBdbObjectVisitorContext* theContext )
{
    cout << "{" << endl;

    size_t num = theContext->size( );
    for( size_t i = 0; i < num; ++i ) {

        if( i > 0 )
            cout << endl;

        switch((*theContext)[i].type( )) {

        case CdbBdbObjectVisitorContext::Element::OBJECT :

            cout << "  TYPE       : <OBJECT>" << endl
                 << "  OID        : " << (*theContext)[i].ref( ).sprint( ) << endl
                 << "  CLASS_NAME : " << (*theContext)[i].name( ).c_str( ) << endl;
            break;

        case CdbBdbObjectVisitorContext::Element::BASE_CLASS :

            cout << "  TYPE       : <BASE_CLASS>" << endl
                 << "  CLASS_NAME : " << (*theContext)[i].name( ).c_str( ) << endl;
            break;

        case CdbBdbObjectVisitorContext::Element::EMBEDDED_OBJECT :

            cout << "  TYPE       : <EMBEDDED_OBJECT>" << endl
                 << "  CLASS_NAME : " << (*theContext)[i].name( ).c_str( ) << endl
                 << "  NAME       : " << (*theContext)[i].name_2( ).c_str( ) << endl
                 << "  INDEX      : " << (*theContext)[i].index( ) << endl;
            break;

        case CdbBdbObjectVisitorContext::Element::MAP_ELEMENT :

            cout << "  TYPE       : <MAP_ELEMENT>" << endl
                 << "  KEY        : " << (*theContext)[i].name( ).c_str( ) << endl;
            break;

        case CdbBdbObjectVisitorContext::Element::REFERENCE :

            cout << "  TYPE       : <REFERENCE>" << endl
                 << "  NAME       : " << (*theContext)[i].name( ).c_str( ) << endl
                 << "  INDEX      : " << (*theContext)[i].index( ) << endl;
            break;

        case CdbBdbObjectVisitorContext::Element::MANY_RELATIONSHIP :

            cout << "  TYPE       : <MANY_RELATIONSHIP>" << endl
                 << "  NAME       : " << (*theContext)[i].name( ).c_str( ) << endl;
            break;

        case CdbBdbObjectVisitorContext::Element::ONE_RELATIONSHIP :

            cout << "  TYPE       : <ONE_RELATIONSHIP>" << endl
                 << "  NAME       : " << (*theContext)[i].name( ).c_str( ) << endl;
            break;

        default:

            cout << "  TYPE       : <unknown>" << endl;
            break;
        }
    }
    cout << "}" << endl;
}

bool
load_patterns( std::vector<CdbBdbObjectVisitorContext*>& theRepository,
                                             const char* theFileName,
                                                    bool verboseMode,
                                                    bool debugMode )
{
    assert( 0 != theFileName );  // a fatal error in the class's implementation

  // Clear the repository

    theRepository.clear( );

  // Open a file with a list of patterns

    ifstream inFile( theFileName );
    if( !inFile.good( )) {
        ErrMsg(error) << "failed to open specified input file." << endmsg;
        return false;
    }

  // Read patterns, translate them and put them into the repository

    CdbBdbObjectVisitorContext* currentPattern = 0;
    do {
        std::string type;
        bool        isEndOfFile = false;
        bool        isBegin     = false;
        bool        isEnd       = false;
        if( !extract_pair_or_delimiter( "TYPE",
                                        type,
                                        isEndOfFile,
                                        isBegin,
                                        isEnd,
                                        inFile,
                                        verboseMode,
                                        debugMode )) return false;
        if( isEndOfFile ) break;
        if( isBegin ) {

          // Check if we're not ie middle of a previous pattern

            if( 0 != currentPattern ) {
                ErrMsg(error) << "wrong format of the input file. The previous pattern was not properly closed." << endmsg;
                return false;
            }

          // Begin a new one

            currentPattern = new CdbBdbObjectVisitorContext( );

        } else if( isEnd ) {

          // Make sure that we're already processing a pattern

            if( 0 == currentPattern ) {
                ErrMsg(error) << "wrong format of the input file. A stray closing paranthesis not related to any pattern found."<< endmsg;
                return false;
            }

          // Put a new pattern into a list and get ready to scan the next pattern

            theRepository.push_back( currentPattern );
            currentPattern = 0;

        } else {

          // We're processing next node in the current pattern. The whole node is expected
          // to be processed in the current block.

            if( "<OBJECT>" == type ) {

                std::string oid;
                std::string className;
                if( !extract_pair( "OID",        oid,       inFile, verboseMode, debugMode )) return false;
                if( !extract_pair( "CLASS_NAME", className, inFile, verboseMode, debugMode )) return false;

              // Note, when translating OID-s from patterns we should also take into
              // account that there will be the '#' symbol preceeding the actual OID.

                ooId id;
                if( !translate_OID( id, oid.c_str( ), true )) return false;
                ooRef(ooObj) ref = id;

                currentPattern->push( CdbBdbObjectVisitorContext::Element::createObject( ref,
                                                                                         className.c_str( )));

            } else if( "<BASE_CLASS>" == type ) {

                std::string className;
                if( !extract_pair( "CLASS_NAME", className, inFile, verboseMode, debugMode )) return false;

                currentPattern->push( CdbBdbObjectVisitorContext::Element::createBaseClass( className.c_str( )));

            } else if( "<EMBEDDED_OBJECT>" == type ) {

                std::string className;
                std::string name;
                std::string indexStr;
                if( !extract_pair( "CLASS_NAME", className, inFile, verboseMode, debugMode )) return false;
                if( !extract_pair( "NAME",       name,      inFile, verboseMode, debugMode )) return false;
                if( !extract_pair( "INDEX",      indexStr,  inFile, verboseMode, debugMode )) return false;

                size_t index;
                if( !extract_index( index, indexStr, verboseMode, debugMode )) return false;

                currentPattern->push( CdbBdbObjectVisitorContext::Element::createEmbeddedObject( className.c_str( ),
                                                                                                 name.c_str( ),
                                                                                                 index ));

            } else if( "<MAP_ELEMENT>" == type ) {

                std::string key;
                if( !extract_pair( "KEY", key, inFile, verboseMode, debugMode )) return false;

                currentPattern->push( CdbBdbObjectVisitorContext::Element::createMapElement( key.c_str( )));

            } else if( "<REFERENCE>" == type ) {

                std::string name;
                std::string indexStr;
                if( !extract_pair( "NAME",  name,     inFile, verboseMode, debugMode )) return false;
                if( !extract_pair( "INDEX", indexStr, inFile, verboseMode, debugMode )) return false;

                size_t index;
                if( !extract_index( index, indexStr, verboseMode, debugMode )) return false;

                currentPattern->push( CdbBdbObjectVisitorContext::Element::createReference( name.c_str( ),
                                                                                            index ));

            } else if( "<MANY_RELATIONSHIP>" == type ) {

                std::string name;
                if( !extract_pair( "NAME", name, inFile, verboseMode, debugMode )) return false;

                currentPattern->push( CdbBdbObjectVisitorContext::Element::createManyRelationship( name.c_str( )));

            } else if( "<ONE_RELATIONSHIP>" == type ) {

                std::string name;
                if( !extract_pair( "NAME", name, inFile, verboseMode, debugMode )) return false;

                currentPattern->push( CdbBdbObjectVisitorContext::Element::createOneRelationship( name.c_str( )));

            } else {
                ErrMsg(error) << "unknown type: \"" << type << "\"." << endmsg;
                return false;
            }
        }

    } while( true );

    return true;
}

bool extract_pair( const std::string& theExpectedKey,
                         std::string& theValue,
                            ifstream& theStream,
                                 bool verboseMode,
                                 bool debugMode )
{
    bool isEndOfFile = false;
    bool isBegin     = false;
    bool isEnd       = false;

  // Firstly, the translation must succeed

    if( !extract_pair_or_delimiter( theExpectedKey,
                                    theValue,
                                    isEndOfFile,
                                    isBegin,
                                    isEnd,
                                    theStream,
                                    verboseMode,
                                    debugMode )) return false;

  // Secondly, it should not be a special case

    return ! ( isEndOfFile || isBegin || isEnd );
}

bool
extract_pair_or_delimiter( const std::string& theExpectedKey,
                                 std::string& theValue,
                                        bool& isEndOfFile,
                                        bool& isBegin,
                                        bool& isEnd,
                                    ifstream& theStream,
                                         bool verboseMode,
                                         bool debugMode )
{
    isEndOfFile = false;
    isBegin     = false;
    isEnd       = false;

  // Read until either end of file or reconized contents is met

    char buf[1024];
    while( theStream.getline( buf, 1024, '\n' )) {

//////////////////////////////////////////////////////////
if( debugMode ) {
cout << "READ FROM INPUT FILE: \"" << buf << "\"" << endl;
}
//////////////////////////////////////////////////////////

      // Skip empty lines

        if( 0 == strlen( buf )) continue;

      // Check if it's either begin or end paranthesis

        if( 0 == strcmp( "{" , buf )) {
            isBegin = true;
            return true;
        }
        if( 0 == strcmp( "}" , buf )) {
            isEnd = true;
            return true;
        }

      // Break the line into tokens

        std::string str( buf );
        Tokenize tokenize( str );

        std::string       key = tokenize( );
        std::string separator = tokenize( );
                     theValue = tokenize( );

        if( key.empty( ) || separator.empty( ) || ( ":" != separator ) || theValue.empty( )) {

            ErrMsg(error) << "illegal syntax of the input file. Pairs of keys and values separated by ':' were expected." << endl
                          << "found at line \"" << buf << "\"." << endmsg;
            return false;
        }

      // Check if the keys is correct

        if( theExpectedKey != key ) {
            ErrMsg(error) << "unexpected key found in the input file." << endl
                 << "    EXPECTED KEY: \"" << theExpectedKey.c_str( ) << "\"" << endl
                 << "    FOUND    KEY: \"" <<            key.c_str( ) << "\"" << endl
                 << "found at line \"" << buf << "\"" << endmsg;
            return false;
        }
        return true;
    }

  // The only condition we can gete here is when EOF has reeched.

    isEndOfFile = true;

    return true;
}

bool
extract_index(            size_t& theIndex,
               const std::string& theStr,
                             bool verboseMode,
                             bool debugMode )
{
    if( "*" == theStr ) {
        theIndex = 0xFFFFFFFF;
    } else {
        if( 1 != sscanf( theStr.c_str( ), "%ud", &theIndex )) {
            ErrMsg(error) << "failed to translate gather an index value from specified string." << endl
                          << "The string was \"" << theStr.c_str( ) << "\"." << endmsg;
            return false;
        }
    }
    return true;
}

bool
translate_OID(       ooId& theId,
               const char* theString,
               bool useHash )
{
    bool result = false;

    do {
        if( 0 == theString ) {
            ErrMsg(error) << "empty string passed where an OID was expeted." << endmsg;
            break;
        }

        int db;
        int cont;
        int page;
        int slot;

        const char* format = ( useHash ? "#%d-%d-%d-%d" : "%d-%d-%d-%d" );
        if( 4 != sscanf( theString, format, &db, &cont, &page, &slot )) {
            ErrMsg(error) << "illegal format of the OID string \"" << theString << "\"." << endmsg;
            break;
        }
        theId.set_DB  ( db );
        theId.set_OC  ( cont );
        theId.set_page( page );
        theId.set_slot( slot );

        result = true;

    } while( false );

    return true;
}
};

/////////////////
// End Of File //
/////////////////

---