Columbia Kermit/kermit.zip/ibm370/ik0por.txt

Text File | 2020-01-01 | 43KB | 972 lines

IK0POR.HLP                                               1991 Sept

Notes on porting Kermit-370 to other operating systems.  This document
consists of three parts: a general specification of functionality, a
detailed guide to some of the more arcane sections of system-specific
code in Kermit-370, and a summary of all the modules within Kermit-CMS.

*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
A. Feasibility.

The following is a list of system-specific operations that must (or
should) be performed by Kermit-370.  Each item is labeled with its
degree of importance and with the name(s) of the macro and/or routine(s)
that perform the function.  The importance level is marked with ">>" and
the program components with "<<".  Names of macros are further marked
with asterisks; routines are usually coupled with function codes.  The
presence of both a macro and a routine indicates that the macro serves
only to invoke the routine.

       TERMINAL FUNCTIONS

 1. Read from the terminal with possible prompt.  Return length read.
    Leave text in specified buffer (unedited, if possible).  Should
    follow techniques of utility programs, if any, such that command
    procedures can issue Kermit subcommands (if possible).
    >> Essential.
    << * RTEXT

 2. Display text at the terminal.  Ok if system supplies a CRLF.
    >> Essential.
    << * WTEXT

 3. Test for stacked lines of terminal (or pseudo-terminal) input.
    >> Cosmetic.  Avoids extra prompts and synchronizes "banner" display
       at startup.
    << SUPFNC,7

 4. Set up a new prompt string, if necessary, for subsequent terminal
    read requests.
    >> Only if needed for #1.
    << SUPFNC,11

 5. Clear the screen (if possible).
    >> Cosmetic.
    << SCRNIO,0

       SYSTEM FUNCTIONS

 6. Analyze user environment at startup and determine if suitable.  Save
    any quantities needed and condition the line for entering commands.
    Determine, if possible, the terminal controller type insofar as that
    is necessary for establishing the method of file transfer.
    >> Essential.
    << SETMSG,1

 7. Reperform system-dependent initialization after SET LINE command
    selects a new communication line.
    >> Needed for SET LINE subcommand.
    << SETMSG,5 + SCRNIO,3

 8. Reverse any setup performed in #6 and clean up before returning to
    system.
    >> Essential.
    << SETMSG,4

 9. Obtain free storage block of specified length.  Return error code,
    if possible, when enough storage is not available.  Method should
    be re-entrant if possible and must preserve registers 2-13 without
    recourse to the save area pointed to by R13.
    >> Essential.
    << * DMSFREE

10. Release free storage block of specified address and length.
    >> Essential.
    << * DMSFRET

11. Invoke the system HELP facility with optional operand string.
    >> Cosmetic, but very useful.
    << KHELP

12. Start typeout interception.  If possible, this should include all
    possible terminal output regardless of source.  At a minimum, it
    must result in messages from Kermit itself being saved in a buffer
    instead of displayed.  The intercepted output may be stored wherever
    convenient.
    >> Needed for REMOTE operations in server mode.
    << SUPFNC,1

13. Stop interception and restore normal terminal functions.
    >> Needed for REMOTE operations in server mode.
    << SUPFNC,5

14. Retrieve intercepted messages and copy them, if necessary, to the
    Kermit disk buffer.
    >> Needed for REMOTE operations in server mode.
    << SUPFNC,2

15. Execute a host command (with or without interception).  Generally,
    the command text may be of two different forms: either a text
    string extracted from a text buffer or a canonical, internal
    representation requiring perhaps less system overhead.  Commands
    invoked by Kermit for purely internal purposes should be of the
    latter form.  If possible, detect whether the command is legal
    before invoking it.  Detect in any case whether the command is legal
    sooner or later.
    >> Cosmetic, but very useful.  If necessary, a minimal set of host
       commands can be emulated.
    << SUPFNC,3

16. Retrieve original command string by which Kermit was invoked.  This
    need not be done more than once (at startup).
    >> Needed for specifying a subcommand in original command line.
    << SUPFNC,6

17. Log off the current session.
    >> Needed for honoring BYE command.
    << SUPFNC,8

18. Wait for a specified time (in seconds).
    >> Needed for DELAY parameter and possibly for screen synchronizing.
    << SUPFNC,9

19. Return the current clock time (in centiseconds).  The code is fully
    generic, even though the function is done in SUPFNC.
    >> Needed for statistics and long-packet optimizing.
    << SUPFNC,10

       DISK/FILE-SYSTEM FUNCTIONS

20. Select a "working directory" specified by a string extracted from
    a text buffer.  The directory is, of course, a concept defined
    within the context of the operating system.  Subsequent files are
    preferentially read from and written to the directory.
    >> Needed if the directory concept is implemented: CWD subcommand.
    << CWDSET

21. Show space available in the "working directory" or other area.
    >> Needed for the SPACE subcommand.
    << DSPACE

22. Open a disk file by name for input (or return a non-zero code in
    case of failure).  If necessary, refer to default file attributes
    specified to Kermit to aid in locating the file.  Return a data area
    filled with the file attributes and a pointer to a storage block
    reserved for controlling the I/O (a "ticket").  OPENF is a generic
    macro.
    >> Essential.
    << * OPENF I + DISKIO,1

