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

Text File | 2020-01-01 | 20KB | 569 lines

@Part(MUSICKERMIT,root="kuser")
@string(-musicversion="4.3.0")
@string(-musicdate="93/9/30")
@Chapter<IBM MUSIC/SP KERMIT>
@Begin<Description,Leftmargin +15,Indent -15,spread 0>
@i(Program:)@\John Chandler (Harvard/Smithsonian Center for
Astrophysics); contributions from
Pierre Goyette (McGill U),
Va@ccd()e Kundak@ccd()i and
Daphne Tzoar (Columbia U),
Bob Shields (U. Maryland),
Greg Small (UC Berkeley), Clark Frazier (Harvard Bus. Sch.),
Bob Bolch and Steve Blankinship (Triangle),
Andr@eac() Pirard (U. Li@egr()ge)

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

@i(Documentation:)@\Pierre Goyette

@i(Version:)@\@value(-musicversion) (@value<-musicdate>)

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

@subheading<Kermit-MUSIC 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<MUSIC Specifics of Kermit-370:>
@begin<format,leftmargin +2,above 1,below 1>
@tabclear()@tabset(3.5inches,4.0inches)
Global INIT file:@\@q(SYSTEM.KERMINI)
User INIT file:@\@q(KERMIT.INI)
Debug packet log:@\@q(KERMIT.LOG)
Server reply log:@\@q(KERMIT.REPLY)
Mail command:@\@q(KERMAIL) (not supported)
Print command:@\@q(KERMPRT) (not supported)
Submit command:@\@q(KERMSUB) (not supported)
Maximum packet size:@\1913 (7171), 230 (TTY)
Maximum disk LRECL:@\32767
@end<format>

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

@Section<The MUSIC/SP File System>

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

The MUSIC @i<filespec> (called a Save File) takes the form
@example<[code:]filename>
The filename can be up to 17 characters in length and consists of one or
more substrings joined by periods.  The substrings can contain
any of the following characters:
@example(A through Z, 0 through 9, national characters # $ @@)
The only restriction is that the first substring must start with a
letter or a national character.
You may also prefix the filename with a 4-digit code if you
have enough privileges.
@Index(Default Code)
By default, the "working directory" will be set to the your
signon code.
All files on this code can be accessed directly.
If you have enough privileges and wish to transfer files
to or from a MUSIC code other than your signon code, you may
change the "working directory" to the new code.

@Index(Wildcards)
MUSIC/SP 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) from the current position to the end of the field;
a @qq<?> matches any single character.
It is important to remember that the period is part of the filename.
Unlike a PC, the file specification @qq<*> will
match all filenames.
Here are some examples:

@Begin(Description,spread 0.5,leftmargin +14, indent -12)
@q<*.COBOL>@\All files of that end with @q<.COBOL>

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

@q<?>@\All files with one-character filename.
@End(Description)

MUSIC files, like those in other IBM 370 systems, are record-oriented
(see the introduction to the Kermit-370 chapter).
In particular, MUSIC files are characterized by record
format (RECFM), which may be fixed-length or varying-length,
and by maximum record length (LRECL).
The size of record blocks is irrelevant, however,
because MUSIC performs the blocking and deblocking operations
automatically and transparently, including the spanning of records
across block boundaries.
Records in MUSIC files may be up to 32767 bytes long.
A third record format, namely, undefined-length, is possible in MUSIC,
but is rarely used and is not supported by Kermit-MUSIC at present.

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

Another file system feature of occasional interest is the means of
reporting errors.
When Kermit-MUSIC encounters a disk error, it attempts to prepare
an explanatory message for inclusion in the STATUS report.
The explanations can be found in the MUSIC reference manual under the
MFIO Error Codes section.
@Index(Error codes)

@section<Program Operation>

@Index(Initialization files)
At startup time, Kermit-MUSIC looks for two initialization
files, @q(*COM:SYSTEM.KERMINI) and @q(KERMIT.INI).
If either of or both of these files exist,
they will be read and executed.
If they do not exist on your code, Kermit will still attempt to locate
the public verion of the system file.
The file @q(SYSTEM.KERMINI) should be saved as a PUBLIC file
by a systems programmer, preferably the same code where
the Kermit executable module is kept.
The file @q(KERMIT.INI) can be maintained by the user on any code.

One important distinction between Kermit-MUSIC and other Kermits
is that a program running under MUSIC/SP is unable to
interrupt a read on the terminal
if you are connected through a 7171 or
Series/1 protocol converter.
This means that the MUSIC variant of Kermit cannot
time out after sending a packet on such devices.
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 most other
Kermits.

