//	File:	BCWIZ.TXT

//                                                   September 20, 1993
//                                                   Fairfield, Iowa

//          Aerosoft  (R)  Broadcast Channel Wizard   Version 1.0
//          Copyright (c)  Aerosoft 1993     All rights reserved.

//          This software source code is FREEWARE.  You may be use the
//          source code or redistribute the source code free of charge.
//          However, you cannot sell this source code or any alteration of
//          the source code.

This file documents some design notes about the program.  See file BCWIZ.MAN 
for a description of the operation of the BCWIZ program.  Before reviewing
this document please read BCWIZ.MAN for an explanation of the concept of a
Broadcast Channel.  Note that an object listening to a channel is called a
consumer while an object sending data is called a producer.

BCWIZ reads an input file specifying broadcast channels and it generates
four files that can be used to implement these channels.

This translation is done in two steps:  the broadcast channel specs are
deciphered and stored in a database.  The channel specs database is then
used to generate the output files.

BCWIZ uses two principle objects to decipher the channel specs: InStream 
and ChannelSpecs.  InStream reads each channel spec entry into a buffer
and provides parsing member functions for extracting tokens from an entry.
There are three kinds of tokens: numbers, labels, and 1-char delimiters.
ChannelSpecs provides a database holding each deciphered channel entry.

A deciphered channel spec consists of six parts:

	return type specifier  (only int, long, float, double, and void are legal)
	function name
	proto-list			   (the argument list including the arguments' type
	                        specifiers)
	arg-list			   (a list of argument names without type specifiers)
	default return value
	max receivers		   (the max number of objects that can be connected to
	                        the channel)
	                        
Member function GetNextChannelSpec deciphers a spec.  It relies upon the
parsing functions of InStream to do this.  It scans left to right looking for
each component of a channel spec. 

NOTE: InStream skips nested parenthesis that may be found inside and argument list.
      This simplifies the work that GetNextChannelSpec must do.
      
Once the channel specs have been deciphered, code generation is a simple matter
of taking each spec and generating "cookbook" code.  This code is as follows:

	1) CHNNLDEF.H declares a class for every channel specified.  Each class
	   declares a pure-virtual member function.  This approach lets C++'s
	   polymorphism route channel messages to the appropriate objects.
	   
	2) BRDCASTR.H declares the class Broadcaster and a global object, oBroadcaster.
	   All broadcast messages are routed thru object oBroadcaster.  For each
	   channel there are four member functions:
	   
	   		Connect, Disconnect, ChannelStatus, Broadcast<channel name>
	   		
	   Connect and Disconnect are used by broadcast consumers to control message
	   routing to themselves.  Broadcast<> is used by a producer to forward
	   a message.  Anyone can use ChannelStatus -- examples are checking whether
	   a connect or disconnect was successful or checking whether a channel has
	   anyone connected.
	   
	   Broadcaster uses function overloading to map from a channel class to
	   the corresponding channel list.  This is done for Connect, Disconnect, and 
	   ChannelStatus.
	   
	   There is a separate ChannelList object for each channel.  This is done for
	   future enhancement when templates are supported.  Then, channel list pointers
	   can refer to channel classes rather than being "void" pointers.
	   
	3) BRDCASTR.CPP defines object oBroadcaster and it's member functions.
	
	4) APP.CPP contains code templates.  It is available to assist programmers in
	   writing code for producers and consumers.

There are two static support files that augment the above four files:

	1) CHANNEL.H declares class ChannelList.  It is used by BRDCASTR.H
	
	2) CHANNEL.CPP defines the member functions of class ChannelList.	     		      	                        


When writing code for a producer or consumer, include file CHNNLDEF.H
Classes that define objects consumers must be derived from the corresponding
broadcast channel's class.  If an object receives data from more than one channel,
then use multiple inheritance.

Build your application by including modules BRDCASTR.CPP and CHANNEL.CPP in your 
project.

Review the example program provided to get a better understanding about the use
of the Broadcast Channel Wizard.