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

Text File | 2020-01-01 | 33KB | 819 lines

@Part(TSOKERMIT,root="kuser")
@string(-tsoversion="4.3.0")
@string(-tsodate="93/9/30")
@Chapter<IBM MVS/TSO KERMIT>
@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),
Bob Shields (U. Maryland),
Greg Small (UC Berkeley),
Bob Bolch and Steve Blankinship (Triangle), Ron Rusnak
(U. Chicago), Charles Painter (U. Toronto),
Roger Fajman and Dale Wright (NIH),
Andr@eac() Pirard (U. Li@egr()ge)

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

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

@i(Version:)@\@value(-tsoversion) (@value<-tsodate>)

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

@Index(TSO)
@subheading<Kermit-TSO Capabilities At A Glance:>
@begin<format,leftmargin +2,above 1,below 1>
@tabclear()@tabset(3.5inches,4.0inches)
Local operation:@\No
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:@\Yes (line mode only)
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<TSO Specifics of Kermit-370:>
@begin<format,leftmargin +2,above 1,below 1>
@tabclear()@tabset(3.5inches,4.0inches)
@Index(Initialization files)@Index(Log files)@Index(LRECL)
Global INIT file:@\@q('SYS1.KERMINI')
User INIT file:@\@q(KERMINI)
Debug packet log:@\@q(KER.LOG)
Server reply log:@\@q(KER.REPLY)
Mail command:@\@q[KERMAIL @i<filespec> LIST(@i<users>)]
Print command:@\@q[KERMPRT @i<filespec> OPTIONS(@i<options>)]
Submit command:@\@q[KERMSUB @i<filespec> OPTIONS(@i<options>)]
Maximum packet size:@\1913 (SERIES1), 1024 (TTY)
Maximum disk LRECL:@\32760
@end<format>

@Index(IBM)
@Index(MVS/TSO)@Index(TTY)@Index(Series/1)
Kermit-TSO 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-TSO is the
variant of Kermit-370 that runs under the MVS/TSO operating system.
The primary documentation for Kermit-TSO 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
TSO operation will be discussed here, @i<e.g.>, command syntax
relating to the TSO file system or commands not offered in general
by Kermit-370.


@Section<The MVS/TSO File System>

The features of the TSO file system of greatest interest to Kermit
users are the format of file specifications (@i<filespecs>)
and the concept of
records.  The latter is described in the Kermit-370 chapter.

@Index(Qualifier)
The MVS/TSO @i<filespec> (called the data set name or DSN) takes the form
of tokens (known as qualifiers) of up to 8 alphanumeric characters each,
separated by periods.  Each qualifier must begin with an alphabetic or
national character.  The total length must be no
more than 44 characters, including periods.
To be precise, a DSN may contain uppercase letters, digits, and
the special characters @qq<$> (dollar sign), @qq<#> (number sign),
@qq<@@> (at sign), and @qq<-> (hyphen) in addition to the separating
periods.  Other characters must not be included.

@Index(Catalog)
There is another, structural restriction on
data set names from the fact that TSO data sets are all cataloged.
In a standard
MVS catalog, each qualifier of each DSN is associated with an
index of the same name.  The index is a hierarchical
catalog component which points downward either to a list of next-level
indices or to a data set, but never to both.  Consequently, a
cataloged DSN is a chain of indices corresponding one-for-one with
DSN qualifers, and the last index is a pointer to the data set itself.
While there may be many indices with the same name, no two such
duplicates may both be chained to the same next-higher-level index,
so that, if DSN's are considered as strings of qualifiers (not of
characters),
no DSN can be a major substring of any other.
For example, if the name @q<'A.BB.C'> exists in the
catalog, then @q<'A.BB'> and @q<'A.BB.C.X'> are illegal, but @q<'A.B'>,
@q<'A.BB.Y'>, @q<'A.BBB'>, and @q<'A.BB.BB'> are all legal.
Although there is a newer form of catalog, known as IFC, which removes
this substring restriction, it is still good practice to avoid violating
it because there are still sites that use the older form.

