Model Railroad System
2.2.2
Overall User Manaual
|
The Freight Car Forwarder (V2) is a hybrid program, consisting of a Tcl/Tk GUI on top of a C++ class library. The GUI provides the user interface to the algorithms and data structures contained in the C++ class library. The program is based on Tim O'Connor's Freight Car Forwarder originally written in QBASIC. I first ported the program to a pure Tcl/Tk application. Then for better performance, I recoded the low-level guts (mostly heavy data indexing logic) to a C++ class library, using the STL to implement the various aggregate collections of objects, retaining Tcl/Tk for the GUI.
The name of the system file to load can be specified on the command line. See Section Opening and loading a system file. for more information.
The main GUI window, shown below,
contains a menu bar, a toolbar,
a text display area, and a button menu.
There is also a work in progress message area, a general status area, a progress meter, and several indicators.
The main GUI also has three "slide out" frames, one for showing train status when trains are run, one for viewing a car's information, and one for editing a car's information. Each slide out has a corresponding indicator.
The File->Open
... menu button and the
toolbar button pop-up a file selection dialog to select a system file to load. Once this file is successfully loaded, the name of the file, the name of the system, the current session and shift number, plus a count of
divisions, stations, industries, cars, and trains is displayed in the main GUI's text area. Also all of the buttons are made active. The name of the system file can be specified on the command line and the named system file will be loaded when the program starts.
The Load
Cars File menu button and the
toolbar button load (or reload) the cars file.
The Save
Cars
File
menu button and the
toolbar button save the cars and statistics files. This is something you need to do after you have simulated a session, by running the car assignment procedure and then run the trains in your session. This saves the state for the next time you run the Freight Car Forwarder.
The Manage
trains/printing menu button and the
toolbar button pop-up the train/printing management menu. This menu provides a set of functions relating to what trains are printed and can also print a dispatcher report and generate lists of various sorts of trains. The menu is shown below.
The Control
Yard
Lists
menu item (y key) pops up a dialog, shown below, to control whether to print 0, 1, or 2 alphabetical lists and whether to print 0, 1, or 2 train lists.
The Print
All
Trains
menu item (p key) turns on printing for all trains.
The Print
No
Trains
menu item (n key) turns off printing for all trains.
The Print
Dispatcher
Report
menu item (d key) enables the printing of a dispatcher report.
The List
Locals
This
Shift
menu item (l key) lists all locals for this shift.
The List
Manifests
This
Shift
menu item (m key) lists manifest freights for this shift.
The List
All
Trains
All
Shifts
(? key) Lists all trains.
The Manage
One
Train
menu item (1 key) pops up a dialog, shown below, to enable or disable printing of a single train, as well as setting the train's maximum length and setting which shift the train will be run. The train is selected with the "Select Train Dialog", described in Section Select A Train Dialog.
The View
Car
Information
menu button and the
toolbar button display the information about a single car. The information is displayed on the view car "slide out", shown below. The car is selected with the "Search For Cars Dialog", described in Section Search For Cars Dialog.
The Edit
Car
Information
menu button and the
toolbar button display the information about a single car and allow for editing this information. The information is displayed on the edit car "slide out", shown below. The car is selected with the "Search For Cars
Dialog", described in Section Search For Cars Dialog.
The Add
a New Car menu button and the
toolbar button provide for adding a new car. The edit car "slide out", shown above, is displayed and the information about the new car can be filled in and the car added.
The Delete
An
Existing
Car
menu button and the
toolbar button provide for deleting an existing car. The car is selected with the "Search For Cars Dialog", described in Section Search For Cars Dialog and the car's information is displayed in the view car "slide out", shown above. Actual removal can then be confirmed.
The Show
Unassigned
Cars
menu button and the
toolbar button display unassigned cars in the text window.
The Run
Car
Assignments
menu button and the
toolbar button run the car assignment procedure. This procedure attempts to give as many unassigned cars assignments, that is possible destinations. Considerations taken into account are the type of car, whether it is loaded or not, industries with available trackage to accommodate the car, and so on. The list of cars is scanned twice and the progress of the procedure is displayed in the text area.
The Run
All
Trains
in
Operating
Session
menu button and the
toolbar button run all trains in the operating session, except the end of session box moves. Each train's progress is shown in the "Train Status
Slideout", shown below.
The Run
Boxmove
Trains
menu button and the
toolbar button run all of the box move trains in the operating session.
Each train's progress is shown in the "Train Status Slideout", shown above.
The Run
Trains
One
At
A
Time
menu button and the
toolbar button run a single train, selected with the "Select Train
Dialog", described in Section Select A Train Dialog. The train's progress is shown in the "Train Status Slideout", shown above.
The Open
Printer
menu button and the
toolbar button open the printer output file, using the "Open Printer
Dialog", shown below. The status of the printer output, open or closed, is shown with the printer status indication.
The Close
Printer
menu button and the
toolbar button close the printer.The status of the printer output, open or closed, is shown with the printer status indication.
The Print
Yard
Lists
, etc. menu button and the
toolbar button print the yard and switch lists.
The Show
Cars
On
Screen
menu button and the
toolbar button pops up a menu, shown below, of classes of cars to show.
The Reports
Menu
menu button and the
toolbar button pops up a menu, shown below, of possible reports.
The Reset
Industry
Statistics
menu button and the
toolbar button resets the industry statistics.
The Quit
– Exit
NOW
menu button and the
toolbar button exit the program. A confirmation dialog is popped up.
The Select a Train Dialog is used to select a train (to manage, run, or print). The Filter
button uses the Train Name Pattern to match against train names to select a subset of trains to select from and can contain these special sequences:
*
Matches any sequence of zero or more characters in the train name.
? Matches any single character in the train name.
[chars] Matches any character in the set given by chars.x-y
appears in chars, then any character between x
and y
, inclusive, will match. Characters are matched in a case insensitive way.\x
matches the single character x
. This provides a way of avoiding the special interpretation of the characters *
?[]\ in the pattern.The Search For Cars Dialog is used to select a car (to view, edit, or delete). The Filter
button selects a subset of cars based on the trailing car number digits.
The Freight Car Forwarder uses a collection of eight data files:
System
File
This is the master file. It contains the (relative) paths to the remaining seven files, along with the name of the railroad system, its divisions, and its stations.Industry
File
This file holds the description of the industries, both on-line, which are actually modeled on the layout and off-line, which are imaginary industries not actually on the layout, but might be modeled as implied by staging yards or by interchange with other layouts or imaginary off-line railroads.Trains
File
This file holds the description of the trains used to actually move the cars about the layout.Orders
File
This file contains standing train orders and is only used to add additional information to the printouts given to train operators.Owners
File
This file contains a mapping between owner initials and owner names. Used with various generated reports.Car
Types
File
This file contains a mapping between car type codes and full names and descriptions of car types.Cars
File
This is the file containing information about all of the rolling stock on or off the layout.Statistics
File
This is the statistics file. It is generated by the program and contains statistical information about car and industry utilization.Some general notes:
A comment it indicated by an apostrophe. All characters from the apostrophe to the end of the line are discarded when read. The files generally contain lines of comma separated fields, a format designed for BASIC read statements–the original program that this program is based on was written in a version of BASIC and uses the same file format.
The first line of the system file is the name of the railroad system. This line is used in various banners and report headings.
The second line should be a blank line.
Then come the names of the remaining seven data files, one per line, in this order: Industry
File
, Trains
File
, Orders
File
, Owners
File
, Car
Types
File
, Cars
File
, and finally Statistics
File
.
After the file names comes the division list. This starts with a count of the maximum number of divisions:
where Number is a positive non zero integer.
This is followed by division specifications, which is a list of 5 values separated by commas:
Where Number is the index of the division (between 1 and the max number of divisions, inclusive), Symbol is an alphanumeric character (a-z, 0-9, A-Z), Home is the number of the home yard for this division (must be a yard specified in the Industry
File
), area is an Area symbol, and Name is the name of the division.
A line containing a -1 terminates the list of divisions.
Then comes the stations (cities), starting with a line defining the maximum number of stations:
where Number is a positive non zero integer.
This is followed by station specifications, which is a list of 4 values separated by commas:
Where Number is the index of the station (between 1 and the max number of stations, inclusive), Name is the name of the city, Division is the division index, and Comment is commentary about the station. City/Station number one is used for the workbench.
A line containing a -1 terminates the list of stations.
The industry file contains industries and yards. The file starts with a line specifying the maximum number of industries:
where Number is a positive non zero integer.
Followed by a line for each industry or yard. Industry number 0 is used for the repair yard, which is for cars not in service. Each industry's line contains these fields:
Where:
A
, P
, or D
. The industry listing is terminated by a line containing a -1.
The trains file contains the trains used to move the cars. The file starts with a line specifying the maximum number of trains:
where Number is a positive non zero integer.
Followed by a record for each train (a newline is acceptable alternative to a comma):
Where Number is the train number, Type is M for manifest; B for boxmove; W for wayfreight; or P for passenger, Shift is 1; 2; or 3, Done is Y for yes or N for no, Name is the train name, Maxcars is the maximum number of cars, Divisions is a set of division symbols or a wildcard (*
),Stops is a space separated list of stations (Boxmove and Wayfrieghts) or industries (Manifests), filler is an unused slot (use 0), Onduty is the time on duty (the train's departure time) in the format HHMM, Print is P for print or N for noprint, Maxclear is the maximum clearance number, Maxweight is the maximum weight number, Types is a set of car types this train can carry, Maxlen is the maximum train length in feet, and Description is a textual description of the train.
The train listing is terminated by a line containing a -1.
This file contains lines with pairs:
where Name is the name of a train and Order is a quoted string containing the order.
This file starts with a count of owners and then lines with with triples:
where Initials are the three letter initials of an owner, Name is the full name of the owner, and Comment is some descriptive text.
This is a file with exactly 91 records. Each record contains:
where Car Type Code is one of 91 printable characters, Car Type Group is a single character, Description is a 16 character brief description, pad is 0, and Comment is some descriptive text.
After the car types is the Car type groupings, which map groups of car types into groups using the second single character, with lines containing these fields:
where Car Type Group is a single character, Description is a 16 character brief description, and Comment is some descriptive text.
The cars file starts with three numbers, one per line:
The first number is the total number of shifts, the second is the current shift number (1, 2, or 3), and the third number is the maximum number of cars in the file.
The remainder of the file is car records. This file must be kept in alphabetical order! Each record contains:
Where Type is from car types file, Marks is the railroad reporting marks (9 characters max), Number is the car number (8 characters max), Home is car home division (from system file), CarLen is extreme car length, ClearPlate is the clearance plate (from plate file), CarWeight is car weight class (from weight file), EmptyWt is light weight in tons, LoadLimit is load limit in tons, Loaded is L for loaded or E for empty, Mirror? is ok to mirror Y for yes or N for no, Fixed? is fixed route Y for yes or N for no, Owner is car owner's 3 character initials (from owners file), Done is car is done moving for this session Y for yes or N for no, Last is last train to handle the car from trains file,Moves is actual movements this session,Loc is car's present location from industry file, Dest car's destination from industry file, NTrips is number of car trips, and NAssigns is number of car assignments.
The statistics is a file generated as an output and should not be hand edited. This file has two formats, V1 and V2. V1 is the original format used by the original BASIC program. V2 is an improved version that avoids getting the fields jammed together due to numerical overflow (result numbers too large for the field sizes).
The first line of either format contains the statistics period number. If in the new format (V2), this number is followed by a comma.
The rest of file file contains lines of four numbers, either space separated (V1) or comma separated (V2): industry index, car count, car length, and statistics length.
There are some additional data files, which are not actually loaded into the system. These are the plate, weight, and hazard files. These are just informational files that are used to map clearance plate, weight class, and hazard levels of cars.