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.
Command Line Usage
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.
Layout of the Main GUI
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.
Opening and loading a system file.
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.
Loading and reloading the cars file.
The Load Cars File menu button and the
toolbar button load (or reload) the cars file.
Saving 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.
Managing trains and printing
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.
Controlling Yard Lists
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.
Enabling printing for all trains
The Print All Trains menu item (p key) turns on printing for all trains.
Disabling printing for all trains
The Print No Trains menu item (n key) turns off printing for all trains.
Printing a dispatcher report
The Print Dispatcher Report menu item (d key) enables the printing of a dispatcher report.
Listing local trains for this shift
The List Locals This Shift menu item (l key) lists all locals for this shift.
Listing manifests for this shift
The List Manifests This Shift menu item (m key) lists manifest freights for this shift.
Listing all trains for all shifts
The List All Trains All Shifts (? key) Lists all trains.
Managing one train
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.
Viewing a car's information
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.
Editing a car's information
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.
Adding a new car
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.
Deleting an existing car
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.
Showing cars without assignments
The Show Unassigned Cars menu button and the
toolbar button display unassigned cars in the text window.
Running the car assignment procedure
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.
Running every train in the operating session
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.
Running the box move trains
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.
Running a single train
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.
Opening a Printer
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.
Closing the printer
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.
Printing yard and switch lists
The Print Yard Lists, etc. menu button and the
toolbar button print the yard and switch lists.
Showing cars on the screen
The Show Cars On Screen menu button and the
toolbar button pops up a menu, shown below, of classes of cars to show.
Printing Reports
The Reports Menu menu button and the
toolbar button pops up a menu, shown below, of possible reports.
Resetting Industry Statistics
The Reset Industry Statistics menu button and the
toolbar button resets the industry statistics.
Quiting the application
The Quit – Exit NOW menu button and the
toolbar button exit the program. A confirmation dialog is popped up.
General Dialogs
Control Yard Lists Dialog
Enter Owner Initials Dialog
Select A Train Dialog
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.- If a sequence of the form
x-yappears in chars, then any character betweenxandy, inclusive, will match. Characters are matched in a case insensitive way. \xmatches the single characterx. This provides a way of avoiding the special interpretation of the characters*?[]\ in the pattern.
Manage One Train Dialog
Open Printer Dialog
Search For Cars Dialog
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.
Select A Division Dialog
Select An Industry Dialog
Select A Station Dialog
Select Car Type
Data files
The Freight Car Forwarder uses a collection of eight data files:
SystemFileThis 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.IndustryFileThis 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.TrainsFileThis file holds the description of the trains used to actually move the cars about the layout.OrdersFileThis file contains standing train orders and is only used to add additional information to the printouts given to train operators.OwnersFileThis file contains a mapping between owner initials and owner names. Used with various generated reports.CarTypesFileThis file contains a mapping between car type codes and full names and descriptions of car types.CarsFileThis is the file containing information about all of the rolling stock on or off the layout.StatisticsFileThis is the statistics file. It is generated by the program and contains statistical information about car and industry utilization.
Data File Formats
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.
System File
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.
Industry File
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:
- ID
- Numeric identifier.
- T
- Types are Y for yard or I for industry or O for offline.
- STA
- Station Identifier.
- NAME
- User friendly place name.
- TLEN
- Actual or virtual track length.
- ALEN
- Assignable length.
- P
- Priority for car assignments. If YARD or STAGE, P is
, the number of yard lists to print of type A,P, orD. - R
- Reloads cars Y for yes or N for no.
- H
- Hazard class for outbound cargo.
- MIR
- Mirror industry or 0 if none.
- C
- Maximum clearance plate.
- W
- Maximum weight class.
- DCL
- Destination Control List of divisions. If YARD or STAGE, DCL can contain:
- A
- Alphabetical listing of cars in yard is permitted.
- P
- Pickup listing of cars in yard is permitted.
- D
- Dropoff listing of cars in yard is permitted.
- MAX
- Maximum allowed car length.
- LD
- Loaded car types accepted.
- EM
- Empty car types accepted.
The industry listing is terminated by a line containing a -1.
Trains File
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.
Orders File
This file contains lines with pairs:
where Name is the name of a train and Order is a quoted string containing the order.
Owners File
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.
Car Types File
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.
Cars File
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.
Statistics File
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.
Other data files
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.
