xc.nro

支持X/YModem和cis_b+协议的串口通讯程序

            echo "Received 'string2' instead."
        endif
    endif
.TP
.I set\ 
Syntax: set
.RB < xc -set-option>
<value>

This command is the same as the command-mode
.B xc
\&'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 xc
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 xc .
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 modem. The string is sent with brief pauses between
characters, to accommodate modems that cannot accept rapid command input, and
within the string, any alphabetic character preceded by a caret (^) is
translated to the corresponding Control-character.

Example:

    transmit "ATDT 5551212^M"

sends the string "ATDT 5551212" to the modem, 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 modem port
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 modem port. This is the same as the
.B xc
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 xc
script keywords, and not literal strings.
.TP
.I waitfor
Syntax: waitfor "string" <number>

Scans input from the modem port 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 modem 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-\fIin\fRsensitive 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 .xc
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.)
.TP
.I xmitbrk
Syntax: xmitbrk

Sends a BREAK signal to the modem port.
.SS \fIFile Transfers\fR
.B Xc 
provides several internal file transfer protocols and supports
external protocols such as ZMODEM. This Linux version of
.B xc
can automatically recognize the trigger string for a ZMODEM download
and invoke rz to handle the transfer. You must use the 'set' command
to have this feature enabled (either use 'set' at the command line
or in your xc.init). By default these are pre-set at compile time.

       set zmcmd rz -y
       set autozm on

There are several options for the rz command. The above '-y' tells
rz to overwrite existing files. Familiarize yourself with the other
options by invoking rz or sz with the '-h' flag. To send files via
ZMODEM you must use the 
.B xc
command line. From terminal mode, ^A x
will bring up the 
.B xc
command prompt. From there you can enter you
ZMODEM command:

        $ sz foobar.tar.Z
                  
Note the '$'. This tells 
.B xc
to attach 'sz' to the current modem port
in use by 
.B xc.
Some more recent versions of rz/sz have this feature
crippled. The versions of rz/sz provided with this package work 
properly. The versions of rz/sz which open the port directly should
be avoided. By the way, rz can be invoked from the command line in
similar fashion, but DON'T specify the file name because it will be
in the header provided by the sender on the other end. Here are
some examples:

      $ rz      /* simple invocation */
      $ rz -y   /* overwrite existing file */
      $ rz -v   /* verbose */
      $ rz -yv  /* verbose and overwrite existing file */

When transferring files using the XMODEM protocol, the file mode is
specified in the upload/download command. The main modes for the
XMODEM transfers are 1K packets or 128 byte packets deternined by
the commands "ro" and "so" for the former, and "rx" and "sx" for
the latter. In actuallity, as implemented here, "rx" and "ro" are
identical as the packet size is automatically determined by the
sender. XMODEM will automatically receive the packet size speci-
fied by the sender, whereas the receiver always determines whether
CRC or CHECKSUM error detection is used. When available, 
.B xc
will always negotiate a CRC transfer.

Use of the send "so" and "sx" send commands require a bit more attention.
The "so" command will try to negotiate an 'old' YMODEM transfer 
of 1K byte packets. If the receiver is unable to receive 1K packets
.B xc
attempts to recover by falling back to 128 byte packets. If
the negotiation is successful, 
.B xc
will transfer 1K byte packets.
If at the end of the transfer there are less that 896 bytes in 
the final packet, 
.B xc
will automatically switch to 128 byte size
so as avoid padding the file with extraneous bytes. The "sx"
command will only send 128 byte packets as specified in the 
original XMODEM specifiacation. As with the receive commands, CRC
or CHECKSUM error detection is determined automatically and will
always revert to CRC if available. Note that for speed of transfer,
1-K byte packet size is better.

When transferring files using CompuServe B-Plus protocol, the format of the
file is specified by the host. An ASCII mode will force
.B xc
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 either the "%t" (take) command, an XMODEM receive command, or a
CompuServe B-Plus download command,
.B xc
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 xc
script language, since during 'waitfor' processing, a file transfer request
from the modem port 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 via scripts, there's no mechanism
built into the
.B xc
script language to use the built-in, 128-byte-packet XMODEM in
.BR xc .
Instead, 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 xc
with the 'pipe' command, or from command mode with the '$' command, or using
the examples under the 
.I bind_script
command above.
.SS \fIDebugging\fR
There are three varieties of debugging in
.BR xc .
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 DEBUG set to 1 in xc.h, all screen output
will be captured in a file called
.I debug.log
in the current directory, providing that it exists before entering
.BR xc,
and providing that output is not being diverted to a current capture file. The
.I debug.log
file is overwritten each time
.B xc
is run. 

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

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

Finally, in the xcb+.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 xc.log .
This file is created if needed, in the current directory, and overwritten
on each run of
.BR xc .
.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.

3@T{
No modem port specified on the command line, or contained in the environment
variable MODEM.
T}

4@Inability to create a LCK..file for the specified port.

5@Inability to open the specified port.

6@No environment variable TERM has been set.

7@No entry for the current TERM setting in /etc/termcap.

8@Problem caused by the 'ungetty' program.
.TE
.SH Copyright
.B Xc
and its source files and sample scripts and manual page are Copyright 1993 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 " xc
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, 1991, 1992, 1993).
.B Xc
itself is the product of many synergistic wise minds. See the README document.
.SH Version
This edition of the manual is for XC \*(]V.