title k20hlp - Kermit-20 Help Text
	subttl Help Text.	;[18] Lengthy help messages added in edit [18].

	search monsym,k20unv	; Wants parsing and Kermit .PSECT definitions
	cmdacs			; Clean up p1-p4 definitions

	sall			; Tidy listing
	.directive flblst	; We don't need to see all the ASCIZ bytes...

	subttl Notes and Cautions

	remark Virtual address space decisions

; The vast majority of the help text (over 32 pages of ASCII data) has
; been moved out of section 0 into section 1.  This is to free up some
; virtual address space in section 0.
;
; However, it also has the benefit of a smaller working set size as
; the help text is typically seldom referenced.  This will make Kermit
; more likely to be selected to run and cause less impact to Tops-20.
;
; Perhaps more significant is the fact that such a layout uses less
; cache space.  This will result in faster performance on both the
; MCA25 and other implementations with cache memories, including the
; cache on systems hosting simulators.

	remark Virtual address space cautions

; Be aware that the help semantic action routine ($help in k20par)
; uses an address calculation to determine whether the result of the
; parse is either a macro whose text needs displaying or a simple text
; to just type.
;
; This is almost a hack in a single section program where there can be
; no issue of in-section address aliasing.  It can get you into real
; trouble if you are using multiple sections.  Thus, care must be
; taken to ensure that the in-section addresses of the macro table and
; help text do NOT conflict.
;
; See the calculations for hlporg in k20unv.mac for further details.

	subttl Table of help commands

	.psect code/ronly	; %key macros will put text in the text .psect

	%table(hlptab,G)	;[194] ;[18]	
	%key2 <36-bit-bytes>,h36bb	;[232] 
	%key2 <bye>,hbye
	%key2 <C-escape-sequences>,hcescp
	%key2 <capture>,hcaptu ;[230] 
	%key2 <clear>,hclear
	%key2 <close>,hclose
	%key2 <connect>,hconne
	%key2 <control-characters>,hcchar
	%key2 <cwd>,hcwd
	%key2 <debugging>,hdebug ;[239] 
	%key2 <define>,hdefin
	%key2 <delete>,hdele
	%key2 <directory>,hdire
	%key2 <echo>,hecho
	%key2 <exit>,hexit
	%key2 <finish>,hfinis
	%key2 <get>,hget
	%key2 <help>,hhelp
	%key2 <input>,hinput
	%key2 <kermit>,hkermi
	%key2 <line>,hline
	%key2 <local>,hlocal
	%key2 <log>,hlog
	%key2 <output>,houtpu
	%key2 <pause>,hpause
	%key2 <prompt>,hpromp
	%key2 <push>,hpush
	%key2 <pwd>,hpwd
	%key2 <quit>,hquit
	%key2 <quote-characters>, hsquo
	%key2 <receive>,hrecei
	%key2 <remote>,hremot
	%key2 <return>,hretur	;[237] 
	%key2 <run>,hrun
	%key2 <send>,hsend
	%key2 <server>,hserve
	%key2 <set>,hset
	%key2 <show>,hshow
	%key2 <space>,hspace
	%key2 <statistics>,hstatu
	%key2 <status>,hstatl
	%key2 <take>,htake
	%key2 <time>,htime ;[210] 
	%key2 <transmit>,htrans
	%key2 <type>,htype
	%tbend

	subttl Table of HELP SET commands.

	%table(sethlp,G)	;[194] 	;[67] 
	%key2 <block-check>, hsbc
	%key2 <break>, hsbrea
	%key2 <debugging>, hsdeb
	%key2 <delay>, hsdel
	%key2 <duplex>, hsdup
	%key2 <escape>, hsesc
	%key2 <expunge>, hsexp
	%key2 <file>, hsfil
	%key2 <flow-control>, hsflo
	%key2 <handshake>, hshan
	%key2 <host>, hshst
	%key2 <incomplete>, hsabf
	%key2 <input>, hsetin
	%key2 <ITS-binary>, hsits
	%key2 <line>, hslin
	%key2 <parity>, hspar
	%key2 <prompt>, hsprom
	%key2 <receive>, hsrcv
	%key2 <retry>, hsrty
	%key2 <send>, hssnd
	%key2 <speed>, hspeed
	%key2 <summary>, hset
	%key2 <TVT-Binary>, hstac
	%tbend
	

	subttl Table of DEFINE switches

;[214] Begin table insertion

; N.B., Note that certain keywords are under an emacro conditional
;    assembly variable.  Editing functions for macros are not
;    completely implemented and thus help has not been written.

	%table(defhlp,G)
emacro < %key2 <add>, hadd >
emacro < %key2 <change>, hchang >
	%keyf3 <co>, %comp, <cm%abr!cm%inv> ; Don't confuse anybody (like me!)
%comp:	%key2 <compact>, hcompa
	%keyf3 <copy>, hcompa, cm%inv  ; For sleepy,forgetful Tom
	%key2 <dump>, hdump
	%key2 <duplicate>, hdupli
emacro < %keyf3 <edit>, hchang, cm%inv >
	%key2 <map>, hmap
emacro < %key2 <remove>, hremov >
	%key2 <rename>, hrenam
	%key2 <reset>, hreset
	%key2 <save>, hsave
	%key2 <summary>, hsumma
	%key2 <undefine>, hundef
	%tbend

	cleans (<%comp>)

;[214] End table insertion


	subttl Table of CLEAR switches

;[214] Begin table insertion

	%table(clrhlp,G)
	%key2 <always>, halways
	%key2 <display>, hdispl
	%key2 <estimate>, hestim
	%key2 <flush>, hflush
	%key2 <peek>, hpeek
	%key2 <repeat>, hrepea
	%key2 <summary>, hclear
	%tbend

;[214] End table insertion


	subttl Begin table of LOCAL keywords

;[214] Begin table insertion

	%table(lclhlp,G)
	%key2 <cwd>, hcwd
	%key2 <delete>, hdele
	%key2 <directory>, hdire
	%key2 <help>, hhelp
	%key2 <host>, hshst
	%key2 <pwd>, hpwd
	%key2 <run>, hrun
	%key2 <space>, hspace
	%key2 <status>, hstatl
	%key2 <type>, htype
	%tbend

;[214] End table insertion


	subttl Table of REMOTE keywords

;[214] Begin table insertion

	%table(remhlp,G)
	%key2 <cwd>, hrcwd
	%key2 <delete>, hrdele
	%key2 <directory>, hrdire
	%keyf3 <error>, hrerro, cm%inv
	%keyf3 <finish>, hfinish, cm%inv
	%key2 <help>, hrhelp
	%key2 <host>, hrhost
	%key2 <pwd>, hrpwd
	%key2 <space>, hrspac
	%key2 <status>, hrstat
	%key2 <type>, hrtype
	%tbend

;[214] End table insertion

	subttl Table of TIME switches

;[214] Begin table insertion

	%table(timhlp,G)
	%key2 <bytesize>, htbyte
	%key2 <mode>, htmode
	%key2 <record-length>, htreco
	%tbend

;[214] End table insertion

	subttl Close out the code segment
	xlist			; Don't see the dumped literals, yuck!
	 lit			; Do them now while we're not looking
	list			; Turn the listing back on

	.endps code		; Done with addresses and all that


	subttl Sole special case of general SET help

; SET command help text.

	.psect text/ronly	; Sole case of help in section zero

hset:	intern hset
	asciz |
SET parameter [option] [value]

  Establish or modify various parameters for file transfer or terminal
  connection.  You can examine their values with the SHOW command.  The
  following parameters may be SET:

  BLOCK-CHECK error detection method
  BREAK       number of nulls at 50 baud for BREAK simulation
  DEBUGGING   mode or log file
  DELAY       how long to wait before starting to send
  DUPLEX      for terminal connection, full (remote echo) or half (local echo)
  ESCAPE      character for terminal connection
  EXPUNGE     Whether to fully delete or not
  FILE        for setting file parameters like name conversion and byte size
  FLOW-CONTROL for enabling and disabling XON/XOFF flow control
  HANDSHAKE   for turning around half duplex communication line
  HOST	      DECnet remote terminal or local loopback pseudo-terminal
  INCOMPLETE  what to do with an incomplete file
  INPUT       desired behavior for INPUT command
  ITS-BINARY  special format for 8-bit binary files
  LINE        TTY line to use for terminal connection or file transfer
  PARITY      character parity to use
  PROMPT      for changing the Kermit-20 program prompt
  RECEIVE     various parameters for receiving files
  RETRY       how many times to retry a packet before giving up
  SEND        various parameters for sending files
  SPEED       set speed (baud rate) of currently selected line
  TVT-BINARY  binary mode negotiation for Internet virtual terminals

For further information, type "help set" followed by one of these keywords.
Also, type "help define" to see how to define "macros" for SET commands.
|

	.endps text		 ;[190] End section zero text

 	subttl Overall summary, more detailed help text is with each command.

	.psect help/ronly,hlporg ;[190] Don't allow stores
hkermi:	asciz &

KERMIT is a file transfer protocol for use over an asynchronous serial
telecommunication line.  Files are broken up into "packets" with
checksums and other control information to promote error-free and
complete transmission.

Kermit-20 is the KERMIT implementation for the DECSYSTEM-20.
Kermit-20 can be run "remotely" from another computer (e.g. a
microcomputer), or "locally" with a remote Kermit on the other end of
an assigned TTY line (e.g. over an autodialer connection) or over a
DECnet connection to another system supporting the Tops-10/Tops-20
Network Remote Terminal (NRT) protocol.  Existing NRT servers include
Tops-10 and Tops-20.

You can run Kermit interactively by typing repeated commands in
response to its "Kermit-20>" prompt, or you can invoke it from the
TOPS-20 Exec with a single command line argument (e.g. "kermit
receive"), or you can run it as a remote server.

You can also run Kermit in a batch job to communicate at off hours via
an autodialer or over an NRT.  When doing this, it is advised that
only the INPUT and OUTPUT commands be used as these are better suited
to the Batch control language.

Further, the batch controller (BATCON) will not work with the Kermit
terminal connection as it is implemented as two asynchronous
processes, one to read from the local terminal and send to the remote
system and the other to read from the remote system and type on the
local system.

While this yields the expected experience with as little delay as
possible, BATCON can't tell when to 'feed' the batch job any input as
Kermit's terminal will always look 'hungry'.  In short, no
asynchronous terminal client will work in a Batch environment and none
of them can be made to work.  Use INPUT and OUTPUT.

Kermit-20 command summary -- optional parts are in [brackets]:

* For exchanging files using KERMIT protocol:
    SEND file(s) [(INITIAL) file]
    RECEIVE [file]
    GET remote-file(s)
    SERVER

* For acting as local Kermit:
    CONNECT [line | DECnet host | pseudo-terminal ], INPUT, OUTPUT, CLEAR
    SET: LINE, FLOW, PARITY, DUPLEX, HANDSHAKE, ESCAPE, BREAK, SPEED

* For talking to a server:
    BYE, FINISH, GET remote-file(s), SEND file(s);
    REMOTE: DISK-USAGE, TYPE, CWD, DIRECTORY, DELETE, HELP, HOST

* Setting nonstandard transmission and file parameters:
    SET: DEBUG, DELAY, FILE, INCOMPLETE, INPUT, ITS, PROMPT, RETRY, TVT;
    SET SEND (or RECEIVE): END-OF-LINE, START-OF-PACKET, PACKET-LENGTH,
		PAUSE, PADDING, TIMEOUT, SERVER-TIMEOUT
    DEFINE a macro for a combination of SET commands.

* For non-protocol data transfer:
    INPUT, OUTPUT, PAUSE, CLEAR, TRANSMIT, LOG SESSION

* For interrupting transmission: Control-X (^X), ^Z, ^C

* Getting information:		HELP [topic], STATISTICS, SHOW, ^A
* Recording information:	LOG or CLOSE TRANSACTIONS, SESSION, DEBUGGING
* Executing command files:      TAKE
* Leaving the program:		EXIT, QUIT, BYE, PUSH

If you have a file called KERMIT.INI in your login directory,
Kermit-20 will execute an implicit TAKE command on it upon initial
startup.  KERMIT.INI may contain any Kermit-20 commands; DEFINE and
SET commands are the most useful.

For further information, type "help" for any of the above, e.g. "help
set", or see the "Kermit Users Guide" and the "Kermit Protocol Manual"
for complete details.
&

	subttl Help text for BYE

hbye:	asciz |
BYE	

When running as a local Kermit, talking to a KERMIT server over a TTY
line specified in a SET LINE command, use the BYE command to shut down
and log out the server.  This will also close any local debugging log
file and exit from the local KERMIT.
|

      subttl Help text for the CAPTURE command

;[230] Begin help text insertion

hcaptu: asciz &
CAPTURE [ [ /TIMEOUT n ] [ /EOF ^Z | ^D | $ | ^G ] ]
	filespec [ prompt | "prompt" ]

Intended for use in remote mode only.  This invisible command is the
remote counterpart to the local TRANSMIT command since it 'captures'
the text file that TRANSMIT sends.  It is used only for testing
purposes and the help text for the TRANSMIT command should be used as
a reference before attempting such a capture.

The prompt must match what TRANSMIT was told to recognize as CAPTURE
will print this after each and every line of text received.  A line
of text is expected to be terminated by carriage return (\r) and
CAPTURE will write this to the indicated file and a line feed (\n)
appended as TRANSMIT assumes carriage returns and strips line feeds.

The prompt string may be enclosed in quotes and may include special
characters by preceding their octal ASCII values with a backslash
(e.g. \15 for carriage return) or C escape sequence (e.g., \r being
converted into octal 15).  Type HELP C-ESCAPE-SEQUENCES for further
information on escape values.  Type HELP INPUT for information on what
TRANSMIT will be able to recognize.

Only a single file may be captured, no wildcards are allowed in the
filespec.  The file must be created on a file structure to which you
either have or have gained access.  No other device is permitted with
the exception of NUL:, which is only used for debugging and testing
purposes.  It is strongly recommended that this file not be
particularly large (see TRANSMIT).

The file will be captured using the current settings for duplex,
parity, and flow control.  These parity settings must be set
beforehand and MUST MATCH as a parity failure will cause the capture
to be aborted.

Unless a SET INPUT TIMEOUT default has been set or a /TIMEOUT switch
has been given there may be no timeouts on input text.  Thus, like
INPUT, CAPTURE command will wait forever for each line of text to
appear.  A control-C typed two or three times will close the file
specified by CAPTURE command and return you to the Kermit-20> prompt.

The optional /EOF switch may be used to indicate that a particular 
character should be sent when the End-of-File (EOF) condition is
detected.  The following EOF characters are supported:

    ^Z	Used by DEC operating systems, such as Tops-10 and Tops-20,
	IBM/Microsoft OS's, such as DOS, OS/2 and Windows.
    ^D	Used by Unix type systems, such as Linux, Mac OSX and Ubuntu.
     $	Dollar sign is used as a talisman for the escape character,
	which is used by Tops-10 and others as a line terminator.
    ^G	Used by certain DEC CUSPs, such as PIP and audible debugging.

The file is always received as an eight bit stream, even if it was
seven bit ASCII originally and is always stored as seven bit ASCII, no
matter what the source was.

Great caution should be exercised when using this command as it can
crash communications systems, hang network connections and otherwise
wedge other terminal based data paths.  The safest approach may be to
split the file up into several smaller pieces and do the TRANSMIT of
each separated by PAUSE's at off hours in a batch job.

Recall that the whole point of the Kermit protocol was specifically to
avoid this situation with DECSYSTEM-20 PDP-11 front end.  Although
these systems are only museum pieces now, their network
implementations can still hang if pushed too hard.

If the wedge is bad enough, somebody may have to reboot the remote
computer, which risks making you unpopular with the staff or owner if
it happens often enough.

If you really want to send the entire file without looking for any
prompts, specify a prompt of "\0" (ASCII zero or NUL).  Again, this
means that you are send the file at the fastest possible speed that
the line will support with no acknowledgements; be aware that this
will almost surely hang any computer which does not have a dedicated,
real time input facility, particularly if this is done at Ethernet
speeds.

Otherwise, this should only be used for testing and debugging purposes
on loopback connections using pseudo-terminals as these will self-
throttle.
&

;[230] End help text insertion

	subttl Help text for CLEAR

hclear:	intern hclear
	asciz &
CLEAR [ /ALWAYS | /DISPLAY | /ESTIMATE | /FLUSH | PEEK [/REPEAT [n] ] ]

Clear the monitor's input and output buffers of the currently selected
line or network connection and remove any internally buffered data.
For physical lines, attempt to clear any XOFF condition if XON/XOFF
negotiation is being done.

A combined count of characters is returned if any were removed from
either the monitor or internally.

This is highly useful in local mode, when the connection to the remote
system appears to be stuck.  Often, a stuck connection is the result
of a rather large number of NAK's having piled up because:

    1)	The user hasn't issued a remote Kermit command in quite some
	time.

    2)	The remote server time-out parameter, which sets the NAK
	interval, having been set too low.

It can also be used for recovering from a TRANSMIT or INPUT error.

Further help on the switches can be found by typing HELP CLEAR
followed by the switch, viz: HELP CLEAR /ESTIMATE.
&

	subttl Help text for CLEAR switches

halway:	asciz |
/ALWAYS

