@Part(MUSICKERMIT,root="kuser") @string(-musicversion="4.3.0") @string(-musicdate="93/9/30") @Chapter @Begin @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 @subheading @begin @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 @subheading @begin @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 @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 features of the MUSIC file system of greatest interest to Kermit users are the format of file specifications (or @i) and the concept of records. The latter is described in the Kermit-370 chapter. The MUSIC @i (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@\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 @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. 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 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 @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 @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 @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, 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 @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 Syntax:@q< SET FILE RECFM @i(option)> This subcommand sets the record format to use for incoming files. Valid @i 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 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 @end @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 and @q: 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 /SYS NOPRINT,REGION=256 /FILE LMOD N($KRM:KERMIT.LMOD) SHR /LOAD XMON KERMIT @end 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 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 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).