Columbia Kermit

home *** CD-ROM | disk | FTP | other *** search

/ Columbia Kermit / kermit.zip / ibmtsoqueens / ts2kerdoc.txt < prev

Wrap

Text File | 2020-01-01 | 23KB | 634 lines

IBM MVS/TSO KERMIT ================== Programmer: Fritz Buetikofer, Help desk member at the University of &Documentation: Bern (Switzerland). Language: PASCAL/VS Adaptation from the CMS-version of Victor Lee (Queens University) Version: 2.3 Date: September 1987 TSO Kermit Capabilities At A Glance: Local operation: No Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y interruption: No Filename collision avoidance: Yes Can time out: No 8th-bit prefixing: Yes Repeat count prefixing: Yes (RECEIVE only) Alternate block checks: Yes Terminal emulation: No Communication settings: No Transmit BREAK: No Transaction logging: Yes Session logging: No Raw transmit: No Act as server: Yes Talk to server: Yes (only from startup file) Advanced server functions: Yes Advanced commands for servers: No Local file management: Yes Command/init files: Yes Command macros: No Handle Attribute Packets: Yes (puts them in the LOG-file) Extended-length packets: Yes (Maximum size is 1K) Sliding windows: No Kermit-TSO is a program that implements the KERMIT file transfer protocol for IBM 370-series mainframes (System/370, 303x, 308x, etc.) under the MVS/TSO operating system. It is written in IBM PASCAL/VS language. This Program runs only over ASCII (asynchronous) lines attached to a 3705-style front end. Actually Kermit-TSO is unable to interrupt a read on its "console". This means that the TSO version of Kermit cannot timeout. The only way to "timeout" TSO Kermit 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. The File System under MVS ========================= The features of the TSO file system of greatest interest to Kermit users are the format of file specifications and the concept of records. File Specifications ------------------- The MVS/TSO file specification is in the form a) sequential files: 'USERID.FILENAME.FILETYPE' or NAME.FILETYPE (short form) a) partitioned files (PDS): 'USERID.FILENAME.FILETYPE(MEMBER)' or NAME.FILETYPE(MEMBER) (short form) FILENAME, FILETYPE and MEMBER are at most 8 characters in length each. The name field is the primary identifier for the file. The type is an an indicator which, by convention, tells what kind of file we have. For instance TEST.FORT is the source of a FORTRAN program named TEST. LOAD is the normal suffix for executable programs. MVS/TSO considers the FILETYPE parameter optional. The USERID parameter is the normal userid under which the user logs on to MVS/TSO. If USERID is omitted from a file specification when sending, the short form of the file specification is used (that means, the file is cataloged under the userid of the KERMIT user). To provide compatibility with most other operating systems, Kermit-TSO sends only the FILENAME and FILETYPE; for members of a partitioned data- set, the MEMBERNAME and FILETYPE are sent. The FILENAME, FILETYPE and MEMBER may contain, in any order, uppercase letters, digits, and the special characters "$" (dollar sign), "@" (at sign) and "#" (hash). File Formats ------------ Several differences exist between MVS/TSO files and those of most other operating systems. One distinction is that MVS encodes its data using the EBCDIC character set. The operating system, MVS, translates all incoming characters from ASCII to EBCDIC. Kermit-TSO then translates the data it reads back to ASCII (characters not representable in ASCII are replaced by a null). This is done in order to correctly calculate the checksum, the method used to guarantee error-free transfer. When Kermit-TSO sends packets, it converts all data back to EBCDIC. Note that the translate tables used by Kermit must correspond to the ones used by the system (MVS/VTAM). Another difference is that MVS/TSO stores files as records rather than byte character streams. MVS/TSO Kermit has to worry about assembling incoming data packets into records and appending carriage return linefeed to outgoing records. Program Operation ================= Kermit-TSO can be invoked at the command line or from a CLIST. Invoke the program under TSO by typing "KERMIT". When you see the command's prompt, KERMIT-TSO> you may type Kermit commands repeatedly until you are ready to exit the program, for example: Welcome to KERMIT under MVS/XA-TSO V2.3 KERMIT-TSO> send foo*.fort KERMIT-TSO> receive test.spss KERMIT-TSO> exit End of Kermit Kermit-TSO Commands =================== Here's a brief summary of all TSO KERMIT commands: DELETE a specific file. DIR shows user directory. DISK space occupied by user. DO execute Kermit commands from a profile member END stop Kermit-TSO. EXIT from Kermit-TSO. FINISH finish server-mode of the micro HELP about Kermit-TSO. LOGOUT from Kermit-TSO and system. MEMBERS displays memberlist of a PDS. QUIT from Kermit-TSO. RECEIVE files from other Kermit. SEND files to other Kermit. SERVER mode of remote operation. SET various parameters. SHOW Kermit settings. STATUS same as SHOW. TAKE execute Kermit commands from a file TSO executes a TSO command. TYPE a specific file. WHO is logged on. Diagramm with KERMIT commands and syntax: KERMIT ---------------------------------------------------------------------+ | | |-- DElete --- <local-filespec> -------------------------------------+ | | |-- DIRectory -------------------------------------------------------+ | |-- <userid> ------------------------------------------+ | | |-- DISk ------------------------------------------------------------+ | | |-- DO ------- <membername> -----------------------------------------+ | | |-- FInish ----------------------------------------------------------+ | | |-- Help ------------------------------------------------------------+ | | |-- LOGout ----------------------------------------------------------+ | | |-- MEmbers -- <local-filespec> -------------------------------------+ | | |-- QUit or EXit or ENd ---------------------------------------------+ | | |-- RECeive ---------------------------------------------------------+ | |------------------- <local-filespec> -----------------+ | | |-- SENd <local-filespec> -------------------------------------------+ | |----<as> ---------- <local-filespec> -----------------+ | | |-- SERver ----------------------------------------------------------+ | | |-- SET -------------------------------------------------------------+ | |-- <DEbug> ------- <ON | OR> -------------------------+ | |-- <TExtmode> ---- <ON | OFF> ------------------------+ | |-- <REcfm> ------- <FB | VB> -------------------------+ | |-- <INcomplete> -- <KEEP | DELETE>--------------------+ | | | | |-- <CHecktype> ---| | | |-- <EOLchar> -----| | | |-- <DElay> -------|-- <decimal number> ---------------+ | |-- <PACketsize> --| | | |-- <SOHchar> -----| | | | | | |-- <CNtrlquote> --| | | |-- <BIt8quote> ---|-- <EBCDIC Char> ------------------+ | |-- <Repchar> -----| | | | | | |-- <ATOE> --------| | | |-- <ETOA> --------|-- <n1> -- <n2> -------------------+ | | |-- STatus ----------------------------------------------------------+ | | |-- TAke ----- <local-filespec> -------------------------------------+ | | |-- TYpe ----- <local-filespec> -------------------------------------+ | | |-- VErsion ---------------------------------------------------------+ | | |-- WHo -------------------------------------------------------------+-> THE DELETE COMMAND Syntax: DELETE filespec The DELETE command causes a file to be deleted from the catalog of the user (actually, no wildcards in the filespec are allowed). THE DIR COMMAND Syntax: DIR [userid] The DIR command causes a list of all cataloged files of a specific user to be displayed at the screen. THE DISK COMMAND Syntax: DISK The DISK command displays the actual size of disk-space occupied by the user. THE DO COMMAND Syntax: DO membername Execute Kermit commands from the file KERMIT.PROFILE, where membername should be an existing member. The command file should not include other DO or TAKE commands! THE END, EXIT and QUIT COMMAND Syntax: END or EXIT or QUIT These commands stop the Kermit-TSO program, the user returns back to the TSO prompt 'READY' to proceed work. THE FINISH COMMAND Syntax: FINISH The FINISH command sends a FINISH-packet to the server of the micro. This command has only an effect if used from within a startup-file. THE LOGOUT COMMAND Syntax: LOGOUT The LOGOUT command stops the Kermit-TSO program. Additionnaly the user is logged off from the host. THE MEMBERS COMMAND Syntax: MEMBERS filespec The MEMBERS command displays the memberlist of a partitionned file. THE RECEIVE COMMAND Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-TSO to receive a file or file group from the other system. You should then issue a SEND command to the remote Kermit. If the optional filespec is not included, Kermit-TSO will use the name(s) provided by the other Kermit. If that name is not a legal TSO file name, Kermit-TSO will try to write the incoming data to the file KERMIT.TEMP. 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 (sent by the other Kermit). When receiving files, any record longer than the logical record length will be split up to as many records as necessary. Actually the following two record formats are supported: 1) Fixed format records, with a record length of 80. This format is used for language sources and OS job control. 2) Variable records, with a record length of 255 bytes. This format is the default, and is used for normal text files. If an error occurs during the file transfer, as much of the file as was received is saved. If the sending of a file is cancelled by the user of the remote system, Kermit-TSO will discard whatever had arrived. If the incoming file has the same name as a file that already exists, Kermit-TSO will change the incoming name so as not to obliterate the pre-existing file. It attempts to rename the file by replacing the last character of the FILENAME or MEMBER (for PDS files) with the next-following character in the alphabetical order. It continues in this manner, until a filename for a non-existant file is found. THE SEND COMMAND Syntax: SEND filespec [[AS] local-filespec] The SEND command causes a file or file group to be sent from the TSO system to the Kermit on the remote system. In filespec you may put ONE wildcard '*' anywhere in the filename, file- type or membername if present. Do not put a wildcard in the userid. Although the file transfer cannot be cancelled from the TSO side, Kermit-TSO is capable of responding to "cancel file" or "cancel batch" signals from the local Kermit; these are typically entered by typing Control-X and Control-Z respectively. THE SERVER COMMAND Kermit-TSO is capable of acting as a server. The user connects to the TSO system once to set various options and to start the server. From then on, he need not connect to the TSO system again. The current version of Kermit-TSO can send files (the user on the other end types the GET command, using the TSO filename conventions), receive files (the user types SEND), several advanced server functions as user directory, typing or deleting files and other, and terminate by either returning to TSO (user types FINISH) or logging the user out (user types BYE). To put Kermit-TSO into server mode, first issue any desired SET command to select various options and then type the SERVER command. Kermit-TSO will await all further instructions from the user Kermit on the other end of the connection. For example: KERMIT-TSO> set debug on KERMIT-TSO> server THE SET COMMAND Syntax: SET parameter value Establish or modify various parameters for file transfer. You can examine their values with the SHOW command. The following SET commands are available in Kermit-TSO: ATOE Modify ASCII -> EBCDIC translation table BIT8-QUOTE Character for 8th bit quoting CHECKTYPE Type of block check to be used CNTRL-QUOTE Character for control character quoting DEBUG Log packets sent and received during file transfer DELAY Delay until first SEND INIT packet is sent EOLCHAR Packet terminator ETOA Modify EBCDIC -> ASCII translation table INCOMPLETE Disposition of file for aborted transfer PACKETSIZE Maximum receive packet size RECFM Record format for incoming files REPEATCHAR Character for compression indication SOHCHAR Start of Packet character TEXTMODE Translation for text files SET ATOE Syntax: SET ATOE n1 n2 This command allows you to modify the ASCII -> EBCDIC translation table which is used to determine the resulting character and checksum on the micro side. The numbers n1 and n2 should lie in the range 0..255. SET BIT8-QUOTE Syntax: SET BIT8-QUOTE x This command allows you to modify the character, which is used for 8th bit quoting. Initially this character is set to '&'. Running in server mode, Kermit-TSO uses the 8th-bit quoting character of the micro. SET CHECKTYPE Syntax: SET CHECKTYPE n This command allows you to specify the block check type to be used for ensuring a safe tranfer of the data. The allowed types are: 1 - single character checksum, 2 - two char checksum or 3 - three char CRC. SET CNTRL-QUOTE SYNTAX: SET CNTRL-QUOTE x Use the indicated printable character for prefixing (quoting) control characters and other prefix characters. The only reason to change this would be for sending a very long file that contains very many "#" characters (the normal control prefix) as data. It must be a single character in the range: 33-62, 96, 123-126 (decimal). SET DEBUG Syntax: SET DEBUG ON / OFF ON Keep a journal of all packets sent and received in the file KERMIT.DEBUG. If the file already exists, it is overwritten. OFF Stop logging the packets. SET DELAY Syntax: SET DELAY nn This command allows you to modify the delay time (in seconds), between issuing the SEND command on TSO side, and when the first 'SEND-INIT' packet. 'nn' must be between 5 and 60 (decimal); the default is 6. SET EOLCHAR Syntax: SET EOLCHAR nn If the remote system needs packets to be terminated by anything other than carriage return, specify the decimal value of the desired ASCII character. 'nn' must be between 0 and 18 (decimal). SET ETOA Syntax: SET ETOA n1 n2 This command allows you to modify the ASCII -> EBCDIC translation table which is used to determine the resulting character and checksum on the micro side. The numbers n1 and n2 should lie in the range 0..255. SET INCOMPLETE Syntax: SET INCOMPLETE KEEP / DELETE If the remote system aborts a filetransfer the INCOMPLETE options speci- fies what should be done with the incomplete file: whether it is kept or deleted. SET PACKETSIZE Syntax: SET PACKETSIZE nn Use the specified number as the maximum length for incoming packets. The valid range is 26-94-1000, where 94 is the default. Packets with a size of greater than 94 are packets according to the extended length protocol. SET RECFM Syntax: SET RECFM FB / VB Set the record format to use for incoming files. Valid options are "FB" for fixed format (as used for job control files) or "VB" for variable format (as used for text or data files). The default is variable. SET REPEATCHAR Syntax: SET REPEATCHAR x This command allows you to modify the character, which is used for character compression on the micro side. Initially this character is set to '~' (tilde). Running in server mode, Kermit-TSO uses the repeat character of the micro. SET SOHCHAR Syntax: SET SOHCHAR nn If the normal start-of-packet character <Ctrl-A> should not get through the communications line, you may change this character to any other suitable character. Specify the decimal value of the desired ASCII character. 'nn' must be between 0 and 18 (decimal). SET TEXTMODE Syntax: SET TEXTMODE ON / OFF ON Tells TSO Kermit that the file is plain text. ASCII-to-EBCDIC and EBCDIC-to-ASCII translation is performed on the data. Carriage return-linefeed are appended to outgoing records and are used to determine the end of incoming records. OFF Tells TSO Kermit to treat each character as a string of bits and not to perform translation on the data. Also, no carriage-return is added to the end of outgoing records. THE SHOW COMMAND Syntax: SHOW Use to display the values of all parameters that can be changed with the SET command. THE STATUS COMMAND Syntax: STATUS Returns the status of the previous command. The response will either display the message "Kermit completed successfully", or the last error encountered. THE TAKE COMMAND Syntax: TAKE filespec Execute Kermit commands from the specified file, where filespec has the normal TSO filename conventions. The command file should not include other TAKE or DO commands. THE TSO COMMAND Syntax: TSO commandstring Although Kermit-TSO does provide only few commands for managing local files (list directory, type and delete files), it is possible to interact with the operating system. You can issue any TSO command. At this time, though, you cannot run another program or clist from within Kermit-TSO. THE TYPE COMMAND Syntax: TYPE filespec The TYPE command causes a file or file group to be sent from the TSO system to the Kermit on the remote system and typed there on the screen. (actually no wildcards in the filespec are allowed ) Although the file transfer cannot be cancelled from the TSO side, Kermit-TSO is capable of responding to "cancel file" or "cancel batch" signals from the local Kermit; these are typically entered by typing Control-X and Control-Z respectively. THE WHO COMMAND Syntax: WHO The WHO command displays a list of the actual users logged on at the host system. The KERMIT startup file ======================= When starting KERMIT, the file called 'KERMIT.SETUP' is executed if it exists. The KERMIT clist checks for the presence of the command file. If he finds it, he passes an additional argument to the program, which causes KERMIT to execute all commands in this startup file. When sending more than one file from within the startup-file, you have to set the micro-Kermit into server mode. Example: +-KERMIT.SETUP--------------------+ | SEND FILE1.TEXT | | SEND KERMIT.INSTALL(*) | | FINISH | +---------------------------------+ Before Connecting to the Mainframe ================================== When connecting to the TSO system as a TTY device ("line at a time" mode) several flags must first be set on the micro version of Kermit. You should set the LOCAL-ECHO flag to OFF (this is used to indicate full-duplex). HANDSHAKE should be set to XON and FLOW-CONTROL should be set to NONE. The parity should be set according to the system's specifications. Set the baud rate to correspond to the line speed and set the parity as needed for the used line.