Columbia Kermit/kermit.zip/ibm370/ikxker.mss

Text File | 2020-01-01 | 40KB | 921 lines

@Part(CICSKERMIT,root="kuser")
@string(-cicsversion="4.3.0")
@string(-cicsdate="93/9/30")
@Chapter<IBM CICS KERMIT>
@Index(CICS)
@Begin<Description,Leftmargin +15,Indent -15,spread 0>
@i(Program:)@\John Chandler (Harvard/Smithsonian Center for
Astrophysics); contributions from
Va@ccd()e Kundak@ccd()i and
Daphne Tzoar (Columbia U),
Brian Lesser (U. New Brunswick), Carrie Ledford (Miami U.), Jeff
Huestis (Washington U.),
Wayne Mery (Lehigh U.), ICSTI, Pierre Goyette (McGill U.),
Clark Frazier (Harvard
Bus. Sch.), Bob Bolch (Triangle), Andr@eac() Pirard (U. Li@egr()ge)

@i(Language:)@\IBM/370 Assembler

@i(Documentation:)@\John Chandler (CfA)

@i(Version:)@\@value(-cicsversion) (@value<-cicsdate>)

@i(Date: )@\1993 September
@end<Description>

@subheading<Kermit-CICS Capabilities At A Glance:>
@begin<format,leftmargin +2,above 1,below 1>
@tabclear()@tabset(3.2inches,3.7inches)
Local operation:@\Yes
Remote operation:@\Yes
Transfers text files:@\Yes
Transfers binary files:@\Yes
Wildcard send:@\Yes
@q(^X/^Z) interruption:@\Yes (through micro)
Filename collision avoidance:@\Yes
Can time out:@\No
8th-bit prefixing:@\Yes
Repeat count prefixing:@\Yes
Alternate block checks:@\Yes
Terminal emulation:@\No
Communication settings:@\No
Transmit BREAK:@\No
Packet logging:@\Yes
Transaction logging:@\Yes
Session logging:@\No
Raw transmit:@\Yes (no prompts)
Sliding window:@\No
Long packets:@\Yes
Act as server:@\Yes
Talk to server:@\Yes
Advanced server functions:@\Yes
Advanced commands for servers:@\Yes
Local file management:@\Yes
Handle Attribute Packets:@\Yes
Command/init files:@\Yes
Command macros:@\No
@end<format>

@subheading<CICS Specifics of Kermit-370:>
@begin<format,leftmargin +2,above 1,below 1>
@tabclear()@tabset(3.2inches,3.7inches)
@Index(Initialization files)@Index(Log files)@Index(LRECL)
Global INIT file:@\@q(KSYS.TD)
User INIT file:@\@q(KINIT.TAKE)
Debug packet log:@\@q(KLOG)@i(term)@q(.TS)
Server reply log:@\@q(KREP)@i(term)@q(.TS)
Mail command:@\@q[KERMAIL R(_...) @i<filespec> LIST(@i<users>)]
Print command:@\@q[KERMPRT R(_...) @i<filespec> OPTIONS(@i<options>)]
Submit command:@\@q[KERMSUB R(_...) @i<filespec> OPTIONS(@i<options>)]
Maximum packet size:@\1913 (SERIES1), 1024 (TTY)
Maximum disk LRECL:@\32767
@end<format>

@Index(IBM)
@Index(TTY)@Index(Series/1)@Index(CICS)
Kermit-CICS is a member of the generic Kermit-370 family and shares most
of the features and capabilities of the group.
As its name implies, Kermit-CICS is the
variant of Kermit-370 that runs under CICS.  As much as possible, it is
designed to be independent of the operating system that runs CICS, but
only on IBM-370-compatible machines.
The primary documentation for Kermit-CICS is actually
the chapter on Kermit-370 (entitled IBM 370 Kermit), which
describes general properties; the present chapter assumes the
reader is familiar with that material.  Only the details specific to
CICS operation will be discussed here, @i<e.g.>, command syntax
relating to CICS data objects or commands not offered in general
by Kermit-370.

@Section<CICS Data Objects>

Unlike other environments for Kermit-370,
CICS is not really an operating system and does not have anything
that can be called a file system.  Nonetheless, CICS supports a
variety of data
objects that can be called "files".  Moreover, Kermit-CICS
itself maintains a Kermit-only collection of storage organized into
user directories.  Furthermore, Kermit simulates a set of CICS
file-maintenance commands: DIRECTORY, TYPE, COPY, and DELETE.  Thus,
for the purposes of Kermit,
we may speak of a "CICS file system".
The features of the file system of greatest interest to Kermit
users are the supported types of data object,
the format of file specifications (or @i<filespecs>),
and the concept of
records.  The latter is described in the Kermit-370 chapter.

