[Jmri-commits] help/en/package/jmri/jmrit/dispatcher AllocateExtra.shtml, NONE, 1.1 AllocateExtraWi

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Update of /cvsroot/jmri/help/en/package/jmri/jmrit/dispatcher
In directory fdv4jf1.ch3.sourceforge.com:/tmp/cvs-serv4929

Added Files:
	AllocateExtra.shtml AllocateExtraWindow.jpg 
	AllocatedSections.shtml AllocatedSectionsWindow.jpg 
	Dispatcher.shtml DispatcherWindow.jpg NewTrain.shtml 
	NewTrainAltWindow.jpg NewTrainWindow.jpg Options.shtml 
	OptionsWindow.jpg 
Log Message:
Add Dispatcher documentation

--- NEW FILE: AllocateExtraWindow.jpg ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: OptionsWindow.jpg ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: Options.shtml ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<!-- $Id: Options.shtml,v 1.1 2008/10/30 15:25:33 djduchamp Exp $ -->
<html lang="en">
<head>
 <TITLE>
      JMRI: Options Help
 </TITLE>
    <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
    <META content="Dave Duchamp" name=Author>
    <META name="keywords" content="JMRI help Dispatcher Options">

<!-- Style -->
  <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
  <link rel="stylesheet" type="text/css" href="/css/default.css" media="screen">
  <link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
  <link rel="icon" href="/images/jmri.ico" type="image/png">
  <link rel="home" title="Home" href="/">
<!-- /Style -->
</head>

<body>
<!--#include virtual="/Header" -->

<H1>Dispatcher Options
</H1>
<H2>Introduction
</H2
The Options Window provides for tailoring 
<a href="Dispatcher.shtml">Dispatcher</a> options according 
to user needs and preferences. The Options Menu provides access to Dispatcher 
options and provides for saving Dispatcher options on disk for later use. Both 
are described below in detail. Available Dispatcher options are described fully 
in the following section.

<H2>Using the Options Window
</H2
<p>Selecting <b>Options Window...</b> in the <b>Options</b> menu of the Dispatcher 
window brings up the window shown below.</p>
<img src="OptionsWindow.jpg" height="312" width="519"/>

