// $Revision: 1.6 $
// Copyright (C) 1995 Taligent, Inc. All rights reserved.
#if 0
---------------------------------------------------------------------------
> Class:
 | TStockServer  
> Taxonomy Category:
 | Documented Samples  
 | Stock Browser:Stock Server  
> Interface Category:
 | Sample.  
> Inherits From:
 | TStockDatabase 
> Inherited By:
 | None. 
> Purpose:
 | This class is the core of the Stock Server. It does the real work of getting data from the permanent stock data store, which it keeps in a TDiskDictionaryOf< >.
> Instantiation:
 | Always allocate on the heap.  
> Deriving Classes:
 | No special instructions.  
> Concurrency:
 | _Not_ multithread safe.  
> Resource Use:
 | No special requirements.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::TStockServer ;
 | 1. TStockServer ()  
 | 2. TStockServer (const TStandardText & dataDirectory, const TStandardText & dataFileName)  
> Interface Category:
 | Sample.  
> Purpose:
 | 1. Default constructor.  
 | 2. Constructor. Clients must use this.  
> Calling Context:
 | 1. Called by derived classes and to construct an object.  
 | 2. Called to construct a valid object.  
> Parameters:
 = 1. Takes no parameters.  
 = 2. const TStandardText & dataDirectory -The directory in which to create or open the persistent storage.  
 = 2. const TStandardText & dataFileName -The name of the disk dictionary to create.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::~ TStockServer ;
 | virtual ~ TStockServer ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Destructor.  
> Calling Context:
 | Called to destroy an object.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::operator >>=;
 | virtual TStream & operator >>=(TStream & toStream) const  
> Interface Category:
 | Sample.  
> Purpose:
 | Stream-out operator.  
> Calling Context:
 | Called to stream out data.  
> Parameters:
 = TStream & toStream -The stream the object streams itself out to.  
> Return Value:
 | Returns a reference to the stream the object streams itself out to.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::operator <<= ;
 | virtual TStream & operator <<= (TStream & fromStream)  
> Interface Category:
 | Sample.  
> Purpose:
 | Stream-in operator.  
> Calling Context:
 | Called to stream in data.  
> Parameters:
 = TStream & fromStream -The stream the object streams itself in from.  
> Return Value:
 | Returns a reference to the stream the object streams itself in from.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::CopyAvailableNames ;
 | virtual void CopyAvailableNames (TCollectionOf < TStandardText > & collectionToFill) 
> Interface Category:
 | Sample.  
> Purpose:
 | Copies the names of available stocks from the disk dictionary.  
> Calling Context:
 | Called by TStockDispatcher::CopyAvailableNamesStub.  
> Parameters:
 = TCollectionOf < TStandardText > & collectionToFill -The collection to fill
with stock names.
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::CopyAllStocks ;
 | virtual void CopyAllStocks (TCollectionOf < TStockData > & collectionToFill) 
> Interface Category:
 | Sample.  
> Purpose:
 | Creates and returns a TLocalStockData object for each of the stocks in the disk dictionary.  
> Calling Context:
 | Called by TStockDispatcher::CopyAllStocksStub.  
> Parameters:
 = TCollectionOf < TStockData > & collectionToFill -The collection to fill with TStockData objects.
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::CopyStock ;
 | virtual TStockData * CopyStock (const TStandardText & stockName)  
> Interface Category:
 | Sample.  
> Purpose:
 | Creates and returns a TLocalStockData object for the given stock.  
> Calling Context:
 | Called by TStockDispatcher::CopyStockStub.  
> Parameters:
 = const TStandardText & stockName -The name of the stock to create a TStockData object for.  
> Return Value:
 | A pointer to a new TStockData object.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::CopyStockData ;
 | virtual bool CopyStockData (const TStandardText & stockName, TCollectionOf < TStockDay > & collectionToFill, const TRangeOfDays & range =TRangeOfDays :: kAllDays) 
> Interface Category:
 | Sample.  
> Purpose:
 | Copies some or all of the data for a particular stock from the disk dictionary.  
> Calling Context:
 | Call this function directly.  
> Parameters:
 = const TStandardText & stockName -The name of the stock for which to retrieve data.  
 = TCollectionOf < TStockDay > & collectionToFill -The collection to fill with
stock data.
 = const TRangeOfDays & range =TRangeOfDays :: kAllDays -The range of time for which to retrieve stock data.  
> Return Value:
 | Returns true if the function ended normally, false if not. This is useful for example, when the collection comes back empty, in figuring out whether it's empty because there was no data (a return value of true) or whether the specified stock didn't exist (a return value of false).  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::GetTimeStamp ;
 | virtual TPseudoTimeStamp GetTimeStamp ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Returns a time stamp indicating how recent the set of stock data is.  