A DSN given in its entirety (as in the foregoing examples)
is called "fully qualified" and must be enclosed in single
quotes when entered in TSO.  However, by convention (and by definition)
the first qualifier of each data set
belonging to a given user must be the user's logon ID, and, by
default, that ID is the assumed prefix in TSO when a DSN is @i(not)
enclosed in quotes.  In practice, then, names are abbreviated by
omitting the quotes and the prefix.  The most common type of name, in
fact, consists of the prefix plus two more qualifiers giving the
data set's name and type, respectively, so that many files have DSN's
that correspond exactly to the canonical Kermit representation of a
@i(filespec).  For instance, @q<TEST.FORT> is the
source of a Fortran program named TEST, and its fully qualified DSN
would be @q<'@i(userid).TEST.FORT'>, where @i(userid) is the owner's
logon ID.

@Index(Partitioned data set)
@Index(Generation data group)
While this description is complete as far as it goes, it omits two
important features widely used in organizing files under MVS
and TSO, namely, the partitioned data set (PDS) and the generation
data group (GDG).  A PDS is a data set
like any other, except that it has members, each of which can
usually be treated as a file in its own right.  In fact, with QSAM
(the file access method employed by Kermit and many other applications),
only members, and not the whole PDS, may be read or written.  Thus,
the term "file", as used in this chapter and the Kermit-370 chapter, may
refer to either a PDS member or an ordinary data set, but not to a PDS.
The notation for a PDS member consists of the member name enclosed
in parentheses and appended to the DSN (and the whole enclosed in
quotes if the DSN is fully qualified).  For example, if the Fortran
program @q<TEST> were copied into a PDS called @q<DEBUG.FORT>, it
would then be known as
@example<DEBUG.FORT(TEST)>
Although the member name is written together with the DSN, it and the
surrounding parentheses are not really part of the DSN and are not
counted toward the 44-character limit.  Still,
a member name must conform to the rules for a DSN qualifier and, in
addition, must not contain any hyphens.

A generation data group is a collection of related data sets with
similar names (distinguished by a serial number in the last qualifier).
This organization is designed for data sets that are updated from time
to time and which must be available in several versions at once.  There
is a notation, similar to that for PDS members, for describing GDG
members relative to the current version, rather than by supplying the
explicit DSN with imbedded serial number.  The last qualifier is omitted,
and a relative generation number in parentheses is appended.  That number
must be a zero or a signed integer
("0" refers to the current version, "-1" the
next most recent, and so on).  For creating a new version, the number
"+1" is used.  Kermit-TSO supports both relative and absolute numbering
for GDG members.

All these properties of DSN's come into play when a file
is being received by Kermit-TSO because a valid DSN must be generated
for the new data set.  For example,
any invalid character in the supplied @i(filespec) is replaced by
a number sign (or converted to uppercase if it is a lowercase letter).
Also, each qualifier (and the member name, if any)
is prefixed with a number sign (if it does not already
begin with an alphabetic or national character) and then
shortened, if necessary, to eight characters.  If
no @i(filespec) is supplied,
Kermit-TSO creates a default DSN of @qq($.$).
The DSN is expanded to
its fully qualified form and then truncated at 44 characters, if need be.

The DSN prefix, which defaults to the user's logon ID, is similar
to a device specification on microcomputer systems: it selects an
area of disk storage, and it usually need not be specified.
In some ways, the prefix is also like
a disk directory designator, since the file system structure is
hierarchical.  For this reason, the Kermit
concept of the "working
directory" is equated with a particular DSN prefix under
Kermit-TSO.  The current "working directory" is the
collection of all data sets whose names begin with the current prefix,
and file transfers take place
to and from that area unless a fully qualified DSN is given.

To provide compatibility with other operating systems, when Kermit-TSO
sends a file, it ordinarily makes a file header with
only the last two qualifiers of the full DSN (or only the member name
plus the last qualifier in
the case of a PDS member).  On the other hand, extra information
may be added by way of the SET FOREIGN subcommand.

