Instructions for the Installation and Use
	of the Computerized Operating System Software (COSS)
		   by Mark J. Quarles
		  Updated August, 1991

	The following instructions are intended to assist you in installing
COSS on your computer and getting it up and running.  Please note that they
are supplemented by the descriptive information in the appendix relative to
setting up the bill of lading database.  This portion
of the paper will not cover the detail of that item.

	First, some general information.  COSS was conceived and written
by myself for simulating operating conditions on my model railroad layout,
the York Haven Short Line.  The operating environment for this 
software is Microsoft Windows 3.x . 

	The programs are written in Visual Basic, and require that the file 
VBRUN100.DLL exist in your search path.   These programs are NOT
public domain.  However, you may freely copy  the
programs and distribute them and their associated documentation to other model
railroaders as long as NO FEE (other than the contribution suggested for the
author) is charged and as long as the programs and title screens remain 
unchanged.  Their distribution on "shareware" or other types of packages where
a fee is charged to receive individual or groups of disks or programs is 
specifically prohibited.

	One other point before launching into the installation procedures...
No warranties, express, implied, or otherwise, are made with respect to what
these programs do/will do/can do/won't do.  If you load them into a machine,
you take all responsibility for what happens.  They work for me on my system,
but I don't guarantee what will happen anywhere else!

Installation

	Well, if you have read all of the preceding, and are still with us,
great!  Let's see if we can get this stuff installed and running on your
machine!

To run this software, you must have an IBM PC,
PS/2, or 100% compatible with a hard disk drive.  This 
software is not intended to operate on a system without a 
hard disk drive and is only intended to operate under MS Windows 3.x.

	To install this software on a hard disk, you must first create
a subdirectory in which to place it.  Subdirectories are used as a place
to put related groups of files so they won't bump into each other.


Then, all that you need to do is unzip the ZIPfile containing the 
programs, placing all of the programs into the subdirectory.  

You may execute the programs under Windows in 1 of 2 ways:

- From the main program manager window use the run command to execute 
the program that you want (e.g. if your files are in the COSS subdirectory, 
then you would select run and enter the filename \coss\billgen.exe to 
execute the billgen program)

- Build a program group, and add the programs to it (this is the 
preferred method).  Follow the instructions for carrying out this 
activity in your Windows documentation.  

- All further discussions will assume that you have built a program 
group for executing the programs, and that you execute a program by 
double clicking on its icon.


Configuring the Software

Road Name
		
	Naturally, you will want all of the documents to be printed using
your road name.  The NAMER program takes care of that problem.  

Double click on the Namer icon and you will be placed in the Namer program.  
If you have already specified a roadname, it will be displayed for you.  

To change the roadname, simply place the cursor in the box provided and 
type the name that you want for your pike.  When you are finished, select 
the SAVE option and you are finished.  Quit will take you back to the 
Windows environment.

Rolling Stock Types

	To provide maximum flexibility in configuring the software for
other systems, the COSS has no fixed car types.  You may define as many 
types (e.g. flatcar, boxcar, etc) of cars that you will be using
on your layout as you desire.

	The file that contains this information is the datafile
CARTYPES.DAT.  This datafile should be created using any text editor
or word processor that can create straight ASCII datafiles (e.g. the
EDLIN editor that comes with PCDOS, or EDIT under MSDOS 5.0).  A 
sample cartypes datafile is included in the ZIPfile with the programs.

	For our example, we will use the dos editor EDLIN:

From the dos prompt, type :

EDLIN CARTYPES.DAT

You will be rewarded with an * prompt.  Type :

1i

and you will get a line number 1 prompt.  Now, just type in the name of 
the car (enclosed in double quotes) and press the ENTER key at the end 
of each line.  After you type the last line, press CONTROL-Z (hold down 
the control and Z keys at the same time) then ENTER.  This will get you 
back to the * prompt.

	Now, just type:

E

and you will exit back to the dos prompt.


	The format of the records in this datafile is
the name of the car type (imbedded spaces are allowed) surrounded by 
double quote characters.  Each record is terminated with a carriage-return 
linefeed pair.

	As an example, the following might be the lines in a typical
CARTYPES.DAT:

	"Boxcar"
	"Flatcar"
	"Cushion Boxcar"

	This datafile must be created prior to attempting to use 
either the car location database OR the bill of lading generator.

	Prior to running any of the other programs, you must also
create the database of valid locations (PLACES.DAT).  The creation of
this database is described under the CAR LOCATION system.  This database
must be created before attempting to run any of the other editors.


Bill of Lading Database

	The program BILLGEN is used to manage the database of bills of 
