12/12/91  dial_out, connect

Syntax as a command:  dial_out channel {destination} {-control_args}
                 or:  connect channel {destination} {-control_args}


Function:  permits you to access a remote system through a dial-out
channel.


Arguments:
channel
   is the name of the dial-out or slave channel to be used.  The star
   convention is allowed, which means the answering service selects a
   channel that has a matching name or generic destination and matching
   attributes (if specified).
destination
   is the dial-out destination.  This string is used when making the
   connection.  If omitted, the channel is priv_attached rather than
   dialed.


Control arguments:
-8bit
   does not suppress the parity bit of characters from the foreign
   system.
-abbrev
   enables abbreviation processing of request lines.
-brief, -bf
   disables printing of informational messages.
-echo
   echoes locally characters typed by you.
-escape CHAR, -esc CHAR
   makes CHAR the escape character.  (Default: !)
-modes MODES
   allows you to select the initial values of dial_out's modes (see
   "List of Modes" below).


-no_start_up, -ns
   disables execution of your start_up.dial_out.  This is assumed for
   the connect command.
-profile PATH
   establishes PATH as the abbrev profile to be used for request lines.
   (Default: your current profile).
-request REQUEST, -rq REQUEST
   executes the given request before entering its interaction loop.
   The rightmost -request is the one that is executed.  (See "List of
   Requests" below.)


-resource RSC_DESC, -rsc RSC_DESC
   allows you to specify a resource description to be used when
   attaching the dial_out channel.
-terminal_type TYPE, -ttp TYPE
   sets the terminal type of the remote connection to TYPE.  You can
   use this for hosts with unusual communications requirements.


List of requests:
escape CHAR, esc CHAR
   sets the escape character.
file_output PATH, fo PATH
   starts copying output to a file.
interrupt, int, break, brk, ip
   sends an interrupt signal (line break) to the foreign system.
modes STR
   allows you to control operational modes.
revert_output, ro
   finishes a previous file_output.
send STR
   sends its arguments to the foreign system as if they were typed by
   you.


send_file PATH {-control_arg}
   sends the contents of pathname PATH to the foreign system.  Any
   characters sent from the foreign system during this time are
   discarded; thus foreign echo of the file being sent is rejected.
   (If the foreign echo is slow, you may still see some echo after this
   request has finished.)

   Control arguments are--
   -display_input, -dsin
      displays characters sent from the foreign system during the
      transfer.
   -no_display_input, -ndsin
      does not display characters sent from the foreign system during
      the transfer.


switch_name
   returns the name of the I/O switch used by dial_out.
wait {STR} {-control_args}, [wait {STR} {-control_args}]
   waits for a specified string to come from the foreign system.  With
   no arguments, this request waits until any characters are sent from
   the foreign system.  Invoked with a string and/or -nl, it waits
   until the specified string is sent.

   Control arguments are--
   -inhibit_error, -ihe
      specifies that dial_out should not abort after a timeout has
      occured. This control argument requires that a timeout interval
      greater than zero also be specified (See the '-timeout' ctl arg).
      This control argument is most useful when wait is used as an
      active request.


   -nl
      waits until the specified string is sent with a trailing new
      line.
   -nnl
      waits until the specified string is sent but without a trailing
      new line.
   -no_inhibit_error, -nihe
      Specifies that timeouts should result in an abort.  This is the
      default.
   -no_timeout, -ntm
      specifies that there is no limit to how much time can elapse
      between character transmissions from the foreign system before
      dial_out assumes that the foreign system has finished
      transmitting.  (Default)


   -timeout N, -tm N
      specifies the maximum number of seconds that can elapse between
      character transmissions from the foreign system before dial_out
      assumes that the foreign system has finished transmitting.

   As an active request (and if a timeout did not occur), all the text
   sent from the foreign system since the last text processed by
   dial_out, including the string specified, is returned as a quoted
   string.


List of modes:
echo, ^echo
   enables/disables local echoing of characters typed by you.
echo_lf, ^echo_lf
   enables/disables echoing of LF after you type a CR.
line, ^line
   enables/disables line-at-a-time mode as opposed to
   character-at-a-time mode for your terminal.
quit, ^quit
   enables/disables transparent quit mode.  In this mode the BREAK key
   performs an "interrupt" request, rather than the normal Multics
   function.
raw, ^raw
   enables/disables direct transmission to the foreign system of
   characters typed.  (Default: raw)


send_lf, ^send_lf
   enables/disables transmission of a LF character as part of the
   new-line sequence.  If you don't set this mode, the new-line
   sequence consists of CR only; if you set it, it is CR-LF.  The
   new-line sequence is sent when you type the CR key or an NL is
   encountered in a file.


List of subsystem requests:
.
   prints a line of requests available in dial_out.
..
   executes Multics command lines.
?
   prints a list of requests available in dial_out.
abbrev, ab
   controls abbreviation processing of requests lines.
answer
   provides preset answers to questions asked by another request.
do
   executes/returns a request line with argument substitution.
execute, e
   executes a Multics command line.


exec_com, ec
   executes a file of dial_out requests that can return a value.
help
   prints information about dial_out requests and other topics.
if
   conditionally executes/returns one of two request lines.
list_help, lh
   displays the name of all dial_out info segments on given topics.
quit, q
   exits dial_out.


ready, rdy
   prints a Multics ready message.
subsystem_name
   prints the name of this subsystem.
subsystem_version
   prints the version number of this subsystem.


Access required:  You must have the dialok attribute and rw access to
the access control segment for the channel (type "user attributes" to
determine what attributes you have).


Notes:  The dial_out command executes your start_up.dial_out exec_com
on invocation; the connect command executes an exec_com specific to the
given destination (or channel if no destination is supplied) instead of
a start_up program.  The ec suffix ".dial_out" for dial_out and connect
exec_coms is assumed if you don't supply it.

The dial_out and connect commands acquire an appropriate communications
channel to a foreign system, execute your dial_out start_up and initial
request, and then enter an environment in which characters typed on
your terminal are sent to the foreign system and in which characters
sent from the foreign system become output at your terminal.  The
connect command differs from dial_out in that it automatically
generates an initial request of "ec DESTINATION" (or "ec CHANNEL" if no
destination is supplied) to start up communications to the appropriate
destination.


When the destination specifies an X.25 address, you can optionally
precede it with "*" or "x29," to indicate that an X.29 (PAD) call
should be made.  For example, a destination of
   x.29,3106:p25 or
   *3106:p25
specifies an X.29-type call on TYMNET.

After the dial_out environment is entered, you can enter dial_out
requests by preceeding them with the escape character ("!" by
default).  Characters from the escape character to the next escape
character or the end of the line are interpreted as a request.  You
must double the escape character to send it to the remote system.


When calling dial_out from an absentee process or from an exec_com
which is to send canned input lines to the remote system, it is
important to use the "dial_out -request ""ec PATH""" control argument.
This request invokes the PATH.dial_out exec_com containing all the
lines to be sent to the remote system.  This data should be given in
the form of dial_out send requests, interspersed with dial_out wait
requests to pause until the remote system is ready to receive more
input.  See the descriptions of the wait and send requests above.
Any attempt to dial_out without the use of PATH.dial_out, or by
placing the dial_out subsystem requests within the calling absin/ec
will result in unrecoverable I/O errors.


The send request sends only the data string given as its first
argument.  It does not append a carriage return (CR) or newline (NL)
character to this string.  Since most remote systems expect input
lines to be terminated by a CR character, this character must be
explicitly included in the send request.  See the example below for a
sample dial_out exec_com.

The wait request pauses within the dial_out exec_com until a specific
string is received from the remote system.  This allows the exec_com
to delay sending further input until the remote system is prepared to
receive the input.  Such pauses are especially important when
communicating with systems that are not prepared to receive type-ahead
input.


When dialing out to another Multics system, the general_ready command
can be used on the remote system to set a ready message which is
distinct from the local ready message.  A distinctive string in the
remote ready line can be specified in wait requests to determine when
the remote system is ready to receive the next command line.  This
technique avoids sending data faster than the remote communications
system can process it.  Rapid bursts of data can cause Front-end
Network Processor (FNP) buffer overflows (the Bell-QUIT syndrome).


Output from the remote system being directed to an absout file via an
absentee process or output_file via the dial_out "file_output"
request may contain terminal delay and or initial_string characters in
the output if the user's remote terminal type contains delays or an
initial_string.  The terminal type specifications can be displayed via
the "display_ttt -ttp TERMINAL_TYPE" command.  One terminal type that
does not contain delays or an intial_string is the ASCII_CRT terminal
type and thus may be used as a parameter to the remote system login
line in the PATH.dial_out exec_com.  Note the remote system login
line in SAMPLE.dial_out below.


A good way to verify that the absentee will correctly send and receive
data as expected is to execute the absin file as an interactive
exec_com until the entire absin/ec performs satisfactorily.  Once the
absin/ec has successfully operated by sending and receiving data
interactively, the absin/ec can be expected to run equivalently via
an absentee process.


If the dial_out exec_com pauses at a wait request and does not
continue, then the remote system has not sent the string expected by
the wait request.  To stop execution of the dial_out exec_com at this
point and print the data from the remote system, hit the BREAK key
(to signal quit on the local system) and then type a program_interrupt
(pi) command to reenter dial_out.  The quit/pi sequence may have to
be given several times.  Because dial_out has adjusted the terminal
modes on the local system, you may have to end the program_interrupt
command line with a newline (LF) character rather than a carriage
return (CR).  Note that, in order to have the BREAK key send a quit
signal to the local system, the dial_out quit mode must be disabled
(via "!modes ^quit").  The quit mode is disabled by default.


Examples:
        ! print SAMPLE.ec

          &command_line -off
          dial_out ** 6430 -rsc line_type=none,baud_rate=1200 -request
            "ec SAMPLE"
          &quit


        ! print SAMPLE.dial_out

          &version 2
          &trace off
          &set CR "\015"
          &set LF "&NL"
          wait "Load"
          wait "&(LF)"
          send "l Parisek -ns -ttp ASCII_CRT &(CR)"
          wait "Password"
          wait "&(LF)"
          send <password> &(CR)"


          send "general_ready -string ""<wait_string>"" -set &(CR)"
          send "ready_on &(CR)"
          wait "<wait_string>"
          send "<command> &(CR)"
          wait "<wait_string>"
          send "logout &(CR)"
          wait "hangup"
          &quit