Whenever Kermit detects that it has cleared characters, it displays a
summary like this:

	Iterations: 2, Cleared: 19, Elapsed: 1:000.00 (TOD: 3)

Using ALWAYS forces this summary to be displayed whether or not
anything was actually cleared.  It is not the default as this causes
more output.  The switch is provided largely for debugging and
check-out purposes.
|

hestim:	asciz |
/ESTIMATE

Display what the monitor thinks is in the line or network buffer.

Be aware that, unless you have a local or "loopback" connection to a
Kermit on a Tops-20 pseudo-terminal (PTY), this number is often wrong
because characters can be stacked up at the remote site, waiting for
transmission.

In short, there is no way Tops-20 can know what a remote host might
have in store for you.  Therefore, the only truly accurate way to know
how much data is stuck is to actually try remove it with either the
/FLUSH or /DISPLAY switches.

To see what might be waiting for INPUT or TRANSMIT to process, do a
/PEEK.
|


hflush:	asciz |
/FLUSH

Remote all data from the line or network connection.  /FLUSH is the
default; giving a CLEAR command with no switch implies /FLUSH.

In addition to getting rid of whatever is in the monitor buffers,
/FLUSH will also remove what Kermit may have buffered internally for
the INPUT or TRANSMIT command to read.

/FLUSH will report a count of characters it was able to remove, which
will include the combined total of the monitor and Kermit internal
buffers.  Doing a SHOW LINE will show these totals separately,
|

hdispl:	asciz |
/DISPLAY

Show the data that was actually removed from the line or network
connection and internal buffers, viz:

	Kermit-20>CLEAR /DISPLAY
	Buffered: 43, 'ENTI2, PANDA TOPS-20 Monitor 7.1(21746)-5
	'
	^A# N3^M
	^A# N3^M
	^A# N3^M
	^A# N3^M
	^A# N3^M
	^A# N3^M
	^A# N3^M
	^A# N3^M
	^A# N3^M

	Characters flushed: 97

When connected to a virtual device, such as a DECnet NRT or a pseudo-
terminal, a count of characters removed is kept.  For DECnet, this
number can get to be quite large and is the result of a Tops-20
monitor anomaly which Kermit-20 compensates for.

Despite the anomaly, be aware that a large number of NAK's can build
up, perhaps because the connection has sat idle overnight, depending
on the remote system's user and monitor buffers.

Although /FLUSH and /DISPLAY will exert best efforts and not return
until the local Tops-20 hosts declares the line cleared, once the
logjam is resolved locally, the remote host may still have more NAK's
to deliver.

Therefore, do not assume that a single CLEAR will do the trick,
multiple clears may need to be issued in order to fully drain the
connection.

Like /FLUSH, /DISPLAY will toss any data in Kermit's internal buffer
which is remaining for the INPUT command to process.  This need only
be done once; using /REPEAT to get rid of buffered internal data
produces no detectable effect.
|

hrepea:	asciz |
/REPEAT

The /REPEAT switch may be used to issue multiple CLEARs.  By default,
/REPEAT will try five clears, each separated by an interval of 1
second.  A count parameter may be specified to change the repetition
and an optional comma may be given, followed by the number of seconds
to delay.  For example:

	CLEAR /DISPLAY /REPEAT:6,1.25

Will cause the CLEAR /DISPLAY logic to be repeated six times with a
delay interval of one and a quarter seconds.  Thus, the total time to
execute the command will be seven and a half seconds.

Leaving a CLEAR /DISPLAY running for a long time is one way to
determine whether you have a noisy line or whether any unexpected
output might be hanging things up.

It is possible to repeat an /ESTIMATE, but the value is unlikely to
change nor be of much value.  The functionality exists for testing and
debugging.  Similarly, using /REPEAT to get rid of buffered internal
data produces no detectable effect as the buffer will not contain any
data until such time as another INPUT or TRANSMIT is issued.

A repeat loop may be aborted with a ^C.  If the process does not have
Control-C capability, then a Control-G may be used instead, and the
user will be advised of this.

The status of a repeat loop may be requested with a ^Y.  It will print
the number of iterations done so far, the total characters cleared and
the elapsed time spent doing this, which includes the accumulated
delays.  For example:

Iterations: 17, Cleared: 120, Elapsed: 12:04.635.810 (TOD: 2198)

See the help for STATISTICS command for an explanation of the time
format, which is granular to a hundredth of a microsecond.

Be aware that in a batch job may have different sleep timing reported
than a normal timesharing job.  This can happen if you are running
batch jobs in the DREGS queue.  Use a longer sleep time.
|				;[232] 

hpeek:	asciz |
/PEEK

Use of the TRANSMIT or OUTPUT and INPUT commands can cause Kermit to
keep a certain amount of host output in an internal buffer.  This
buffer is exclusive to these commands and will not be seen by any data
transfer commands (such as SEND and RECEIVE) nor will it be seen if
you reconnect.

/PEEK will show the size of this internal buffer and what is in it,
but does not remove anything to allow for further use of TRANSMIT,
INPUT and OUTPUT.  This is useful for debugging scripts (I.E., 'TAKE'
files), macros and batch jobs.

Therefore, /ESTIMATE will not report this data, but /FLUSH will get
rid of it and /DISPLAY will show it as part of removing it.
|

	subttl Help text for CLOSE

hclose:	asciz &
CLOSE [ TRANSACTION | DEBUGGING | SESSION] ]

Close the specified log file, and stop recording to that file.  If
anything has been written to the log, then the quantity written will
be displayed.

If no particular keyword is selected, all logs will be closed.

It is not an error to close a log which was not open, however that
fact will be remarked on by Kermit-20.
&

	subttl Help text for CWD

hcwd:	asciz &
CWD directory [ password | "password" ]

CWD means CHANGE WORKING DIRECTORY.  It is the same as LOCAL CWD,
which is executed on the local Tops-20 system.  This operation is the
same as the DEC-20 CONNECT command and, similarly, a password may be
requested for proper completion.  CWD is a Unix term; the operation
here being more properly known as a "CONNECT".

Be aware that connecting to a Tops-20 directory has VERY different
functionality than other operating systems and can have far-reaching
consequences.

In particular, CWD can change access to other files as well as change
the default directory in which file operations will be performed.
This means that file operations which previously failed may now
succeed and vice versa.  CWD is commonly used to gain this access.

Also, a CWD changes the directory for the entire job and not just for
the Kermit-20 fork.  Concurrently executing forks will not be aware of
this.  Open files will not be effected, but any new file operation
that does not explicitly specify or default the structure and directory
will use the new 'working' (I.E., connected) directory. 

Note that if the directory in question is on a regulated structure,
then that structure must be mounted first with the DEC-20 MOUNT
STRUCTURE command as Kermit-20 contains no facility to do this and
is prevented from bypassing mount counts in most situations.

Attempting to specify a directory on a structure which has not been
mounted will be rejected as a parse error.  This allows the user to
type a ^H to get the command back, ^C to the EXEC, mount the structure
and then CONTINUE the Kermit-20 fork to confirm the CWD.  The parse
error will abort batch jobs.

Finally, it can readily be seen that makes no sense to connect to a
device which does not support file structures and Kermit-20 will
reject this.  Trying to connect to NUL: does nothing and leaves you
still connected to your currently connected directory.

Simply issuing CWD with no arguments will connect you to your login
directory.  If you are connected to a directory on one structure and
wish to connect to a directory of the same name on another structure,
you can merely type the structure name by itself and Kermit-20 will
default the directory.  If this fails for some reason, you will get
a parse error and can retry the command.

The second form of CWD allows both the directory and the password to
be specified on the same line.  This is primarily intended for .CMD
files, batch jobs and never for interactive use.  This is because the
password is echo'ed can thus be seen by others!

In this case, omit the password and Kermit-20 will only prompt for a
password if it determines that it can't connect without one.  When
Kermit-20 prompts for a password, it will not be echo'ed.

In an attempt to decrease the needless use of passwords, Kermit-20
will reject a quoted password as a parse error in addition to not
prompting for one.  This will allow the user to type a ^H to get the
command back and then type a ^W, rubout (or delete) and hit enter to
retry the command.  The parse error will abort batch jobs.

CAUTION: Kermit-20 is not able overwrite the password text on half-
duplex lines because it has no control over the line feed that is
typed after the enter key is hit.  It is suggested that the screen be
promptly cleared or the paper removed.
&

	subttl Help text for DELETE

hdele:	asciz |
DELETE filespec

DELETE is the same as LOCAL DELETE.  It works like the DEC-20 DELETE
command, except that if you SET EXPUNGE ON, then all files that you
delete with Kermit-20, whether with interactive DELETE commands, or
via REMOTE DELETE commands when Kermit-20 is running as a server, will
also be automatically expunged.

Where files have multiple generations, setting Kermit-20 to run
without automatic file expunging will result in far faster
performance.  If a delete results in multiple generations being
removed, then the count of generations per file will be displayed.
Otherwise, a single generation will not be remarked on.  At the end,
the total number files deleted will be displayed.

Be aware that Kermit-20 does not have an UNDELETE command.  If EXPUNGE
is off, then you must use the DEC-20 UNDELETE command to recover the
file.

If the directory is EXPUNGED by another user (perhaps by a LOGOUT),
then the deleted files will no longer exist and can not be undeleted.
Similarly, any file that is deleted with EXPUNGE set ON can not be
undeleted.

A file may only be deleted from a directory based device, such as a
file structure.  All other devices will be rejected with the exception
of NUL:.  The NUL: device may be deleted as many times as you like,
but nothing useful happens.  Such functionality is intended purely for
debugging purposes, only.
|

	subttl Help text for DIRECTORY

hdire:	asciz |
DIRECTORY filespec

DIRECTORY is the same as LOCAL directory.  It produces a listing of
the specified files at your terminal.  The default is to list all
generations of all file types of all file names in the currently
connected directory.

The DIRECTORY command can not be used to list files that have either
been set invisible or are deleted.  Use the DEC-20 DIRECTORY command
to do this.  Additionally, neither command can be used to list files
that have been protected against listing or are in a directory to
which you have no list access.

Kermit-20 can not list files on a device that has no directories and
will reject such requests.  Therefore, it makes no sense to try to
list your or anyone else's terminal.

NUL: may be listed, but nothing particularly useful is happens, a
single zero length file with a zero byte length named "NUL:" being
displayed, the creation date always being "Now".  Such functionality
is intended purely for debugging purposes, only.
|

	subttl Help text for ECHO

hecho:	asciz &
ECHO [/debug | /session | transaction] [ "Quoted Text" | text-string ]

Echoes the given text string at your terminal.  Useful in TAKE command
files and with login scripts for reporting progress or telling you
what to do.  A quoted string may also be given, which may then be
explicitly visually confirmed.  Typing nothing (I.E., an ECHO all by
itself) will echo a blank line.

Echo will expand C escape sequences.  For example, issuing this command

	ECHO "\r\n\qHello\q\r\n"

    will result in:

	"Hello"

being displayed on the terminal.  This is useful for learning,
prototyping and refamiliarization with the functionality for use with
the INPUT and OUTPUT commands.  Type HELP C-ESCAPE-SEQUENCES, INPUT or
OUTPUT for further information.

Switches may be given to copy the given text into one or more of the
logs that Kermit keeps.  This is useful for commenting on or otherwise
identifying particular test cases.  Giving a switch for a log that is
not open is silently ignored.

Note that switches must be given before the text that is to be echoed,
otherwise they will be considered text and merely echoed rather than
being acted on.  Switches are not considered part of the text to be
echoed, thus

   Kermit-20>ECHO /Debug /Trans /Sess "\n\t\qNo switches Echoed\q\r\n"

will result in only the following string being displayed:

	"No switches Echoed"

Echo will display the text as 8 bit bytes, respecting whatever parity
Kermit is told to use, regardless of whether the line discipline
supports it or not.

This isn't really useful for anything but debugging and internal
checkout.  In many cases, abject gibberish will be displayed,
depending on the character font of the terminal or rendering device.
Type HELP SET PARITY for more information.

ECHO also has an invisible /UPPERCASE switch, which removes all
leading white space (I.E., tabs and spaces) and after doing so,
converts remaining text to uppercase.  It is used purely for internal
checkout.
&

	subttl Help text for QUIT and EXIT

hquit:	asciz |
QUIT

Synonym for EXIT.
|

hexit:	asciz |
EXIT

Exit from Kermit-20.  You can CONTINUE the program from the TOPS-20
Exec, provided you haven't run another program on top of it.  You can
also exit from Kermit-20 by typing one or more control-C's, even if
it's in the middle of transferring a file.  Kermit-20 will always
restore your terminal to its original condition, and you will be able
to CONTINUE the program to get back to Kermit-20> command level.  When
you EXIT from Kermit-20, any open files, including logs, will be
closed.
|

	subttl Help text for HELP command

hhelp:	asciz |
HELP [topic]

Typing HELP alone prints a brief summary of Kermit-20 and its
commands.  You can also type

   HELP command

for any Kermit-20 command, e.g. "help send", to get more detailed
information about a specific command.  To see a list of all the
available help commands, type

   HELP ?

or consult the Kermit User Guide.
|

	subttl Help text for INPUT command

hinput:	asciz &
INPUT [/SILENT] [interval] [ "quoted text string" | text-string ]

INPUT is useful with OUTPUT and PAUSE for sending connect and login
sequences to a remote host, e.g. over a dialout or network connection.

On the currently selected communication line, network or virtual
connection, look for the given string for the specified time interval.

If no interval is specified, then wait for the default interval, which
is 5 seconds unless changed by SET INPUT DEFAULT-TIMEOUT.  An interval
of 0 means no timeout (wait forever).  A negative time will result in
a parse error.

Typing only a carriage return and no parameters at all will cause the
default interval to be used and the default search string to be used.
If no search default has been given with a SET INPUT SEARCH-DEFAULT,
then a default sequence of carriage return, line feed will be used.

Fractional seconds may be given for n, such as 1.25.  These will be
converted to the nearest millisecond value.  Such short waits may be
useful for communicating with extremely fast remote machines over very
high speed lines.

They are also used for debugging and stress testing.  Unless you are
actively debugging or the machine is very lightly loaded, it is unwise
to perform stress tests.

Characters coming in from the connection will be scanned for the
search string, and when a match is found, the command will terminate
successfully.  If the string is not found within the given interval,
the command will terminate unsuccessfully.  While the INPUT command is
active, all incoming characters will appear on your screen.

The search string may contain any printable characters.  Control or
other special characters may be included by preceding their octal
ASCII value with a backslash, for instance foo\15 is "foo" followed by
a carriage return,  \100 is an atsign (@).

Another way of writing "foo\15" would be "foo\r" because certain
common C language escape sequences, which are useful for their
mnemonic value, are recognized.  Type HELP C-ESCAPE-SEQUENCES for
further information on these.

Alphabetic case is ignored ("a" = "A") unless you have SET INPUT CASE
OBSERVE.  If no search string is given, then the INPUT command will
keep operating until it times out.

As INPUT scans the character stream for a match, it displays the text
on the terminal under the assumption that these are system responses
that the user will want to see.  This is essential for understanding
what might have gone wrong on a failure.

However, this might not be desirable for commands which produce
copious output, in a batch environment or for certain types of
debugging.  For this reason, the /SILENT switch may be used to discard
this text and not print it.  Caution should be used because any error
messages will also be discarded when /SILENT is in effect.

As such, /SILENT processing can not be set as a default for the input
command.  It must be issued for each and every command.

If the INPUT command fails to find the requested string within the
given interval, it will "fail"; if the INPUT command was issued from a
command file (see TAKE), then the next command will be executed,
unless you have SET INPUT TIMEOUT-ACTION to QUIT, in which case the
command file will be terminated.  An INPUT command can by interrupted
by typing two ^C's.

A quoted string may prove useful for interactive prototyping or to
allow Kermit to recognize an at-sign (@), the Tops-20 prompt.  

Type HELP SET INPUT for further information.
&

	subttl Help text for OUTPUT command

houtpu:	asciz &
OUTPUT [ "quoted text-string" | text-string ]

The given string is sent out the currently selected physical
communication line, pseudo-terminal or network connection.  A quoted
string may prove useful for interactive prototyping or to allow Kermit
to emit an at-sign (@) while retaining the ability to use indirect
files.

Typing a simple carriage return will emit a bare ASCII carriage return
(octal 15).  Control characters may be included in \ooo format, that
is, a backslash followed by the octal numeric representation of the
ASCII value.

In addition, certain common C language escape sequences, which are
useful for their mnemonic value are recognized.  Thus, the \015 may be
more easily written as \r.  Type HELP C-ESCAPE-SEQUENCES for further
information.

Type HELP INPUT for further background
&

	subttl Help text for C escape sequences