Although TSO data sets are cataloged, MVS allows uncataloged data sets
@Index(Uncataloged data sets) as well, and Kermit-TSO can download
such files, as long as the user specifies the proper disk volume
via the SET FILE VOLUME subcommand.  In principle, uncataloged
data sets may have names with illegal characters or qualifiers longer
than 8 characters, but such names are not recognized by Kermit-TSO.

@Index(Wildcards)
Kermit-TSO allows a group of files to be specified in a single
@i(filespec) by including the special
"wildcard" character @qq<*>, which
matches any string of characters (even a null
string) anywhere either in the DSN proper or in the member name, if any.
Only one @q(*) may be used in
a @i(filespec).
Here are some examples:

@Begin(Description,spread 0.5,leftmargin +18, indent -16)
@q<*.COBOL>@\All files of type @q<COBOL> (all COBOL source files) in
the current working directory.

@q<BATCH*H.FORT>@\All files in the current directory which begin
with @q(BATCH) and which end with @q(H.FORT).  This would
not include @q(BATCH.FORT), however.
@End(Description)

TSO files, like those in other IBM 370 systems, are record-oriented
(see the introduction to the Kermit-370 chapter).
In particular, TSO files are characterized by record
format (RECFM), which may be fixed-length,
varying-length, or undefined-length;
by maximum record length (LRECL); and
by maximum block size (BLKSIZE).  Fixed-length
and varying-length records
can be (and, under Kermit, always are) combined into
blocks, but undefined-length records cannot.  Indeed, by convention,
they have no logical record length, only a maximum block size.
Records (and blocks) in TSO files may be up to 32760 bytes
long, but varying-length record blocks
use four bytes to specify the block length
and, therefore, place an effective limit of 32756 on the records.
Indeed, the data portion of such records is limited to 32752 bytes.

When sending files, Kermit-TSO includes a date/time attribute if
available.  However, any date attribute of a file
received into TSO is merely checked for validity and then discarded.
Unlike many operating systems, MVS does not provide a time along with
the date of creation of modification.  Further, although partitioned
data sets can store any amount of information regarding the individual
members, there is no universal convention for saving a date for each
member.  ISPF is one system that supports both date and time tags for
PDS members, and Kermit-TSO uses those whenever possible.

Another file system feature of occasional interest is the means of
reporting errors.  When Kermit-TSO encounters a disk error, it attempts
to prepare an explanatory message for inclusion in the @q(STATUS)
report.  The primary method is the standard @q(SYNADAF) macro.

MVS/TSO allows, but does not encourage, the use of passwords
@Index(Passwords) to protect individual data sets.  When a password
is needed for file access, it is entered immediately after the
@i(filespec), separated only by a slash (@qq</>).  In the case of a
fully-qualified DSN, the password must be after the closing quotation
mark.

@Section<Program Operation>

@Index(Initialization files)
At startup time, Kermit-TSO looks for two initialization
files, @q('SYS1.KERMINI') and @q(')@i(userid)@q(.KERMINI')
(where, as before, @i(userid) is the user's
logon ID).  The latter file would also be known as just @q(KERMINI).
The file @q('SYS1.KERMINI') would be maintained
by a systems programmer, but
@q(KERMINI) would be maintained by the user.

@Index(User profile)
Three parameters in the user's profile (the character delete and line
delete and intercom) are disabled
during protocol mode
(and restored afterwards) to prevent any conflict in case either of
these characters has been defined to be printable.
The settings in effect when Kermit starts up are saved as a sort of
"normal" status snapshot (as opposed to the "protocol" status just
described).  The protocol status is selected whenever
Kermit enters protocol mode, and the normal status is selected when
Kermit leaves protocol mode.  Note: if Kermit is
interrupted in the midst of a transfer or while in server mode, these
parameters will be left with peculiar settings (namely, the protocol
status), and they may need
to be restored by hand.