lading that you will create.  These bills are the heart of the system.
More detailed information on how to develop the information you will need 
for this database is contained in the clinic notes in the appendix.

	To enter the program, you select it from the program group by 
	double clicking on its icon.


	NOTE:  Do NOT run the BILLGEN Generate bills option until you
	       have configured the CAR DATABASE.  

	In Billgen, the following options are available to you:

	Adding a bill to the database
	----------------------------

	This is the option you will use to create the database of bills.

	You will be asked to supply the information on the location and
name of the originating shipper and consignee, contents of the car, type 
of car, revenue generated, interchange information, etc.  You supply this 
information by simply filling out the blanks in the form presented on the 
screen.  You then select the manage menu option, and then select the Add 
option.  You will be asked how many of this bill to add.  It should be 
noted that you may place any information that you wish in the fields 
(this is allowed for maximum flexibility), however, as an aid to creating 
a valid database, you should use the buttons located next to the various 
windows to fill in the data for that window.  These buttons are provided 
wherever the data entered must match the data from other databases (e.g. 
the locations to and from must exist as valid locations in the PLACES.DAT 
datafile).  Clicking on one of these buttons will provide a scrollable 
list of data from which you may select the desired item.  Clicking 
the button again will remove the list from the screen.




	Printing  the Bill database

	This option will give you a printout of all of the information you
have in the bill of lading database.  Note that bills that are in use on 
your layout are not in the BILL_BOX.DAT database (as explained in the 
appendix), and as such, will not appear on the printout
from this option.

	Viewing the database
	-------------------

In order to view the data in the bill database, simply click on the 
view next button.  This will replace the data on the screen with the 
data for the next bill sequentially in the datafile.

The screen will indicate which database (available bills or used bills) 
is being displayed.  You can switch from one to the other by use of the 
menu option provided under view.


	Delete a bill from the database
	---------------------------------

In order to remove a bill from the database, you should use an editor 
on the datafile BILLBOX.DAT.  This is the datafile which contains all 
of the bill of lading information in comma-delimited format.  Simply 
pick the bill(s) that you wish to remove and delete the lines that they 
are on.  When you save the datafile back out, the bills are eliminated.


	Generate bills for operation
	------------------------------

	Ah, the meat of the subject!  When you are ready to use the system,
this is where you get COSS to generate the bills of lading for your operating
session.  It will ask you how many bills to generate, and will then proceed
to assign cars to them.  You will be able to watch the system analyze the 
car database looking for the appropriate type of car at the appropriate 
location in the required status.  If a suitable car is found, the system 
will tell you that it has a match.  If no suitable car is located, you 
will get a message box informing you of that fact.  You may then either 
continue assigning bills, or cancel the generation of further waybills.  
The bills already assigned will be issued. 

When you assign a car to a bill, The car load status will be set to Loaded 
by the system 

	Bills that you don't assign a car to are left in the database, and
will be presented to you again next time for assignment.

	The bills print out four to a page on standard printer paper.


	In order to prevent a buildup of cars at destination locations
as an end result of cars being shipped to the destinations without a 
corresponding movement of empty cars back to the originating point, it 
is the responsibility of the station agents on my layout to manually 
route empty cars to the originating points of the loads (in other words,  
when a car is delivered loaded to a shipper, an empty of the same type 
is routed back to the original shipper to reloading for a later shipment).



	Report a bill as completed
	----------------------------

	After a bill of lading has been completed (that is, after the car
specified on the bill has been delivered 
to the destination specified on the face of the bill) you need to tell the
system that it is done.  This is the option that you use to do that.

	In order to report a bill completed, simply enter the bill number 
in the appropriate field on the screen, then from the manage menu, select 
the report completed option (it is not important what is in the other 
fields on the screen).  If the bill is found, it will be removed from the 
USEDBILL.DAT datafile, returned to the bottom of the available bills, 
and the car that was being shipped will be reported as moved to the 
destination location and marked as empty.


	If you enter a bill number that does not exist as an active bill,
the system will tell you that that bill does not exist.

	It is important, if you want to be able to use the features of the
system to suggest cars for assignment, etc. that you keep the CAR LOCATION
database updated.  When you report a car as moved, be sure to update its
status (availability for assignment), as the system marks a car as
unavailable for assignment when the car is assigned to a bill .


	Quit
	------

	Like it says.

		Shuffling the Bill Database


	As you will see from the discussion in the appendix, the bill
database will order itself based on the way that bills are used and 
returned to the database.  Over a period of time, this may (should) result
in a particular order to the datafile.  The SHUFFLE option may be run
at any time to rearrange the bills into a pseudo-random order, which will
break up any clustering of bills in the system.  This SHUFFLE operation
is also useful after you enter a group of bills into the system, to insure
that they are evenly spread out in the datafile.

	To run the shuffle on the bill database, simply select the option 
from the manage menu.  You will see the bills as they are read and written 
and will be notified when the shuffle is completed.


		The Car Location Database


	The car location database is the second database you must setup.