> Calling Context:
 | Call this function directly.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | A TPseudoTimeStamp object.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::AddStockData ;
 | virtual void AddStockData (const TStandardText & stockName, const TDirectory & sourceFileDirectory, const TStandardText & sourceFileName)  
> Interface Category:
 | Sample.  
> Purpose:
 | Adds stock data to the server's persistent storage.  
> Calling Context:
 | Called by the setup program.  
> Parameters:
 = const TStandardText & stockName -The name of the stock to add.  
 = const TDirectory & sourceFileDirectory -The directory object representing the directory that contains the source data file.  
 = const TStandardText & sourceFileName -The name of the source data file.  
> Return Value:
 | None.  
> Exceptions:
 | Passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::GetDictionary ;
 | TServerDictionary * GetDictionary ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Returns a pointer to the disk dictionary object.  
> Calling Context:
 | Called by this class and derived classes.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | A pointer to the disk dictionary.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | This creates the disk dictionary if it doesn't exist.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::CreateOrOpenDiskDictionary ;
 | TServerDictionary * CreateOrOpenDiskDictionary ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Creates a new disk dictionary or opens an existing one and uses it as the persistent storage for the server.  
> Calling Context:
 | Called by GetDictionary and this object's constructors.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | A pointer to the disk dictionary.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServer::HandleCreateStock ;
 | virtual TStockData * HandleCreateStock (const TStandardText & stockName)  
> Interface Category:
 | Sample.  
> Purpose:
 | Creates a TStockData object for the specified stock. This is in a separate function to factor code into smaller, more easily overridable, pieces.  
> Calling Context:
 | Called by CopyStock.  
> Parameters:
 = const TStandardText & stockName -The name of the stock to create a TStockData object for.  
> Return Value:
 | A pointer to a new TStockData object.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Typedef: TStockServer :: TServerDictionary
 | typedef TDiskDictionaryOf < TStandardText , TCollectionOf < TStockDay > > TServerDictionary
> Taxonomy Category:
 | Documented Samples.  
> Interface Category:
 | Sample.  
> Purpose:
 | This is a short typedef for a long class name.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Typedef: TStockServer :: TServerDictionaryIterator
 | typedef TDiskDictionaryIteratorOf < TStandardText , TCollectionOf < TStockDay > > TServerDictionaryIterator
> Taxonomy Category:
 | Documented Samples.  
> Interface Category:
 | Sample.  
> Purpose:
 | This is a short typedef for a long class name.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Class:
 | TStockDispatcher  
> Taxonomy Category:
 | Documented Samples  
 | Stock Browser:Stock Server  
> Interface Category:
 | Sample.  
> Inherits From:
 | MRemoteDispatcher 
> Inherited By:
 | None. 
> Purpose:
 | This is the receiver (dispatcher) side of the Stock Server caller-dispatcher pair. It unmarshals function arguments, dispatches control to its implementation object, and marshals the results back across the RPC connection.  
> Instantiation:
 | Allocate on the heap or the stack.  
> Deriving Classes:
 |  
> Concurrency:
 | _Not_ multithread safe.  
> Resource Use:
 | No special requirements.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::~ TStockDispatcher ;
 | virtual ~ TStockDispatcher ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Destructor.  
> Calling Context:
 | Called to destroy an object.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::CopyStockStub ;
 | void CopyStockStub (TStream & argStream, TStream & resultStream)  
> Interface Category:
 | Sample.  
> Purpose:
 | Unmarshals function arguments and dispatches control to the implementation object's CopyStock function. Marshals the results back across the RPC connection.  
> Calling Context:
 | Called by the RPC services.  
> Parameters:
 = TStream & argStream -The stream to read arguments from.  
 = TStream & resultStream -The stream to write results to.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::CopyAllStocksStub ;
 | void CopyAllStocksStub (TStream & argStream, TStream & resultStream)  
> Interface Category:
 | Sample.  
> Purpose:
 | Unmarshals function arguments and dispatches control to the implementation object's CopyAllStocks function. Marshals the results back across the RPC connection.  
> Calling Context:
 | Called by the RPC services.  
> Parameters:
 = TStream & argStream -The stream to read arguments from.  
 = TStream & resultStream -The stream to write results to.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::CopyStockDataStub ;
 | void CopyStockDataStub (TStream & argStream, TStream & resultStream)  
> Interface Category:
 | Sample.  
> Purpose:
 | Unmarshals function arguments and dispatches control to the implementation object's CopyStockData function. Marshals the results back across the RPC connection.  
> Calling Context:
 | Called by the RPC services.  
> Parameters:
 = TStream & argStream -The stream to read arguments from.  
 = TStream & resultStream -The stream to write results to.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::CopyAvailableNamesStub ;
 | void CopyAvailableNamesStub (TStream & argStream, TStream & resultStream)  