Although TSO does not allow an application program to take control of
terminal synchronization on @qq(TTY) lines, the various full-screen
emulation front ends
are quite a different matter.  The standard IBM handshake (XON) is
unnecessary, for example, with a 7171 or 4994 because the front end
itself turns the line around with essentially no delay in transparent
mode.  Thus, handshaking should be suppressed for @qq(SERIES1) devices
(the micro Kermit should have
HANDSHAKE set OFF, and Kermit-TSO should have HANDSHAKE set to 0).
Since the generic Kermit-370 default handshake (XON) is retained in
Kermit-TSO, the subcommand @qq(SET HANDSHAKE 0) is a good candidate
for inclusion the KERMINI file of any user who habitually uses
@qq(SERIES1) lines.

@subheading(Interactive Operation:)

To run Kermit-TSO interactively, invoke the program from TSO by
typing @q<KERMIT>.  When you see the prompt,
@example(Kermit-TSO>)
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-TSO Version @value(-tsoversion) (@value<-tsodate>)
Enter ? for a list of valid commands

Kermit-TSO>@ux(send foo.*)

  @i(Files beginning with FOO are sent)

Kermit-TSO>@ux(receive test.spss)

  @i(File is received and called TEST.SPSS)

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

@subheading(Command Line Invocation:)

Kermit-TSO may also be invoked with command line arguments from TSO.
The arguments are interpreted as a subcommand to be executed
by Kermit after completion of the initialization.
For instance:
@Begin(Example)
.@ux(KERMIT send test.fort)
@End(Example)

Kermit will exit and return to TSO after completing the specified
subcommand.

@subheading(CLIST Operation:)
@Index(CLIST)

Like other TSO programs, Kermit-TSO may be invoked from a CLIST.
Subcommands can be passed to Kermit using the program input stack
and/or command line arguments.  For example, to start up Kermit-TSO
and have it act as a server, include the line:
@Begin(Example)
@ux(KERMIT server)
@End(Example)
To pass more than one subcommand, they must be stacked in the order in
which they are to be executed.  To start up a Kermit-TSO server with a
three character CRC, create and stack a file with the following:
@Begin(Example)
@ux(set block 3)
@ux(server)
@End(Example)
and then invoke Kermit.  Like many utility programs, Kermit-TSO uses
the GETLINE/PUTLINE
service routines for terminal I/O, and the nominally
interactive subcommands can thus be supplied under program control.
Another way of setting up multiple subcommands would be to collect the
subcommands into a TAKE file and then issue the TAKE subcommand via the
command line.
CLIST's may be executed from Kermit, either directly or from
a TAKE file, and CLIST's in turn may freely issue Kermit subcommands.
The subcommand KERMIT is especially useful in this context for
distinguishing Kermit subcommands from TSO commands.
After each subcommand completes, the &LASTCC variable is set
according to the current status code (see Table @ref(-ikcodes))
so that CLIST processing can take appropriate action if a transfer
fails.

@subheading(Server mode:)

Command execution in server mode is different in several respects
from normal operation.  First of all, some Kermit subcommands
are not allowed (see the list of subcommands in the Kermit-370 chapter).
Moreover, command errors
always terminate any active TAKE file.
@Index(User profile)
Also, commands run in a
special environment with the User Profile temporarily modified.
Another difference is that Kermit intercepts
terminal I/O as much as possible and transmits the data to the local
Kermit as text packets.  The problem with this redirection is that
some MVS/TSO commands issue terminal I/O directly, so
that many messages never appear to the local Kermit (except, perhaps,
as bad packets).

@Section<Kermit-TSO Subcommands>

Kermit-TSO supports all the subcommands
described in the
Kermit-370 chapter.  In addition, there is the system-specific
subcommand @qq(TSO), which is just a synonym for
the generic subcommand @qq(HOST).  @qq(TSO)
can be issued as a remote Kermit command when Kermit-TSO
is in server mode.  Also, the @qq(END) subcommand is available as a
synonym for @qq(EXIT) and @qq(QUIT).

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