23. Open a disk file by name for output (or return a non-zero code in
    case of failure).  If the file already exists, prepare to either
    overwrite it or append to it as the occasion requires.  If the file
    is to be extended, be sure its attributes are not altered.  Return
    a data area and "ticket" as with opening for input.
    >> Essential.
    << * OPENF O + DISKIO,2

24. Test for the existence of a file by name.  Return a data area with
    the file attributes if found.
    >> Essential.
    << * OPENF T + DISKIO,3

25. Close the file specified by a "ticket".  The ticket should then be
    "blank", so that reclosing would have no ill effects.  CLOSF is
    generic.
    >> Essential.
    << * CLOSF + DISKIO,4

26. Write a record out to a disk file specified by a "ticket".  The data
    address and length must be subject to change with each invocation,
    but must be retained if not explicitly changed.  A completion code
    of 13 must be returned if the write encounters a full disk.  Any
    other I/O error must return some other non-zero code.
    >> Essential.
    << * WRITF + DISKIO,10

27. Read a record in from a disk file specified by a "ticket".  The
    buffer address and length must be subject to change with each
    invocation, but must be retained if not explicitly changed.  If line
    numbers are kept in predictable locations within each record, there
    must be an option to remove them before returning the length of data
    read.  If the end of the file is reached, a completion code of 12
    must be returned.  An error must return some other non-zero code.
    >> Essential.
    << * READF + DISKIO,9 or DISKIO,0

28. Update the disk directory for given file (specified by a "ticket")
    such that the file is still open for output.
    >> Needed for SET DEBUG SAVE subcommand.
    << * SAVEF + DISKIO,21

29. Set up disk directory search for files matching a given pattern
    name.  This may entail as little as saving the pattern or as much
    as creating a file with the complete list of matches.  Note: the
    former is dangerous in a multi-user system if the name space to be
    searched can be altered while Kermit is searching, especially if
    control blocks can be unchained.  The latter approach also has a
    drawback, in that files can still be created or deleted after the
    "complete" list is made.  NXTFSET is a generic macro.
    >> Needed for wildcard filespecs.
    << * NXTFSET + DISKIO,5

30. Fetch the next filespec from a directory search and get a pointer to
    a list of its file attributes.  Must return a non-zero code if no
    more files (and must persist even if called repeatedly).  NXTF is
    a generic macro.
    >> Needed for wildcard filespecs.
    << * NXTF + DISKIO,6

31. Clean up after a disk directory search.
    >> Needed for wildcard filespecs.
    << * NXTFSET END + DISKIO,7

32. Check candidate name of a directory for validity and accessibility.
    >> Needed for CWD subcommand.
    << * NXTFSET CWD + DISKIO,8

33. Test current directory (or environment) for sufficient disk space.
    >> Cosmetic, used for processing A-packets.
    << DISKIO,11

34. Analyze disk I/O error; set up error message and code.  ERRF is a
    generic macro.
    >> Cosmetic, but useful.
    << * ERRF + DISKIO,12

35. Display directory information about specified file (possibly with
    wildcard notation).
    >> Needed for DIR subcommand.  Cosmetic, but very useful.
    << DISKIO,13

36. Delete a specified file.  ERASF is a generic macro.
    >> Cosmetic, but useful, especially for REMOTE server functions.
    << * ERASF + DISKIO,14

37. Rename a specified file.
    >> Cosmetic, but useful, especially for REMOTE server functions.
    << DISKIO,15

38. Copy a specified file.
    >> Cosmetic, but useful, especially for REMOTE server functions.
    << DISKIO,16

39. Parse input string for a filespec under a variety of circumstances.
    The name must be converted to a uniform internal format suitable for
    Kermit I/O routines.
      a) Native file for input (possible wild-card notation).
      b) Native file for output.
      c) Foreign filespec.
      d) TAKE file (input or output).
      e) Native file for utility operations.
    >> Essential.
    << FSPEC (q.v.)

40. Check a given filespec for uniqueness and either generate a unique
    new name if possible or return an error indication if necessary.
    Possibly query the user for permission to overwrite a file that
    already exists, provided the filespec was entered by hand.
    >> Essential.
    << FSPEC (q.v.)

41. Convert an internal filespec to the form for transmission.
    >> Essential.
    << FSPEC (q.v.)

42. Convert an internal filespec to the display form.
    >> Needed for STATUS display and transaction log.
    << FSPEC (q.v.)

43. Open a library *per se* for purposes other than transferring its
    members.  OPENF is a generic macro.
    >> Useful if the concept of libraries is important.
    << * OPENF L + DISKIO,22

44. Skip over the first "n" records of a newly-opened input file.
    POINTF is a generic macro.
    >> Useful for SEND with line range.
    << * POINTF + DISKIO,23

       COMMUNICATION FUNCTIONS

45. Open a specified communication line for I/O (default to the terminal
    connection).  Set parameters needed for transparent operation.  The
    procedure may depend on the type of terminal (or line) controller
    and should include both linemode and fullscreen types.  After the
    line is open, if it is the terminal, no display messages will be
    issued by Kermit, and messages from other sources should also be
    suppressed, if possible.  These opening functions are to be divided
    into controller-specific (of which there may be different variants)
    and general.
    >> Essential.
    << TERMIO/SCRNIO,1 + SETMSG,2