hcescp: asciz &
The following ANSI C escape sequences are recognized by Kermit-20:

	 Escape		Octal		 Character
	Sequence     ASCII Value	Description
	========     ===========	===========

	   \a		   7		Alert (Beep, Bell)
	   \b		  10		Backspace
	   \t		  11		Horizontal Tab
	   \n		  12		Line Feed (Unix Newline)
	   \v		  13		Vertical Tab
	   \f		  14		Formfeed (Page Break)
	   \r		  15		Carriage Return (bare, no line feed)
	   \"		  42		Double quotation mark
	   \'		  47		Apostrophe or single quotation mark
	   \?		  77		Question mark (used to avoid trigraphs)
	   \\		 134		Backslash

	   \e		  33		Escape character

	   \c		   3		ETX (Control-C, useful for DEC OS's)
	   \d		   4		EOT (Control-D, Unix end of file)
	   \o		 177		DEL (I.E., rubout or obliterate)
	   \q	          42		Double quote (for use inside quoted strings)
	   \u		   0		NUL character (I.E., nUl)
	   \z		  32		SUB (Control-Z, Tops-10/20 end of file)
	   \@		 100		Tops-20 default EXEC command prompt
	   \.		  56		Tops-10 monitor prompt

At-sign is probably best managed inside a quoted string.  As an
example, searching for "foo" followed by a Tops-20 newline and EXEC
prompt might be written as "foo\r\n@".

Note the following:

    1)	All octal values are range checked to US ASCII seven bits and
	an error is thrown if this limit is exceeded.  An IBM system
	is expected to be front-ended with the appropriate converter
	to handle explicit EBCDIC values.

    2)	Digits 8 and 9 will fail an octal conversion, terminating the
	entire expansion.  All other characters will merely silently
	stop an octal conversion.

    3)	In all cases, Kermit will not process more than eleven octal
	digits after a backslash.

    4)	Newline on Tops-20, Tops-10 and other DEC operating systems is
	unlike Windows, Unix or Multics, where it is the single
	character "\n".  The proper sequence to search for is "\r\n",
	in that order. 

    5)	Unlike C, its derivatives or imitiations, escape sequences in
	Kermit-20 do not carry the limitation of being case sensitive,
	meaning \N will produce the same value as \n (octal 12).  This
	is in keeping with all parsing under Tops-20 and allows for a
	user to provide emphasis.

    6)	Any character that is not in the above table will cause an
	error.

    7)	Because of the string instructions being used, it is far more
	efficient to search for a single character.  For example, on
	Tops-20, when searching for the result of an EXEC command,
	INPUT "\@" will execute with substantially less processor
	overhead then INPUT "\r\n\@". 

    8)	\" will not work in a quoted string, use \q instead.

    9)	\e for the escape character (Octal 33, decimal 27, hexadecimal
	1B) is non-standard, but is recognized by many C
	implementations.

   10)	The last eight items (\c, \d, \o, \q, \u, \z, \@ and \.) are
	also non-standard, being unique to Kermit-20.
&


	subttl Help text for specifying Control Characters

hcchar:	asciz |
Where it is necessary to specify an ASCII control character (for
example, when setting the ESCAPE or HANDSHAKE characters), Kermit-20
provides the user with some flexibility.

The basic problem with specifying a control character is that these
are frequently used by operating systems and applications as a source
of interrupts to signal specific conditions or requests.  Therefore,
the character may not be directly available interactively and
difficult to insert into a KERMIT.INI file.

Kermit allows a control character to be specified in one of two ways,
the first being to simply type the octal numeric value.  For example,
015 might be typed to indicate a carriage return.  However, unless you
happen to have an eidetic or otherwise photographic memory, recalling
these values can be challenging in the absence of a handy table (which
can be its own challenge).

The easier way to do this with Kermit is to type the carat or "^"
character (also known as the up arrow character) followed by another
character.  This is intended as a mnemonic aid.

For example, when typing a ^B (ASCII 002) normally, the "B" key is
'chorded' with the Control key.  This means that the Control key is
pressed and held down and while being held thusly, the "B" key is
pressed and released and then the Control key is released.  The
resulting character (ASCII 003) is then generated and it is commonly
displayed as "^B".

In order to specify this ^B (or Control-B) to Kermit, the user would
simply type the carat character followed by the letter "B".  Kermit is
caseless in this regard, so either "^b" or "^B" will work.  As with
all native Tops-20 programs, escape and question mark may be used,
viz:

Kermit-20>SET ESCAPE ^ ? ASCII control character one of the following:

 A    B    C    D    E    F    G    H    I    J    K    L    M    N
 O    P    Q    R    S    T    U    V    W    X    Y    Z
  or to specify the NUL character, type "@"
  or to specify the ESCAPE character, type "["
  or to specify the file separator character, type "\"
  or to specify the group separator character, type "]"
  or to specify the record separator character, type "^"
  or to specify the unit separator character, type "_"
  or to specify the rubout or delete character, type "/"

Kermit-20>SET ESCAPE ^

The carat and printable character to control character mapping is as
follows:

     Control   Octal	     Control   Octal	     Control   Octal
    Character  Value	    Character  Value	    Character  Value

	^@	 0		^K	13		^V	26
	^A	 1		^L	14		^W	27
	^B	 2		^M	15		^X	30
	^C	 3		^N	16		^Y	31
	^D	 4		^O	17		^Z	32
	^E	 5		^P	20		^[	33
	^F	 6		^Q	21		^\	34
	^G	 7		^R	22		^]	35
	^H	10		^S	23		^^	36
	^I	11		^T	24		^_	37
	^J	12		^U	25		^/     177

Note that the use of up-arrow forward slash is non-standard as the
more typical way of representing rubout would be up-arrow question
mark ("^?").  This is not possible with Kermit-20 as question mark
gives the menu shown above.  Forward slash is used as it is on the
same key as question mark is, unshifted on many keyboards.
|


      subttl Help text for PAUSE command

hpause: asciz |
PAUSE interval

Pause for the given number of seconds.  Useful with INPUT and OUTPUT.

There is no realistic maximum of seconds, other than what is imposed
by the PDP-10's arithmetic and Tops-20's acceptance of the dismiss
time.  It is probably not useful to sleep for more than a few minutes.

The interval is assumed to be seconds, yet is parsed is a floating
point number, which will be converted into milliseconds to allow for
greater granularity of waits and debugging.

The smallest pause value is 0.001 or one millisecond.  A negative
value will be rejected.
|

      subttl Help text for TIME command

htime:	intern htime		;[214] 
	asciz \
TIME device-keyword | COPY | device: [/switches]

Performs basic communications checks and timing tests on the specified
device.  These are not normally required as is not necessary to time a
physical line because the baud rate can be gotten from the monitor.

TIME exists largely for network transport code validation and for the
verification of certain internal self-checks.  The speed results may
be used as a basis for populating the device efficiency portion of the
statistics command, but this will probably mean very little.

TIME is not necessary in any way to a regular user, having use only to
a programmer.  Because of this, the TIME command is invisible and does
not show up as a keyword when a question mark list given to either the
top-level or HELP command prompt.

A timed device keyword may be one of the following which also may be
specified by the cooresponding unpunctuated device name:

          data-sink - NUL, for NUL: device
             DECnet - DCN or SRV, for DCN:/SRV: pair
               pipe - PIP, for PIP: device
    pseudo-terminal - PTY, generic PTY: devices

This allows for the device name to be specified with escape
recognition without punctuation and for the unit number to not need to
be specified.

    COPY from-device to-device

Used to copy test results from one device to the other, which has the
effect of causing the to-device to appear to have a different virtual
speed than what was measured.  This is used for algorithm checkout,
edge case testing and providing abnormal inputs to trigger error
recovery.

Transfer results checking is typically on a byte-by-byte comparison if
parity is set to NONE.  However, if parity checking is turned on, then
the timing routines will use that parity to check results.  This is
for the purpose of validating the parity implementation--it is slower
to check by parity.

For an idiomatic device type or explicitly specified device name, a
switch may be one or more of the following: /BYTESIZE: /MODE: and
/RECORD-LENGTH:.  TYPE HELP TIME /switch for more information about each
one.

CAUTION:

   1)   Not all devices support all switch options
   2)   Not all devices support all switch values
   3)   On a pseudo-terminal, the post transfer check will ALWAYS fail
        for any byte size greater than 8, even if the device is opened
        in IMAGE mode.  This the nature of the terminal driver.
   4)   Timing results can vary wildly, based on whatever else the
        system happens to be doing.
   5)   A test may time out on a heavily loaded system.  It is
        probably anti-social to keep trying immediately.
   6)   The virtual speed is calculated by characters sent, the
        default being 8 bit characters.  Since a character (or byte)
        on the PDP-10 can vary between 1 and 36 bits, the reported
        speed will change with different byte sizes, but the
        differences may be counter-intuitive, if not flat out
        meaningless.
   7)	An odd byte size may trigger other false negatives.  "Odd" in
	this case does not mean that bit 35 is set, it means very
	uncommon or 'strange'; say a byte size of 13, for example.
\

	subttl Help for TIME switches

htbyte:	asciz |
/BYTESIZE: decimal-number

    Requests a decimal number between 1 and 36.  Not all devices
    support all byte sizes.  DECnet, for example, will only support
    byte sizes of 7, 8 and 36; eight being the most efficient.

    The data used for the timing tests is formed internally from a
    sequence of thirty six bit words, each consisting of four 8 bit
    bytes with monotonically increasing values followed by a single
    four bit field with monotonically increasing value.  The 8 bit
    fields will wrap after 377 octal while the 4 bit field wraps after
    17 octal.

    The default byte size used to calculate transfer speeds is 8 bit.  
    Since speed is bytes sent divided by elapsed microseconds, a
    smaller byte size will result in a faster speed being calculated
    for a transfer that took the exact same wall time because the
    number of bytes has increased.

    Thus, the displayed speed may first appear to be counter-
    intuitive, whereas it is actually likely to be devoid of any
    useful information.

    It is possible to specify a pathological byte size which will
    cause the post transfer validation tests to fail and drastically
    change computed transfer times.  Such results are either all false
    negatives or useful only for debugging.

    For example, while DECnet will explicitly refuse an OPENF% that
    does not specify a byte size 7, 8 or 36, PIP: and PTY: will accept
    the parameter without complaints.  However while transfers against
    PIP: will work, the exact same transfer against PTY: will be found
    to have errors.  Strictly speaking, these are not errors but
    rather a result of the nature of the monitor's terminal driver
    (TTYSRV).

    In all cases, a negative, zero or byte size greater than 36 will
    be rejected.
| ;[214] 

htmode:	asciz &
/MODE: (DUMP) | IMAGE | NORMAL | SMALL

    The keyword may be one of the following: IMAGE, NORMAL or SMALL. 
    Be aware that not all devices support all modes.  While Kermit
    will parse for all values, some of them will fail.  In this case,
    a failure is defined behavior and not indicative of any true
    problem.

    NORMAL means different things, depending on device context.  For
    pseudo-terminals, it will cause the monitor to interpret certain
    characters as opposed to doing a straight passthrough.  Otherwise,
    it means to use normal buffering and flushing.

    SMALL mode is for the monitor to use smaller buffers and/or flush
    them more frequently, giving perhaps better interactive response.
    It is valid only for DECnet and pipes. 

    IMAGE mode is for the monitor to not process characters going
    through the device, which can result in less CPU usage.  Only
    pseudo-terminals will accept IMAGE, which is set via the
    associated controlled terminal line. 

    DUMP is an invisible MODE keyword.  No current Kermit transport
    device supports DUMP mode, however this selection can be specified
    and is used to test and debug device open failure recovery.

NUL: device considerations:

    Be aware that /MODE can not be specified for the NUL: device.
    This is because the NUL: test uses the special JFN, .NULIO.  As no
    GTJFN% is ever done on NUL:, no OPENF% is done and thus there is
    nothing to pass the MODE value to.

    Since writing to NUL: has the expected effect of throwing data
    away, certain post-transfer operations (such as parity checking)
    are impossible.
& ;[214] 

htreco:	asciz |
/RECORD-LENGTH: decimal number

    This switch is valid only for the PIP: (pipe) device and cannot be
    specified for any other.

    Specify a decimal number between 1 and 511 for the size of records
    to write to the pipe device.  A negative or zero record-length
    will be rejected.

    Generally speaking, larger record sizes will result in faster
    transfer times.
| ;[214] 

      subttl Help text for the TAKE command

htake:  asciz |
TAKE filespec

Execute Kermit-20 commands from the specified file.  The file may
contain contain TAKE commands.  Command files may be nested up to a
depth of 20.

If you have a file named KERMIT.INI in your login directory,
Kermit-20 will execute an implicit TAKE command on it upon initial
startup.  While the KERMIT.INI file may contain any sequence of
Kermit-20 commands, DEFINE and SET commands are typically among the
most useful.

TAKE file processing may be prematurely terminated with the RETURN
command.  See HELP RETURN for further information.

Once the set of Kermit-20 macros is relatively stable, it is faster to
put all the DEFINE commands at the end of the file and precede with a
DEFINE /MAP, followed by a RETURN.  They may be dumped in binary format
beforehand with a DEFINE /DUMP.

See HELP DEFINE /DUMP and HELP DEFINE /MAP for more information.
| ;[237] 

      subttl Help text for the RETURN command

hretur:  asciz |
RETURN

Immediately terminates processing of the current TAKE file and either
returns processing to the TAKE file which invoked it or goes to top
level.  It is not an error to issue a RETURN at the terminal, but it
does nothing useful other than informing you that you are not
currently taking commands from a file.

The purpose of the command is multi-fold.  First, in addition to
judicious use of ECHO commands, stopping TAKE file processing can be a
significant debugging aid.

Second, RETURN allows information to be kept in the TAKE file which is
not parsable, such as free form comments or commands which are no
longer necessary.

Third, and perhaps most importantly, RETURN can also substantially
speed up start up times for KERMIT.INI's which have a large number of
macro definitions.

In this case, instead of having multiple seperate lines defining macro
names and bodies, a single DEFINE /MAP can be given to directly map
them into memory and .INI processing stopped.  The previous DEFINE
statements can then follow the RETURN and will be ignored.

Thus, imagine the following macro definitions:

    define foo flow-control none
    define bar duplex full
    define baz parity even
    define boo handshake none
    define CU20B set prompt "CU20B>"
    <End-of-File>

If DEFINE /DUMP:KERMIT.BIN is used to save them into binary format,
then the following is going change the number of necessary COMND%
parses from thirty to five, which is a reduction by a factor of six.

    DEFINE /MAP KERMIT.BIN
    RETURN
    define foo flow-control none
    define bar duplex full
    define baz parity even
    define boo handshake none
    define CU20B set prompt "CU20B>"
    <End-of-File>

See HELP DEFINE for further information on macros.  Be aware that
DEFINE /COMPACT should be used before dumping macros to use the
minimum amount of disk space.  See HELP TAKE for further information
on the TAKE command.
| ;[237] 

      subttl LOCAL command help text.

hlocal: intern hlocal           ;[214] 
        asciz |
LOCAL option

Execute a command locally.  Options include:

 CWD                    Change Working Directory (connect to directory).
 DELETE filespec        Delete a file or file group.
 DIRECTORY filespec     Print a directory listing.
 HOST command           A command to be executed by the TOPS-20 Exec.
 RUN program            Run the specified program.
 PWD                    Print Working Directory
 SPACE                  Disk usage query.
 STATUS                 Status of last transfer
 TYPE filesec           Type a local file or file group at the terminal.

For further information, type HELP LOCAL CWD, HELP LOCAL DELETE, etc.

These commands are also available at the top-level.  For example PWD
alone will execute the exact same code as LOCAL PWD.  Similarly,
HELP PWD will display precisely what HELP LOCAL PWD.
|

      subttl Help text for SPACE command

hspace: asciz |
SPACE

SPACE is the same as LOCAL SPACE.   It tells the number of disk pages
allowed and in use in the currently connected local directory.
|

      subttl Help text for STATISTICS command

hstatl: asciz |
STATISTICS

STATISTICS is the same as LOCAL STATUS,  It gives information
about the last transfer.

Note, when issued as a REMOTE STATUS command, the information shown
can only displayed once because the operation of the REMOTE counts as
a transfer.  Issuing the command again will provide statistics about
the previous REMOTE STATUS command itself.
|

      subttl Help text for the PWD command

hpwd:   asciz |
PWD

PWD is the same as LOCAL PWD.  It displays the currently connected
local directory.
|

      subttl Help text for the RUN command

hrun:   asciz |
RUN [filespec]

RUN is the same as LOCAL RUN.  It runs the specified file as a program
in a fork underneath Kermit-20, which is known as a sub-fork.  The
default file type is .EXE.

Although Tops-20 will allow you to run a program from magnetic tape,
Kermit-20 will not; the file must reside on a directory based device.
The sole exception is that you can run a program from NUL:, which
causes a fork creation and a small program to be run from the
sub-fork's accumulators.  This is used for testing and debugging.

When the program terminates, you will be back at Kermit-20 prompt
level.  If you want to issue Exec commands without leaving Kermit-20,
you can RUN SYSTEM:EXEC.EXE, and then type POP to get back to KERMIT.

If you have already RUN a program once, you can run it again without
the overhead of fork creation by typing the RUN command without an
argument.
|


      subttl Help text for the TRANSMIT command

htrans: asciz &
TRANSMIT [[/SILENT] [/TIMEOUT n] [ /EOF ^Z | ^D | $ | ^G ]]
	filespec [ prompt | "prompt" ]

Intended for use in local mode only, but will function in remote mode
for debugging purposes.  Sends the specified text file a line at a
time to the remote system, waiting for the specified prompt for each
line.  Kermit protocol is not used; the file is sent "raw".

The file is expected to be a sequence of variable length ASCII lines,
each terminated by a carriage return (\r or octal 15), linefeed (\n or
linefeed) The final linefeed will be clipped out of the text that is
sent.  Problems may happen for files which use bare carriage returns
for the purposes of overprinting.

