



     
     
     
     
		  Textual Object Database (TODB) library, v 1.01
			       For the C++ language
     
     
     
     
     
     
     
     
     
				Reference Manual
     
				  April, 1994
     
     
     
     
     
     
     
     
     
     This software is provided as-is.
     There is no guarantee, either expressed or implied.
     
     
     
     
     
     
     
     
     
     
     Copyright (C) 1993 by Christian Therien
     All rights reserved
     
     
     
     DALIPLUS enr.
     8535, Saint Gerard street,
     Montreal (Quebec)
     Canada
     H2P 2E3
     Phone (514)382-8178



				TABLE OF CONTENTS
     
     
     1.  Introduction............................................  2
     1.1 Overview................................................  2
     1.2 Development philosophy..................................  2
     1.3 Basic requirements......................................  2
     1.4 Library files...........................................  3
     
     2.  Reference manual........................................  4
     2.1 IdxColl class description...............................  5
     2.2 IdxString class description.............................  8
     2.3 MakeToken class description.............................  9
     2.4 SearchSet class description............................. 10
     2.5 TODB class description.................................. 16
     2.6 Parameters description.................................. 18
     2.7 Faults control.......................................... 19
     
     3.  Legal issues............................................ 20
     3.1 Software license........................................ 20
     3.2 Guarantee............................................... 20
     3.3 Registration............................................ 21
     3.4 User support............................................ 21
     
     4.  Conclusion.............................................. 21
     5.  References.............................................. 22
     
     
     Many product names found throughout this manual are trademarks of various 
     companies.



     Reference manual                                             Page: 2

     1. INTRODUCTION
     
     1.1 Overview
     
     TODB is an object oriented class library, written in C++, with automatic
     textual indexing and textual information retrieval, common to all textual 
     databases.  TODB has many interesting features, including:
     
     - an object oriented error handling system (in view of the near-future 
       "throw" and "catch" C++ instructions)
     
     - the code is portable;
     
     - you can define the size of the keys to be indexed;
     
     - you can define the data blocks size of the key set database;
     
     - the retrieval system allow full-text searching, regular 
       expressions searching, Boolean operators and comparison operators;
     
     - automatic word de-indexing;
     
     - a parameter turn on fast batch indexing;
     
     - the token generator (the function giving tokens to the indexing class) is 
       an abstract base class.  This property gives you a way to implement almost
       any indexation and information retrieval scheme.
     
     We are proud to offer you this efficient textual database tool and hope you 
     will enjoy its use as much as we have been doing.  We will welcome any 
     comment you may have regarding TODB software, and will appreciate any 
     suggestion for code extension or improvement.
     
     
     1.2  TODB development philosophy
     
     Much care in this software project development has been brought to an 
     efficient object oriented design, keeping in mind the main goal of a fast 
     textual indexing and textual information retrieval library tool.
     
     
     1.3 Basic requirements
     
     TODB was tested with Microsoft C/C++ compiler version 7.00, with Borland 
     C++ compiler version 3.0 and with different IBM-PC memory models.  We 
     recommend the use of a MEDIUM or LARGE memory model setting for 
     compilation.  If data to be indexed is smaller than 64k, the SMALL memory 
     model should be sufficient; however, most of the time data requirements 
     will ask for a LARGE memory model compilation.
     
     To ensure TODB software compatibility we wrote our own string class 



     Reference manual                                             Page: 3

     definition with only the basic procedures strictly needed by our software 
     and usually found in the standard string class offered by your compiler.  
     However, you can decide to write your own or use Microsoft's or 
     Borland's.  Consult the STRN.H file for your string class functionality.  
     Be advised that maximum portability should be better obtained using the 
     String class definition as defined for the TODB project development.
     
     IMPORTANT NOTICE:
     
     TODB use the B-Plus shareware.  Registration to TODB does not include 
     registration fee to B-Plus.  If your intention is to keep TODB we can only 
     stress the point that you should also register to B-Plus.  The whole B- 
     Plus package is supplied with the TODB files.  Please consult this 
     documentation for information relating to B-Plus registration.
     
     Use of TODB with B-Plus requires some minor modifications to the BPLUS.C 
     file.  The modified file have been clearly annotated and can be consulted 
     for more information in the LIB sub-directory.
     
     Some Microsoft C/C++ compiler instructions for code optimization may 
     prevent correct execution of TODB.  Please check for specifics in the 
     TODBMAKE.MSC file.
     
     
     1.4 Library files
     
     TODB Library has 41 files including header files, classes implementations 
     and a demo program.  TODB library will also make use of the "match" public 
     domain software and the B-Plus shareware.  Here is a listing of the files 
     found on the distribution diskette:
     
     Demonstration program:
     DEMO.H        - Demo-specific application framework class definition
     DEMO.CPP      - Demonstration model program
     SCHEMA.H      - Indexed data class definition
     SCHEMA.CPP    - Indexed data class implementation
     
     Error handling:
     CERR.H        - C program (BPLUS.C) error handling
     CPPERR.H      - C++ programs error handling
     CPPERR.CPP    - Error handling implementation
     
     Key set database:
     FBLOCK.H      - File blocking declaration.
     FBLOCK.CPP    - File blocking implementation
     KEYSET.H      - In memory processing of key set
     KEYSET.CPP    - In memory processing implementation
     KSPERSIS.H    - I/O management class definition
     KSPERSIS.CPP  - I/O management class implementation
     TODB.H        - Opening and closing management class definition
     TODB.CPP      - Opening and closing management class implementation



     Reference manual                                             Page: 4

     
     Data indexing:
     ICOLL.H       - Indexed collection class definition
     ICOLL.CPP     - Indexed collection class implementation
     
     Data retrieval:
     SCHSET.H      - Data retrieval class definition
     SCHSET.CPP    - Data retrieval class implementation
     
     Miscellaneous:
     BOOLEAN.H     - Boolean type
     PTODB.H       - Library global parameters
     STRN.H        - String class definition
     STRN.CPP      - String class implementation
     READ.ME       - Presentation
     MANUAL.TXT    - Reference manual
     ORDER.TXT     - Order form
     
     B-Plus shareware (B-tree)
     MATCH public domain software (Pattern matching - regular expression)
     
     
     2. REFERENCE MANUAL
     
     Here is the application programmer interface:
     
     MakeToken class  - token generator (see ICOLL.H file)
     IdxString class  - indexed string (see ICOLL.H file)
     IdxColl class    - data indexing (see ICOLL.H file)
     TODB class       - key set database management (see TODB.H file)
     SearchSet class  - data retrieval (see SCHSET.H file)
     parameters       - key length and block length definition
			(see PTODB.H file)
     
     Each class is described in detail:



     Reference manual                                             Page: 5

     2.1 IdxColl class description
     
     class IdxColl
     {
     public:
	 IdxColl( TODB & db, IdType cid );
     
	 virtual ~IdxColl();
     
	 void SaveIdx();
	 void ChangeIdx();
	 void DeleteIdx();
     
	 void IndexObject( KeyType key, IdType idxid,
			   MakeToken & mt,
			   const IdxString & str );
	 ...
     protected:
	 virtual void Index() = 0;
     ...
     };
     
     Description:  The IdxColl class is responsible for strings indexation and 
     de-indexation.  Indexation and de-indexation are called at object 
     destruction.  An object with strings to be indexed inherits from the 
     IdxColl class, i.e.:
     
     MyRecord : private IdxColl
     {
	 ...
	 IdxString Field1;
	 IdxString Field2;
     ...
     };
     
     An indexed object like MyRecord manages the indexation process with the 
     following functions:
	 void SaveIdx();
	 void ChangeIdx();
	 void DeleteIdx();
     
     An indexed object will define indexes with the following functions:
	 void IndexObject( KeyType key, IdType mid,
			   MakeToken & mt,
			   const IdxString & str );
	 virtual void Index() = 0;
     
     An indexed object must specify an implementation for the Index() function 
     of IdxColl class.  This implementation should contains indexes description 
     using IndexObject() function.  Destruction of an indexed object will call 
     upon the Index() function, i.e.:



     Reference manual                                             Page: 6

     
     void BibNote::Index()
     {
	 IndexObject( noteno, TITLES, UW_token, title );
	 IndexObject( noteno, TITLES, UW_token, article_title );
	 IndexObject( noteno, SUBTITLES, UW_token, subtitle     );
	 IndexObject( noteno, SUBTITLES, UW_token, article_subtitle );
	 IndexObject( noteno, AUTHOR, UW_token, author );
	 IndexObject( noteno, PUBLISHER, UW_token, publisher );
	 IndexObject( noteno, KEYWORDS, UW_token, keywords );
	 IndexObject( noteno, DATE, UW_token, date );
	 IndexObject( noteno, PUB_PLACE, UW_token, publishing_place );
     }
     
     The IndexObject() function will define and process indexation or 
     de-indexation.
     
     ---------------------------------
     IdxColl( TODB & db, IdType cid );
     
     TODB & db    Reference to the global pointer, 
		  this pointer points to the key set database
     IdType cid   Indexed object class identifier
     
     Description:  The class constructor will link an object with strings to be 
     indexed to the key set database.  Key set database must be opened by TODB 
     class prior to calling the class constructor.  The indexed class is 
     specified by cid, which will be used later on by the SearchSet class for 
     index search.
     
     ---------------
     void SaveIdx();
     
     Description:  This function will be called by and for destruction of an 
     object with strings to be indexed (see SCHEMA.H file).  The Index() 
     function of object with strings to be indexed will be called by SaveIdx() 
     as per state of IdxColl.  The IdxColl class state was set with functions 
     ChangeIdx() and DeleteIdx().
     
     -----------------
     void ChangeIdx();
     
     Description:  The ChangeIdx() function will switch the state of an IdxColl 
     object.  The Index() function will then be called automatically upon if 
     indexed object is to be destroyed.
     
     -----------------
     void DeleteIdx();
     
     Description:  The DeleteIdx() function will switch the state of an IdxColl 
     object.  The Index() function will then be called automatically upon if 



     Reference manual                                             Page: 7

     indexed object is to be destroyed.  Call to Index() function will start de-
     indexation of strings declared by IndexObject() function.  The IdxStrings 
     must have been previously initialized with your database data to be de-
     indexed.
     
     --------------------------------------------
     void IndexObject( KeyType key, IdType idxid,
		       MakeToken & mt,
		       const IdxString & str );
     
     KeyType key              Key value to be indexed
     IdType idxid             String index identification
     MakeToken & mt           Token generator
     const IdxString & str    String to be indexed
     
     Description:  The IndexObject() function is responsible for indexation for 
     each token in a string "str" generated by "mt".  The IndexObject() function 
     will save the "key" (RECORD-ID or record number) in a key set identified by 
     class identifier "cid" and index identifier "idxid".  If the DeleteIdx() 
     function or if the IdxString class /= operator was previously called, 
     IndexObject() function will de-index tokens.
     
     -------------------------
     virtual void Index() = 0;
     
     Description:  The object to be indexed must supply an Index() function 
     implementation.  When indexed object destructor is called upon, it will 
     call SaveIdx() which will in turn call indexed object's own Index() 
     function implementation.  Thus, indexed object is automatically indexed as 
     per definition in Index() function.



     Reference manual                                             Page: 8

     2.2 IdxString class description
     
     class IdxString : public String
     {
	 ...
     public:
	 IdxString();
	 IdxString( const IdxString & istr );
	 IdxString( const String & str );
     
	 ~IdxString();
     
	 // -- assignment
	 IdxString & operator = ( const IdxString & istr );
	 IdxString & operator = ( const String & str );
     
	 // -- update operator
	 IdxString & operator /= ( const String & str );
     ...
     };
     
     Description:  This class uses the IdxColl class.  The IdxColl class indexes 
     IdxString type strings.  The IdxString class provides to the class string a 
     de-indexation mechanism of the content of a previously indexed string and 
     indexation of this string's new content (/= operator).  This mechanism is 
     required to update your data.  Example:
     
     MyIndex : private IdxColl
     {
	 ...
	 IdxString MaChaine;
     ...
     };
     
     MyIndex * mi;
     mi = new MyIndex;
     mi->MyString = "First string"; // "First string" is indexed,
				    // and after, saved to a database
				    // (like Access or Oracle)
     delete mi;
     // save "First string" to your preferred database
     
     mi = new MyIndex;
     // read "First string" from your database
     mi->MyString = "First string"; // "First string" is read from a
				    // database (i.e. Access or Oracle)
				    // and MyIndex is loaded with it
     mi->MyString /= "Another string"; // "First string" is saved to old_str_
				       // and "Another string" is ready to
				       // be indexed
     



     Reference manual                                             Page: 9

     delete mi; // old_str_ string is de-indexed,
		// and "Another string" is indexed
     // update "First string" by "Another string" in your database
     
     -----------------------------------------------
     IdxString & operator /= ( const String & str );
     
     IdxString & operator /= (...) The current string is affected to old_str_,
				   the new string str is affected to the current
				   string
     const IdxString & str         RHS string
     
     Description:  The index update operator allows you to de-index the old 
     string content and index its new one.  First, assign the old content to the 
     = operator and then the new one to the /= operator.  The de-
     indexation/indexation process will occur in the IdxColl object destruction.
     
     
     2.3 MakeToken class description
     
     class MakeToken
     {
     public:
	 virtual ~MakeToken();
	 virtual void Put( const char * s ) = 0;
	 virtual int First( char * token ) = 0;
	 virtual int Next( char * token ) = 0;
     };
     
     Description:  The MakeToken class is an abstract class.  You have to define 
     its implementation.  The IdxColl class uses this class by polymorphism in 
     order to segment in tokens the string to be indexed.  Example:
     
     MyTokenGenerator : public MakeToken
     {
     ...
     }
     
     You pass as parameter MyTokenGenerator to the IdxColl class.  This class 
     uses the MakeToken interface functions in order to segment the string.
     
     ---------------------
     virtual ~MakeToken();
     
     Description:  You can use MyTokenGenerator class destructor to destroy 
     the local copy of the string to be indexed.



     Reference manual                                             Page: 10

     ---------------------------------------
     virtual void Put( const char * s ) = 0;
     
     const char * s       String to be indexed
     
     Description:  When you call this function, you have to save a local copy of 
     the *s string in your token generator.  This string ends with a null 
     character.
     
     --------------------------------------
     virtual int First( char * token ) = 0;
     
     int Fist(...)        Returned values
			  1 - accept the token (it was indexed)
			  0 - reject the token (it was not indexed)
     char * token         Token returned by First
     
     Description:  This function is used by the IdxColl class to obtain the 
     first string's token.  Returning by the First() function of an empty token 
     (="") means the end of the operation.
     
     -------------------------------------
     virtual int Next( char * token ) = 0;
     
     int Next(...)        Returned values
			  1 - accept the token (it was indexed)
			  0 - reject the token (it was not indexed)
     char * token         Token returned by Next
     
     Description:  This function is used by the IdxColl class to obtain the 
     following tokens after a first call to First() function.  Returning by the 
     Next() function of an empty token (="") means the end of the operation.
     
     
     2.4 SearchSet class description
     
     class SearchSet
     {
     public:
	 // constructor
	 SearchSet( TODB * db );
	 SearchSet( const SearchSet & ss );
     
	 // destructor
	 ~SearchSet();
     
	 // number of elements
	 KeyNbr Card() const;
     
	 // assignment
	 SearchSet & operator = ( const SearchSet & ss );



     Reference manual                                             Page: 11

     
	 // sets operators:
     
	 // union (3 operands)
	 SearchSet operator * ( const SearchSet & ss );
	 // union (2 operands)
	 void operator *= ( const SearchSet & ss );
     
	 // intersection (3 operands)
	 SearchSet operator + ( const SearchSet & ss );
	 // intersection (2 operands)
	 void operator += ( const SearchSet & ss );
     
	 // difference (3 operands)
	 SearchSet operator - ( const SearchSet & ss );
	 // difference (2 operands)
	 void operator -= ( const SearchSet & ss );
     
	 // sets comparison:
	 // same sets?
	 int operator == ( const SearchSet & ss ) const;
	 // different sets?
	 int operator != ( const SearchSet & ss ) const;
     
	 // test
	 // returns 1 if pattern has any special wildcard characters, 0 
	 // otherwise
	 int isPattern( char * pattern ) const;
	 // check if pattern is valid
	 int isValidPattern( char * pattern ) const;
     
	 // search functions
	 int FindExact( IdType cid, IdType idxid, char * buf);
	 int FindAll( IdType cid, IdType idxid );
	 int FindPattern( IdType cid, IdType idxid, char * pattern );
     
	 // navigation (a returned value of 0 marks the end)
	 KeyType First();
	 KeyType Next();
     
     protected:
	 SearchSet();
     ...
     };
     
     Description:  The SearchSet class allows you to retrieve the key set 
     according to research criterion.  Also, this class allows you to execute 
     basic Boolean operations on the key set.  The SearchSet objects can access 
     the database by the TODB type global pointer.  Example:



     Reference manual                                             Page: 12

     TODB * keyDB;
     ...
     keyDB = new TODB;
     keyDB->Open( "db.key", "db.idx", IDX_EXIST );
     SearchSet s1( keyDB ), s2( keyDB );
     s1.FindExact( BIBREF, AUTHOR, "MADSEN" ); // search keyDB key set database
     
     The s1 and s2 search set carry out their research in the keyDB database.
     
     -----------------------
     SearchSet( TODB * db );
     
     TODB * db   Reference to the global pointer,
		 this pointer points to the key set database
     
     Description:  The constructor initializes the search set and combines it 
     with the TODB type global pointer to access the key set database.
     
     ----------------------------------
     SearchSet( const SearchSet & ss );
     
     const SearchSet & ss       RHS search set
     
     Description:  This function is the copy constructor.
     
     --------------------
     KeyNbr Card() const;
     
     KeyNbr Card()        Search set keys count
			  0 - if search set is empty
     
     Description:  The Card() function returns search set cardinal number.  If 
     the set is empty, the Card() function returns a zero (0) value.
     
     ------------------------------------------------
     SearchSet & operator = ( const SearchSet & ss );
     
     SearchSet & operator = (...)  LHS (Left Hand Side) search set
     const SearchSet & ss          RHS search set
     
     Description:  The affectation operator assigns a RHS search set to a LHS 
     search set.
     
     If the RHS and the LHS sets come from two different key set databases, the 
     LHS set is separated from its database (in other words: todb_ = NULL).  In 
     this particular case, the LHS set contains keys that do not belong to the 
     key set database initially associated to this LHS set.  It represents a 
     minor problem for the affectation operator but it becomes a more important 
     one for the union, intersection and difference operators.  For these last 
     three operations, the LHS contains a mix of keys coming from two key set 
     databases.  If both key set database pertains to the same data, there is no 



     Reference manual                                             Page: 13

     real problem, although it's impossible for the SearchSet class to detect 
     this possibility.
     
     ----------------------------------------------
     SearchSet operator * ( const SearchSet & ss );
     
     SearchSet operator * (...)    New search set
     const SearchSet & ss          RHS search set
     
     Description:  The new search set is the result of the union between the 
     actual and the RHS search sets.  If both come from two different key set 
     databases, the new set is separated from its database.
     
     ------------------------------------------
     void operator *= ( const SearchSet & ss );
     
     const SearchSet & ss       RHS search set
     
     Description:  The LHS search set is the result of the union between the LHS 
     and RHS search sets.  If both come from two different key set databases, 
     the LHS search set is separated from its database.
     
     ----------------------------------------------
     SearchSet operator + ( const SearchSet & ss );
     
     SearchSet operator + (...)    New search set
     const SearchSet & ss          RHS search set
     
     Description:  The new search set is the result of the intersection between 
     the actual and the RHS search sets.  If both come from two different key 
     set databases, the new set is separated from its database.
     
     ------------------------------------------
     void operator += ( const SearchSet & ss );
     
     const SearchSet & ss       RHS search set
     
     Description:  The LHS search set is the result of the intersection between 
     the LHS and RHS search sets.  If both come from two different key set 
     databases, the LHS search set is separated from its database.
     
     ----------------------------------------------
     SearchSet operator - ( const SearchSet & ss );
     
     SearchSet operator - (...)    New search set
     const SearchSet & ss          RHS search set
     
     Description:  The new search set is the result of the difference between 
     the actual and the RHS search sets.  If both come from two different key 
     set databases, the new set is separated from its database.
     



     Reference manual                                             Page: 14

     ------------------------------------------
     void operator -= ( const SearchSet & ss );
     
     const SearchSet & ss       RHS search set
     
     Description:  The LHS search set is the result of the difference between 
     the LHS and RHS search sets.  If both come from two different key set 
     databases, the LHS search set is separated from its database.
     
     -----------------------------------------------
     int operator == ( const SearchSet & ss ) const;
     
     int operator == (...)      Returned values
				1 - the two sets are identical
				0 - they exist at least one difference
				    between the two sets
     const SearchSet & ss       RHS search set
     
     Description:  The comparison operator == compares both search sets key by 
     key.  If both search sets are identical, you get a value of 1.  If there is 
     at least a difference between both search sets, you get a value of zero 
     (0).
     
     -----------------------------------------------
     int operator != ( const SearchSet & ss ) const;
     
     int operator != (...)      Returned values
				1 - the two sets are not identical
				0 - they exist at least one identity
				    between the two sets
     const SearchSet & ss       RHS search set
     
     Description:  The comparison operator != compares both search sets key by 
     key.  If both search sets are different, you get a value of 1.  If there is 
     at least an identical key between both search sets, you get a value of zero 
     (0).
     
     --------------------------------------
     int isPattern( char * pattern ) const;
     
     int isPattern(...)         Returned values
				1 - the string is a regular expression
				0 - the string is not a regular expression
     char * pattern             The string
     
     Description:  The isPattern() function allows you to check if there is a 
     regular expression present in the string.



     Reference manual                                             Page: 15

     -------------------------------------------
     int isValidPattern( char * pattern ) const;
     
     int isValidPattern(...)    Returned values
				1 - the string is a valid regular expression
				0 - the string is not a valid regular expression
     char * pattern             The string
     
     Description:  The isValidPattern() function allows you to check if there is 
     a valid regular expression present in the string.
     
     ------------------------------------------------------
     int FindExact( IdType cid, IdType idxid, char * buf );
     
     int FindExact(...)         Returned values
				1 - a set was found for buf
				0 - no set was found for buf
     IdType cid                 Class identification
     IdType idxid               String index identification
     char * buf                 Token to seek
     
     Description:  The key set associated to the token used in parameter is 
     retrieved by the FindExact() function.  If the token does not happen to be 
     indexed or if it has been completely de-indexed, you get a zero (0) value 
     from the FindExact() function and an empty search set.  This function does 
     not allow any regular expression.
     
     ----------------------------------------
     int FindAll( IdType cid, IdType idxid );
     
     int FindAll(...)   Returned values
			1 - a set was found for string index idxid
			0 - no set was found for string index idxid
     IdType cid         Class identification
     IdType idxid       String index identification
     
     Description:  You get the key set of all "idxid" index tokens from the 
     FindAll() function.  It combine all key sets of the index "idxid".  Note 
     that this function keeps the CPU busy for a while.



     Reference manual                                             Page: 16

     ------------------------------------------------------------
     int FindPattern( IdType cid, IdType idxid, char * pattern );
     
     int FindPattern(...)       Returned values
				1 - a set was found for the regular expression
				0 - no set was found for the regular expression
				-1 to -4 - Not a valid regular expression
     IdType cid                 Class identification
     IdType idxid               String index identification
     char * pattern             Regular expression
     
     Description:  The key set associated to the regular expression is retrieved 
     by the FindPattern() function.  It sequentially cover the "idxid" index and 
     associate all key sets which have a token corresponding to the expression.  
     Careful!  This function can keep CPU busy for a long time.  The 
     FindPattern(cid, idxid, "*") call corresponds to the FindAll(cid, idxid) 
     call.  However, the last call is faster.
     
     ----------------
     KeyType First();
     
     KeyType First()   Returned values
		       Key - return the first key of the set
		       0   - if key set is empty
     
     Description:  The First() function returns the first key of the set.  If 
     the set happens to be empty, First() returns a zero (0) value.
     
     ---------------
     KeyType Next();
     
     KeyType Next()       Returned values
			  Key - return the next key of the set
			  0   - after the last key of the set
     
     Description:  The Next() function returns the set next key.  Use the 
     First() function to position yourself to the first element.  The Next() 
     function returns the zero (0) value after the last element.
     
     
     2.5 TODB class description
     
     class TODB
     {
	 ...
     public:
	 TODB();
     
	 ~TODB();
     
	 // -- open a key set database



     Reference manual                                             Page: 17

	 Boolean Open( String & fname_key, String & fname_idx, 
		       int omode );
	 // -- close it
	 void Close();
	 // -- database state
	 Boolean isOpen() const;
     ...
     };
     
     Description:  The key set database is operated by the TODB class.  It is 
     responsible for the database opening and closing and for faults control.  
     You have to assign a global pointer to each key set database.  Most of the 
     TODB library classes use this global pointer in order to transmit their 
     messages to the TODB class or to the other library classes.  For example: 
     the IdxColl uses this pointer to transmit the token that needs to be 
     indexed to the TIndex class which operates the B-tree.  Other classes 
     directly communicate with the TODB class for file access.  So, the first 
     step to take is to assign a global pointer and then to associate it to a 
     TODB object.  The second step to take is to open the database.  Then, you 
     can start your data processing.
     
     ------------------------------------------------------------------
     Boolean Open( String & fname_key, String & fname_idx, int omode );
     
     Boolean Open(...)  Opening state
			1 - opening done
			0 - not opened
     String & fname_key Key set database file name
     String & fname_idx B-tree file name
     int omode          Opening mode
     
     Description:  The Open() function opens two files, the first one for the 
     key sets (.KEY) and the other one for the B-tree index (.IDX).  Different 
     access modes are available:
     
     IDX_CREAT
     Description:  Opens an empty key set database (the .IDX and .KEY files are 
     empty).  Access is denied if the files already exist.
     
     IDX_EXIST
     Description:  Opens an existing key set database.  Access is denied if the 
     files don't exist.
     
     IDX_CREAT || IDX_APPEND
     Description:  Opens a new key set database.  Ascending order keys are 
     required for indexation.  In order to save performance, there is no key 
     validity verification made.  This kind of verification has to be done by 
     the library client.  You draw great benefit from the IDX_APPEND mode when 
     you need in bulk file indexation.  This mode allows you to use the 
     SearchSet class.
     



     Reference manual                                             Page: 18

     IDX_EXIST || IDX_APPEND
     Description:  Opens an existing key set database.  Ascending order keys are 
     required for indexation (see previous mode).
     
     -------------
     void Close();
     
     Description:  The Close() function closes the key set database.
     
     -----------------------
     Boolean isOpen() const;
     
     Boolean isOpen()  Opening state
		       1 - database is opened
		       0 - the database is closed
     
     Description:  The isOpen() function returns the key set database state.
     
     
     2.6 Parameters description
     
     ---------------------------
     const int blocklength = 70;
     
     Description: The block length is defined by blocklength parameter.  A key 
     cannot spill over a file block.  For this reason, the block length value 
     must respect these constraints:
     
     1) For the first block in a key set thread
	block length = 2 * sizeof( BlockNbr ) + sizeof( ObjHeader )
		       + X1 * sizeof( KeyType );
	X1 is the number of keys saved in the first block.
     
     2) For the next block in a key set thread
	block length = sizeof( BlockNbr ) + sizeof( ObjHeader )
		       + X2 * sizeof( KeyType );
	X2 is the number of keys saved in the next block.
     
     Where:
	sizeof( ObjHeader ) = sizeof( IdType ) + sizeof( KeyType );
     
     In general:
	X2 = X1 + 1 or
	X2 = X1 + 2



     Reference manual                                             Page: 19

     Example:
	You need 120 keys by block, a key is four bytes long.
	sizeof( IdType ) is always = 2
	sizeof( KeyNbr ) = sizeof( KeyType ) = 4
	sizeof( ObjHeader ) = 2 + 4 = 6
	First block:
	  2 * 4 + 6 + (X1 = 119) * 4 = 490
	Next block:
	  4 + 6 + (X2 = 120) * 4 = 490
	Block length = 490
     
     So:
     const int blocklength = 490;
     
     -----------------------------
     typedef unsigned int KeyType;
     
     Description: The KeyType parameter defines the key type saved in the 
     database.  We strongly recommend the use of unsigned type.
     
     If you use on an IBM-PC a 2 bytes length key, you must define KeyType of 
     type unsigned int.  On another CPU, unsigned int may have a 4 bytes length.  
     Depending on the CPU, set KeyType to your needs.
     
     -------------------
     typedef int IdType;
     
     Description: IdType defines the indexed class identification (cid) and the 
     string index identification (idxid).  The value of sizeof( IdType ) must be 
     2.  Depending on your CPU, use an appropriate type.
     
     --------------------
     typedef long ObjAdr;
     
     Description: The ObjAdr type defines the logical file block address for 
     KSPersistent class.  If you use this class, you may declare logical address 
     with this type.
     
     
     2.7 Faults control
     
     In general, each library class has its own faults control functions.  
     Faults control functionality is defined by ErrReporter class (its operation 
     mode is very close to the class chosen by Ladd S. Robert, although it is 
     lightly optimized in this case).  The DosErrReporter class is an 
     implementation adapted to the DOS exploitation system of ErrReporter class.  
     For another exploitation system, you will have to define a class coming 
     from the ErrReporter class correctly adapted to the system (for example, an 
     ostream class can be used by DosErrReporter for faults writing).  Please 
     note that the ostream class cannot be used with Windows.  Then, you will 
     have to consequently change the TODB class so that it can use your new 



     Reference manual                                             Page: 20

     definition.  This mechanism is the first step to later introduction of 
     catch and throw instructions.
     
     However, certain classes cannot detect faults.  The TIndex class has two 
     mechanisms: one of the same type than the other classes (ErrReporter class) 
     and another one to retrieve faults generated by the B-Plus shareware (C 
     language Exit() function).
     
     The TODB class can activate or stop faults control of each library class.  
     In changing this class code, you can adapt faults control according to 
     your needs.
     
     
     3. LEGAL ISSUES
     
     3.1 License
     
     This current license that has been provided to you by this convention 
     allows you to:
     
     1) Use the TODB library as a development tool for only one computer.
     
     2) Copy the TODB library in any acceptable way you chose, whether with a 
	computer or in writing, in order to save copies or for modification
	purposes so you could use only one computer.
     
     3) Change the TODB library or to combine it with any other software so you 
	could use it with only one computer.    You will have to copy and include the
	royalties notice on all copy, change or any combined part of another
	software.
     
     You have the right to use or sell, without any restrictions or royalties to 
     its author, any program executable in machine code pertaining to all or 
     part of the TODB library.
     
     You must have the written agreement of its author for any publication of 
     all or part of the TODB library.
     
     It is forbidden to use, copy, change or transfer the TODB library or any 
     other copy, modification or merged part in all or in part without taking 
     into account this convention agreement. 
     
     
     3.2 Guarantee
     
     Users of TODB library must accept this guarantee:
     
     TODB library is supplied as is. The author disclaims all guarantees, either 
     expressed or implied, including, without limitation, the guarantees of 
     merchantability and of fitness for any purpose. The author assumes no 
     liability for damages, direct or consequential, which may result from the 



     Reference manual                                             Page: 21

     use of TODB library.
     
     
     3.3 Registration
     
     If you continue using TODB library after a reasonable trial period, you
     must register.  To do this, either print and fill in the registration form
     provided (type "COPY ORDER.TXT PRN" at the DOS prompt), or send a check or
     money order for $35US + shipping or $45CA + shipping.  If you are a
     Canadian resident, add GST to $45CA+$3CA (7% * $48CA = $51.36CA) and
     if you are a Province of Quebec resident, add PST to $51.36CA
     (8% * $51.36CA = $55.47CA).

     Send your payment to the following address:
     
	 DALIPLUS enr.
	 8535, Saint Gerard street,
	 Montreal (Quebec)
	 Canada
	 H2P 2E3
	 Phone (514)382-8178
     
     You will receive the latest version of TODB library, full source code and 
     free support.
     
     
     3.4 User support
     
     The support is provided to all registered users of TODB library direct from 
     DaliPlus enr. Check the front of this manual for contact details.  If you 
     have any suggestions or comments, please write to us or give us a call.
     
     
     4. CONCLUSION
     
     In developing TODB, our purpose was to offer you all the flexibility of an 
     object oriented design for indexation and data retrieval.  We have chosen 
     the C++ language because of its great possibilities.
     
     This library was greatly influenced by a certain number of object oriented 
     specialists.  The KSPersistent class, its satellite classes and the 
     interface organization of the IdxColl class have been inspired by Al 
     Stevens' work.  The C++ faults control come from Scott Robert Ladd's work.  
     The C B-Plus faults control module used by the TIndex class has been 
     inspired by Scott Meyers.  James O. Coplein's ideas have also been of a 
     great influence to us.  And finally, Bjarne Stroustrup has inspired the 
     TODBmgr application framework class and the MakeToken abstract class.
     
     I would like to thank all these specialists.
     
     And also, I would like to particularly extend my thanks to Linda Cazale and 
     Richard Gagnon for their comments, corrections and encouragement.



     Reference manual                                             Page: 22

     5. REFERENCES
     
     Coplien, James O., Advanced C++ programming styles and idioms,  Addison-
     Wesley, 1992.
     
     Dromey, R. G., How to Solve it by Computer, Prentice-Hall International, 
     1982.
     
     Ladd, Scott R., C++ Components and Algorithms, M&T Books, 1992.
     
     Meyers, Scott, Effective C++ 50 Specific Ways to Improve Your Programs and 
     Designs, Addison-Wesley, 1992.
     
     Stevens, Al, C++ Database Development, MIS:Press, 1992.
     
     Stroustrup, Bjarne, The C++ programming language, second edition, Addison-
     Wesley, 1991.