This system tracks the car types, reporting marks, location, load status,
and availability for use.

	The first thing you must do is create the datafile of valid locations.
This file contains records that name the places
that a car may be sent.  If a place is not entered into this datafile, you
will be unable to inform the system that a car has been sent there.  A 
sample PLACES.DAT datafile is included in the ZIPfile.


	Using any standard ASCII TEXTFILE editor (i.e. don't use a word
processing program that will not save data as a standard dos textfile)
create the datafile PLACES.DAT.  For our example, we will use the dos
editor EDLIN:

	From the dos prompt, type :

	EDLIN PLACES.DAT

You will be rewarded with an * prompt.  Type :

1i

and you will get a line number 1 prompt.  Now, just type in the names of
the places (enclosed in double quotes)  pressing the ENTER
key at the end of each line.  After you type the last line, press CONTROL-Z
(hold down the control and Z keys at the same time) then ENTER.  This will
get you back to the * prompt.

	Now, just type:

E

and you will exit back to the dos prompt.

	You should enter the location names in the order that a train
would reach them traveling in one direction from one end of your layout
to the other.  This requirement is only important if you intend to use the
switchlist generator module when it becomes available.

	Now you can use the car location database system.  To do this,
double click on the CARLOC icon.  This will invoke the database
program.

	From the program, you may do the following things:

	Print out a list of car locations
	-----------------------------------

	Selecting this option will allow you to get printouts of the 
car database.

	Report a car movement
	-----------------------

	This option allows you to report that a car has moved from one
location to another.   Enter the reporting marks on the screen where 
indicated, and then select the menu option to find the specified car.  
After the screen is updated to show you the current data on the car, 
simply change the location (or other) fields and then select the menu 
option to change the displayed car record.


	Adding a new piece of rolling stock
	----------------------------------

	This option is used to add a car to the database.  All of the cars
that you will be using must be entered into the database.  When you get new
stock, you must enter those cars into the system before they can be used.

To add a new car to the database, simply fill out all of the fields on the 
screen, then select the menu option to add a car.

When adding a car, you must enter the reporting marks of the car
(which must be unique... ), type of car (e.g. tank, box, etc.), current 
location, status (available for use or unavailable), and load status 
(loaded or unloaded).


	Deleting a car from the database
	--------------------------------

Simply get the data for that car displayed on the screen, then select 
the option to delete the car record.



	Listing the car database
	-----------------------

	This will list the database to the screen for your review.

To list the database to the screen, simply press on the view next button 
each time you wish to view the next car record in the datafile.

TIMER
			
The timer program provides a simple fast clock for use in operating 
session management.  

Simply double click on the timer icon to invoke the program.

You may start the clock at midnight (00:00:00) by simply pressing the 
start button.

To set the fastclock to a specific time, use the set time option, and 
then press the start button.

To suspend the fast clock at any time, press the start / stop button.

The status of the clock (running or not running) is displayed at the 
bottom of the window.


		Closing Comments

	At the end of each operating session, you should get a car
summary report from carloc, note which cars have been moved to new locations
(that still have not been delivered to their final destination), and then
use CARLOC to update their locations on your layout (although this is 
not necessary for use of the software, it is quite helpful as a record 
of the operating session in the event that you move some cars before the 
next operating session).

	I and my fellow model railroading friends have found this suite of
programs greatly increased our enjoyment of operating sessions on the
York Haven Short Line by taking the tedious motion out of tracking orders
and generating forms and actions.  I hope you get as much enjoyment out of
them as we do!

		Happy Model Railroading!



	Appendix to the Computerized Operating Software System
		    manual by Mark J. Quarles

		The Bill-of-Lading Generator
		----------------------------

		Selection of Bill Elements
		--------------------------

	Any business that is in operation, has requirements for raw materials
to come in, and for products to leave.  If either of these goes for too long
without being met, the business must shutdown until the shipments or receipts
can catch up.

	The basis of the bill database is a frequency table for the 
businesses on the layout.  The following paragraphs will discuss how to 
construct this table and use it to create the database.

	The first step in creating the frequency table, is to write down
the names of all of the businesses on the layout that will send products or
receive raw materials. Leave enough space (5 or 6 lines typically should 
do it) for the next step.

	After the list of businesses has been generated, you need to write 
down what you think the raw materials used by the facilities would be 
(for example, a furniture manufacturer would receive lumber, paint, 
adhesives, varnishes, occasional tools or metal fixtures).  After you 
have done this for the raw materials, do it for the products (in the case 
of our furniture manufacturer, he ships out chairs, tables, etc.).

	Now, select a time period as your basis (I used 4 weeks on my layout)
and next to each product or raw material, write down how many shipments
or receipts of that item would be made in your base time period.  Using a 
4 week period instead of a 2 week period allowed me to account for some
interesting, but infrequent, shipments to a couple of businesses.

	The last step in creating the frequency table is to go through the