Only a single file may be sent, no wildcards are allowed in the
filespec.  The file must exist on a file structure to which you either
have or have gained access.  No other device is permitted with the
exception of NUL:, which is only used for debugging and testing
purposes.

It is strongly recommended that this file not be particularly large
nor have very long lines (see below).

The prompt is any string, for instance, the prompt of a line editor in
text insertion mode.  The prompt string may be enclosed in quotes and
may include special characters by preceding their octal ASCII values
with a backslash (e.g. \15 for carriage return) or C escape sequence
(e.g., \r being converted into octal 15).  Type HELP C-ESCAPE-
SEQUENCES for further information.

If a prompt string is supplied, then alphabetic case will be ignored
in searching for it unless you have SET INPUT CASE OBSERVE.  If a
prompt string is not supplied, then the following defaults will be
tried, in order:

    1)  If a SEARCH-DEFAULT has been specified with SET INPUT, then
        this will be used.
    2)  If you have performed a SET HANDSHAKE command, then that
        handshake character will be used.
    3)  If neither 1 or 2 apply, then linefeed will be used.

Set INPUT for further information on search string matching.

The file will be sent using the current settings for duplex, parity,
and flow control.  Timeouts may be given via setting an INPUT TIMEOUT
or via the use of the /TIMEOUT switch You may do a /TIMEOUT 0 to cause
Kermit to wait forever for each prompt to appear.  You may use the
following control characters during TRANSMIT:

  Carriage Return - Send the next line immediately, even if the prompt
                    hasn't appeared.  Note that in remote mode, an
		    input string which includes \r will not work.
  Control-P       - Resend the previous line.
  Control-C       - Typed two or three times will cancel the TRANSMIT
                    command and return you to the Kermit-20> prompt.
                    You may then need to do a number of CLEAR/FLUSH's.

The optional /EOF switch may be used to indicate that a particular 
character should be sent when the End-of-File (EOF) condition is
detected.  The following EOF characters are supported:

    ^Z	Used by DEC operating systems, such as Tops-10 and Tops-20,
	IBM/Microsoft OS's, such as DOS, OS/2 and Windows.  Note that
	the later systems will require a line terminator after the ^Z.
    ^D	Used by Unix type systems, such as Linux, Mac OSX and Ubuntu.
     $	Dollar sign is used as a talisman for the escape character,
	which is used by Tops-10 and others as a line terminator.
    ^G	Used by certain DEC CUSPs, such as PIP and audible debugging.
	Be aware that if Kermit is run with Control-C capability
	disabled, then it will use ^G instead, which will override
	its use here.

The file is always sent as an eight bit stream, even if it is seven
bit ASCII.  An eight bit file is expected to never have bit 0 set in
any byte.  If no parity is in effect, this bit is left alone and sent
as is, which may cause confusion on the receiving system.

If this turns out to be a problem, then SET PARITY SPACE (or ZERO),
will keep bit 0 cleared.  If parity is in effect, then bit 0 will be
ignored and the byte is processed as if it were 7 bit ASCII, thus
eventually overwriting the bit.

As TRANSMIT scans the character stream for the prompt, it displays the
text on the terminal under the assumption that these are system
responses to commands (which were perhaps via OUTPUT) that the user
will need to see.  Reviewing the responses is essential for
understanding what might have gone wrong in the case of a failure.

However, this behavior might not be desirable for commands which
produce copious amounts of output, in a batch environment or for
certain types of debugging.  For this reason, the /SILENT switch may
be used to discard this text and not print it.

Be aware that any and all error messages will also be discarded when
/SILENT is in effect.  As such, /SILENT processing can not be set as a
default for the transmit command.  It must be issued for each and
every command.

Great caution should be exercised when using this command as it can
crash communications systems, hang network connections and otherwise
wedge other terminal based data paths.  The safest approach may be to
split the file up into several smaller pieces and do the TRANSMIT of
each separated by PAUSE's at off hours in a batch job.

Recall that the whole point of the Kermit protocol was specifically to
avoid this situation with DECSYSTEM-20 PDP-11 front end.  Although
these systems are only museum pieces now, their network
implementations can still hang if pushed too hard.

If the wedge is bad enough, somebody may have to reboot the remote
computer, which risks making you unpopular with the staff or owner if
it happens often enough.

If you really want to send the entire file without looking for any
prompts, specify a prompt of "\0" (ASCII zero or NUL).  This will
almost surely hang any computer which does not have a dedicated, real
time input facility, particularly if this is done at Ethernet speeds.
This is commonly done only for testing and debugging purposes on
pseudo-terminals.
&

      subttl Help text for the TYPE command

htype:  asciz |
TYPE filespec

TYPE is the same as LOCAL TYPE.  It types the specified file or files
at your terminal.  Unlike the DEC-20 TYPE command, it will try to do
input from each file based on its byte size.  Also, Control-O output
suppression applies only on a per-file basis.

The file must exist on a file structure in a directory to which you
have or can gain access.  All other devices are rejected except for
NUL:, which displays nothing useful.  NUL: is provided for debugging
and check out purposes.

For testing purposes, parity is applied to the output, should this be
indicated by a SET PARITY command.  This is independent of whatever
parity setting might be in effect for the terminal or indeed whether
the line supports parity at all.
|

      subttl Help text for the REMOTE command

hremot: intern hremot
        asciz |
REMOTE command

Ask the KERMIT server on the other end of the connection to execute a
command on its own system.  The REMOTE command does not work unless
you are running in local mode (I.E., you have done either a SET LINE n
or a SET HOST x::) and the KERMIT on the other end is running as a
server.

Commands include:

 CWD                    Change Working Directory (connect).
 DELETE filespec        Delete a file or file group.
 DIRECTORY filespec     Send a directory listing.
 HELP                   Provide a brief summary of Kermit-20 remote commands.
 HOST command           Execute command with remote system's command processor.
 PWD                    Print Working (or connected) Directory
 SPACE                  Disk usage query.
 STATUS                 Provide statistics on last transfer
 TYPE filesec           Type a file or file group at the terminal.

In addition to a simple text string, all commands which take foreign
file or directory specifications will optionally parse these as quoted
strings.  This is useful for operating systems which allow embedded
spaces to be used in these cases.

Note: While Kermit-20 implements these commands, not all other Kermit
implementations do.  Therefore, an error may be a simple statement of
this fact rather than an indication of any actual problem.

For example, like a number of older implementations, earlier versions
of Kermit-20, do not implement PWD (Print Working Directory).
|

      subttl Help Text for the REMOTE CWD command

hrcwd:  asciz &
REMOTE CWD [ text | "text" ]

Change the working directory on the remote system.  The intended
effect is that this will become the default area that the remote
system will attempt to create or find files, absent an explicit
specification of the area.

The text may optionally be inclosed in quotes, which may help in
operating systems that contain characters that would not normally
be found in a Tops-20 directory, such as a folder with a trailing
space.  In other words, "FOO " would be different than FOO alone.

Be aware that CWD is a Unix term and that other operating systems may
have subtle to vastly different understandings of what this means.
Type HELP CWD for an explanation of the Tops-20 nuances.

One example of such a diference is Tops-10 Kermit, which implements
paths instead of working directories.  A Tops-10 path can be seen to
be a set of multiple working directories to try for file operations.
When creating a file, Tops-10 will look through the path for a UFD
or SFD with available space.
&

      subttl Help Text for the REMOTE DELETE command

hrdele: asciz &
REMOTE DELETE text | "text"

Requests the remote Kermit server to remove a file on the remote
system.  A file specification may be given as simple text or enclosed
in double quotes.  Unless a directory, path or prefix is given, the
file will be looked for in what the remote system has been
conditioned to use as the current working directory.  See HELP
REMOTE CWD for more information on this concept.
&


      subttl Help Text for the REMOTE DIRECTORY command

hrdire: asciz &
REMOTE DIRECTORY text | "text"

Requests the remote Kermit server to list information about one or
more files on the remothe system.  A file specification may be given
as simple text or enclosed in double quotes.

Unless a directory, path or prefix is given, the file will be looked
for in what the remote system has been conditioned to use as the
current working directory.  See HELP REMOTE CWD for more information
on this concept.

In order to list more than one file, the user will probably need to
understand the remote system's idea of wildcards and what can be wild
carded in a file specification.  For example, systems such as VMS, RSX
and Tops-20 define file specifications with sufficient syntax so as to
allow a directory to be wildcarded.

While Unix systems will allow full regular expressions to be used, it
is not possible to traverse a set of directories because the file
syntax makes what is a directory and what is a file ambiguous.

If the listing contains the space used by a file, then the user should
be aware that these units may be quite different.  See HELP REMOTE
SPACE for more information.
&


      subttl Help Text for the REMOTE ERROR command

hrerro: asciz &
REMOTE ERROR [ text | "text" ]

Used to send an "E" packet to the remote system.  If the connection
becomes wedged and doing a number of CLEAR's has not worked, this may
get the remote Kermit into a defined state.

Text may be specified and the remote Kermit should display this.

Be aware that sending an unsolicited "E" packet may cause certain
Kermit implementations to stop and exit.  Tops-10 Kermit is one
such example.
&


      subttl Help Text for the REMOTE HELP command

hrhelp: asciz |
REMOTE HELP

Requests the remote system to send a brief summary of those commands
which are available for use.  It is not possible to request additional
help granularity using this command.  Many Kermit implemenations have
built-in help, some of it quite extensive.  However, it will probably
be necessary to connect to the system and run that Kermit interactively.

Be aware that a remote Kermit may list commands that Kermit-20 does
not implement parsing for.  Thus, even though they are there, they can
not be used.
|


      subttl Help Text for the REMOTE HOST command

hrhost: asciz &
REMOTE HOST text | "text"

The given text, which may be enclosed in quotes, is given to the
remote Kermit to be executed using the remote system's command parser.
To be specific, the text in question will NOT be executed by the
foreign Kermit but rather given to whatever parses regular system
commands.

Be aware that this command may not be implemented and may be of
limited utility.  Operating systems which do not implement a process,
task or fork structure may not be able to concurrently run the
command processor along with the remote Kermit.

The remote Kermit is only obligated to respond that the command was
successfully transported.  There may be no way to determine whether
it was successfully executed nor any mechanism to transport any
output back to the local Kermit.

Kermit-20 currently will parse for REMOTE HOST, but does not implement
it and therefore will not accept it from a foreign host.
&


      subttl Help Text for the REMOTE PWD command

hrpwd:  asciz |
REMOTE PWD

Print the current working directory.  See HELP REMOTE CWD for an
explanation of what a working directory can mean.

Be aware that not all Kermit's implement PWD (Generic packet type
"A").  Tops-10 Kermit does not and neither do earlier versions of
Kermit-20.

One work-around may be to try REMOTE SPACE as this often lists
what is being used as the current working directory.
|


      subttl Help text for the REMOTE SPACE

hrspac: asciz |
REMOTE SPACE

Asks the remote Kermit to provide information on available storage for
file creation.  This is typically, although not always, relative to
the current working directory.  See HELP REMOTE CWD for further
explanation on what this might mean.

The user is expected to understand the units being displayed.  For example,
a Unix based Kermit will report in 8 bit bytes.  Other systems may display
something vastly different.

For example, Tops-20 will report the number of pages (see HELP LOCAL
SPACE).  Each page can store 512 thirty six bit words, that can store
either four 8 bit sized bytes or five 7 bit sized bytes.  Thus, each
page can be seen as the equivalent of 2,048 (2 KB) of Unix data or
2,560 (2.5 KB) of ASCII data.

Tops-10 has similar format representations but reports Blocks, which are
units of 128 thirty six bit words.

Not all the storage may be available.  For example, the directory storage
limits may be more than what is available on the file structure.
|


      subttl Help text for the REMOTE STATUS command

hrstat: asciz |
REMOTE STATUS

Requests the remote Kermit to report its current status, which will
typically include information about data transfers.

Be aware that it is entirely up to the remote system to determine what
to display and that Kermit-20 has no control over this.  As a
comparison, Kermit-20 displays fairly comprehensive information about
the last transfer only, while Kermit-10 displays less information
overall, the information contains data transfer totals.

TYPE HELP LOCAL STATUS for more information on Kermit-20's display.
|

      subttl Help text for the REMOTE TYPE command

hrtype: asciz &
REMOTE TYPE text | "text"

Causes the referenced remote file to be displayed on the local
terminal instead of being stored on the local disk.

Certain Kermit implementations will allow the file specification to
be wildcarded, resulting in more than one file being listed.  See
HELP REMOTE DIRECTORY for more information.
&


      subttl Help text for the SET BLOCK-CHECK command

hsbc:   asciz |
SET BLOCK-CHECK option

A block check is a quantity formed by arithmetically combining all the
characters in a packet.  The sender of the packet appends the block
check to the packet and the receiver recomputes the block check and
compares it with the one that was received.

If they don't agree, the packet is retransmitted.  The SET BLOCK-CHECK
command is used to request one of three block check techniques:

     1-CHARACTER-CHECKSUM
        The standard KERMIT 6-bit checksum, the most efficient of the
        three options, sufficient in almost every case.  This is the
        default.
     2-CHARACTER-CHECKSUM
        A 12-bit checksum.  Adds transmission overhead, but catches
        more errors.
     3-CHARACTER-CRC
        A 16-bit cyclic redundancy check.  Adds even more communicates
        and processor overhead, yet catches even more errors.  Only
        use this for very noisy connections.

Kermit-20 will request the type of block check set by this command be
used for a transfer.  If the other KERMIT agrees (not all KERMITs know
how to compute the 2- and 3-character block checks), then the desired
block check type will be used.  If not, the single character checksum
will be used.
|

      subttl Help text for the SET INCOMPLETE command

hsabf:  asciz |
SET INCOMPLETE options

Specify what to do when a file transfer fails before it is completed.
The options are DISCARD (the default) and KEEP.  If you choose KEEP,
then if a transfer fails to complete successfully, you will be able to
keep the incomplete part that was received.

Note that Kermit-20 can not restart a transfer at a particular point,
in contrast to what might be possible with the FTP REST verb.
Therefore, although it may be useful to have a portion of the file,
the only way to get the whole file is to start the transfer from the
beginning of the file.
|

      subttl Help text for the SET BREAK command

hsbrea: asciz |
SET BREAK n

Specify the number of nulls to be sent at 50 baud to simulate a BREAK
signal when connected to a remote host via SET LINE and CONNECT.

The BREAK signal sees use in full duplex auto-baud detections and in
half duplex situations when the currently executing job or process
must be stopped.

