xcomm 2.2, part 1 of 3 (docs)

[Gareth J. Barker]

After compiling the recently posted 'xcomm' source I merged the 'xcomm' 
documentation into a NROFF/TROFF file suitable for accessing with the 'man' 
command, and thought this might be of use to others.

(You will probably want to change the line about which port the modem
is on. Search for the string 'GJB' to find the line I'm talking about).

Gareth J. Barker,

INTERNET : ufnmr!gareth at BIKINI.CIS.UFL.EDU
UUCP     : ...gatech!uflorida!ufnmr!gareth

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of shell archive."
# Contents:  /usr/man/manl/xcomm.l
# Wrapped by gareth at ufnmr_1 on Fri Sep 30 14:55:01 1988
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'xcomm.l' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'xcomm.l'\"
else
echo shar: Extracting \"'xcomm.l'\" \(17103 characters\)
sed "s/^X//" >'xcomm.l' <<'END_OF_FILE'
X.TH XCOMM 1L "29 Oct 1988" Local LOCAL
X.SH NAME
Xxcomm \- X-modem communications program
X.SH SYNOPSIS
X.B xcomm
X[
X.B \-options
X]
X.SH OPTIONS
X.IP "-l device"
X(Line option) Specifies the path name to be used for the modem device.  
XThis overrides the value of the MODEM environment variable.  
X.LP
XNote that if the MODEM environment variable is not set, the -l Line option 
Xis mandatory.  
X.LP
XThe MODEM environment variable is used as the default path name to be used 
Xfor the modem device.  If this environment variable is not set, the -l 
XLine option is mandatory.  (/dev/cua0 is the correct line for the
Xmodem on "ufnmr" - GJB).
X.LP
XThe MODEM variable is usually set in a shell profile.  In the Bourne 
Xshell, this is placed in the .profile file of your home directory with 
Xstatements similar to that shown below:  
X.sp
X	export MODEM; set MODEM="/dev/tty00"
X.sp
X(assuming your modem device is /dev/tty00).  Using the C Shell, the 
Xfollowing statement may be place in .cshrc in your home directory:  
X.sp
X	setenv MODEM "/dev/tty00"
X.IP "-g file"
X(GO option) Specifies a script to be executed as soon as \fIxcomm\fP is finished 
Xinitializing.  
X.IP -t
X(Terminal option) Directs \fIxcomm\fP to jump directly into terminal mode after 
Xinitializing.  
X.LP
XEntering \fIxcomm\fP with an invalid option will display a summary of the valid
Xoptions supported.
X.SH DESCRIPTION
X.LP
X\fIXcomm\fP is a public domain terminal program that currently features
X.sp
Xo XMODEM and CIS "QuickB" file transfers with optional "text" translation
X.br
Xo Hayes Modem dialing directory with BAUD and BIT parameters
X.br
Xo Unix CU compatible PUT and TAKE commands
X.br
Xo Simple HOST communication mode
X.br
Xo Communication scripting with optional linkage from phone directory.
X.LP
X\fIXcomm\fP is offerred free of charge with NO requests for financial compensation
Xreqested (this is public domain, not shareware).  The source code may be
Xused or modified by anyone, but this code, or derivations of this code,
Xmay not be sold by anyone to anyone.
X.SH "COMMAND SUMMARY"
X.LP
X\fIXcomm\fP prompts for commands using the string:
X.sp
X    XCOMM>
X.sp
XWith version 2.2, \fIxcomm\fP supports the following commands:
X.IP c		
XInitiate CIS QuickB File Transfer.  This command is used for both uploading and
Xdownloading from CompuServe.
X.IP "g file"
XExecute the \fIxcomm\fP script file "file".  Returns to terminal mode when the
Xscript is complete.
X.IP "rb file"
X.IP "rt file"
XXMODEM receive (rb = binary mode; rt = text mode).  Receive the specified
Xfile from the remote system.
X.IP "sb file"
X.IP "st file"
XXMODEM transmit (sb = binary mode; st = text mode).  Transmit the specified
Xfile to the remote system.
X.IP set
XDisplay or set the transmission parameters used by the \fIxcomm\fP program.  Refer
Xto the SET section of this document.
X.IP t
XEnter terminal mode.  Refer to the TERMINAL section of this document.
X.IP x
XExit program.  Return to invoking program/shell.
X.IP "! <cmd>"
XExecute the specified command as a child process.  If <cmd> is ommitted,
Xexecute a local interactive shell.
X.IP "!!"
XRe-execute the last shell command string.
X.IP $
XExecute a shell command with stdin and stdout redirected to the modem port.
XThis effectively puts the computer into a "host" mode.
X.IP "%p file"
XTransmit a file (put) to a remote Unix system.  This command uses standard Unix
Xutilities on the other end.
X.IP "%t file"
XReceive a file (take) from a remote Unix system.  This command uses standard
XUnix utilities on the other end.
X.IP ?
XPrint a short \fIxcomm\fP command summary.
X.SH "FILE TRANSFERS - TEXT AND BINARY MODES"
X.LP
XWhen transferring files using the XMODEM protocol, the file mode is
Xspecified int the upload/download command.  A "Text" file transfer enables
Xspecial translation of the transmitted or received file to support CP/M and
XMS-DOS end of line characters.  When transmitting a file using text mode,
Xall newlines are converted to carriage-return, newline sequences.  When
Xreceiving a file using text mode, all carriage-return, newline sequences are
Xconverted to a single newline.  A "binary" file transfer transmits the file
X"as is" without any conversion.
X.LP
XWhen transferring files using CompuServe QuickB protocol, the format of the
Xfile is specified by the host.  An "Ascii" file will force \fIxcomm\fP to perform
Xtext-mode translation; a "binary" file will turn off any translation.
X.SH "THE SET COMMAND"
X.LP
XThe SET command is used to display and set/reset \fIxcomm\fP's tunable parameters.
XThe usage is shown below:
X.IP (1) set
XDisplay \fIxcomm\fP's current parameters.
X.IP (2)   
Xset 7bit
X.br
Xset 8bit
X.br
Xset crc
X.br
Xset chk
X.br
Xset term
X.br
Xset cmd
X.br
Xset cr
X.br
Xset nl
X.LP
XSet the indicated parameter:
X.RS +0.5i
X.IP 7bit	
XModem high-bit masking.  All characters received from the
Xmodem are masked so their values are between 0 and 127.
XThis is useful for remote systems that transmit parity
Xcharacters (the parity is ignored).
X.IP 8bit	
XDisable Modem high-bit masking.  All characters received
Xfrom the modem are displayed verbatim.
X.IP crc	
XSet XMODEM CRC protocol.  All transferred blocks use a
X16-bit block check, which is more reliable than the older
X"checksum" block check.
X.IP chk	
XSet XMODEM Checksum protocol.  All transferred blocks use an
X8-bit block check, which is not as reliable as the CRC
Xblock check, but is compatible with older programs using
XXMODEM.
X.IP term	
XSet auto-jumpback to terminal mode after all file transfers.
X.IP cr	
XSet newline translation mode (in terminal mode, all newlines
Xwill be translated to carriage returns).
X.IP nl	
XSet carriage return mode (in terminal mode, all newlines are
Xsent as newlines; carriage returns are sent as carriage
Xreturns.)
X.LP
XThe above parameters are paired; that is, the "crc" parameter is
Xnegated by the "chk" parameter.
X.LP
XXMODEM Transfers:  When using "crc" protocol on a transmit, the \fIxcomm\fP
Xprogram will fall back to "checksum" block checks if the receiving
Xprogram does not support the special "crc" handshake.
X.RS -0.5i
X.IP (3)   
Xset cis   on|off
X.br
Xset mung  on|off
X.br
Xset purge on|off
X.br
Xset xoff  on|off
X.br
Xset baud  <value>
X.br
Xset cfile name
X.br
Xset pfile name
X.RS +0.5i
X.IP cis	
XSet CompuServe <ENQ> file transfer requests.  An "on" value
Xspecifies that when in terminal mode, an <ENQ> character
Xwill perform an automatic CIS QuickB protocol transfer.
XThis parameter should be set "off" when not connected to
XCompuServe, as phone line noise may cause a bogus file
Xtransfer request.
X.IP mung	
XSet file overwrite flag.  If "on", files may be overwritten
Xwhen receiving data files.  If "off", files will not be
Xoverwritten (will cause an error message to be displayed).
X.IP purge	
XSet Bad Telephone Line Purge mode.  If "on", removes
Xspurious characters received through the phone line due to
Xnoise before listening for an acknowledgement.  This
Xincreases the amount of time spent transmitting each block,
Xbut can improve throughput overall by reducing the number of
Xblock retransmissions.
X.IP xoff	
XSet XON/XOFF flow control flag.  If "on", the program will
Xhonor the XOFF control character and wait until an XON
Xcharacter is received before transmitting any more
Xinformation.  If "off", the program will ignore XOFF/XON
Xrequests.
X.IP baud	
XSet the desired baud rate.  Supported baud rates are 300,
X1200, 2400, 4800, and 9600 baud.
X.IP cfile	
XSet the name of the terminal mode capture file to "name".
X.IP pfile	
XSet the name of the terminal mode phonelist file to "name".
X.RS -0.5i
X.LP
XA sample "set" command status display is shown below:
X.sp
X.RS +0.5i
XModem port is '/dev/tty00'.
X.br
XSpeed is 1200 baud.
X.br
XSeven-bit communication mask enabled.
X.br
XXMODEM CRC protocol enabled.
X.br
XExtra bad telephone line purging enabled.
X.br
XCapture save file is 'capture.log'.
X.br
XPhone number file is '.phonelist'.
X.br
XXON/XOFF Flow control is OFF.
X.br
XCIS <ENQ> Auto Download is ON.
X.br
XNewline translation mode is active.
X.sp
X.RS -0.5i
X.SH "TERMINAL MODE"
X.LP
XIn terminal mode, all characters typed at the keyboard are sent to the
Xmodem; all characters received from the modem are displayed on the local
Xterminal screen.
X.LP
XNewline characters (0x0A) are translated to carriage returns (0x0D) when
XNewline mode is active.
X.LP
XWhen the ESC key is typed in terminal mode, the program will examine the
Xnext key pressed.  If it is a special command function, that function will
Xbe performed; otherwise, the second character is sent to the modem.  Thus,
Xto send an ESC character through the modem, it is necessary to press the
Xkey TWICE.
X.LP
XSupported ESC commands:
X.IP "ESC f	send File"
XSend a file through the modem (ascii transfer).  An
Xoption is available for waiting after each line is
Xsent to avoid overrunning the remote systems input
Xbuffer.
X.IP "ESC g	script (GO)"
XExecute a script file.
X.IP "ESC h	Hangup"
XDisconnect from the remote system.
X.IP "ESC t	Toggle capture"
XToggle capture file - If the file is not open, it is
Xopened in APPEND mode (text receive accumulates at
Xthe end of the file).  If the file is already open,
Xit is closed, instead.
X.IP "ESC x	eXit"
XExit terminal mode back to \fIxcomm\fP command mode.
X.SH "PHONELIST"
XThe .phonelist must exist with the file name ".phonelist" either in the
Xcurrent directory, or your home directory as defined by the $HOME
Xenvironment variable.  The name of the phonelist file can be changed
Xusing the SET PFILE command.
X.LP
XThe .phonelist file is ASCII text (lines of text separated by newlines).
XIt can be created and maintained using emacs, vi, or even ed.
XThe first field of data in each line (after any whitespace and up to the
Xnext occurance of whitespace) is assumed to be a phone number in a valid
Xformat for the modem being dialed.
XAny text may follow the phone number.
X.LP
XSpecial strings within each line:
X.br
XBITS=x	(x=7|8) - Set the terminal mode mask to 7/8 bits.
X.b
XrBAUD=nnnn	(n=300|1200|2400|4800|9600) - Set the baud rate to the
Xspecified value
X.br
XSCRIPT=file	Immediately after sending the autodial string, execute the
Xscript file specified. (Note that the specified filename is
XCASE SENSITIVE!)
X.sp
XA sample entry is shown below:
X.sp
X687-0374	CompuServe		BITS=7	BAUD=1200, SCRIPT=cis.cmd
X.sp
XThe above entry indicates that the number to be dialed is 687-0374; the
Xbit mask is to be set to seven bits (ignore high bits), the baud rate is
Xto be set to 1200 baud, and commands are to be taken from the file
X"compusrv.cmd" in either the current or home directory.
X.LP
XA sample .phonelist file is included in the \fIxcomm\fP source code
Xdistribution.
X.SH "XCOMM SCRIPT LANGUAGE"
X.LP
XScript files can automate some tedious tasks such as logging into a
Xsystem.  A script file is an Ascii text file and may be entered or
Xedited using any standard Unix text editor.
X.LP
XThe script file is read line by line.  Empty lines (consisting of white
Xspace only) are ignored.  Comments are lines whose first non-space
Xcharacter is a pound sign (#).
X.LP
XThe script processor reads each script line, ignoring leading white
Xspace, into "words".  A word is defined as either:
X.sp
X- A sequence of characters delimited by white space; or
X.br
X- A sequence of characters enclosed in single or double quotes.
X.sp
X.LP
XThe first word of a script file is considered the "command word."
XIf the last character of the command word is a colon (:), the line is
Xconsidered to be a LABEL (the object of a GOTO statement).  Otherwise,
Xit is assumed to be a script command and is interpreted as such.
XCommand words are case insensative.
X.LP
XSome commands take one or more arguments.  Each argument is parsed as a
Xsingle word as defined above.  If blanks are required in an argument,
Xthe argument MUST be quoted using single or double quotes.
X.LP
XEnclosed in the \fIxcomm\fP distribution is the file "compusrv.cmd".  This is
Xan example script file (No, that is not really my user ID or my
Xpassword in that file!), and shows the use of most of the available
Xscript commands.  The script commands are self explanatory for the most
Xpart.
X.SH "STARTUP SCRIPTS"
X.LP
XWhen \fIxcomm\fP is started up, it looks for the file ".xcomm" in the current
Xor $HOME directory.  If it is found, it is executed.  This is useful for
Xsetting your "basic" parameters without having to recompile \fIxcomm\fP.  For
Xexample, your startup file may turn CIS <ENQ> mode off, set your baud
Xrate to 9600, and set 7BIT translation.
X.SH "SCRIPT COMMAND LIST"
X.IP "CAPTURE ON|OFF"
XThe command CAPTURE ON will open the capture command; all characters
Xreceived during WAITFOR processing will be appended to the capture file.
XThe command CAPTURE OFF will close the capture file.
X.br
XThis setting does NOT currently extend to terminal mode.  This may be
Xoffered in a later release (probably through the SET command).
X.IP "DIAL <number>"
XDial the specified number.  \fIxcomm\fP supports generic "Hayes" compatible
Xmodems for dialing.  Note that this command requires an actual phone
Xnumber; the phonebook is not used for this function.
X.IP "ECHO ON|OFF"
XIf the argument to the ECHO command is ON, all subsequent command lines
Xthat are processed will be displayed on the local screen.  The exception
Xto this is lines containing a TRANSMIT command.  These lines will just
Xprint "TRANSMIT ...", so that passwords, etc. can be protected.
X.br
XIf the argument to the ECHO command is OFF, scripts will execute
Xquietly (this is the default setting).
X.IP EXIT
XTerminate the script file prior to the end of file.  Returns to terminal
Xmode.
X.IP "GOTO <label>"
XGo to the specified label in the script file and continue execution from
Xthat point.  The label may either precede or follow the actual GOTO
Xstatement.
X.IP "IF <condition>"
X.IP "<statements>"
X.IP "[ ELSE"
X.IP "statements ]"
X.IP "ENDIf"
XConditionally execute statements based on specified condition.  \fIXcomm\fP
Xsupports the following conditions:
X.sp
XWAITFOR		TRUE if the last WAITFOR command was successful
XLINKED		TRUE if this script was executed from the phonebook
X.sp
XConditions may be negated using the prefix NOT or the character "!":
X.sp
X!WAITFOR		TRUE If the last WAITFOR command timed out
XNOT WAITFOR		Same as !WAITFOR above
X.sp
XThe ELSE and ENDIF keywords must appear on their own lines.  IF
Xstatements may not be nested.
X.IP "PAUSE <time>"
XSuspend execution of the script for the specified number of seconds.
XThis is usually used for timing considerations; for example, waiting a
Xcouple of seconds after receiving the CONNECT message and typing ^C to
XCompuServe.
X.IP "QUIT"
XTerminate the script AND the \fIxcomm\fP program (return to the shell).
X.IP "REDIAL"
XRedial the last number dialed using the DIAL command OR the phonebook.
X.IP "SET <parameter> <value>"
XSets the specified parameter to the specified value.  The SET parser
Xused in command mode is used, and the parameters/values are identical.
X.br
XDuring script processing, internal status messages are NOT displayed on
Xthe local terminal (eg, SET 7BIT ON in a script file does not display
Xthe new value on the terminal).  This may be changed in the future
X(probably tied to the ECHO setting).
X.br
XDuring script processing, specifying SET alone is an ERROR... there is
Xno way currently display the current status of the SET-able parameters
Xduring script processing.
X.IP "TRANSMIT <text>"
XTransmit the specified text to the remote.  The text argument should be
Xquoted (using single or double quotes) if there are spaces to be
Xtransmitted.  The text is transmitted AS IS (no case conversions are
Xperformed).
X.br
XPrefix characters:
X.sp
X^	Control character prefix - The next character is made into a
Xcontrol character.  
XFor example:  ^M = RETURN (0x0D); ^J = NEWLINE (0x0A).
X.sp
X\	Quote prefix - The next character is transmitted verbatim.  For
Xexample, \^ would transmit a literal ^.
X.IP "TTY ON|OFF"
XThe TTY command specifies whether or not characters received from the
Xmodem will be displayed on the local terminal.  Since the only time that
Xthe script processor looks at the receive queue is during WAITFOR
Xprocessing, the displays may look a bit erratic.
X.br
XUse the TTY OFF command to disable local display of received characters
Xduring script processing.
X.IP "WAITFOR <text> [timeout]"
XWait for the specified text to appear from the modem.  The text argument
Xshould be quoted (using single or double quotes) if there are spaces to
Xbe transmitted.
X.br
XSpecial characters are interpreted the same as for TRANSMIT.
X.br
XIf the timeout argument is specified, \fIxcomm\fP will wait that number of
Xseconds for the string to appear.  If no timeout is given, \fIxcomm\fP
Xdefaults to 30 seconds.
X.br
XDuring WAITFOR processing, characters received (up to and including the
Xlast character found in the text or in the timeout) can be captured to a
Xdisk file (if CAPTURE ON was specified), and/or displayed to the screen
X(if TTY ON was specified).
X.SH "BUGS"
X.LP
X\fIXcomm\fP does not support or respect uucp/tip LCK lock files.  
XCheck that the modem is free before trying to use \fIxcomm\fP.
X.SH "AUTHOR"
X.LP
XMy electronic addresses are:
X.sp
XCompu$erve:		[72236,3516]   (UNIXFORUM)
X.br
XDelphi:			larryg
X.br
XBix:			lar3ry
X.br
XAndover CNode:		larry gensch
X(This is a FIDO BBS dedicated to C Language
Xprogramming - phone number (617) 470-2548)
END_OF_FILE
if test 17103 -ne `wc -c <'/usr/man/manl/xcomm.l'`; then
    echo shar: \"'/usr/man/manl/xcomm.l'\" unpacked with wrong size!
fi
# end of '/usr/man/manl/xcomm.l'
fi
echo shar: End of shell archive.
exit 0