list one last time and write down the type of car that would be used for
each of the shipments (boxcar, reefer, flat, etc.).

	Note that as you use the bill generator, you will find that this
base set of frequencies may not be ideal for your layout (factors such as
siding capacities, number of a type of car (e.g. you have lots of reefers 
and want a lot of reefer traffic), etc. can affect how well this estimate
of frequencies suits your system), but it is a very good starting point.
You can fine tune the database as you use it.

		Developing the Bills
		--------------------

	Now that we have the frequency table put together, we need to
develope the information that each bill will require.  To do this, you
will need some more paper and a fresh pencil.

	For each business and type of shipment, label a piece of paper with
the business name and type of material.

	We will now write down for each page, the name and location of the
shipper or consignee.  If the shipper or consignee is another business on
the layout, each time we write them down on one sheet, we need to make the
alternate entry on the other sheet (e.g. if we have a furniture manufacturer
that receives lumber from a lumber mill, the lumber mill should be shipping
to the furniture manufacturer).  If the shipper or consignee is off of the
layout (via an interchange point), we need to note this on the shipment data.

	The last step is to go through the pages, and delete common 
shipments (in the case above with the lumber and furniture manufacturers, we
need to delete either the shipper or consignee entries for each of those
shipments).  If we don't do this, then we will be effectively doubling the
frequency of shipments for that type of material.

			Creating the Database
			---------------------

	Finally,  we are ready to create the database of bills.

	Taking our pages from above in hand, settle down with the BILLGEN
program, and start entering bills. Just go through the list, and create an
entry for each entry on the sheets.  It is at this point that you can add
some extra touches, such as notes on flammables not to place them closer
than one car from the engine or caboose, etc.

	When you are entering this information, you should enter one bill
from a page, mark it off, then turn to the next page.  Go through the entire
pile of paper, then start off at the top of the pile again.  After you have
entered all of the items from a piece of paper, you can remove it from the
stack you are working with.  This will start the database off equally
distributed.  You may also select any other methodology that you wish for
tracking the bills as you enter them.  In any event, you should run the
SHUFFLE program after you enter the bills, and prior to the first use of
the system to generate bills for use.  This will assure an even distribution
of the bills in the system.  This program may also be run at any time that
you desire to reorder the database into something approaching a normal
distribution (such as after entering a new batch of bills to the end of
the database).

		How the Bill Generator Works
		----------------------------

	Now that we have created our database, and understand how the 
frequency of bills was selected, we can discuss how the generator works.

	It may help to conceptualize the system as a cardfile, with each
database element being an index card.  The cards are all sitting in the box,
and when we need a bill, we pull the card from the front of the box.  When
a bill is completed, we place it in the back of the box.  The major variable
is how long the card (bill) is out of the box, and how many bills are 
pulled and replaced in between our bill being pulled and replaced.
To keep track of the bills, the system utilizes two datafiles.  One of the
files contains the available bills (those that are not currently in use).  The
other file contains the bills that are in use on the layout currently.

	When a bill is pulled from the box, it starts some movements on the
layout (such as getting an empty, spotting it, loading it, and sending it
to the consignee).  All of this may take variable amounts of time (we may
already have a loaded car one time, but not another time).  The bill stays
"in-use" until the shipment that it represents has reached the destination.
If too many shipments from/to a single point are "ordered", then the subsequent
pileup of cars at the shipper/consignee docks will result in some bills being
delayed in their completion.  This variable time period results in automatic
sorting of the bills based on the details of your layout and car 
availabilities. This "variable sorting" will also result in "clumping" (or
grouping of orders by car type and shipper) of the database over a period of
time.  To eliminate this clumping, just run the SHUFFLE program periodically
on the database.

	When the bill generator issues a bill, it assigns it a control number
(which is actually the database index number for the "in-use" database).
This bill is removed from the front (top) of the "available" bills database,
and appended to the end of the "in-use" database.  Thus the bill is not
available for use until it is reported complete.  At the same time, it will
assign car reporting marks to the bill.  This information
is sent to a datafile on active car movements.  The data in the datafile
may be printed out with a menu option in BILLGEN. 

	When the bill is reported complete, you enter its' control number
into the bill generator, and that bill is marked complete in the "in-use"
database, and appended to the end of the "available" database, thus completing
the action in a fashion very similar to our cardfile.  Additionally, the 
record in the car movements datafile is marked as completed and removed
from the file. 

			Adding New Bills
			----------------

	As your layout grows, or existing businesses expand, you will need to
increase certain bills, or add new ones to the existing database.  This is
done in the same fashion as when you typed in the first set.  Keep in mind
the analogy of the cardfile.  The bills that you enter are being added to
the back of the file so you may want to use the shuffle function to 
redistribute the cards.