Auto-baud is not done with pseudo-terminals (PTY's) nor with DECnet
Network Remote Terminals (NRT's) because the speed is not known.  You
may use ^C to stop a Tops-10 job or a Tops-20 fork instead of BREAK.
|

      subttl Help text for the SET DEBUG command

hsdeb:  asciz |
SET DEBUG options [/DECODE]

Show packet traffic explicitly on your terminal (if local) or in a
file.  Options are:

     STATES   Show Kermit state transitions and packet numbers
              (brief).

     PACKETS  Display each incoming and outgoing packet (lengthy).

     OFF      Don't display debugging information (this is the
              default).  If debugging was in effect, turn it off and
              close any log file.

To record debugging information in a file, use LOG DEBUGGING.

When debugging packets, the default is to dump the raw data.  Giving
the /DECODE switch will cause Kermit to break out some of the fields,
which can aid when trying to trace down a protocol issue.

Caution:

The log file previously had a time of day time stamp that was only
accurate to the second.  With high speed transfers, this is not nearly
enough resolution.

While it is possible to time intervals to 100 kHz (I.E., DK10)
resolution, it is fundamentally impossible to accurately correlate
such intervals with the time of day.  This is because Tops-20 keeps
the time of day as an 18 bit fixed point fraction, which works out to
a 'Time of Day' tick being approximately 329.58858646932 milliseconds.

However, there is no way to tell when Tops-20 will advance this
because the last system set time (TADIDT) as calculated STAD% is not
available nor is the millisecond uptime counter that is used to
calculate it.

The problem is made worse because there is thus no public correlation
between HPTIM%, either.  Trying to guess or simulate this can result
in time stamps that appear to go backwards in time.

The problem really can't be resolved without a change to Tops-20 to
make the TADIDT available and to store the elapsed millisecond clock
that was used to do the calculation.

This is not a problem for commands that display elapsed time, such as
CLEAR.  It is a problem for logging where using HPTIM% can
occasionally produce the effect of time going backwards.

Kermit does the best it and makes certain assumptions to achieve
millisecond resolution that does not go backwards, which is good
enough for many new cases.

On newer monitors, a higher precision time of day is provided, which
provides a resolution to 10 microseconds. At a 100 kHz clock rate,
this is one hundred times more granularity than millisecond
resolution.

If Kermit determines that this functionality is available, it will use
it in preference to the computationally more expensive method of
trying to figure milliseconds.  On the fastest machines, certain
communications tests can in fact happen in less than a millisecond,
where microsecond resolution can be useful.
| ;[229] 


      subttl Help text for the SET FILE command

hsfil:  asciz |
SET FILE paramater keyword

Establish file-related parameters:

   BYTESIZE keyword or number

     Byte size for DEC-20 file input/output.  The choices are 7-BIT,
     8-BIT, 36-BIT and AUTO.  If 7-BIT is selected, then Kermit will
     do normal ASCII character I/O.  8-BIT is necessary for
     transmission of non-DEC-20 binary files, such as .COM files from
     microcomputers.

     AUTO is equivalent to 7-BIT for incoming files.  For outgoing
     files, it means to use 8-BIT if the DEC-20 file bytesize (as
     shown by the Exec VDIR or LOCAL KERMIT DIRECTORY command) is 8,
     otherwise, it will use SEVEN.  The default is AUTO.

     SEVEN or AUTO can be used to send and receive DEC-20 binary
     files, such as .EXE or .REL files.  EIGHT is only for "foreign"
     8-bit binary files.

     While Kermit-20 has always been able to send and receive DEC-20
     binary files with absolutely no loss of data, receiving a DEC-20
     binary file would cause both an incorrect file byte size (7
     instead of 36) and file byte count (off by over a factor of five)
     to be set.

     Setting 36-BIT forces an internal 7-bit transfer but a post-
     transfer meta-data processing to use full 36 bit words in the
     calculations.  It will also clear ITS-BINARY mode.  For more
     information, type HELP 36-BIT-BYTES.

   NAMING UNTRANSLATED or NORMAL-FORM

     If the NAMING option is set to NORMAL-FORM, the names of
     incoming or outgoing files will be converted to contain only
     uppercase letters, digits, and periods.

     If it set to UNTRANSLATED instead, filenames will be left alone
     as much as is possible.

     If conversion must be done because the foreign file name contains
     characters which are not valid in a Tops-20 file name, all
     control and punctuation characters (other than ".") in filenames
     will be translated to "X", and lower case letters will be
     capitalized.

     UNTRANSLATED is the default.
|				;[232] 


h36bb:	asciz &
Since its inception, Kermit-20 has always been able to send and
receive DEC-20 binary files perfectly with absolutely no loss of data,
as can be verified by doing a binary comparison using FILCOM with the
/W switch or comparing checksums via the EXEC's Checksum By-Pages
option.

It did this by adopting a kind of 'trick' that Tops-20 itself uses
when writing a 9-track ANSI-ASCII magnetic tape.  The file is read
using a 7 bit byte pointer, which guarantees that bit 8 (or the parity
bit) can NEVER be set.  Since it is unused, this bit may be considered
as a kind of undocumented 'spare' and is used to store bit 35 in the
following way.

The trick is to set bit 8 (or the parity bit) of every 5th character
to the value of bit 35 of the PDP-10 word it came from on a send and
check for it on a receive.

This allows for Tops-10/20 .EXE's, other 36-bit binary files, and
SOS-line numbered files, to be sent to 8-bit systems and retrieved
intact.  Clearly, no adverse effects can be suffered by ordinary text
files.

That being said, the problem is that a received file will be stored
with a size byte of 7 instead 36 and a byte count that will be off by
a factor of five.  This can cause undesired behavior in programs which
rely on or otherwise pay attention to either one.

Setting a byte size of 36 forces a 7 bit transfer but then causes
special post-receive processing to be done to properly set the byte
size to 36 bits and calculate the byte count according.
&				;[232] 

      subttl Help text for the SET PARITY command

hspar:  asciz &
SET PARITY [ [ even | mark | none | odd | space
    [ /check-parity | /generate-only |
      /packets-only | /terminal-and-packets ] ] ]

If parity is being used on the communications line, you must inform
Kermit-20 so it can both send the desired parity on outgoing
characters, and either check or strip it from incoming ones.

Be aware that parity may exist and be enforced by the foreign host
before the Kermit protocol itself ever starts.  Thus, Kermit can not
negotiate parity because no communications will be possible before it
is set--therefore, you MUST specify parity beforehand or you may have
problems up to and including the connection being dropped.

The parity types are even, mark, none, odd and space.  "none" means no
parity processing is done, and the 8th bit of each character can be
used for data when transmitting binary files.  This will make
transferring eight bit data more efficient.

The domain on which parity may be applied (or generated) while sending
is either /packets-only or /terminal-and-packets.  The DEC-20 does not
normally use parity on communication lines and thus Kermit strips
parity on all received data.  This domain can be overridden by
specifying /parity-checking.  Tops-20 will only generate even parity.

If nothing is specified, then the defaults are used, which are none,
/terminal-and-packets and /generate-only; there are congruent with
previous behavior.

If odd, even, mark, or space are selected, binary files will be
transferred using 8th-bit-prefixing, but only if the other side
agrees.  If this is not the case, they cannot be successfully
transferred.  If none is specified, 8th-bit-prefixing will not be
requested.  Be aware that 8th-bit-prefixing may result in slower
transfer speeds for 8 bit data.

SET PARITY should be used for communicating with hosts that require
character parity, or through devices or networks (like TELENET) that
add parity to characters that pass through them.  Both KERMITs should
be set to the same parity.

The specified parity is used both for terminal connection (CONNECT/
SET LINE) and file transfer (SEND, RECEIVE, GET) along with direct
text issuance and recognition (INPUT, OUTPUT and TRANSMIT).
Specifying /packets-only will cause parity to be restricted from
terminal connections and text issuance and recognition.

Unless the foreign host insists on parity, specifying parity provides
no real benefit as Kermit already has powerful error detection and
correction that is built into the protocol.  Furthermore, any
detection of a parity error is considered a transfer terminating
condition as would be the case were real parity being used.

Parity is unnecessary on a pseudo-terminal as the data transfer is not
going over any communications medium and is entirely internal to
Tops-20.  Tops-20 will generate parity on a pseudo-terminal, but this
is only used for testing purposes.  Tops-20 itself does not check
parity although a front-end line may do this.

Parity is also unnecessary for a Network Remote Terminal as DECnet is
already providing error detection and recovery at both the packet and
certain transport levels (via DDCMP, for example).  Note that Tops-20
will not generate parity on a DECnet Network Remote Terminal.

Parity can be still be specified in these cases, however, yet is used
only for packet debugging and checkout.  The default terminal handling
on pseudo-terminals and NRT's ignores parity on input.  In this
scenario, /packets-only and /parity-checking should be specified.

The current parity setting, the domains and whether the local terminal
will tolerate parity can be displayed with SHOW LINE.

If the line supports parity and the monitor supports querying line
parity, then Kermit will report whether the line supports parity.  If
the line supports parity, then Kermit will self-configure to respect
that parity.
&

      subttl Help text for the SET PROMPT command

hsprom: asciz &
SET PROMPT string | "string"

Set the Kermit-20 prompt to whatever character string you like.  This
is especially useful when connected to another DEC-20 through an auto-
dialer or via a network, using another Kermit-20 on the remote system.

A unique prompt for each Kermit-20 will clear up any confusion about
which one you're talking to.  This is also useful in a batch job doing
configuration of the remote Kermit-20 via OUTPUT and INPUT commands
prior to putting it in SERVER mode.

The string may optionally be enclosed in double quotes.  This will
allow a macro to change the prompt.  One of the uses of this is to
change the prompt to be the same name as the macro that sets it.
This can serve as a memory aid to recall what settings are in
effect.

The string may include C escape characters, although most of them will
be of little use if not flat out counter productive by potentially
invoking command parsing.  See HELP C-ESCAPE-SEQUENCES for further
information.

As an aid, when Kermit-20 is running local and using a DECnet
connection, the prompt will default to the node name of the local
system, otherwise, it defaults to "Kermit-20>"  Such defaulting will
also happen for a pseudo-terminal connection, but it should be kept
in mind that it is really the same system on both sides.

Setting the prompt to nothing (perhaps by doing a SET PROMPT "")
will result in the default prompt being setting.
& ;[190] 

	subttl Help text for the SET RETRY command

hsrty:  asciz |
SET RETRY option decimal-number

   Set the maximum number of retries allowed for:

     INITIAL CONNECTION -- How many times to try connecting before
        giving up. 
     PACKETS -- How many times to try sending a particular packet.
|

      subttl Help text for the SET FLOW-CONTROL command

hsflo:  asciz |
SET FLOW-CONTROL option

For communicating with full duplex systems.  The DEC-20 system is
capable of regulating the flow of characters on the line using
XON/XOFF flow control.  If characters are coming into the DEC-20 too
fast, the DEC-20 front end will send an XOFF signal, Control-S, to
tell the system on the other side to stop sending characters.

After it has finished processing the characters in its input buffer,
it will send a Control-Q to tell the other side to resume sending.
The other system does the same thing when the DEC-20 is sending data
characters.

Kermit-20 will use XON/XOFF flow control on a full-duplex connection
by default, and it will not use it on a half duplex connection.  The
options of the SET FLOW-CONTROL command are XON-XOFF and NONE.  If you
SET FLOW-CONTROL to anything other than NONE, HANDSHAKE is set to NONE.

FLOW-CONTROL is unnecessary on both pseudo-terminals and DECnet Remote
Network Terminals, although it is simulated on both.  This is largely
useless for two reasons.

First, the XON/XOFF can not be honored by the simulation quickly
enough to do any real good in contrast to the front end which will
start and stop transmission in milliseconds, typically within a single
character.

Second, other flow controls exist which Kermit does not need to
manage.  For a pseudo-terminal, Tops-20 will not allow an overrun,
putting whomever is clogging the pipe to sleep until such time as the
partner has drained and processed the stacked up communications data.
Similar functionality is implemented by DECnet but is not visible to
the NRT.

FLOW-CONTROL functionality is kept for debugging and checkout.

Note: If you notice that you are seeing ^S/^Q's being sent during
communications (and you are not on a VT100 using smooth scroll), then
the DEC-20's front end is probably being driven too hard.  This is a
dangerous thing to do as it risks crashing it, throwing off all the
other users.  You should remediate by using a smaller packet size and
small pauses between packets.
|

      subttl Help text for the SET HANDSHAKE command

hshan:  asciz &
SET HANDSHAKE [ option | octal number | ^ + character ]

For communicating with half duplex systems.  This lets you specify the
line turnaround character sent by the half duplex host to indicate it
has ended its transmission and is granting you permission to transmit.

When a handshake is set, Kermit-20 will not send a packet until the
half duplex host has sent the specified character.  The options are:

     NONE
     XOFF  (^S)
     XON   (^Q)
     BELL  (^G)
     CR    (^M, carriage return)
     LF    (^J, linefeed)
     ESC   (Escape)

If you SET HANDSHAKE to anything other than NONE, FLOW-CONTROL is set
to NONE.

If you do not specify anything, Kermit will default the handshake to
XOFF.  If you wish to use the default when defining a macro, simply
type a comma and go on to the next SET value you wish to change.

See HELP CONTROL-CHARACTERS for further information on how to specify a
handshake character mnemonically.
&


      subttl Help text for the SET INPUT command

hsetin: asciz &
SET INPUT parameter value

   Specify how the INPUT command is to behave (see INPUT).

   SET INPUT CASE [ IGNORE | OBSERVE \

      Specify whether alphabetic case should be ignored ("a" matches
      "A") or observed ("a" does NOT match "A").  If nothing is
      specified, then case will be ignored when matching.

   SET INPUT DEFAULT-TIMEOUT [ n ]
      n is the number of seconds for an INPUT command to time out after
      not receiving the requested input, if no interval is explicitly
      given in the INPUT command.

      The default timeout value is 10 seconds.  Fractional seconds may
      be given for n, such as 1.25.  These will be converted to the
      nearest millisecond value.  Such short waits may be useful for
      communicating with extremely fast remote machines over very high
      speed lines or for testing.

      A negative value will be rejected.  A value of zero means to
      never time out.

      A default timeout may be override on a case by case basis by
      explicitly specifying the value to the INPUT command.

   SET INPUT SEARCH-DEFAULT [ "string" | string ]
      Sets the default string to search for if nothing is given for
      this parameter to the INPUT command.  The string may be inclosed
      in quotes.  If nothing is given, then the default match will be
      set to a carriage return followed by a line feed.

   SET INPUT TIMEOUT-ACTION PROCEED or QUIT
      If the INPUT command comes from a command file (see TAKE command),
      then use this command to specify whether processing of the command
      file should proceed or quit after a timeout occurs.
&


      subttl Help text for the SET ITS-BINARY command

hsits:  asciz |
SET ITS-BINARY (format) ON or OFF

Specify whether ITS-Binary file headers are to be recognized or
ignored.  ITS binary format is a way (devised at MIT) of storing
foreign 8-bit binary data on a 36-bit machine to allow automatic
recognition of these files when sending them out again, so that you
don't have to depend on the file byte size, or to issue explict SET
FILE BYTESIZE commands to KERMIT.

An ITS format binary file contains the sixbit characters "DSK8" left-
adjusted in the first 36-bit word.  If ITS-BINARY is ON, then
Kermit-20 will send any file starting with this "header word" using
8-bit i/o, and will not send the header word itself, and it will store
any incoming file that begins with that header word with 8-bit
bytesize, again discarding the header word itself.  If ITS-BINARY is
OFF, then the header word, if any, will be sent, and i/o will be
according to the setting of FILE BYTESIZE.

Note, setting ITS-BINARY will force a file byte size of AUTO and clear
36-bit byte file mode.  Setting a 36-bit file bytesize will clear
ITS-BINARY.
|				;[232] 


      subttl Help text for the SET LINE command

hslin:  asciz &
SET LINE octal-number | DECnet node name | "pseudo-terminal"

Specify the octal TTY number or DECnet node to use for file transfer
or CONNECT.  If you issue this command, you will be running as a local
Kermit, and you must log in to the remote system and run Kermit on
that side in order to transfer a file.  If you don't issue this
command, Kermit-20 assumes it is running remotely, and does file
transfer over its job's controlling terminal line.

You can also select the line directly in the CONNECT command.

"pseudo-terminal" may be given for a loopback connection to the local
host.  This is largely used for testing, debugging and checkout.
However, it is possible to use the remote job to sign into other
systems using different protocols, such as CTERM and TELNET.

Note the restriction that the remote DECnet host must be running
Tops-20 terminal transport, currently Tops-20, Tops-10 and Ultrix.

Be aware that, when logging into the pseudo-terminal, if you use the
same user id as the user id which you are currently signed on as, you
will not be prompted for a password.  Therefore, do not type it as it
may wind up being echo'ed and also show up in a log file.

Issuing a bare set line with no arguments closes the current active
connection, if there is one.
&       ;[186] 


      subttl Help text for the SET HOST command

hshst:  asciz &
SET HOST DECnet node name | "pseudo-terminal" [/stay | /timeout]

Specify the DECnet node to use for file transfer or CONNECT.  If you
issue this command, you will be running as a local Kermit, and you
must log in to the remote system and run Kermit on that side in order
to transfer a file.  If you don't issue this command, Kermit-20
assumes it is running remotely, and does file transfer over its job's
controlling terminal line.

You can also select the host directly in the CONNECT command.  Type
HELP CONNECT for an explanation of the /STAY and /TIMEOUT switches.

"pseudo-terminal" may be given for a loopback connection to the local
host.  This is largely used for testing, debugging and checkout.

Be aware that, when logging into the pseudo-terminal, if you use the
same user id as the user id which you are currently signed on as, you
will not be prompted for a password.  Therefore, do not type it as it
may wind up being echo'ed and also show up in a log file.

Specifying neither will close any remote connection.

Note the restriction that the remote DECnet host must support Tops-10/
Tops-20 NRT protocol.  This is usually PDP-10 running either Tops-10
or Tops-20, but the protocol is simple enough that any DECnet host can
implement it, which Ultrix does.
& ;[186] 


      subttl Help text for the SET DELAY command

hsdel:  asciz |
SET DELAY floating-point-number

How many seconds to wait before sending the first packet.  Use when
remote and SENDing files back to your local Kermit.  This gives you
time to "escape" back and issue a RECEIVE command before packets start
arriving.

The normal delay is 5 seconds.

The delay may be given in fractions of seconds and this will be
converted to milliseconds.  Negative delays are rejected.  If no
number is given, then the delay will default to 10 seconds.

Note that the delay is ignored both when Kermit is running in LOCAL or
SERVER mode as there is no need to escape back and forth.
|


      subttl Help text for the SET DUPLEX command

hsdup:  asciz |
SET DUPLEX keyword

For use when CONNECTed to a remote system.  The choices are FULL and
HALF.  FULL means the remote system echoes the characters you type,
HALF means the local system echoes them.  FULL is the default, and is
used by most hosts.  HALF is necessary when connecting to IBM
mainframes.
|

      subttl Help text for the SET ESCAPE command

hsesc:  asciz &
SET ESCAPE [ octal-number | ^ + another character ]

Indicate what control character you want to use to "escape" from
remote connections.  The number is the octal value of the ASCII
control character, 0 through 37 and 177.

You may also type the carat ("^") character followed by a single
character indicating the control character you wish to use.

When you type whatever has been chosen as the escape character, you
must follow it by a single-character "argument":

   C  Close connection (brings you back to the local host)
   S  Status report
   P  Push to a new Exec on the local system
   Q  If you have given a LOG SESSION command, temporarily Quit logging
   R  Resume logging to session log
   B  Attempt to send a simulated BREAK signal.
   ?  List available options

Entering the escape character twice in a row will cause the escape
character itself to be sent.  As is the case with other Kermit
implementations, the word "Close" does not mean disconnect.  It means
bring you back to the local host while holding the remote connection
open.  It is best to think of Close as meaning Escape.

If you do not specify anything, Kermit will default the escape
character to octal 34 (Control-Backslash ^\).  If you wish to do this
when defining a macro, simply type a comma and go on to the next SET
value you wish to change.

See HELP CONTROL-CHARACTERS for further information on how to specify
an escape character mnemonically.

Kermit will reject a number of escape characters, among the following:

    1)  ^C is rejected in all cases.
    2)  ^G is rejected in a Batch job or if Kermit is running without
        ^C capability (SC%CTC), which is typically while debugging.
    3)  If you are running with Flow Control on, then neither ^S (a.k.a
        XOFF, DC3 or octal 23) or ^Q (a.k.a. XON, DC1 or octal 21)
        will be accepted.
    4)  If you are running with handshaking, then the handshake character
        will not be accepted.