@Heading(The CWD Subcommand)
@Index(CWD)@Index(Prefix)

Syntax:@q< CWD [@i(string or PDSname)()]>

@Index(User profile)
The CWD (Change Working Directory)
subcommand establishes a new default DSN prefix or turns prefixing off.
This facility is similar to, but not quite the same as, the prefix
defined in the User Profile.  The
@i(string), if specified, must consist of one or more DSN qualifiers,
and the first must already be an index
in the disk catalog.  Subsequent file transfers
take place to and from the corresponding disk area whenever a fully
qualified DSN (one enclosed in quotes) is not given.  The initial
prefix is the user's logon ID, @i<i.e.>, the same as the default prefix
in the User Profile.  If no prefix is given in this subcommand, then
prefixing is no longer performed.  The user must be careful to
remember the distinction between the prefix defined for Kermit and that
for TSO.  Pure Kermit subcommands (like @q<SEND> and @q<TAKE>) always
use the former, but TSO commands (and the TSO-related subcommand
@q<TYPE>) use the latter.

An alternative form of the CWD subcommand allows specifying the full (but
unquoted) name of a PDS followed by paired parentheses.  When such a
"working directory" is in use, a @i(filespec) other than a fully
qualified DSN is taken to be a member name within the PDS.  For
that reason, this form should be used cautiously, since the Kermit-TSO
log @i(filespecs) (such as @q<KER.LOG> and @q<KER.REPLY>) would be
treated the same way.  In particular, it is advisable to turn on debug
mode only when the Kermit prefix is a partially qualified DSN (once
started, the log continues to the same data set regardless of what
happens to the prefix).

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

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

The DIRECTORY subcommand uses the TSO LISTCAT command to display part
of the data set catalog, @i<i.e.>, all data sets whose names begin
with the
qualifiers in the Kermit prefix (if any) concatenated with the given
@i(filespec) (if any).  Note: wildcards may not be used, and no options
are allowed.  If you require the LISTCAT options, you
must issue a TSO LISTCAT command directly.

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

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

The HELP subcommand uses TSO HELP facilities to display part or all
of the Kermit help file.  It follows the same syntax.

@Heading<The RECEIVE Subcommand>

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

The RECEIVE subcommand tells Kermit to receive a file or file group
from the other system.  You must issue the corresponding
SEND subcommand to the
other Kermit.

A @i(filespec) in the subcommand indicates what name the incoming file
should be given.  Wildcards may not be used.
If the @i(filespec) is invalid, Kermit-TSO will suppress the transfer.
If the optional @i(filespec) is omitted (and, in any case, for all files
after the first in a group) Kermit-TSO will use the
name(s) provided by the other Kermit.  If a name is not a legal
DSN, Kermit-TSO will delete excess characters, change illegal
characters to number signs, and so on, to create a legal name.

For the purposes of folding and truncation, the maximum record
length, @i(i.e.), the limit on the length of data in each record,
is "LRECL" if RECFM is F, "LRECL"-4 if RECFM is V, and "BLKSIZE"
if RECFM is U.
@Index(Truncation)@Index(Folding)

@Index(Filename collision)
If the incoming file has the same name as an existing file
(either a data set or a PDS member), 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-TSO change the incoming name
so as not to obliterate the 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 operates on
the second qualifier of the full DSN (or the member
name in the case of a PDS member) and
begins by truncating it
to seven characters, if necessary, and
then appends @qq(0).  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.
If FILE COLLISION has not been set, but the obsolete option WARNING
has been set ON, however, Kermit-TSO will protect an existing
file in a different way when the @i(filespec) is entered with the
RECEIVE subcommand.  In that case,
Kermit will prompt the user for permission to overwrite
the file.

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

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

The SEND subcommand causes a file or file group to be sent from TSO
to the Kermit on the other system.  DSN prefixing is done on the
@i(filespec) in the usual way
(see also the CWD subcommand).  For details on the @i(options), see the
chapter on Kermit-370.  Note that a @i(filespec) may have both a
password and options -- in that case, the options must be at the
very end.  Blanks may not appear anywhere in the string.