> Interface Category:
 | Sample.  
> Purpose:
 | Unmarshals function arguments and dispatches control to the implementation object's CopyAvailableNames function. Marshals the results back across the RPC connection.  
> Calling Context:
 | Called by the RPC services.  
> Parameters:
 = TStream & argStream -The stream to read arguments from.  
 = TStream & resultStream -The stream to write results to.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::GetTimeStampStub ;
 | void GetTimeStampStub (TStream & argStream, TStream & resultStream)  
> Interface Category:
 | Sample.  
> Purpose:
 | Unmarshals function arguments and dispatches control to the implementation object's GetTimeStamp function. Marshals the results back across the RPC connection.  
> Calling Context:
 | Called by the RPC services.  
> Parameters:
 = TStream & argStream -The stream to read arguments from.  
 = TStream & resultStream -The stream to write results to.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Enumeration:
 | TStockDispatcher :: EStockDispatcherRequest  
> Taxonomy Category:
 | Documented Samples.  
> Interface Category:
 | Sample.  
> Purpose:
 | Defines the requests that can be made of the Stock Server. TStockDispatcher handles the requests.  
> Tags:
 = kCopyAvailableNames -Return the names of all available stocks.  
 = kCopyAllStocks -Return a new TStockData object for each available stock.  
 = kCopyStock -Return a new TStockData object for a particular stock.  
 = kCopyStockData -Return a collection of TStockDay object containing the data for a particular stock.  
 = kGetTimeStamp -Return the time stamp of the Stock Server's data.  
 = kLastRequest -Used internally by TStockDispatcher.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::operator <<= ;
 | virtual TStream & operator <<= (TStream & fromStream)  
> Interface Category:
 | Sample.  
> Purpose:
 | Stream-in operator.  
> Calling Context:
 | Called to stream in data.  
> Parameters:
 = TStream & fromStream -The stream the object streams itself in from.  
> Return Value:
 | Returns a reference to the stream the object streams itself in from.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::operator >>=;
 | virtual TStream & operator >>=(TStream & toStream) const  
> Interface Category:
 | Sample.  
> Purpose:
 | Stream-out operator.  
> Calling Context:
 | Called to stream out data.  
> Parameters:
 = TStream & toStream -The stream the object streams itself out to.  
> Return Value:
 | Returns a reference to the stream the object streams itself out to.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::TStockDispatcher ;
 | 1. TStockDispatcher (TStockDatabase * implementation)  
 | 2. TStockDispatcher ()  
> Interface Category:
 | Sample.  
> Purpose:
 | 1. Constructor.  
 | 2. Default constructor.  
> Calling Context:
 | 1. Called to construct a valid object.  
 | 2. Called by derived classes.  
> Parameters:
 = 1. TStockDatabase * implementation -The implementation object to forward requests to.  
 = 2. Takes no parameters.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockDispatcher::LaunchStockServer ;
 | static void LaunchStockServer (const TQualityOfService & networkOrSameHost)  
> Interface Category:
 | Sample.  
> Purpose:
 | Starts up the Stock Server.  
> Calling Context:
 | Called by the Stock Server launch program.  
> Parameters:
 = const TQualityOfService & networkOrSameHost -Indicates what type of service to start.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Class:
 | TStockServerShutdownHandler  
> Taxonomy Category:
 | Documented Samples  
 | Stock Browser:Stock Server  
> Interface Category:
 | Sample.  
> Inherits From:
 | TShutdownHandler 
> Inherited By:
 | None. 
> Purpose:
 | A shutdown handler for the Stock Server.  
> Instantiation:
 | Allocate on the heap or the stack.  
> Deriving Classes:
 | No special instructions.  
> Concurrency:
 | _Not_ multithread safe.  
> Resource Use:
 | No special requirements.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServerShutdownHandler::TStockServerShutdownHandler ;
 | TStockServerShutdownHandler ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Default constructor.  
> Calling Context:
 | Called to construct an object.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServerShutdownHandler::~ TStockServerShutdownHandler ;
 | virtual ~ TStockServerShutdownHandler ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Destructor.  
> Calling Context:
 | Called to destroy an object.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif
#if 0
---------------------------------------------------------------------------
> Member Function: TStockServerShutdownHandler::CompleteShutdown ;
 | virtual void CompleteShutdown ()  
> Interface Category:
 | Sample.  
> Purpose:
 | Shuts down the Stock Server.  
> Calling Context:
 | Called by the Shutdown framework.  
> Parameters:
 = Takes no parameters.  
> Return Value:
 | None.  
> Exceptions:
 | Throws no exceptions, passes all exceptions through.  
> Concurrency:
 | _Not_ multithread safe.  
> Other Considerations:
 | None.  
---------------------------------------------------------------------------
#endif