Care should be taken for escape character selection.  For example, a ^O
may produce unexpected results.  Some experimentation may be useful.
& ;[186] ;[217] 


      subttl Help text for the SET EXPUNGE command

hsexp:  asciz |
SET EXPUNGE ON or OFF

Tell whether you want a DELETE command (either the LOCAL DELETE
command or a REMOTE DELETE command sent to a Kermit-20 server) to
expunge files as it deletes them.

On the DEC-20, a deleted file continues to take up space, and may be
"undeleted" at a later time in the same session.  To expunge a deleted
file means to remove it completely and irrevocably.  EXPUNGE is OFF
(i.e. no automatic expunging of deleted files) by default.

It may be useful to turn EXPUNGE on if you are running out of disk
quota and are unable to receive further files.

Be aware that setting EXPUNGE to ON may result in significantly slower
completion times.  In either case, any deleted files will be expunged
when the job logs out. 

While you may undelete a file with the Tops-20 Executive, Kermit
itself contains no functionality to do this.
|


      subttl Help text for the SET RECEIVE command

hsrcv:  asciz &
SET RECEIVE parameter

   Parameters to request or expect for incoming packets, as follows:

   END-OF-LINE [ octal-number | ^ + character ]
     The octal value of the ASCII character to be used as a line
     terminator for packets, if one is required by the other system.
     If nothing is specified, then carriage return (ASCII 15) will be
     used by default.  See HELP CONTROL-CHARACTERS for information as
     to how to set END-OF-LINE mnemonically.  The DEC-20 itself does
     not actually need any line terminator for incoming packets.

   PACKET-LENGTH decimal-number
     Maximum length packet for the other side to send, decimal number,
     between 10 and 9000, 80 by default.

   PADCHAR [ octal-number | ^ + character ]
     Sets the padding character to an octal ASCII value or mnemonic.
     See HELP CONTROL-CHARACTERS for information as to how to set
     PADCHAR mnemonically.  The default padding character is NUL
     (ASCII 0),  It should never be necessary to do this; the DEC-20
     needs no padding as the Kermit protocol manages throughput.

   PADDING decimal-number
     Sets the number of padding characters to emit.  The maximum number
     of padding characters is 1,024.  See PADCHAR for more information.

   PAUSE floating-point-number
     How many seconds to pause before acknowledging a packet.  Setting
     this to a nonzero value will slow down the rate at which data
     packets come in to the DEC-20, which may be necessary for
     DEC-20's that have "sensitive" front ends that cannot accept input
     at a high rate.  Normally, no per-packet pausing is done.

   QUOTE [ octal-number | character | mnemonic ]
     What printable character to use for quoting of control
     characters.  If nothing is specified, "#" (ASCII 43) is used by
     default.  The character may be directly typed in most cases or a
     mnemonic or octal value may be used where it cannot.  See HELP
     QUOTE-CHARACTERS for more information.  There should be no reason
     to change this.

   SERVER-TIMEOUT floating-point-number
     When running as a server, how often to send periodic NAKs during
     server server command wait.  If Kermit is running with flow-
     control (XON-XOFF) enabled, then the NAK packet will be preceded
     with an XON (^).

     A value of 0 means don't send any NAK's at all.  The maximum time
     out value is 94 seconds.  If no number is given, then a default of
     10 seconds will be used.

     The number is assumed to be seconds, yet is parsed is a floating
     point number, which will be converted into milliseconds to allow
     for greater granularity and time-outs of shorter duration.

     CAUTION: a very short SERVER-TIMEOUT can cause Kermit-20 to
     flood the line when in SERVER mode which will most likely result
     in a in a stuck connection, if not an outright crash of the front
     end.  Such a value is only expected for debugging purposes.

   START-OF-PACKET [ octal-number | ^ + character ]
     The control character that marks the beginning of a packet.  If
     nothing is specified, then SOH (Control-A, ASCII 1) will be used
     by default.  See HELP CONTROL-CHARACTERS for information as to
     how to set START-OF-PACKET mnemonically.  Normally, there should
     be no reason to change this. 

   TIMEOUT floating-point-number
     How many seconds the other Kermit should wait for a packet before
     asking for retransmission.  If 0, then no timing out will be
     done.  The maximum time out value is 94 seconds.  If no number is
     given, then a default of 10 seconds will be used.

     The number is assumed to be seconds, yet is parsed is a floating
     point number, which will be converted into milliseconds to allow
     for greater granularity and time-outs of shorter duration.

Note: Numbers which are parsed as fractional seconds are displayed to
the fourth fractional digit (thousandth's) to show any rounding that
was done to integer milliseconds.
&


      subttl Help text for the SET SEND command

hssnd:  asciz &
SET SEND parameter

Parameters for outgoing packets, as follows:

   END-OF-LINE [ octal-number | ^ + character ]
     The octal value of the ASCII character to be used as a line
     terminator for packets, if one is required by the other system.
     If nothing is specified, carriage return (ASCII 15) will be used
     by default.  See HELP CONTROL-CHARACTERS for information as to
     how to set END-OF- LINE mnemonically.  You will only have to use
     this command for systems that require a line terminator other
     than carriage return.  This is different from the half duplex
     handshake (or line turnaround) character.

   PACKET-LENGTH decimal-number
     Maximum packet length to send, decimal number, between 10 and
     9000, 80 by default.  Shortening the packets might allow more of
     them to get through through without error on noisy communication
     lines.

   PADCHAR [ octal-number | ^ + character ]
     Sets the padding character to an octal ASCII value or mnemonic.
     See HELP CONTROL-CHARACTERS for information as to how to set
     PADCHAR mnemonically.  Defaults are no padding, and NUL (0) for
     the padding character.

   PADDING decimal-number
     Sets the number of padding characters to emit.  The maximum number
     of padding characters is 1,024.  See PADCHAR for more information.

   PAUSE floating-point-number
     How many seconds to pause before acknowledging a packet.  Setting
     this to a nonzero value will slow down the rate at which data
     packets come in to the DEC-20, which may be necessary for
     DEC-20's that have "sensitive" front ends that cannot accept input
     at a high rate.  Normally, no per-packet pausing is done.

   QUOTE [ octal-number | character | mnemonic ]
     What printable character to use for quoting of control
     characters.  If nothing is specified, "#" (ASCII 43) is used by
     default.  The character may be directly typed in most cases or a
     mnemonic or octal value may be used where it cannot.  See HELP
     QUOTE-CHARACTERS for more information.  There should be no reason
     to change this.

   START-OF-PACKET [ octal-number | ^ + character ]
     The control character that marks the beginning of a packet.  If
     nothing is specified, then SOH (Control-A, ASCII 1) will be used
     by default.  See HELP CONTROL-CHARACTERS for information as to
     how to set START-OF-PACKET mnemonically.  Normally, there should
     be no reason to change this. 

   TIMEOUT floating-point-number
     How many seconds to wait for a packet before trying again.  If 0,
     then no timing out will be done.  94 seconds maximum.  If no
     number is given, then a default of 10 seconds will be used.

     The number is assumed to be seconds, yet is parsed is a floating
     point number, which will be converted into milliseconds to allow
     for greater granularity and time-outs of shorter duration.
&

      subttl Help text for valid QUOTE characters and how to type them

hsquo:	asciz 
QUOTE CHARACTERS

The Kermit protocol mandates that the quote character be in the ASCII
printable range, meaning you could see it were you to print it.  More
specifically, the character can not be in the control range (0 to 37
octal), nor a space (octal 40) nor rubout (177).

Kermit-20 allows the quote character to be directly specified,
provided it is one of the following:

    0 1 2 3 4 5 6 7 8 9
    A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
    a b c d e f g h i j k l m n o p q r s t u v w x y z
    " # $ % & ' ( ) * + . / : < = > [ \ ] ^ _ ` { | } ~

Other grammatical characters can not be specified directly because
they are either usurped by Tops-20 itself or Kermit already uses them
for other purposes (such as macro definition).  These may be specified
either as a mnemonic keyword or as octal.  The following table lists
the keywords, the characters and the octal equivalents:

	Keyword		Character      Octal
	at-sign		    @		100
        comma		    ,		 54
	dash		    -		 55
        exclamation-mark    !		 41
	question-mark	    ?		 77
	semicolon	    ;		 73

Thus, as far as Kermit-20 is concerned, the following two SET commands
do exactly the same thing, setting the start-of-packet character to a
comma.

    Kermit-20>set send quote (to) comma 
    Kermit-20>set send quote (to) 54
 ;[217] 

      subttl Help text for the SET SPEED command

hspeed: asciz |
 SET SPEED n

   Set the speed of the currently selected line.  By default, this is
   the currently logged in job's controlling terminal.  If you have an
   active SET LINE session in progress, then baud rate will be applied
   to this line, instead.

   Be aware that the speed parsed is actually not a number, but rather
   a table of defined speeds for a front-end's DH11 or DL11 line
   handlers.  The valid speeds are the following baud rates: 110, 150,
   300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200 and 9600.  You

   Caution: under releases of TOPS-20 prior to 6.0, you must issue
   this command before you can send a simulated BREAK signal during
   CONNECT.

   You can set the speed on an Internet TVT when you in remote mode, but
   the command is silently ignored,

   It is an error to attempt to set the speed of a DECnet Network Remote
   Terminal or a pseudo-terminal.

   On a non-physical terminal, such as an Internet TVT, a DECnet NRT
   or CTerm, a LAT or pseudo-terminal, no speed will ever be dislayed
   because the monitor does not know it.
| ;[186] 


      subttl Help text for the SET TVT-BINARY command

hstac:  asciz |
 SET TVT-BINARY AUTOMATIC, ON or OFF

   Only for users running Kermit-20 on an Internet DEC-20, signed on
   to a DEC-20 TVT (Internet virtual terminal), from either another
   Internet host or through a TAC.  Without TVT Binary mode, file
   transfer through a TVT would not work in most cases.

   SET TVT AUTOMATIC causes Kermit to determine your line type.  If
   you sign on from a TVT, then TVT-Binary mode will be enabled.  Any
   other type of line wil cause TVT-Binary mode to be disabled.
   SET TVT AUTOMATIC is the default.

   SET TVT ON overrides the detection logic and forces Kermit-20 to
   always negotiate TELNET binary mode during a file transfer.  This
   should ONLY be done on a line that you are positive is a TVT that
   Kermit-20 is not recognizing as such.  This can happen on older
   pre-Release 7 monitors.

   If this happens and you normally use Kermit-20 through a TVT, you
   can put the command SET TVT-BINARY ON into your KERMIT.INI file.

   SET TVT OFF overrides the detection logic and forces Kermit-20 to
   NEVER negotiate TELNET binary mode during a file transfer.  This
   should ONLY be done on a line that you are certain is NOT a TVT
   that Kermit-20 is mistakenly identifying as a TVT.  While such a
   problem is indicative of a monitor problem, this will allow you to
   get around it until such time as the monitor is fixed.

   Any value of TVT is ignored when communicating over pseudo-terminal
   or DECnet Network Remote Terminal lines as these always run in
   binary mode (and do not require parity).

   CAUTION: This functionality requires certain facilities in the
   Release 5 TOPS-20 Internet monitor: TELNET binary negotiations are
   accepted (bug fix), and the monitor does NOT double the TELNET
   attention character (IAC, octal 377).

   Kermit-20 will attempt to use monitor calls to enable TELNET binary
   mode, but these do not exist in all monitors.  If the calls fail,
   it will then send IAC escape sequences to negotiate TELNET binary
   mode, and doubles any IACs that appear in data during file
   transfer.

   Be aware that setting or unsetting TVT binary mode may take up to 8
   seconds.
| ;[186] 


      subttl Help text for the STATISTICS command

hstatu: asciz |
STATISTICS

Gives statistics about the most recent file transfer.  A sample is
shown with the explanation following:

    Maximum number of characters in packet:  94 received: 94 sent
    Communications duration: 1.293.990 (TOD: 4), analysis:

           Sent:      5498         Efficiency:     [100% Overhead]
           Received:  97702        Efficiency:       0.8786
           Total:     103200       Efficiency:       1.2022

    Total characters per second:     77.8841 KC/s
    Effective data rate:            647.8267 KBd
    Pseudo-efficiency:                3.3687 per cent
    ILDB: 96604  SIN:  1098  SIN Max:  91  BIN:  1098
    Interpacket pause in effect: 0 ms

    Timeouts: 0
    NAKs:     0

The first line of output indicates what size packets were negotiated
for the transfer.

The second line of output gives the time spent doing the transfer in
the form of hh:mm:ss.mssnn.  hh indicates the number of hours spent
and can go over 24 hours.  mm and ss indicate minutes and seconds
respectively and do not go over 59.  mss indicates the number of
milliseconds and can vary between 0 and 999.  nn indicates 10's of
microseconds and can vary between 0 and 99, meaning 10 and 990
microseconds.

The TOD figure is the number of elapsed Tops-20 time-of-day (TOD)
ticks.  A TOD tick is a fixed fraction whose unit quantity is the
number of seconds in a day (86,400) divided by 2 to the 18th power
(262,144) or .329589844 seconds.  This is quite close to, but NOT a
third of a second.

The efficiency is a multiplicative factor that is derived from
counters that are kept on a per transfer basis,  A transfer is defined
to be all files that were either sent or received by the last command.
It is calculated as follows: the total number of characters in every
file is divided by the number of characters that were necessary to
communicate them.

If the factor is over 1, then Kermit compression is saving time.  If
it is under one, then the total characters used, including prefixing, 
is causing extra bandwidth to be consumed.

Since Kermit will only support one send or receive file group at a
time, one part of the transfer will always show as %100 overhead, as
these are the acknowledgements sent for packets received,

The numbers kept for statistics and the numbers kept for SHOW LINE are
not related and have nothing to do with one another.

Pseudo-efficiency is used to simulate the efficiency of the
communications line, which was useful for hardware serial lines where
the baud rate was known.  As it is almost impossible to know the speed
of all legs of a network transfer, this number is simulated against
data that is gathered with the TIME command.

The ILDB: 1457309  SIN:  5888  SIN Max:  249  BIN:  6012 line
indicates how efficiently Tops-20 is being used and is of
interest largely to developers.  Briefly, the higher the ILDB number
is, the better as monitor buffering (via SIN) has been used instead
issuing single byte inputs.

Note: if the speed of the machine and the communications lines are
extremely fast and the packet sizes are at maximum (9000 characters),
then millisecond transfer times will be seen.  In such environments,
pathologically short file sizes will see microsecond transfer times.
These are all far less then the TOD granularity described above which
was the previous Kermit-20 time base.

The maximum time precision of most Tops-20 systems is derived from the
frequency of the KL clock which operates at 1 mHz.  This is converted
to DK10 clock units, which runs at 100 kHz unless using an external
clock source, in which case the maximum frequency is 400 kHz.
Assuming 100 kHz, the finest granularity that can be measured on an
unmodified Tops-20 is 10 microseconds.
|


      subttl Help text for the SHOW command

hshow:  asciz \
SHOW [parameter] | [macro]

Display current SET parameters, version of Kermit-20, or other info:

  DAYTIME           Current date, time, phase of moon.
  DEBUGGING         Debugging mode and log file in effect, if any.
  FILE-INFO         Byte size for DEC-20 file i/o, incomplete file disposition.
  INPUT             Parameters for INPUT command.
  LINE              TTY line, parity, duplex, handshake, escape character.
                    For addition help on line information, type HELP LINE.
  MACROS            Definitions for SET macros.
  PACKET-INFO       For incoming and outbound packets.  Items under RECEIVE
                    column show parameters for packets Kermit-20 expects
                    to receive, under SEND shows parameters for outgoing
                    packets.
  TIMING-INFO       Delays, retries, server NAK intervals.
  VERSION           Program version of Kermit-20.
  ALL               All of the above.

If one or more macros are defined, then a macro name may be given
instead of the SET parameter, in which case Kermit-20 will display the
macro name followed by an equals sign and then display the SET
parameters that make up the body of the macro.

If neither macro or a parameter is given, then Kermit-20 will display
all of the above.

Additional help is available for SHOW LINE and SHOW DEBUGGING
\ ;[239] 


	subttl Additional help text on SHOW LINE command

hline:  asciz &
SHOW LINE

When running as LOCAL and using network or pseudo-terminal connection,
Kermit keeps extra performance information.  This information is
separate from what is shown in STATISTICS for a Kermit protocol based
transfer.

In this case, it is specific to the virtual terminal use by CONNECT,
INPUT, OUTPUT and TRANSMIT.  The following is an example:

Remote host for file transfer:  TOMMYT::
 (Network Remote Terminal, Kermit-20 is LOCAL)
  Handshake:        None
  Flow-Control:     None
  Escape:           ^\
  Parity:           None
  Duplex:           Full
  Break Simulation: Disabled
  NRT Connection:   Online
  Terminal BIN%'s:  11
  Virtual CFIBF%'s: 2048
   Buffer CFIBF%'s: 933
  Virtual BOUT%'s:  9
  SIN%'s Issued:    0
  SIN% Bytes Total: 0
  Max SIN% Length:  0
  SOUTR%'s Issued:  1
  SOUTR% Bytes:     3
  Max SOUTR% Count: 3
  Network BIN%'s:   16
  Network SIN%'s:   8
  Network SIN% Cnt: 524
  Network SIN% Max: 299
  Log: (Enabled)  : SESSION.LOG.3


The following counters are kept on behalf of the operation of a
virtual terminal being driven by direct user activity on a local
terminal.

Terminal BIN%'s

    This is when a single character is read from the local terminal
    for transmission over the network link.

Virtual CFIBF%'s

    The Tops-20 buffer clearing JSYi (CFIBF% and CFOBF%) do not work
    on a network connection that is not using a physical line.  The
    data must be read and discarded.  This is the count of the total
    characters 'cleared' in this way.

Buffer CFIBF%'s

    Kermit-20 uses buffered network I/O to implement the INPUT and
    OUTPUT commands.  Kermit holds any remaining characters after a
    successful search in case other INPUT commands are given.  On a
    CLEAR command, this contains the total of how many of those
    characters were removed. 

    This data is different from a Virtual CFIBF% as it has already
    been read, the result of the CLEAR being merely that INPUT's
    buffer counter and pointer were reset.

Virtual BOUT%'s

    This is when a single character is sent over the network line as a
    result of being read and no further terminal input being
    available.  In this case, a SOUTR% must be used for a single byte
    to push the data over.  This has more overhead than other cases.

SIN%'s Issued

    If input is detected on the local terminal after it has woken up
    from a BIN%, a check is made for any type-ahead.  If any exists,
    it is captured with a counted SIN%.  This is the number of times
    that has happened.

SIN% Bytes Total

    Total number of type ahead characters we were able to capture with
    a SIN.

Max SIN% Length

    The maximum size of the type ahead that we've seen.  On a fast or
    lightly loaded machine, this number may not be very high.  The
    more data captured this way, the less any data may be in a front
    end, thus avoiding instability.

SOUTR%'s Issued

    Total times we've used a SOUTR% to push captured type ahead.  This
    does not include the SOUTR% used to push a single character.

SOUTR% Bytes

    Total characters that have been written to the network as a result
    of data produced by typeahead activity.

Max SOUTR% Len

    The maximum number of characters that have been able to be written
    using a SOUT%  This shows the best case conditions of capturing
    type-ahead.  The number will be artificially high in a batch job
    because the batch controller issues text a line at a time.

The following counters are kept on behalf of the network input being
done while operating the remote connection. 

Network BIN%'s

    This is when a single character is read from the network.

Network SIN%'s

    When a character is read from the network, a check is made for any
    additional data that might be available.  Any such data is read
    with a single SIN%, which cuts down on JSYS overhead.  This is the
    total number of times Kermit has been able to do that.

Network SIN% Cnt

    This is the total number of characters that were captured by
    detecting additional data.

Network SIN% Max

    This is the maximum number of characters that could be read at once.

Note that when doing a /FORKLESS connect, remember that Tops-20 itself
is handling the NRT connection outside of user mode, and that
therefore, Kermit-20 cannot know the remote terminal character counts
and thus, these will not be displayed by SHOW LINE.
&


	subttl Additional help text on SHOW DEBUGGING command

hdebug:  asciz /
SHOW DEBUGGING

Displays information concerning debugging information, including where
the information is being written.  Debugging in this context means
capturing certain information during transfers and either displaying
it if a local connection or writing it to a file.

Debugging information can be captured on either a state or packet
basis.  State transitions mean what Kermit is currently expecting
during a transfer as well as related packet numbers.  Packet debugging
means that the entire contents of the packet are captured.

When doing packet level debugging, Kermit will display whether the
packets are being decoded as well as the logging resolution.  For an
unmodified Tops-20, this will be one millisecond.  For a Tops-20 with
high precision uptime and time of day, this will be ten microseconds.

If debugging information is being written to a file, then the name of
the file will be shown and the number of bytes written as well as the
byte size of the file as it was opened.  Tops-20 does not count bytes
when writing to the special NUL: designator, so this information will
not be shown.

For example:

Kermit-20>SHOW DEBUGGING

Debugging: Packets [Decoding, 10 microsecond resolution]
  Debugging log file: K20DPD-PACKET-DECODE.LOG.33, 12048 Bytes Written, bytesize 7
/ ;[239] [240]


	subttl Help text for FINISH command.

hfinis: asciz |
FINISH

When running as a local Kermit, talking to a KERMIT server over a TTY
line specified in a SET LINE, SET HOST or CONNECT command, use the
FINISH command to shut down the server without logging out the remote
job, so that you can CONNECT back to it.  Also, close any local
debugging log file.

Finish functions in exactly the same way for physical lines
pseudo-terminals and DECnet NRT's.
|


	subttl  Help text for CONNECT

hconne: asciz @
CONNECT [ [number] | 
        [ [ host:: | "pseudo-terminal" [ [ "/forkless" | "/stay" ] |
                                           "/timeout" ] ] |
        [ ["close"] | ["kill"] ] ]

Establish a terminal connection to the specified destination system or
reconnect to the currently active connection.  A destination may be
one of the three following choices:

 1) A physical terminal, parsed as a simple octal number.
 2) A DECnet node.
 3) The keyword, "pseudo-terminal", for a loopback connection to the
    local host.

