% @(#)connecback.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:23 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      connecback.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, CONNECT/BACK_MIDAS
%.PURPOSE    On-line help file for the command: CONNECT/BACK_MIDAS
%.VERSION    1.0  12-MAR-1990 : Creation, KB
%.VERSION    1.1  22-FEB-1993 : Update, KB
%----------------------------------------------------------------
\se
SECTION./BACK_MIDAS
\es\co
CONNECT/BACK_MIDAS					27-OCT-1994  KB
\oc\su
CONNECT/BACK_MIDAS unit wait_specs b_char method
	connect "command syntax" to another MIDAS 
\us\pu
Purpose:
         Connect to another MIDAS (which will be started if not running yet)
         to execute commands in that MIDAS session from the current MIDAS.
\up\sy
Syntax:
         CONNECT/BACK_MIDAS unit wait_specs b_char method display
\ys\pa
         unit = unit of Midas session we want to connect to;
\\
              if the Midas session runs on another host, `host:unit' must
              be entered, but then the Midas session must be already running
              on theat host
\ap\pa
         wait_specs = `nowait' or `wait[,max_wait]' to indicate, if we want
             to wait until the background command terminates or not;
\\
             if `,max_wait' is given, at most max_wait seconds are waited,
             then control is returned to the current MIDAS
\ap\pa
         b_char = character to indicate a background command;
\\
             `bchar,command' will execute the command in the Midas session
             with `unit' given above
\ap\pa
         method = FILES or SOCKETS to define the mechanism used for the
             communication with the "background" MIDAS;
\\
             for FILES simple ASCII files and interrupts are used to
             communicate,
\\
             for SOCKETS the communication is established via Unix sockets;
\\
             defaulted to FILES
\ap\pa
         display = display name in X11 notation if the background MIDAS session
             will be started via the CONNECT command
\\
             the backgr. MIDAS will then be displayed in a terminal window on
             the given display
\ap\sa
See also:
         SHOW/BACK_MIDAS, WAIT/BACK_MIDAS, DISCONNECT/BACK_MIDAS 
\\
         SET/BACKGROUND, CLEAR/BACKGROUND, [BackgroundMidas]
\as\no
Note:  
         This command provides a simple way to enforce execution of commands
         in another Midas session, using the current Midas as client and the
         other (background) Midas as server. Up to 5 background Midas sessions
         can be connected to.
\\
         If `method'=FILES, the Midas session we connect to may or may not
         be in background mode (by executing the command SET/BACKGROUND) and
         must run on the same host. I.e. host:unit is not possible for the
         FILES method.
\\
         If `method'=SOCKETS, the Midas session we connect to must already be 
         in background mode. If that Midas session is started up by the
         CONNECT/BACK command this is done automatically.
\\
         Important: for the socket method, the `unit' parameter must be two 
         digits, e.g. 33, `unit' like xx will NOT work!!
\\
         Also, remote Midas sessions cannot be started via the CONNECT command!
\on\exs
Examples:
\ex
         CONNECT/BACK zk nowait z
           Indicate, that all commands with prefix "z," or "Z," will be 
           executed with the prefix stripped off again in background Midas with
           unit `zk', do NOT wait until that command terminates. ASCII files
           and interrupts will be used as the communication mechanism.
\\
           If a Midas session with unit `zk' does not run yet, it will be
           started first.
\\
           The command: Z,HELP LOAD/IMAGE    would then display the help text
           in the window belonging to the background Midas with unit `zk'.
\xe \ex
         CONNECT/BACK 44 wait b
           Indicate, that all commands with prefix "b," or "B," will be 
           executed (prefix stripped off) in background Midas with unit `44',
           wait until that command terminates. ASCII files and interrupts
           are used as the communication mechanism.
\\
           B,HELP READ/KEY INPUTC  would then display the contents of keyword 
           INPUTC in the window of to the background Midas with unit `44'.
\xe \ex
         CONNECT/BACK 88 wait,10 c
           All commands with prefix "c," or "C," will be executed (with prefix 
           stripped off) in background Midas with unit `88'. ASCII files
           and interrupts are used as the communication mechanism.
\\
           We wait at most 10 seconds for the termination of the command which
           has been sent to MIDAS with unit `88'. If the command has not
           finished by then, control returns and an error message is displayed
           in the current MIDAS.
\xe \ex
         CONNECT/BACK 33 no x sockets xt119:0.0
           All commands with prefix "x," or "X," will be executed in the Midas
           session with unit `33' running on the same host.
\\
           This Midas session will be started using a window on the X-terminal 
           xt119:0.0. Local sockets are used as communication mechanism.
\\
           If this Midas session is already running the `display' parameter is
           ignored.
\xe \ex
         CONNECT/BACK ns2:33 no x sockets 
           All commands with prefix "x," or "X," will be executed in the Midas
           session with unit `33' running on system named `ns2'.
\\
           This Midas session must be already running. Network sockets are used
           as the communication mechanism.
\xe \sxe