@Index(Wildcards)
The @i(filespec) may contain a wildcard @qq<*>.  If it does,
then all matching files will
be sent, up to 711 files in all (possibly more in the case of PDS
members).

The @i(foreign-filespec), if any, is used for the file header of the
outgoing file, replacing the usual name.type derived from the
MVS/TSO @i(filespec).
Normally, this form of the SEND subcommand is used only for single files
because 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, and the respective syntaxes are exactly
as described above.
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-TSO downloads the file.  In order to treat
such blanks as significant, you must convert the record format to V,
for example, by using TSO COPY with the "RECFM V" option.

@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-TSO, but not in Kermit-370 in general:
@Begin(Format,spread 0)
@tabclear()@tabset(2.0inches)
DELIM@\Line delimiter for entering multiple commands.
FILE
  BLKSIZE@\Block size for incoming file.
  LRECL@\Logical Record length for incoming file.
  RECFM@\Record format for incoming files.
  SPACE@\Allocation unit (in tracks) for incoming files.
  UNIT@\Device type for incoming files.
  VOLUME@\Disk pack for incoming files.
PREFIX@\Default disk area.
@End(format)

@Subheading(SET DELIM)@Index(Line delimiter)

Syntax:@q< SET DELIM [@i(letter)]>

This sets (or clears) a command line delimiter for interactive
Kermit subcommands.  Each occurrence of the delimiter character in
the command buffer read from the terminal is treated as the start of
a new subcommand.  The initial value is a blank, @i<i.e.>, no delimiter,
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 BLKSIZE)
@Indexentry(key="DCB",entry="DCB.  @i<See> File attributes")
@Indexentry(key="Data set",entry="Data set.  @i<See> File")

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

This sets the block size for incoming files to a @i(number)
from 1 to 32760.  In the case of fixed-format files, this number is just
an upper bound; the actual block size is taken to be the largest
multiple of the LRECL which does not exceed this limit.
The default is 6233.

@Subheading(SET FILE LRECL)

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

This sets the effective logical record length for incoming files to a
@i(number) from 1 to 32760.  This parameter is not used for files of
undefined record format.
The default is 80.

@Subheading<SET FILE RECFM>

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

This sets the record format to use for incoming files.  Valid
@i<options> are
"Fixed", "Varying" (the default), and "Undefined".
This parameter is thus limited to a subset of the range of
possibilities for the MVS/TSO RECFM.  In Kermit-TSO, all incoming files
of fixed or varying format are automatically blocked according to the
current block size.

Note: the most common files with RECFM=U, load modules, cannot be
transported directly using Kermit, since they contain disk-location
pointers.  Such files can be "unloaded" using IEHMOVE and then
transmitted freely.
@Index(Load modules)

@Subheading<SET FILE SPACE>

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

This sets the track allocation unit for incoming files to a number from
1 to 32760.  The default is 5.  Since data sets are allowed as many as
15 extents, this default provides for files up to 75 tracks.

@Subheading<SET FILE UNIT>

Syntax:@q< SET FILE UNIT @i(type)>

This sets the device type or group for incoming files.  Valid
@i<types> are installation-dependent.  The default is blank, which
signifies the default UNIT group found in the User Attribute Data Set.
This parameter should generally be left blank unless the user wishes to
create files on a specific disk volume not included in the default
group (for example, a private volume).

@Subheading<SET FILE VOLUME>

Syntax:@q< SET FILE VOLUME @i(name)>

This sets the disk volume for incoming files.  Valid @i<names> are
installation-dependent, but are, in any case, no more than six
alphanumeric characters.  The default is blank (none); in that
case, the system chooses one of the available volumes of the
current UNIT type.

@Subheading<SET PREFIX>
@Index(Prefix)

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

This subcommand is equivalent to the CWD subcommand (@i<q.v.>).

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

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