@Index(TTY)@Index(Flow control)@Index(Handshake)
If you are connecting to MUSIC through a 7171 or @q(Series/1)
protocol converter, then no handshaking is required since
Kermit-MUSIC can control the data sent to the micro Kermit.
But if you are connected as a @qq(TTY) terminal (through a 370x
type line), then you must enable handshaking on the micro Kermit.
This is because the MUSIC/SP system will add an XON (X'11')
character to the end of every packet sent.
The micro Kermit must not reply with the next packet before
the XON character is received.
Usually the command @qq(SET HANDSHAKE XON) or @qq(SET HANDSHAKE 17)
on the micro Kermit will do this.

@subheading(Interactive Operation:)

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

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

  @i(Files with prefix FOO. are sent)

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

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

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

@subheading(Command Line Invocation:)

Kermit-MUSIC may also be invoked with a command line argument from MUSIC.
The argument is interpreted as a subcommand to be executed
by Kermit after completion of the initialization.
For instance:
@Begin(Example,below 0.5)
@ux(KERMIT send test.fortran)
@End(Example)
or
@Begin(Example,above 0.5)
@ux(KERMIT server)
@End(Example)

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

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

@Section<Kermit-MUSIC Subcommands>

Kermit-MUSIC supports all the subcommands described in the Kermit-370
chapter, plus one more: @qq(MUSIC), which is a synonym for the generic
subcommand @qq(HOST).
This section concentrates on
the subcommands that have special form or meaning for Kermit-MUSIC.
These are ordered alphabetically.
See the chapter on Kermit-370 for further details.

@Heading(The CWD Subcommand)
@Index(Default Code)@Index(CWD)

Syntax:@q< CWD @i(code)>

The CWD (Change Working Directory)
subcommand establishes a new default code.
@i(code) may be any valid 4-digit MUSIC code.
Subsequent file transfers take place preferentially to
and from the default code.
The initial code is the user's signon code.

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

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

Under Kermit-MUSIC, the DIRECTORY subcommand is similar
to the MUSIC LIBRARY command.
DIRECTORY will also display the number of lines in a file.

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

Syntax:@q< HELP>

This subcommand displays information on the use of Kermit-MUSIC.

@Heading(The MUSIC Subcommand)

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

Currently, MUSIC does not support the execution of host commands
under Kermit-MUSIC.
However, the MUSIC commands LIBRARY, PURGE, RENAME, COPY, and LIST
are simulated by Kermit itself, thus providing a set of
subcommands for managing
local files.  The subcommand MUSIC is synonymous with the generic
subcommand HOST.

@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 should then issue a SEND subcommand to the other Kermit.

If the optional @i(filespec) is omitted, Kermit-MUSIC will use the
name(s) provided by the other Kermit.
If that name is not a legal MUSIC file name, Kermit-MUSIC will
delete excess characters and will change illegal characters to
dollar signs.
A @i(filespec) in the subcommand indicates what name the incoming file
should be given.
Wildcards may not be used.
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 on the default code.

For purposes of folding and truncation, the maximum record length for
a received file is 32767 if RECFM is V and "LRECL" if RECFM is F.
@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-MUSIC 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 begins by truncating the filename to fifteen
characters if necessary, and then appending @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.

@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 MUSIC
to the Kermit on the other system.
Kermit-MUSIC will remove any code prefix for the file header of the
outgoing file.
@Index(Wildcards)
The @i(filespec) may contain the wildcard characters @qq<*> or @qq<?>.
If it does, then all matching
files will be sent.  For details on the @i(options), see the chapter on
Kermit-370.  There must be no blanks between the @i(filespec) and the
@i(options), if any.

The @i(foreign-filespec), if any, is used for the file header of the
outgoing file, replacing the usual filename copied from the
MUSIC @i(filespec).
If wildcards are present in the @i(filespec),
then no @i(foreign-filespec) should be specified.

@Indexsecondary(primary="Blanks",secondary="preserving trailing")
Trailing blanks in a text file with RECFM F are deemed superfluous and
are stripped off when Kermit-MUSIC downloads the file.  In order to treat
such blanks as significant, you must convert the record format to V.

@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-MUSIC,
but not in Kermit-370 in general:
@Begin(Format,spread 0)
@tabclear()@tabset(2.0inches)
DELIM@\Line delimiter for entering multiple commands.
DESTINATION@\Default Code.
FILE
  LRECL@\Logical Record length for incoming file.
  RECFM@\Record format for incoming files.
@End(format)

@Subheading(SET DELIM)

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

@Index(Line delimiter)
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 DESTINATION>
@Index(Default Code)

Syntax:@q< SET DESTINATION @i(code)>

This subcommand is equivalent to the CWD subcommand (@i[q.v.]).

@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.
The default is 80.

@Subheading<SET FILE RECFM>

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