All destination choices may be following with the /STAY switch, which
instructs Kermit to not create a terminal fork, but rather stay at the
local system; this can aid processing the INPUT/OUTPUT commands by
eliminating a source of asynchronous reads.

/FORKLESS is valid only for a DECnet connect and specifies to use
Tops-20's built-in (monitor based) NRT client instead of having Kermit
create a fork for user communications.  This can save on processor and
memory resources and may be significant on heavily loaded systems.

/STAY, INPUT and OUTPUT are the recommended way to use Kermit-20 from
a batch stream.  Using the communications fork in that context will
not work without special modifications to BATCON.  Even an arcane
sequence of pause commands may not work.

/STAY with only INPUT and OUTPUT will also circumvent certain Tops-20
DECnet buffering bugs.

The use of /FORKLESS is undetectable by the remote system and is
entirely separate from normal Kermit transfers.  It has no effect on
either the INPUT or OUTPUT commands.

The SET DELAY parameter is taken to be the default duration before
declaring a connection time out.  /TIMEOUT may be used to override
this and takes a numeric argument to specify the number of seconds to 
wait before failing the connection attempt.  The maximum duration is
94 seconds.

While /TIMEOUT can be specified for any connection, it only has
relevance for DECnet connections.  You can abort the connection
attempt by typing a ^C.  Typing a ^Y will get you the current
connection status as seen by Tops-20.

An open connection may be managed with CLOSE and KILL keywords.

Specifying "close", will close the current connection, yet the
terminal fork will be kept should there be one to allow later reuse.
Once the close is complete, Kermit-20 will be set back to remote mode.

The transfer fork may be killed separately.  Killing the transfer fork
will not close the connection, but could cause repeated or lost data
which should be irrelevant as no active transfer is in process.  In
this case, the clear command may be tried to clear out any data.

Be aware of the following cautions and limitations:

 1) The physical terminal must not be in use or otherwise assigned to
    another job.  You can not Kermit to another person's logged in job.

 2) You can not connect to a local network terminal; the line must be
    a physical line.

 3) If you specify a DECnet node and the parse is successful, then
    that node is guaranteed to be known to Tops-20.  However, it may
    or may not be online and connections may take several seconds to
    complete.  The connection can fail for other reasons (see below).

 4) The remote DECnet host must support the Tops-20 NRT protocol; the
    connection will be rejected if this is not the case.  Currently,
    only a PDP-10 running either Tops-10 or Tops-20 or PDP-11 or VAX
    running Ultrix has such support. 

 5) When logging in via a pseudo-terminal, if you use the same user id
    as the user id with which you are currently signed on, you will
    not be prompted for a password.

    Therefore, do not immediately type a password as it may wind up
    being echo'ed and also show up in a log file. 

 6) A pseudo-terminal connection is largely used for testing and
    debugging.  Using it to run another program, such as TELNET
    to connect to an Internet host or CTERM a non-36 bit DECnet
    host is not guaranteed to work.

 7) Although a /FORKLESS switch can be specified for any connection,
    it is only honorable for a DECnet NRT connection.  When giving it
    for the other types (serial, pseudo-terminal), a message will be
    generated, stating that it will be ignored.

8)  When using /FORKLESS, remember that Tops-20 itself is handling
    the NRT connection outside of user mode, and that therefore,
    Kermit-20 cannot know the remote terminal character counts and
    thus, these will not be displayed by SHOW LINE.

Specifying nothing will reconnect to the remote connection.  If there
is no remote connection currently open, then an error will be given.

Get back to Kermit-20 by typing the escape character followed by the
letter C.  The escape character is Control-Backslash (^\) by default.
When you type the escape character, several single-character commands
are possible:

B -- Transmit a BREAK signal.
C -- Return to the local Kermit-20; check-pointing log.
P -- Push to a new Exec.  POP from the Exec to get back to the connection.
Q -- Temporarily quit logging.
R -- Resume logging.
S -- Show status of the connection.
^\ (or whatever you have set the escape character to be) -- Typing the
 escape character twice sends one copy of it to the connected host.

The "B" command is always accepted but silently does nothing on a pseudo-
terminal nor on a DECnet NRT; it is only relevant for a physical line.

You can use the SET ESCAPE command to define a different escape character.

Be aware the "C" command does NOT close an active connection.  Use the
"CLOSE" keyword to accomplish this.  Holding the connection open means
that a subsequent connect command with no argument will have the
effect of continuing the remote session.  This is contrasted with SET
LINE where specifying no parameter will close the currently active
session.
@ ;[236] 


	subttl Escape character Help

eschlp: intern eschlp
        asciz \
Kermit-20 Single-Character CONNECT-Mode Commands:

 B - Send BREAK signal
 C - Close connection (checkpoints session log, allows reconnection)
 K - Return to Kermit-20 command level (holds connection open)
 P - Push to Exec (holds connection open)
 Q - Quit logging
 R - Resume logging
 S - Status
 ? - This message

Type the escape character twice to send one copy of it to the remote host.

Escape character is "\          ;" (Font lock fool)


;[214] Begin help text reformat and addition

emacro <
hdefin: intern hdefin
        asciz &
DEFINE [macroname] | ["macroname"] [ /macro-switch ] | [set-parameters]

                         or top level switch

DEFINE /COMPACT | /DUMP | /MAP | /RESET | /SAVE | /SUMMARY

A macro switch may be one of the following:

         /CHANGE | /DUPLICATE | /REMOVE | /RENAME | /UNDEFINE

Define a "SET macro" to allow convenient association of one or more
SET parameters with a mnemonic keyword of your choice.

The set-parameters are a list of one or more SET options, separated by
commas.  If you use Kermit-20 to communicate with several different
kinds of systems, you may set up a macro for each, for instance:

  DEFINE IBM PARITY MARK, DUPLEX HALF, HANDSHAKE XON, SEND PACKET-LENGTH 80
  DEFINE UNIX PARITY NONE, DUPLEX FULL, HANDSHAKE NONE
  DEFINE TELENET PARITY MARK

You may then type SET IBM, SET UNIX, and so forth to set all the
desired parameters with a single command.  It is convenient to include
these definitions in your KERMIT.INI file.

Putting the macro name in double quotes allows the use of escape
recognition of the rest of the SET parameters.  Similarly, question
mark ("?") can then be used to get a list of the available set
parameters.  This can ease the process of creating macros.

You may redefine an existing macro in the same manner as you defined
it.  You can undefine an existing macro by typing an empty DEFINE
command for it, for instance:

  DEFINE IBM

Be aware of the following:

    1)  Macro definitions may not 'nest'.  This means that they may
        not include other macro names as set arguments.

    2)  Using a quoted macro name when defining will allow you to
        define macros that consequently can not be parsed.  One
        example would be the use of embedded spaces or tabs, such as
        "my macro".

        If this happens, then the macro may be removed by specifying
        the quoted name with the /UNDEFINE switch.  It is best to keep
        macro names being alphanumeric with a dash ("-") or
        underscore ("_") as a separator character.
&
>;;emacro

nmacro <
hdefin: intern hdefin
        asciz &
DEFINE [macroname] | ["macroname"] [ /macro-switch ] | [set-parameters]

                         or top level switch

DEFINE /COMPACT | /DUMP | /MAP | /RESET | /SAVE | /SUMMARY

A macro switch may be one of the following:

                   /DUPLICATE | /RENAME | /UNDEFINE

Define a "SET macro" to allow convenient association of one or more
SET parameters with a mnemonic keyword of your choice.

The set-parameters are a list of one or more SET options, separated by
commas.  If you use Kermit-20 to communicate with several different
kinds of systems, you may set up a macro for each, for instance:

  DEFINE IBM PARITY MARK, DUPLEX HALF, HANDSHAKE XON, SEND PACKET-LENGTH 80
  DEFINE UNIX PARITY NONE, DUPLEX FULL, HANDSHAKE NONE
  DEFINE TELENET PARITY MARK

You may then type SET IBM, SET UNIX, and so forth to set all the
desired parameters with a single command.  It is convenient to include
these definitions in your KERMIT.INI file.

Putting the macro name in double quotes allows the use escape
recognition of the rest of the SET parameters.  Similarly, question
mark ("?") can then be used to get a list of the available set
parameters.  This can ease the process of creating macros.

You may redefine an existing macro in the same manner as you defined
it.  You can undefine an existing macro by typing an empty DEFINE
command for it, for instance:

  DEFINE IBM

Be aware of the following:

    1)  Macro definitions may not 'nest'.  This means that they may
        not include other macro names as set arguments.

    2)  Using a quoted macro name when defining will allow you to
        define macros that consequently can not be parsed.  One
        example would be the use of embedded spaces or tabs, such as
        "my macro".

        If this happens, then the macro may be removed by specifying
        the quoted name with the /UNDEFINE switch.  It is best to keep
        macro names being alphanumeric with with a dash ("-") or
        underscore ("_") as a seperator character.
&
>;;nmacro

emacro <
hchang: asciz &
/CHANGE set-parameter value

The /CHANGE switch is used to modify a single SET parameter in an
existing macro, that is, one that has been previously created with
either a DEFINE command or via the use of a DEFINE with the /DUPLICATE
switch.

The /CHANGE switch allows the creation of largely similar macros with
differing SET parameters.  This is useful when you are trying to
determine optimal values for a particular transfer as you can vary a
parameter while leaving others intact.

You can use the /DUPLICATE switch to create a macro that you can
use /CHANGE on if you want two macros that are only different by a few
parameters.

If the SET parameter being changed does not exist in the macro, then
it is added.
&
>;;emacro

hcompa: asciz &
/COMPACT

If Kermit gives an error that the macro buffer is full, you can use
the /COMPACT switch to run the garbage collector.  The delay for this
action is not normally noticeable.

/COMPACT will give some statistics to indicate what has been
reclaimed, if anything.  For example, a macro table that started out
with 11 macros, with four being undefined produces the following:

        Kermit-20>DEFINE/COMPACT
        Before: Macros: 7 used, 114 remaining.
        Available storage: 10705 characters
        After:  Macros: 7 used, 114 remaining.
        Available storage: 11315 characters
        Elapsed: 0.00097 (TOD: 0), CPU:  0.00094

The timing figures indicate that 970 microseconds were spent doing the
/COMPACT, of which 940 microseconds were processor related.  Elapsed
time is also known as "wall" time.

The /COMPACT switch is unnecessary if no macros have ever been
undefined or redefined. Issuing it in that case will do absolutely
nothing other than expend processor time, while at the same time
providing no benefit whatsoever.

Similarly, issuing two or more /COMPACT switches in a row will not
provide any further benefit.

Issuing a /COMPACT after a /RESET does nothing other than inform you
that there is nothing to compact.

It is possible to define the maximum number of macros while still
having remaining macro memory if the macro names and bodies are
relatively short.  In this case, while /COMPACT may be able to release
storage for macro names and bodies, you will still not be able to
DEFINE or /DUPLICATE a new macro because the limit being exceeded is
the number of entries in the macro keyword table.
&


hdump: asciz &
/DUMP [output file specification]

The macro table may be written directly to disk in a binary format
with the /DUMP switch, which takes an output file argument.  /DUMP
writes exactly what is in the table, so it will not write the smallest
file unless you /COMPACT the table, first.

The binary file may be read with the /MAP switch.  A smaller binary
file can both be written faster by /DUMP and processed faster by /MAP.
The size of the file produced by /DUMP bears little relation to what
is created with /SAVE.

If you have a large number of macros, then it may pay not to define
them in the KERMIT.INI file but rather have your KERMIT.INI map the
binary definitions which can then immediately be used with no further
parsing.  The character definitions themselves can always be extracted
with /SAVE.

The format of the binary file is designed for speed, not size.  It can
be used directly by Kermit.  A file produced by /SAVE may actually be
smaller, but takes far longer to process.

