Columbia Kermit

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

/ Columbia Kermit / kermit.zip / archives / trs80model4.zip / m4mit.txt < prev next >

Wrap

Text File | 1986-10-22 | 88KB | 2,179 lines

TRS-80 Model 4(p) KERMIT: Version 5.2 For Use Under TRSDOS 6.1 or Later Program by: Gregg Wonderly Oklahoma State University, (gregg@okstate) rewritten from the origi- nal Model-4 KERMIT which was derived from the TRS-80 KERMIT done by Stan Barber, Rice University who modified the CP/M-80 version by Bill Catchings and others. Language: Z80 Assembler, compatible with M80 and EDAS from Misosys Version: 5.2 Date: Wed Oct 22 10:17:07 CDT 1986 Documentation by: Gregg Wonderly 1. Summary of TRSDOS 6.1 TRSDOS (The Radio Shack Disk Operating System) has a large library of built in commands dealing with files, directory maintenance, device I/O, etc. Programs are also used for some functions on some TRSDOS-based DOS's. Model 4(p) KERMIT gives you access to all of the library commands of TRSDOS versions 6.x via the LOCAL command. Issue the LIBRARY command at TRSDOS Ready to obtain a list. TRSDOS file specifications can be represented as a sequence of characters of the form FILESPEC/EXT.PASSWORD:D FILESPEC is the filename up to eight characters. EXT is the file type, up to three characters. PASSWORD is the password for that file, up to eight char- acters. D is a numerical drive specification (0-7). File names, file types and passwords may contain letters and numbers, but the first character in each must be a letter. No special characters or spaces are allowed. All fields are optional except the filespec. Any field added - 2 - must be preceded by its special delimiter '/' for file type, '.' for passwords and ':' for drive specifications. Upper and lower case characters are equivalent. 2. TRSDOS Commands of Interest 2.1. CAT PARTSPEC:D (OTHER OPTIONS) This command is specific to TRSDOS version 6.2 and later. It displays only the names of visible files on the drive specified, or all drives if no partspec is given. (other options) allows different formats and invisible as well as system files to be selected. See the TRSDOS manual for specifics 2.2. DIR PARTSPEC:D (OTHER OPTIONS) DIR is common to all version of TRSDOS. Versions after 6.1 replaced the DIR command with CAT, and changed the DIR command so that always produces a long listing. 2.3. FREE :D Gives statistics on disk usage. If D is present, it indicates a drive number, and only the statistics for the specified disk will be shown. 2.4. REMOVE/PURGE FILESPEC (PARAMETERS) Remove the file(s) given by FILESPEC from the directory and frees the space allocated to the file for reassign- ment. Purge allows PARTSPECs that specify groups of files. With no PARAMETERS, PURGE prompts before delet- ing any file. REMOVE requires a full filespec as the name of the file to remove. REMOVE allows more than one filespec to be given on the command line. 2.5. LIST FILESPEC (PARAMETERS) Lists the file on the display. Parameters are described in the TRSDOS manual in detail. (HEX) is sometimes useful to display the hexidecimal values of the characters in a file. 2.6. RENAME oldfile newfile Changes the name of oldfile to newfile, provided that newfile is a unique file name on that disk. 3. Copying Disks and Files: - 3 - 3.1. COPY file1 file2 Copies file1 and name the copy file2. If file2 exists, it will be replaced. 3.2. BACKUP :D :E Makes a copy of the disk in drive D on the the disk in drive E. 3.3. FORMAT :D Formats the disk in drive D. The disk will be ready for any normal read or write operation fol- lowing successful completion of this operation. This operation must be performed before use of a blank disk. Reformatting a previously formatted disk will cause all previously stored information to be lost. 4. Transfers without the KERMIT Protocol Model 4(p) KERMIT adds 2 logical devices to the already resident devices. These devices are used to access the com- munications port. These devices, *FI (File Input) and *FO (File Output), can be used as the source, and destination of a copy command, respectively. They make use of the status of the SET FLOW-CONTROL parameter, to send and receive data using the communications port. For instance, say you are communicating with a computer that does not have KERMIT. Say you also wish to transfer a file to this computer to do some further processing. The normal method involves start- ing a program on the remote computer to collect the data into a file on that system. On a VAX/VMS system, you might use the CREATE command to capture the file. The following KERMIT commands will accomplish the transmition of a file in this case. OUTPUT CREATE MYPROG.DAT<CR> LOCAL COPY PROG/DAT *FO The KERMIT command, OUTPUT, will send the string "CREATE MYPROG.DAT<CR>" to the host. Let's say for now that this is sufficient to cause all future characters sent to the host to be placed into the file MYPROG.DAT on that system. The KERMIT command LOCAL is then used to invoke the TRSDOS library command COPY. COPY will copy the contents of the file "PROG/DAT" to the *FO device. The driver for this dev- ice is part of the KERMIT program, and will take care of transmitting the data out of the communications port to the HOST. If the HOST sends XOFF because DATA is arriving TOO fast, then the XON/XOFF option to the KERMIT command, SET FLOW-CONTROL, will allow the transfer to pause while the HOST catches up. You may wish to collect the contents of a - 4 - file that is on another computer. If particular computer does not have KERMIT, you can use a series of commands simi- lar to those listed below to retrieve the file. It should be noted that the SESSION-LOG can also be used to trap the contents of a file. For that very reason, this is only one of several possible ways to get a file from another computer that does not have KERMIT. OUTPUT TYPE MYPROG.DAT<CR> INPUT TYPE MYPROG.DAT<CR><LF> LOCAL COPY *FI MYPROG/DAT:1 It may help to clarify the use of the OUTPUT command, and the corresponding INPUT command. If you use the KERMIT command CONNECT to enter terminal mode, and then proceed to tell the host to type out a file, it may start sending data before you can escape back, and type the COPY command. This means that some of the data would be lost. With FLOW- CONTROL set to XON/XOFF, and the remote host recognizing this fact, the previous commands would not allow any data to be lost. The use of INPUT is only to remove the characters ECHOed by the host from the input buffer (The TEXT of the command "TYPE MYPROG.DAT"). If you are communicating with a half-duplex system in which Model (4)p KERMIT is echoing the characters typed on the keyboard, then the INPUT command need not be used. 5. Control of File Transfers Using the KERMIT Protocol During the transfer of a file using either SEND, or GET and possibly during the use of the REMOTE command, protocol operations may need to be aborted, or altered. Several key strokes allow the user to control the protocol operations. These are listed below, and are listed on the screen after issuing either the SEND or GET commands. The operation of the REMOTE command is purposefully silent. The key strokes are available to the user during REMOTE commands, for added flexibility. This allows the user to cancel commands like REMOTE TYPE that may otherwise cause large amounts of data to be displayed for an extended amount of time. The valid key strokes are: Control-F During data transfers using the KERMIT proto- col, Control-F will terminate the current transaction. If there are more files to transfer, the next transaction will be started. Model 4(p) KERMIT will send a sig- nal to the remote KERMIT telling it to stop sending packets for the current transaction. - 5 - If the remote KERMIT understands this signal (not all implementations of KERMIT do), it will comply, otherwise the transaction will continue. Control-B Like Control-F, except that if a group of files is being processed this will stop the entire group. If only a single file is being SENT or RECEIVED, Control-B behaves exactly like Control-F. Control-C Aborts the protocol immediately. This should be a last resort to stopping a transmission as it will leave the remote KERMIT in an unk- nown state. Control-E Aborts the protocol after sending an ERROR packet to the remote KERMIT. Control-D Toggles DEBUG mode ON and OFF. This is help- ful when trying to figure out why a particu- lar host is unable to talk to Model 4(p) KER- MIT. <ENTER> If you type <ENTER>, Model 4(p) KERMIT will resend the current packet. Control-H Displays the list of KEYS that you may press during a transfer. I.E. the keys described above. This is the same message that is printed when a SEND, GET, or RECEIVE command is issued. 6. Model 4(p) KERMIT Commands Model 4(p) KERMIT uses a subset of the the DECSYSTEM-20 keyword style command language. Each keyword may be abbre- viated to its minimum unique length. "?" may be typed to request a list of the available options for the current field at any point in a command. If insufficient characters have been typed to identify the current field uniquely, Model 4(p) KERMIT will display all available choices, and then reprompt to allow you to continue from that point. If there are sufficient characters, then only a single choice will be displayed. The following list of commands are available when using Model 4(p) KERMIT. - 6 - 6.1. BYE When talking to a remote KERMIT Server, this command should shut down a remote server and terminate the login that you had there. Model 4(p) KERMIT will then exit to TRSDOS Ready. NOTE: Due to some deviations from the specifica- tion, some systems do not perform exactly in this manner. You should check the documentation of the KERMIT on the remote system in order to obtain the operation performed by this command. 6.2. CLEAR 6.2.1. INPUT-PORT Model 4(p) KERMIT uses the "Interrupt on received character available" feature of the COM/DVR com- munications line driver. This driver is part of the standard software on your system diskette. All characters received via the interrupt vector, are placed in a 256 byte circular buffer. This command clears all characters currently buffered. This is used most commonly with the INPUT, OUTPUT, PULSE, and PAUSE commands, none of which expli- citly clear the input buffer. YOU MUST DO THIS YOURSELF. The execution of this command will not send an XON character to the communications port. This is also left up to you to do. 6.2.2. SCREEN As you would expect, this command clears the screen. 6.3. CLOSE 6.3.1. DEBUG-LOG Closes the file previously opened with the LOG DEBUG-LOG command. If there is not a debug log- file active, then a message is printed telling you so. 6.3.2. SESSION-LOG Closes the file previously opened with the LOG SESSION-LOG command. If no file is open, you will be advised so. - 7 - 6.3.3. TRANSACTION-LOG Closes the file previously opened with the LOG TRANSACTION-LOG command. As with the other log- files, if a file is not currently open, then a message to that affect is printed. 6.4. CONNECT (can be abbreviated to 'C') Establish a "virtual terminal" connection to any host that may be connected to the serial port, i.e. pass all typed characters to the serial port and display all input from the serial port on the screen. A two character sequence of characters is required to return the user to the KERMIT program. An escape character must be typed followed by a 'c' (Case is not significant). The default <ESCAPE> character is entered by pressing the <SHIFT> key, and then and <CLEAR> key, while hold- ing the <SHIFT> key down. Pressing '?' after the <ESCAPE> character will display a list of valid keystrokes that do helpful things during connect mode. The first time that you issue the CONNECT command, a message will be displayed telling you what the <ESCAPE> character is. The <ESCAPE> character should generally be an uncommonly-used control character. The following characters are valid following the <ESCAPE> character, and gen- erate specific actions. The actions are described beside the character. C Return to Model 4(p) KERMIT command level. The contents of the screen and the cursor location will be saved prior to displaying the KERMIT screen. When you reconnect to the HOST using the KER- MIT command, CONNECT, the old screen will be restored. ? List available single-character com- mands, I.E. These commands. B Send a TRUE modem break. R Resume logging if file open, and <ESCAPE>Q was used previously to turn logging off. See the LOG command for more information. Q Quit logging to file but leave it open. 0 (zero)Send a null (0) character out the communications port. - 8 - <ESCAPE>Send the <ESCAPE> character itself to the remote host. 6.5. DIR partspec Produces a listing of the directory for "partspec". If partspec is not given, than the directory will be displayed for the DEFAULT-DISK drive as established by SET DEFAULT-DISK. 6.6. EXIT Exit Model 4(p) KERMIT, and return to TRSDOS. Before the KERMIT program is terminated, all open files will be closed. This includes the LOGFILES used for SESSION, TRANSACTION, and DEBUG logging. The *FO, and *FI devices will also be removed. 6.7. ECHO This command echoes text given as an argument to the screen. It can used in take files to put mes- sages on the screen when TAKE-DISPLAY is OFF, although other uses are possible. 6.8. FINISH Shuts down a remote server without logging it out. Leaves you at Model 4(p) KERMIT command level. A subsequent CONNECT command will reconnect you to the remote host. The remote KERMIT should return to the mode it was in prior to entering SERVER mode. 6.9. GET filespec Get allows you to retrieve files from a remote host. Get works with either a SERVER or a KERMIT that has initiated a SEND command. Filespec is a filename compatible with that system. When Model 4(p) KERMIT is talking to a KERMIT Server, you may include a filespec in a form legal to the HOST KERMIT. 6.10. INPUT <control string> INPUT provides one of 4 commands that provide an automatic logon facility. INPUT allows you to watch for the occurrence of certain text strings that are made up characters arriving in the com- munications port. This is useful in TAKE files that can automatically log you onto a certain sys- tem. - 9 - When INPUT in initiated, it begins matching characters in the input to those given in the con- trol string. When an exact match is found as established by the SET INPUT options then INPUT will return to the KERMIT command level. If TAKE is active than the next line of the TAKE file will be read. The Control string may be comprised of any printable ASCII characters. SPACE must not occur as either the beginning or end of the string. ASCII character codes 0-32 are denoted as <NUL> - <SPA>, and <DEL> represents character 127. The string <DLY*> signifies an immediate delay. The * should be replaced by a character. The sig- nificance of the character is this. Decimal 48 is subtracted from the ASCII value of the character to obtain the number of seconds to delay. Thus, you can obtain delays 1-9 seconds, with no trick- ery. Delays longer than that will have to be cal- culated since the formula (ASCII code - 48 decimal) is used to calculate the binary value to use as a counter. The "*" should be replaced with the single proper ASCII character. If you use <DLY*> in a PULSE command, it should be noted that it will only be done once. An alternative format for control characters is to explicitly type a carat ("^") preceding a charac- ter. The result of subtracting 64 from the ASCII code for the character following will then be used. Since <, >, and ^ now have special mean- ings, you will need some way to specify them explicitly. To do this you should precede them with a backslash, "\", character. In this case, backslash itself now must be represented as "\\". Finally, any and all characters can be represented using a string of the form \nnn where nnn is 1 or more octal digits. nnn is evaluated, and the resulting value will be the ASCII value of the character. Some examples might be: INPUT login:<SPA> Find the string "login:" followed by a space. INPUT <SPA>^M^Jenter \\userid\\:<CR><LF> Find the string with a space followed by a carriage return followed by a line feed followed by the text "enter \userid\:" followed by carriage return and another linefeed. - 10 - INPUT USERNAME\77\40 Find the string "USERNAME? ". Note that \77 is the ONLY way that a question mark can be specified since a question mark is recognized by the command stream as a request for help. While input is waiting for a match, you may type characters on the keyboard to be transmitted. BREAK will abort the INPUT command and if TAKE is active, close the take file. ESCAPE will abort the INPUT command, but will just skip to the next line in a TAKE file, if TAKE is active. These same 2 actions apply to the PULSE command while no input has been received. 6.11. KILL wildspec This command performs the task of deleting one or more files from disk. Wildspec is a wild card filespec that will be evaluated. All files that match the wildspec will be removed. A wildspec may contain any characters valid is a TRSDOS filespec, plus zero or more occurances of the characters '*', and '$'. These two characters have special meanings. When comparing the wildspec with the name of a file, a '*' matches zero or more of the charac- ters in the filename. E.g. If a file FOO/ASM is compared with '*/ASM', then it would match, because '*' can be thought of as 'FOO', and then '/ASM' is matched literally. M4*/ASM matches M4MIT/ASM, M4XFER/ASM, M4SEND/ASM, and any other filename that begins with M4, and ends with /ASM. The '$' character matches any single character. This means that FILE$/DOC matches the filename FILE1/DOC, but not FILE1A/DOC. A drivespec may be appended to the wildspec to force the search for matches to be restricted to a single drive. An example might be M4*/ASM:1, which limits the matches to those file on drive 1. Normally, only visible, nonsystem files are considered in the search. However, the inclusion of a parameter list containing either, or both of the keywords, INVIS or SYSTEM, will include invisible and/or system files. An example would be: KILL (I,S) config/sys (I) backup/cmd This example would cause Model 4(p) KERMIT to attempt to remove the two files listed. Note that - 11 - as this example shows, you must specify the param- eters with each wildspec that you wish to apply them to, as they are nullified each time that a new wildspec is evaluated. Other examples are given in the description of the SEND command. 6.12. LOCAL <TRSDOS library command> (Can be abbreiviated to L) This command allows you to issue commands from within Model 4(p) KERMIT. You must remember where Model 4(p) KERMIT resides in memory, to assure that you do not overwrite it. KERMIT loads at 6000H, and continues up through LOW$. From within KERMIT, you can issue the command: LOCAL MEMORY to see where KERMIT ends. The value of LOW$ tells you this information. KERMIT was placed at 6000H to allow most of the TRSDOS library programs and commands to work in conjunction with KERMIT. Some commands extend above 3000H, and must have memory available up to approximately 5300H. The COPY command creates a problem because it apparently tries to examine HIGH$ to see if there is space to load a large portion of the source file into memory before writing it to the destination. This creates problems because KERMIT moves LOW$ up so that HIGH$ has a value that will allow additional high memory module to be loaded. It is suggested that you not use COPY while KERMIT is running, as the machine may crash when COPY completes. This is because it will have copied data into the KER- MIT memory space. 6.13. LOG 6.13.1. DEBUG-LOG The debug log can be used to debug transfer problems that sometimes arrise when talking to a newly written KERMIT. The information written to the DEBUG-LOG is nearly identical to that which is displayed on the screen when the command, SET DEBUG ON, is issued, or the CTRL-D key is pressed during a transfer. This file can be closed explicitly with the CLOSE DEBUG-LOG command. The EXIT command also causes an implicit closing of this file. - 12 - 6.13.2. SESSION-LOG When CONNECTed to a foreign host as a termi- nal, this command establishes a log of the terminal session in the file specified. This function depends, to some extent, on the remote host's ability to do XON/XOFF flow control. Without FLOW-CONTROL, data may be lost when KERMIT writes to the file. The log file is closed by explicitly typing the KER- MIT command CLOSE SESSION-LOG or implicitly when KERMIT is exited via the EXIT command. It will also be closed if an I/O error occurs in file processing for the file involved. LOGGING may be toggled on and off during CON- NECT using the sequence of keys described in the CONNECT description. 6.13.3. TRANSACTION-LOG The transaction log is used to keep a record of the files transfered during a KERMIT ses- sion. The information includes whether or not the transaction was SENDING, or RECEIV- ING, the name of the file transfered, and the number of bytes involved in the transfer. 6.14. LOGOUT Logout tells a remote kermit server to terminate itself, as well as your login session. When this is completed, you are left at Model 4(p) KERMIT command level. 6.15. OUTPUT <control string> This is the other side of the INPUT command. Con- trol string follows the same conventions as in INPUT, and the resulting character(s) will be out- put to the communications port immediately. It should be noted that NO characters other than what you specify are transmitted. In other words if you want to simulate typing some string, followed by pressing <ENTER>, then you will have to use a command similar to: OUTPUT mypassword<CR> The <CR> will explicitly send the ASCII character 13 to the communications port. - 13 - 6.16. PAUSE <number of seconds> This command is usually used in conjunction with INPUT, OUTPUT, and PULSE as a means of syncroniz- ing Model 4(p) KERMIT to a remote host. A delay of the specified number of seconds will be gen- erated based on the accuracy of the 60HZ inter- rupt. No means has been made for aborting the delay. The maximum delay is 65536 seconds by specifying 0 as the number. 6.17. PULSE <control string> This command is an extension/combination of INPUT and OUTPUT. It allows you to transmit one or more characters repeatedly until a character appears in the input port. The use of this command is valu- able when logging onto systems that don't always respond immediately after the reception of some control character(s). For instance, you might (Now that all of the functions of this nature have been described) use the following commands as part of a logon sequence to log onto a computer system. SET INPUT CASE-IGNORE ON SET INPUT DISPLAY ON SET OUTPUT HOST-ECHO ON SET OUTPUT DISPLAY ON CLEAR INPUT-PORT PULSE ^T<CR> INPUT <CR><LF>XYZ: PAUSE 2 CLEAR INPUT-PORT PULSE <CR> INPUT Username:<SPA> OUTPUT joeblow<CR> INPUT <CR><LF>Terminal type: OUTPUT h19<CR> SET KEY 8 <DEL> SET KEY 128 <ETX> After you study this awhile, it should make sense. If these commands are placed into a TAKE file, then you could use a CONNECT command after the last command, to connect immediately to the host. If this is done, then only after you escape back to Model 4(p) KERMIT, will the TAKE file finally be closed. 6.18. RECEIVE <filespec> This command is synonomous with the GET command. It may be abbreviated to the single character 'R', as in: - 14 - R *.asm 6.19. REMOTE <command> Remote commands are not supported in totality by all servers. If a server supports remote com- mands, then remote help should display all of the commands available to the remote user of the server. Below are descriptions of the remote com- mands that Model 4(p) KERMIT knows how to send to a remote server. The arguments to most commands are dependent on the remote system. You should be familiar with any system before using the remote server commands available from that server. Usu- ally only a small number of these commands are supported since some require abilities that some operating systems just don't have. 6.19.1. CLOSE-LOG Close a remote LOG previously opened via the command REMOTE START-LOG. 6.19.2. COPY Copy one file to another. 6.19.3. CWD <directory path> If a particular server's operating system supports the concept of separate directories, then this command will allow you to change to a different directory. 6.19.4. DELETE Deletes file(s) from the remote system. Any arguments will probably be file names in the format of the remote system. 6.19.5. DIR Display a list of files on the remote system. 6.19.6. DISK Display information about disk utilization on the remote system. - 15 - 6.19.7. HELP Get information about remote capabilities on the remote system. 6.19.8. HOST Execute a command on the remote system. 6.19.9. KERMIT Execute a KERMIT command on the remote sys- tem. This command should accept a normal KERMIT command as an argument. The command, if valid, will then be executed by the remote KERMIT server. 6.19.10. LOGIN Create a login entity on the remote system. This may be incorporated into a dedicated server. 6.19.11. MESSAGE Send a message to a user on the remote sys- tem. 6.19.12. PROGRAM Feed command input to a command executing on the remote system, or control the execution of a program. 6.19.13. QUERY-VARIABLE Get the value of a variable maintained on the remote system. 6.19.14. RENAME Change the name of a file on the remote sys- tem. 6.19.15. SEND-LOG Tells the server to close any open log, and then transfer it to the user. 6.19.16. SERVER-STATUS Retrieve certain information about the status of a REMOTE server. The information returned is dependent on the REMOTE system. - 16 - 6.19.17. SET-VARIABLE Set the value of a variable on the remote system. 6.19.18. START-LOG Start a transaction log on the remote system. 6.19.19. STOP-LOG Stops logging to the log file started by the REMOTE START-LOG command. The file is not closed. Logging may be started again by using the the command, REMOTE START-LOG. 6.19.20. TYPE Display the contents of the file/files given as arguments. The remote server should use the KERMIT protocol to send the contents of the specified file/files to Model 4(p) KER- MIT. The file contents will be displayed on the screen using the *SO device. 6.19.21. WHO Display a list of users on the remote system. 6.20. SEND <wildspec> (May be abbreviated to 'S'); File specifications may contain wild card charac- ters. The recognized wild card characters are '*' and '$'. '*' means zero or more of any character. '$' means exactly one of any character. There are a lot of specifics associated with wild carding, and search order through the drives. When files by the same name exist on dif- ferent drives, a wild card match of one will also match all other occurances. e.g. if drive 0 con- tains the file report/dat, and report.dat also exist on drive 1, then the command other varia- tions can be used to send only one of the 2 files. 'SEND */dat:1' will only match files on drive 1. Another alternative would be Case is NOT significant, so both REPORT/DAT and report/dat are identical. so "*/*" is the same as "*" for all file names with an extension. "*/*", however, does not match names of the form "data", "fred", "file", "temp", or others without extensions. Other examples are given in the - 17 - description of the KILL command. 6.21. SET <parameter [value(s)...]> Set the specified parameter to the specified value. Possible settings: 6.21.1. BELL ON (or OFF) When DUMB terminal emulation is in effect, a simple noise generator is used to produce a tone like a bell each time the BELL character is received. If you don't like it, than use SET BELL OFF to disable it. 6.21.2. BLOCK-CHECK-TYPE The options are: 6.21.2.1. 1 (character checksum) Normal, default, standard 6-bit check- sum. 6.21.2.2. 2 (character checksum) A 12-bit checksum encoded as two charac- ters. 6.21.2.3. 3 (character crc-ccitt) A 16-bit CCITT-format Cyclic Redundancy Check, encoded as 3 characters. The 2 and 3 character options should only be used under conditions of extreme line noise. Many implementations of KERMIT only support the single character checksum. 6.21.3. DEBUGGING OFF (or ON) When transmitting or receiving packets, con- trols whether the packets are displayed on the local screen. 6.21.4. DEFAULT-DISK <drive number> The default-drive value is used for received files. The file names created by Model 4(p) KERMIT will have a ':' and the default drive number affixed to the end so that they will be forced to be saved on the selected drive. - 18 - 6.21.5. EIGHT-BIT-QUOTING ON (or OFF) This command enables or disables 8th bit quoting. This is useful when a full 8 bit path is available for binary file transfers. 6.21.6. EMULATION NONE (or DUMB) When connected as a terminal to a foreign host, SET EMULATION controls whether the Model 4 emulates no terminal, allowing the use of a terminal filter, or whether a DUMB terminal emulation is used. No emulation is the default. 6.21.7. ESCAPE Change the escape character for virtual ter- minal connections. Model 4(p) KERMIT will prompt you for the new escape character, which you type in locally. 6.21.8. FILE 6.21.8.1. DISPOSITION KEEP (or DISCARD) When the transfer of a file is inter- rupted, this tells Model 4(p) KERMIT what to do if it receives only a partial file. If FILE-DISPOSITION is DISCARD, then any partial file is removed. Oth- erwise, the file is left as it is when a transfer is interrupted. 6.21.8.2. TYPE (ASCII or BINARY) Tells Model 4(p) KERMIT how to deal with the file being sent/received. It is IMPORTANT to tell KERMIT if the file is in ASCII when sending to a NON Model 4(p) KERMIT. The action taken with this value is as follows. If ASCII mode is set, then CR-LF pairs of characters are translated to CR on input, and CR is translated to CR-LF on output. When binary mode is in effect, this transla- tion does not occur. 6.21.9. FLOW-CONTROL XON/XOFF (or NONE) When this feature is set to XON/XOFF (the default), Model 4(p) KERMIT will try its best to obey and use XON characters and XOFF char- acters for all transmitions through the - 19 - communications port. NONE will disable all attempts at this sort of flow- control. 6.21.10. INPUT 6.21.10.1. CASE-IGNORE OFF (or ON) Controls whether of not case matching is done on characters during the input com- mand. In most instances, you will want this ON. 6.21.10.2. DISPLAY OFF (or ON) Controls the display of characters that are input during the execution of the INPUT command. 6.21.11. KEY <key value> <string> This command allows you to send an arbitrary (the length of the KERMIT command line is the limit) string with a single key stroke. The definition of string is identical for that of the INPUT, OUTPUT, and PAUSE commands. KEY VALUE is the ASCII value of the key stroke as given in the TRSDOS manual. If KEY VALUE is not given, then you will be asked to press the key corresponding to the key that you wish to define. All keys are valid in string except BREAK. Pressing BREAK signals the end of the definition string. While in CONNECT mode, typing the defined key will cause the characters typed as the definition to be typed instead. Defining a key to have a NULL length deletes any previous definition. 6.21.12. LOCAL-ECHO OFF (or ON) When you CONNECT to a remote host, you must set LOCAL-ECHO ON if the host is half duplex, OFF if full duplex. 6.21.13. OUTPUT 6.21.13.1. HOST-ECHO ON (or OFF) When using OUTPUT, and communicating with a remote host, the host commonly echoes the characters as you type. Since OUTPUT effectively types charac- ters for you, these characters may be echoed back. If HOST-ECHO is ON, OUTPUT will wait for the echoed character to - 20 - reappear in the input buffer before it sends the next. In the example for send- ing and receiving raw data, that is above, setting HOST-ECHO ON, will enable us to remove the INPUT TYPE MYPROG.DAT<CR><LF> command. Control characters are NOT normally echoed, so this feature when set ON, will not wait for them. If you must catch the echo of a control character, then follow the OUTPUT command with the appropriate INPUT command. 6.21.13.2. DISPLAY OFF (or ON) This parameter when on controls the display of characters that are received when HOST-ECHO is ON. Otherwise, They are displayed based on the status of the LOCAL-ECHO setting. 6.21.14. PRINTER OFF (or ON) Turns copying of CONNECT session to printer on and off. With FLOW-CONTROL turned on, and a sending host that will acknowledge the XOFF, you should have no problems using the printer continuously. 6.21.15. RECEIVE 6.21.15.1. END-OF-LINE <ASCII code> Set the end of line character in packets to some other character than <CR> which is the default. 6.21.15.2. PAD-CHAR <ASCII code> If the host you are communicating with needs one or more padding characters before it receives actual data during packet transfers, this character will be sent PADDING times. 6.21.15.3. PADDING <decimal number> The repeat count for the number of times the padding character is transmitted. 6.21.15.4. QUOTE-CHARACTER <ASCII code> The character used to quote control characters. The default is pound "#" - 21 - 6.21.15.5. START-OF-PACKET <ASCII code> The character used to syncronize the packets that KERMIT transmits. By default <SOH>. 6.21.15.6. TIME-OUT <decimal number> Model 4(p) KERMIT uses this value as the number of seconds to wait for a response to a packet. If no response is received within the number of seconds given, then the packet for which the response has not been received is retransmitted. 6.21.15.7. TURN-CHAR The character used to syncronize KERMIT when used over a half duplex line. Model 4(p) KERMIT will wait for this character at the end of a packet, and will send the SEND TURN-CHAR at the end of a packet. 6.21.16. SEND 6.21.16.1. END-OF-LINE <ASCII code> Set the end of line character in packets to some other character than <CR> which is the default. 6.21.16.2. PAD-CHAR <ASCII code> If the host you are communicating with needs one or more padding characters before it receives actual data during packet transfers, this character will be sent PADDING times. 6.21.16.3. PADDING <decimal number> The repeat count for the number of times the padding character is transmitted. 6.21.16.4. QUOTE-CHARACTER <ASCII code> The character used to quote control characters. The default is pound "#" 6.21.16.5. START-OF-PACKET <ASCII code> The character used to syncronize the packets that KERMIT transmits. By - 22 - default <SOH>. 6.21.16.6. TIME-OUT <decimal number> This value is given to the other host as its' timeout value. You should assure that this is different from the RECEIVE TIME-OUT value so that both timeouts do not occur simultaneously. 6.21.16.7. TURN-CHAR <ASCII code> The character used to syncronize KERMIT when used over a half duplex line. Model 4(p) KERMIT will send this charac- ter at the end of a packet. The RECEIVE TURN-CHAR will be waited for before data is transmitted. 6.21.17. TAKE-DISPLAY OFF (or ON) Controls the display of TAKE files as they are executed. By default this feature is off. 6.21.18. WARNING ON (or OFF) Warns user if filename conflicts when receiv- ing files from remote host, and attempt to generate a unique name by modifying the given one. ON by default. 6.22. SETCOM <TRSDOS SETCOM command parameter> Sets/shows the status of the communications driver, COM/DVR. If no arguments are given, than the current status will be shown. Any arguments must be enclosed in parenthesis as the result of this command, is a generated TRSDOS command as in: SETCOM (B=9600,P=N,W=8) The default values are established according to you. If you set up the driver for a certain con- figuration, and then use SYSGEN to save it, then that will be the default. NO sysgen should give you: 300 BAUD EVEN PARITY DTR=YES 7 DATA BITS 1 STOP BIT - 23 - 6.23. SHOW Allows one or ALL of the options of the SET com- mand to be displayed. Using the "?" feature will aid you if you can't figure out where to find something. All of the things that can be SET can be displayed. The items not listed below can be displayed by using a command like: SHOW BLOCK or SHOW DEFAULT SHOW ALL will display all of the set values except keys. You must use SHOW KEY to see these values. 6.23.1. SEND Displays all options described under the SET SEND command. 6.23.2. RECEIVE Displays all options described under the SET RECEIVE command. 6.23.3. KEY <ASCII key value> If <ASCII key value> is specified, then the defin- ition for the specified key number is display. Otherwise, a prompt is issued for the user to type the keystroke that should be taken as the key to display. \nnn is used to display all values greater than 127. ^x where x is a character 64 greater than 0 through 31, and 127 is used to display control characters. Any other printable ASCII character is displayed normally. 6.24. STATUS Shows certain information about the status of Model 4(p) KERMIT. Items currently displayed include the amount of space left in the KEY definition table, the number of bytes written to files during transfers, the number of bytes read from files during transfers, as well as statistics on the latest transfer. 6.25. TAKE <filespec> TAKE allows commands to be stored in a file, and then executed by the KERMIT command interpreter. Only one level of TAKE files is supported. This means that a - 24 - TAKE command can not appear inside of a TAKE file. No checking is done to enforce this, so good luck if you want to try it. When KERMIT is first entered, a check is made for a file called KERMIT/INI on all of the active disk drives as per normal TRSDOS searching order. If it is found, than it is used as a TAKE file where you can store initialization commands. Pressing the BREAK key, or the ENTER key during the startup of KERMIT (before the TAKE file is opened) will cause KER- MIT to skip processing of the TAKE file. 7. Setting up to use Model 4(p) KERMIT To use Model 4(p) KERMIT, you need to have your Model 4 set up properly. The program expects that the *CL device will be driven by the COM/DVR Communications Driver that comes with TRSDOS. It also expects that the *SO device is ROUTED to the *DO device, and that the *SI device is ROUTED to the *KI device. The former 2 are the defaults, and in general, you should not worry about them, unless you have changed them. Setting up the *CL device involves typing the command: SET *CL COM/DVR at the TRSDOS Ready prompt. If you do not do this, you will get a message of the form Can't find *CL DCB from Model 4(p) KERMIT when it is starting up. The program will return control to TRSDOS after issuing this message, as it is a fatal error. Model 4(p) KERMIT is not a small program. It occupies memory starting at 6000H, and extends up past 0D300H. If you have parts of TRSDOS resident (Using the SYSTEM (SYSRES=....) command), or perhaps other filters or memory resident modules, then you should make sure that they do not extend below the maximum address used by the program. The last memory address used by Model 4(p) KERMIT can be obtained by using the command LOCAL MEMORY from within the Model 4(p) KERMIT program. - 25 - 8. Installation To install Model 4(p) KERMIT, you must obtain the two files M4BOO.BAS and M4MIT.HEX. Because of the size of the executable, the hex file could not be placed into a basic program as data statements. Instead, the basic program opens and reads the file M4MIT.HEX. This file is an ASCII image of the executable. All that needs to be done, is to run the BASIC program which will convert the file back to its original binary format. The resulting executable should probably be called KERMIT/CMD. Follow the prompts of the BASIC program and there should not be any problems. 9. Building Model 4(p) KERMIT from the Source. The Source for Model 4(p) KERMIT is in approximately 15 modules. The names of the modules are: M4ADD/ASM Code for miscellaneous routines. M4CMD/ASM Command parser code. M4EQU/ASM Mosts constants are defined here M4FILE/ASM Additional logfile code such as the LOG command, and the CLOSE command. M4GET/ASM Receive file routines + other miscel- lany. M4KEY/ASM Code for handling the SET KEY functions M4LOG/ASM INPUT, OUTPUT, PAUSE, PULSE commands. M4MAC/ASM Macros used in the program M4MIT/ASM Main entry and some command routines. M4PKT/ASM New packet routines for encoding and decoding packets. M4RMT/ASM The base of what will be the remote com- mand. M4SEND/ASM Send file routines. M4SET/ASM Set options routines. M4SHOW/ASM Show settings routines. M4STR/ASM The majority of storage, prompts, and messages. - 26 - M4TERM/ASM Terminal Emulation, and I/O routines. M4WILD/ASM Wild card file name processing. M4XFER/ASM File processing, and some packet stuff. Model 4(p) KERMIT was developed using the EDAS assem- bler from Misosys. Other macro assemblers should be able to assemble the program with minor conversions. M4MIT/ASM is the main source module. It will call the other source files into the assembly (using the *GET directive) as needed. If any system calls need to be changed, they are all defined in M4ADD/ASM for the most part. All of the SVC's are coded in M4ADD/ASM as subroutines that are accessed by CALL Xaaaaa, where aaaaa is the name of the TRSDOS supervisor call (SVC) without the "@" sign. If this version is moved to another OS, there are several things that you should consider. The things that come to mind are: 1. Consider the format of the TRSDOS directory struc- ture. The wild card routines depend on this structure for validating directory entries, and for retrieving the file name. 2. There are 2 places where real time counting is required. The delay specified in a PAUSE state- ment can be handled with a counter, as all other processing is halted (except the interrupt tasks) during the pause. Currently, the Real Time Clock task is used to measure the appropriate delay. The other use of a Real Time counter occurs in the Receive packet timeout. This must be handled using asyncronous processes in order to be accu- rate. 3. There exist code at the beginnning and end of the segment that accesses the screen which outputs the bytes 14, and 15 to the *DO device. These are used to force the cursor to be invisible before the screen is accessed, and to then make it reap- pear after the screen access is completed. 4. The interrupt driven receiver must also be delt with. The code in the routine SETINT, establishes the interrupt vector that the *CL driver will call when a "character received interrupt" is gen- erated. 5. In many instances, the characters having values 16, and 17 are used to enable, and disable reverse video respectively. If the driver for *DO does - 27 - not recognize this convention, as the current one does, then these characters must be handled in some manner. I.E. either removed from the source, or filtered from the terminal output stream. The PRTSTR() routine is a good place to mask these characters at, as it is the sole source of output for strings containing these type of characters. It should be noted that KERMIT/CMD loads into RAM at 6000H. This avoids high memory filters and drivers, and also allows use of TRSDOS library commands that use low memory beyond 3000H, as FORMAT, and BACKUP do. Exclusive use is made of the *DO device for screen output from the KERMIT program, for informational messages and the like. During connect mode, *SI and *SO are used as the input and output devices to allow filters to be attached that will not effect the operation of Model 4(p) KERMIT during command operations. If you install a different driver or filter it must be compatible in these areas. 10. Performance Specifics of Model 4(p) KERMIT The Model 4(p) KERMIT has been tested and proven to work properly at 9600 BAUD with flow control on, transfer- ring files between 2 Model 4's. What makes the Model 4(p) KERMIT perform so well is the idea of flow control, and the interrupt driven receiver. With out these features, I expect that 2400 baud would be the reliable limit. Flow control can be disabled at speeds less than or equal to ~2400 baud, but greater speeds require that flow control be functional in order to protect the integrity of data in the input buffer. 11. The Heath 19 Filter The files M4H191.ASM, M4H192.ASM, M4H19.MAC, and M4H19.EQU make up the sources for a Heath 19 terminal emula- tion filter for the TRS-80 Models 4 and 4p. The assembler used was EDAS by Misosys. To build the filter from sources, you need the above 4 files on a disk. M4H191.ASM is the main source module, and it *GETs all the other necessary files. The structure of the program is pretty simple. Single character (non escape) sequences, are passed to the filtered device via the @CHNIO svc. This filter depends on the TRSDOS *DO driver being at the end of the chain. Several control characters are merely translated, and then the new values are passed to *DO. - 28 - A multi-character escape sequence is handled by remembering the previous characters that the filter was passed. The previous characters are remembered by the pres- ence of a non-zero value in the contents of STATE. The value in STATE represents the address of the code to handle the next character, given the previous string of characters. The filter is relocatable, but MUST reside below screen memory because it accesses it directly when performing several of the advanced terminal functions. For this rea- son, it will never load above F3ffH. 12. The SETH19 Program The SETH19 program allows you to configure a few options that are available to you when using the H19 filter. The SETH19 program is created from the sources M4H19S.ASM, M4H19.EQU, and M4H19.MAC. M4H19S.ASM is the main source module, and will *GET the other 2 files. The program sup- ports a few parameters that are listed below. REMOVE Remove and reclaim if possible. DURATION Length of BELL tone. FREQUENCY Frequency value (bigger value is lower tone) for BELL. BELL Turn audible BELL ON or OFF. BLOCK Block cursor character. CURSOR Normal cursor character. STRIP8 Control display of 8 bit data. HELP Displays information similiar to this. SHOW Displays the current settings of the parameters, this is the default. These options are specified when you invoke SETH19, as per the usual TRSDOS 6.x parameter list. An example is shown below: SETH19 (BLOCK=191,CURSOR=23,BELL=ON,SHOW) This command sets the normal CURSOR, and the edit mode CURSOR values, as well as turning the audible bell on. The show parameter causes 2 lines similiar to those below to be printed on the screen. Normal Cursor: 23, Block Cursor: 191 - 29 - Bell: ON, Frequency: 20, Duration: 120 Strip8: ON The REMOVE option takes several things for granted, as it tries to thoroughly remove the device. It assumes that the H19 filter is attached to the *HP device, and that this device is a filter hooked to *SO. Further more, it assumes that *SO is routed to *DO. This particular set up can be used easily if the fol- lowing commands are used to set up the filter: SET *HP H19/FLT FILTER *SO *HP This is assuming that *SO is routed to *DO. The SETH19 com- mand will perform these very operations if you invoke it, and the memory module, $HEATH, is not in place. The other parameters to the SETH19 command can be used to control certain preferable options to the filter. Set- ting BELL off causes the filter to flash the screen when it receives an ASCII(7) character. If BELL is set ON, then an audible bell is issued when an ASCII(7) is received. When BELL is ON, then the DURATION, and FREQUENCY parameters take effect. These 2 parameters select the length and pitch, respectively, of the BELL tone. The FRE- QUENCY value is used as a delay between oscillations of the sound port, so the bigger the number, the lower the tone will be. The default DURATION is set to 20, and the FREQUENCY is set to 125. You can adjust them as you please. The DURA- TION is inversely proportional to the FREQUENCY, since the delay caused by the FREQUENCY value is part of the overall DURATION of the sound. This means that as you increase FRE- QUENCY, you must decrease DURATION to maintain the same length of BELL, and vice-versa. The BLOCK and CURSOR parameters are used to control the characters that are used as the cursor by the H19 filter. The H19 terminal has the ability to use a visual mode cur- sor, or a line mode cursor. Since the normal visual mode cursor is usually a block cursor, the parameter BLOCK is used to set the ASCII value of the visual mode cursor. The CURSOR parameter sets the normal line mode cursor. The switch between cursors must be done by the HOST computer that is attached to the Model 4's communications port. There is no magic to when the BLOCK cursor is selected, see the description of the recognized control sequences below. - 30 - The STRIP8 parameter controls whether or not data is printed on the screen with the eighth bit set. Normally, the filter now trims the eighth bit off so that parity can be ignored. The command SETH19 (STRIP8=NO) will cause the eighth bit to not be stripped. That is to say, data will be used as it is received by the filter. Note that when this is done, some control characters with parity bits attached may not be recognized. 13. Future modifications It should be fairly straight forward to build extra states into the filter so that it will recognize the ANSI 3.64 sequences for the operations the filter knows how to perform. Full support of all the ANSI 3.64 sequences would be a non-trivial investment in time. The best bet here would, be a completely new device driver, since the overhead of going to *DO is already costly, and trying to implement scroll regions with *DO would be a HACK at best. If some- body wants to do the conversion, I would like to have a copy of the result. 14. HEATH-19 filter capabilities The HEATH-19 terminal supports several advanced video capabilities that make it an ideal source for a terminal emulation package. Below is a list of the functions sup- ported by the Model 4(p) H-19 emulator, and the escape sequences that perform the operations. 15. Heath/Zenith-19 Control Codes The Heath/Zenith-19 terminal is equivalent to the DEC VT52 with extensions for line and character insertion and deletion. Items marked with an asterisk are not currently supported by Model 4(p) H19 emulation. Cursor Functions Sequence Mnemonic Definition ESC H HCUH Cursor Home ESC C HCUF Cursor Forward ESC D HCUB Cursor Backward ESC B HCUD Cursor Down ESC A HCUU Cursor Up ESC I HRI Reverse Index *ESC n HCPR Cursor Position Report ESC j HSCP Save Cursor Position ESC k HRCP Set Cursor to Previously Saved Position - 31 - ESC Y HDCA Direct Cursor Addressing, 1-based: 31+line# 31+col# (same as VT52) Erasing and Editing Sequence Mnemonic Definition ESC E HCD Clear Display (Shift Erase) ESC b HBD Erase Beginning of Display ESC J HEOP Erase to End of Page (Erase Key) ESC l HEL Erase Entire Line ESC o HEBL Erase Beginning of Line ESC K HEOL Erase to End of Line ESC L HIL Insert Line ESC M HDL Delete Line ESC N HDCH Delete Character ESC @ HEIM Enter Insert Character Mode ESC O HERM Exit Insert Character Mode Configuration Sequence Mnemonic Definition *ESC z HRAM Reset to Power-Up Configuration *ESC r Bn HMBR Modify Baud Rate: Bn= A=110, B=150, C=300, D=600, E=1200, F=1800, G=2000, H=2400, I=3600, J=4800, K=7200, L=9600, M=19200 ESC x Ps HSM Set Mode(s): Ps= * 1 = Enable 25th line * 2 = No key click * 3 = Hold screen mode 4 = Block cursor 5 = Cursor off * 6 = Keypad shifted * 7 = Alternate keypad mode 8 = Auto line feed on CR 9 = Auto CR on line feed ESC y Ps HRM Reset mode(s): Ps= * 1 = Disable 25th line * 2 = Enable key click * 3 = Exit hold screen mode 4 = Underscore cursor 5 = Cursor on * 6 = Keypad unshifted * 7 = Exit alternate keypad mode 8 = No auto line feed 9 = No auto CR - 32 - *ESC < HEAM Enter ANSI Mode Modes of Operation Sequence Mnemonic Definition *ESC [ HEHS Enter Hold Screen Mode *ESC \ HXHS Exit Hold Screen Mode ESC p HERV Enter Reverse Video Mode ESC q HXRV Exit Reverse Video Mode *ESC F HEGM Enter Graphics Mode *ESC G HXGM Exit Graphics Mode *ESC t HEKS Enter Keypad Shifted Mode *ESC u HXKS Exit Keypad Shifted Mode *ESC = HAKM Enter Alternate Keypad Mode *ESC > HXAM Exit Alternate Keypad Mode Additional Operations Sequence Mnemonic Definition *ESC } HDK Keyboard Disable *ESC { HEK Keyboard Enable *ESC v HEWA Wrap Around at End of Line *ESC w HXWA Discard at End of Line *ESC Z HID Identify as VT52 (ESC / K) *ESC ] HX25 Transmit 25th Line *ESC # HXMP Transmit Page Enhanced Character Support ESC [ p1 ; ... pn m Set Graphics Rendition where p1, ..., pn are chosen from the following: *0 Reset to normal character display. *1 Display characters in high intensity. *4 Display characters underlined. *5 Display characters blinking. *7 Display characters in reverse video. The Heath-19 transmits the following sequences, but it will not respond to them if they are received. Model 4(p) Kermit will transmit them only if they are programmed with SET KEY. ESC S HF1 Function Key #1 ESC T HF2 Function Key #2 ESC U HF3 Function Key #3 ESC V HF4 Function Key #4 ESC W HF5 Function Key #5 ESC P HF7 Function Key #7 - 33 - ESC Q HF8 Function Key #8 ESC R HF9 Function Key #9 My thanks to Michael Carter and Roland Stolfa for their help in testing and debugging this implementation. Gregg Wonderly Department of Computing and Information Sciences Oklahoma State University UUCP: {cbosgd, ea, ihnp4, isucs1, mcvax, uokvax}!okstate!gregg ARPA: gregg@A.CS.OKSTATE.EDU