This subcommand sets the record format to use for incoming files.
Valid @i<options> are "Fixed" and "Variable" (the default).
Fixed-format records are padded, folded, or truncated, as needed,
to the current LRECL.  Note: these two formats correspond to FC and VC
in standard MUSIC nomenclature.  MUSIC formats F, V, and U are not
supported.

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

Syntax:@q< SPACE>

This subcommand displays the storage allocation on the default code.
The available space is calculated by subtracting the current allocated
space from the total space available to the user's code.

@Section<How to build an executable version of Kermit-MUSIC>

Before attempting to build Kermit-MUSIC, look in the
Kermit distribution under IKMKER 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 and more detailed than what you see here.

Kermit-MUSIC consists at present of a few small jobs that (a)
build GUPI (Generic Update Program), (b) use
GUPI to apply the current fixes to the base code, and (c)
assemble and link
the updated Kermit source.
The source for Kermit and GUPI itself is in many pieces,
some generic for Kermit-370 and some specific to MUSIC.
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 can be applied to the source.

To create a runnable version:

@begin<format,leftmargin +2,above 1,below 1>
@end<format>
@tabclear()@tabset(3.5inches,4.0inches)

@begin(enumerate,spread 0.5)
Collect the following @qq(ASM) files from the Kermit distribution onto
the code $KRM with @q<RECFM FC> and @q<LRECL 80>: IK0DOC, IK0MAC,
IKMMAC, IK0DEF, IK0MAI, IK0COM, IK0CMD, optionally IK0KAN,
IKMUTL, IK0PRO, IK0GUP,
and IKMGUP.
The files must have an extension of ".S".

Assemble and link the Generic Update Program GUPI, producing
@q($KRM:GUPI.LMOD).
Before assembling the GUPI program, you must change the IK0GUP module.
Edit the file $KRM:IK0GUP.S and convert all COPY pseudo-instructions
into macro invocations.
This is easily achieved by removing the word "COPY"
from in front of the copy block's name.
There are only 5 occurences of this and they are all in column 10.
The source for GUPI consists of the combination
IK0MAC, IKMMAC, IKMGUP, and IK0GUP.

Build the base Kermit source so that you can apply the
modifications to it.
Merge the source files in the order
IK0DOC, IK0MAC, IKMMAC, IK0DEF, IK0MAI, IK0COM, IK0CMD, IKMUTL, IK0PRO,
and save the result as @q($KRM:KERMIT.BASE.S).

Apply the updates using GUPI.  Note: this operation requires a region
of at least 1024K.
The following command will apply the fixes to the source
module $KRM:KERMIT.BASE.S using the update file $KRM:IKMKER.UPD
and save the updated source in $KRM:KERMIT.S.
@example(GUPI $KRM:KERMIT.BASE.S $KRM:IKMKER.UPD $KRM:KERMIT.S)

Assemble the Kermit source and
link the object deck together with
MATCH and MFINDX to produce @q($KRM:KERMIT.LMOD).

Save the following jobstream in the file $KRM:KERMIT
This will execute the KERMIT program with the proper system
parameters.
@begin<format,leftmargin +2,above 1,below 1>
/SYS NOPRINT,REGION=256
/FILE LMOD N($KRM:KERMIT.LMOD) SHR
/LOAD XMON
KERMIT
@end<format>

Kermit-MUSIC requries the LSCAN privilege since it does a
save library scan directly.
You must modify either the system module LOOKUP or the macro
invoked by LOOKUP called $MCM:USERTBL.M.
Add the line
@example<FILNAM '$KRM:KERMIT',(LSCAN,0)>
to either of the two files.
Reassemble the module LOOKUP and make sure that the new
object deck is used when rebuilding the nucleus.
If you do not give Kermit this privilege, the program will
abend on user codes that do not have LSCAN.
@end(enumerate)

@Index(Initialization files)@Index(Translation)
Since Kermit-MUSIC drives the I/O directly for both @qq(TTY) and
@qq(SERIES1) devices, your site's
ASCII/EBCDIC translation tables will not affect Kermit-MUSIC
in file transfer mode.

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

@begin(enumerate,spread 0.5)
Multiple Kermit subcommands specifiable on the MUSIC command line if
the INIT file defines a delimiter.

Support for time tags for files being sent.

@end(enumerate)

@Section(What's Missing)

Work on Kermit-MUSIC will continue.  Features that need to be
improved or added include:
@begin(itemize)
Allow timeouts so Kermit-MUSIC does not wait forever if a packet does
not arrive in a timely fashion.  This is not possible under MUSIC at
present for I/O through a protocol converter.

Implement file archiving.

Support execution of Music commands from Kermit or the remote
Kermit.

Add a SET REPEAT subcommand.

Support subdirectories and userids longer than four characters.  There
is already an update for this support, but it requires MUSIC 2.4 and
has not been tested yet.  See the "beware" file for the latest
information.

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