C-KERMIT (Part 2 of 10)

[gregg at okstate.UUCP]

echo x - ckermi.mss part 2
sed '1,$s/^X//' <<\!FUNKY!STUFF! >> ckermi.mss
Xlocal Kermit and issue a 'receive' command.  Normally 5 seconds.
X
Xduplex {full, half}@\For use during 'connect'.  Specifies which side is doing
Xthe echoing; 'full' means the other side, 'half' means C-Kermit must echo
Xtypein itself.
X
Xend-of-packet @i(cc)@\Specifies the control character needed by the other
XKermit to recognize the end of a packet.  C-Kermit sends this character at the
Xend of each packet.  Normally 13 (carriage return), which most Kermit
Ximplementations require.  Other Kermits require no terminator at all, still
Xothers may require a different terminator, like linefeed (10).
X
Xescape-character @i(cc)@\For use during 'connect' to get C-Kermit's attention.
XThe escape character acts as a prefix to an 'escape command', for instance to
Xclose the connection and return to C-Kermit or Unix command level.
XThe normal escape character is Control-Backslash (28).
XThe escape character is also used in System III/V implementations,
Xto prefix interrupt commands during file transfers.
X
Xfile {display, names, type, warning}@\
XEstablish various file-related parameters:
X at begin(description,leftmargin +4,indent -4)
Xdisplay {on, off}@\Normally 'on'; when in local mode, display progress of file
Xtransfers on the screen (stdout), and listen to the keyboard (stdin)
Xfor interruptions.  If off (-q on command line) none of this is
Xdone, and the file transfer may proceed in the background oblivious
Xto any other work concurrently done at the console terminal.
X
Xnames {converted, literal}@\
XNormally converted, which mean that outbound filenames have path
Xspecifications stripped, lowercase letters raised to upper,
Xtildes and extra periods changed to X's, and an X inserted in
Xfront of any name that starts with period.  Incoming files have
Xuppercase letters lowered.  Literal means that none of these
Xconversions are done; therefore, any directory path appearing in a
Xreceived file specification must exist and be write-accessible.
XWhen literal naming is being used, the sender should not use path
Xnames in the file specification unless the same path exists on the
Xtarget system and is writable.
X
Xtype {binary, text}@\Normally text, which means that conversion is done between
XUnix newline characters and the carriage-@|return/@|linefeed sequences
Xrequired by the canonical Kermit file transmission format, and in
Xcommon use on non-@|Unix systems.  Binary means to transmit file
Xcontents without conversion.  Binary ('@q(-i)' in command line notation)
Xis necessary for binary files, and desirable in all Unix-@|to-@|Unix
Xtransactions to cut down on overhead.
X
Xwarning {on, off}@\Normally off, which means that incoming files will silently
Xoverwrite existing files of the same name.  When on ('@q(-w)' on command line)
XKermit will check if an arriving file would overwrite an existing file; if so,
Xit will construct a new name for the arriving file, of the form @q(foo~)@i(n),
Xwhere foo is the name they share and @i(n) is a "generation number"; if @i(foo)
Xexists, then the new file will be called @q(foo~1).  If @q(foo) and @q(foo~1)
Xexist, the new file will be @q(foo~2), and so on.
X at end(description)
X
Xflow-control {none, xon/xoff}@\Normally xon/xoff for full duplex flow control.
XShould be set to 'none' if the other system cannot do xon/xoff flow control.
X
Xhandshake {xon, xoff, cr, lf, bell, esc, none}@\
XNormally none.  Otherwise, half-duplex communication line turnaround
Xhandshaking is done, which means Unix Kermit will not reply to a packet
Xuntil it has received the indicated handshake character or has timed out
Xwaiting for it.
X
Xline [device-name]@\
XThe device name for the communication line to be used for file transfer
Xand terminal connection, e.g. @q(/dev/ttyi3).  If you specify a device name,
XKermit will be in local mode, and you should remember to issue any other
Xnecessary 'set' commands, such as 'set speed'.  If you omit the device
Xname, Kermit will revert to its default mode of operation.
X
Xmodem-dialer {direct, hayes, ventel}@\ The type of modem dialer on the
Xcommunication line.  "Direct" indicates either there is no dialout modem, or
Xthat if the line requires carrier detection to open, then 'set line' will hang
Xwaiting for an incoming call.  "Hayes" and "Ventel" indicate that the
Xsubsequent 'set line' (or the -l argument) will prepare for a subsequent 'dial'
Xcommand for Hayes and Ventel dialers, respectively.
X
Xpacket-length @i(n)@\Specify the maximum packet length to use.  Normally 90.
XShorter packet lengths can be useful on noisy lines, or with systems or front
Xends or networks that have small buffers.  The shorter the packet, the higher
Xthe overhead, but the lower the chance of a packet being corrupted by noise,
Xand the less time to retransmit corrupted packets.
X
Xpad-character @i(cc)@\C-Kermit normally does not need to have incoming packets
Xpreceded with pad characters.  This command allows C-Kermit to request the
Xother Kermit to use cc as a pad character.  Default cc is NUL, ASCII 0.
X
Xpadding @i(n)@\How many pad characters to ask for, normally 0.
X
Xparity {even, odd, mark, space, none}@\Specify character parity for use in
Xpackets and terminal connection, normally none.  If other than none, C-Kermit
Xwill seek to use the 8th-bit prefixing mechanism for transferring 8-bit binary
Xdata, which can be used successfully only if the other Kermit agrees; if not,
X8-bit binary data cannot be successfully transferred.
X
Xprompt [string]@\The given string will be substituted for "@q(C-Kermit)>" as
Xthis program's prompt.  If the string is omitted, the prompt will revert to
X"@q(C-Kermit>)".
X
Xspeed {0, 110, 150, 300, 600, 1200, 1800, 2400, 4800, 9600}@\The baud rate for
Xthe external communication line.  This command cannot be used to change the
Xspeed of your own console terminal.  Many Unix systems are set up in such a way
Xthat you must give this command after a 'set line' command before you can use
Xthe line.
X
Xstart-of-packet @i(cc)@\The Kermit packet prefix is Control-A (1).  The only
Xreasons it should ever be changed would be: Some piece of equipment somewhere
Xbetween the two Kermit programs will not pass through a Control-A; or, some
Xpiece of of equipment similarly placed is echoing its input.  In the latter
Xcase, the recipient of such an echo can change the packet prefix for outbound
Xpackets to be different from that of arriving packets, so that the echoed
Xpackets will be ignored.  The opposite Kermit must also be told to change the
Xprefix for its inbound packets.  Unix Kermit presently can be told to change
Xonly its outbound packet prefix.
X
Xtimeout @i(n)@\Normally, each Kermit partner sets its packet timeout interval
Xbased on what the opposite Kermit requests.  This command allows you to
Xoverride the normal procedure and specify a timeout interval.  If you specify
X0, then no timeouts will occur, and Unix Kermit will wait forever for expected
Xpackets to arrive.
X at end(description)
X
X at heading(The 'show' Command:)
X
XSyntax: @q<show {parameters, versions}>
X
XThe show command displays the values of all the 'set' parameters described
Xabove.  If you type 'show versions', then C-Kermit will display the version
Xnumbers and dates of all its internal modules.  You should use the 'show
Xversions' command to ascertain the vintage of your Kermit program before
Xreporting problems to Kermit maintainers.
X
X at heading(The 'statistics' Command:)
X
XThe statistics command displays information about the most recent Kermit
Xprotocol transaction, including file and communication line i/o, as well
Xas what encoding options were in effect (such as 8th-bit prefixing,
Xrepeat-@|count compression).
X
X at heading(The 'take' and 'echo' Commands:)
X
XSyntax: @q<take >@i<fn1>
X
XThe 'take' command instructs C-Kermit to execute commands from the named
Xfile.  The file may contain any interactive C-Kermit commands, including
X'take'; command files may be nested to any reasonable depth.  The 'echo'
Xcommand may be used within command files to issue greetings, announce
Xprogress, etc.
X
XCommand files are in exactly the same syntax as interactive commands.
XNote that this implies that if you want to include special characters like
Xquestion mark or backslash that you would have to quote with backslash when
Xtyping interactive commands, you must quote these characters the same way
Xin command files.
X
XCommand files may be used in lieu of command macros, which have not been
Ximplemented in this version of C-Kermit.  For instance, if you commonly
Xconnect to a system called 'B' that is connected to ttyh7 at 4800 baud,
Xyou could create a file called @q(b) containing the commands
X at begin(example)
Xset line /dev/ttyh7
Xset speed 4800
Xecho Connecting to System B...
Xconnect
X at end(example)
Xand then simply type 'take b' (or 't b' since no other commands begin with
Xthe letter 't') whenever you wished to connect to system B.
X
XFor connecting to IBM mainframes, a number of 'set' commands are required;
Xthese, too, are conveniently collected into a 'take' file like this one:
X at begin(example)
Xset speed 1200
Xset parity mark
Xset handshake xon
Xset flow-control none
Xset duplex half
X at end(example)
X
XAn implicit 'take' command is executed upon your @q(.kermrc) file upon
XC-Kermit's initial entry into interactive dialog.  The @q(.kermrc) file should
Xcontain 'set' or other commands you want to be in effect at all times.
XFor instance, you might want override the default action when incoming files
Xhave the same names as existing files -- in that case, put the command
X at example(set file warning on)
Xin your @q(.kermrc) file.
X
XCommands executed from take files are not echoed at the terminal.  If you
Xwant to see the commands as well as their output, you could feed the
Xcommand file to C-Kermit via redirected stdin, as in
X at example('kermit < cmdfile')
XErrors encountered during execution of take files (such as failure to complete
Xdial or script operations) cause termination of the current take file, popping
Xto the take file that invoked it, or to interactive level.  When kermit is
Xexecuted in the background, errors during execution of a take file are fatal.
X
X at heading(The 'connect' Command:)
X
XThe connect command links your terminal to another computer as if it were
Xa local terminal to that computer, through the device specified in the most
Xrecent 'set line' command, or through the default device if your system
Xis a PC or workstation.  All characters you type at your keyboard
Xare sent out the communication line, all characters arriving at the
Xcommunication port are displayed on your screen.  Current settings of speed,
Xparity, duplex, and flow-@|control are honored.  If you have issued a 'log
Xsession' command, everything you see on your screen will also be recorded
Xto your session log.  This provides a way to "capture" files from systems
Xthat don't have Kermit programs available.
X
XTo get back to your own system, you must type the escape character, which is
XControl-@|Backslash (@q[^\]) unless you have changed it with the 'set escape'
Xcommand, followed by a single-@|character command, such as 'c' for "close
Xconnection".  Single-@|character commands include:
X at begin(description,leftmargin +8,indent -6,spread 0.4)
Xc@\Close the connection
X
Xb@\Send a BREAK signal
X
X0@\(zero) send a null
X
Xs@\Give a status report about the connection
X
X at q[^\]@\Send Control-Backslash itself (whatever you have defined the
Xescape character to be, typed twice in a row sends one copy of it).
X at end(description)
XLowercase and control equivalents for these letters are also accepted.  A
Xspace typed after the escape character is ignored.  Any other character will
Xproduce a beep.
X
XThe connect command simply displays incoming characters on the screen.  It is
Xassumed any screen control sequences sent by the host will be handled by
Xthe firmware in your terminal or PC.  If terminal emulation is desired,
Xthen the connect command can invoked from the Unix command line (@q(-c) or
X at q(-n)), piped through a terminal emulation filter, e.g.
X at example(kermit -l /dev/acu -b 1200 -c | tek)
X'c' is an acceptable non-unique abbreviation for 'connect'.
X
X at heading(The 'dial' command:)
X
XSyntax: @q(dial )@i(telephone-number-string)
X
XThis command controls dialout modems.  The telephone-@|number-@|string may
Xcontain modem-@|dialer commands, such as comma for Hayes pause, or '@q(&)'
Xfor Ventel dialtone wait and '@q(%)' for Ventel pause.
X
XBecause modem dialers have strict requirements to override the carrier-@|detect
Xsignal most Unix implementations expect, the sequence for dialing is more rigid
Xthan with the rest of kermit's features.
X
XExample one:
X at begin(example)
X at ux<kermit -l /dev/cul0 -b 1200>
XC-Kermit>@ux<set modem-dialer hayes>	@i(hint: abbreviate) set m h
XC-Kermit>@ux<dial 9,5551212>
XConnected!
XC-Kermit>@u<connect>			@i(hint: abbreviate) c
X at i(logon, request remote server, etc.)
XC-Kermit> ...
XC-Kermit>@u<quit>			@i(hint: abbreviate) q
X at end(example)
Xthis disconnects modem, and unlocks line.
X
XExample two:
X at begin(example)
X at u(kermit)
XC-Kermit>@ux(set modem-dialer ventel)
XC-Kermit>@ux(set line /dev/cul0)
XC-Kermit>@ux(dial 9&5551212%)
XConnected!
XC-Kermit> ...
X at end(example)
XExample three:
X at begin(example)
Xkermit
XC-Kermit>@ux(take my-dial-procedure)
XConnected!
X
X at i(file my-dial-procedure):
Xset modem hayes
Xset line /dev/tty99
Xdial 5551212
Xconnect
X at end(example)
XFor Hayes dialers, two important switch settings are #1 and #6.  #1
Xshould be up so that the DTR is only asserted when the line is 'open'.
X#6 should be up so carrier-@|detect functions properly.  Switches #2
X(English versus digit result codes) and #4 (Hayes echoes modem commands)
Xmay be in either position.
X
X at heading(The 'script' Command:)
X
XSyntax: @q(script )@i(expect send [expect send] . . .)
X
X"expect" has the syntax: @i(expect[-send-expect[-send-expect[...]]])
X
XThis command facilitates logging into a remote system and/or invoking
Xprograms or other facilities after login on a remote system.
X
XThis login script facility operates in a manner similar to that commonly
Xused by the Unix uucp System's "@q(L.sys)" file entries.  A login script 
Xis a sequence of the form:
X at example(@i<expect send [expect send] . . .>)
Xwhere @i(expect) is a prompt or message to be issued by the remote site, and
X at i(send) is the string (names, numbers, etc) to return.  The send may also be
Xthe keyword EOT, to send Control-D, or BREAK, to send a break signal.  Letters
Xin send may be prefixed by '@q[~]' to send special characters.  These are:
X at begin(description,leftmargin +8,indent -4,spread 0)
X at q(~b)@\backspace
X
X at q(~s)@\space
X
X at q(~q)@\'@q[?]'(trapped by Kermit's command interpreter)
X
X at q(~n)@\linefeed
X
X at q(~r)@\carriage return
X
X at q(~t)@\tab
X
X at q(~')@\single quote
X
X at q(~~)@\tilde
X
X at q(~")@\double quote
X
X at q(~c)@\don't append a carriage return
X
X at q(~)@i(o[o[o]])@\an octal character
X at end(description)
XAs with some uucp systems, sent strings are followed by @q(~r) unless they have
Xa @q(~c).
X
XOnly the last 7 characters in each expect are matched.  A null @i(expect),
Xe.g. @q(~0) or two adjacent dashes, causes a short delay before proceeding
Xto the next send sequence.  A null expect always succeeds.
X
XAs with uucp, if the expect string does not arrive, the script attempt
Xfails.  If you expect that a sequence might not arrive, as with uucp, 
Xconditional sequences may be expressed in the form:
X at example(@i<-send-expect[-send-expect[...]]>)
Xwhere dashed sequences are followed as long as previous expects fail.
X
X at i(Expect/send) transactions can be easily be debugged by logging
Xtransactions.  This records all exchanges, both expected and actual.
X
XNote that '@q[\]' characters in login scripts, as in any other C-Kermit
Xinteractive commands, must be doubled up.
X
XExample one:
X
XUsing a modem, dial a unix host site.  Expect "login" (...gin), and if it
Xdoesn't come, simply send a null string with a @q(~r).  (Some Unixes
Xrequire either an EOT or a BREAK instead of the null sequence, depending
Xon the particular site's "logger" program.)  After providing user id
Xand password, respond "x" to a question-mark prompt, expect the Bourne
Xshell "@q($)" prompt (and send return if it doesn't arrive).  Then cd to
Xdirectory kermit, and run the program called "wermit", entering the
Xinteractive connect state after wermit is loaded.
X at begin(example)
Xset modem-dialer ventel
Xset line /dev/tty77
Xset baud 1200
Xdial 9&5551212
Xscript gin:--gin:--gin: smith ssword: mysecret ~q x $--$ 
X	cd~skermit $ wermit
Xconnect
X at end(example)
X
XExample two:
X
X at index(TELENET)
XUsing a modem, dial the Telenet network.  This network expects three
Xreturns with slight delays between them.  These are sent following
Xnull expects.  The single return is here sent as a null string, with
Xa return appended by default.  Four returns are sent to be safe before
Xlooking for the prompt.  Then the telenet id and password are entered.
XThen telenet is instructed to connect to a host site (c 12345).  The
Xhost has a data switch, and to "which system" it responds "myhost".
XThis is followed by a TOPS-20 logon, and a request to load Kermit,
Xset even parity, and enter the server mode.  Files
Xare then exchanged.  The commands are in a take file.  The
Xlogin command is split onto two lines for readability, though it
Xis a single long line in the take file.
X at begin(example)
Xset modem-dialer hayes
Xset line /dev/cul0
Xset baud 1200
Xdial 9,5551212
Xset parity even
Xscript ~0 ~0 ~0 ~0 ~0 ~0 ~0 ~0 @@--@@--@@ id~saa001122 = 002211 @@ 
X    c~s12345 ystem-c~s12345-ystem myhost @@ joe~ssecret @@ kermit 
X    > set~sparity~seven > server
Xsend some.stuff
Xget some.otherstuff
Xbye
Xquit
X at end(example)
XSince these commands may be executed totally in the background, they
Xcan also be scheduled.  A typical shell script, which might be scheduled
Xby cron, would be as follows (csh used for this example):
X
X at begin(example)
X#
X#keep trying to dial and log onto remote host and exchange files
X#wait 10 minutes before retrying if dial or script fail.
X# 
Xwhile ( 1 )
X	kermit < tonight.cmd &
X	if ( ! $status ) break
X	sleep 600
Xend
X at end(example)
XFile tonight.cmd might have two takes in it, for example, one to take
Xa file with the set modem, set line, set baud, dial, and script, and
Xa second take of a file with send/get commands for the remote server.
XThe last lines of @q(tonight.cmd) should be a bye and a quit.
X
X at heading(The 'help' Command:)
X
X at begin(example,leftmargin 0)
X at r(Syntax:) help
X@ @ @ @i(or): help @i(keyword)
X@ @ @ @i(or): help {set, remote} @i(keyword)
X at end(example)
X
XBrief help messages or menus are always available at interactive command
Xlevel by typing a question mark at any point.  A slightly more verbose form
Xof help is available through the 'help' command.  The 'help' command with
Xno arguments prints a brief summary of how to enter commands and how to
Xget further help.  'help' may be followed by one of the top-level C-Kermit
Xcommand keywords, such as 'send', to request information about a command.
XCommands such as 'set' and 'remote' have a further level of help.  Thus you
Xmay type 'help', 'help set', or 'help set parity'; each will provide a
Xsuccessively more detailed level of help.
X
X
X at heading(The 'exit' and 'quit' Commands:)
X
XThese two commands are identical.  Both of them do the following:
X
X at begin(itemize,spread 0)
XAttempt to insure that the terminal is returned to normal.
X
XRelinquish access to any communication line assigned via 'set line'.
X
XClose any open log files.
X
XRelinquish any uucp and multiuser locks on the communications line.
X
XHang up the modem, if the communications line supports data terminal ready.
X at end(itemize)
XAfter exit from C-Kermit, your default directory will be the same as when
Xyou started the program.  The 'exit' command is issued implicitly whenever
XC-Kermit halts normally, e.g. after a command line invocation, or after certain
Xkinds of interruptions.
X
X at section(C-Kermit under Berkeley or System III/V Unix:)
X
XC-Kermit may be interrupted at command level or during file transfer by
Xtyping Control-C.  The program will perform its normal exit function,
Xrestoring the terminal.  If a protocol transaction was in progress, an
Xerror packet will be sent to the opposite Kermit so that it can terminate
Xcleanly.
X
XC-Kermit may be invoked in the background ("&" on shell commmand line).
XIf a background process is "killed", the user will have to manually
Xremove any lock file and may need to restore the modem.  This is because 
Xthe kill signal (@q<kill(@i[x],9)>) cannot be trapped by Kermit.
X
XDuring execution of a system command, C-Kermit can often be returned to
Xcommand level by typing a single Control-C.  (With System III/V, the
Xusual interrupt function (often the DEL key) is replaced by Control-C.)
XOn detecting Control-C, C-Kermit takes its normal exit, removing
Xlock files and restoring the communication line, modem, and/or console
Xterminal.
X
X at begin(description,leftmargin +4, indent -4)
XUnder Berkeley Unix only:@\
XC-Kermit may also be interrupted by ^Z to put the process in the background.
XIn this case the terminal is not restored.  You will have to type
XControl-J followed by "reset" followed by another Control-J to get your
Xterminal back to normal.  C-Kermit can be halted in a similar manner by
Xtyping Control-@\Backslash, except that instead of moving it to the
Xbackground, a core dump is produced.
X
XUnder System III/V Unix:@\
XThe Control- at q(\) character (or whatever control character has been
Xselected via "set escape") at the C-Kermit command level
Xis ignored; it is trapped and will not core-@|dump or interrupt Kermit.
X at end(description)
X
XControl-C, Control-Z, and Control- at q(\) lose their normal functions during
Xterminal connection and also during file transfer when the controlling tty
Xline is being used for packet i/o.
X
XThe BSD implementation of C-Kermit has code to take advantage of a special
Xnonstandard kernel-mode line driver, which boosts the speed of packet i/o
Xsignificantly.  The problem is that "raw" mode, needed for packet i/o, also
Ximplies "cbreak" (character wakeup) mode, which is very expensive.  The new
Xline driver is a modification of the "berknet" driver, which allowed raw mode
Xi/o to take place with process wakeup only upon receipt of a linefeed.  The
XBerknet driver, unfortunately, strips off the high order bit of each
Xcharacter and does not allow the line terminator to be specified.  The
Xmodification allows all 8 bits to pass through unmolested, allows the wakeup
Xcharacter to be specified, and allows the buffer to be tested or cleared.
X
XThe System III/V implementation uses regular kernel drivers, but "gulps"
Xrawmode input in large blocks, thus overcomming the usual system call
Xoverheads.
X
XIf you are running C-Kermit in "quiet mode" in the foreground, then
Xinterrupting the program with a console interrupt like Control-C will not
Xrestore the terminal to normal conversational operation.  This is because
Xthe system call to enable console interrupt traps will cause the program to
Xblock if it's running in the background, and the primary reason for quiet
Xmode is to allow the program to run in the background without blocking, so
Xthat you can do other work in the foreground.
X
XIf C-Kermit is run in the background ("&" on shell commmand line), then
Xthe interrupt signal (Control-C) (and System III/V quit signal) are
Xignored.  This prevents an interrupt signal intended for a foreground
Xjob (say a compilation) from being trapped by a background Kermit session.
X
X
X at section(C-Kermit on the DEC Pro-3xx with Venix 1 at q(.)0)
X
XThe DEC Professional 300 series are PDP-11/23 based personal computers.
XVenix 1 at q(.)0 is a Unix v7 derivative.  It should not be confused with
XVenix 2 at q(.)0, which resembles ATT System V.
XC-Kermit runs in local mode on the Pro-3 at i(xx) when invoked from the
Xconsole; the default device is @q(/dev/com1).  When connected to a
Xremote system (using C-Kermit's 'connect' command), Pro/Venix itself (not
XKermit) provides VT52 terminal emulation.
X
XDuring file transfer, the interruption and status commands (Control-A,
XControl-F, etc) are not available.
X
X at section(C-Kermit Restrictions and Known Bugs)
X
X at begin(enumerate)
X at ux(File renaming):  When filename collision avoidance ("warning") is
Xselected, C-Kermit constructs unique names by appending a generation number
Xto the end of the file name.  Currently, no checking is done to ensure that
Xthe result is still within the maximum length for a file name.
X
X at ux(UUCP line locking):  C-Kermit locks lines, to prevent UUCP and
Xmultiuser conflicts, when it first opens a communications line.  This
Xoccurs either when 'set line' is issued, or if the '-l' argument is
Xused, when the first 'dial',
X'connect', or protocol operation occurs.  The lock is released if 
Xanother 'set line' is issued, or if the program quits, exits, or is
Xterminated by Control-C.
XIf a user connects and returns to the shell command level, for example
Xto initiate kermit by piped commands, on a communications line, the
Xline lock is released when returning to the shell.
XLocking is not needed, or used, if communications occur over the
Xlocal terminal line (e.g. @q[/dev/tty]).  In that case, there is no
Xdifficultly with "piped" operations releasing locks and lines.
X
X at begin(multiple)
X at ux(Removing stale lock files):
XFor various reasons, lock files sometimes get left about after
Xuucp or C-Kermit activities.  (The most common reason is that
Xthe uucp or C-Kermit activity was "killed" by a shell command.)
XIf the lock file is owned by yourself, clearly you may remove
Xit (presuming you are not running C-Kermit or uucp in the background
Xwhen you discovered it).
X
XUucp supports a function, called uuclean, which is customarily
Xused to remove these files after a predetermined age.  If in doubt
Xabout a lock file on the dial-out line you need, contact your
Xsystem's operator.
X at end(multiple)
X
X at ux(Modem controls):
XIf connection is made over a communication line (rather than on
Xthe controlling terminal line), and that line has modem controls,
X(e.g. data terminal ready and carrier detection implementation),
Xreturning to the shell level will disconnect the conversation.
XIn that case, one should use interactive mode commands, and
Xavoid use of piped shell-@|level operation (also see 'set modem-dialer'
Xand 'dial' commands.)
X
X at ux(Login Scripts):  The present login scripts implementation follows
Xthe Unix conventions of uucp's "@q(L.sys)" file, rather than the normal
XKermit "INPUT/@|OUTPUT" style.  Volunteers have indicated an intent to
Ximplement the Kermit standard for login scripts, and indeed even others
Xmay be implemented in the future as needed.
X
X at begin(multiple)
X at ux(Dial-out vs dial-in communications lines)
XC-Kermit requires a dial-out line for the "set line" or "-l" options.
XMost systems have some lines dedicated to dial-in, which they enable
X"loggers" on, and some lines available for dial-out.  Where a line
Xmust be shared between dial-in and dial-out, several options are
Xavailable (though they are, strictly speaking, outside the pervue of
XC-Kermit).
X
XA simple shell program can be used to change directionality of the line
Xif your Unix has the enable(8) and disable(8) commands.  In that
Xcase, the shell program could "grep" a "who" to see if anybody is
Xlogged onto the desired line;  if not, it could "disable" the line.
XThe shell program will need to be set-uID'ed to root.  The shell
Xprogram can be called from kermit prior to a dial command, e.g.,
X"! mydisable.shellprog".  Prior to the final "quit" from C-Kermit,
Xanother shell program could be executed to "enable" the line
Xagain.  This program also needs to be set-uID'ed to root.
X
XIf your Unix lacks the enable(8) and disable(8) commands, another
Xcommon technique works if your system supports the /etc/ttys file.
XA shell program could call up an awk program to find the line
Xin the file and set the enable byte to 0 (to directly disable the
Xline).  Likewise, it can be reenabled by a counterpart at the end.
XIt may be necessary to pause for 60 seconds after modifying that
Xfile before the logger sees it and actually disables the line.
X at end(multiple)
X
X at begin(multiple)
X at ux(Using C-Kermit on Local Area Networks):
XC-Kermit can successfully operate at speeds up to 9600 baud over
XLANs.  Testing has, however, shown that most processors, whether
XPC/XTs with PC/IX, or Vaxes, need flow control at these rates.
XA command, "set flow x" should be issued to each end of this form
Xof connection. 
X
XIf the LAN is the sort with an interface card (or box, like the
XSytek), then the interface card/box must be programmed to handle
Xthe flow control characters (xon and xoff) at the card/box level
X(rather than forwarding these characters to the remote site).  This
Xis because packetizing LANs will not deliver the xoff character
Xto the other end, after packetization, until long after the receive
Xbuffer has been overrun.
X at end(multiple)
X
X at ux(Resetting terminal after abnormal termination or kill): When C-Kermit
Xterminates abnormally (say, for example, by a kill
Xcommand issued by the operator) the user may need to reset the terminal state.
XIf commands do not seem to be accepted at the shell prompt, try
XControl-J "stty sane" Control-J (use "reset" on Berkeley Unix).
XThat should take the terminal out of "raw mode" if it was stuck there.
X
X at ux(Remote host commands may time-out on lengthy activity):
XUsing "remote host" to instruct the C-Kermit server to invoke Unix
Xfunctions (like "make") that might take a long time to produce output can cause
Xtimeout conditions.
X
X
X at ux(PC/IX Login Scripts -- Unfound Bug):
XThough login scripts appear to work properly on most processors, in the
Xcase of the PC/XT with PC/IX, it appears that longer scripts
Xneed to be broken up into shorter scripts (invoked sequentially from
Xthe take file).  This is because the portion of the script handler
Xwhich checks if an operation timed out seems to leave the processor
Xin a strange state (i.e. hung).
X at end(enumerate)
X
X at section(How to Build C-Kermit for a Unix System)
X
XThe C-Kermit files, as distributed from Columbia, all begin with the
Xprefix "ck".  You should make a directory for these files and then cd
Xto it.  A makefile is provided to build C-Kermit for various Unix systems.
XAs distributed, the makefile has the name "@q(ckermi.mak)".  You should
Xrename it to "@q(makefile)" and then type "make xxx", where xxx is the
Xsymbol for your system, for instance "make bsd" to make C-Kermit for
X4.2 BSD Unix.  The result will be a program called "wermit".  You should
Xtest this to make sure it works; if it does, then you can rename it to
X"kermit" and install it for general use.  See the makefile for a list of
Xthe systems supported and the corresponding "make" arguments.
X
X at section(Adapting C-Kermit to Other Systems)
X
XC-Kermit is designed for portability.  The level of portability is indicated
Xin parentheses after the module name: "C" means any system that has a C
Xcompiler that conforms to the description in "The C Programming Language" by
XKernighan & Ritchie (Prentice-Hall, 1978).  "Cf" is like "C", but also
Xrequires "standard" features like printf and fprintf, argument passing via
Xargv/argc, and so on, as described in Kernighan & Ritchie.  "Unix" means the
Xmodule should be useful under any Unix implementation; it requires features
Xsuch as fork() and pipes.  Anything else means that the module is particular
Xto the indicated system.  The modules are:
X
X at begin(description,leftmargin +4, indent -4)
X at q<ckmain.c, ckermi.h, ckdebu.h (Cf)>:@\This is the main program.  It contains
Xdeclarations for global variables and 
Xa small amount of code to initialize some variables and invoke the command
Xparser.  In its distributed form, it assumes that command line arguments are
Xpassed to it via argc and argv.  Since this portion of code is only several
Xlines long, it should be easy to replace for systems that have different
Xstyles of user interaction.  The header files define symbols and macros used
Xby the various modules of C-Kermit.  @q(ckdebu.h) is the only header file
Xthat is included by all the C-Kermit modules, so it contains not only the
Xdebug format definitions, but also any system-@|dependent typedefs.
X
X at q<wart.c (Cf), ckprot.w (C)>:@\The ckprot module embodies the Kermit protocol
Xstate table and the code to accomplish state switching.  It is written in
X"wart", a language which may be regarded as a subset of the Unix "lex" lexical
Xanalyzer generator.  Wart implements enough of lex to allow the ckprot module
Xto function.  Lex itself was not used because it is proprietary (but lex may be
Xused in place of wart with minor reformatting of @q(ckprot.w) -- removal of
X at q(#includes) and comments, which must be reinserted into lex's output C
Xprogram).  The protocol module @q(ckprot.w) is read by wart, and a
Xsystem-independent C program is produced.  The syntax of a Wart program is
Xillustrated by @q(ckprot.w), and is described in @q(ckwart.doc).
X
X at q<ckfns.c (C)>:@\The module contains all the Kermit protocol support functions
X-- packet formation, encoding, decoding, block check calculation, filename and
Xdata conversion, protocol parameter negotiation, and high-level interaction
Xwith the communication line and file system.
XTo accommodate small systems, this module has been split into two --
X at q(ckfns.c) and @q(ckfns2.c).
X
X at q(ckx???.c) (specific to system ???):@\For instance, @q(ckxunx.c)
X(Berkeley, Venix, ATT System III/V, and other Unix systems) -- The ckx
Xmodule contains the system-@|dependent primitives for communication line
Xi/o, timers, and interrupts.  Certain important variables are defined in
Xthis module, which determine whether C-Kermit is by default remote or
Xlocal, what the default communication device is, and so forth.  The ckx
Xmodule maintains its own private database of file descriptors and modes
Xfor the console terminal and the file transfer communication line so
Xthat other modules (like ckfns or the terminal connect module) need not
Xbe concerned with them.  This module will vary significantly among Unix
Ximplementations since the sgtty/@|ioctl/@|termio functions and their
Xarguments are among the least compatible areas of Unix.  The @q(ckxunx.c)
Xfile has conditional compilation for the variations of Unix.
X
X at q(ckz???.c) (specific to system ???):@\For instance, @q(ckzunx.c) (Berkeley,
XVenix, System III/V Unix) -- The ckz module contains system-dependent
Xprimitives for file i/o, wildcard (meta character) expansion, file existence
Xand access checking, and system command execution.  It maintains an internal
Xdatabase of i/o "channels" (file pointers in the case of Unix) for the files
XC-Kermit cares about -- the input file (the file which is being sent), the
Xoutput file (the file being received), the various logs, the screen, and so
Xforth.  This module will vary little among Unix implementations except for the
Xwildcard expansion code, which requires detailed knowledge of the directory
Xstructure.  The ckz module also defines variables containing the system command
Xstrings used to perform certain functions like directory listing, file
Xdeletion, etc.  The @q(ckzunx.c) file has conditional compilation for the
Xvariations of Unix.
X
X at begin(multiple)
X at q(ckuser.h, ckuser.c, ckusr2.c, ckusr3.c) (Unix):@\This is the "user
Xinterface" for C-Kermit.  It includes the command parser,
Xthe screen output functions, and console input functions.  The command
Xparser comes in two pieces -- the traditional Unix command line decoder
X(which is quite small and compact), and the interactive keyword parser
X(which is rather large).  This module is fully replacable; its interface to
Xthe other modules is very simple, and is explained at the beginning of the
Xsource file.  The ckuser module also includes code to execute any commands
Xdirectly which don't require the Kermit protocol -- local file management,
Xetc.  The module is rated "Unix" because it makes occasional use of the
Xsystem() function.
X
XNote that while ckuser is logically one module, it has been split up into
Xthree C source files, plus a header file for the symbols they share in common.
XThis is to accommodate small systems that cannot handle big modules.
X at q(ckuser.c) has the command line and top-level interactive command parser;
X at q(ckusr2.c) has the help command and strings; @q(ckusr3) has the set
Xand remote commands along with the logging, screen, and "interrupt" functions.
X at end(multiple)
X
X at q(ckcmd.c, ckcmd.h) (Cf):@\This is an interactive command parsing package
Xdeveloped for C-Kermit.
XIt is written portably enough to be usable on any system that has a C
Xcompiler that supports functions like printf.  The file name parsing
Xfunctions depend upon primitives defined in the ckz module; if these
Xprimitives cannot be supplied for a certain system, then the filename
Xparsing functions can be deleted, and the package will still be useful
Xfor parsing keywords, numbers, arbitrary text strings, and so forth.
XThe style of interaction is the same as that found on the DECSYSTEM-20.
X
X at q(ckconu.c) (Unix):@\This is the connect module.  As supplied, it should
Xoperate in any Unix environment, or any C-based environment that provides the
Xfork() function.  The module requires access to global variables that specify
Xline speed, parity, duplex, flow control, etc, but invokes functions from the
Xckx module to accomplish the desired settings and input/output, and functions
Xfrom the ckz module to perform session logging.  There is no code for
Xcontrolling modem signals.  No terminal emulation is performed, but since
Xstandard i/o is used for the console, this may be piped through a terminal
Xemulation filter.  The ckconu function may be entirely replaced, so long as
Xthe global settings are honored by its replacement.  PC implementations of
XC-Kermit may require the ckcon module to do screen control, escape sequence
Xinterpretation, etc, and may also wish to write special code to get the best
Xpossible performance.
X
X at q(ckdial.c) (Unix):@\This is the dialer module.  As supplied, it handles hayes
Xand ventel modems.
X
X at q(cklogi.c) (Unix):@\This is the login script module.  As supplied, it handles
Xuucp-@|style logins. 
X at end(description)
X
XMoving C-Kermit to a new system entails:
X at begin(enumerate)
XCreating a new ckx module in C, assembler, or whatever language is
Xmost appropriate for system programming on the new system.
X
XCreating a new ckz module, as above.
X
XIf the system is not Unix-like, then a new ckuser module may be required,
Xas well as a different invocation of it from ckmain.
X
XIf the distributed connect module doesn't work or performs poorly, then
Xit may be replaced.  For instance, interrupt-driven i/o may be required,
Xespecially if the system doesn't have forks.
X at end(enumerate)
XThose who favor a different style of user/program interaction from that
Xprovided in @q(ckuser.c) may replace the entire module, for instance with one
Xthat provides a mouse/@|window/@|icon environment, a menu/@|function-@|key
Xenvironment, etc.
X
XA few guidelines should be followed to maintain portability:
X at begin(itemize)
XKeep variable and function names to 6 characters or less.
X
XKeep modules small.  For instance, on a PDP-11 it is necessary to keep
Xthe code segment of each module below 8K in order to allow the segment
Xmapping to occur which is necessary to run programs larger than 64K on a
Xnon-I-&-D-space machine.
X
XKeep strings short; many compilers have restrictive maximum lengths.
X
XKeep (f,s)printf arguments short.  If these exceed some compiler dependent
Xmaximum (perhaps as short as 128, after expansion) memory will be overwritten
Xand the program will probably core dump.
X
XDo not introduce system dependencies into @q(ckprot.w) or @q(ckfns*.c).
X at End(Itemize)
XIn general, remember that this program will have to be compilable by old
Xcompilers and runnable on small systems.
X
X
!FUNKY!STUFF!