46. Close the current communication line.  Restore normal operation.
    The same division of functions obtains as in #45.
    >> Essential.
    << TERMIO/SCRNIO,2 + SETMSG,3

47. Write a packet to the communication line.  If possible, control the
    entire contents, including terminators.  Also, if possible and if
    Kermit will immediately be requesting a read, begin the following
    read operation so that there is no delay between the completion of
    the write and the readiness of the system to read -- this may be
    important in a heavily loaded time-sharing environment.
    >> Essential.
    << TERMIO/SCRNIO,4

48. Read a packet from the communication line.  If possible, suppress
    any prompts the system might normally supply.  If possible, arrange
    for a timer interrupt after a specified wait such that the I/O
    request can be cancelled.
    >> Essential.
    << TERMIO/SCRNIO,5

49. For fullscreen lines, write a message to the screen despite the line
    having been opened.
    >> Cosmetic, but useful.
    << SCRNIO,6

*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
B. Hints.

In general, the operation of porting Kermit-370 entails starting from
one or more existing versions of the system-specific code (IKxMAC.ASM
and IKxUTL.ASM) and replacing one set of system-specific code with
another.  Each subroutine has comments documenting the interface with
the rest of the program, and a fair amount of the code itself deals with
such bookkeeping details and can be carried over.  Similarly, each macro
begins with a brief function/syntax description.  In one example
(porting Kermit-370 to the MUSIC O.S.), about 2/3 of the final macro
definition code had been carried across from CMS as well as about 2/5 of
the final MUSIC-specific subroutine code.  In all, only about 850 lines
of non-comment code had to be written.  In another example (porting to
CICS), only about 1/2 of the macro definition code had been carried
across, along with about 1/4 of the subroutine code.

In some cases, particularly when the operating system is supplied in
source form, it may be useful to examine the system code and macro
definitions for helpful hints on the techniques of invoking system
functions, manipulating filespecs, and the like.  Care should be taken,
of course, not to violate copyright restrictions.

------------------------------------------------------------------------
Parameters.

It is necessary to define the symbols in the SSYMS macro.  A useful
technique is to compare two existing variants to determine which
symbols are always present.  Items in the KSYSTF macro are also system-
specific, and many of them are required in all variants; some are not
required, but are generally useful (again, compare existing variants
for tips).

------------------------------------------------------------------------
Entry and exit conditions.

Kermit at entry should have R13 -> 72-byte save area and R15 -> Kermit,
and there must be a macro SAVE similar to that of MVS.  If there is no
system macro SAVE, Kermit must supply one itself.  If necessary, that
macro can distinguish between internal linkages (in which R13, R14, and
R15 *must* follow type-I conventions) and the initial call from the
system (which may be anything at all).  The entry conditions for Kermit
consist of two macro calls:
         SAVE  (14,12),,&LABEL
         KMAIN ENTER
plus code appropriate to internal linkages.  &LABEL will be either GUPI
or KERMIT.  For internal linkages, that parameter is always "*".  After
the invocation of KMAIN, R13 must point to the original save area, of
which the first 12 bytes must be unused, and if the values originally in
R0 and R1 were important, they must be saved in bytes 20-27.  KMAIN
ENTER must assign free storage and zero-fill it; point register KWRKBASE
at the storage, register KSUBBASE at Kermit, and R10 at COMMON; and set
up pointers to the stack.  KMAIN RETURN must release the storage,
restore any registers necessary, and return to the system with the
proper condition code (initially in R15).

------------------------------------------------------------------------
FSPEC.  Notes from source code:

* Entry: R1->name field, R0=flags selecting operation (see below)
*        For parse operations, SCANPTR defines the input string.
*        For getting foreign or display filespec, R7->output buffer
* Exit: if not FFNEW, then R15=0 if ok, 1 if ?, 2 if bad.
*        For R15=1 or 2 R3,R4 give message.  ERRNUM may be leftover.
*
*                                 Flags:                  Notes:
*   Tasks:               FFRCF FFSND FFGET FFNEW
* Parse RECV               X                     set ROVR properly
* Parse SEND 1st                 X
* Parse SEND 2nd           X     X
* Parse GET 1st                        X
* Parse GET 2nd            X           X         set ROVR properly
* Parse F-packet   (FFHDR) X     X     X
* Parse for Generic(FFUTL)       X     X         FFWLD: allow partial
* Parse TAKE
*
* Get unique name                            X     R15: 0=>ok, 1=>bad
* Interactive name check               X     X     R15: 0=>ok, 1=>bad
* Get foreign name (FFENC) X                 X     R15->end of string
* Get display form (FFDSP)       X           X     R15->end of string

Further explanation of entry conditions -
"name field" is a fixed-length string of length LFID to be filled with
the internal representation of a file name.  SCANPTR is a pair of
pointers (LEN, ADR) of a character string to be parsed, typically a
string typed by the user, possibly in lower case.  Note: Kermit assumes
that a file specification will fit into a string of no more than 256
bytes, i.e., LFID must be <257.

FSPEC parses out one filename at a time.  There is, of course, the
alternate command syntax for SEND that allows the user to specify a list
of files.  The only contribution of FSPEC to the parsing is to note the
delimiter it finds after the name; the list control is managed by the
generic code.

