packages icon
 XT(1)                                                   UNIX
 (printed 7/8/97)

 Name         xt - communications program using telnet

 Syntax         xt [ [-nhostname] | [-sscript] ]

 Description          Xt  connects  to  a  remote host  using   the   telnet
 protocol. It  can  manage          an interactive session or be called from
 cron(C).  It has  various  means          for  transferring  files  between
 computers,  and  can  be  partially or         totally under the control of

         Xt starts up by reading the file .xtrc, which is sought for in this
         order:  in  "XT_PATH",  in the  current  directory,  in  your  HOME
 directory,         or  in  a default directory  defined  at  compile  time.
 This startup file           may  contain  any of  the  valid  SET  commands
 described  below.  Xt  then          displays  the  current  settings,  and
 presents an <XT> prompt, unless the         -s option was used.

    Options         -nhostname Connect  to  the  specified  hostname,  which
 may be  given  as  a                     Fully Qualified Domain Name (e.g.,  or  as                        an   IP   octet   (e.g.,  If a telnet command                    issued from a shell
 prompt can reach a site, then xt can                    reach it too.

         -sscript   Execute the specified script after program startup.

         The two options are mutually exclusive.

    Environment          The  environment may  contain  a  variable   called
 "XT_PATH",   consisting   of           colon  separated absolute  paths  to
 directories.    If    this     variable is     set             to,     say,
 "/usr/joe/xt:/usr/lib/xt", then those two directories are the         first
 places searched for any scripts.

    Command Mode         When entering characters in command mode (that  is,
 at  the  <XT>  prompt),         control characters echo as ^x, where "x" is
 the control character that         was entered. Backspacing (using whatever
 key  is defined in  the  current          environment) backspaces over both
 positions of the displayed control         character, as expected.

         An "interpreted" key can be added in a manner similar  to  that  of
 vi(C);           simply   type  ^V  followed by  the  character  to  insert
 (backspace, delete,         carriage return, or newline).

         The following commands are available at the <XT> command prompt:

         c         cis              Respond to an ENQ signal  for  a CIS  B-
 Plus  protocol                           transfer. This command is used for
 both uploading and                          downloading from CompuServe.

         n hostname         nethost hostname Establish a  telnet  connection
 to hostname, then enter                          terminal mode.

         s  file          script  file       Execute  file,  which  contains
 appropriate  xt  script                           commands. Enters terminal
 mode when the script is com-                          plete.

         set [options]    Display or set the  parameters  used  by  xt.  See

         t         term             Enter terminal mode.

         x         q          exit          quit              Exit  program.
 Return to invoking program/shell.

         ?            help               Displays   a   brief   summary   of
 xt commands,  the SET                          options, and terminal-escape

         [Note: a  compile-time  option  can  disable  the  following  three
 options  to          prevent any access to shells or other programs outside
 of xt.]

         ! command      Execute the specified command as a child process. If
                         command  is  omitted,  execute  a local interactive
 shell.                         (A space is required between the !  and  the

         !!             Re-execute the last shell command string.

         $ command      Execute  a  shell  command  with  stdin  and  stdout
 redirected                          to  the telnet socket. This effectively
 puts the computer                        into  a  "host"  mode.   (A  space
 is required between the $                        and the command.)

    Using the SET Command         The  SET command is  used to  display  and
 set/reset  xt's  tunable parame-         ters. Any of these commands may be
 placed in the .xtrc file which is         read upon starting up xt.

         Used alone, SET displays xt's current parameters.

         The following parameters can be set (note that except in  the  case
 of          names,  these commands are case-insensitive, and that there are
 alterna-         tive forms of the commands shown on the XT help screen):

         set  auto  on|off Sets  the  auto-capture  feature.  When  entering
 terminal                           mode,  capturing commences  without  the
 necessity to                         manually request it.

         set cfile name  Set the name of the capture file.

         set cis on|off  Set response to a CompuServe file transfer  request
                         (<ENQ>).  An  "on"  value  specifies  that  when in
 terminal                         mode, an <ENQ> character will launch a CIS
 B-Plus  pro-                          tocol transfer. This parameter should
 be set "off"                         when not connecting to CompuServe,  as
 line noise may                         cause a bogus file transfer request.

         set cr on|off   In  uploads  using  B-Plus protocol,  setting  this
 option                          "on"  will  insert  a carriage-return after
 each newline                         in an ASCII file. If  you  expect your
 ASCII  upload  to                          be  captured  by  DOS  users, it
 is best  to set  cr  "on".                           If  your ASCII  upload
 is meant  strictly for Unix users,                         then you may set
 cr  "off".   The B-Plus  protocol imple-                          mentation
 used  by xt will always strip end-of-line                         carriage-
 returns from incoming ASCII files.

         set dir name    Set the current working directory.

         set menu on|off By default, a one-line menu is displayed above  the
                         <XT> prompt to remind the user of options most fre-
                         quently chosen  at  this  point:  "[t]erminal  mode
 [q]uit                         [s]cript [?]help".  Setting the option "off"
 turns off                         this display.

         set nl on|off   If this option is set "on", then newlines are  sent
 as                          carriage-returns.  If this option is set "off",
 then                          newlines  are  sent  as  newlines  (carriage-
 returns are  in                          any  case always sent as carriage-
 returns).  This                         option applies  to  input from  the
 keyboard,  or  from a                         disk file using the "XCAPE F"
 facility or a script                         "type"  command  (See  below).
 This   option  has  no effect                          on  B-Plus  protocol
 transmissions, and has no effect on                         incoming data.

         set xcape char         set escape char Set the XCAPE character (see
 below)  to  char.  This                          should be set to some non-
 printing  character  (other                          than   backspace, tab,
 newline,   of  course).   The  charac-                          ter  may be
 entered by depressing the  Control  key  first                          and
 then      typing a     letter,     or     by typing     a     caret     (^)
                         followed by a letter.

    Terminal Mode         In terminal mode,  all  characters  typed  at  the
 keyboard  are  sent to  the          telnet connection, except that newline
 characters  (0x0A)  are  translated          to   carriage-returns   (0x0D)
 when you  have  "set  nl  'on'"; all  characters          received from the
 telnet connection are displayed on the local terminal         screen.

         XCAPE is a key that will, when typed in terminal mode, introduce an
 xt          "escape"  command.  Don't confuse XCAPE  with the <ESCAPE> key.
 The         default definition for XCAPE is ASCII 1, or Control-A.  It  can
 be  rede-          fined at run time with the "set escape C" command (or it
 can be rede-         fined in the .xtrc startup script).

         When the XCAPE key is typed  in  terminal mode,  the  program  will
 examine          the  next  key  pressed.  If  this key has been "bound" to
 perform  a certain          function,  that   function will   be performed;
 otherwise,   the   second   char-          acter  is  sent  to  the  telnet
 connection. Thus, to send the XCAPE charac-         ter through  the telnet
 connection, it is necessary to press the key         TWICE.

         Thus the ESCAPE key itself would be a terrible  choice  for  XCAPE,
         because it  is  used so often by other programs: if you were logged
 into         a remote system and running, say, vi,  it  would  be  a  great
 annoyance to         have to hit ESCAPE twice to get it transmitted once.

         The following keys (case insensitive) are  bound at  startup  time.
 Others          may  be  added through the binding commands available in xt

         Command  Function     Description

         XCAPE /  Help         Display the table of bound keys         XCAPE
 ?  Help         Display the table of bound keys

         XCAPE  f    File           Send   a   file   through   the   telnet
 connection (ASCII                               transfer).

         XCAPE s  Script       Xt will request  the  name  of  a  script  to

         XCAPE y  Capture Yes  Open the capture file in  APPEND  mode  (text
                                  received    over   the telnet   connection
 accumulates                               at the end of the file).  If  the
 file is already                               open, a message is printed to
 that effect.

         XCAPE n  Capture No   Close the capture file. If it wasn't open,  a
                               message of regret is printed.

         XCAPE x  eXit         Exit terminal mode back to <XT> command mode.

         XCAPE q  Quit         Quit xt altogether.

    Scripts         The xt script language is intended to be closely similar
 to   the Unix           Bourne  shell  language.  Unfortunately,  it  isn't
 identical to the Bourne         shell, so it has the same problem that  the
 awk(C) program does for         those experienced in the C language: an awk
 script LOOKS like C, but it         isn't, really; and in the same way,  an
 xt  script  LOOKS  like  a  Bourne          shell  script,  but  isn't.  So
 the operation of the Bourne shell, if         you're familiar with  it,  is
 useful  as  an  analogy  in  understanding  the         xt script language,
 but only as an analogy.

         An xt script consists of lists of commands. Commands  are  set  off
 from          each  other  within  a  list  by  either  a newline ('0) or a
 semicolon (;),         as is the case with the Bourne shell. The  semicolon
 and the  newline          have  identical  effect  as  command  separators,
 so (anticipating a bit         here) you could say either

           if counter morethan 5           then             transmit "bye^M"
             quit           endif


           if counter morethan 5; then transmit "bye^M"; quit; endif

         and  the result  will  be  the  same either  way.   The newline and
 the semi-          colon  are  treated the same way as in the Bourne shell,
 except that  a          newline cannot  be  quoted  so  as  to  remove  its
 interpretation  as a com-         mand terminator (in other words, a quoted
 string cannot contain a new-         line).

         Commands  are  composed  of  words  separated  by  spaces  or   tab
 characters,         and a word can be one of the following:

         *  One of the xt script language keywords, which are listed  below,
 with            appropriate explanations.

         *  A number, meaning a sequence consisting only of digits,  with an
            optional leading minus sign to indicate a negative number.

         *  A literal string of  characters  surrounded  by double-quotation
 marks             ('"'); such a string can be no longer than 80 characters.
 A double-            quotation mark can be imbedded within  the  string  by
 preceding   it                with a   backslash  ('              backslash
 is disregarded  and the  double-quotation  mark  is  treated  as
 part of  the string. Mismatched quotation marks result in a syntax

         *  The name of a user variable, which can have either a string or a
             numeric  value.  The name of a user variable must begin with an
            alphabetic character.

         *  The name of a shell environment variable, preceded by  a  dollar
 sign            ('$'). The xt script language examines the Unix environment
 for the            specified variable  and,  if  such  a  variable  exists,
 substitutes the            value of that variable. The result is treated as
 if it were a quoted            literal string, and, therefore,  should  not
 be  more than 80 charac-            ters long, or else it will be truncated
 to its first 80 characters.               Similarly,  such  an  environment
 variable should not contain a new-            line.

         *   An  expression  surrounded  by  back-quotation   marks   ('`').
 This sort of            expression operates similarly to the Bourne shell's
 command-substi-            tution mechanism:  the  contents  of  the  back-
 quotes  are  passed to the            Bourne shell, and the standard output
 of the back-quoted command is            treated as if  it  were  a  quoted
 literal  string.  Therefore,  the            command's output should not be
 more than 80 characters  long, nor              contain  a  newline.  Also,
 the contents  of  the back-quotes  cannot  be              longer  than  80
 characters, nor contain a newline.

         *  An expression introduced by a pound-sign (or number-sign:  '#'),
            which is treated as a comment. All characters from the '#' until
 the              end  of  the  physical  line  are ignored.  This   comment
 mechanism is the            same as in the Bourne shell.

         *  A limitation of the script language is that  only  one character
             string  can  be  passed as  an  argument  to  any of the script
 commands.               The  bind_function,  bind_script,  and  bind_string
 commands  thus  need            to use a decimal digit to represent the key
 that is to be bound. The            ASCII value of the the key is employed.
 As  an  example,  Control-C is            identified as 3, Control-Z is 26,
 the ESCAPE key is 27, a space is             32,  the  number  "1"  is  49;
 letters are case-insensitive so that iden-            tifying the bound key
 as "65" or as "97" will always bind both "a"            and "A" to the same

         Quoted literal strings (and the two other mechanisms that act  like
         quoted literal strings, shell environment variables and back-quoted
         shell commands) may be up to 80 characters long.  All  other  words
 must          be  no  longer  than  16  characters,  and  are treated case-
 independently          (which  is  to  say,  uppercase   is   the   same as
 lowercase);  note,  though,          that  the  names  of shell environment
 variables are case-dependent          (uppercase  must match  uppercase and
 lowercase must match lowercase),         because they are case-dependent in
 the shell.

         Any word  not  recognizable  within  the  foregoing  categories  is
 treated  as          the  name  of  a  new  user  variable. Such a word, if
 longer than 16 charac-         ters, is considered to be a syntax error.

         User variables are created with the 'assign'  script  keyword,  and
 may          have  either  numeric  or  string  values.  The type of a user
 variable is         determined by how it's created; if it's assigned  to  a
 string,  it's  a         string variable, and if it's assigned to a number,
 it's a numeric vari-         able. The value of any user  variable  can  be
 changed with another         'assign' command, and numeric variables can be
 changed   to   string   vari-           ables   and    vice-versa.    Shell
 environment variables  cannot  be  changed         within an xt script, but
 the value of a shell environment variable can         be assigned to a user
 variable, and  the value  of  the  user  variable can         thereafter be

         Scripts are contained in  ASCII  text  disk  files, one  script  to
 a file. A         script can invoke another script as a subroutine with the
 'call' key-         word; up to 5 scripts can be nested in this way at  any
 single time.

         With all this  said,  the following  list  of  xt  script  language
 commands          should  be comprehensible. The format "<something>" means
 that a token,         or word-type, of the "something" type is meant rather
 than the literal         sequence 'something'.

    Script Language Commands         Note that all the  commands  are  case-

         affirm             Syntax: affirm

             Reads a string from the  terminal,  and  returns  TRUE  if  the
 string              begins with 'y' or 'Y'; otherwise, returns FALSE.  Used
 in evaluat-             ing conditional expressions.  The  string  must  be
 terminated by a             newline or carriage-return.


               echo -n "Continue (y/n)? "               if  affirm
 then                   continue                 else                  break

         assign                 Syntax:   assign    <varname>    eq <number>
                     assign <varname> eq "string"                     assign
 <varname> eq "string" ["string"|<varname>] ...                       assign
 <varname1>  eq  <varname2>                     assign <varname> eq <script-

             Assigns to user variable <varname> the value following "eq"; if
              that  value is a number, then <varname> becomes a numeric user
 vari-             able; if that value is a string, then <varname> becomes a
 string              user variable. If <varname> does not already exist as a
 user vari-             able, it  is created.  Variable  space is  allocated
 dynamically,  but              running out of memory space for variables is
 unlikely. All vari-             ables are global across  scripts  that  run
 at the  same  time  via  the              'call' keyword, and all variables
 vanish when a script, called              directly  from  xt  as opposed to
 called  from  another  script, exits.              In other words, variable
 values  are not  static  except  during   'call'                 execution.
 Variable names cannot be longer than 8 characters. Suc-             cessive
 'assigns' are permissible, and the type of the variable             changes
 according  to  the  type  of  the  value  following  "eq".  A user
 variable is destroyed with the 'unassign' keyword.

             If a variable is assigned the value of a script  command,  then
 it               becomes  a  numeric  variable  with  value  TRUE or FALSE,
 depending on             the status returned by the script  command.  If  a
 variable  is               assigned  the value of a back-quoted command, it
 becomes a string             variable  with  the  value  of  the  first  80
 characters  of  the  back-               quoted  command.  If a variable is
 assigned equal to an environment             variable, it becomes a  string
 variable with the value of the first             80 characters of the value
 of the environment variable.

             If the third form given above is used, then the various strings
 are               concatenated.  A  string  variable  can be created from a
 numerical             variable with 'assign "" numvar' or 'assign "" 678'.


               assign numvar eq  5                 assign  strvar  eq  "This
 variable is a string"               assign strvar eq "This" " variable is a
 " 7 " word string"               assign mydir eq $HOME               assign
 numvar2   eq numvar                   assign   strvar2  eq strvar
 assign numvar eq true               assign today eq `date`; echo "today  is
 " today

         beep             Syntax: beep

             Sends a Control-G to the terminal. Useful for alerting the user
              that some event has occurred, for example the end of a lengthy
 file             transfer operation.

         bind_function             Syntax: bind_function code "function"

             Bind the character identified by the number specified  by  code
 to             the xt builtin function "function".

             The "function" may be one of the following (case is ignored):

               CAPTEND Turn off terminal mode capture                CAPTYES
 Turn  on  terminal mode capture               DIVCHAR Send file through the
 telnet  connection                 DOSCRPT  Execute  script  file  (prompts
 interactively)               EMITSTR Emit string               ENDCHAR Exit
 terminal mode                HLPCHAR  Display  terminal  mode  key bindings
                 QUITCHR  Quit  program                 SCRPCHR  Prompt  for
 script file


               bind_function 26 "quitchr"

             This binds Control-Z to quit the XT program.

         bind_script             Syntax: bind_script code "scriptname"

             Bind the character identified by the number specified  by  code
 to             execute the script named by "scriptname".

              Upon  termination  of the  script,   the program will   resume
 terminal             mode, unless the "quit" script function was executed.


               bind_script 18 "/usr/lib/xt/.rz"

             This binds Control-R to execute the script /usr/lib/xt/.rz. The
 .rz             script supplied with the source code contains:

               tty  "on"                 echo  -n  "What  files  are  to  be
 received?  "                 read  FILES                 transmit  "sz -y "
               transmit FILES               transmit "^M"               echo
 "Starting ZMODEM Receive (rz -y)"               pipe "rz -y"

             Pressing XCAPE ^R will ask for some file name(s), and  start an
 sz               command  on  the  remote  system,  and  an rz on the local
 system to             receive the file(s).

               bind_script 19 "/usr/lib/xt/.sz"

             This binds Control-S to execute the script /usr/lib/xt/.sz. The
 .sz             script supplied with the source code contains:

               tty "on"               echo -n "What files are to be sent?  "
                read FILES               echo "Starting ZMODEM send (sz -y "
 FILES ")"               pipe "sz -y " FILES

             Pressing XCAPE ^S will ask  for  some file  name(s),  and  then
 launch               sz  on the current system.  Sz will itself start an rz
 process on             the remote system.

         bind_string             Syntax: bind_string code "string"

             Bind the character identified by the number specified  by  code
 to             emit the string specified by "string".

             The string is sent to the telnet  connection untranslated;  eg,
 it is             not examined for embedded terminal mode escapes.


               bind_string 49 "pwd^M"

             This binds "1" to send  the  sequence to  report  your  current
 direc-             tory on a remote system.

         break             Syntax: break

             Exits from the immediately enclosing 'while' loop. Identical to
 the              C language 'break', and to the Bourne shell 'break' except
 that the             xt script language 'break'  does  not take  a  numeric

         call             Syntax: call "scriptname"

             Suspends execution of the current script, and attempts to  load
 and               run the  specified  scriptname.  The scriptname must be a
 quoted             literal string. There is no xt analogue  of  the  Bourne
 shell "exec"              command; all subscripts in xt are treated as sub-
 routines. All             variables are global across subscripts, so  if  a
 subscript  changes               the value  of a variable, then that change
 will remain in effect             after return to the parent script.  Shell
 environment variables can-             not be changed by any xt script.

         capture                 Syntax:   capture   "on"
 capture "off"

             Turns the file-capture  function  on  or  off.  Note  that  the
 arguments               must  be  quoted  literal  strings.  Note also that
 when the script              exits  into  terminal mode,  the  file-capture
 function is  turned off.              If you have 'set auto "on"', then you
 will begin capturing immedi-             ately upon entering, or  returning
 to,  terminal  mode. If not, then             you must manually type "XCAPE
 Y" to start capturing when entering             terminal mode.

         continue             Syntax: continue

             Resumes execution  at  the  top  of  the immediately  enclosing
 'while'                 loop.    Identical  to the  C  language  'continue'
 instruction, and to             the Bourne shell  'continue' command except
 that no numeric argument             is accepted.

         debug              Syntax:  debug  "on"                       debug

              If  the  'debug'   option   is   on,   then   xt   will   make
 many parenthetical             comments about what it's doing while it runs
 the script. These  com-               ments  can  sometimes be  helpful  in
 debugging script logic. Note that             the argument must be a quoted
 literal string.

             While debugging  a  script  containing a  password,  turn  this
 option               off,  then on again, to reduce the excitement-level of
 any col-             leagues collected circa your screen.

             See, below, the Debugging Section.

         decr             Syntax: decr <numeric-variable>

             Decrements the value of the specified numeric user  variable by
 1.                Useful  in  controlling  loop execution. If the specified
 variable             isn't  numeric,  or  doesn't  exist,  a  syntax  error

         echo                 Syntax:   echo   "string"    <variable>    ...
                     echo -n "string" <variable> ...

             This command sends its arguments to the  user's  terminal.  The
 number               of arguments is optional, except that the total result
 may not             exceed 80 characters. Variables  and back-quoted  shell
 commands are             expanded as necessary.

             If the "-n" switch is present, then no  carriage-return/newline
             sequence is appended to the output.


               echo "The time and date are now " `date`                 echo
 "My  terminal type  is "  $TERM                 echo "My terminal type is "
 $TERM " today."

             Note that whitespace isn't echoed unless it's part of a  quoted
             literal string.

         exit             Syntax: exit

             Terminates execution of the current script. If a script reaches
 its              end, it exits automatically, so 'exit' is useful mainly to
 ter-             minate a script prematurely.

         false             Syntax: false

             Same as the Unix 'false' command. Does  nothing,  but returns a
 FALSE             status value. Useful within conditional expressions.


                if  waitfor  "CONNECT"  30  eq  false                   then
                 quit               endif

             Note that above example could be rewritten using  the  negating
             modifier "!":

                 if   !   waitfor   "CONNECT"    30                     then
                 quit               endif

             and note too that the "!" must be separated from  its  argument
 by             whitespace.

         file             Syntax: file <script-command>

             The standard output of the specified script command is  sent to
 the               current capture file. If the "capture" option is not set,
 then an               error  message  is  displayed, but  script  execution


               file echo "--------- CUT HERE ----------"

             Sends the output of the 'echo' command to the  current  capture
 file,             provided that the "capture" option is now "on".

               file echo `date`

             Sends a timestamp to the current capture  file,  provided  that
 the               "capture"  option  is now "on". The same thing could have
 been done             with

               file shell "date"

         host             Syntax: host "hostname"

             Open a telnet connection  to a  hostname,  given  either  as  a
 domain                name  or  a  dotted  quad.  If  there  is  a  current
 telnet connection             open,  it  will  be  terminated with  extreme

         if             Syntax: if <list1>; then  <list2>;  [ else  <list3>;
 ] endif

             If <list1> evaluates as TRUE, performs <list2>;  otherwise,  if
              <list3> is specified, performs <list3>; then resumes execution
             immediately following 'endif'. To accommodate those whose minds
             wander while writing scripts, 'fi' is an acceptable synonym for

              Each  list  may  consist  of  any  number of  script  commands
 separated  by               semicolons or newlines. The value of <list1> is
 determined by             inclusively OR'ing the value of each directive in
 the list, so that             if any of the directives in <list1> evaluates
 as TRUE, then so will              <list1>.  <list1>  is performed  in  its
 entirety  regardless  of the               value  of  any  of its component

             The keywords 'then', 'else', and  'endif'  (or  'fi')  must  be
 immedi-                ately  preceded  by  command  separators,  either  a
 semicolon or a new-             line, just as is the  case  in  the  Bourne

             For conditional evaluation in 'if' and  'while'  constructions,
 the               following  comparators  are  available in addition to the
 script             directives mentioned elsewhere:

               <varname1> eq "string"               <varname1>  eq  <number>
                <varname1>  eq  <varname2>               <varname1>

             evaluates as TRUE if the value of user variable  <varname1>  is
 the               same as that of a specified string or numeric constant or
 of a             specified second  variable  name.  If  the  variable  name
 <varname1>   is                 not followed  by  anything  else,  then the
 expression evaluates as             TRUE if the variable is numeric and has
 a  non-zero  value, or if the             variable is a string variable and
 has a non-zero  length;  otherwise,               the expression  evaluates
 as FALSE. Comparing a string variable to a             numeric variable, or
 vice-versa, causes a syntax error.

             If a conditional expression consists only of a  quoted  literal
             string, the expression evaluates as TRUE if the string's length
 is                     non-zero,     and     otherwise     evaluates     to
 FALSE. Because environment               variables  and  back-quoted  shell
 commands are treated as  if  their               output/value  were  quoted
 literal  strings,  this  allows  direct  test-               ing of a shell
 command   or   of   an   environment for   non-zero    length.
 Nonexistent environment   variables  are  treated  as  if they  exist  with
             the value "" (a string of zero length).

               <varname1> neq "string"               <varname1> neq <number>
               <varname1> neq <varname2>

             evaluates as TRUE if the value of user variable  <varname1>  is
 not              equal to that of a specified string or numeric constant or
 of  a               specified  second  variable  name.  Comparing  a string
 variable to  a             numeric variable, or vice-versa, causes a syntax

                <varname1>  lessthan   "string"                   <varname1>
 lessthan <number>               <varname1> lessthan <varname2>

             evaluates as TRUE if the value of user variable  <varname1>  is
 less              than that of a specified string or numeric constant or of
 a speci-               fied  second variable  name.  String  variables  are
 compared lexically             according to ASCII value.

                <varname1>  morethan   "string"                   <varname1>
 morethan <number>               <varname1> morethan <varname2>

             operates identically to 'lessthan', except in reverse.

             The value of  any  conditional  expression  may be  negated  by
 preceding               it  with  an  exclamation point followed by a space
 or tab.


               if counter eq 0; then break; endif;               if var1  eq
 var2;  then  echo  "identical"; endif               if counter morethan 20;
 then break; endif;               if counter lessthan 0; then break;  endif;
               if ! counter; then echo "counter is " counter; endif

             To perform a list if any of a set of conditions exist:

               if counter morethan 5;                  counter eq  brkvalue;
 # a second comparator               then break;               endif;

               i.e.,   perform   the   'break'   directive if   the    value
 of numeric user              variable 'counter' is greater than the numeric
 constant 5, or if             the value of 'counter' is equal  to  that  of
 the user numeric vari-             able 'brkvalue'.

         incr             Syntax: incr <numeric-variable>

             Increments the value of the specified numeric user  variable by
 1.              The opposite of 'decr'.

         pause             Syntax: pause <number>

             Suspends execution  for  the  specified  <number>  of  SECONDS.
 Identical             to Unix "sleep."

         pipe             Syntax: pipe "<shell-command>"

             The standard input and standard output of the  specified  shell
 com-               mand  are  connected  to  the telnet connection, and the
 command is             executed. This is the equivalent of the command mode
 "$" command.


               pipe "echo

             sends a DELETE character to the telnet connection.

               pipe "rz"

              performs  a  file  receive  via ZMODEM, assuming  that   Chuck
 Forsberg's             'rz/sz' programs reside on your system.

         quit             Syntax: quit

             Exits  the  script  and  terminates  xt  entirely.  The  user's
 terminal               will  be  restored  to the  state  it was in when xt
 was invoked.

         read             Syntax: read <variable-name>

             Takes a string from the user's keyboard and places it into  the
              specified  user  variable. Any previous value of the specified
 vari-             able is discarded.

         seen             Syntax: seen "string" <number>

             Evaluates as TRUE if "string"  has  occurred  within  the  last
 <number>               characters received during the most recent 'waitfor'
 command. Only             up to 2048 characters are remembered  at  any one
 time   during 'wait-                 for'  processing.  If no  <number>  is
 specified, then all the charac-             ters received during  the  most
 recent  'waitfor'  command  are  exam-             ined, up to a maximum of
 2048. The 'seen' buffer is reset  at  the               beginning  of  each
 'waitfor' command.  This  is  useful to  tell which              of several
 strings has been received.


                  if    waitfor    "string1"    20                      then
                 echo     "Received     'string1'."                     else
                 if  seen "string2"                  then
 echo   "Received   'string2'   instead."                   endif

         set             Syntax: set <xt-set-option> <value>

             This command is the same as the command-mode xt 'set'  command,
 such             as "set bps 1200", "set cis on", and so forth, except that
 a string              <value>  must  be  enclosed  within  double-quotation


               set cis "on"               set  cfile "newfilename"
 set auto "on"               set bps 2400

         shell             Syntax: shell "<shell-command>"

             The shell command enclosed within the double-quotation marks is
              executed.  This is similar to the xt command-mode "!" command.
             Remember that if the  shell  command  contains double-quotation
 marks,             they must be escaped with backslashes.

         timeout             Syntax: timeout <number>

              If  <number> is  greater  than zero,  starts  a  timer   which
 will cause                 the MOST  DEEPLY  NESTED  script  to  exit  when
 <number> of MINUTES              expire.  If  <number> is  zero,  then  any
 pending timeout is cancelled.              If <number> is negative, nothing

             Expiration  of  the  specified timeout causes  the  most deeply
 nested               script  to  exit,  not to  terminate xt.  To cause the
 program to quit             if a timeout expires, use a subscript.


               'script1' contains:

                 call       "script2"                       if       expired
                 then                          quit                    endif
                 # more commands

               'script2' contains:

                 assign expired eq 1                 timeout 5      #  limit
 of 5 minutes                 while ! waitfor "login:" 30                 do
                     xmitbrk                   done                   assign
 expired eq 0                 exit

             When 'script2' exits, the numeric variable  'expired'  will  be
 set  to               1  if  'script2'  timed out, and will be 0 otherwise.
 'script1' can             act on this information accordingly.

         transmit             Syntax: transmit "string"

             Sends a string to the telnet connection.   Within  the  string,
 any              alphabetic character preceded by a caret (^) is translated
 to the             corresponding Control-character.


               transmit "date^M"

             sends the string "date" to the telnet connection, followed by a
             carriage-return character.

         true             Syntax: true

              Does  nothing,  but  always  evaluates  as   TRUE. Useful   in
 conditional             expressions. The opposite of 'false'.

         tty             Syntax: tty "on"                     tty "off"

             Ordinarily, during script execution, characters  received  from
 the                   telnet    connection   are   echoed   to   the user's
 terminal screen. This             happens only during 'waitfor' and  'type'
 execution, so  it  may  be  a               bit choppy. This echoing can be
 turned off with

               tty "off"

             and turned back on with

               tty "on"

             Note that "on" and "off" must be enclosed in quotation marks.

         type             Syntax: type "<filename>"

             Sends the specified ASCII file to the telnet  connection.  This
 is             the same as the xt terminal-mode "send ASCII file" escape.

         unassign             Syntax: unassign <variablename>

             Erases the specified user variable. The variable may be  either
              numeric or string type. The variable name must not be enclosed
 in             quotation marks, because variable names are considered to be
 xt             script keywords, and not literal strings.

         waitfor             Syntax: waitfor "string" <number>

             Scans input from the telnet connection for an occurrence of the
              specified  string,  which must be enclosed in quotation marks.
 The             scanning continues for the specified  <number>  of  SECONDS
 or until             the specified string is identified in the telnet input
 stream,             whichever comes first. This command evaluates  as  TRUE
 if  the  speci-               fied  string is  found,  and  as FALSE if the
 specified <number> of              SECONDS  elapses  and the  string  isn't
 found  within  that  time.  The             default time, if no <number> is
 specified, is roughly 30 seconds.

             String matching  is  performed  on  a  case-insensitive  basis.
 Within             the string, any alphabetic character preceded by a caret
 (^) is             translated to the corresponding Control-character.


               assign counter eq 1               while ! waitfor "login:" 15
               do                 xmitbrk; incr counter; if counter morethan
 5                   then                       quit                   endif

             If in a CompuServe Forum the "prompt character" has been set by
 the              user to be a backspace, this test will log off if the main
 prompt             is not seen in the next sixty seconds:

                if   !   waitfor   "forum   !^H"   60                   then
                 transmit "bye^M"; quit               endif

             If the 'cis' option has been set to "on", either  in the  .xtrc
             startup script, or by a direct 'set' command from command mode,
 or             with

               set cis "on"

             within a current script, and if during  'waitfor'  processing a
 CIS               B-Plus  protocol  file transfer request is received, then
 the B-Plus               protocol  transfer  is   performed,   the <number>
 argument   is   reset  to               its original  value, and  'waitfor'
 processing continues. This allows               automatic  B-Plus  protocol
 file transfers from within a script.

         while             Syntax: while <list1>; do <list2>; done

             Operates similarly to the 'if' command, except  that <list2> is
 exe-             cuted repeatedly so long as <list1> evaluates as TRUE. All
 the  con-               ditional  comparators  and  rules  for  comparisons
 that apply  for  the              'if' command also apply to 'while'. (Note
 that 'while' loops can  be               nested  within  'if'  commands and

    File Transfers          When  transferring  files using  CompuServe   B-
 Plus protocol,  the format of         the file is specified by the host. An
 ASCII mode will force xt to per-          form  TEXT  mode  translation;  a
 BINARY  mode  will  not  do  any  translation.          This means that, in
 either direction, a BINARY mode will send bytes  "as          is",  whereas
 in ASCII  mode, an incoming file will always be stripped of         end-of-
 line  carriage-returns,  while  an  ASCII  file   being uploaded   may   or
         may  not have  carriage-returns added after each newline, depending
 on         the "on" or "off" setting of the "cr" option.

         When using a CompuServe B-Plus download command, xt will  check  if
 the          file  name  you specify already exists on your system, and ask
 for an OK         to overwrite the file, or for an alternative name. In the
 CompuServe          case,  there  will  also  be  an  option  to "Resume" a
 download. If the CRC         checksum of the bytes that you already have in
 the  file matches          CompuServe's  checksum  on  the the same initial
 bytes in its version of         the file, file transfer will  proceed  from
 that  point  onwards.  This          saves  connect  time when a very large
 download has been interrupted dur-         ing a prior session.

         Script-driven file transfers using the CompuServe  B-Plus  protocol
 are          more  or less  built into the xt script language, since during
 'waitfor'         processing, a  file  transfer  request  from  the  telnet
 connection will         trigger a B-Plus transfer if the "cis" mode is set.
 The  difficulty   in           performing   such transfers   isn't in   the
 transfer itself, but rather in         the maneuvering required to get into
 position to transfer  the  correct          file,  and  is  something  that
 probably  only  experienced  script  writers          should  wrestle with.
 However, if we assume that in the midst of a         script, you've reached
 a point where you can issue a "download" command         to CompuServe, for
 instance a "Disposition"  prompt  during  a  File          Library "BROWSE"
 command,  and  you  want  to  download  the  present file,         which is
 "XCALL.C"  on  CompuServe,   and   "xcall.c" does   not   exist   in   your
         current working directory,  you'd  use  the  following  sequence of
 script         commands to do it:

           set cis on    #  can't do  auto file  B-Plus  transfer  otherwise
             transmit   "dow^M"               pause 2       # wait  for  CIS
 to display protocol menu           transmit "2^M"  # B-Plus is number 2  on
 that  menu            transmit "xcall.c^M" # "file name for your computer:"
           waitfor "Disposition"

         During the final "waitfor" processing, the CompuServe ENQ character
         will     be recognized    and    the    transfer    will    proceed
 automatically. Then             'waitfor'     will     continue waiting for
 the "Disposition"  prompt, after         which your script can proceed. The
 same sort of thing can be done with         file uploads, but  once  again,
 the    difficulty    isn't    with the    transfer,            but   rather
 with setting things up so that the transfer will  be          requested  at
 the correct place.

         A shell script, cisdownload provided  with  the  distribution,  can
         automatically retrieve a single file from a CompuServe library.

         For   XMODEM,   YMODEM,   and ZMODEM   transfers,    we    strongly
 recommend that          you  obtain  Chuck  Forsberg's excellent, shareware
 utility called "RZSZ",         which can handle XMODEM, XMODEM-1K,  YMODEM,
 and ZMODEM  transfers and         which can be used from within xt with the
 'pipe' command, or from com-         mand mode  with  the  '$'  command, or
 using the examples under the         bind_script command above.

    Debugging         There are three varieties of  debugging  in  xt.   The
 script  command  (set          debug  "on" or set debug "off") will control
 echoing of each line of a         script to the screen.

         If the program was compiled with LOG set to 1 in xt.h,  all  screen
 out-          put  will  be captured in a file called xt.log in the current
 directory,          providing  that  it  exists  before entering  xt,   and
 providing  that output          is  not being diverted to a current capture
 file. The xt.log file is         overwritten each time xt is run.

         If  you  forgot  to  turn  on  capturing,  if   the   program   was
 compiled with          LOG set to 1, and if xt.log exists, all is not lost:
 your session is         recorded in xt.log.

         Note that capturing to files  is turned  off  when exiting terminal
 mode,         and this includes running the built-in B+ protocol.

         Finally, in the xtb+.c module, there is a CIS_DEBUG definition line
         which is normally commented out. If this definition is uncommented,
         then a B+ transfer will record every byte in a file called xtb+log.
         This  file  is  created  if needed, in  the  current directory, and
 overwrit-         ten on each run of xt.

 Exit Codes         0  Successful, uneventful completion.

         1  Error in command-line arguments.

         2  Failure in forking to execute a command or run a shell.

         6  No environment variable TERM has been set.

         7  No entry for the current TERM setting in the terminfo database.

 Copyright         Xt and its source files and  sample  scripts  and  manual
 page are Copy-         right 1995, 1997 by Jean-Pierre Radley.

         Permission is granted to the public to use this code in any manner,
         without any  warranty,  implied  or  otherwise,  of  fitness  for a
 particular         purpose.

         By  virtue  of  a  restriction  previously  placed  upon  all  code
 derivative          from  xcomm,  the xt  code and associated files may not
 be sold by anyone         to anyone, nor incorporated into any product that
 is not also free.          It's OK to transfer them for free.

 Authors         This manual page was written by Fred Buck (1989) and  Jean-
 Pierre  Radley          (1990-1997).   Xt  itself is  the  product  of many
 synergistic wise minds.          See the README document.

 Version         This edition of the manual is for XT version 1.2 JPRadley 8
 July 1997.