@Part(CICSKERMIT,root="kuser") @string(-cicsversion="4.3.0") @string(-cicsdate="93/9/30") @Chapter @Index(CICS) @Begin @i(Program:)@\John Chandler (Harvard/Smithsonian Center for Astrophysics); contributions from Va@ccd()e Kundak@ccd()i and Daphne Tzoar (Columbia U), Brian Lesser (U. New Brunswick), Carrie Ledford (Miami U.), Jeff Huestis (Washington U.), Wayne Mery (Lehigh U.), ICSTI, Pierre Goyette (McGill U.), Clark Frazier (Harvard Bus. Sch.), Bob Bolch (Triangle), Andr@eac() Pirard (U. Li@egr()ge) @i(Language:)@\IBM/370 Assembler @i(Documentation:)@\John Chandler (CfA) @i(Version:)@\@value(-cicsversion) (@value<-cicsdate>) @i(Date: )@\1993 September @end @subheading @begin @tabclear()@tabset(3.2inches,3.7inches) Local operation:@\Yes Remote operation:@\Yes Transfers text files:@\Yes Transfers binary files:@\Yes Wildcard send:@\Yes @q(^X/^Z) interruption:@\Yes (through micro) Filename collision avoidance:@\Yes Can time out:@\No 8th-bit prefixing:@\Yes Repeat count prefixing:@\Yes Alternate block checks:@\Yes Terminal emulation:@\No Communication settings:@\No Transmit BREAK:@\No Packet logging:@\Yes Transaction logging:@\Yes Session logging:@\No Raw transmit:@\Yes (no prompts) Sliding window:@\No Long packets:@\Yes Act as server:@\Yes Talk to server:@\Yes Advanced server functions:@\Yes Advanced commands for servers:@\Yes Local file management:@\Yes Handle Attribute Packets:@\Yes Command/init files:@\Yes Command macros:@\No @end @subheading @begin @tabclear()@tabset(3.2inches,3.7inches) @Index(Initialization files)@Index(Log files)@Index(LRECL) Global INIT file:@\@q(KSYS.TD) User INIT file:@\@q(KINIT.TAKE) Debug packet log:@\@q(KLOG)@i(term)@q(.TS) Server reply log:@\@q(KREP)@i(term)@q(.TS) Mail command:@\@q[KERMAIL R(_...) @i LIST(@i)] Print command:@\@q[KERMPRT R(_...) @i OPTIONS(@i)] Submit command:@\@q[KERMSUB R(_...) @i OPTIONS(@i)] Maximum packet size:@\1913 (SERIES1), 1024 (TTY) Maximum disk LRECL:@\32767 @end @Index(IBM) @Index(TTY)@Index(Series/1)@Index(CICS) Kermit-CICS is a member of the generic Kermit-370 family and shares most of the features and capabilities of the group. As its name implies, Kermit-CICS is the variant of Kermit-370 that runs under CICS. As much as possible, it is designed to be independent of the operating system that runs CICS, but only on IBM-370-compatible machines. The primary documentation for Kermit-CICS is actually the chapter on Kermit-370 (entitled IBM 370 Kermit), which describes general properties; the present chapter assumes the reader is familiar with that material. Only the details specific to CICS operation will be discussed here, @i, command syntax relating to CICS data objects or commands not offered in general by Kermit-370. @Section Unlike other environments for Kermit-370, CICS is not really an operating system and does not have anything that can be called a file system. Nonetheless, CICS supports a variety of data objects that can be called "files". Moreover, Kermit-CICS itself maintains a Kermit-only collection of storage organized into user directories. Furthermore, Kermit simulates a set of CICS file-maintenance commands: DIRECTORY, TYPE, COPY, and DELETE. Thus, for the purposes of Kermit, we may speak of a "CICS file system". The features of the file system of greatest interest to Kermit users are the supported types of data object, the format of file specifications (or @i), and the concept of records. The latter is described in the Kermit-370 chapter. @seealso(primary="Queues",other="TD, TS") As of this writing, Kermit-CICS supports three different types of data object: temporary storage (TS) queues, transient data (TD) queues, and Kermit-managed directory members. The first two are standard CICS objects while the third is a special kind of object designed for small, personalized, infrequently used, quasi-permanent files, such as on-line help files and individual Kermit initialization files. @Index(Initialization files) In principle, Kermit also supports three other types, but the support is provided through an interface to external programs, only one of which has yet been written. These other types are non-TD pipes, spool files, and native OS data sets. No external drivers are included in the standard distribution. The CICS @i takes one of two forms: @Begin(example,below 0.5) [fileclass/]filename[.filetype] @End(example) or @Begin(example,above 0.5) 'qualified.file.name @End(example) @Index(Qualified File Names)@Index(Fileclass) The first form represents a "normal" CICS data object while the second is the means of specifying a data object in the native operating system that supports CICS. In the first form, the optional fileclass is a string of up to eight characters. The filename is the primary identifier for the file, but the formats of both the fileclass and the filename depend on the filetype. The latter must be one of a small set of supported types: PGM, SPOOL, TAKE, TD, TS, TSAUX or TSMAIN. The last two are alternates for TS and are intended for specifying the type of storage desired for a new TS queue. The default is Auxiliary storage. Any of the three types will serve equally well@Index(TS queues) to identify a queue that already exists. With filetypes @qq and @qq, the fileclass is meaningless but may be specified anyway. Kermit-CICS supplies a default filetype of @qq for any received file if no filetype is provided by the remote system. If no filename is supplied either, Kermit invents one by concatenating the letter @qq, a three-digit number, and the user's four-character CICS terminal id. In any case, Kermit forces the filename @Index(TD queues) to conform to CICS rules by truncating it, if necessary, to eight characters (four for a TD queue). Also, Kermit converts any lower-case letters to upper case. Kermit-CICS supports a special file naming construct for TS queues. If the string ";;;;" appears in the name given to Kermit, that is replaced by the terminal id of the current session. This is useful for avoiding name conflicts when two or more users are running Kermit at the same time. The special string may also be set to any other desired four-byte string, simply by changing the definition of variable symbol &KTRMS in the source code. The string should not contain any reserved characters, such as Asterisk, Percent, Period, Slash, Less-than, Comma, or Blank, and should not begin with quasi-reserved characters such as Apostrophe or Question mark. Filetype @qq refers to any kind of transient data queue. TD queues are much like files in a true file system, except for two important features: TD queues are permanent data objects (despite the transience of the data), and there is no straightforward means of determining how much storage a given TD queue occupies. These two features combine to defeat the provisions made by Kermit for handling filename collision @Index(Filename collision) (see SET FILE COLLISION in the Kermit-370 chapter). Intra-partition queues, at least, have an associated number of queued records, but output extra-partition queues do not and therefore must always be presumed to contain data, @i(i.e.), to exist in a real sense. Of course, all TD queues exist insofar as they are pre-defined in the CICS DCT, but the intent of the default filename collision handling is to protect data from erasure. Thus, Kermit-CICS will not normally write an uploaded file into an output extra-partition TD queue at all. Because of the filename collision, the file would be written to a TS queue, according to the algorithm described under SET FILE COLLISION in this chapter. The only way of uploading to a TD queue is to change the COLLISION setting to APPEND or OVERWRITE. Another effect of the non-dynamic quality of TD queues is that Kermit, when presented with an undefined TD queue name for an uploaded file, cannot create the missing queue. Thus, it must behave as if there were a filename collision and find an alternate place to store the file. However, if COLLISION were not set to RENAME, Kermit would not even check for collisions, but would simply attempt to write to the undefined queue and stop the file transfer because of the resulting I/O error. Because TD queues are system-wide resources available to all users, data could be destroyed or confused if more than one user attempted to read or write the same queue at once. To prevent that, Kermit-CICS uses the CICS ENQUEUE command with a resource name equal to the name of the TD queue and gives up if the resource is busy for three consecutive seconds of waiting. @Index(Pipes) Filetype @qq specifies a pipe managed by a CICS program whose name is the filename. Such a program is invoked to open the pipe, then successively to read or write, and finally to close the pipe. A single program can be written to manage both input and output, even perhaps both at the same time. The optional fileclass in the @i(filespec) may be used by the program for any desired purpose. See the installation guide for details about writing such a program. @Index(Spool files) Filetype @qq represents a special type of pipe. The filename gives the name of the desired spool file, and the program to be invoked is IKXDYNAL. The optional fileclass is the spool class. @Index(Fileclass) @Index(Directories)@Index(Userids)@Index(TAKE files)@Index(TAKE) Filetype @qq denotes a Kermit-managed directory member. Note that this filetype is not reserved for TAKE files, even though directory storage is the logical place to keep most TAKE files. Throughout this chapter, as in the other chapters on Kermit-370, the term "TAKE file" will always mean a file containing Kermit subcommands suitable for execution via the TAKE subcommand, regardless of the filetype. Data objects with filetype @qq will be called "directory members", regardless of the purpose of those objects. The fileclass, if any, specifies the directory name (either @qq<0000> to select the common directory or a userid to select a personal directory). The default directory name is @qq<*>, which represents the userid of the current session. Userids in Kermit-CICS are determined according to an algorithm chosen as part of the installation process (@i, the CICS operator id). The filename of a member specifies that member within the given directory. Obviously, distinct members having the same filename may exist simultaneously in different directories. In short, this Kermit-managed storage comes close to being a real file system, aside from the limitation to the single filetype @qq. For this reason, the Kermit concept of the "working directory" is implemented in Kermit-CICS primarily as the current directory associated with filetype @qq. However, there is an alternate use of the "working directory" concept, namely, to specify a default @Index(Qualified File Names) prefix for Qualified File Names (QFN's). Selecting a "directory" name that begins with an apostrophe establishes that string as a QFN prefix for subsequent @i(filespecs) given to Kermit-CICS. See the description of the CWD subcommand in this chapter for more details about "working directories". @Index(Quotas) Despite the apparent convenience and privacy of Kermit directory members, these objects are not intended for routine file transfers, but only for small, quasi-permanent files. The implementation makes use of a VSAM KSDS for storing the members and is geared entirely toward simplicity, rather than efficiency. Thus, each record of a directory member is a separate record in the KSDS identified by a human-readable 17-byte key consisting of the directory name, the member name, and the record number. Reading or writing a large member could tie up significant amounts of system resources. To ensure that users respect the restriction on directory members, Kermit imposes a two-tiered quota on each directory. If the first limit is exceeded, no further members may be created in the offending directory until enough space has been freed by deleting members. If the second limit is exceeded, Kermit will stop writing to the new member immediately and will give a "disk full" error indication. These limits apply equally to all directories. The limits in the standard version of Kermit-CICS are 100,000 and 150,000 bytes, respectively, but each installation is free to establish its own limits. To provide compatibility with other operating systems, when Kermit-CICS sends a file, it ordinarily makes a file header with only the filename and filetype. However, extra information may be added by way of the SET FOREIGN subcommand. In the case of a QFN, the last two tokens of the name are used for sending. @Index(Wildcards) CICS allows a group of files to be specified in a single @i(filespec) by including the special "wildcard" characters @qq<*> and @qq<%>. A @qq<*> matches any string of characters (even a null string) within the filename; a @qq<%> matches any single character. Here are some examples: @Begin(Description,spread 0.5,leftmargin +18, indent -16) @q<*.TS>@\All TS queues currently in CICS. @q@\All TD queues whose names start with F. @q<0000/%%.TAKE>@\All system directory members with two-character names. @End(Description) CICS files, like those in other IBM 370 systems, are record-oriented (see the introduction to the Kermit-370 chapter). In particular, CICS files are characterized by record format (RECFM), which may be fixed-length or varying-length, and by record length (LRECL). Extra-partition TD queues are the only currently supported type of file that may have fixed-length records. An important point to note is that records being written to a RECFM V data object are generally not limited in length by the current LRECL, but only by the CICS Kermit maximum (32767 bytes). This is true of directory members and TS and intra-partition TD queues, but other limits may apply to other data objects. When sending files, Kermit-CICS includes a date/time attribute if available. However, any date attribute of a file received into CICS is merely checked for validity and then discarded. Another file system feature of occasional interest is the means of reporting errors. When Kermit-CICS encounters a file I/O error, it records @Index(Error codes) the function name and the error code from EIBRCODE for inclusion in the STATUS report. The explanations of EIBRCODE can be found in Appendix A of the CICS command-level reference manual. In some cases, however, Kermit will report an error code for an operation not directly performed by CICS. These extra codes have not been defined, since they would result from operations on as-yet-unsupported filetypes. @Section @Index(Initialization files) Kermit-CICS is a conversational transaction. Thus, when it starts up, it allocates and initializes buffers and storage arrays. In addition, to provide for site- and user-specific environments, it looks for two initialization files, @q(KSYS.TD) and @q(KINIT.TAKE). The file @q(KSYS.TD) is a read-only, extra-partition TD queue maintained by a systems programmer. The file @q(KINIT.TAKE) resides in the user's Kermit directory and must be maintained by the user. For example, the file could be changed by downloading it to a microcomputer, editing it there, and uploading it again (making sure to set FILE COLLISION to OVERWRITE). Alternatively, if tools exist for editing TS queues within CICS, the file could be copied to a TS queue, edited, and copied back. Kermit-CICS cannot time out while waiting for a packet. The only way to time out is from the other side: typing a carriage return to the local Kermit causing it to retransmit its last packet, or an automatic timeout as provided by many Kermits. @Index(TTY)@Index(Handshake) CICS is different from some other IBM mainframe systems in that it allows a program to take control of prompting and synchronization on @qq lines. Kermit-CICS takes advantage of this option, and it is not necessary to enable handshaking on the micro Kermit before connecting to CICS. Thus, the micro Kermit should have HANDSHAKE set OFF, and Kermit-CICS should have HANDSHAKE set to 0. Since the generic Kermit-370 default handshake (XON) is retained in Kermit-CICS, the subcommand @qq is a good candidate for inclusion in @q(KSYS.TD). @Index(Initialization files) @subheading(Interactive Operation:) To run Kermit-CICS interactively, invoke the program from CICS by typing @q. When you see the prompt, @example(Kermit-CICS>) you may type a Kermit subcommand. When the subcommand completes, Kermit issues another prompt. The cycle repeats until you exit from the program. For example: @Begin(Example) .@ux(KERMIT) Kermit-CICS Version @value(-cicsversion) (@value<-cicsdate>) Enter ? for a list of valid commands Kermit-CICS>@ux(send foo*.ts) @i(TS queues with names beginning FOO are sent) Kermit-CICS>@ux(receive test.td) @i(File is received and stored in the TD queue called TEST) Kermit-CICS>@ux(exit) @end(example) In this example, which assumes a linemode session with a system prompt of @qq<.>, the text entered by the user is displayed along with messages and prompts. The annotations are indented, but the distinction between user text and Kermit text may depend upon how this document is printed. Normally, the text entered by the user is underscored, and the messages and prompts are not. The prompt string from Kermit-CICS is truly interactive. In other words, the prompt appears only when fresh input is needed from the terminal. If, for example, multiple Kermit subcommands have been stacked up using the delimiter feature, the stack is read and executed before the next prompt appears. @subheading(Command Line Invocation:) Kermit-CICS may be invoked with command-line arguments from CICS. The arguments (taken to be the string beginning after the first blank after the four-letter transaction id @qq) are interpreted as one or more subcommands to be executed by Kermit after completion of the initialization. Thus, the command may be abbreviated as @qq or @qq at the user's discretion. For instance: @Begin(Example) .@ux(KERMIT send test.take) @End(Example) Kermit will exit and return to CICS after completing the specified subcommand. A command line may contain up to 256 characters. Note that the subcommand delimiter is initially disabled in Kermit-CICS, but it can be enabled in either of the initialization files and can then be used for entering multiple subcommands on the command line. @subheading(Non-interactive Operation:) @Index(Automatic operation) Kermit-CICS is both a CICS transaction named KERM and a CICS program named KERMIT. As with any transaction, it may be started automatically as well as by hand, but it will then read the terminal expecting to find the command-line arguments (if any) for execution as a Kermit subcommand. In addition, Kermit may be invoked via the CICS LINK and XCTL commands and (optionally) supplied with a COMMAREA. If there is no COMMAREA, Kermit reads the terminal just as if it were invoked as a transaction. If supplied, the COMMAREA is scanned, instead of a terminal buffer, for the command string. Note that, if the COMMAREA does not begin with a blank, the first blank-delimited word will be ignored in the same way as the transaction name in a terminal buffer. In both cases, the command-line arguments begin with the first non-blank character after the first blank. Once the command line is established, execution proceeds the same as if Kermit had been started by hand; since Kermit exits as soon as it finishes the subcommand specified in the command string, there is no need to enter any subcommands at the terminal in this mode of operation. Even so, Kermit should be given a terminal, since that provides the communication line for file transfer. When Kermit exits, if the given COMMAREA is at least seven bytes long, Kermit sets a return or completion code in the COMMAREA according to the current status. See the table of error codes in the Kermit-370 chapter. The return code takes the following form: the characters @qq, a four-byte signed binary integer, and the character @qq<)>. It is, thus, compatible with the convention described below under the CICS subcommand. @Index(Completion codes) @subheading(Interface to mail, print, and batch) @Index(Electronic mail)@Index(Printing files)@Index(Batch jobs) Unlike many other IBM/370 environments, CICS does not provide a standard means of returning a completion code from an invoked program. As the previous paragraph indicates, Kermit-370 has adopted its own standard, using the COMMAREA, and this applies to the calling sequences for the commands that handle electronic mail, print files, and batch jobs. Thus, the @qq shown in those sequences at the beginning of this chapter is not to be considered as an option, but as a required part of the COMMAREA to allow room for a return code. Consequently, when Kermit-CICS calls one of those programs to verify the feasibility of that kind of file disposition, the COMMAREA consists of seven bytes, rather than none. See below under the HOST subcommand for more details about invoking CICS programs from Kermit. @subheading(Server mode:) Command execution in server mode is different in three respects from normal operation. First, some Kermit subcommands are not allowed (see the list of subcommands in the Kermit-370 chapter). Second, command errors always terminate any active TAKE file. Third, Kermit intercepts its terminal output and transmits the data to the local Kermit as text packets. However, any other programs that wish to write to the terminal will do so, and such messages never appear to the local Kermit (except, perhaps, as bad packets). @Section Kermit-CICS supports all the subcommands described in the Kermit-370 chapter. In addition, there is the system-specific subcommand @qq, which is a synonym for the generic subcommand @qq. @qq can be issued as a remote Kermit command when Kermit-CICS is in server mode. This section concentrates on the subcommands that have special form or meaning for Kermit-CICS. These are ordered alphabetically. See the chapter on Kermit-370 for further details. @Heading(The CICS Subcommand) @Index(Host commands) Syntax:@q< CICS @i(text of command)> @Index(File management) Kermit-CICS supports two kinds of "system" commands. Both kinds are designated by the prefix @qq or @qq, even though neither kind can be invoked directly from a CICS session. The first word of the command string is taken to be the name of the command. Kermit first checks whether the name is in a list of simulated CICS functions (and their abbreviations). If so, Kermit itself simulates the function. The @Index(TYPE)@Index(DIRECTORY) available functions are DIRECTORY, TYPE, COPY, and DELETE. DIRECTORY and TYPE are identical to the corresponding Kermit subcommands. COPY has a straightforward syntax (old @i followed by new); DELETE is even simpler (just the desired @i). DELETE and DIRECTORY have no special options, but COPY and TYPE offer one: the source @i may have a range of line numbers (in the same syntax as the SEND subcommand) to be copied/typed instead of the entire file. @Index(COPY)@Index(DELETE) All four functions are applicable to the same data objects as KERMIT SEND and RECEIVE, but none of the four recognize wildcards. No RENAME function is implemented,@Index(RENAME) although that command name is reserved. @Indexentry(key="Command level", entry="Command level. @i CICS command level") If the command name is not found in the list of special functions, Kermit attempts to invoke a CICS program of that name with a COMMAREA consisting of the remainder of the command string. The CICS commands used in @Index(CICS command level)command-level programming are not supported. Kermit detects numeric return codes from co-operating invoked programs by examining the COMMAREA upon return. If the first two bytes are the string @qq, the seventh byte is @qq<)>, and the third byte is the same as the fourth, the string of bytes three though six is taken to be a binary fullword return code. The conditions are sufficiently restrictive that "accidental" return codes are very rare (one chance in four billion, assuming totally random bytes, but probably less than that in practice). A negative code is taken to mean that the host command was actually "illegal" in some sense, a zero code means that the command completed successfully, and a positive code means that the command encountered an error of some kind while executing. Positive codes are reported to the user in the form @qq, where the numeric value is given in decimal. @Heading(The CWD Subcommand) @Index(CWD)@Index(Directories)@Index(Fileclass) Syntax:@q< CWD @i(directory) @i(or) '@i(prefix)> The CWD (Change Working Directory) subcommand establishes a new default directory or specifies a default prefix for Qualified File Names. The specified name is normally the four-character userid associated with a directory in Kermit-managed storage. However, if the name is omitted, this resets the directory to @qq<*>, which is a synonym for the session userid. If the name begins with an apostrophe, that establishes the use of Qualified File Names with the given string as prefix. When a QFN prefix is established, any @i(filespec) given to Kermit-CICS without an explicit fileclass (directory) will be appended to the current prefix and interpreted as a QFN, rather than as a normal CICS data object name. @Index(Qualified File Names) When a fileclass is given explicitly, even if the fileclass is ignored (as in the case of TD and TS queues), that overrides the presumption of a QFN. Thus, while the CWD subcommand allows the convenience of an abbreviated notation for both QFN's and normal data object names, the underlying syntax always permits the specification of any desired file by spelling out the @i(filespec) in full. For example, if the current prefix is @qq<'AAA1234.>, the QFN @qq<'AAA1234.OLD.TAKE'> may be abbreviated as just @qq, but the system initialization file can still be specified (as @qq<*/KSYS.TD>). Similarly, if the prefix is @qq<*>, @i(i.e.), the session default directory name, the same QFN must be spelled out in full, while the filespec @qq would refer to member @qq in the user's directory. @Heading(The DIRECTORY Subcommand) @Index(DIRECTORY) Syntax:@q< DIRECTORY @i(filespec)> The DIRECTORY subcommand displays attributes of one or more files (name, LRECL, RECFM, size, type, and date). The @i(filespec) may have wildcard characters if it refers to members of the current working directory or to TS or TD queues. For TD queues, the type is displayed as @qq, @qq, @qq, or @qq, and the type for all other data objects is @qq. The size is displayed, where possible, in two forms, both the number of records and the total number of bytes (rounded to the nearest kilobyte). If either of those sizes is shown as zero, it may simply mean that Kermit was unable to obtain the required information, @i(e.g.), for main-storage TS queues in CICS under MVS/ESA. A value of zero for the LRECL means that the only limit is 32767. Similarly, if the date is unavailable (often the case), it will simply be omitted. @Heading(The GIVE Subcommand) @Index(GIVE)@Index(Translation tables) Syntax:@q< GIVE @i(table-name) @i(filespec)> This subcommand compares the named translation table with its default values and saves the differences in a TAKE file named @i(filespec). The @i(filespec) has the usual format, except that the default filetype is @qq, rather than @qq. See the Kermit-370 chapter for a fuller description of this subcommand. @Heading(The HELP Subcommand) @Index(HELP) Syntax:@q< HELP [@i(subcommand)]> This subcommand displays a message that explains the specified Kermit-CICS subcommand. If no subcommand is given, the message explains the Kermit command itself. These messages are stored in the Kermit-managed storage in the common directory. @Heading @Index(RECEIVE) Syntax:@q< RECEIVE [@i(filespec)]> The RECEIVE subcommand tells Kermit to receive one or more files from the other system. You must issue the corresponding SEND subcommand to the other Kermit. If the optional @i(filespec) is omitted, Kermit-CICS will use the name(s) provided by the other Kermit. If that name is not a legal CICS file name, Kermit-CICS will delete excess characters, if any. If the filetype is illegal, however, Kermit will reject the file. Wildcards may not be used. A @i(filespec) in the subcommand indicates what name the incoming file should be given. If the optional @i(filespec) is provided, but more than one file arrives, the first file will be stored under the given @i(filespec), and the remainder will be stored under their own names, as provided by the other Kermit. For purposes of truncation and folding, the maximum record length for a received file depends on the file type and the filetype. BINARY files are folded at the current LRECL, but TEXT files may have a maximum size of 32767 (TS queues and Kermit directory members do, as do TD queues with varying-length records). @Index(Truncation)@Index(Folding) @Index(Filename collision) If the incoming file has the same name as an existing file, the action taken depends on the FILE COLLISION setting. The possible settings and their meanings are given in the Kermit-370 chapter. Two of the settings (BACKUP and RENAME) require that Kermit-CICS change the incoming name so as not to obliterate a pre-@|existing file. It attempts to find a unique name by successively modifying the original and checking for the existence of such a file at each step. The procedure begins by truncating the filename to six characters if necessary and then appending @qq<$0> and changing any filetype other than @qq to @qq. If a file by that name exists, Kermit then replaces the @qq<0> with a @qq<1>. It continues in this manner up to @qq<9>, and if an unused name cannot be found, the transfer fails. In Kermit-CICS, the default setting of FILE COLLISION is RENAME, which causes the new file to be stored under the modified name. The BACKUP option is not supported by Kermit-CICS. @Heading @Index(SEND) Syntax:@q{ SEND [@i(filespec)[<@i(options)>] [@i(foreign-filespec)]][, ...]} The SEND subcommand causes one or more files to be sent from CICS to the other system. For details on the @i(options), see the description of SEND in the Kermit-370 chapter. Note that no blanks may intervene between the CICS @i(filespec) and the @i(options). @Index(Wildcards) If the filetype is @qq, @qq, or @qq, the filename may contain the wildcard characters @qq<*> or @qq<%>. Wildcards are valid with @qq only for the current directory. If wildcards are used, all eligible matching files will be sent. Note that wildcard specification for TS queues cannot be guaranteed to work correctly, since CICS is a multi-user environment, and the system chain of queues can be modified dynamically while Kermit is following the chain looking for matches. The result might be to skip one or more files, to send a file more than once, or to attempt sending a non-existant queue (cutting short the transfer with an I/O error message). The @i(foreign-filespec), if any, is used for the file header of the outgoing file, replacing the usual @qq copied from the CICS @i(filespec). Normally, this form of the SEND subcommand is used only when the @i(filespec) has no wildcards, since the @i(foreign-filespec) is used only for the first file of a group (subsequent files having default headers). If both @i(filespecs) are omitted for this subcommand, Kermit will prompt separately for each. This prompting mode is especially useful when more than one file (or file group) is to be sent, since the command line is limited to 130 characters. @Indexsecondary(primary="Blanks",secondary="preserving trailing") Trailing blanks in a text file with RECFM F are deemed superfluous and are stripped off when Kermit-CICS downloads the file. In order to treat such blanks as significant, you must convert the record format to V by using, for example, the Kermit HOST COPY subcommand to move the file to a TS queue. @Heading @Index(SET) Syntax:@q< SET @i(parameter) [@i(value)]> The SET subcommand establishes or modifies various parameters controlling file transfers. The following SET parameters are available in Kermit-CICS, but not universally in Kermit-370: @Begin(Format,spread 0) @tabclear()@tabset(2.0inches) DELIMITER@\character for terminal input. FILE LRECL@\Logical Record length for incoming file. RECFM@\Record format for incoming files. PREFIX@\New directory. @End(format) @Subheading @Index(Delimiter) Syntax:@q< SET DELIMITER @i(character)> This subcommand is defines a character to be interpreted as the logical end of an input command line (for the purpose of entering multiple commands on a single line). This is used only for commands entered at the terminal and has no effect on commands contained in TAKE files. The delimiter is initially undefined, but it can be set in one of the initialization files and thereby be used in parsing the initial command-line arguments. @Subheading(SET FILE COLLISION) Syntax:@q< SET FILE COLLISION @i(option)> Unlike most other variants of Kermit-370, Kermit-CICS has RENAME as the default value for FILE COLLISION. As a consequence, the usual mode of operation for receiving a file that already exists (or appears to exist, as extra-partition TD queues always do), is to assign a new and unique name and save the file as a TS queue. If you really want to upload into an extra-partition TD queue, you must first SET FILE COLLISION OVERWRITE or APPEND, whichever is appropriate. Actually, if the queue in question already exists but is closed, these two options have the same effect, which is to overwrite the queue. @Index(Filename collision)@Index(TD queues) @Subheading(SET FILE LRECL) Syntax:@q< SET FILE LRECL @i(number)> This sets the logical record length for incoming files to a @i(number) from 1 to 32767 (32K-1). This variable is used only for fixed-format and binary files. However, the only currently supported type of fixed-format files is the extra-partition TD queue, which does not allow Kermit to alter the pre-defined LRECL. The default is 80. @Subheading(SET FILE RECFM) @Index(RECFM) Syntax:@q< SET FILE RECFM @i(option)> This sets the record format to use for incoming files. Valid @i