SEND takes one or two parameters, namely, the native filename and,
optionally, a different filename to send to the other Kermit.  A
reversed pair of parameters is taken for the GET subcommand: a required
"foreign" filename and an optional overriding "native" one.  Foreign
filenames, since they depend on the system of the other Kermit, might be
thought of as independent of the IBM/370 operating system, but
Kermit-CMS offers a special syntax extension that isn't implemented in
Kermit-TSO.  Anyway, that is the meaning of SEND 1st, etc.  The foreign
filename, by the way, is stored in JFSPEC, which is a varying-length
string in COMMON (one-byte length indicator, followed by a maximum of 47
bytes).  "Parse RECV", in case that's not clear, means grab the
filename, if any, entered on the RECEIVE subcommand, and (as the Note
says), set flag ROVR in FL1, if a filename is actually found.  I also
note that the code clears flag NMOK in FL4 (in the CMS version), but
that happens to be part of the internal logic of FSPEC to avoid
duplicate efforts in filename collision testing.  "Parse F-packet" means
grab a (valid) filename from the file header sent from the other Kermit.
"Parse for Generic" means grab a filename from the text string sent by
the other Kermit for one of the Generic Server mode commands.  The
corresponding Note says that FFWLD set in the input flags means that
part or all of the filename can be omitted to indicate all matching
files, as in the DIRECTORY command.  "Parse TAKE" means grab a file name
from the text of a TAKE subcommand.

The difference between "Get unique name" and "Interactive name check" is
that the latter is permitted to type out a message and query the user
for further instructions if necessary (as might be the case when the
user types RECEIVE DUP.FILE), while the former must either find a unique
name, or return an error condition.  "Get foreign name" means putting
the foreign filespec into a buffer (in ASCII) with JFSPEC taking
precedence over whatever is found at (R1).  Finally, "Get display form"
is just the reverse of the various parse operations: the internal
representation is converted to conventional external representation
(with excess blanks, if any, removed according to whatever convention
holds).

------------------------------------------------------------------------
FDB.  File Descriptor Block + File Access Block:

In IKxMAC.ASM, the FDBD macro has two parts, an FAB and FDB.  The FAB is
intended to map the operating system's macro, whereas the FDB is
Kermit's local variables.  Some of the variables in the FDB are used
throughout the generic Kermit code.  The common part begins at FDBD and
includes everything mapped by FDBPAT macro, and also includes FABLRTR,
which is a recent addition giving the maximum record length for output
to a file (which may in CMS, for example, differ from the current
largest record length).

------------------------------------------------------------------------
Host command execution.

Not all operating systems make it possible for one application program
(such as Kermit) to invoke another.  When that is not possible, Kermit
should make an effort to emulate the basic file-management commands
corresponding to DISKIO functions 13-16 plus the appropriate commands
(even if the system doesn't have them) to invoke on-line help and to
display a file at the terminal.  For an example of how such emulation
can be done, see function 3 of SUPFNC in the MUSIC version of Kermit.
Some calls to SUPFNC are generated internally by Kermit-370 itself
(these are identified by *not* having flag UCMD set in FL4).  Such calls
should not require any syntax checking and may, in fact, be already
converted to a special "system" format, if any, suitable for passing
directly to the command processor.  The details of formatting and syntax
check will, of course, be highly system-specific.

------------------------------------------------------------------------
SCRNIO.  Fullscreen packet I/O.  See part C for calling sequence info.

For the Series/1 interface (and whenever else possible), Kermit-370
takes advantage of a Read chained to a Write to speed up the I/O.
Actually, the operation is chained by the Series/1, so Kermit issues
both a write and a read synchronized by a hardware interrupt from the
Series/1.

Fullscreen buffer limits are defined by symbols MAXWS and MAXRS set in
macro SSYMS.

In principle, all you need to know is the sequence of calls to SCRNIO.
You can handle the system interface in any convenient manner.  The
sequence is (by R0 code): 1, 6 (with greetings message), 4, 5, 4, 5, ...
4, 5, 2.  The value of WRRD determines whether a "4" means Write/Read
(value is 5) or just Write (value is 0) -- that value will always be 5
except possibly the last time.  Even if WRRD is 0 on the last call with
R0=4, there will still be a call with R0=5 just afterwards, followed by
a call to release control of the screen.

The difference between "4" and "6" is just that no read is required
following a "6".  Also, "6" is intended for displaying messages to the
user, in case he's watching, but "4" is for sending to the micro Kermit.

------------------------------------------------------------------------
TERMIO.  Similar to SCRNIO in many respects.

TTY buffer limits are defined by symbols MAXWT and MAXRT set in the
macro SSYMS.

The way to signal a timeout from TERMIO is to return a packet of exactly
one character: an ASCII 'T'.  You can see an example by looking at the
TSO version.

There is a potential problem for Kermit transfers that arises if the
user has a printable character for any editing functions used in the
interpretation by the system of terminal input.  Examples of such
functions include character-delete and line-end (both normally found
only on line-mode terminals).  If such a character appears in a packet
sent to the 370, the packet will be mangled unless Kermit takes special
precautions.  CMS Kermit deals with the problem by noting the LINEDIT
setting when it starts up, turning off LINEDIT during a protocol
transfer, and restoring LINEDIT afterwards.  TSO Kermit, on the other
hand, simply suppresses the user's line and character deletes during a
transfer (and simultaneously saves the current values) and then restores
them afterwards.  The functions of saving, changing, and restoring the
edit characters would be performed under variants 1, 2, and 3,
respectively, of SETMSG.

------------------------------------------------------------------------
Type-out interception.

Intercepting host command output depends on the operating system
facilities.  In any case, the info would go directly to the screen
unless you first call SUPFNC,1 to start typeout interception.  For
example, under CMS that means intercepting all SVC's (and BALR's to the
system typeout entry point) and copying the corresponding info into a
buffer as it's generated (leaving x'15' separators).  That sort of
operation is self-pacing, so that the cleanup consists of nothing more
than copying the end-of-buffer pointer into a global variable.  Under
TSO, the setup call creates a STACK entry such that the TSO-type
utilities will write to a pre-allocated dataset.  Cleanup in that case
consists of closing the file and then reading the file into the buffer,
again with X'15' (Newline) characters separating lines, and finally
copying out the end-of-buffer pointer.

