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

Text File | 2020-01-01 | 18KB | 439 lines

@part(170KERMIT,root="USER")
@Chapter<CYBER 170 KERMIT>
@label<-k170>
@Index[CDC]
@Index[NOS]
@Index[NOS/BE]
@Index[CYBER]
@begin<description,leftmargin +12,indent -12,spread 0>
@i(Authors:)@\Jim Knutson, University of Texas

@i(Version:)@\2.2

@i(Date:)@\September 1984
@end<description>

Cyber Kermit was written for a Cyber 170/750 in
FTN5, CDC's FORTRAN 77 compiler.  It should run on any NOS or
NOS/BE system with only minor changes to the I/O routines.  This
is a necessary evil since every Cyber site seems to run a
different front end.

@Section<Cyber File Systems>

The features of a Cyber file system of greatest interest to
KERMIT users are storage class, file structure, file
specifications and character sets.

@Subheading<Cyber Storage Classes>

The NOS and NOS/BE operating systems use 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 to local storage first before using it
(actually, direct access permanent files help alleviate this
problem).  Most Kermit users will only want to use local files.

@Subheading<Cyber File Structure>

Many Cyber files use internal structure information much like VMS
files.  These internal structures are mainly used in executable
binary files or certain CRM record types.  The internal structure of
files is not currently supported by Cyber Kermit.  Cyber
executable binaries, and multi-record files are not
transferable using Kermit.

@Subheading<Cyber File Specification>

A Cyber file name consists of from 1 to seven alphanumeric
characters.  NOS systems allow the first character to be numeric
but most Cyber processors do not support this.  Cyber Kermit
allows the first character to be a digit on NOS systems.  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.  The Cyber Kermit command processor does not
support wild cards at this time.

@Subheading<Cyber Character Sets>

Until the recent Cyber 800 Series mainframes, 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 character, 64 character and UT 64 character sets.  These
character sets not only differ in their ordering but also in the
characters they use.  Some use the underscore and percent sign,
others do not.  ASCII characters received by Cyber Kermit are
translated to the appropriate display code when possible.  A
character that can not be translated will be set to a blank.
Users of the 64 character set may have
problems with colons at the end of a line being truncated or
lines with sequential colons being split into two or more lines since
the character value of a colon is 00B (half of an End-Of-Line).

There are also several ASCII character sets in use on the various
Cyber systems.  One set, called 6/12, uses 6 bit display code
characters with certain characters set aside as flags to indicate
case (upper/lower) or control characters.  Cyber Kermit does not
support the 6/12 character set.  Another ASCII character set is
the 8/12 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 also support UT 8/12 ASCII.
The difference between this and NOS 8/12 ASCII is UT 8/12 ASCII
uses the NEL character (205B) from the 256 character ASCII set to
represent an End-Of-Line.

@Section<Program Operation>

Cyber Kermit's prompt is "Kermit-170>".  It must be run
interactively and without any parameters.  Commands can then be
typed in like this:
@begin<example>
.@ux[kermit]
Kermit-170>@ux[send foobar]

  [file foobar sent]

Kermit-170>@ux[status]

  [performance statistics are printed]

Kermit-170>@ux[receive]

  [files are received]

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

@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.  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.
It must be watched during transfer if the local
Kermit has no timeout since it has no timeout capabilities.

A Cyber filename is restricted to 7 alphanumeric characters with the first
character being an alpha.  Kermit will use the first 7 valid characters
of any file being sent to the Cyber.  If a file under that name already
exists, an Error packet stating so will be sent back and Cyber Kermit will
abort the 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 so it just guesses that it will be NONE.
If you are having problems getting the first packet to transfer,
then this is probably the problem.  If you are running with a
parity other than NONE, then you must use the SET PARITY command
every time you enter Cyber Kermit.

@Section<Cyber Kermit Commands>
The following is a list of Cyber Kermit commands and their description.
@begin<description>
@Index<!>
! @i<command>@\Execute a Cyber control command and then return to
Kermit.

@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 the program (CTRL-C or
CTRL-G ABORT); the program traps them and puts your terminal back to normal
before halting.

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

@Index<PUSH>
PUSH@\Exit to control 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 file being received will be
removed from the local file list to allow the transfer to be retried.
You should escape back to your local Kermit after entering RECEIVE
mode and give the SEND command.

@index<SEND>
SEND @i<filename>@\Send a file to the other host.  The name of the file is
passed to the other host 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 "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.