@seealso(primary="Queues",other="TD, TS")
As of this writing, Kermit-CICS supports three different types of data
object: temporary storage (TS) queues, transient data (TD) queues,
and Kermit-managed directory members.  The first two are standard CICS
objects while the third is a special kind of object designed for small,
personalized, infrequently used, quasi-permanent
files, such as on-line help files and
individual Kermit initialization files.
@Index(Initialization files)
In principle, Kermit also supports three other types, but the support
is provided through an interface to external programs, only one of which
has yet been written.  These other types are non-TD pipes, spool files,
and native OS data sets.  No external drivers are included in the
standard distribution.

The CICS @i<filespec> takes one of two forms:
@Begin(example,below 0.5)
[fileclass/]filename[.filetype]
@End(example)
or
@Begin(example,above 0.5)
'qualified.file.name
@End(example)
@Index(Qualified File Names)@Index(Fileclass)
The first form represents a "normal" CICS data object while
the second is the means of specifying a data object in the native
operating system that supports CICS.
In the first form, the optional fileclass is a string of up to eight
characters.  The filename is the primary identifier
for the file, but the formats of both the fileclass and the
filename depend on the filetype.  The latter must
be one of a small set of supported types: PGM, SPOOL, TAKE, TD, TS,
TSAUX or TSMAIN.  The last two are alternates for TS and are intended
for specifying the type of storage desired for a new TS queue.  The
default is Auxiliary storage.  Any
of the three types will serve equally well@Index(TS queues) to
identify a queue that already exists.  With filetypes @qq<TD> and
@qq<TQ>, the fileclass is meaningless but may be
specified anyway.

Kermit-CICS supplies a default filetype of @qq<TS> for any
received file if no filetype is
provided by the remote system.  If no filename is supplied either,
Kermit invents one by concatenating the letter @qq<K>, a three-digit
number, and the user's four-character CICS terminal id.  In any case,
Kermit forces the filename
@Index(TD queues)
to conform to CICS rules by truncating it, if necessary, to eight
characters (four for a TD queue).  Also, Kermit converts any lower-case
letters to upper case.
Kermit-CICS supports a special file naming construct for TS queues.  If
the string ";;;;" appears in the name given to Kermit, that is replaced
by the terminal id of the current session.  This is useful for avoiding
name conflicts when two or more users are running Kermit at the same
time.  The special string may also be set to any other desired four-byte
string, simply by changing the definition of variable symbol &KTRMS in the
source code.  The string should not contain any reserved
characters, such as Asterisk, Percent, Period, Slash, Less-than, Comma,
or Blank, and should not begin with quasi-reserved characters such as
Apostrophe or Question mark.

Filetype @qq<TD> refers to any kind of transient data queue.  TD queues
are much like files in a true file system, except for two important
features: TD queues are permanent data objects (despite the transience
of the data), and there is no straightforward means of determining how
much storage a given TD queue occupies.  These two features combine to
defeat the provisions made by Kermit for handling filename collision
@Index(Filename collision)
(see SET FILE COLLISION in the Kermit-370
chapter).  Intra-partition queues, at least, have an associated number
of queued records, but output extra-partition queues do not and
therefore must always be presumed to contain data, @i(i.e.), to exist in
a real sense.  Of course, all TD queues exist insofar as they are
pre-defined in the CICS DCT, but the intent of the default filename
collision handling is to protect data from erasure.  Thus, Kermit-CICS
will not normally write an uploaded file into an output extra-partition
TD queue at all.  Because of the filename collision, the file would be
written to a TS queue, according to the algorithm described under SET
FILE COLLISION in this chapter.  The only way of uploading to a TD queue
is to change the COLLISION setting to APPEND or OVERWRITE.  Another
effect of the non-dynamic quality of TD queues is that Kermit, when
presented with an undefined TD queue name for an uploaded file, cannot
create the missing queue.  Thus, it must behave as if there were a
filename collision and find an alternate place to store the file.
However, if COLLISION were not set to RENAME, Kermit would not even
check for collisions, but would simply attempt to write to the undefined
queue and stop the file transfer because of the resulting I/O error.

Because TD queues are system-wide resources available to all users,
data could be destroyed or confused if more than one user attempted
to read or write the same queue at once.  To prevent that, Kermit-CICS
uses the CICS ENQUEUE command with a resource name equal to the name
of the TD queue and gives up if the resource is busy for three
consecutive seconds of waiting.

@Index(Pipes)
Filetype @qq<PGM> specifies a pipe
managed by a CICS program whose name is
the filename.  Such a program is invoked to open the pipe, then
successively to read or write, and finally to close the pipe.  A single
program can be written to manage both input and output, even
perhaps both at
the same time.  The optional fileclass in the @i(filespec) may be used
by the program for any desired purpose.  See the installation guide for
details about writing such a program.