If there's no general way to save the output of a class of utility
programs, then you would just have to do what you can: put any
preliminaries in SUPFNC,1 and the nitty-gritty (for, say, DIR) in
DISKIO,13 with the buffer-read-back in SUPFNC,2/SUPFNC,5.  You might
want to get a copy of TSO Kermit to see how it does things.

The expansion for WTEXT in the TSO version generates a call to a
subroutine in COMMON which checks the interception flags and then either
issues a TPUT or copies the info into the output buffer.

------------------------------------------------------------------------
GUPI.

Updates for Kermit-370 are in the same format as in CMS, except that the
multi-level updates are applied from a single, concatenated file, rather
than a flock of separate updates listed by an AUX.  You should take a
look at implementing the generic update program GUPI for your operating
system.

Bear in mind that there are almost always some updates to the base
generic source, so the "package" for installation must include a means
of applying those, and it would also be nice if subsequent changes,
particularly generic changes, could be transmitted to all systems in the
same form.  In any case, instructions for applying updates should be
included in the IKxKER.BWR file (see IKCKER.BWR for a pattern).  It is
pretty easy to make a GUPI, once you've got Kermit: just take subroutine
DISKIO (functions 1, 2, 3, 4, 9, and 10) plus any associated data
structures and tack on a command interface.  GUPI uses the same macros
as Kermit.  You can see a working example by getting IKTGUP.ASM +
IK0GUP.ASM from Columbia.  The only complication is that you'll need to
make a macro library consisting of the macros in IK0MAC.ASM, IKxMAC.ASM,
and IKxGUP.ASM.  The awkward (but workable) alternative would be to
convert all the COPY blocks in GUPI into macros as the MUSIC version
does.  Making a macro libary is simplified by the structure of the code:

 a) All the pieces have *COPY cards imbedded appropriately (the source
    components have each macro preceded by a card of the form
    *COPY                                              macro-name
    to improve legibility).

 b) The builder may concatenate all the pieces in any order, both for
    Kermit itself and GUPI, then change the *COPY cards into the
    appropriate member-separators, and finally run the result through a
    PDS (library) generator.

 c) The "real" source for Kermit or GUPI can then be a small skeleton
    which consists of comments and COPY instructions (which refer to
    members of the macro+source library).

------------------------------------------------------------------------
Reentrancy.

Kermit-370 is fully re-entrant in the generic sections, and provides a
simple means for any system-specific code to be re-entrant as well.  The
ENTER, LOCALS, and EXIT macros can (and should) be used to begin a new
routine, end the static code, and end the routine, respectively.
Storage locations defined between the LOCALS and EXIT macros are
allocated as temporary variables and initialized to zeroes for each
invocation of the subroutine (and may be allocated recursively, if
necessary).  Sufficient stack space must be reserved for Kermit by
setting the symbol STKDWDS in the SSYMS macro.  The requirement is 18
doublewords per subroutine call plus the sum of all temporaries (rounded
up to doublewords) for the subroutines in the longest path.  There is
automatic overflow checking at each subroutine call performed by COMMON
code routine named SUBENT.  The result of overflow is an immediate
return with an error code from the subroutine, but that may still lead
to unpredictable consequences, and STKDWDS should be given generous
proportions.  When TEST is set on in Kermit-370, the STATUS subcommand
displays the maximum extent of stack space used (in doublewords).

------------------------------------------------------------------------
Miscellaneous notes.

1. Does your O.S. have a LINEND character facility like VM?  If not, it
   might pay to copy the implementation of that from TSO Kermit.  This
   will, of course, mean some changes to IKxMAC.
2. Would TAKE files generated by Kermit users tend to have line
   numbers imbedded?  If so, it would pay to copy/adapt the stripping
   facility of TSO or CMS Kermit.
3. Does your O.S. have a way of timing out on a line-mode terminal read?
   The way to signal a timeout from TERMIO is to return a packet of
   exactly one character: an ASCII 'T'.  You can see an example by
   looking at the TSO variant.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
C. Module summary

This summary was produced for Kermit-CMS 4.2.2.  The system-specific
modules vary (of course), but all should be quite similar to the
CMS variant.  Some of the differences lie in whether a particular
entry point is treated as a separate routine or not.

          ALPHABETIC LIST OF SUBROUTINES
