Dispatcher2 Guide

Read the dispatcher overview for a brief description of the dispatcher its interactions with other processes.

Status of the ESI dispatchers can be seen on the ESI Console window, which is started automatically upon logging into an ESI observer account or via the "esicon" command. The console shows the presence of a healthy traffic connection to each dispatcher. Traffic is the interface process between the ESI dashboard and the dispatcher processes. The "esi status" command described below also reports the status of any dispatchers started locally via the "esi start" command.

Normally the ESI dispatcher processes are already up and running, since they are started at boot time on koki, the ESI supervisor computer. If a dispatcher needs to be restarted, two basic methods can be used from the command line. Neither of these options are available to observers. The dispatchers must be started by either an observing assistant, instrument specialist, or other qualified personnel from the ESI instrument account on koki, the ESI supervisor computer.

The primary method of starting the ESI dispatchers uses the "esi" command script. The "esi" command has four basic action options: "start", "restart", "stop" and "status". Each does exactly what is says: "start" starts processes that aren't running, "restart" stops and restarts processes, "stop" stops processes, and "status" tells you whether or not a process is running (and other related info). The "esi" command requires a process or subsystem name in addition to the action parameter. Just execute the command with no parameters for a usage statement outlining the processes that are managed via the "esi" command on any ESI computer.

The individual dispatcher process names known by the "esi" command are "dispatcher2.0" and "dispatcher2.1". The last digit of the name is the same as the id number of both the dispatcher and the Galil motor controller interfaced via the dispatcher. The "esi" command provides the remaining parameters required to start up or shutdown the dispatcher processes in a consistent manner every time. It will not start up multiple copies of the same process.

The other method of starting a dispatcher process from the command line is to use the "dispatcher2" executable directly. This method should only be used for special tests or when direct access to the dispatcher2 command line parameters is required. However, this is discouraged since a dispatcher started in this fashion is not reported as running via the "esi status" command and may not be reported as running via the ESI Console panel (it could connect to a different traffic process than expected by the console panel, see the following warning and parameter notes!). This can lead to incorrect diagnosis of problems and confusion regarding the status of the dispatcher processes. Confusion regarding the status of the dispatcher process can lead to the starting of multiple copies of the same dispatcher process. Running multiple copies of the same dispatcher can result in one of two very annoying and disabling problems that are described in the warning below.

---

WARNING

Only one dispatcher can be connected to a controller at a time. Since the dispatchers communicate to the controllers via serial connections, the file system prevents newly started dispatchers from successfully opening a connection to a controller already connected to another dispatcher or other process (i.e. an xterm telnet session). So, a "new" dispatcher attempting to connect to a controller already connected to a "older" dispatcher would sit waiting for the older dispatcher to disconnect from the controller. This effectively makes the new dispatcher's keywords inaccessible or incorrect.

The interactions between two dispatchers, using identical KTL service names and dispatcher id numbers, and the traffic process is a more serious problem than both of the dispatchers attempting to connect to the same controller. It is important to understand how the traffic process views connections from other processes to understand this problem.

Each process that connects to traffic sends traffic a process name to use as a unique id for the process. Traffic will not allow connections from two processes with the same name. When it receives a connection request from a process that has already established a connection. It assumes the first connection is stale and closes it.

A dispatcher identifies itself from other dispatchers connected to a traffic process by creating a unique name for itself using the KTL service name, i.e. "esi" for ESI, and dispatcher id numbers, i.e. "0" or "1" for ESI. The unique name is sent with connection attempts to the traffic process. If two dispatchers are started with the same KTL service name and dispatcher id parameters, they will identify themselves to traffic with the same process name.

The dispatcher software is designed to reconnect to the traffic process when disconnected (normally a very useful feature). However, if two or more dispatchers are started with the same KTL service name and dispatcher id's and attempt to connect to the same traffic process, they end up in an infinite loop with each other. They identify themselves to traffic with the same name, so traffic only allows only one connection for the twin processes. Each dispatcher making a successful connection to traffic will disconnect the last "identical" dispatcher in establishing a connection. The disconnected dispatcher then proceeds to reconnect to traffic, disconnecting its twin. This continues until all except one of the twin dispatchers are stopped.