<p>This window shows options currently selected for Dispatcher. To change 
Dispatcher options, change to the desired option configuration, and 
click the <b>Apply</b> button. All options are set to the selections in the 
Options window, and the Options window disappears. To dismiss this window without 
changing any options, click the <b>Cancel</b> button. Each option is explained 
below:</p>
<ul>
<li><p>Check <b>Use connectivity from Layout Editor panel:</b> and select a 
Layout Editor panel (if there's more than one panel), if you have a Layout Editor 
panel that fully describes your layout, including blocks and turnouts, and would 
like Dispatcher to make use of this connectivity. Uncheck this item if no 
Layout Editor panel with full connectivity is available.</p>
</li>
<li><p>Select one of the three options for Dispatcher to select trains from 
when creating Active Trains. The three possibilities are:</p></li>
	<ul>
	<li><b>Trains from Roster</b> - Dispatcher will list all trains in the JMRI 
	Roster that are not currently in Active Trains.</li>
	<li><b>Trains from Trains</b> - Dispatcher will list all trains available 
	from Operations that are not in Active Trains.</li>
	<li><b>Trains from User Entry</b> - Dispatcher will replace the train 
	selection box in the 
	<b><a href="NewTrain.shtml">Activate New Train</a></b> window with two 
	entry fields allowing the user to enter a train name and a dcc Address.
	</li></ul>
<li><p>Check <b>Layout has block detection hardware</b> if block occupancy 
detection is available from the layout. Uncheck if the layout does not have block 
occupancy detection, or if Dispatcher should not make use of block occupancy 
detection.</p>
</li>
<li><p>Check <b>Automatically allocate Sections to Active Trains</b> to activate 
automated dispatching. Uncheck to deactivate automated dispatching features. 
This item is equivalent to the <b>Auto Allocate</b> item in Dispatcher's 
<b>Options</b> menu.
</li>
<li><p>Check <b>Automatically set turnouts when a Section is allocated</b> to 
activate automatic setting of turnouts. Uncheck to deactivate automatic 
setting of turnouts. This item is equivalent to <b>Auto Set Turnouts</b> in 
Dispatcher's <b>Options</b> menu.
</li>
<li><p>Check <b>Use short Active Train names</b> to use the train name as the 
Active Train name in tables and selection boxes where Active Trains are 
referenced. Uncheck to use the full Active Train name in those locations.
</li>
<li><p>Check <b>Place train name in starting Block</b> to request that 
Dispatcher set the "value" of the starting Block to the train name when 
creating a new Active Train. Uncheck to suppress setting the starting Block 
value to the train name. This feature is designed to facilitate Train 
Tracking in Layout Editor panels.</p>
</li>
</ul>
<p><b>Note: Automated dispatching and automatic setting of turnouts are not 
implemented in the initial version of Dispatcher.</b> These functions will 
be available in a later version of Dispatcher.</p>
<H2>Using the Options Menu
</H2
<p>The <b>Options</b> menu is used to access, edit, and save Dispatcher options. 
Items in this menu and their use are explained below:
<ul>
<li><p><b>Auto Allocate</b> - This check box is used to turn automated 
dispatching functions on (checked) or off (unchecked). This item is equivalent 
to an item in the Options Window. Automated dispatching may be turned on or off 
at any time. The item is repeated here for convenience of the dispatcher.</p>
</li>
<li><p><b>Auto Set Turnouts</b> - This check box is used to turn on (checked) 
or off (unchecked) automatic setting of turnouts when Sections are allocated. 
This item is equivalent to an item in the Options Window. Automatic setting of 
turnouts may be turned on or off at any time. The item is repeated here for 
convenience of the dispatcher.</p>
</li>
<li><p><b>Options Window...</b> - Selecting this item brings up the Options 
Window described above.</p>
</li>
<li><p><b>Save Options...</b> - Selecting this item saves Dispatcher options 
currently in effect into a small XML file (<i>dispatcheroptions.xml</i>) in the 
user's preferences directory. This is the same location where JMRI preference 
files are saved. When Dispatcher is started, if a file named 
"<i>dispatcheroptions.xml</i>" is found in the user's preference directory, 
that file is read, and Dispatcher options are set accordingly.  If the 
file is not present when Dispatcher is started, default options are used. 
<b>Note: Dispatcher options are not saved automatically.</b> Saving Dispatcher 
options is optional. Selecting this menu item is the only way to save 
Dispatcher options.<p>
</li>

<!--#include virtual="/Footer" -->
</body>
</html>

--- NEW FILE: NewTrainWindow.jpg ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: NewTrain.shtml ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<!-- $Id: NewTrain.shtml,v 1.1 2008/10/30 15:25:33 djduchamp Exp $ -->
<html lang="en">
<head>
 <TITLE>
      JMRI: New Train Help
 </TITLE>
    <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
    <META content="Dave Duchamp" name=Author>
    <META name="keywords" content="JMRI help Dispatcher New Train">

<!-- Style -->
  <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
  <link rel="stylesheet" type="text/css" href="/css/default.css" media="screen">
  <link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
  <link rel="icon" href="/images/jmri.ico" type="image/png">
  <link rel="home" title="Home" href="/">
<!-- /Style -->
</head>

<body>
<!--#include virtual="/Header" -->

<H1>Activate New Train Window
</H1>
<H2>Introduction
</H2
<p>The <b>Activate New Train</b> window supports the creation of a new <b>Active 
Train</b>. To create an Active Train, the dispatcher uses this window to assign
a <b><a href="../beantable/TransitTable.shtml">Transit</a></b>, assign a train, 
and specify a starting Block (train location at start) and an end Block (train 
location when transit of the layout is complete). Options for the new <b>Active 
Train</b> are also set using this window. It is likely that more Active Train 
options will be added in the future.</p>
<p>Transits are always selected from Transits defined in the Transit Table. 
Trains may come from any one of three sources:</p>
	<ul>
	<li><b>Trains from Roster</b> - Dispatcher will list all trains in the JMRI 
	Roster that are not currently in Active Trains.</li>
	<li><b>Trains from Trains</b> - Dispatcher will list all trains available 
	from Operations that are not in Active Trains.</li>
	<li><b>Trains from User Entry</b> - Dispatcher will replace the train 
	selection box in the Activate New Train window with two entry fields 
	allowing the user to enter a train name and a dcc Address.
	</li></ul>
<p>Dispatcher's train source is set by selecting one of the above in the 
<b><a href="Options.shtml">Options</a></b> window accessed from Dispatcher's 
<b>Options</b> menu.</p>
<p>Active Trains must start from a Block in the selected Transit, or from a 
Block connected to a Block in the selected Transit. Active Trains must stop 
in a Block within the selected Transit. Transits have a direction, so for 
a starting Block outside the Transit to be a valid starting Block, entry to 
the Transit from the starting Block must result in travel in the Transit's 
defined direction. This window only allows selection of valid starting and 
stopping Blocks. If an expected Block is not in the starting Block selection 
box, it may be because of this requirement.</p>

<H2>Using the Activate New Train Window
</H2
To create a new Active Train, use the following procedure:
<ol>
<li>Click the New Train... button in the 
<a href="Dispatcher.shtml">Dispatcher</a> window to bring up 
the window shown below.
<img src="NewTrainWindow.jpg" height="258" width="375"/>
</li>
<li>Select a Transit from the Transit selection box. The selected 
Transit specifies the route the Active Train will follow while 
running on the layout. Transits are displayed and new Transits are created 
using the <a href="../beantable/TransitTable.shtml">Transit Table</a> 
accessed from the Tables submenu of the JMRI Tools menu. This 
Transit selection box will allow selection of any Transit in the Transit Table 
that is not in use by an Active Train.
</li>
<li>If the window shown above is displayed, select a train from the Train 
selection box. This window is displayed if the Trains from Roster or 
the Trains from Trains options are selected as Dispatcher's train 
source.
- OR -
</li>
<li>If the window shown below is displayed, 
<img src="NewTrainAltWindow.jpg" height="277" width="368"/>
enter a train name in the Train Name: field, and enter a numeric 
address in the DCC Address: field. Any short name that identifies 
the train may be used provided the name is not being used by another Active 
Train. Dcc addresses must be a number in the range 1 - 9999. Note: If the 
train will not be run automatically, the dcc address need not be accurate. This 
window is displayed if Trains from User Entry is selected as Dispatcher's 
train source.
</li>
<li>If the starting location of the Active Train is a Block within the 
selected Transit, check the Train in selected Transit box. If the 
starting location of the Active Train is outside the selected Transit, (in 
a Block connected to a Block within the selected Transit) uncheck this box. 
Checking and unchecking this box results in different selections in the 
Starting Location of Train: select box.
</li>
<li>Select a Starting Location of Train: from the select box. This 
select box lists all Blocks consistent with the check box above and the 
selected Transit. To identify each Block uniquely, the Block identifier 
consists of the Block system name, followed by the Block user name (in 
parentheses) followed by the sequence number of a Section in the 
Transit definition. If the train is located in the Transit, this 
sequence number identifies the Section where the train is located. If the 
train is located in a connected Block, the sequence number identifies the 
Section that will be entered when the train enters the Transit. If the train 
spans two blocks, select the Block where the engine is located.
</li>
<li>Select a Destination Location of Train: from the select box. This 
select box lists all Blocks consistent with the selected Transit that can be 
reached from the selected starting location by travel in the direction of 
the Transit. The Block identifier in the select box consists of the Block system 
name, followed by the Block user name (in parentheses). If a Section is in the 
Transit more than once, the sequence number of the destination Section is 
appended to the Block identifier to identify the destination 
Block uniquely.
</li>
<li>Enter a Priority for the Active Train relative to other Active 
Trains. Larger numbers are higher priority. The priority is used in by 
automated dispatching functions to arbitrate between Active Trains if multiple 
Active Trains are requesting the same resources.
</li>
<li>Check Run Train Automatically to request that the Active Train 
be run automatically by the computer.
</li>
<li>Click Add New Train after all the above have been set to create 
and activate the new Active Train. The new Active Train will immediately 
appear in the Dispatcher window, and this window will be dismissed.
- OR -
</li>
</li>
<li>Click Cancel to exit this window without creating a new Active 
Train.
</li>
</ol>
Note: Automated dispatching and automatic running of trains are not 
implemented in the initial version of Dispatcher. These functions are 
expected to be introduced in later versions of JMRI.

<!--#include virtual="/Footer" -->
</body>
</html>

--- NEW FILE: DispatcherWindow.jpg ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: AllocatedSectionsWindow.jpg ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: Dispatcher.shtml ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<!-- $Id: Dispatcher.shtml,v 1.1 2008/10/30 15:25:33 djduchamp Exp $ -->
<html lang="en">
<head>
 <TITLE>
      JMRI: Dispatcher Help
 </TITLE>
    <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
    <META content="Dave Duchamp" name=Author>
    <META name="keywords" content="JMRI help Dispatcher">

<!-- Style -->
  <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
  <link rel="stylesheet" type="text/css" href="/css/default.css" media="screen">
  <link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
  <link rel="icon" href="/images/jmri.ico" type="image/png">
  <link rel="home" title="Home" href="/">
<!-- /Style -->
</head>

<body>
<!--#include virtual="/Header" -->

<H1>Dispatcher
</H1>
<dt class="left"><a name="contents"><h3>Contents</h3></a></dt>
<p>This document describes <b>Dispatcher</b>, and how to use Dispatcher to 
help with dispatching and running trains on layouts with PanelPro panels. The 
document is divided into sections; click below to jump to the named section. 
Underlined items are links to sections of this document or to other help files.</p>
<ul>
	<li><a href="#intro">Introduction to Dispatcher</a></li>
	<li><a href="#glossary">Glossary of Terms</a></li>
	<li><a href="#transits">Using Transits and Sections in Dispatching Active 
	Trains</a></li>
	<li><a href="#window">The Dispatcher Window</a></li>
	<li><a href="#atrains">The Active Trains Table</a></li>
	<li><a href="#arequests">The Allocation Requests Table</a></li>
</ul>

<dt class="left"><a name="intro"><H2>Introduction to Dispatcher
</H2></a></dt>
Dispatcher provides functions and organizes information relating to 
dispatching trains on a model railroad layout. It's main function is allocation 
of sections of track to various trains running around the layout. Dispatcher is 
not designed to completely replace a human dispatcher during a session of 
running trains, but it should make the dispatching job easier and more fun. 
Dispatcher is envisioned to work alongside a panel, constructed in either 
Layout Editor or Panel Editor, which provides visual feedback of layout status. 
There was no attempt to make Dispatcher look or feel prototypical. It 
was simply designed to be functional for dispatching a model railroad layout.
Dispatcher requires that a layout be divided into Blocks, and that 
Blocks along the mainline be organized into 
<a href="../beantable/SectionTable.shtml">Sections</a>. It also requires 
that Sections be used to define routes, called 
<a href="../beantable/TransitTable.shtml">Transits</a>, that describe 
paths that trains will follow when active on the layout. Blocks are 
portions of track whose occupancy can be monitored individually. Sections 
are groups of Blocks that are allocated as a unit by the dispatcher using 
Dispatcher functions. Blocks are usually defined to facilitate signaling 
on a layout. Dispatcher does not require that block detection hardware or signals 
be installed on the physical layout, or even that the physical layout be divided 
into blocks. Dispatcher will work if layout blocking is defined in a panel only. 
However, Dispatcher works best if hardware blocks with block detection are present. 
It works even better if hardware signals are present on the layout, and 
signal logic uses Section direction sensors.
Functionality provided by Dispatcher includes: support for train start up and 
termination, information to allow easy set up of meets at passing sidings, 
automation of some dispatcher functions, set up of automatic running of trains
(including automatic station stops for passenger trains), support for linking
signals to allocation via simple APB signaling support, and automatic setting 
of turnouts when a section of track is allocated. Many of these functions are 
included in the current version of Dispatcher; others will follow in future 
releases of JMRI.
Central to Dispatcher is the Active Train, which carries the 
information needed to run a train around the layout. Basically, an Active Train 
is created by the dispatcher by combining a Transit with a Train. 
The <a href="../beantable/TransitTable.shtml">Transit</a> provides a 
description of the route to be followed by the Train, including which 
<a href="../beantable/SectionTable.shtml">Sections</a> need to be 
allocated along the route, and any special actions that need to 
take place in specific Sections. The Train specifies what is to be run 
along the route specified by the Transit. Trains can be complete descriptions of 
all engines and cars as provided by JMRI Operations, or engines selected 
from the JMRI Roster menu, or simply a train name and dcc address entered 
by the dispatcher.
When creating an Active Train, the dispatcher also specified where the Active 
Train is currently located, and the location of the Active Train when it is 
terminated after it completes its transit of the layout. Other options, like 
train priority and a request to run the Active Train automatically may also be 
entered. More options are expected to be added in the future as more 
functionality is added to JMRI. 
All Active Trains are displayed in a table in the Dispatcher Window, 
along with status information about the Active Train. The Dispatcher Window 
also contains a table of pending Allocation Requests, and buttons that allow 
the dispatcher to easily allocate Sections, create new Active Trains, terminate 
Active Trains, and display a table of all Allocated Sections. Allocated 
Sections are released using buttons in the Allocated Sections table. The 
<a href="#window">Dispatcher Window</a> is discussed in detail below.
Note: The current version of JMRI does not have automated dispatching, 
automatic running of trains, or automatic setting of turnouts. Those optional 
features will be added in future releases.
Many of the terms in this introduction to Dispatcher may be new to users. 
Some were created specifically for use with Dispatcher. Please briefly review 
the Glossary of Terms which follows, and come back to it as needed when 
reading the remainder of this documentation.

<dt class="left"><a name="glossary"><H2>Glossary of Terms
</H2></a></dt>
Block - A portion of track whose occupancy may be individually monitored. 
Blocks are defined by subdividing the track in a layout. Blocks normally correspond 
to physical blocks on a layout, each wired for occupancy detection. However, if 
the layout track is not subdivided into blocks, dividing a Layout Editor panel 
into blocks will allow Dispatcher to be used. For Dispatcher use, blocking of 
mainline track is required. Hardware occupancy detection is optional. Dispatcher 
works best if hardware block occupancy detection is present, but it can work 
without it.
Section - A group of one or more connected Blocks that may be 
allocated to a train for travel in a given direction. Blocks are normally defined 
to facilitate signals. This often results in short Blocks, sometimes containing 
only one track switch. Sections allow Blocks to be grouped into track 
sections that are reasonable for a dispatcher to allocate. More information is 
contained in the <a href="../beantable/SectionTable.shtml">Section Table</a> 
help file, along with instructions on how to create a Section.
Transit - A group of two or more connected Sections that describes
a route around the layout for a train traveling in a given direction. Transits 
are required for Dispatcher, and at least one must be defined before Dispatcher 
can be opened. A detailed description of Transits, how they are created and 
how they are used is contained in the 
<a href="../beantable/TransitTable.shtml">Transit Table</a> help file.
Train - An engine (or consist) usually attached to a group of cars, 
that travels around the layout as an entity. For use with Dispatcher, trains 
may be selected from engines in the JMRI engine roster, may be selected from trains 
created in JMRI Operations, or train information may be entered manually by 
the dispatcher.
Active Train - A combination of a Train and a Transit, along with other 
information and options. The Train describes what is traveling, and the Transit 
describes where it is going. Details are filled in by other information and options
selected when the Active Train is created. Active Trains are central to Dispatcher. 
How Active Trains are used is described in detail <a href="#transits">below</a>. 
The <a href="#atrains">Active Trains Table</a> section below provides more 
details. Active Trains are created and terminated from the Dispatcher window.
Allocation Request - A request to allocate (assign) a Section for 
the exclusive use of an Active Train. Allocation Requests that are not 
immediately acted upon are gathered in a queue that is displayed in the Dispatcher 
window. Action on an Allocation Request can be delayed for a number of reasons, 
for example, if the requested Section is allocated to a different Active Train.
Allocated Section - A Section that is currently assigned to an 
Active Train. When a Section is allocated, if there are alternate Sections 
following the Allocated Section, the dispatcher must choose the next Section from the 
alternate Sections contained in the Transit. A window listing all Allocated Sections 
may be displayed by clicking a button in the Dispatcher window.
Alternate Section - An alternate Section connecting two 
Sections in a Transit. In user-specified areas of a Transit, alternate 
Sections may be designated. For example, to move between the "2nd" and "4th" 
Sections in a Transit, there may be multiple "3rd" Sections, any of which might 
be used to travel between the 2nd and 4th Sections. Alternate Sections provide for 
passing tracks and staging yards.

<dt class="left"><a name="transits"><H2>Using Transits and Sections in Dispatching 
Active Trains
</H2></a></dt>
When a Transit is paired with a Train to form an Active Train, 
the starting Block (Active Train location at start) and ending Block (Active Train 
location when the travel is complete) are specified. The Active Train is referred to by 
its Train name and its Transit name, each of which must be unique among Active 
Trains. A Train and a Transit may be in only one Active Train at a time. When 
an Active Train is terminated, its Transit and its Train are deactivated, 
and both may be reused in different Active Trains.
An Active Train usually starts from a Block outside of the Transit, but connected 
to a Block within the Transit. Optionally a train may start from a Block within a 
Section in the Transit. A train moves through a Transit in only one direction--
defined by the order in which Sections are included in the Transit. Trains move 
from lower sequence number Sections toward higher sequence number Sections. When 
an Active Train is created, an Allocation Request is placed for a starting 
Section. If the Section is free, the Section will be allocated to 
the Active Train. Allocation means that the Section is assigned to the Active 
Train, and the Active Train is authorized by the dispatcher to proceed to the 
end of that Section.
An Active Train may be run by an engineer using a throttle, or automatically 
by the computer. Dispatching for the Active Train consists of allocating 
Sections, one by one, to the Active Train, and holding the Active Train in a 
Section as needed when its needs conflict with the needs of other Active Trains. 
The actual allocation may be done by the dispatcher by manually clicking 
buttons in the Dispatcher Window, or the dispatcher may request Auto Allocate 
in the <a href="Options.shtml">Options</a> menu of the Dispatcher window, 
and allow the computer do some of the routine work. If a requested Section is 
currently in use, an Allocation Request is placed in the Allocation Request 
table in the Dispatcher window.
Transits provide for a special action to be performed when a train is in a 
Section. Currently two special actions are supported: Pause for a user-designated 
number of fast clock minutes, and Await a manual restart. The Pause action 
may be used for automatic station stops. The Await action is designed to support 
an engineer doing work in a specified Section, and requesting a restart when the 
work is complete. More actions may be added in the future as needed.

<dt class="left"><a name="window"><H2>The Dispatcher Window
</H2></a></dt>
The Dispatcher window is opened when Dispatcher... is selected 
in the JMRI Tools menu. It displays a table of Active Trains and 
their status, and a table of pending Allocation Requests. It provides 
buttons that allow the dispatcher to easily allocate Sections, create new Active 
Trains, terminate Active trains, and display a table of all 
<a href="AllocatedSections.shtml">Allocated Sections</a>. Allocated Sections 
are released using buttons in the Allocated Sections table. Dispatcher 
window buttons are discussed below. The 
<a href="#atrains">Active Trains</a> table and the Allocation Request 
table are discussed in the following sections.
A typical Active Trains window early in a train running session is shown below.

<img src="DispatcherWindow.jpg" height="386" width="843"/>
In the example window above, two Active Trains have been created. The top 
Active Train, ATSF4581, has been allocated a Section and is RUNNING. The second 
Active Train, SP234 is WAITING for its first allocation. An Allocation Request 
has been entered for the first Section needed by SP234. The requested Section is 
FREE and UNOCCUPIED, so it could be allocated by clicking the Allocate 
button in the lower table or the Allocate Next button in the upper table.
 The four buttons below the Active Trains table are described below:
<ul>
<li>New Train... - Click this button to bring up an Activate New 
Train window that allows the dispatcher to create an Active Train. The 
Train source used by this window is set in the 
<a href="Options.shtml">Options</a> window. More information on creating 
new Active Trains may be found in the help file for the 
<a href="Options.shtml">Activate New Train</a> window, along with a 
simple procedure to follow when creating an Active Train. Options should 
not be changed with the Activate New Train window open.
</li>
<li>Show Allocations... - Click this button to bring up a window 
containing a table that displays all Sections currently allocated to 
Active Trains. The <a href="AllocatedSections.shtml">Allocated 
Sections</a> window displays information about each Allocated Section and 
provides for release of Allocated Sections. This table is in a 
separate window, instead of being included in the Dispatcher window to allow more 
flexibility in placing windows on the computer screen.
</li>
<li>Allocate Extra... - Click this button to bring up a window that 
allows the dispatcher to allocate Sections to an Active Train that may not be 
the "next" Section in the Active Train's Transit. Any Section that is FREE and 
is connected to an Allocated Section of the Active Train may be allocated to 
the Active Train using this window. More information and a simple procedure for 
allocating extra Sections may be found in the help file of the 
<a href="Options.shtml">Allocate Extra</a> window.
</li>
<li>Terminate Train... - Click this button to terminate 
an Active Train. A small window appears to allow the selection of which 
Active Train the dispatcher wants to terminate. When an Active Train is 
terminated, all Sections allocated to it are automatically released. The Train 
and Transit are freed up to be used in other Active Trains as needed.
An Active Train is usually terminated 
when it reaches its destination Block, however, it may be terminated at any point 
during its transit of the layout. The dispatcher is responsible for deciding 
whether it is appropriate to terminate an Active Train before it reaches its 
destination.</li>
</li></ul>
Dispatcher options allow tailoring of the dispatcher function. Options are 
accessed via the Dispatcher window's Options menu. Descriptions of currently 
available options, the Options menu, the Options window are contained in 
the <a href="Options.shtml">Options</a> help file.

<dt class="left"><a name="atrains"><H2>The Active Trains Table
</H2></a></dt>
<p>
<p>Each row of <b>Active Trains</b> table corresponds to one Active Train. The 
columns are explained below.
<ul>
<li><p><b>Transit</b> - The name of the Transit of the Active Train is shown. 
The displayed name is the system name followed by the User Name in parentheses.
</p></li>
<li><p><b>Train</b> - The name of the Train of the Active Train is shown.</p>
</li>
<li><p><b>Train Status</b> - Active Train status is displayed here. An Active 
Train may have any one of the following statuses:
	<ul>
	<li><b>RUNNING</b> - Actively running on the layout, according to its mode 
	of operation.</li>
	<li><b>PAUSED</b> - Paused waiting for a user-specified number of fast clock 
	minutes.  The Active Train is expected to move to either RUNNING or WAITING 
	once the specified number of minutes has elapsed. This is intended for 
	automatic station stops.</li>
 	<li><b>WAITING</b> - Stopped waiting for a Section allocation. This is the 
 	status the Active Train is in when it is created.</li>
	<li><b>WORKING</b> - Performing work under control of a human engineer. This 
	is the status an Active Train assumes when an engineer is picking up or 
	setting out cars at industries or in a yard.</li>
 	<li><b>READY</b> - Indicates the Active Train has completed WORKING, and is 
 	<i>awaiting</i> a restart - dispatcher clearance to resume running.</li>
 	<li><b>DONE</b> -  Indicates the Active Train has reached its destination 
 	and is ready to be terminated by the dispatcher.</li> 
	</ul></p>
<p>Not all Active Trains will use all the above statuses.</p>
<p><b>Note: In the current version of Dispatcher all statuses are not 
implemented.</b> More statuses will be implemented as functionality is added 
in future JMRI versions.</p>
</li>
<li><p><b>Mode</b> - Mode of operation of the Active Train is displayed. The 
following modes are allowed:
	<ul>
	<li><b>DISPATCHED</b> - Indicates the Active Train is run by an operator  
 	using a throttle. A dispatcher will allocate Sections to the Active Train as 
 	needed, control optional signals using a CTC panel or computer logic, and 
 	arbitrate any conflicts between Active Trains. If signals are present, the 
 	operator is expected to follow signals as set by the computer or the 
 	dispatcher.</li>
 	<li><b>AUTOMATIC</b> - Indicates the Active Train will be run under automatic 
	control of the computer. Under AUTOMATIC running, the computer is expected 
	to follow signals set by the dispatcher. Automatic station stops will 
	occur, as described above. If the Active Train reaches a Section where 
	work must be done (e.g. setting out or picking up cars), the mode of 
	operation changes to MANUAL until the work is complete. Restarting from 
	MANUAL work changes the mode back to AUTOMATIC.</li>
 	<li><b>MANUAL</b> - Indicates an Active Train running in AUTOMATIC mode has 
 	reached a Special Action in its Transit that requires MANUAL operation. 
	When this happens, the status changes to WORKING, and the mode changes to 
	MANUAL. While in MANUAL mode, the Active Train is run by an operator  
	using a throttle. AUTOMATIC running is resumed when the work has 
	been completed.</li>
	</ul></p>
<p><b>Note: In this version of Dispatcher, only DISPATCHED mode is implemented.
</b> Automatic running of Active Trains will be added in a future release of 
JMRI.</p>
</li>
<li><p><b>Allocated Section</b> - Displays the name of the <b>Section</b> of the 
<b>Transit</b> that was last allocated to this Active Train.
</li>
<li><p><b>Next Section</b> - Displays the name of the <b>Section</b> of the 
<b>Transit</b> that will need to be allocated next.
</li>
<li><p><b>Allocate Next Button</b> - Click this button to request that the 
<b>Section</b> shown in the <b>Next Allocation</b> column be allocated to this 
Active Train. If the Section is FREE and not occupied it will be allocated 
immediately, and the Sections in the Allocated Section and Next Section columns 
will be updated.</p>
<p>If the Section is not FREE, an <b>Allocation Request</b> will 
be entered into the <b>Allocation Requests</b> table (see below). If the Section 
is FREE, but is OCCUPIED, the dispatcher will be queried. The dispatcher is 
responsible for deciding whether an OCCUPIED Section should be allocated. If 
the Next Section is the first Section to be allocated, and the Active Train 
is occupying that Section, Dispatcher knows that allocating the OCCUPIED 
Section is appropriate, so the dispatcher is not queried.
</li>
</ul>

<dt class="left"><a name="arequests"><H2>The Allocation Requests Table
</H2></a></dt>
<p>This table, headed <b>Requested Allocations waiting for Dispatch</b>, 
displays pending <b>Allocation Requests</b>. Each row corresponds to one 
<b>Allocation Request</b>. Columns are explained below.
<ul>
<li><p><b>Active Train</b> - Shows the <b>Active Train</b> requesting the Section. 
Active Train names are displayed in either short form (shown above) or long form 
depending on the option selected in the Dispatcher's 
<b><a href="Options.shtml">Options</a></b> window.</p>
</li>
<li><p><b>Priority</b> - Shows the priority of the <b>Active Train</b> requesting 
the Section. Larger numbers are higher priority. If two Active Trains are 
requesting the same Section, the higher priority Active Train would normally 
take precedence.
</li>
<li><p><b>Requested Section</b> - Shows the name of the requested <b>Section</b>.
</li>
<li><p><b>Section Status</b> - Shows the allocation status of the requested 
<b>Section</b>. The Section will be either:
	<ul>
	<li><b>FREE</b> - Available for allocation.
	</li>
	<li><b>ALLOCATED</b> - Allocated to a different Active Train.	
	</ul>
</li>
<li><p><b>Occupancy</b> - Shows the occupancy of the requested <b>Section</b>. 
Three entries are possible:
	<ul>
	<li><b>UNOCCUPIED</b> - Nothing is detected in any Block of the Section. 
	(The occupancy sensors of all Blocks in the Section are INACTIVE.)
	</li>
	<li><b>OCCUPIED</b> - Something is detected in one of the Blocks of the 
	Section. (The occupancy sensor of at least one Block in the Section is 
	ACTIVE.)
	</li>
	<li><b>UNKNOWN</b> - The occupancy status of at least one of the Blocks of 
	the Section is not known. This indicates that the occupancy sensor of at least 
	one Block in the Section is neither ACTIVE nor INACTIVE. <b>- OR-</b> The 
	Dispatcher option <b>"Layout has block detection hardware"</b> is not checked - 
	see <b><a href="Options.shtml">Dispatcher Options</a></b>. 
	</ul>
</li>
<li><p><b>Allocate Button</b> - Click this button to request immediate allocation 
of the Section to the requesting Active Train. If the Section is FREE, and if the 
Section occupancy is either UNOCCUPIED or UNKNOWN, the Section will be allocated 
to the requesting Active Train. If the Section is FREE, but the Section  
is OCCUPIED, the dispatcher is prompted to either override the occupancy or 
wait.</p>
<p>If the Section is ALLOCATED to another Active Train, the button click 
will be ignored. A Section may be allocated to only one Active Train at a time. 
If an ALLOCATED Section needs to be reallocated to a different Active Train, it 
must first be <b>released</b>. (See the 
<b><a href="AllocatedSections.shtml">Allocated Sections</a></b> window help file 
for instruction on <i>releasing</i> Allocated Sections.)</p>
</li>
<li><p><b>Cancel Button</b> - Click this button to delete the Allocation 
Request without allocating the requested Section.
</li>
</ul>

<!--#include virtual="/Footer" -->
</body>
</html>

--- NEW FILE: AllocateExtra.shtml ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<!-- $Id: AllocateExtra.shtml,v 1.1 2008/10/30 15:25:33 djduchamp Exp $ -->
<html lang="en">
<head>
 <TITLE>
      JMRI: Allocate Extra Window Help
 </TITLE>
    <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
    <META content="Dave Duchamp" name=Author>
    <META name="keywords" content="JMRI help Dispatcher New Train">

<!-- Style -->
  <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
  <link rel="stylesheet" type="text/css" href="/css/default.css" media="screen">
  <link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
  <link rel="icon" href="/images/jmri.ico" type="image/png">
  <link rel="home" title="Home" href="/">
<!-- /Style -->
</head>

<body>
<!--#include virtual="/Header" -->

<H1>Allocate Extra Window
</H1>
<H2>Introduction
</H2
The Allocate Extra Window allows "extra Sections" to be allocated to 
any Active Train. "Extra Sections" are Sections that are not in the sequence 
of Sections defined in the Transit being followed by the Active Train. The need 
to allocate "extra Sections" can arise if the engineer of an Active Train needs 
to do more than simply run around the layout. For example, extra Sections could 
be needed for setting out or picking up cars, especially if a run around is 
needed.

Extra Sections are allocated manually via the Dispatcher panel, using this 
window to select the Active Train and the Section to be allocated. Once allocated, 
extra Sections will show in the <a href="AllocatedSections.shtml">Allocated 
Sections</a> window. The Release button in the Allocated 
Sections window should be used to release the extra Sections when they are no 
longer required.

<H2>Using the Allocate Extra Window
</H2
To allocate and extra Section to an Active Train, use the following 
procedure:
<ol>
<li>Click the Allocate Extra... button in the 
<a href="Dispatcher.shtml">Dispatcher</a> window. This brings up 
the window shown below.
<img src="AllocateExtraWindow.jpg" height="146" width="267"/>
</li>
<li>Select an Active Train in the Active Train: select box. When an 
Active Train is selected, the Section to Allocate: select box will change 
to display Sections that are appropriate to that Active Train. Active Train 
names are displayed in either short form (shown above) or long form depending 
on the option selected in the Dispatcher's <a href="Options.shtml">Options</a>
window.
</li>
<li>Select a Section to allocate in the Section to Allocate: select box.
To be listed in this select box, a Section must be FREE (not allocated to any 
Active Train), and must be connected to a Section that is currently allocated 
to the Active Train selected in the Active Train: select box.
<li>Click the Allocate button to allocate the selected Section to the 
selected Active Train. The Section is allocated immediately, and this window
disappears.
</li>
<li>Or click the Cancel button to exit without allocating an extra
Section.
</li>
</ol>
Note: If this window accidently should be left open, allocating a Section in 
another manner will automatically cancel the operation in this window, and this 
window will disappear.

<!--#include virtual="/Footer" -->
</body>
</html>

--- NEW FILE: AllocatedSections.shtml ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<!-- $Id: AllocatedSections.shtml,v 1.1 2008/10/30 15:25:33 djduchamp Exp $ -->
<html lang="en">
<head>
 <TITLE>
      JMRI: Allocated Sections Help
 </TITLE>
    <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
    <META content="Dave Duchamp" name=Author>
    <META name="keywords" content="JMRI help Dispatcher New Train">

<!-- Style -->
  <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
  <link rel="stylesheet" type="text/css" href="/css/default.css" media="screen">
  <link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
  <link rel="icon" href="/images/jmri.ico" type="image/png">
  <link rel="home" title="Home" href="/">
<!-- /Style -->
</head>

<body>
<!--#include virtual="/Header" -->

<H1>Allocated Sections Window
</H1>
<H2>Introduction
</H2
The Allocated Sections window displays a table of all Sections 
currently allocated to Active Trains. This window serves two purposes. It 
shows which Allocated Sections are allocated to which Active Trains, and it 
allows the dispatcher to release an Allocated Section for use by a 
different Active Train. This table could have been displayed in the Dispatcher 
window, but instead is displayed separately to allow more flexibility in arranging 
windows on the computer screen. This window may be minimized or dismissed using 
the standard items in its title bar. It is listed in the Window menu, which may 
be used to bring it to the front if it becomes buried.
The Allocated Sections window is requested by clicking the 
Show Allocations... button in the 
<a href="Dispatcher.shtml">Dispatcher</a> window. Clicking this 
button brings up the small window shown below.
<img src="AllocatedSectionsWindow.jpg" height="171" width="543"/>
 The table has four columns as follows:
<li>Active Train - Shows the Active Train to which the Section is assigned. 
Active Train names are displayed in either short form (shown above) or long form 
depending on the option selected in the Dispatcher's 
<a href="Options.shtml">Options</a> window.
</li>
<li>Allocated Section - Shows the name of the Section allocated to 
the Active Train on the left.
</li>
<li>Occupancy - Displays whether the Allocated Section is OCCUPIED 
by a train, or UNOCCUPIED. The Occupancy column is updated whenever 
the occupancy of the Allocated Section changes. If the user has not specified 
that the layout has occupancy detection in the Dispatcher's 
<a href="Options.shtml">Options</a> window, Occupancy for all Sections 
will be displayed as UNKNOWN.
</li>
<li>The last column displays a Release button for each Allocated Section.
If the Release button is clicked, that Section is immediately released. Section status becomes FREE, and 
the Section is available for allocation to an Active Train.
 Often a Section should not be released if it is still OCCUPIED. When 
an Active Train is terminated, all of its allocated Sections are automatically 
released, regardless of occupancy. The automated dispatcher will not release an 
OCCUPIED Section automatically. Caution: With manual dispatching, the 
dispatcher is responsible for determining whether it is appropriate to release 
an OCCUPIED Section.
</li>

<!--#include virtual="/Footer" -->
</body>
</html>

--- NEW FILE: NewTrainAltWindow.jpg ---
(This appears to be a binary file; contents omitted.)

[Jmri-commits] help/en/package/jmri/jmrit/dispatcher AllocateExtra.shtml, NONE, 1.1 AllocateExtraWi

Java applications to control a model railroad layout.