Each item begins with a one-line description, possibly followed by more
details, including entry and exit conditions and function.  If any
alternate entry points exist, each one is similarly described.  Finally,
all common references, callers, and calls are lists -- these are joint
lists in the cases of routines with alternate entries.

ACCTNG: save statistics for a transfer in the transaction log
     ENTRY ACCTST
 * add a new entry (name only) to the transaction log
     CALLERS- RECEIV  SEND

COMMON: Kermit-370 common routines/data areas
       CALLS- CWDSET  DECODE  DISKIO  DUMP    ENCODE  FSPEC   INTINI
              RIO     RPACK   RPAR    SET     SPACK   SPAR    STATUS
              SUPFNC

CRCCLC: calculates crc
 * Calculate the CRC and return it in R15.  Expects R5 to point to the
 * start of the data on which the CRC is calculated, and R6 to the
 * char after the last one.
     CALLERS- RPACK   SPACK

CWDSET (system-specific): set working directory
 * Set new 'working directory', i.e., filemode letter
 * Entry: SCANPTR string has option
 * Exit: R15=0 if ok, R15=1 if error or help needed. ERRNUM unchanged.
     ENTRY DSPACE
 * Show space in 'working directory' or other minidisk
 * Entry: SCANPTR string has option (none => working directory)
 * Exit: R15=0 if ok, R15=1 if error or help needed. ERRNUM unchanged
     COMMONS- COMMON
     CALLERS- COMMON  SERVER  SET
       CALLS- DISKIO

DECODE: decode pkts from RDATA to WBUF
 * Exit: ERRNUM left unchanged unless there is an error.
     CALLERS- COMMON  GENCMD  RECEIV
       CALLS- OUTBUF

DISKIO (system-specific): performs disk I/O functions
 * ERRNUM unchanged unless there is a disk error.
 * Function selected on entry by R0:
 * 0=> unnum: R1->FAB.  Return R1->buffer,R0=# and remove the sequence
 *     number (if any) from the buffer (used for TAKE files)
 * 1=> open (in): R1->pattern FDB, R2->name.  Returns R0->FAB, R1->FDB
 * 2=> open (out): (same)
 * 3=> test name: R2->name.  Returns R1->FDB if found (else R15=1)
 * 4=> close file: R1->adr(FAB).
 * 5=> set up search: R1->pattern name.
 * 6=> return next file in list:  Returns R1->FDB + sets up FILNAM
 * 7=> close search (if any).
 * 8=> test CWD string: R1->string.  Returns R15=0 if ok, else =1.
 * 9=> read: R1->FAB.  Returns R15=12 if EOF, 0 if ok; R0=# data
 * 10=> write: R1->FAB.  Returns R15=13 if disk full, 0 if ok.
 * 11=> test space: R1->pattern FDB (has size in Kbytes),
 *   R2->name (used if FAB not found), R6->adr(FAB). Return R15=0 if ok.
 * 12=> analyze R/W error, set ERRNUM, make EMSG: R1->FAB, TMPDW=code
 *      always returns R15=1
 * 13=> directory info on file: R1->name.  Returns R15=0 if ok.
 * 14=> delete file: R1->name.  Returns R15=0 if ok.
 * 15=> rename file: R1->name, R2->new name.  Returns R15=0 if ok.
 * 16=> copy file: R1->name, R2->new name.  Returns R15=0 if ok.
 * 21=> save file status in directory: R1->FAB. (not used)
 * 22=> open library (in): R2->DDNAME.  Return R15=0 if ok.
 * 23=> point for next read, R1->adr(FDB), R2=records to skip.
 *      Return R15=0 if ok.
     CALLERS- COMMON  CWDSET  DUMP    FSPEC   GENCMD  INBUF   KERMIT
              OUTBUF  RECEIV  RIO     SEND    SERVER  SET     USNTRF
       CALLS- SUPFNC

DUMP: show translation table or transaction log
 * Display current contents of table or log
 * Entry: SCANPTR string has option
 * Exit: R15=0 if ok, R15=1 if error or help needed. ERRNUM unchanged.
     ENTRY DUMPTOD
 * Extra entry point for dumping TOD (in sec) from R0 into buf
 * at R1 and return updated buffer ptr in R15
     ENTRY GIVTAB
 * Save current translation table in STORAG into a TAKE file on disk
 * Entry: SCANPTR string has option
 * Exit: R15=0 if ok, R15=1 if error or help needed.  ERRNUM set
 *       appropriately as long as command syntax is ok, else unchanged.
     COMMONS- ERRTAB
     CALLERS- COMMON  SCRNIO
       CALLS- DISKIO  FSPEC   STATUS  TBLSET

ENCODE: encode from RBUF into SDATA buffer
     CALLERS- COMMON  SEND
       CALLS- INBUF

ERPACK: send error packet based on ERRNUM
     COMMONS- ERRTAB
     CALLERS- GENCMD  RECEIV  SEND    SERVER
       CALLS- SPACK   STATUS

FOPSTR: test string for file options
 * Entry: R1->Address of option field, R6->string, R7=length - 1
 * Exit: R15=0 + R6,R7 fixed if ok, R15=1 if error (msg ptrs set up)
     CALLERS- FSPEC

