KERMIT
 
 
Kermit-MUSIC is a program that implements the KERMIT file transfer protocol
for IBM 370-series mainframes running the MUSIC/SP operating system.  It
allows for the transfer of files between computers over asynchronous ASCII
communications lines (attached to a 3705-style front end, such as the
COMTEN, or to a Series/1 or 4994 running the Yale ASCII Terminal
Communication System, or to an IBM 7171 ASCII Device Control Unit).  For
more details, see SET CONTROLLER.
 
The calling format for Kermit-MUSIC is:
 
        +----------+-----------------------+
        |          |                       |
        |  KERMIT  |  [kercmd ... kercmd]  |
        |          |                       |
        +----------+-----------------------+
 
where kercmd is a valid Kermit-MUSIC command.  If no Kermit commands are
supplied, Kermit-MUSIC will issue a prompt and wait for instructions.  When
Kermit is invoked with command line arguments, it will exit and return to
MUSIC after completing the specified command or commands.  Several commands
may be given on the command line as long as they are separated by the
linend character.  The command line may contain up to 130 characters.
 
Commands:
 
 
SEND fn[<n-m>] [filespec]
         Send a file or file group from MUSIC to the Kermit on the remote
         system.  The wildcard characters "*" or "?" may be used.  A "*"
         matches any string of characters from the current position to the
         end of the field, including no characters at all; a "?" matches
         any single character.  If the input contains wildcard characters
         then all matching files will be sent.  The exact file name on the
         foreign Kermit system may be specified; otherwise, Kermit-MUSIC
         will make it up out of the MUSIC name.  A range of lines, "n"
         through "m", may be specified for sending.
 
RECEIVE [fn]
         Receive a file or file group from the other system.  If the
         optional filename is not included, Kermit-MUSIC will use the name
         provided by the other Kermit.  If that name is not a legal MUSIC
         file name, Kermit-MUSIC will delete excessive characters from it,
         and will change illegal characters to dollar signs.  Use the file
         specification to indicate that the incoming file should be stored
         under a different name.  The filespec may include a code to
         designate the destination code.  If none is provided, the file
         will be saved in the current working directory which is by default
         your code.  Wildcards may not be used in any field.  If the
         optional filespec is provided, but more than one file arrives, the
         first file will be stored under the given filespec, and the
         remainder will be stored under their own names in the current
         working directory.
 
TAKE fn
         Execute Kermit commands from the specified file.  The command file
         may include TAKE commands.
 
SERVER
         Kermit-MUSIC is capable of acting as a server.  In server mode,
         Kermit-MUSIC can send and receive files, execute certain MUSIC
         commands, execute a restricted set of Kermit commands, and perform
         a variety of generic Kermit functions.  The following list shows
         the typical local Kermit commands along with the server functions
         they elicit.  Note that when Kermit-MUSIC is talking to a Kermit
         server, these same commands may be used in the other direction.
 
          BYE                 log out of MUSIC
          FINISH              exit from server mode
          GET                 send a file or files from MUSIC
          REMOTE COPY         copy a file or files
          REMOTE CWD          set new "home" disk
          REMOTE DIRECTORY    display file attributes
          REMOTE ERASE        delete a file or files
          REMOTE HELP         display this command summary
          REMOTE HOST         execute a MUSIC command
          REMOTE KERMIT       execute a Kermit-MUSIC command
          REMOTE RENAME       rename a file or files
          REMOTE SPACE        display disk allocations
          REMOTE TYPE         display a file
          SEND                receive a file or files onto MUSIC
 
         If your local Kermit does not support the REMOTE KERMIT command,
         you may need to issue SET commands to select various options
         before typing the SERVER command.  Once in server mode,
         Kermit-MUSIC will await all further instructions from the user
         Kermit on the other end of the connection.
 
CWD code
         Change Working Directory - establish new default "code" for all
         files.
 