Execute Kermit subcommands from the specified file.  The default
DSN extension is @qq(TAKE), so that datasets with names of the
form @i(prefix.name).@q(TAKE) can be executed by typing merely
@ux(TAKE @i<name>).  Names that end with @q(.TAKE) or @q(.KERMINI) are
accepted as entered (aside from prefixing), and names in quotes are, of
course, accepted exactly as entered,
but all others are assumed to have a DSN
extension of @q(.TAKE) for the purposes of the TAKE (and GIVE)
subcommands.

@Heading(The TSO Subcommand)

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

Although Kermit-TSO does not have a full set of its own
subcommands for managing
TSO files, it provides those services through the operating system.
You can issue any TSO command, @i<e.g.>, to
list, type, rename or
delete files, send messages, and so on.
The @q(TSO) subcommand under Kermit is
synonymous with the @q(HOST) subcommand.

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

Before attempting to build Kermit-TSO, look in the
Kermit distribution under IKTKER for an
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.

Kermit-TSO consists at present of a large assembly
(KERMIT.ASM, containing the Kermit program) and a small
one (DYNALC.ASM, containing a subroutine for allocating data sets).
Although DYNALC is a single file in the Kermit distribution, the
source for Kermit itself is in many pieces, some generic for Kermit-370
and some specific to TSO.  All the necessary pieces are sequenced in
columns 73-80 so that the numbers form a strictly increasing
sequence when the pieces are correctly "pasted" together.
It is important to preserve the original sequence numbers so that
updates, if any, can be applied to the source.

To create a runnable version (the hard way):

@begin(enumerate,spread 0.5)
Combine the following @qq(ASM) files from the Kermit distribution into
a single file with @q<RECFM=F(B)> and @q<LRECL=80>: IK0DOC, IK0MAC,
IKTMAC, IK0DEF, IK0MAI, IK0COM, IK0CMD, IKTUTL, and IK0PRO.
The resulting file is the composite source for Kermit-TSO, called
KERMIT.ASM.  This source must retain the original sequence numbers
in columns 73-80 (in other words, be sure not to resequence the source
accidentally by using the editor!)

Copy or rename IKTDYN.ASM from the Kermit distribution
to a file called
DYNALC.ASM with @q<RECFM=F(B)> and @q<LRECL=80>.

Assemble the source file(s).

Create the executable load module @q<KERMIT> using the linkage editor.
Be sure to specify the REUS option.
Kermit is designed to run as a command processor, and so it must be
placed in SYS1.CMDLIB or in a PDS concatenated to SYS1.CMDLIB (for
example, via the STEPLIB command).

@end(enumerate)
To create a runnable version the easy way, extract the batch job from
the installation document, supply a proper JOB card, and submit it.

@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 into @q('SYS1.KERMINI').
@i<NOTE:> If the ASCII/EBCDIC translation is not invertible,
Kermit will not and cannot work.

In order to verify the operation of a new version of Kermit-TSO, you may
run it under TEST using the CP parameter.

@Section<What's New>
Below is a list of the TSO-specific features in Version
@value(-tsoversion) of Kermit-TSO 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)
ISPF modification dates are used on
downloads, where available.  Suppression of invalid dates.

Proper selection of default disk unit group for received files.

Support for relative GDG numbers.

Multiple Kermit subcommands specifiable on TSO command line if the
INIT file defines a delimiter.

Kermit status code available to CLIST after each subcommand completes.

Small bug fixes.

@end(enumerate)

@Section(What's Missing)

Work on Kermit-TSO will continue.  Features that need to be
improved or added include:
@begin(itemize)
Intercept ABEND's in TSO commands executed under Kermit.

Implement file archiving.

Add a SET REPEAT subcommand.

Finish SET LINE, so that Kermit-TSO can be used as a local
Kermit, connecting to a remote host over an alternate
communication port.  Add a CONNECT subcommand.

Compute file size for outgoing A-packets and implement the SPACE
subcommand.

Reject files known (via A-packets) to be too big for available storage.

Intercept @i(all) terminal output during protocol mode.

@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).