FSPEC (system-specific): extract filespec from scan string
 * Entry: R1->name field, R0=flags selecting operation (see below)
 *        For parse operations, SCANPTR defines the input string.
 *        For getting foreign or display filespec, R7->output buffer
 * Exit: if not FFNEW, then R15=0 if ok, 1 if ?, 2 if bad.
 *        For R15=1 or 2 R3,R4 give message.  ERRNUM may be leftover.
 * See part B for calling flags.
     CALLERS- COMMON  DUMP    GENCMD  RECEIV  SERVER  SET     USNTRF
       CALLS- DISKIO  FOPSTR

GENCMD: send a Generic command
 * Entry: SCANPTR has string
 * Exit: R15=0 if ok, 1 if help needed, 2 if bad parameter
 *       ERRNUM set appropriately
     CALLERS- USNTRF
       CALLS- DECODE  DISKIO  ERPACK  FSPEC   INTINI  OUTBUF  RECEIV
              SEND

INBUF: read next disk record into RBUF
 * Exit: R15=0 if ok, -1 if EOF, 1 if read error (ERRNUM set)
     CALLERS- ENCODE  NPREAD
       CALLS- DISKIO

INTINI: Initialize/reset terminal for protocol
 * If R1 is 0, reset for interactive unless in Server mode.
 * If R1 is positive, set up for protocol:
 *  1 for SERVER, 2 for SEND, 3 for RECEIVE, 4 for short msg
 * R15 = 0 on return if ok
     CALLERS- COMMON  GENCMD  SEND    SERVER  USNTRF
       CALLS- SCRNIO  SUPFNC  TERMIO

KERMIT: main entry point
 * Assign buffers, initialize STORAG section; do Kermit; return.
     COMMONS- COMMON  KSYSNIT
       CALLS- DISKIO  SCRNIO  SPAR    TBLSET  USNTRF

KHDMP: dump storage to log file (not generated unless &KTRACE is YES)
 * Dump area to log
 * Entry: R1->area, R0=length, R2-> 8-byte title for area
 * Exit: R15=0 if ok

KHELP (system-specific): perform HELP command
 * Handle HELP command, rest of string given by SCANPTR.
     COMMONS- SETCMDS
     CALLERS- USNTRF
       CALLS- SUPFNC

NPREAD: copy from RBUF to SDATA buffer (no encoding)
     CALLERS- SEND
       CALLS- INBUF

OPTPKT: compute optimum packet size
 * Entry: TINSV contains stack of data
 * Exit: R15=0 if no limit, else optimum packet size (per algorithm)
     CALLERS- SEND    STATUS

OUTBUF: write record from WBUF to a disk file
 * Entry: R1=length of buffer (which starts where WBUF points)
 * Exit: R15=0 if ok, other if error (ERRNUM set)
     CALLERS- DECODE  GENCMD  RECEIV
       CALLS- DISKIO

RECEIV: receives a file
 * Receive file(s) and set ERRNUM appropriately
 * Entry: filespec in FILNAM if ROVR is set, latest received packet
          in buffer
     COMMONS- COMMON
     CALLERS- GENCMD  SERVER  USNTRF
       CALLS- ACCTNG  DECODE  DISKIO  ERPACK  FSPEC   OUTBUF  RPACK
              RPAR    SPAR    SUPFNC  TBLSET

RIO: Read packet into receive packet buffer
     ENTRY SIO
 * Send packet in SNDPKT
     CALLERS- COMMON  RPACK   SEND    SPACK
       CALLS- DISKIO  SCRNIO  TERMIO

RPACK: Read and validate a packet
 * ERRNUM set if error found, unchanged otherwise
     CALLERS- COMMON  RECEIV
       CALLS- CRCCLC  RIO

RPAR: sets up parms to send to other host
     ENTRY RPARSET
 * set up for exchange (RPAR to be called 1st)
     CALLERS- COMMON  RECEIV  SEND    SERVER
       CALLS- SCRNIO  TERMIO

SCRNIO (system-specific): Handle screen I/O via protocol converter
 * R1 points to a pair of (adr,len) for read or write.  If I/O is
 * successfull, R15 returns transferred byte count (else returns -1).
 *               Command code is in R0:
 * 0 => Clear screen on console (not comm line)
 * 1 => Open screen for I/O            4 => Write packet
 * 2 => Close screen                   5 => Read packet
 * 3 => Reset screen status after      6 => Write message (no ATTN)
 *      environment changes            7 => Read screen buffer
     ENTRY SETMSG
 * Entry: R1 selects operation
 * Exit: R15=0 if ok
 * 1-> Analyze user environment, determine if suitable.
 *     Save quantities needed and condition line for entering commands.
 *     Perform any system-dependent initialization.
 * 2-> Condition line for protocol transfers.
 * 3-> Decondition line at end of transfer.
 * 4-> System-dependent clean-up at exit.
 * 5-> Reperform system-dependent initialization after SET LINE.
     COMMONS- KSYSNIT
     CALLERS- INTINI  KERMIT  RIO     RPAR    SET     SUPFNC
       CALLS- DUMP    USNTRF