@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, or by
connecting back to the Cyber, and typing Control-C or Control-G ABORT.

@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 +8,indent -8)
@index<Character Set>
DATA-MODE @i<ctype>@\Set the character code to use for files
received by Kermit-170.  Allowable values for @i<ctype> are:
ASCII, DISPLAY-CODE, IMAGE-ASCII, NOS-ASCII.  The interpretation
of these is dependent on the system.  DISPLAY-CODE will be the
six bit character set in use at the site (63 or 64).  ASCII will
be NOS 8/12 ASCII for all sites except the University of Texas.
NOS-ASCII is used to describe NOS 8/12 ASCII at UT while ASCII
describes UT 8/12 ASCII.  The default character set in use when
Kermit starts up is DISPLAY-CODE.  Automatic character set
recognition is used for sending files unless IMAGE-ASCII is set.

@index<Debugging>
DEBUG @i<option>@\Show packet traffic explicitly.  Options are:
@Begin(Description,leftmargin +8,indent -8)
ALL@\Set all debug options.

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

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

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

STATES@\Show kermit state transitions and packet numbers (brief).
@End(Description)

DELAY @i<decimal-number>@\How many seconds to wait before sending the first
packet.  This gives you time to "escape" back and issue a RECEIVE command.

@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 systems echoes them.  Full is
the default, and is used by most hosts.

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

@index<Parity>
PARITY @i<keyword>@\Allows you to adjust the parity on characters
sent or received by Kermit-170 to
another system's requirements.  The possibilities are NONE, EVEN, ODD,
SPACE, or MARK.  If NONE, then the 8th bit can be used for data when
sending and receiving binary files.  If other than NONE, the 8th bit
on outgoing characters will be set to achieve the desired parity, and the
8th bit on incoming characters will be discarded.  The default is NONE.

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).  Characters values are specified
as the numeric equivalent of the ASCII character.
@Begin(Description,leftmargin +8,indent -8)
END-OF-LINE @i<value>@\The octal value of the ASCII character to
be used as a line terminator
or packets, if one is required by the other system.  Carriage return
(15B) is the default.

PACKET-LENGTH @i<value>@\Maximum packet length to send, decimal
number, between 20 and 94,
94 by default.

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

PAD-LENGTH @i<value>@\How much padding to send before a packet.  Default is
no padding.

QUOTE-CHARACTER @i<value>@\What printable character to use for quoting of
control characters.

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 the other Kermit should wait for a packet
before asking for retransmission.
@End(Description)

@index<Performance Tuning>
RDELAY @i<millisec>@\Set up a delay of @i<millisec> seconds
before each TTY read.  This can be used for performance tuning by
causing enough delay that data will be ready when the read is
issued.  If data is not ready when the read is issued, the job
will be swapped out.  The delay should be specified as a multiple
of 100.  The default delay is 100 milliseconds.

RETRY @i<value>@\Set the maximum number of retries for a given packet before
giving up.

SEND @i{parameter value}@\These commands allow you to specify how outgoing
packets should look, in case the other Kermit has nonstandard requirements.
@Begin(Description,leftmargin +8,indent -8)
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 94, 94 by default.

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

PAD-LENGTH @i<value>@\How much padding to send before a packet.  Default is
no padding.

QUOTE-CHARACTER @i<value>@\What 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 the other Kermit should wants before
being asked for retransmission.  Unfortunately, the Cyber has no way of
timing out so this parameter is ignored.
@End(Description)
@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.
@End(Description)

@Section<Installation>

Cyber Kermit is distributed in two forms.  If you received it from
Columbia University, the sources are in UPDATE source format.  If
you received it from the University of Texas, it will be in UPDATE
program library format.  Other formats may be written by the
University of Texas upon request.

The Cyber Kermit source comes in two files.  One file (KERMUPL)
will contain the FTN5 source code for Kermit itself.  The other
file (AZLBUPL) contains the COMPASS I/O and low level support
routines supplied by the University of Arizona.  Many of these
routines are FORTRAN interface routines to the COMPASS system
macros.  These should run as is on NOS/BE systems and most should
run as is on NOS systems.  The routines that are needed from AZLIB
(the library produced from AZLBUPL) are: CPU.BTZ, CPU.MFS, CPU.VFN, CLOSE,
CPU.MVC, CPU.SCS, CPU.SXT, CPU.TXS,
OPEN, READ, WRITER, READC, READW, WRITEW, ENDRUN, RECALL, RTIME,
MOVECH, XSCS, XSXT, XTXS, XVFN, RETFILE, XCON,
EXCST, and MACREL.  These routines should be assembled and placed
in the file AZLIB and tested to make sure they work on your system.
The normal command sequence for this would be:
@begin<example>
.@i<UPDATE,P=AZLBUPL,F.>
.@i<COMPASS,I.>
.@i<LIBGEN,P=AZLIB.>
@end<example>