You may only dump to file structures.  Dumping the file to NUL: is
also allowed, but does not do anything of obvious value and is only
provided for debugging and checkout.

Although the binary file is not human readable, you can find out how
many macros are in the file by looking at the byte count in a
directory listing, which is the number of macros contained therein,
not the number of bytes.  This example shows a binary file with 7
macros in it.

  STAR:<KERMIT.K20MIT>
                          PGS Bytes(SZ)  Write                Writer

 K.BIN.5;P777700            1 7(0)       22-Jul-2022 22:47:59 SLOGIN

 Total of 2 pages in 1 file

The word size is 0 because it is meaningless, the contents of the file
having varying byte sizes.  This will also prevent both Kermit and the
EXEC from typing the file, which will produce nothing but gibberish
that runs the risk of locking up smart terminals and terminal
simulators.

If you wish to know what is in the file, use FILDDT and look at
k20mac. 
&


hdupli: asciz &
/DUPLICATE new-macro-name | "new-macro-name"

Takes the text associated with the indicated macro and creates a new
macro whose name is specified after the /DUPLICATE switch and sets
that new macro's body to be a copy of the text of the originally
specified macro.  For example:

        Kermit-20>SHOW IBM
          IBM = parity mark, duplex half, handshake xon
        Kermit-20>DEFINE IBM/DUPLICATE MBI
        Kermit-20>SHOW MBI
          MBI = parity mark, duplex half, handshake xon

You can only duplicate an existing macro.  The new macro's name can
not be that of an existing macro.  The new macro name may be specified
inside of double quotes to allow for question mark and escape
recognition after the field.

/DUPLICATE will optimally use macro storage space and thus it is not
necessary to do a /COMPACT, afterwards.
&


hmap:   asciz &
/MAP [input file specification]

The binary file created by /DUMP can be read with the /MAP switch.  It
is substantially faster to use the /MAP switch on startup than to
define all your macros in a TAKE file.

Kermit does a few checks on the binary file, but these are not
exhaustive.  If a binary file becomes corrupted, it can crash Kermit.

If this is a concern, you should also /SAVE your macros for recovery.
If you have not done this, you may be able to fix things with FILDDT,
the first part of the binary file being a TBLUK% table.

You can /MAP from NUL:, but this only does the equivalent of a /RESET
and is provided for debugging and checkout purposes.
&

emacro <
hremov: asciz &
/REMOVE set-parameter

Looks in a macro for the specified set-parameter and, if the parameter
exists in the macro text, it is removed from the macro text.

An error will be produced if Kermit detects an invalid set parameter
keyword in either the existing macro text or in the parameter to be
removed.

Normally, it is impossible for this situation to occur as the original
DEFINE should never have succeeded in the first place, even if it were
in a take file.  It is, however, possible to corrupt a dump file so
that this error will be seen.

It is not an error to attempt to remove a set parameter that was not
in the macro text to begin with.  In other words, removing a non-
existing set parameter will not terminate a batch stream.  However, it
will be remarked on in a benign way.

The macro must exist and its name must be unabiguously specified.

You can use the /DUPLICATE switch to create a macro that you can
use /REMOVE on if you want two macros that are only different by a few
parameters.
&
>;;emacro


hrenam: asciz &
/RENAME new-macro-name | "new-macro-name"

Changes the name of an existing macro, the text of the macro being
entirely unchanged.  It is different from /DUPLICATE in that the
existing macro name will no longer exist and its text is not
duplicated having been assigned to the new macro name.

Thus, the old macro text may now only be used by the new macro name.

For example:

        Kermit-20>SHOW IBM
          IBM = parity mark, duplex half, handshake xon
        Kermit-20>DEFINE IBM/RENAME MBI
        Kermit-20>SHOW MBI
          MBI = parity mark, duplex half, handshake xon

At this point, you can not do a SET IBM because the macro name IBM no
longer exists; you must do a SET MBI, instead.

You can only rename an existing macro.  The new macro's name can not
be that of an existing macro.  The new macro name may be specified
inside of double quotes to allow for question mark and escape
recognition after the field.
&


hreset: asciz &
/RESET

The /RESET switch may be used to remove all macro definitions,
resulting in a pristine macro table that is completely empty.  Thus,
the maximum macros, names and bodies will be available, viz:

        Kermit-20>DEFINE/RESET
        Kermit-20>DEFINE/SUMMARY
        Macros: 0 used, 121 remaining.
        Available storage: 12150 characters

Doing a /COMPACT after a /RESET does nothing useful because there is
nothing to /COMPACT.
&


hsave:  asciz &
/SAVE [output file specification]

You can save the macro table into a human readable (ASCII) file using
the /SAVE switch, which takes an output file argument.  It writes the
macro table as a series of DEFINE commands, which can subsequently be
used in a KERMIT.INI file or changed with a text editor.

It is not necessary to do a /COMPACT before a /SAVE; the resulting
file will always have the exact same size as the undefined macro text
will never be written.  This is in contrast to a /DUMP where doing a
/COMPACT beforehand can matter significantly.

The size of the file produced by a /SAVE does not bear an immediately
obvious relation to what is created with /DUMP and it is not useful to
compare the two as they are designed for different purposes, the
former for readability and the latter for speed.

You can only /SAVE to file structures with two exceptions:

    1)  You can save to your currently logged in terminal (TTY:) to
	see what would be written to disk.  The information displayed
	is effectively no different than what you would see from a
	SHOW MACROS.  This functionality is primarily used for
	debugging and checkout.

    2)  You can /SAVE to NUL:, but this does nothing particularly
        useful and is only used for debugging and checkout.

You can not /SAVE to any other device nor someone else's terminal nor
any other line, even if you have assigned that line.
&


hsumma: asciz &
/SUMMARY

The /SUMMARY switch provides a brief analysis of current macro table
resource usage, as follows:

        Kermit-20>DEFINE /SUMMARY
        Macros: 11 used, 110 remaining.
        Availible storage: 10705 characters
&


hundef: asciz &
DEFINE existing-macro-name /UNDEFINE

Another way remove a macro is to follow the macro name with an explicit
/UNDEFINE switch.  Therefore, the following two commands do the same
thing: 

  DEFINE IBM

  DEFINE IBM /UNDEFINE

If you've managed to define a macro name that turns out to be quirky
in some way or completely unusable, you can put it in quotes to
undefine it, for example:

  DEFINE "WRONG WAY" /UNDEFINE

Be aware that undefining a macro does not automatically reclaim the
memory for reuse as this operation is relatively computationally
expensive and, since most macros are read from the KERMIT.INI file, is
not expected to happen frequently, if ever.

See the /COMPACT switch for information on handling out of memory
situations.
&

;[214] End help insertion


; LOG help text..

hlog:   asciz &
LOG TRANSACTIONS | SESSION | DEBUGGING (to) filespec

Begins logging various information to files.

TRANSACTIONS:

Direct Kermit-20 to log transactions, such as files successfully sent
or received, files that could not be successfully sent or received,
and so forth, to the specified file.

SESSION:

Create a transcript of a CONNECT session, when running Kermit-20 in
local mode and connected to a remote system, in the specified file.
Log is closed when connection is closed.  Logging can be toggled by
typing the connect escape character followed by Q (Quit logging) or R
(Resume logging).

DEBUGGING:

Log the selected information (STATES or PACKETS, type HELP SET DEBUG
for further information) to the specified file.  If log file is not
specified, then use TTY if local, DEBUGGING.LOG if remote.  If
specified, then log STATES by default.  Also allow specification of
bytesize for log file, 7 (normal, default), or 8 (for debugging binary
transfers, use FILDDT to inspect the log).

Besides the TTY case described above, all Log files are required to be
on disk with one exception.  It is possible to log to the NUL: device,
but this does nothing useful except expend extra processor cycles.
The feature is used for debugging and check out.

Log files are closed upon exit from Kermit-20, or explicitly by the CLOSE
command.
&



; PROMPT help text...

hpromp: asciz |
PROMPT

If Kermit-20 runs in server mode by default, typing the following
command to the TOPS-20 Exec

   kermit prompt

will start it up in interactive mode, and leave you at the
"Kermit-20>" prompt.  This is the only instance where PROMPT provides
any obvious functionality.

Otherwise, it is of limited use.  If you are running interactively,
PROMPT will do nothing.  If you interactively put a remote Kermit into
SERVER mode, you must escape back to the local Kermit and issue a
FINISH command.  If you type SERVER to a local Kermit that is not
connected to anything, then you will need to issue a ^C to get back to
the "Kermit-20>" prompt.

Use SET PROMPT to change the Kermit-20 command prompt.
|


hpush:  asciz |
PUSH

Push to a DEC-20 command processor.  Get back to KERMIT with all current
settings intact by typing the Exec POP command.

During the PUSH, if a remote connection exists, then that connection
will be held open and you will be returned to it if you pushed from
the via the escape character.
|



; Help text.

hserve: asciz |
SERVER

Act as a server for another Kermit.  Take all further commands only
from the other Kermit.  Only works when running remotely.  After
issuing this command, escape back to your local system and issue SEND,
RECEIVE or GET, REMOTE, FINISH, BYE, or other server-oriented commands
from there.

If your local KERMIT does not have a BYE command, then you should
check to see if it has the FINISH command.  In that case, you can
issue a FINISH, which does not close an active connection, but does
cause the remote KERMIT to exit at which point you can reconnect and
log out manually.

If your local KERMIT has neither BYE nor FINISH, it does not have the
full ability to communicate with a KERMIT server in which case you
shouldn't run Kermit-20 as a server.

If your local KERMIT does have a BYE command, use it to shut down and
log out the KERMIT server when you are done with it.  Otherwise, use
the FINISH command as described above.

If neither works, you can try reconnecting to the remote DEC-20 and
typing several Control-C's to stop the server, and logout.

For doing nonstandard kinds of file transfer (for instance to send
binary files from a microcomputer), you must issue the appropriate SET
commands before the SERVER command.
|


; GET command help text.

hget:   asciz \
GET [remote-filespec] | ["remote-filespec" [ local-filespec ] ]

For use only when talking to a remote KERMIT server.

When running as a local KERMIT (I.E., when communicating with a remote
KERMIT over an assigned TTY line, which you have specified with the
SET LINE command or having done a SET HOST command), you may use the
GET command to request the remote KERMIT server to send you the
specified files.

The remote-filespec is any string that can be a legal file
specification for the remote system; it is not parsed or validated
locally.  As files arrive, their names will be displayed on your
screen, along with "." and "%" characters to indicate the packet
traffic.  You may type Control-A to get a brief status report, ^X to
request that the current incoming file be cancelled, or ^Z to request
that the entire incoming batch be cancelled.

If the remote KERMIT is not capable of server functions, then you will
probably get an error message back from it like "Illegal packet type".
In this case, you must connect to the other Kermit, give a SEND
command, escape back, and give a RECEIVE command.

Syntax: The first form of GET command accepts an arbitrary string,
terminated by a carriage return.  The string specifies a file or files
in the syntax of the remote system.

The normal DEC-20 command characters for help (?), comment
delimitation (! and ;), and file indirection (@) are enabled at the
beginning of the field, you can only enter filenames starting with one
of these characters by "quoting" it with a Control-V, which is
discarded before sending the string to the remote system.

If you want to store the incoming file name with a different name than
the remote host sends it with, just type GET alone on a line;
Kermit-20 will prompt you separately for the source (remote) and
destination (local) file specification.  If more than one file
arrives, only the first one will be stored under the given name; the
rest will be stored under the names they are sent with.

The second form of the command can be used gain the same functionality
on a single line by enclosing the remote file specification in double
quotes.  Escape recognition can then be used on the local file
specification.  The following example gets an ITS file "foo bar" from
the baz device and stores it locally as foo-bar.txt:

        GET "BAZ;FOO BAR" FOO-BAR.TXT

The local file must be stored on a mounted file structure to which the
user has access.  It is possible to store to NUL:, but this does
nothing but throw the data away and is only used for testing and
debugging purposes.
\


; Help text

hrecei: asciz |
RECEIVE [filespec]

Receive a file or file group from the other host.  If only one file is being
received, you may include the optional filespec as the name to store it under
when it arrives; otherwise, the name is taken from the incoming file header
packet.  Even if the name in the header packet is not a legal TOPS-20 file
name, Kermit-20 will store it under that name, in which case you can refer to
it later only by quoting the illegal characters (spaces, lowercase letters,
control characters, etc) with ^V.  (You may also use SET FILE NAMING to have
Kermit-20 pick out a more conventional name.)

If a file with the same name already exists, Kermit-20 just creates a new
generation of the same name and type.

A file can only be received into a disk structure.  NUL: may also be
given, but this is useful only for debugging and best case timings,
which should not normally be necessary.

If running as a local Kermit, the names of the incoming files will be
displayed on your screen, along with "." and "%" characters to indicate the
packet traffic; you can type Control-A during the transfer for a brief status
report.

If you are asking Kermit-20 to receive binary files from a microcomputer or
other 8-bit system, you must first type SET FILE BYTESIZE 8.  Otherwise, the
8th bit of each byte will be lost.  For ordinary text files, no special action
is necessary.

If you have SET PARITY, then 8th-bit quoting will be requested.  If the other
side cannot do this, binary files cannot be transferred correctly.  In all
cases, Kermit-20 will request the other KERMIT to compress repeated characters;
if the other side can do this (not all KERMITs know how) there may be a
significant improvement in transmission efficiency.

When running locally and receiving files, you can attempt to cancel the
current file by typing Control-X; this sends a cancellation request to the
remote KERMIT.  If the remote KERMIT understands this request, it will comply;
otherwise it will continue to send.  If a file group is being sent, you can
request the entire group be cancelled by typing Control-Z.

If running as a remote Kermit, you should escape back to your local Kermit and
give the SEND command.
|



; Help text.

hsend:  asciz |
SEND filespec (AS) [target-name]
SEND wild-filespec1 (INITIAL) [initial-file]

Send a file or file group from the DEC-20 to the other host.  If the filespec
contains wildcard characters (* or %) then all matching files will be sent, in
alphabetical order by name.  If a file can't be opened for read access, it will
be skipped.  The name of each file is passed to the other host in a file header
packet, so that the file can be stored there with the same or similar name.

If a single file is specified, you may optionally specify a diffent name for it
"target-name") to be sent in the file header packet.  This name is not parsed;
it is sent to the other system as is, except any lowercase letters are raised
to upper case.

If a wildcard file group is specified, you may optionally specify an initial
file to send.  This is handy to continue a previously interrupted wildcard
transfer from where it left off, or to skip some files that would be
transmitted first.

If running as a local Kermit, the name of each file will be displayed on your
screen as the transfer begins, a "." will be displayed for every 5 data packets
sucessfully sent, and a "%" for every retransmission or timeout that occurs
you may also elect other typeout options with the SET DEBUG command).  If you
see many "%" characters, you are probably suffering from a noisy connection.
You can type Control-A at any point during the transfer to get a brief status
report.

When running locally and sending files, you can cancel (stop sending) the
current file by typing Control-X.  If sending a file group, Control-X will
cause the current file to be skipped, and Kermit-20 will go on to the next
file.  Control-Z will cancel sending the entire group and return you to
Kermit-20 command level.

If running as a remote Kermit, you should escape back to your local Kermit and
give the RECEIVE command.  If you don't do this fast enough, several
"send-init" packets may arrive prematurely; don't worry, Kermit-20 will keep
sending them until it gets a response.

If communication line parity is being used, Kermit-20 will request that the
other KERMIT accept a special kind of prefix notation for binary files.  This
is an advanced feature, and not all KERMITs have it; if the other KERMIT does
not agree to use this feature, binary files cannot be sent correctly.  This
includes executable programs, relocatable object modules, files with EDIT line
sequence numbers (as produced by EDIT, SOS, or OTTO), etc.

Kermit-20 will also ask the other KERMIT whether it can handle a special prefix
encoding for repeated characters.  If it can, then files with long strings of
repeated characters will be transmitted very efficiently.  Columnar data,
highly indented text, and binary files are the chief beneficiaries.
|


;[120] HELP server command.

srvhlp: intern srvhlp
        asciz /
The DECSYSTEM-20 KERMIT server is capable of the following:

                                    Command you would normally type to your
  Server Function:                  local KERMIT to invoke the server function:

  Receive a file or file group      SEND filespec
  Send a file or file group         GET filespec
  Logout                            BYE
  Exit to TOPS-20                   FINISH
  Delete a file or file group       REMOTE DELETE filespec
  List file(s) at the terminal      REMOTE TYPE filespec
  Provide a directory listing       REMOTE DIRECTORY filespec
  Change working directory          REMOTE CWD directory [password]
  Print working directory           REMOTE PWD
  Report disk usage                 REMOTE SPACE
  Provide status of last transfer   REMOTE STATUS
  Send this message                 REMOTE HELP
/ ;[189] 

        xlist                   ; We surely don't care about all those little numbers
        lit                     ;[194] Dump any literals (there won't be any)
        list                    ; Turn the listing back on
        .endps help             ;[190] Close off help .PSECT

;;;;    .xcmsy (macsym not searched)    ;[194] Ditch MACSYM junk

        end

; Local Modes:
; Mode:MACRO
; Comment Column:32
; Comment Start:;[239] 
; Comment Begin:;[239] 
; Auto Fill Mode: 0
; End: