@Part(CMSKERMIT,root="kuser") @string(-cmsversion="4.3.0") @string(-cmsdate="93/9/30") @Chapter @Index(CMS) @Begin @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), Clark Frazier (Harvard Bus. Sch.), Bob Bolch and Steve Blankinship (Triangle), Ron Rusnak (U. Chicago), Andr@eac() Pirard (U. Li@egr()ge) @i(Language:)@\IBM/370 Assembler @i(Documentation:)@\John Chandler (CfA) @i(Version:)@\@value(-cmsversion) (@value<-cmsdate>) @i(Date: )@\1993 September @end @subheading @begin @tabclear()@tabset(3.5inches,4.0inches) 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 @subheading @begin @tabclear()@tabset(3.5inches,4.0inches) @Index(Initialization files)@Index(Log files)@Index(LRECL) Global INIT file:@\@q(SYSTEM KERMINI *) User INIT file:@\@q(@i KERMINI *) Debug packet log:@\@q(KER LOG A1) Server reply log:@\@q(KER REPLY A1) Mail command:@\@q[EXEC KERMAIL @i ( @i] Print command:@\@q[EXEC KERMPRT @i ( @i] Submit command:@\@q[EXEC KERMSUB @i ( @i] Maximum packet size:@\1913 (SERIES1), 2030 (TTY) Maximum disk LRECL:@\65535 @end @Index(IBM) @Index(TTY)@Index(Series/1)@Index(CMS) Kermit-CMS 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-CMS is the variant of Kermit-370 that runs under the CMS operating system. The primary documentation for Kermit-CMS 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 CMS operation will be discussed here, @i, command syntax relating to the CMS file system or commands not offered in general by Kermit-370. @Section The features of the CMS 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 CMS @i takes the form @example (often abbreviated FN FT FM). The filename and filetype are one to eight characters each. The filename is the primary identifier for the file, and the type is an indicator which, by convention, tells what kind of file it is. For instance, @q is the source of a Fortran program named TEST. @q(MODULE) is the filetype for executable programs (as distinct from object code, which has a filetype of @q!). Although some operating systems consider the filetype optional, CMS requires a type for each file. Therefore, Kermit-CMS supplies a default type of @qq($) for any received file if no type is provided by the remote system. The same default is used for a missing filename. At the same time, Kermit forces the FN and FT to conform to CMS rules in other respects. The FN and FT may contain, in any order, uppercase letters, digits, and the special characters @qq<$> (dollar sign), @qq<#> (number sign), @qq<@@> (at sign), @qq<+> (plus), @qq<-> (hyphen), @qq<:> (colon), and @qq<_> (underscore). Any other character, if found in the FN or FT, is replaced by an underscore (or converted to uppercase if it is a lowercase letter). Also, both FN and FT are truncated, if necessary, to eight characters. @Index(Home disk) The filemode, which consists of a letter and a number, is similar to a device specification on microcomputer systems: @w<@q(FN FT FM)> would translate to @q in CP/M or MS-DOS if the filemode number is ignored. Indeed, the filemode number is more properly an attribute of a file than part of its name -- no two files can co-exist with names that match in all but the filemode number. Even the filemode letter is not a fixed part of the @i(filespec) because the same mini-disk or Shared File System (SFS) directory could be accessed under a different mode letter. In some ways, the filemode letter is like a disk directory designator, even when it refers to a mini-disk, since many such mini-disks may reside on the same disk drive. For this reason, the Kermit concept of the "working directory" is equated with a particular disk mode letter under Kermit-CMS. The current "working directory" is, thus, the "home" filemode (normally @qq, which is the primary user mini-disk under CMS), and file transfers take place preferentially to and from the "home" disk. If the filemode is omitted from a @i(filespec) when sending, the "home" disk is normally used, but there is an option for using a default of @qq(*) instead. @Index(Search order) In this case, the user's disks are scanned according to the search order and the first occurrence of the file is the one that is sent. If the filemode is omitted from a @i(filespec) when receiving, the "home" disk is used with a filemode number of @qq(1). To provide compatibility with other operating systems, when Kermit-CMS sends a file, it ordinarily makes a file header with only the filename and filetype. It also converts the intervening blank to a period. However, extra information may be added by way of the SET FOREIGN subcommand. @Index(Wildcard) CMS 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. Here are some examples: @Begin(Description,spread 0.5,leftmargin +14, indent -12) @q<* COBOL A>@\All files of type @q (all COBOL source files) on the A disk. @q@\All files whose names start with F. @q<% * B>@\All B-disk files with one-character FN's. @End(Description) CMS files, like those in other IBM 370 systems, are record-oriented (see the introduction to the Kermit-370 chapter). In particular, CMS files are characterized by record format (RECFM), which may be fixed-length or varying-length, and by record length (LRECL). The size of record blocks is irrelevant, however, because CMS performs the blocking and deblocking operations automatically and transparently, including the spanning of records across block boundaries. An important point to note is that records being written to a RECFM V file are not limited in length by the LRECL, but only by the CMS maximum (65535 bytes). Another file system feature of occasional interest is the means of reporting errors. When Kermit-CMS encounters a disk error, it records @Index(Error codes) the function and error code for inclusion in the STATUS report. The explanations can be found in the CMS reference manual under the FSREAD and FSWRITE macros (which correspond to the RDBUF and WRBUF functions). @Index(RDBUF)@Index(WRBUF) @Section @Index(Initialization files) At startup time, Kermit-CMS looks for two initialization files, @qq(SYSTEM KERMINI) and @qq<@i(userid) KERMINI> (where @i(userid) is the user's logon ID). If either of these files exists on more than one disk, it will be read and executed from the first copy in the search order. The file @qq(SYSTEM KERMINI) should be placed on a publicly accessible disk by a systems programmer, preferably the same disk where the Kermit executable module is kept. The file @qq<@i(userid) KERMINI> can be maintained by the user on any convenient disk. One important distinction between Kermit-CMS and other Kermits is that a program running under CMS is unable to interrupt a read on its "console". This means that the CMS variant of Kermit cannot time out after sending 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 most other Kermits. Five CP SET parameters (MSG, IMSG, WNG, ACNT, and TIMER) are set OFF during protocol mode (and restored afterwards) to prevent CP from interrupting any I/O in progress, LINEDIT is set OFF to ensure that all characters are taken literally, and RUN is set ON to ensure that Kermit can recover from accidental attention interrupts. Also, on a @q(TTY) line, the TERMINAL LINESIZE is set OFF to prevent CP from inserting carriage return-linefeed pairs into packets, TERMINAL SCROLL is set to CONT to prevent CP pauses, and the @Index(Translation tables) CMS user terminal translation tables (established via the CMS SET INPUT and OUTPUT commands) are temporarily suppressed for both short and long packet protocols. @Index(Long packets) 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 also after Kermit executes a CP command in server mode. Similarly, normal status is selected when Kermit leaves protocol mode and before Kermit executes a CP command in server 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. @Index(Reconnecting) If, at some installation, Kermit can be run only on @qq(TTY) lines, users will often be forced to disconnect or log off ongoing sessions on fullscreen lines. In general, users may operate through IBM 3270-type terminals and then disconnect in order to reconnect to a line that supports Kermit. In cases like this, users should be warned that reconnecting to a session over a @qq(TTY) line is different from logging on initially over such a line. In particular, the CMS SET parameters AUTOREAD and BLIP and the CP TERMINAL parameter LINESIZE may need to be reset after reconnecting. AUTOREAD should be ON for @qq(TTY) lines and OFF for fullscreen lines; the other two parameters are a matter of taste. A similar warning applies to reconnecting in the opposite direction. @Index(TTY)@Index(Handshake) CMS 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-CMS takes advantage of this option, and it is not, in general, necessary to enable handshaking on the micro Kermit before connecting to CMS. In other words, handshaking should be suppressed for both @qq(TTY) and @Index(Series/1)@qq(SERIES1) devices (the micro Kermit should have HANDSHAKE set OFF, and Kermit-CMS should have HANDSHAKE set to 0). Since the generic Kermit-370 default handshake (XON) is retained in Kermit-CMS, the subcommand @qq(SET HANDSHAKE 0) is a good candidate for inclusion in @q(SYSTEM KERMINI). @Index(Initialization files) @subheading(Kermit under VM/XA and beyond) Recent evolution of IBM's VM operating system has been marked by @Index(VM/XA) sharp discontinuities caused by, among other things, the transition to Extended Architecture (XA) mode. As a result, there are now two CMS variants of Kermit-370, one for the traditional systems and one for VM/XA. The former is now XA-cognizant but not, in IBM's terminology, XA-tolerant. In other words, it will run only in 370 mode or under VM/SP. The latter variant is fully bimodal and will run in 370, XA, or ESA mode under a bimodal (5.5 or 7 or higher) CMS, but will not assemble or run under pre-5.5 releases of CMS. The differences between the two variants are essentially invisible to the user, however, aside from the announcement of the release number when Kermit starts up. Both variants carefully determine whether they are running under VM/XA and, if so, avoid setting the CP parameters ACNT and TIMER, which VM/XA SP 2 does not support. Also, the traditional variant halts gracefully if it finds itself running in XA mode. @subheading(Interactive Operation:) To run Kermit-CMS interactively, invoke the program from CMS by typing @q. When you see the prompt, @example(Kermit-CMS>) 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-CMS Version @value(-cmsversion) (@value<-cmsdate>) Enter ? for a list of valid commands Kermit-CMS>@ux(send foo *) @i(Files with fn FOO are sent) Kermit-CMS>@ux(receive test spss) @i(File is received and called TEST SPSS A1) Kermit-CMS>@ux(exit) @end(example) The prompt string under CMS is truly interactive. In other words, the string (without carriage return or linefeed) appears only when fresh input is needed from the terminal. If, for example, Kermit is invoked after several subcommands have been stacked up, the stack is read and executed before the first prompt appears. @subheading(Command Line Invocation:) Kermit-CMS may also be invoked with command line arguments from CMS. The arguments are interpreted as one or more subcommands 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 set debug on # set file type binary # server) @End(Example) Kermit will exit and return to CMS after completing the specified subcommand or subcommands. Several subcommands may be given on the command line as long as they are separated by the LINEND character, which is number sign in this case. Note that the LINEND delimiter @Index(Delimiter) is a function of CP, rather than Kermit, and applies only to commands entered from the terminal and only when LINEDIT is on or when talking to CP itself. A command line may contain up to 130 characters. @subheading(EXEC Operation:) @Index(EXEC operation) Like other CMS programs, Kermit-CMS may be invoked from a CMS EXEC. Subcommands can be passed to Kermit using the program stack and/or command line arguments. For example, to start up Kermit-CMS 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-CMS server with a three character CRC, include: @Begin(Example) @ux(&STACK set block 3) @ux(&STACK server) @ux(KERMIT) @End(Example) 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 or program stack. EXEC's may be executed from Kermit, either directly or from a TAKE file, and Kermit subcommands, in turn, may be issued from EXEC's as long as Kermit is active. See the TAKE subcommand for more details. @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. Also, commands other than CP commands run in a special environment with RUN ON, TIMER OFF, and so forth. Another difference is that Kermit intercepts all SVC instructions in order to catch console I/O and transmit the data to the local Kermit as text packets. However, some CMS system or user commands may issue console I/O directly to CP, so that some messages never appear to the local Kermit (except, perhaps, as bad packets). For non-TTY terminals, such messages are stacked up in the console output queue and appear all at once when Kermit returns from server mode. However, some system configurations, especially those including VTAM, are incapable of resuming Kermit protocol transmission after interruption by direct console I/O, so such commands should generally be avoided. @Section Kermit-CMS supports all the subcommands described in the Kermit-370 chapter. In addition, there are two more, both of which can be issued as remote Kermit commands when Kermit-CMS is in server mode. The first is @qq(CMS), which is just a synonym for the generic subcommand @qq(HOST). The second is @qq(CP), which specifically issues a command to CP. In most circumstances, the latter is not needed, since CMS will pass along CP commands to CP. This section concentrates on the subcommands that have special form or meaning for Kermit-CMS. These are ordered alphabetically. See the chapter on Kermit-370 for further details. @Heading(The CP and CMS Subcommands) Syntax:@q< CP @i(or) CMS @i(text of command)> @Index(KERMBOOT)@Index(User area)@Index(File management) Although Kermit-CMS does not have a full set of its own subcommands for managing local files, it provides those services through the operating system. You can issue any CP or CMS command, but if Kermit-CMS has been invoked as a normal user-area program, rather than as a high-memory "resident" program or nucleus extension, other user-area CMS commands (such as COPYFILE) are illegal. Even then, you can list, type, rename or delete files, send messages, and so on. The CMS subcommand under Kermit is synonymous with the HOST subcommand. @Heading(The CWD Subcommand) @Index(Home disk)@Index(CWD) Syntax:@q< CWD @i(letter)> The CWD (Change Working Directory) subcommand establishes a new default ("home") CMS disk. @i(letter) may be the mode letter of any accessed disk. Subsequent file transfers take place preferentially to and from the default disk. The initial home disk is @qq(A). Note: setting the home disk in Kermit has no effect on the CMS search order. @Index(Search order) @Heading(The DIRECTORY Subcommand) @Index(DIRECTORY) Syntax:@q< DIRECTORY [@i(filespec)]> Under Kermit-CMS, the DIRECTORY subcommand is identical to the CMS LISTFILE command. @Heading @Index(GET) Syntax:@q< GET [@i(foreign-filespec) [@i(filespec)]]> The GET subcommand tells Kermit to request a file or file group from the other system, which must have a Kermit running in server mode. The syntax is complicated by the allowance of two forms for the @i(foreign-filespec), just as in the SEND subcommand. Here the parsing is based on the number of "words" (blank-delimited strings) in the subcommand argument, which can be anything from one to five. If the number is anything but four, the interpretation is unambiguous, but when there are four words, the first word plays the key role. If it has more than eight characters or contains a @qq(.) or @qq(/), it is assumed to be the whole @i(foreign-filespec); otherwise, it is assumed to be the first of two words that, when joined by a @qq(.), make up the @i(filespec) on the other system. If this subcommand is issued without any arguments at all, Kermit-CMS will prompt the user for both foreign and native @i. @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 format of @i(filespec) is @q(fn [ft [fm]]). The default filetype is @qq(TAKE), and the default filemode is that of the "home" disk. See the CWD subcommand. @Heading(The HELP Subcommand) @Index(HELP) Syntax:@q< HELP @i(subcom)> This subcommand displays the relevant part of the Kermit help file when the latter is a partitioned data set. Kermit verifies that the argument is a valid Kermit subcommand (or a non-ambiguous abbreviation) and then displays the corresponding member of the PDS. For the SET subcommand, individual parameters may also be specified, as in @example If no subcommand name is included, Kermit displays the member that gives an overview of Kermit operation. Kermit looks for a help file with a filename matching the Kermit command itself, but will settle for one with a filename of KERMIT if necessary. Thus, the response to the HELP subcommand may depend upon which Kermit module is invoked. The choice of whether to format the help file as a PDS is an option at installation time. If the installer has chosen to leave it as an ordinary sequential file, or if no help file has been installed recently, Kermit will fall back on the old behavior of the HELP subcommand: it will issue the CMS HELP command for Kermit and therefore display the entire file. Since the help file is rather long, this subcommand is not recommended for users with line-mode terminals, unless the help file is installed as a PDS. See the installation guide for more details about the help files. @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 must issue the corresponding SEND subcommand to the other Kermit. The format of @i(filespec) is: @example If the optional @i(filespec) is omitted, Kermit-CMS will use the name(s) provided by the other Kermit. If that name is not a legal CMS file name, Kermit-CMS will delete excess characters and will change illegal characters to underscores. A @i(filespec) in the subcommand indicates what name the incoming file should be given. The @i(filespec) may include a filemode to designate the destination disk. If none is provided, the file will be saved on the "home" disk with filemode number @qq(1). If you want to use the same name but a different filemode, specify @w(@qq<= = FM>). 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 "home" disk. If, however, @qq<= = FM> is used, all files will be placed onto the specified disk. For purposes of truncation and folding, the maximum record length for a received file is 65535 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-CMS 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 filetype to six 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 CMS to the Kermit on the other system. @i(filespec) takes the form: @example(filename filetype [filemode]) or @example(fn.ft.[fm]) but the filemode is optional only if the @i(foreign-filespec) is omitted. The "dotted" notation is interpreted by changing up to two dots into spaces, so only the normal CMS-style form is "real" as far as Kermit is concerned. For details on the @i(options), see the description of SEND in the Kermit-370 chapter. Note that no blanks may intervene between the CMS @i(filespec) and the @i(options), even though the @i(filespec) itself has imbedded blanks (either explicitly or implicitly through the "dotted" notation). @Index(Wildcards) @Index(Search order) The @i(filespec) may contain the wildcard characters @qq<*> or @qq<%>. If it does, then all matching files will be sent. If, however, a file exists by the same name on more than one disk, only the first one Kermit-CMS encounters, according to the disk search order, is sent. See also the CWD subcommand. The @i(foreign-filespec), if any, is used for the file header of the outgoing file, replacing the usual filename.filetype copied from the CMS @i(filespec). It may take one of two forms: @example(filename filetype) or @example(arbitrary-string) 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). However, in the two-token form of the @i(foreign-filespec) either the name or type may be an Equals sign @qq(=) to signify that the corresponding CMS name or type is to be retained in the file header. In that case, the partial renaming carries through an entire group of files. It is the user's responsibility to prevent such partial renaming from sending duplicate file headers within a file group. If both @i(filespecs) are omitted for this subcommand, Kermit will prompt separately for each, and the respective syntaxes are exactly as described above, except the filemode is optional even if a @i(foreign-filespec) is to be supplied. 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-CMS downloads the file. In order to treat such blanks as significant, you must convert the record format to V, for example, by using COPYFILE with the "RECFM V" option. Note: you must not use XEDIT for such a conversion, since it also strips trailing blanks from files with RECFM 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-CMS, but not in Kermit-370 in general: @Begin(Format,spread 0) @tabclear()@tabset(2.0inches) DESTINATION@\"Home" disk. FILE LRECL@\Logical Record length for incoming file. RECFM@\Record format for incoming files. SEARCH-ALL@\Determine the default disk search scope. @End(format) @Subheading @Index(Home disk) Syntax:@q< SET DESTINATION @i(letter)> This subcommand is equivalent to the CWD subcommand (@i). @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 65535 (64K-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 sets the record format to use for incoming files. Valid @i