SEND: sends a file
 * Send file(s) and set ERRNUM appropriately
 * Entry: filespec pattern in IFILE, Disp code (if any) in R1
     CALLERS- GENCMD  SERVER  USNTRF
       CALLS- ACCTNG  DISKIO  ENCODE  ERPACK  INTINI  NPREAD  OPTPKT
              RIO     RPAR    SPAR    SUPFNC

SERVER: performs Server mode functions
 * Exit: ERRNUM set appropriately.
     CALLERS- USNTRF
       CALLS- CWDSET  DISKIO  ERPACK  FSPEC   INTINI  RECEIV  RPAR
              SEND    SPAR    SUPFNC  USNTRF

SET: perform SET command options
 * Set/change values in STORAG.
 * Entry: SCANPTR string has option
 * Exit: R15=0 if ok, 1 if help needed, 2 if bad parameter name
 *       ERRNUM unchanged
     ENTRY SHOW
 * Display current values in STORAG.
 * Entry: SCANPTR string has option
 * Exit: R15=0 if ok, 1 if help needed, 2 if bad parameter name
 *       ERRNUM unchanged
     COMMONS- SETCMDS ETCETERA
     CALLERS- COMMON
       CALLS- CWDSET  DISKIO  FSPEC   SCRNIO  SETCMDS SUPFNC  TBLSET

SPACK: fill sending packet buffer and send it
     CALLERS- COMMON  ERPACK  USNTRF
       CALLS- CRCCLC  RIO

SPAR: use parms from other host in RDATA
     ENTRY SPARSET
 * set up for exchange (SPAR to be called 1st)
     CALLERS- COMMON  KERMIT  RECEIV  SEND    SERVER

STATUS: display latest error (if any), transfer statistics, etc.
 * Exit: R15=0.  ERRNUM unchanged.
     ENTRY PEMSG
 * Display just error message and its backup explanations.
     COMMONS- ERRTAB
     CALLERS- COMMON  DUMP    ERPACK  USNTRF
       CALLS- OPTPKT

SUPFNC (system-specific): various supervisor functions
 *  On entry, R1 = operation code, R0 = possible ptr
 * Exit: R15 set (0 => ok, <0 => illegal cmd, >0 => depends)
 *       ERRNUM set appropriately (R1=1,3,4) or unchanged (2,5-11)
 * 1 -> Start typeout interception.  N.B.  &MAXLR >> 2048 for this
 * 2 -> Clean up afterwards and stop interception
 * 3 -> Execute host command with or without interception
 *      If UCMD set, SCANPTR gives text, else R0->text,R6=len
 * 4 -> Execute CP command with or without interception
 *      R0->text, R6=len
 * 5 -> Stop interception if going
 * 6 -> Retrieve original cmd parm string into CBUF (R15=1 if null)
 * 7 -> Test for stacked lines, return number in R15
 * 8 -> Log off (doesn't return!)
 * 9 -> Wait specified time
 * 10-> Return clock time in R15 (centisec)
 * 11-> Setup up new prompt string at (R0)
     CALLERS- COMMON  DISKIO  INTINI  KHELP   RECEIV  SEND    SERVER
              SET     USNTRF
       CALLS- SCRNIO

TBLSET: set up character set
 * Define new translation tables
 * Entry: Names of table in TRNALF and FILALF, R1->tables
 *        R0->item just changed, if any (else, 0)
 *        Tables should be a pair with ATOE first
 * Exit: R15=0 if ok, R15=1 if error ERRNUM unchanged.
     ENTRY TBLATT
 * Entry: R6->Designator string, R7=length
 * Exit:  Correct table set up and R15=0 if ok, else 1
     COMMONS- COMMON  TRNTBLD
     CALLERS- DUMP    KERMIT  RECEIV  SET

TERMIO (system-specific): Handle terminal I/O
 * R1 points to a pair of (adr,len) for read or write.  If I/O is
 * successfull, R15 returns transferred byte count (else returns -1).
 *               Command code is in R0:
 * 1 => Open line for I/O            4 => Write packet
 * 2 => Close line                   5 => Read packet
 * 3 => Reset line status after    ( 6 => Write message ) not used
 *      environment changes        ( 7 => Read buffer ) not used
     COMMONS- COMMON
     CALLERS- INTINI  RIO     RPAR

USNTRF: execute main loop
 * Execute Kermit commands (beginning with default TAKE files)
 * Entry: environment already set up
 * Exit: R15=0, ERRNUM set appropriately
     COMMONS- COMMON
     CALLERS- KERMIT  KHELP   SCRNIO  SERVER
       CALLS- DISKIO  FSPEC   GENCMD  INTINI  KHELP   RECEIV  SEND
              SERVER  SPACK   STATUS  SUPFNC

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

          ALPHABETIC LIST OF COMMON BLOCKS

COMMON: Kermit-370 common data areas
     USED BY- CWDSET  KERMIT  KSYSNIT RECEIV  TBLSET  TERMIO  USNTRF

ERRMSGS: text of error messages
     USED BY- ERRTAB

ERRTAB: List of error messages
     COMMONS- ERRMSGS
     USED BY- DUMP    ERPACK  STATUS

ETCETERA: overflow from COMMON
     USED BY- SET

KSYSNIT: initial parameter values
     USED BY- KERMIT  SCRNIO

SETCMDS: tables of command keywords
     USED BY- KHELP   SET

TRNTBLD: translation tables and variations thereon
     USED BY- TBLSET