SET parameter [value]
         Establish or modify various parameters for file transfer.  You can
         examine their values with the SHOW command.  Valid options are:
 
        ATOE [num1 num2]
                Modify the ASCII-to-EBCDIC translate table used by
                Kermit-MUSIC to conform to your system.  Specify the offset
                of the ASCII value within the table and the new value for
                that location.  Both "num1" and "num2" should be in the
                range 0-255 (decimal).  If "num1" and "num2" are omitted,
                restore the table to its default values.  Tables ETOA,
                TATOE, and TETOA may be modified in the same way.
 
        ATTRIBUTE [attribute] <ON | OFF>
                Allows or suppresses the exchange of Attribute packets.
 
        BLOCK num
                Determine the type of block check used during file
                transfer.  Valid options for "num" are: 1 (for a one
                character checksum), 2 (for a two character checksum) and 3
                (for a three character CRC).
 
        CONTROLLER <TTY | SERIES1 | GRAPHICS>
                Kermit-MUSIC automatically determines whether you are
                connected via a Series/1-style emulation controller or a
                TTY line.  This command is provided, though, so you can
                change connections and because Kermit may not be able to
                distinguish between Series/1 and graphics throughput
                devices.  For both of those, Kermit attempts to disable the
                3270 protocol conversion function by putting the controller
                into "transparent mode"; this allows Kermit packets to pass
                through intact.
 
        DEBUG <ON | OFF | RAW | I/O>
                If ON, keep a journal of all packets sent and received in
                the file KERMIT.LOG.  If the file already exists, it is
                overwritten.  If OFF, stop logging the packets.  If RAW,
                same as ON, but record packets "exactly" as sent or
                received (without translating to EBCDIC).  If I/O, same as
                ON, but record supplemental info for SERIES1 transfers.
 
        DELAY num
                How long to wait before sending the first packet.  Use a
                DELAY of 0 to suppress the extra 1-second pause for issuing
                the protocol-mode greetings.
 
        DELIM char
                Specifies a character to be interpreted by Kermit as a line
                delimiter in subsequent subcommands.
 
        DESTINATION code
                Specify a new user code.
 
        EOF <ON | OFF>
                ON means incoming text files are to be cut off at first
                Ctrl-Z character within the data, OFF means accept incoming
                text files in their entirety.
 
        FILE COLLISION <APPEND | BACKUP | DISCARD | OVERWRITE | RENAME>
                Specifies the action to take when a file is received that
                has the same name as an existing one.  BACKUP and RENAME
                are similar, but BACKUP renames the old file while RENAME
                renames the new one.  OVERWRITE is the default.
 
        FILE LONGLINE <FOLD | TRUNC | HALT>
                Specifies the action to take upon receiving records longer
                than the effective limit (for TEXT files).  With fixed
                record format, the limit is the logical record length, but
                with variable record format, the limit is 32K-1.
 
        FILE LRECL num
                Set the logical record length for incoming files to a "num"
                from 1 to 32767 (32K-1).  This variable is used only for
                fixed format and binary files.  The default is 80.
 
        FILE OVERWRITE <DEFAULT | PRESERVE>
                Specifies what attributes to use when writing a new file
                over an old one.  DEFAULT is the default.
 
        FILE RECFM <FIXED | VARIABLE>
                Set the record format to use for incoming files, using "F"
                for fixed format and "V" for variable format.  The default
                is variable.
 
        FILE TYPE <BINARY | TEXT | V-BINARY | D-BINARY>
                If BINARY, MUSIC Kermit treats each character as a string
                of bits and does not perform translation on the data.
                Also, carriage returns are not added to the end of outgoing
                records.  Incoming bytes are added to the end of the
                current record which is written out when the specified
                LRECL is reached.  If TEXT, MUSIC Kermit treats the file as
                plain text; ASCII-to-EBCDIC and EBCDIC-to-ASCII translation
                is performed on the data.  A carriage return-linefeed is
                appended to each outgoing record and is used to determine
                the end of each incoming record.  V-BINARY specifies
                variable-length-record binary data; like BINARY, except
                that a 2-byte length field precedes each outbound record,
                and is assumed for incoming records.  D-BINARY is similar,
                but the length field is a 5-byte ASCII decimal string.
 
        FOREIGN <PREFIX | SUFFIX> string
                The specified string is added to the beginning or end of
                outbound filespecs.
 
        INCOMPLETE <DISCARD | KEEP>
                The specified action is taken when a transfer is cancelled
                by the other Kermit before MUSIC has completely received
                the file.
 
        MARGIN <LEFT | RIGHT> column
                The specified margin is set for restricting the width of
                files to be sent.  A value of zero disables the specified
                margin.
 
        PROMPT string
                This command defines the character string that Kermit-MUSIC
                displays when asking for a command.  The prompt may be any
                string of up to 20 characters.  The default is
                "Kermit-MUSIC>".
 
        <SEND | RECEIVE> END-OF-LINE num
                If the remote system needs packets to be terminated by
                anything other than carriage return, specify the decimal
                value of the desired ASCII character.  "num" must be in the
                range 0 - 31 (decimal).
 
        RECEIVE PACKET-SIZE num
                Use the specified "num" as the maximum length for incoming
                packets.  The valid range is 26-1910, where 80 is the
                default.  SET RECEIVE PACKET-SIZE 95 or greater causes
                Kermit-MUSIC to negotiate reception of extended length
                packets with other Kermit programs that support this
                option.
 
        <SEND | RECEIVE> PAD-CHAR num
                Padding character to use between packets, NUL (ASCII 0) by
                default.
 
        <SEND | RECEIVE> PADDING num
                Number of copies of the interpacket padding character, zero
                by default.
 
        <SEND | RECEIVE> PARITY <MARK | NONE>
                Transparent-mode ASCII data from a SERIES1 or GRAPHICS
                device will typically have either all Mark parity (seven
                data bits with the eighth bit set) or no parity (eight data
                bits).  Kermit-MUSIC must know which kind of parity to
                expect in order to calculate checksums properly.  The SEND
                parity controls SERIES1 and GRAPHICS mode transfers.
 
        <SEND | RECEIVE> QUOTE char
                Control character quoting prefix, normally #.
 
        <SEND | RECEIVE> START-OF-PACKET num
                Control character to mark start of packet, normally Ctrl-A
                (ASCII 1).
 
        <SEND | RECEIVE> TIMEOUT num
                Number of seconds to wait for a packet before
                retransmitting.
 
        RETRY <INITIAL | PACKET> num
                Establish the threshold for retrying a particular packet.
                The default is 16 for initial and 5 for ordinary packets.
 
        SERVER-TIMEOUT num
                Number of seconds to wait for a packet in the server loop
                before sending a NAK.  Default is 120.
 
        SPEED num
                Specifies the lines speed to be assumed by Kermit-MUSIC in
                calculating the optimum packet size on a noisy line.  If
                the value is zero, such calculations are suppressed.  The
                default is 1200.
 
        SYSCMD <ON | OFF>
                Determine whether non-Kermit commands are assumed to be
                MUSIC commands.
 
        TABS-EXPAND <ON | OFF>
                Controls whether tabs in incoming text files are expended
                to blanks.
 
        TAKE ECHO <ON | OFF>
                Controls whether the contents of TAKE command files are
                echoed during execution.
 
        TAKE ERROR-ACTION <CONTINUE | HALT>
                Controls whether an error occuring during execution of a
                TAKE command file is fatal to the execution of that file.
 
        TEST <ON | OFF>
                Used for testing new versions, suppresses block check
                verification, allows start-of-packet to be set to anything
                at all.
 
        TTABLE <ON | OFF>
                Controls whether ATOE/ETOA or TATOE/TETOA are used for
                counteracting the system translations on TTY lines.
 
        8-BIT-QUOTE <ON | OFF | char>
                Control whether eighth-bit prefixing is done and specify
                the character to be used.
 