The next thing to do is start building Kermit.  There are several
things to do first, though.  Cyber Kermit uses conditional
compilation for the different operating systems and site dependent
routines.  Modify the parameter definitions in common deck COMCKER
to reflect your operating system and site.  Note that the site
definition is only usefull if you need to have site specific
routines or code.  Currently, the only site specific routines are used to
change the duplex from FULL to HALF and back again (ECHOPLX used at
UA, BELLC used at UT).  Site specific code is used at UT due to our
strange character sets, and for setting ASCII mode for I/O in
subroutine FOPEN.  The display code character set parameter must
also be modified in common deck COMCKER to reflect the appropriate
character set (63, 64) in use at your site.

NOS sites will probably have to modify subroutine RDELAY to
accomodate the different format returned by the RTIME macro.
If a NOS site would send it's mods back to the University of Texas,
then this could be conditionally compiled and other NOS sites would
no longer have to worry about this.

Once the duplex changing (not neccessary at half duplex sites, but
be sure to change the default duplex in subroutine BLOCK DATA to
HALFDUP) and the code for setting ASCII I/O has been set up
debugging can take place.  Decide on which version of Cyber Kermit
you wish to run (OVCAP or SEGLOAD).  Most sites are running the
OVCAP version and installing it in the system nucleus.  To build
the OVCAP version place the following lines in file UPDMODS:
@begin<example>
*IDENT,moddeck
*DEFINE,OVCAP
@end<example>
and run the commands:
@begin<example>
.@i<UPDATE,P=KERMUPL,F,I=UPDMODS.>
.@i<FTN5,I,OPT=2.>                      COMPILE KERMIT SOURCE
.@i<FTN5,I,OPT=2,B=LIBREL.>             COMPILE LIBRARY SOURCE
.@I<LIBGEN,P=KERMLIB.>                  BUILD KERMIT LIBRARY
.@I<LDSET,MAP=SBEX.>
.@I<LOAD,LGO.>                          LOAD KERMIT, KERMLIB AND AZLIB
.@I<NOGO,KERMIT.>
@end<example>

To build the segload version, place the following segload
directives into file KERMSEG:
@begin<example>
        TREE    KERMIT-(SET,HLPCMD,EXECMD,SERVER-(RECEIVE,SEND))
SET     INCLUDE SHOW,STATUS,MATCH,SETVAL
RECEIVE INCLUDE RINIT,RFIEL,RDATA
SEND    INCLUDE SINIT,SFILE,SDATA,SEOF,SBREAK
KERMIT  GLOBAL  PROTO,PACKET,DEBUG,MESSAGE,FILEIO,FILEIOC
        END     KERMIT
@end<example>
and run the commands:
@begin<example>
.@i<UPDATE,P=KERMUPL,F.>
.@i<FTN5,I,OPT=2.>                      COMPILE KERMIT SOURCE
.@i<LDSET,LIB=AZLIB>
.@I<LDSET,MAP=SBEX.>
.@I<SEGLOAD,I=KERMSEG,B=KERMIT.>        LOAD KERMIT, AZLIB
.@I<LOAD,LGO.>
.@I<NOGO.>
@end<example>

To aid in debugging of the OVCAP version, remove the line:
@begin<example>
          LDSET    OMIT=SYSERR.
@end<example>
from the COMPASS main program.  This was put there to remove
uneeded (hopefully) code and reduce field length.

Be sure to read the implementation notes in the program source.
These notes are likely to be the more upto date.

Planned further enhancements to Kermit-170 being done at the University
of Texas include:
@begin<example>

- Addition of new server functions: directory, type, delete, etc.
- Two and Three character checksums.
- 8th-bit quoting, to allow transfer of binary files with systems that
  can't use the parity bit for data.
- Repeat processing for data compression.
- Badly needed performance tuning.  Currently we have been experiencing
  700-900 baud effective data throughput on a 2400 baud line.
@end<example>