Telnet客户端

开发平台：
Unix_Linux

xt.nroff：源码内容
							.ds ]V version 1.2 JPRadley 8 July 1997
.tm
.tm xt.nroff *(]V
.tm
.ta 4 4 4 4 4 4 4 4
.if n .po 0
.if n .nrLL 7.9i
.lln(LLu
.ltn(LLu
.TH XT 1
.SH Name
xt - communications program using telnet
.SH Syntax
.B xt
[
.RB [ -n hostname]
|
.RB [ -s script]
]
.SH Description
.B Xt
connects to a remote host using the telnet protocol. It can manage an
interactive session or be called from
.BR cron (C).
It has various means for transferring files between computers, and can be
partially or totally under the control of scripts.
.B Xt
starts up by reading the file 
.IR .xtrc ,
which is sought for in this order: in "XT_PATH", in the current directory,
in your
.I HOME
directory, or in a default directory defined at compile time. This startup
file may contain any of the valid
.I SET
commands described below. 
.B Xt
then displays the current settings, and presents an
.I <XT>
prompt, unless the fB-sfR option was used.
.SS fIOptionsfR
.TP 11
.BI -n hostname
Connect to the specified fIhostnamefR, which may be given as a Fully
Qualified Domain Name (e.g., who.excitement.com) or as an IP octet
(e.g., 198.207.210.2). If a telnet command issued from a shell prompt can
reach a site, then
.B xt
can reach it too.
.TP
.BI -s script
Execute the specified
.I script
after program startup.
.TP
The two options are mutually exclusive.
.SS fIEnvironmentfR
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.
.SS fICommand ModefR
When entering characters in command mode (that is, at the 
.I <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
.BR vi (C);
simply type ^V followed by the character to insert (backspace, delete,
carriage return, or newline).
The following commands are available at the
.I <XT>
command prompt:
.TS
tab(@);
l1B lw(54) .
c
cis@T{
Respond to an ENQ signal for a CIS B-Plus protocol transfer. This command is
used for both uploading and downloading from CompuServe.
T}
n fIhostname
nethost fIhostnamefR@T{
Establish a telnet connection to fIhostnamefR, then enter terminal mode.
T}
s fIfile
script fIfilefR@T{
Execute fIfilefR, which contains appropriate fBxtfR
script commands. Enters terminal mode when the script is complete.
T}
set fR[fIoptionsfR]@T{
Display or set the parameters used by fBxtfR. See below.
T}
t
term@Enter terminal mode.
x
q
exit
quit@Exit program. Return to invoking program/shell.
?
help@T{
Displays a brief summary of fBxtfR commands, the SET options, and
terminal-escape commands.
T}
.TE
.P
[Note: a compile-time option can disable the following three options to
prevent any access to shells or other programs outside of
.BR xt .]
.TS
tab(@);
l6B lw(56) .
! fIcommandfR@T{
Execute the specified fIcommandfR as a child process. If fIcommandfR is
omitted, execute a local interactive shell.
(A space is required between the fB!fR and the fIcommandfR.)
T}
!!@Re-execute the last shell command string. 
$ fIcommandfR@T{
Execute a shell fIcommandfR with stdin and stdout redi%rected to the
telnet socket. This effectively puts the computer into a "host" mode.
(A space is required between the fB$fR and the fIcommandfR.)
T}
.TE
.SS fIUsing the SET CommandfR
The
.I SET
command is used to display and set/reset
.BR xt 's
tunable parameters. Any of these commands may be placed in the
.I .xtrc
file which is read upon starting up
.BR xt .
Used alone,
.I SET
displays
.BR xt 's
current parameters.
The following parameters can be set (note that except in the case of
.IR name s,
these commands are case-fIinfRsensitive, and that there are alternative forms
of the commands shown on the XT help screen):
.TS
tab(@) ;
l1 lw(54) .
set auto on|off@T{
Sets the auto-capture feature. When entering terminal mode, capturing
commences without the necessity to manually request it.
T}
set cfile fInamefR@Set the fInamefR of the capture file.
set cis on|off@T{
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 protocol transfer. This parameter should be set "off" when not
connecting to CompuServe, as line noise may cause a bogus file transfer
request.
T}
set cr on|off@T{
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 implementation used by fBxtfR
will always strip end-of-line carriage-returns from incoming ASCII files.
T}
set dir fInamefR@Set the current working directory.
set menu on|off@T{
By default, a one-line menu is displayed above the fI<XT>fR prompt to
remind the user of options most frequently chosen at this point:
"[t]erminal mode [q]uit [s]cript [?]help".
Setting the option "off" turns off this display.
T}
set nl on|off@T{
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
"fBXCAPEfR fBFfR" 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.
T}
set xcape fIcharfR
set escape fIcharfR@T{
Set the fBXCAPEfR character (see below) to fIcharfR. This should be set to
some non-printing character (other than backspace, tab, newline, of course).
The character may be entered by depressing the Control key first
and then typing a letter, or by typing a caret (^) followed by a letter.
T}
.TE
.SS fITerminal ModefR
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.
fBXCAPEfR is a key that will, when typed in terminal mode, introduce an
.B xt
"escape" command. Don't confuse fBXCAPEfR with the <ESCAPE> key.
The default definition for fBXCAPEfR is ASCII 1, or Control-A. It can 
be redefined at run time with the "set escape fICfR" command (or it can be
redefined in the
.I .xtrc
startup script).
When the fBXCAPEfR 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 character is
sent to the telnet connection. Thus, to send the fBXCAPEfR character through
the telnet connection, it is necessary to press the key TWICE.
Thus the ESCAPE key itself would be a terrible choice for fBXCAPEfR, because
it is used so often by other programs: if you were logged into a remote system
and running, say, fBvifR, it would be a great annoyance to have to hit ESCAPE
twice to get it transmitted once.
The following keys (case fIinfRsensitive) are bound at startup time. Others
may be added through the binding commands available in 
.B xt
scripts.
.TS
tab(@) ;
l2 l2 l
l2B l2 l .
Command@Function@Description
XCAPE /@Help@Display the table of bound keys
XCAPE ?@Help@Display the table of bound keys
XCAPE f@fIFfRile@T{
Send a file through the telnet connection (ASCII transfer).
T}
XCAPE s@fISfRcript@fBXtfR will request the name of a script to execute.
XCAPE yfR@Capture fIYfRes@T{
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.
T}
XCAPE nfR@Capture fINfRo@T{
Close the capture file. If it wasn't open, a message of regret is printed.
T}
XCAPE xfR@efIXfRit@Exit terminal mode back to fI<XT>fR command mode.
XCAPE q@fIQfRuit@Quit fBxtfR altogether.
.TE
.SS fIScriptsfR
The
.B 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
.BR awk (C)
program does for those experienced in the C language: an
.B awk
script LOOKS like C, but it isn't, really; and in the same way, an
.B 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
.B xt
script language, but only as an analogy.
An
.B xt
script consists of lists of commands. Commands are set off from each other
within a list by either a newline ('\n') 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
.nf
  if counter morethan 5
  then
    transmit "bye^M"
    quit
  endif
or
  if counter morethan 5; then transmit "bye^M"; quit; endif
.fi
and the result will be the same either way. The newline and the semicolon
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 command terminator (in
other words, a quoted string cannot contain a newline).
Commands are composed of
.IR word s
separated by spaces or tab characters, and a
.I word
can be one of the following:
.TP 3
*
One of the
.B xt
script language keywords, which are listed below, with appropriate explanations.
.TP
*
A number, meaning a sequence consisting only of digits, with
an optional leading minus sign to indicate a negative number.
.TP
*
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 ('\"'); when the
string is interpreted, the backslash is disregarded and the double-quotation
mark is treated as part of the string. Mismatched quotation marks result in a
syntax error.
.TP
*
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.
.TP
*
The name of a shell environment variable, preceded by a dollar sign ('$'). The
.B 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
newline.
.TP
*
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.
.TP
*
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.
.TP
*
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 fIbind_functionfR,
fIbind_scriptfR, and fIbind_stringfR 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
.RI case- in sensitive
so that identifying the bound key as "65" or as "97" will always bind 
.I both 
"a" and "A" to the same command.
.P
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 characters, 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 variable. The value of any
user variable can be changed with another 'assign' command, and numeric
variables can be changed to string variables and vice-versa. Shell
environment variables cannot be changed within an
.B 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 changed.
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' keyword; up
to 5 scripts can be nested in this way at any single time.
With all this said, the following list of
.B 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'.
.SS fIScript Language CommandsfR
Note that all the commands are case-fIinfRsensitive!
.TP 4
.I 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 evaluating conditional
expressions.  The string must be terminated by a newline or carriage-return.
Example:
  echo -n "Continue (y/n)? "
  if affirm
  then
    continue
  else
    break
  endif
.TP
.I assign
Syntax: assign <varname> eq <number>
        assign <varname> eq "string"
        assign <varname> eq "string" ["string"|<varname>] ...
        assign <varname1> eq <varname2>
        assign <varname> eq <script-command>
Assigns to user variable <varname> the value following "eq"; if that value is a
number, then <varname> becomes a numeric user variable; if that value is a
string, then <varname> becomes a string user variable. If <varname> does not
already exist as a user variable, it is created. Variable space is allocated
dynamically, but running out of memory space for variables is unlikely. All
variables are global across scripts that run at the same time via the 'call'
keyword, and all variables vanish when a script, called directly from
.B 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. Successive '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'.
Examples:
  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
.TP
.I 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.
.TP
.I bind_function
Syntax: bind_function fIcodefR "function"
Bind the character identified by the number specified by fIcodefR to the
fBxtfR 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
Example:
  bind_function 26 "quitchr"
This binds Control-Z to quit the XT program.
.TP
.I bind_script
Syntax: bind_script fIcodefR "scriptname"
Bind the character identified by the number specified by fIcodefR 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.
Examples:
  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 fBXCAPEfR fB^RfR will ask for some file name(s), and start an
.B sz
command on the remote system, and an
.B 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 fBXCAPEfR fB^SfR will ask for some file name(s), and then launch
.B sz
on the current system.
.B Sz
will itself start an
.B rz
process on the remote system.
.TP
.I bind_string
Syntax: bind_string fIcodefR "string"
Bind the character identified by the number specified by fIcodefR 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.
Example:
  bind_string 49 "pwd^M"
This binds "1" to send the sequence to report your current directory
on a remote system.
.TP
.I 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
.B xt
script language 'break' does not take a numeric argument.
.TP
.I 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
.B xt
analogue of the Bourne shell "exec" command; all subscripts in
.B 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 cannot be
changed by any
.B xt
script.
.TP
.I 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 immediately upon entering, or returning to,
terminal mode. If not, then you must manually type "fBXCAPEfR fBYfR" to
start capturing when entering terminal mode.
.TP
.I 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.
.TP
.I debug
Syntax: debug "on"
        debug "off"
If the 'debug' option is on, then
.B xt
will make many parenthetical comments about what it's doing while it runs the
script. These comments 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 colleagues collected circa your
screen.
See, below, the fIDebuggingfR Section.
.TP
.I 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 results.
.TP
.I 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.
Examples:
  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.
.TP
.I exit
Syntax: exit
Terminates execution of the current script. If a script reaches its end, it
exits automatically, so 'exit' is useful mainly to terminate a script
prematurely.
.TP
.I false
Syntax: false
Same as the Unix 'false' command. Does nothing, but returns a FALSE status
value. Useful within conditional expressions.
Example:
  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.
.TP
.I 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 continues.
Examples:
  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"
.TP
.I 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 prejudice.
.TP
.I 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 'endif'.
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 commands.
The keywords 'then', 'else', and 'endif' (or 'fi') must be immediately preceded
by command separators, either a semicolon or a newline, just as is the case in
the Bourne shell.
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>
  "string"
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 testing 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 error.
  <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 specified 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.
Examples:
  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 variable 'brkvalue'.
.TP
.I incr
Syntax: incr <numeric-variable>
Increments the value of the specified numeric user variable by 1. The
opposite of 'decr'.
.TP
.I pause
Syntax: pause <number>
Suspends execution for the specified <number> of SECONDS. Identical to Unix
"sleep."
.TP
.I pipe
Syntax: pipe "<shell-command>"
The standard input and standard output of the specified shell command are
connected to the telnet connection, and the command is executed. This is the
equivalent of the command mode "$" command.
Examples:
  pipe "echo \"\177\""
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.
.TP
.I quit
Syntax: quit
Exits the script and terminates
.B xt
entirely. The user's terminal will be restored to the state it was in when
.B xt
was invoked.
.TP
.I 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 variable is discarded.
.TP
.I 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 'waitfor' processing. If no <number> is
specified, then all the characters received during the most recent 'waitfor'
command are examined, 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.
Example:
  if waitfor "string1" 20
  then
    echo "Received 'string1'."
  else
    if seen "string2"
    then
      echo "Received 'string2' instead."
    endif
  endif
.TP
.I set 
Syntax: set
.RB < xt -set-option>
<value>
This command is the same as the command-mode
.B 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 marks.
Examples:
  set cis "on"
  set cfile "newfilename"
  set auto "on"
  set bps 2400
.TP
.I shell
Syntax: shell "<shell-command>"
The shell command enclosed within the double-quotation marks is executed. This
is similar to the
.B xt
command-mode "!" command. Remember that if the shell command contains
double-quotation marks, they must be escaped with backslashes.
.TP
.I 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
happens.
Expiration of the specified timeout causes the most deeply nested script to
exit, not to terminate
.BR xt .
To cause the program to quit if a timeout expires, use a subscript.
Example:
  '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.
.TP
.I 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.
Example:
  transmit "date^M"
sends the string "date" to the telnet connection, followed by a carriage-return
character.
.TP
.I true
Syntax: true
Does nothing, but always evaluates as TRUE. Useful in conditional
expressions. The opposite of 'false'.
.TP
.I 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.
.TP
.I type
Syntax: type "<filename>"
Sends the specified ASCII file to the telnet connection. This is the same as
the
.B xt
terminal-mode "send ASCII file" escape.
.TP
.I 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
.B xt
script keywords, and not literal strings.
.TP
.I 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 specified 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-fIinfRsensitive basis.
Within the string, any alphabetic character preceded by a caret (^) is
translated to the corresponding Control-character.
Examples:
  assign counter eq 1
  while ! waitfor "login:" 15
  do
    xmitbrk; incr counter; if counter morethan 5
    then
      quit
    endif
  done
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
.I .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.
.TP
.I while
Syntax: while <list1>; do <list2>; done
Operates similarly to the 'if' command, except that <list2> is executed
repeatedly so long as <list1> evaluates as TRUE. All the conditional
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 vice-versa.)
.SS fIFile TransfersfR
When transferring files using CompuServe B-Plus protocol, the format of the
file is specified by the host. An ASCII mode will force
.B xt
to perform 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,
.B 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 during a prior session.
Script-driven file transfers using the CompuServe B-Plus protocol are more or
less built into the
.B 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,
.B 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
.B xt
with the 'pipe' command, or from command mode with the '$' command, or using
the examples under the 
.I bind_script
command above.
.SS fIDebuggingfR
There are three varieties of debugging in
.BR 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 output
will be captured in a file called
.I xt.log
in the current directory, providing that it exists before entering
.BR xt,
and providing that output is not being diverted to a current capture file. The
.I xt.log
file is overwritten each time
.B xt
is run. 
If you forgot to turn on capturing, if the program was compiled with
LOG set to 1, and if
.I xt.log
exists, all is not lost: your session is recorded in
.IR 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
.IR xtb+log .
This file is created if needed, in the current directory, and overwritten
on each run of
.BR xt .
.SH Exit Codes
.TS
tab(@) ;
c2B lw(60) .
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.
.TE
.SH Copyright
.B Xt
and its source files and sample scripts and manual page are Copyright 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
.BR 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.
.SH Authors
This manual page was written by Fred Buck (1989) and Jean-Pierre Radley
(1990-1997).
.B Xt
itself is the product of many synergistic wise minds. See the README document.
.SH Version
This edition of the manual is for XT *(]V.

						