SHOW option
         Display the values of any or all parameters that can be changed
         with the SET command, except for ATOE and ETOA (see the TDUMP
         command).
 
SPACE [letter]
         Show the storage allocation on the specified MUSIC code.
 
STATUS
         Return the status of the previous command.  The response will
         either display the message "No errors", or the last error
         encountered.  The throuput statistics for the last transfer are
         also shown.
 
TDUMP <table-name | NAMES>
         Display the contents of "table-name" since it can be modified
         using the SET command.  The ATOE, ETOA, TATOE, and TETOA tables
         can be 'dumped' (also, the list of files sent in the last
         transfer).
 
GIVE table-name fn
         Save the contents of "table-name" as a TAKE file containing SET
         commands to change the default into the current arrangement.
 
ECHO line
         Display the line at your terminal.
 
XECHO line
         Display the line at your Series/1 terminal in transparent mode.
 
TYPE fn
         Display the specified file at your terminal.
 
XTYPE fn
         Display  the   specified  file   at  your   Series/1  terminal  in
         transparent mode.
 
HOST     Issue a MUSIC command from within Kermit-MUSIC.
 
DIR      Similar to MUSIC LIBRARY
 
SPACE    Same as SHOW.
 
HELP     Display a message that explains Kermit-MUSIC commands.
 
EXIT     Exit from KERMIT back to the host operating system.
 
QUIT     Synonym for EXIT.
 
?        List all legal Kermit-MUSIC commands.
 
 
You may use the help ("?") feature while typing Kermit-MUSIC commands.  A
question mark typed at almost any point in a command, followed by a
carriage return, produces a brief description of what is expected or
possible at that point.
 
Usage Notes:
 
1.  To use MUSIC Kermit though a 3705-style linemode connection, you should
    be sure  to set  the following  parameters:   ECHO LOCAL (half duplex),
    PARITY MARK (or whatever  your system uses), FLOW-CONTROL  NONE (rather
    than XON/XOFF), HANDSHAKE NONE, TIMER ON.
 
2.  To use MUSIC  Kermit through a  Series/1-style protocol converter,  use
    ECHO REMOTE (full duplex), FLOW-CONTROL XON/XOFF, HANDSHAKE NONE, TIMER
    ON, and PARITY to EVEN or whatever your front end requires.
 
3.  The current version  of Kermit-MUSIC does  not support timeouts.   Your
    local Kermit program should supply them (SET TIMER ON enables  timeouts
    in most microcomputer Kermits).
 
4.  When sending  packets to  Kermit-MUSIC, the  micro must  use a carriage
    return as the end-of-line character.  Both TTY and Series/1 connections
    require a carriage return to terminate a read from the terminal;  thus,
    if  any  other  character  is  used,  Kermit-MUSIC  will  never get the
    packets.
 
