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
scripts.
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.,
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 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
below.
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
commands.
[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
command.)
!! 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
scripts.
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
execute.
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
or
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
error.
* 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
command.
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
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' 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-
insensitive!
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.
Example:
echo -n "Continue (y/n)? " if affirm
then continue else break
endif
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
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'.
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
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
Example:
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.
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 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.
Example:
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
argument.
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
"off"
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
results.
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.
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.
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.
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"
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.
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
immedi- ately preceded by command separators, either a
semicolon or a new- line, 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 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
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 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.
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 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.
Examples:
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.
Example:
if waitfor "string1" 20 then
echo "Received 'string1'." else
if seen "string2" then
echo "Received 'string2' instead." endif
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
marks.
Examples:
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
happens.
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.
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.
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.
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.
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 .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
vice-versa.)
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.