Starting up multiple dispatchers with the same traffic names is very bad, don't do it!

To avoid this problem:

1. Don't start the dispatchers directly, always use the "esi start" command.
2. Check the ESI Console window to see if the dispatcher is connecting to the regular traffic process. It will show any existing traffic connections to ESI dispatchers.
3. If you must start up a dispatcher directly, shutdown any dispatchers currently running that will conflict with the one you want to start up. Use the dispatcher mode keyword "DISPxMOD", where x is the id of the dispatcher (it is usually the same as the controller id), i.e. "modify -s esi DISP0MOD = shutdown" will shutdown the dispatcher for ESI motor controller #0. You can also use the "esi stop" command to halt any dispatchers started via the "esi" command.
4. Use "ps auxww|grep dispatch" to check for any dispatchers that were started without using the "esi start" command, or that just failed to stop. Use the Unix "kill" command to stop these processes.
5. Notify anyone who may try to restart the dispatcher to leave the dispatcher alone.
6. Shutdown the dispatcher when you are finished. Use the dispatcher mode keyword as shown above to tell the dispatcher to shutdown. You can also be a little less civilized and use the Unix "kill" command if you wish.
7. Always use "ps auxww|grep dispatch" when you are done to make sure you stopped any dispatchers you started.

---

If you still want to start a dispatcher directly after reading the warning above, then continue. If you skipped the warning above, then go back and read it first. If you have read the warning before and are skipping it because you don't think you need to read it again, go back and read it again anyway; you need to follow the safety steps at the end of the warning.

If you are now ready to invoke the dispatcher from the command line you must do the following:

1. Steps 2-5 in the warning above.
2. Get the fully qualified host name of the machine where you will start the dispatcher.
3. Check the value of the DTAKESERVICE environment variable. If the DTAKESERVICE environment variable isn't set, a "dtakeservices" file must be present in the local directory when you start the dispatcher.
4. An "esi_trtalk" entry must exist for the dispatcher's host machine in the "dtakeservices" file. The dispatcher connects with the traffic process on the machine specified by the "esi_trtalk" entry. Add the necessary entries to the "dtakeservices" file, if they do not exist.
5. Make sure traffic is running on the machine specified by the "esi_trtalk" entry. You may be able to do this via the ESI console or you may need to do a "ps auxww|grep traffic" on the traffic host machine. The dispatcher will run without traffic, but you can't talk to it from any remote process, i.e. the ESI GUI or the show/modify/waitfor commands.
6. Determine the directory path to the destination for the dispatcher log file.
7. Determine the directory path to the default configuration files you need to run the dispatcher. If you have some special configuration files that you wish to use in place of some of the default configuration files, these must be in a directory below the default configuration file directory.
8. Invoke the "dispatcher2" command with no parameters. It will tell you its required and optional parameters in a usage statement.
9. Start the dispatcher via the "dispatcher2" command with appropriate parameters.

   ---

   Notes On Parameters

   • The KTL service name for ESI is "esi".
   • Each dispatcher acts as an interface to a controller of some kind. The dispatcher id is usually the same as the controller's id. For ESI two dispatchers exist, one for each motor controller. Their id's are "0" and "1".
   • If no path is specified via the "-c" or "-l" parameters for the configuration file and log file directories, the "dtakeservices" file will be searched for "esi_dispatcher_cfgdir" and "esi_dispatcher_logdir" entries. If the entries are found, the paths specified by the entries will be used for the default config file directory and log file directory respectively.
   • The default configuration file directory reverts to your current directory, if no "-c" command line parameter and no "esi_dispatcher_cfgdir" dtakeservices file entry are found.
   • The default log file directory reverts to your current directory, if no "-l" command line parameter and no "esi_dispatcher_logdir" dtakeservices file entry are found.
   • The "-t" option is not implemented at this time, so omit it.
   • The "-v" option provides additional configuration information in the log file at start up.
   • The "-h" option prints the usage message and causes the dispatcher to exit, omit it.

   ---

10. When you are finished running the special dispatcher be sure it is shutdown (see step 6 & 7 in the warning again). Also, restore the "dtakeservices" file to its original configuration if you changed it.