Columbia Kermit/kermit.zip/cdccyber/cd3ker.mss

Text File | 2020-01-01 | 19KB | 431 lines

@make(manual)
@device(talaris)
@Style<Justification On, Hyphenation On, WidestBlank 1.4, Spacing 1,
        Spread 1, Indent 0, HyphenBreak Off, DoubleSided>
@Define<Q,FaceCode R>
@Case<Device,
 TALARIS=(
    @Define<QU,FaceCode R,AfterEntry=[],BeforeExit=["]>),
 ELSE=(
    @Define<QU,FaceCode R,AfterEntry=["],BeforeExit=["]>)
 >
@heading<Cyber 170 Kermit>
@begin<description,leftmargin +10,indent -10,spread 0>
@i(Author:)@\Jim Knutson, University of Texas.

@i(Language:)@\CDC FTN5 (Fortran 77) and COMPASS Assembler

@i(Version:)@\2.2@ @ @ @ September 1984, Jim Knutson, University of Texas.
@i( )@\2.2.1@ @ June 1985, Mark Miller, S. O. Lidie, Lehigh University.
@i( )@\2.2.2@ @ July 1986, S. O. Lidie, Lehigh University.
@i( )@\3.0@ @ @ @ October 1984,  Joerg Hallbauer, Cal State University.
@i( )@\3.1@ @ @ @ December 1984,  Paul Wells, University of Washington.
@i( )@\3.2@ @ @ @ February 1987, Steve Roseman, Lehigh University.
@i( )@\3.3@ @ @ @ March 1987, Steve Roseman, Lehigh University.

@end<description>

@B<CYBER 170 Kermit Capabilities at a Glance:>
@begin<verbatim>  @tabset<+32>

 Local Operation@\No
 Remote Operation@\Yes
 Transfers text files@\Yes
 Transfers binary files@\Yes
 Wildcard Send@\Yes
 ^X/^Z interruption@\Yes (through micro)
 Filename collision avoidance@\Yes
 Can time out@\Yes
 8th-bit prefixing@\Yes
 Repeat count prefixing@\Yes
 Alternate block checks@\No
 Terminal emulation@\No
 Communications settings@\No
 Transmit BREAK@\No
 Transaction logging@\Yes
 Session logging@\No
 Raw transmit@\No
 Sliding windows@\No
 Long packets@\Yes
 Act as server@\Yes
 Talk to server@\No
 Advanced server functions@\No
 Advanced commands for servers@\Limited
 Handle Attribute Packets@\No
 Command/Init files@\Yes
 Command Macros@\No
@end<verbatim>

@Section<Cyber File Systems>

The features of the Cyber's file system that are of greatest interest to
Kermit users are storage class, file structure, file specifications and
character sets.

@Subheading<Cyber Storage Classes>

The NOS operating system uses the concept of local and permanent file storage.
This means that files that are to be kept around after a job is finished must
be moved to permanent storage first.  Jobs that wish to use a file from
permanent storage must copy or attach it to local storage before using it.

To send a file from the Cyber, you may GET/ATTACH the file before entering
Kermit, or have Kermit access the file itself.  If you request that Kermit
send a file which is not found as a local file, it will attempt to find a
matching permanent file.  You may restrict Kermit to local or permanent files
by prefixing the file name with @B<L:> or @B<P:>, respectively. After
receiving a file on the Cyber do not forget to SAVE/REPLACE/DEFINE the file to
make it permanent.

The DIRECTORY command and REMOTE DIRECTORY server command allow the user to
display the names of available local or permanent files.

@Subheading<Cyber File Structure>

Many Cyber files use internal structure information.  Cyber Kermit supports
two file types: Z-type (line image, unit record) called TEXT, and any other
arbitrary file whose data is transferred 8 bits at a time (7.5 bytes per
60-bit word), called BINARY.  Other internal file structures, such as other
Cyber Record Manager record types, are not supported by Cyber Kermit.

@Subheading<Cyber File Specification>

A NOS file name consists of from one to seven alphanumeric characters.  Special
characters are not allowed in the file name.  File names beginning with ZZ or
SCR should be avoided, since these are commonly used scratch file names.

@index<Wildcard>

Cyber Kermit allows a group of files to be specified in a single file
specification by including the special @qu"wildcard" characters, @qu"*" and
@qu"?".  A @qu"*" matches any string of characters, including no characters at
all; a @qu"?" matches any single character.  Any number of @qu"*" and @qu"?"
may appear in a wildcard specification.  To complement the selection criteria,
suffix a @qu"-" to the wildcard specification.

Here are some examples:
@Begin(Description,spread 0.5,leftmargin +10, indent -8)
@q<*BUG>@\All files ending in @q<BUG>.

@q<*DOG*>@\All file names containing @q<DOG>.

@q<F*>@\All files whose names start with F.

@q<F?X*>@\All files whose names start with F and contain X in
the third position, followed by zero or more characters.

@q<FRED->@\All files except FRED.
@End(Description)

Wildcard notation is most commonly used to instruct Kermit to send, or display
a directory of, a group of files.  Its usage is similar to capabilities on
many other computer systems.

@Subheading<Cyber Character Sets>

Until the recent NOS/VE operating system, the character set used by most Cyber
systems was a six bit DISPLAY CODE character set.  The six bit character sets
supported by Cyber Kermit are the 63 and 64 character sets.  These character
sets differ in the use of the COLON and PERCENT SIGN characters.

There are also several ASCII character sets in use on NOS.  One set, called
6/12 or simply ASCII, uses 6-bit DISPLAY CODE characters with certain
characters set aside as flags to indicate lower case or control characters.

Another ASCII character set is the 8/12 or ASCII8 character set.  This stores
ASCII characters as 8 bits in a 12-bit byte.  The exception to this is that an
EOL (End-Of-Line) is indicated by the usual CDC convention of at least twelve
bits of 0 (0000B) in the low order bits of the word.  NUL characters are
represented as 4000B to prevent interpretation as an EOL sequence.

Cyber Kermit will normally automatically recognize the character set when
sending a TEXT file, and will do the appropriate conversions.  The first
buffer full (approx 1000 characters) from the disk file is examined and the
file is recognized to be 8/12 ASCII if the top 4 bits of each byte are zero;
6/12 ASCII if the first 2 characters in any CM word are lower case; display
code otherwise.  Received TEXT files are normally converted to 6/12 ASCII.
The SET TEXT-MODE command allows the user to request specific conversion modes
of DISPLAY, 6/12-ASCII, or 8/12-ASCII, or set AUTO conversion as described
above.

@Section<Program Operation>

Cyber Kermit's prompt is @qu"Kermit-170>".  It must be run
interactively and has no parameters.  Commands can be
typed in like this:
@begin<example>
/@ux[kermit]
Cyber-170/NOS KERMIT Ver 3.2.0  (87/01/16)
Kermit-170>@ux[send dog*]

  [the files are sent]

Kermit-170>@ux[status]

  [performance statistics are printed]

Kermit-170>@ux[receive]

  [files are received]

Kermit-170>@ux[exit]
/
@End<example>

@index(KERMINI) @index(Kermit Initialization)

Cyber Kermit provides an initialization file capability.  It will look for a
file named KERMINI in the user's local files, and then in the permanent file
catalog.  If found, Kermit will take commands from this file before requesting
commands from the user.

@index<Help>
Cyber Kermit mimics the DEC-20 style command parser in that a question mark
followed by a carriage return may be placed anywhere on the command line
(except for the SEND and DIR commands).
This will display the options available at that point.  Unfortunately, the
entire command will have to be retyped afterwards.

Command keywords may be abbreviated to their shortest unique combination.
This comes in very handy since Cyber Kermit does not support command
completion.

Cyber Kermit may only be run as a remote Kermit.  This Kermit is @qu"smart"
and hence need not be closely watched during a transfer since it will timeout
in a deadlock situation.

A Cyber filename is restricted to 7 alphanumeric characters. When a file is
being sent to the Cyber, Kermit will take up to 3 characters of the extension
(part following a period) of the micro's file name, plus as much as possible
from the first part of the file name.  This will lessen the conflicts when
transferring a group of files with the same name but different extensions.

If a file under that name already exists, an @qu"error packet" stating so will
be sent back to the micro and Cyber Kermit will abort the entire transfer.

@index<Parity>
If you are having trouble transferring files with Kermit, it may be due to the
parity.  Cyber Kermit has no way of determining the parity of the connection
and does not affect it in any way.  If you are having problems getting the
first packet to transfer, then this is probably the problem.  If necessary,
enter a !@ TRMDEF command from within Kermit to set the Cyber front-end's
parity to match that of your micro (eg.  !@ TRMDEF,PA=N for no parity,
!@ TRMDEF,PA=E for even.)

@Section<Cyber Kermit Commands>
The following is a list of Cyber Kermit commands and their descriptions.
@begin<description,leftmargin=+10,indent=-10>
@Index<!>
! @i<command>@\@ Execute a NOS command and then return to Kermit.
Note that a single space must follow the ! character.
Cyber Kermit will supply a control statement terminator if needed.

@index(DIR)@index(DIRECTORY)
DIRECTORY [@i<filename>]@\Displays the names of the files
local to the
user's job, or the names of files in the user's permanent file catalog;
@i<filename> may be a wildcard filename.
@blankspace<1 line>
If the command is specified with no
parameters or the L: parameter, all local files are listed.  If the P:
parameter is used, all permanent files are listed.
@blankspace<1 line>
To list a single local file or subset of local files, the user may specify a
file name or wildcard file name.  To list a single or subset of permanent
files, the user may precede the file name or wildcard file name by P:
@blankspace<1 line>
[The above syntax is also applicable to the REMOTE DIRECTORY server command.]

@Index<EXIT>@index<QUIT>@Index<Control-C>
EXIT, QUIT@\Exit from Kermit-170.  You may also stop Kermit-170 in the midst
of a transfer or during server operations by aborting your local Kermit
with a CTRL-C.  Connect to the Cyber Kermit (don't forget to first FINISH
if you were using the Cyber Kermit in server mode) and then EXIT.

@Index<HELP>
HELP [@i<topic>]@\Give Help.  There's a general help text, plus
separate help texts for each Kermit-170 command.  HELP ? lists the available
topics.

@Index<PUSH>
PUSH@\Exit to NOS command level, saving the current Kermit
environment.  The environment will be restored when Kermit is
reentered.

@index<RECEIVE>
RECEIVE@\Receive a file or group of files from the other host.
If the name in the header packet is not a legal Cyber file name,
the first 7 legal characters will be used.
@blankspace<1 line>
If the file already exits as a local file, Kermit will abort the transfer.
If an error occurs during transfer, the local file being received will be
deleted to allow the transfer to be retried.
After entering the RECEIVE command, you should escape back to your local Kermit
and give the SEND command.

@index<SEND>
SEND @i<filename or L:filename or P:filename>
@\Send one or more files to the local (micro) Kermit; @i<filename> may
be a wildcard filename.  The name of each file is
passed to the other Kermit in a file header packet, so that the file can be
stored there with the same name.
You should escape back to your local Kermit and give the RECEIVE
command.  If you don't do this fast enough the @qu"send-init" packet may
arrive prematurely.  To prevent this, use SET DELAY or hit the RETURN key
on your microcomputer if it does not timeout.
@blankspace<1 line>
If you use the first form of this command and no local file(s) match your
request, your permanent file catalog is searched for matching file(s).
If you prefix the filename with L:, only your local files are searched; if P:,
only your permanent file catalog is searched.  (Note that for a permanent file
transfer, any local file which has the same name as a permanent file being
sent, is deleted.)

@Index<SERVER>@Index<Control-C>
SERVER@\Act as a server for another Kermit.  Whatever options were
previously SET will be used.  The server may be shut down from the local
Kermit by using the BYE or FINISH commands.
Generally, you should use the FINISH command if you were transferring
a file to the Cyber so that you may then connect and make the file
permanent. The BYE or LOGOUT command causes the remote Kermit to logout
and thus should be used when receiving a file from the Cyber and there
is no real reason to re-connect.
@blankspace<1 line>
The following server features are currently supported in Kermit-170:
GET, SEND, FINISH, BYE, REM DIR

@Index<SET>
SET @i{keyword value}@\Establish system-dependent parameters.  You can examine
their values with the
SHOW command.  Numeric values may be decimal, octal (postfixed with a B),
or hexadecimal (postfixed by an H).  The following may be SET:
@Begin(Description,leftmargin +4,indent -4)
@index<Debugging>
DEBUG @i<option>@\Show packet traffic explicitly.  Options are:
@Begin(Description,leftmargin +4,indent -4)
ALL@\Set all debug options (PACKETS and STATES).

LOG-FILE @i<filename>@\Log states and packets to the specified file.  The
default log-file is named KERMLOG.

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

PACKETS@\Log each incoming and outgoing packet (lengthy).

STATES @\Log Kermit state transitions and packet numbers (brief).
@End(Description)

DELAY @i<decimal-number>@\Sets the number of seconds to wait before sending
the first packet.  This gives you time to @qu"escape" back and issue a RECEIVE
command.  The default is 2 seconds.

@index<Duplex>
DUPLEX @i<keyword>@\Changes the method of echoing characters when being
prompted for commands.
The choices are FULL and HALF.  FULL means the Cyber will echo the
characters you type.  HALF means the local system echoes them.  FULL is
the default, and is used by most hosts.

@index<File Type>
FILE-MODE @i<ftype>@\Declares the file mode to be used while processing Cyber
disk files.  Allowable values for @i<ftype> are TEXT and BINARY.
TEXT means that the file contains text in either 8/12 ASCII, 6/12 ASCII, or
Display Code (See SET TEXT-MODE command). BINARY means that file contains
binary data, packed 7.5
8-bit bytes per 60-bit word.  The default is TEXT.

@index<Retry>
INIT-RETRY @i<decimal-number>@\Set the maximum number of retries allowed for
the initial connection before giving up. Default is 15.

@index<Receive>@index<Receive Files>
RECEIVE @i{parameter value}@\These commands allow you to specify
to the other Kermit what the packets it sends should look like,
or to inform this Kermit what to expect.  @i<Value> may be
specified as a decimal number, an octal number (B suffix), or a
hexadecimal number (H suffix).  Character values are specified
as the numeric equivalent of the ASCII character.
@Begin(Description,leftmargin +4,indent -4)
END-OF-LINE @i<value>@\The octal value of the ASCII character which will be
used as a line terminator for packets by the other system.  Carriage return
(15B) is the default.

PACKET-LENGTH @i<value>@\Maximum packet length the other system may send,
a decimal number, between 20 and 1000,
94 by default.  Size used is the minimum of this parameter and the
SEND PACKET-LENGTH of the other Kermit.

PAD-CHARACTER @i<value>@\Character to use for padding.  Default is NUL.

PAD-LENGTH @i<value>@\Set the number of padding characters to send before a
packet.  Default is no padding.

QUOTE-CHARACTER @i<value>@\The printable character to use for quoting of
control characters. Default is # (43B).  There should be no reason to change
this.

SYNC-CHARACTER @i<value>@\The control character that marks the beginning of
the packet.  Normally SOH (Control-A, ASCII 1).  There should be no reason
to change this.

TIME-OUT @i<value>@\The number of seconds the other Kermit should wait for a
packet before asking for retransmission. Default is 10 seconds.
@End(Description)

RETRY @i<decimal-number>@\Sets the maximum number of retries allowed for
a particular packet before giving up. Default is 10.

SEND @i{parameter value}@\These commands allow you to specify how outgoing
packets should look, in case the other Kermit has non-standard requirements.
@Begin(Description,leftmargin +4,indent -4)
END-OF-LINE @i<value>@\The octal value of the ASCII character to be used as a
line terminator for packets, if one is required by the other system.  Carriage
return (15B) by default.

PACKET-LENGTH @i<value>@\Maximum packet length to send, decimal number,
between 20 and 1000, 94 by default.  Size used is the minimum of this
parameter and the RECEIVE PACKET-LENGTH of the other Kermit.

PAD-CHARACTER @i<value>@\Character to use for padding.  Default is NUL.

PAD-LENGTH @i<value>@\Set the number of padding characters to send before a
packet.  Default is no padding.

QUOTE-CHARACTER @i<value>@\The printable character to use for quoting of
control characters.  The default is # (43B).  There should be no reason
to change this.

SYNC-CHARACTER @i<value>@\The control character that marks the beginning of
the packet.  Normally SOH (Control-A, ASCII 1).  There should be no reason
to change this.

TIME-OUT @i<value>@\How many seconds to wait for a packet before
trying again.  Default is 10 seconds.
@End(Description)

@index<Text Mode>
TEXT-MODE @i<ctype>@\Sets the character set of TEXT files.  Allowable values
for @i<ctype> are: AUTO, DISPLAY, 6/12-ASCII, and 8/12 ASCII.  The default is
AUTO, which tells Cyber Kermit to attempt to auto-recognize files on send,
and write 6/12 ASCII files on receive.
@End(Description)

@index<SHOW>
SHOW@\Display current SET parameters, version of Kermit-170, and other
information.

@index<STATUS>
STATUS@\Give statistics about the most recent file transfer.

@index(TAKE)
TAKE @i<filename or L:filename or P:filename>@\Take Kermit commands from a
file.  Kermit will first look in the user's local files; if not found it will
then look in the permanent file catalog.  You may restrict the search by
prefixing the filename with "P:" or "L:".  (See the SEND command above.)  When
an logical end-of-record is encountered on the TAKE file, Kermit will revert
to accepting commands from the terminal.  TAKE commands cannot be nested; a
TAKE command read from a file will begin reading commands from the new file,
but at it's end will not revert to the first file.
@End(Description)