@Index(Spool files)
Filetype @qq<SPOOL> represents a special type
of pipe.  The filename gives
the name of the desired spool file, and the program to be invoked is
IKXDYNAL.  The optional fileclass is the spool class.
@Index(Fileclass)

@Index(Directories)@Index(Userids)@Index(TAKE files)@Index(TAKE)
Filetype @qq<TAKE> denotes a Kermit-managed directory
member.  Note that this
filetype is not reserved for TAKE files, even though directory
storage is the
logical place to keep most TAKE files.  Throughout this chapter, as in
the other chapters on Kermit-370, the term "TAKE file" will
always mean a file containing Kermit subcommands suitable for execution
via the TAKE subcommand, regardless of the filetype.  Data objects
with filetype @qq<TAKE> will be called "directory members", regardless of
the purpose of those objects.  The fileclass, if any,
specifies the directory name (either @qq<0000> to select the common
directory or a userid to select a personal directory).  The default
directory name is @qq<*>, which represents the userid of the
current session.  Userids
in Kermit-CICS are determined according to an algorithm
chosen as part of the installation process (@i<e.g.>, the CICS operator
id).  The filename of a member
specifies that member within the given directory.  Obviously, distinct
members having the same filename may exist simultaneously in different
directories.  In short, this Kermit-managed storage comes close to being
a real file system, aside from the limitation to the single filetype
@qq<TAKE>.  For this reason, the Kermit concept of the "working
directory" is implemented in Kermit-CICS primarily
as the current directory associated with filetype
@qq<TAKE>.  However, there is an alternate
use of the "working directory" concept, namely, to specify a default
@Index(Qualified File Names)
prefix for Qualified File Names (QFN's).  Selecting
a "directory" name that
begins with an apostrophe establishes that string as a QFN prefix for
subsequent @i(filespecs) given to Kermit-CICS.  See the description of
the CWD subcommand in this chapter for more details about "working
directories".

@Index(Quotas)
Despite the apparent convenience and privacy of Kermit directory
members, these objects are not intended for routine file transfers,
but only for small, quasi-permanent files.  The implementation makes use
of a VSAM KSDS for storing the members and is geared entirely toward
simplicity, rather than efficiency.  Thus, each record of a directory
member is a separate record in the KSDS identified by a human-readable
17-byte key consisting of the directory name, the member name, and the
record number.  Reading or writing a large member could tie up
significant amounts of system resources.  To ensure that users respect
the restriction on directory members, Kermit imposes a two-tiered quota
on each directory.  If the first limit is exceeded, no further members
may be created in the offending directory until
enough space has been freed by deleting members.  If the second limit
is exceeded, Kermit will stop writing to the new member immediately
and will give a "disk full" error indication.  These limits apply
equally to all directories.  The limits in the standard version of
Kermit-CICS are 100,000 and 150,000 bytes, respectively, but each
installation is free to establish its own limits.

To provide compatibility with other operating systems, when Kermit-CICS
sends a file, it ordinarily makes a file header with
only the filename and filetype.  However, extra information
may be added by way of the SET FOREIGN subcommand.  In the case of a
QFN, the last two tokens of the name are used for sending.

@Index(Wildcards)
CICS allows a group of files to be specified in a single
@i(filespec) by including the special
"wildcard" characters @qq<*>
and @qq<%>.  A @qq<*> matches any string of characters (even a null
string) within the filename;
a @qq<%> matches any single character.  Here are some examples:

@Begin(Description,spread 0.5,leftmargin +18, indent -16)
@q<*.TS>@\All TS queues currently in CICS.

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

@q<0000/%%.TAKE>@\All system directory members with two-character names.
@End(Description)

CICS files, like those in other IBM 370 systems, are record-oriented
(see the introduction to the Kermit-370 chapter).
In particular, CICS files are characterized by record
format (RECFM), which may be fixed-length or varying-length,
and by record
length (LRECL).  Extra-partition TD queues are the only
currently supported type of file that may have fixed-length
records.  An important point to note is that records
being written to a RECFM V data object are generally
not limited in length by the current LRECL,
but only by the CICS Kermit maximum (32767 bytes).  This is true of
directory members and TS and
intra-partition TD queues, but other limits may apply
to other data objects.

When sending files, Kermit-CICS includes a date/time attribute if
available.  However, any date attribute of a file
received into CICS is merely checked for validity and then discarded.

Another file system feature of occasional interest is the means of
reporting errors.  When Kermit-CICS encounters a file I/O
error, it records
@Index(Error codes)
the function name and the error code from EIBRCODE
for inclusion in the STATUS report.  The
explanations of EIBRCODE can be found in Appendix A of the
CICS command-level reference manual.  In some cases, however,
Kermit will report
an error code for an operation not directly performed by CICS.  These
extra codes have not been defined, since they would result from
operations on as-yet-unsupported filetypes.

@Section<Program Operation>

@Index(Initialization files)
Kermit-CICS is a conversational transaction.  Thus, when it starts up,
it allocates and initializes buffers and storage arrays.  In addition,
to provide for site- and user-specific environments, it
looks for two initialization
files, @q(KSYS.TD) and @q(KINIT.TAKE).
The file @q(KSYS.TD) is a read-only, extra-partition TD queue
maintained by a systems programmer.  The file @q(KINIT.TAKE)
resides in the user's Kermit directory and
must be maintained by the user.  For example, the file could be changed
by downloading it to a microcomputer, editing it there, and uploading
it again (making sure to set FILE COLLISION to OVERWRITE).
Alternatively, if tools exist for editing TS queues within CICS, the
file could be copied to a TS queue, edited, and copied back.

Kermit-CICS cannot
time out while waiting for a packet.  The only way to
time out is from the other side:
typing a carriage return to the local Kermit causing it to retransmit
its last packet, or an automatic timeout as provided by many
Kermits.

@Index(TTY)@Index(Handshake)
CICS is different from some other IBM mainframe systems in that it allows
a program to
take control of prompting and synchronization on @qq<TTY> lines.
Kermit-CICS takes advantage of this option, and
it is not necessary to enable handshaking
on the micro Kermit before
connecting to CICS.  Thus,
the micro Kermit should have
HANDSHAKE set OFF, and Kermit-CICS should have HANDSHAKE set to 0.
Since the generic Kermit-370 default handshake (XON) is retained in
Kermit-CICS, the subcommand @qq<SET HANDSHAKE 0> is a good candidate
for inclusion in @q(KSYS.TD).
@Index(Initialization files)

@subheading(Interactive Operation:)

To run Kermit-CICS interactively, invoke the program from CICS by
typing @q<KERMIT>.  When you see the prompt,
@example(Kermit-CICS>)
you may type a Kermit subcommand.  When the subcommand completes, Kermit
issues another prompt.  The cycle repeats
until you exit from the program.  For example:
@Begin(Example)
.@ux(KERMIT)

Kermit-CICS Version @value(-cicsversion) (@value<-cicsdate>)
Enter ? for a list of valid commands

Kermit-CICS>@ux(send foo*.ts)

  @i(TS queues with names beginning FOO are sent)

Kermit-CICS>@ux(receive test.td)

  @i(File is received and stored in the TD queue called TEST)

Kermit-CICS>@ux(exit)
@end(example)

In this example, which assumes a linemode session
with a system prompt of @qq<.>, the text entered by the user is
displayed along with messages and prompts.  The annotations are
indented, but the distinction between user text and Kermit text
may depend upon how this document is printed.  Normally,
the text entered by the user is underscored, and the
messages and prompts are not.

The prompt string from
Kermit-CICS is truly interactive.  In other words, the prompt
appears only when fresh
input is needed from the terminal.  If, for example, multiple Kermit
subcommands have been stacked up using the delimiter feature,
the stack is read and
executed before the next prompt appears.

@subheading(Command Line Invocation:)

Kermit-CICS may be invoked with command-line arguments from CICS.
The arguments (taken to be the string beginning after the first blank
after the four-letter transaction id @qq<KERM>)
are interpreted as one or more subcommands to be executed
by Kermit after completion of the initialization.  Thus, the command
may be abbreviated as @qq<KERM> or @qq<KERMI> at the user's discretion.
For instance:
@Begin(Example)
.@ux(KERMIT send test.take)
@End(Example)

Kermit will exit and return to CICS after completing the specified
subcommand.  A command line may contain up to
256 characters.  Note that the subcommand delimiter is initially
disabled in Kermit-CICS, but it can be enabled in either of the
initialization files and can then be used for entering
multiple subcommands on the command line.

@subheading(Non-interactive Operation:)

@Index(Automatic operation)
Kermit-CICS is both a CICS transaction named KERM
and a CICS program named KERMIT.  As with any
transaction, it may be started automatically as well as by hand, but it
will then read the terminal expecting to find the command-line arguments
(if any) for execution as a Kermit subcommand.  In addition, Kermit may
be invoked via the CICS LINK and XCTL commands and (optionally)
supplied with a COMMAREA.

If there is no COMMAREA, Kermit reads the terminal just as if
it were invoked as a transaction.  If supplied, the COMMAREA is scanned,
instead of a terminal buffer, for the command string.  Note that, if the
COMMAREA does not begin with a blank, the first blank-delimited word
will be ignored in the same way as the transaction name in a terminal
buffer.  In both cases, the command-line arguments begin with the first
non-blank character after the first blank.  Once the command line is
established, execution proceeds the same as if Kermit had been started
by hand; since Kermit exits as soon as it finishes the subcommand
specified in the command string, there is no need to enter any
subcommands at the terminal in this mode of operation.  Even so, Kermit
should be given a terminal, since that provides the communication line
for file transfer.

When Kermit exits, if the given COMMAREA is at least
seven bytes long, Kermit sets a return or completion
code in the COMMAREA according to
the current status.  See the table of error codes in the Kermit-370
chapter.  The return code takes the following form: the characters
@qq<R(>, a four-byte signed binary integer, and the character @qq<)>.
It is, thus, compatible with the convention described below under the
CICS subcommand.
@Index(Completion codes)

@subheading(Interface to mail, print, and batch)

@Index(Electronic mail)@Index(Printing files)@Index(Batch jobs)
Unlike many other IBM/370 environments, CICS does not provide a standard
means of returning a completion code from an invoked program.  As the
previous paragraph indicates, Kermit-370 has adopted its own standard,
using the COMMAREA, and this applies to the calling sequences for the
commands that handle electronic mail, print files, and batch jobs.
Thus, the @qq<R(_...)> shown in those sequences at the beginning of this
chapter is not to be considered as an option, but as a required part of
the COMMAREA to allow room for a return code.  Consequently, when
Kermit-CICS calls one of those programs to verify the feasibility of
that kind of file disposition, the COMMAREA consists of seven bytes,
rather than none.  See below under the HOST subcommand for more details
about invoking CICS programs from Kermit.

@subheading(Server mode:)

Command execution in server mode is different in three respects
from normal operation.  First, some Kermit subcommands
are not allowed (see the list of subcommands in the Kermit-370 chapter).
Second, command errors
always terminate any active TAKE file.
Third, Kermit intercepts its terminal output
and transmits the data to the local
Kermit as text packets.  However, any other programs that wish to write
to the terminal will do so, and
such messages never appear to the local Kermit (except, perhaps,
as bad packets).

@Section<Kermit-CICS Subcommands>

Kermit-CICS supports all the subcommands
described in the
Kermit-370 chapter.  In addition, there is the system-specific
subcommand @qq<CICS>, which is a synonym for
the generic subcommand @qq<HOST>.  @qq<CICS>
can be issued as a remote Kermit command when Kermit-CICS
is in server mode.

This section concentrates on
the subcommands that have special form or meaning for Kermit-CICS.
These are ordered alphabetically.
See the chapter on Kermit-370 for further details.

@Heading(The CICS Subcommand)
@Index(Host commands)

Syntax:@q< CICS  @i(text of command)>

@Index(File management)
Kermit-CICS supports two kinds of "system" commands.  Both kinds are
designated by the prefix @qq<CICS> or @qq<HOST>, even though neither
kind can be invoked directly from a CICS session.  The first word of the
command string is taken to be the name of the command.  Kermit first
checks whether the name is in a list of simulated CICS functions (and
their abbreviations).  If so, Kermit itself simulates the function.  The
@Index(TYPE)@Index(DIRECTORY)
available functions are DIRECTORY, TYPE, COPY, and
DELETE.  DIRECTORY and TYPE are identical to the corresponding
Kermit subcommands.
COPY has a straightforward syntax (old @i<filespec> followed by new);
DELETE is even simpler (just the desired @i<filespec>).  DELETE and
DIRECTORY have no special options,
but COPY and TYPE offer one: the source @i<filespec>
may have a range of line numbers (in the same syntax as the SEND
subcommand) to be copied/typed instead of the entire file.
@Index(COPY)@Index(DELETE)
All four functions are applicable to the same data objects
as KERMIT SEND and RECEIVE, but none of the four recognize wildcards.
No RENAME function is implemented,@Index(RENAME) although that
command name is reserved.
@Indexentry(key="Command level",
 entry="Command level.  @i<See> CICS command level")
If the command name is not found in the list of special functions,
Kermit attempts to invoke a CICS program of that name with a COMMAREA
consisting of the remainder of the command string.  The CICS
commands used in @Index(CICS command level)command-level
programming are not supported.  Kermit detects numeric return
codes from co-operating invoked programs by examining the COMMAREA
upon return.  If the first two bytes are the string @qq<R(>, the seventh
byte is @qq<)>, and the third byte is the same as the fourth, the string
of bytes three though six is taken to be a binary fullword return code.
The conditions are sufficiently restrictive that "accidental" return
codes are very rare (one chance in four billion, assuming totally
random bytes, but probably less than that in practice).  A
negative code is taken to mean that the host command was actually
"illegal" in some sense, a zero code means that the command completed
successfully, and a positive code means that the command encountered
an error of some kind while executing.  Positive codes are reported to
the user in the form @qq<R(number)>, where the numeric value is given
in decimal.

@Heading(The CWD Subcommand)
@Index(CWD)@Index(Directories)@Index(Fileclass)

Syntax:@q< CWD @i(directory) @i(or) '@i(prefix)>

The CWD (Change Working Directory)
subcommand establishes a new default directory
or specifies a
default prefix for Qualified File Names.  The specified name is
normally the four-character userid associated with a directory in
Kermit-managed storage.  However, if
the name is omitted, this resets the directory to @qq<*>, which is a
synonym for
the session userid.  If the name begins with an apostrophe, that
establishes the use of Qualified File Names with the given string
as prefix.  When a QFN prefix is established, any @i(filespec) given
to Kermit-CICS without an explicit fileclass (directory) will be
appended to the current prefix and interpreted as a QFN, rather than
as a normal CICS data object name.
@Index(Qualified File Names)
When a fileclass is given explicitly, even if the fileclass is
ignored (as in the case of TD and TS queues), that
overrides the presumption of a QFN.  Thus, while the CWD subcommand
allows the convenience of an abbreviated notation for both QFN's and
normal data object names, the underlying syntax always permits the
specification of any desired file by spelling out the @i(filespec) in
full.  For example, if the current prefix is @qq<'AAA1234.>, the QFN
@qq<'AAA1234.OLD.TAKE'> may be abbreviated as just @qq<OLD.TAKE>, but
the system initialization file can still be specified (as
@qq<*/KSYS.TD>).  Similarly, if the prefix is @qq<*>, @i(i.e.), the
session default directory name, the same QFN must be spelled out in
full, while the filespec @qq<OLD.TAKE> would refer to member @qq<OLD>
in the user's directory.

@Heading(The DIRECTORY Subcommand)
@Index(DIRECTORY)

Syntax:@q< DIRECTORY @i(filespec)>

The DIRECTORY subcommand displays attributes of one or more files
(name, LRECL, RECFM, size, type, and date).
The @i(filespec) may have wildcard characters if it refers to members
of the current working directory or to TS or TD queues.
For TD queues, the type is displayed as @qq<EXTRA>, @qq<INTRA>,
@qq<REMOTE>, or @qq<INDIRECT>, and the type for all other data
objects is @qq<OTHER>.  The size is displayed, where possible, in
two forms, both the number of records and the total number of
bytes (rounded to the nearest kilobyte).  If either of those
sizes is shown as zero, it may simply mean that Kermit was unable
to obtain the required information, @i(e.g.), for main-storage TS
queues in CICS under MVS/ESA.  A value of zero for the LRECL means
that the only limit is 32767.  Similarly, if the date is unavailable
(often the case), it will simply be omitted.

@Heading(The GIVE Subcommand)
@Index(GIVE)@Index(Translation tables)

Syntax:@q< GIVE @i(table-name) @i(filespec)>

This subcommand compares the named translation
table with its default values and saves the differences
in a TAKE file named @i(filespec).  The @i(filespec)
has the usual format, except that the default
filetype is @qq<TAKE>, rather than @qq<TS>.  See the Kermit-370 chapter
for a fuller description of this subcommand.

@Heading(The HELP Subcommand)
@Index(HELP)

Syntax:@q< HELP [@i(subcommand)]>

This subcommand
displays a message that explains the specified Kermit-CICS subcommand.
If no subcommand is given, the message explains the Kermit command
itself.  These messages are stored in the Kermit-managed storage in
the common directory.

@Heading<The RECEIVE Subcommand>

@Index(RECEIVE)
Syntax:@q< RECEIVE [@i(filespec)]>

The RECEIVE subcommand tells Kermit to receive one or more files
from the other system.  You must issue the corresponding
SEND subcommand to the
other Kermit.

If the optional @i(filespec) is omitted, Kermit-CICS will use the
name(s) provided by the other Kermit.  If that name is not a legal
CICS file name, Kermit-CICS will delete excess characters,
if any.  If the filetype is illegal, however,
Kermit will reject the file.  Wildcards may not be used.
A @i(filespec) in the subcommand indicates what name the incoming file
should be given.
If the optional @i(filespec) is provided,
but more than one file arrives, the
first file will be stored under
the given @i(filespec), and the remainder will be stored under
their own names, as provided by the other Kermit.

For purposes of truncation and folding, the maximum record length for
a received file depends on the file type and the filetype.  BINARY
files are folded at the current LRECL, but TEXT files may have a
maximum size of 32767 (TS queues and Kermit directory members do,
as do TD queues with varying-length records).
@Index(Truncation)@Index(Folding)

@Index(Filename collision)
If the incoming file has the same name as an existing file, the action
taken depends on the FILE COLLISION setting.  The possible settings
and their meanings are given in the Kermit-370 chapter.  Two of the
settings (BACKUP and RENAME) require that
Kermit-CICS change the incoming name
so as not to obliterate a pre-@|existing file.  It attempts to find
a unique name by successively modifying the original and checking for
the existence of such a file at each step.  The procedure begins by
truncating the filename to six characters if necessary and then
appending @qq<$0> and changing any filetype other than @qq<TAKE>
to @qq<TS>.  If a file by that name exists,
Kermit then replaces the @qq<0> with a @qq<1>.
It continues in this manner up to @qq<9>, and if an unused name cannot
be found, the transfer fails.  In Kermit-CICS, the default setting of
FILE COLLISION is RENAME, which causes the new file to be stored under
the modified name.  The BACKUP option is not supported by Kermit-CICS.

@Heading<The SEND Subcommand>
@Index(SEND)

Syntax:@q{ SEND [@i(filespec)[<@i(options)>] [@i(foreign-filespec)]][, ...]}

The SEND subcommand causes one or more files to be sent from CICS
to the other system.
For details on the @i(options), see the description of
SEND in the Kermit-370 chapter.  Note that no blanks may intervene
between the CICS @i(filespec) and the @i(options).

@Index(Wildcards)
If the filetype is @qq<TD>, @qq<TS>, or @qq<TAKE>,
the filename may contain the wildcard characters @qq<*> or
@qq<%>.  Wildcards are valid with @qq<TAKE> only for the current
directory.  If wildcards are used, all eligible matching files will
be sent.  Note that wildcard specification for TS queues cannot be
guaranteed to work correctly, since CICS is a multi-user environment,
and the system chain of queues can be modified dynamically while
Kermit is following the chain looking for matches.  The result might
be to skip one or more files, to send a file more than once, or to
attempt sending a non-existant queue (cutting short the transfer with
an I/O error message).

The @i(foreign-filespec), if any, is used for the file header of the
outgoing file, replacing the usual @qq<name.type> copied from the
CICS @i(filespec).
Normally, this form of the SEND subcommand is used only
when the @i(filespec) has no wildcards, since
the @i(foreign-filespec) is used only for the first file of a
group (subsequent files having default headers).
If both @i(filespecs) are omitted for this subcommand, Kermit will
prompt separately for each.
This prompting mode is especially useful when more than one file
(or file group) is to be sent, since the command line is limited
to 130 characters.

@Indexsecondary(primary="Blanks",secondary="preserving trailing")
Trailing blanks in a text file with RECFM F are deemed superfluous and
are stripped off when Kermit-CICS downloads the file.  In order to treat
such blanks as significant, you must convert the record format to V by
using, for example, the Kermit HOST COPY subcommand to move the file
to a TS queue.

@Heading<The SET Subcommand>
@Index(SET)

Syntax:@q< SET @i(parameter) [@i(value)]>

The SET subcommand establishes or modifies various parameters controlling
file transfers.
The following SET parameters are available in Kermit-CICS, but not
universally in Kermit-370:
@Begin(Format,spread 0)
@tabclear()@tabset(2.0inches)
DELIMITER@\character for terminal input.
FILE
  LRECL@\Logical Record length for incoming file.
  RECFM@\Record format for incoming files.
PREFIX@\New directory.
@End(format)

@Subheading<SET DELIMITER>
@Index(Delimiter)

Syntax:@q< SET DELIMITER @i(character)>

This subcommand is
defines a character to be interpreted as the logical end of an input
command line (for the purpose of entering multiple commands on a
single line).  This is used only for commands entered at the terminal
and has no effect on commands contained in TAKE files.  The delimiter
is initially undefined, but it can be set in one of the initialization
files and thereby be used in parsing the initial command-line
arguments.

@Subheading(SET FILE COLLISION)

Syntax:@q< SET FILE COLLISION @i(option)>

Unlike most other variants of Kermit-370, Kermit-CICS has RENAME as the
default value for FILE COLLISION.  As a consequence, the usual mode of
operation for receiving a file that already exists (or appears to
exist, as extra-partition TD queues always do), is to assign a new and
unique name and save the file as a TS queue.  If you really want to
upload into an extra-partition TD queue, you must first SET FILE
COLLISION OVERWRITE or APPEND, whichever is appropriate.  Actually, if
the queue in question already exists but
is closed, these two options have the
same effect, which is to overwrite the queue.
@Index(Filename collision)@Index(TD queues)

@Subheading(SET FILE LRECL)

Syntax:@q< SET FILE LRECL @i(number)>

This sets the logical record length for incoming files to a @i(number)
from 1 to 32767 (32K-1).  This variable is used only for fixed-format
and binary files.  However, the only
currently supported type of fixed-format files is the extra-partition TD
queue, which does not allow Kermit to alter the pre-defined LRECL.
The default is 80.

@Subheading(SET FILE RECFM)
@Index(RECFM)

Syntax:@q< SET FILE RECFM @i(option)>

This
sets the record format to use for incoming files.  Valid @i<option>s are
"Undefined", "Fixed", and "Variable" (the default).
Fixed-format records are padded, folded,
or truncated, as needed, to the current LRECL.  Most kinds of files,
in fact, cannot be anything but variable.  There is no current use for
this subcommand, since the only files that can have fixed-length
records are not affected by the Kermit setting.  However, there may
be future applications for as-yet-unsupported filetypes.

@Subheading<SET PREFIX>

Syntax:@q< SET PREFIX @i(string)>

This subcommand is equivalent to the CWD subcommand (@i<q.v.>).  Issuing
@qq<SHOW PREFIX> will not reveal the name of the default directory,
since that is called by its alias @qq<*>.  You must use the SPACE
subcommand instead (@i<q.v.>).  There is no mechanism for displaying
the list of all existing directories.
@Index(Directories)

@Heading(The SPACE Subcommand)
@Index(SPACE)

Syntax:@q< SPACE>

This subcommand displays the storage
allocation in the current directory and the allowed quota.  If there
is no current directory, @i(i.e.), if a QFN
@Index(Qualified file names)
prefix has been selected, the response is @qq<No directory defined>.

@Heading<The TAKE Subcommand>
@Index(TAKE)

Syntax:@q< TAKE @i(filespec)>

Execute Kermit subcommands from the specified file.  The @i(filespec)
has the usual format, except that the default
filetype is @qq<TAKE>, rather than @qq<TS>.

@Section<How to build an executable Kermit-CICS>

Before attempting to build Kermit-CICS, look in the
Kermit distribution under IKXKER for the
installation document, as well as "beware", help, and update files, and
read them first.  They will probably contain information that is more
current than what you see here.  Indeed, the process of applying the
updates is complicated enough that it cannot be adequately described
here.  The installation document @q(IKXKER.INS)
contains a full description of the process, including
@Index(Batch jobs)
batch jobs for carrying out the various steps.
You will need to extract the JCL and submit it (suitably
tailored to your local environment).  These jobs apply the updates, pass
the source through the command-level translator and the assembler, and
finally link the program into an executable phase or load module.
@Index(CICS command level)

@Index(Initialization files)@Index(Translation tables)
If your site's ASCII/EBCDIC translation table
for TTY lines does not conform
to the one listed in the appendix (which in turn conforms to the
one given in the IBM System/370 Reference Summary), then enter
the appropriate SET ATOE/ETOA/TATOE/TETOA
subcommands in @q(KSYS.TD).  The generic Kermit-370 chapter includes
an invertible 256-entry translation table and describes a procedure
for determining what SET subcommands are needed.
@i<NOTE:> If your site's ASCII/EBCDIC translation is not invertible for
at least 96 entries, Kermit will not and cannot work.

@Section(What's New)
Below is a list of the CICS-specific features in Version
@value(-cicsversion) of Kermit-CICS added since the previous major
release, Version 4.2 in March of 1990.
For the list of generic additions, see the chapter on Kermit-370.

@begin(enumerate,spread 0.5)
Termid substitution in filenames.

User id for Kermit storage expanded to 8 bytes.

Compatibility with CICS 3.1.

Prompt string padded with XON.

Serialized access to TD queues.

Small bug fixes.

@end(enumerate)

@Section(What's Missing)

Work on Kermit-CICS will continue.  Features that need to be
improved or added include:
@begin(itemize)
IKXDYNAL for both CICS/VSE and CICS/MVS.  The former
would probably support only
spool files, but the latter should support both spool
files and MVS data sets (QFN's).

Sample exit routines for supporting userid algorithms besides
the OPID and TERM options.

Sample package of security exit routines.

Support for data objects on a remote CICS.

Cleaner performance of server-mode BYE function, dependent on local
conventions.

Support for indirect TD queues.

Mechanism for flushing terminal output from Kermit (such as for the
TYPE subcommand).

Mechanism for collecting "terminal" output from invoked programs.

Testing under CICS/VM.

SET REPEAT subcommand.

CONNECT subcommand.  This may be impossible.
@end(itemize)

Anyone interested in working on these or other improvements should first
get in touch with the Center for Computing Activities at Columbia
University to find out if someone else has already begun a similar
project (and, if so, who).