APDL Public Domain 1

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

/ APDL Public Domain 1 / APDL_PD1A.iso / comms / a_l / kermit / Kermit_man < prev next >

Wrap

Text File | 1989-03-16 | 51.8 KB | 1,439 lines

Arc-Kermit - Documentation ============================ 1. Introduction ---------------- This documentation briefly describes Archimedes C-Kermit, which was derived from QL-Kermit version 2. It incorporates most of the features of that program, with some general and some Acorn- specific additions, and some minor changes. As with the earlier documentation, it is assumed that the reader is reasonably familiar with Kermit concepts and how to use a "standard" Kermit program. This version of Arc-Kermit (referred to from here on as 'Arc-K') comprises about 150K bytes of C and Basic (assembler) source, compiling to about 100K bytes of object code (good old RISC architecture!). It is believed that the object will run on all machines from the A305 upwards, although a larger configuration will ease compilation or development work considerably. Refer to the Building Arc-Kermit section for information on building Arc-K from source. 2. Capabilities at a Glance ---------------------------- Local operation Yes Remote operation Yes1 Transfer text files Yes Transfer binary files Yes Wildcard send Yes ^X/^Z interruption Yes Filename collision avoidance Yes Can time out Yes 8th-bit prefixing Yes Repeat count prefixing No Alternate block checks No Terminal emulation Yes Communications settings Yes Transmit BREAK No IBM mainframe communication No Transaction logging No Session logging No Raw transmit No Act as server Yes Talk to server Yes Advanced server functions Yes Advanced commands for servers Yes Local file management Yes Handle file attributes No Command files Yes Command macros No XON/XOFF flow control No Split baud rates Yes I have not implemented some of these features for various reasons: (a) they are not relevant to my intended use of Arc-K; (b) they would be impossible to implement on the Archimedes hardware (e.g. transmit BREAK); (c) they may be implemented at a later date. Note: At present Arc-K has only been tested transferring files to and from a BBC running Lancs-Kermit (version 1.45), therefore the only extensively tested features are those which are exercised by this configuration. I cannot guarantee that other facilities work well enough, if at all. 3. Using the program --------------------- Assuming that the binary version of Arc-K has been obtained or built, it can be run in the standard way; the simplest is to name the object file "kermit" and put it into the library directory (usually $.Library), from where it can be run simply by the command "kermit". Before running Kermit, the utility module must be installed. This only needs to be done once, using the LOAD or RMLOAD commands. If this module is not installed, Kermit will refuse to start up, giving an error message. It is also recommended that the RS423 fix module (the latest version - 1.24) is installed. Leave this out only if you wish to extensively test the error correction features of Kermit! When invoking Kermit from Arthur, the following control arguments are accepted on the command line: -n Don't execute the default startup file. -c file Take and execute commands from the given 'file'. If -n is not given, i.e. if the default startup file is to be executed as well, this file will be executed after the default one. -q Don't enter the interactive command parser, i.e. exit as soon as any startup file and command file have been executed. -c will normally be used with this option. -r Start up in remote mode (see DETACH in §4) by default. Assuming that the modules are installed correctly, the [Archimedes or remote terminal] screen will clear and the version is displayed. At this point, unless the -n flag has been given, Kermit will execute a startup file which will typically contain a series of SET commands to configure Arc-K for the intended application. As supplied the file searched for is "%.KermitInit"; it can be altered to look for a different file by changing the symbol DFTAKE in the header file kermit.h and recompiling. When this startup file has ended, or if none is found, any command file specified with -c will be executed. After executing these files, unless the -q argument has been given, the prompt "Arc> " will be displayed. (Fairly) standard Kermit commands can now be entered; these are listed in the next section. The following control keys can be used to control and edit command lines. When running in local mode, either the function keys or the alternatives can be used, according to personal preferences; it will be necessary to use the alternatives if Arc-K is being run in remote mode. F1 (HELP) When pressed at the beginning of a field, indicate what this field needs to be completed with, or display a list of options. Alternative: ? F2 (DELETE WORD) Delete the "word" (back to the previous space) before the cursor. Alternative: ^W F3 (DELETE LINE) Abandon the current command entirely. Alternative: ^U F4 (COMPLETE/DEFAULT) If pressed at the beginning of a field, supply and display the default value for that field (if any). If pressed in the middle of a 'keyword' field, complete the field if what has been typed already is valid and unambiguous. If these do not apply, the key is ignored. Alternative: ESC F5 (DELETE CHARACTER) Delete the character to the left of the cursor. Alternative: DELETE, BACKSPACE or ^H ^R (REDISPLAY) Replay the current command line (e.g. if the screen has been corrupted by another job's output or line noise). The Arc-K "panic" key is: BREAK This causes Arc-K to interrupt whatever it is doing, and to return to local command mode. If a transfer is in progress, no error packet or other indication will be sent although an attempt will be made to clean up the Arc environment (screen, keyboard) as best as can be done. It should only be necessary to use this interrupt for very serious problems. Note that if Arc- K is in remote mode, pressing this key will return to local - this is the only keyboard key recognised in remote mode. Commands may be entered in either upper or lower case (or indeed any mixture of the two). If ? needs to be entered literally, it can be escaped with \ (backslash), which will also escape itself or any top-bit-set character. During non-server file transfer in local mode, the following control keys are recognised: ^X (INTERRUPT FILE) If sending, end transmission of the current file and send an EOF packet with a Discard request. After this has been sent and acknowledged, the next file in the current batch will be started, or if no more remain an EOT will be sent. If receiving, request the remote system to abort the transmission of the current file and continue with the next one (if it is sending multiple files). ^Z (INTERRUPT BATCH) If sending, end transmission of the current file and send an EOF packet with a Discard request, followed by an EOT packet to end the batch. If receiving, request the remote system to abort the transmission of the current file and not send any more (if it is sending multiple files). RETURN (FORCE TIMEOUT) If pressed while Arc-K is waiting for a packet to be received, the wait will be abandoned and a timeout simulated, thus forcing the previous packet or acknowledgment to be resent. This is useful for manually unjamming the deadlock caused by a lost packet, if for some reason the timeout facility is not being or cannot be used. ^E (FATAL ERROR) If for some reason the remote system does not support ^X/^Z interruption,these control keys will have no effect in stopping the transfer. In this case pressing ^E will cause an Error packet to be sent with an appropriate message - this should cause any remote system to stop. 4. Commands ------------ The commands available in Arc-K are listed here, with the syntax and a description for each. Note that a command or required keyword need not be typed in full - only enough characters need be typed to make what is meant unambiguous. UPPERCASE is to be typed literally; lowercase indicates variable parameters; [brackets] indicate optional parameters. Possible options are separated by ','s. LOCAL and REMOTE, although logically sub-commands, are described here as if each option were a complete command. ATTACH This command is valid only in remote mode, and causes the command input source to revert to the Archimedes keyboard. See DETACH for more detail. BYE This command has been superseded by REMOTE BYE. CONNECT This enters terminal emulation on the currently selected serial line. The screen will clear and the cursor reappears in the top left corner. Terminal emulation is extremely dumb, with no support for any special features of the Archimedes screen or any standard video terminal. The special keys recognised are: F2 (EXIT) This returns to Kermit command mode. F3 (NULL) This sends the ASCII code 0. F5 (DEL) This sends the ASCII code 127. RETURN (EOL) Sends the currently defined end of line sequence, as set by SET ENTER. All other keys are sent to the serial line. If the LOCAL-ECHO option has been set to ON, the key press is also echoed to the screen. RETURN is always echoed as a newline regardless of the setting of the end of line sequence. DETACH This command is valid only in local mode, and causes all further Kermit input to be taken from the currently set communication line. There should be a machine running Kermit (or another terminal program) at the other end of that line before this command is issued. The prompt "Arc> " will appear on that system, and Kermit will run in remote mode just as if that machine were being used as a terminal to a mainframe system. No further activity will take place on the Archimedes screen until the ATTACH command is used to reconnect. All file transfer will also take place over the same serial line, however no progress or error messages will be issued once the transfer is started. Server mode is also available. The user environment is modified slightly as a consequence of running in remote mode: 1) The keyboard function keys are no longer available for line editing, help prompting and other facilities. The alternatives, which should be available on any terminal, can be used. 2) File transfer interruption is not available; however an interrupt will of course be accepted from the other system. 3) Only one serial port is available, which obviously cannot be connected to a server. Therefore certain commands are not available; they are CONNECT, GET, STOP and all the REMOTE sub-commands. 4) The transfer progress display is not available. Note that other SET commands can be used to change the line speed, parity, etc. Note also that, if communications with the other system is not set up correctly or fails, then there is no way of returning control to the Archimedes keyboard other than by using the BREAK key. DO command-line This command has been superseded by REMOTE HOST. EXIT or QUIT Exits the Kermit program. FINISH This command has been superseded by REMOTE FINISH. GET remote-file [local-file] Asks the remote server to send a file. 'remote-file' is the file to be sent, in the filename syntax appropriate to the remote system. 'local-file' is the Archimedes filename to store it under; if omitted, the name that the remote sends in the File- Header packet will be translated to a suitable Archimedes filename (see SET FILE NAME in §5). If 'local-file' is not given, or if it is given but it includes no ADFS directory specification, the file will be stored in the current directory. Note that if the server sends multiple files as a result of including wildcards in 'remote-file', then 'local-file' should not normally be given. If the file overwrite warning is set to OVERWRITE, the file will be repeatedly overwritten; if it is set to RENAME no data will be lost but the file names will have to be sorted out. Arc-K knows nothing about the syntax of a wildcard name on the remote system, and so cannot check for this situation before the transfer is started. However, it may be sometimes useful to take advantage of this: for example, to list the files on a (parallel!) printer give the appropriate device name ("PRINTER:") as the destination. HELP Displays a summary of the control keys available in command, transfer and terminal modes. LOCAL CWD [directory] Sets the current directory, where 'directory' is in Arthur format and can include filing system, drive or volume name prefixes. If it is omitted, & (the user root directory on the current drive) is assumed. LOCAL DIRECTORY [directory] Displays a list of the files in the specified directory, in roughly the same format as would be sent by REMOTE DIRECTORY (see later). If the 'directory' parameter is omitted, @ (the current directory) is assumed. LOCAL HOST command-line Sends the given 'command-line' to Arthur's CLI for execution. Note that built-in commands or those contained in modules will cause no problem, but running another application will abort Kermit. See REMOTE HOST in §6. LOCAL SPACE [device] This reports the medium name, the amount of space free and the largest contiguous free space available either on the specified device, or the current drive by default. RECEIVE [local-file] Waits for a file to be sent from a remote non-server. 'local- file' is the filename that it will be stored under; if omitted, the name that the remote sends in the File-Header packet will be used (as for GET). The remarks under GET regarding multiple files also apply here. REMOTE BYE Sends a command to a remote server requesting it to end server operation, and usually (depending on the particular server system) to terminate the Kermit program and/or log out the job/user running it. REMOTE COPY original-file new-file Requests the remote server to copy a file or group of files. In this command, as with all other commands that manipulate remote files, the file names are in the syntax of the remote system. REMOTE CWD [new-directory] Requests the remote server to change its current directory, i.e. the default location for files whose names do not include a directory specification. If 'new-directory' is omitted, either set a system default, or simply reply with the current directory. REMOTE DELETE file Tells the remote server to delete a file. Whether 'file' may include wildcards or not is determined by the remote system. REMOTE DIRECTORY [directory,selection-args] Requests the remote server to send a directory listing. If no argument is given, the current directory is listed. The server may also accept arguments for selective listing, or to control the listing format. REMOTE FINISH Sends a command to a remote server requesting it to exit server operation, and usually (depending on the particular server system) to return to Kermit command mode. REMOTE HELP [topic] Asks the remote server to send help on its operation, Kermit commands or remote system information. A topic may be given for specific information. REMOTE HOST command-line This sends the specified 'command-line' to be executed by the remote server's operating system, and displays the results on the Archimedes screen. REMOTE KERMIT command-line This sends the specified 'command-line' to be executed by the remote Kermit's command processor, just as if it was typed at Kermit command level. Usually this will be a SET command. REMOTE RENAME old-file new-file Requests the server to rename a file or group of files. REMOTE SPACE [area] Asks the server for a disc usage report. If the 'area' argument is not given, space on the current disc or drive will be reported. REMOTE STATUS Asks the server for a status report. This may include the current state, and statistics of the last file transfer. REMOTE TYPE file Requests that the remote server sends the given file or group of files in the same way as GET, except that the files will be displayed on the Archimedes screen rather than being stored on disc. REMOTE WHO [selection-args] Asks the server (if it is running on a timesharing system) to list the users currently logged in. The optional argument gives user names to list, or listing options. SEND local-file [remote-file] Sends a file to a remote Kermit, whether a server or not. 'local-file' is the Archimedes file to be sent. 'remote-file', if given, is the name that will be sent in the File-Header packet; if omitted, the (possibly translated) local name will be used. If 'local-file' includes no ADFS directory specification, the file will be taken from the current directory. Wildcards can be used in the local name to send a group of files. If a wildcard name is given, all those files matching it will be transmitted as a batch. Note that the remote name should not normally be given if a wildcard is specified, and Arc-K will give a warning if this is done. See the remarks under GET above, which will probably apply to the receiving system. For compatibility with other Kermit implementations, the construction of a wildcard name does not follow the Acorn ADFS standard, but uses a syntax similar to that of the Unix2 shell. It recognises the following special characters and combinations: * Matches any number of characters, including none. For example, "*" matches all files and "a*_c" would match "accept_c", "accept_new_c" and of course "a_c". # Matches any single character. For example, "###" matches all 3-character filenames, while "s##_*" would match "sbr_c", "sbr_h" and "set_obj", but not "swit_c" or "set". [ccc] Matches a single character, which is one of the ones enclosed between the []s. The c's can be either single characters, or a range of characters specified as c1-c2 which includes any character between c1 and c2 (inclusive) in the ASCII collating sequence. For example, "*_[ch]" would match all C source or header files, while "[a-m]*" would match all files beginning with a letter in the first half of the alphabet. As shown in the examples, these special characters can be used in any combination within the same wildcard name. Matching is case sensitive. No facility is provided to "escape" the special characters so that they are treated normally - people who are in the habit of creating filenames with strange characters in them deserve all the trouble they get. SERVER This command causes Arc-K to enter server mode, on the currently selected serial line. Commands will now be accepted in packets from the remote system until a BYE or FINISH request is received. See §6 for a description of the facilities available. Note that if Arc-K is in local mode when this command is given, no further input will be accepted from the keyboard until server mode ends. Similar remarks to those given under DETACH apply here. Also note that, as with DETACH, if communication with the other end is not set up correctly or is lost then it will not be possible to regain control of Arc-K other than by using the BREAK key. SET parameter option SET sub-section parameter option Controls various options of the Kermit program. See the next section. SHOW [what] Displays the current Kermit settings and parameters. 'what' indicates what is to be shown, it may be: ALL Everything except VERSION. COMMUNICATION Settings relating to the serial port and terminal emulation. FILE Settings relating to file transfer. PREFIX The current quote characters. SYSTEM Settings which don't fit in anywhere else. TRANSFER Protocol parameters, timeouts, etc. VERSION The current Arc-K version. If 'what' is omitted, ALL is assumed. STOP This command causes a single Error packet to be sent to the remote system, which should cause any transfer in progress to fail with a fatal error. It is useful for recovering from a fatal crash or communication problem, when the remote system thinks that the transfer is still in progress (and so is listening for packets) although Arc-K may have returned to command mode. TAKE filename Read and execute Kermit commands from a file. No specific file type is required; lines may be terminated by CR or LF (or both). If the TAKE-ECHO option is set to ON, command lines read from a TAKE file will be listed on the screen prior to them being executed. They will be preceded by "TAKE-n>", where n is the TAKE file nesting level, to distinguish them from commands typed at the keyboard. The TAKE command can be used within a TAKE file, thus allowing them to be nested to a maximum of 10 levels. However, if an invalid command is read, or if an error occurs during a file transfer, the entire stack of TAKE files will be abandoned if the TAKE-ABORT option is set to ON. (This does not include a transfer interruption initiated by ^X or ^Z; however it does include a fatal error initiated by ^E, or the use of the STOP command (what would this command be doing in a TAKE file anyway?)). This can be disabled by setting the TAKE-ABORT option to OFF. * command-line Issues an Arthur command, equivalent to LOCAL HOST as above. The space after the * is required. 5. The SET command ------------------- The options that can be controlled by the SET command are given below. Some of these options can also be controlled by generic commands received in server mode - see the next section. When a character is required, it is specified by ASCII code (except in the case of CONTROL-QUOTE and EIGHT-BIT-QUOTE, where it is given literally). Wherever a number is required, it can be given in any form acceptable to OS_ReadUnsigned. This means that hexadecimal can be specified with a leading &, or a base can be specified using the "b_nn" notation. The default base is 10 (decimal). Note that SHOW always displays numbers in decimal. Note that SEND, RECEIVE and FILE are logically sub-sections, although they are described here as if each variant were a separate option. BAUD speed [TRANSMIT,RECEIVE] SPEED speed [TRANSMIT,RECEIVE] Set the baud rate to be used on the communication line. The valid rates are those listed in the Archimedes manual (75, 150, 300, 1200, 2400, 9600, 19200). The transmit or receive speeds can be set independently by using the optional argument; if it is omitted, then both speeds are set. The setting on entry is for the current speed to be retained (as set by the *FX7 or *FX8 commands, or the CONFIGURE BAUD option), and the speed will be displayed as "Not set" in this case. CONTROL-QUOTE char Sets the character that Arc-K will prefix control characters in packets that it sends with, and indicate to the remote system that it will do so. This is normally '#', but can be changed for special applications. Note that Arc-K, when receiving packets, always uses the quote character the remote has asked it to. DEBUGGING OFF,ON,FULL Sets the debugging level. OFF is the initial setting, no information is displayed. ON causes messages regarding file manipulation and packet read failures to be displayed. FULL in addition displays information regarding the switcher state, and the contents of all incoming and outgoing packets. Note that even if Arc-K is being used in remote or server mode, debug information will always be displayed on the Archimedes screen. Also note that the debug information will interfere with the transfer status display, if it is enabled. DISPLAY should normally be set to OFF if DEBUGGING is set to ON or FULL; if it is ON a warning message will be displayed. DELAY time Sets the wait, in seconds, between a SEND command being accepted and the file transfer starting. If in remote (non-server) mode, this gives time to escape from the other system's terminal mode and type the RECEIVE command. The initial setting is 5 seconds. If Arc-K is in local mode the wait can be interrupted by pressing any key; the transfer will start immediately. DEVICE options This QL-specific sub-section has been superseded by the LOCAL CWD command, and it will give an appropriate warning message. DISPLAY OFF,ON Controls whether a progress display is shown while local mode transfer is in progress. If it is set to OFF, no output other than interrupt or error messages will be displayed during a file transfer, and generic command output will use the full screen. If the display is set to ON, status will be shown in the upper part of the display and generic command output in the lower part. The display is not available in remote mode, or if the screen mode in use is not at least 80 columns wide. If either of these apply, a warning will be given and DISPLAY will be automatically set to OFF (the transfer will proceed normally). It is recommended that DEBUGGING and DISPLAY are not simultaneously selected. The initial setting is ON. DUPLEX option This option is implemented as LOCAL-ECHO, and is retained for historical compatibility. It will give an appropriate warning message. EIGHT-BIT-QUOTE char Sets the character that Arc-K will use for 8th-bit quoting, if it is necessary and the remote system agrees to use the same character. This is normally '&', but can be changed for special applications. ENTER CR,LF,CRLF,LFCR Sets the character(s) that will be transmitted in terminal emulation mode when the RETURN key is pressed. CR is Carriage Return (ASCII 13); LF is Line Feed (ASCII 10). If it is set to CRLF or LFCR then two characters will be transmitted in succession. The initial setting is CR. FILE INCOMPLETE DELETE,KEEP Controls what happens to a partially received file if a transfer is abandoned (by a ^X or ^Z interrupt) or fails (due to an error or a ^E interrupt). If set to DELETE, the file is deleted; if set to KEEP, the partial file is retained. The initial setting is DELETE. FILE NAME NORMAL,REVERSED,UNTRANSLATED Controls whether file names sent or received in File-Header packets are translated from or to a standard Kermit format before use. If set to UNTRANSLATED, when sending the name sent will be identical to the name the Archimedes file was opened with (not necessarily that given on the command line); for receive, the name contained in the packet will be used for the Archimedes file. If set to NORMAL, the Archimedes filename will be translated to or from the "standard" Kermit format (as described in the Protocol Manual). The conversions applied for sending are: (a) Any Archimedes device prefix is stripped off. (b) Any special directory name at the start (one of '@', '$', '%', '^', '&' or '\' followed by a '.') is stripped off. (c) The last '_', if present, is changed to a '.' (this is done to make the send and receive translations inverses of each other). (d) The last two components (separated by '.'s) only are retained. (e) Any letters are converted to upper case. The conversions applied on receiving are: (a) The last two components (separated by '.'s) only are retained. (b) If present, the last '.' is changed to a '_'. (c) Any letters are converted to lower case. (d) The name is trimmed to the ADFS maximum of 10 characters. If set to REVERSED a slightly different translation is applied, which will be useful for applications, e.g. language compilers, which use the directory part of a filename in place of a "file extension" as used on many other systems. It is mostly identical to above, except that: (a) No translation of '_' to '.' or vice versa is done. (b) If the result has two components, they are reversed (still separated by a '.'). Some examples of send translation (omitting UNTRANSLATED) are: Original Normal Reversed path.c.file C.FILE FILE.C c.file C.FILE FILE.C file FILE FILE :0.$.file FILE FILE path.file_c FILE.C FILE_C file_c FILE.C FILE_C Some examples of receive translation (omitting UNTRANSLATED) are: Original Normal Reversed FILE.C file_c c.file FILE file file VERYLONGNAME verylongna verylongna VERYLONGNAME.EXT verylongna ext.verylongna Note that ADFS does not automatically create directories when creating files, i.e. if "c.file" is to be stored then the directory "c" must already exist (a "Not found" error will be given if it does not). When using NORMAL translation, any '.' is changed to an '_' to avoid this problem. Also note that, if a remote name is given in the SEND command, this will be sent verbatim in the packet, even if NORMAL or REVERSED mode is set. Similarly, if a local name is given for GET or RECEIVE, this will not be translated. The initial mode is NORMAL. FILE SUFFIX [string] This facility is no longer supported. FILE TYPE ASCII,BINARY [CR,LF,CRLF,LFCR] Controls whether end-of-line translation is applied to file data sent or received during a transfer. If set to BINARY, no translation is done; this allows object files, etc. to be sent and received exactly as they appear in the filestore. If set to ASCII, the further options are available to set the end of line sequence (these options are not available if BINARY is set). End-of-line translation is done as follows: For sending, CRLF is equivalent to CR and LFCR to LF. A CR or LF (respectively) in the file is sent in the packet as the prefix sequence "#M#J", assuming that the control-quote in use is '#'. The "other" character (LF or CR respectively) will be ignored. For receiving, the encoded "other" character is ignored and the encoded CR or LF is written to the file as CR, LF, CRLF or LFCR respectively. This has the effect (assuming that the option is set correctly at both ends of the link) of allowing a printable text file on the sending system to become a printable text file on the receiving system, regardless of the means by which the other system represents end of line. The four end-of-line options allow files used by almost any Archimedes application to be transferred. If the end-of-line option is omitted when setting ASCII mode, the option last given will be used. If none has been used before, CR is assumed. Note that the FILE TYPE setting has no bearing on whether the 8th-bit of a byte is sent, with quoting or otherwise. It affects end of line translation only. The initial setting is ASCII CR. FILE WARNING OVERWRITE,RENAME This option controls the action that Arc-K takes when a file that it intends to create (when receiving) already exists. If it is set to OVERWRITE, the existing file will be lost and no warning given. If it is set to RENAME, the existing file will be retained and the new file created under a unique name made by adding a numeric suffix to the original name. The initial setting is RENAME. LINE port Sets the serial port to be used for data transfer. At present, only line '1' (the built-in serial port) is supported. Future versions may support the multiple port podules available. LOCAL-ECHO OFF,ON Controls whether keys pressed in terminal mode are echoed to the screen by Arc-K, or by the remote computer. Note that if it is set to ON, the RETURN key is always echoed as a newline regardless of the setting of the ENTER action. The initial setting is OFF. PADDING [amount [character]] Controls whether padding is inserted after a transmitted packet, to allow for communication line delays or remote system requirements. 'amount' is the number of pad characters that are to be transmitted; the default is 0 (no padding). 'character' is the character to be used; the default is NUL (ASCII 0). If 'amount' and 'character' are omitted, no padding will be done. Note that the amount of padding and the character used are subject to negotiation in the Send-Init packet exchange. The algorithms used are explained later. PARITY NONE,ODD,EVEN,MARK,SPACE Selects the parity setting that will be used by Arc-K for transmission, and checked on reception. The initial setting is NONE. The parity setting interacts with whether 8th-bit quoting will be specified or requested in the Send-Init packet exchange. See the notes later regarding this exchange. RECEIVE END-OF-LINE code Specifies the end-of-line character that Arc-K will request the remote system to terminate a packet with; the initial setting is Carriage Return (ASCII 13). Arc-K does not require any end of packet marker, so this option is redundant. It also appears pointless to allow this character to be specified in the Send- Init exchange, since if a different terminator to the default was required the Send-Init packet or its acknowledgement could not be received! RECEIVE MARKER code Specifies the character that Arc-K will look for to indicate the start of an incoming packet. The initial setting is SOH (ASCII 1). RECEIVE PACKET-LENGTH length Specifies the maximum packet length that Arc-K will request the remote system to send. The initial setting is the maximum of 94. A sensible minimum is about 30, but this is not enforced by Arc- K. RECEIVE TIMEOUT time Specifies the time, in seconds, that Arc-K will wait for an incoming packet (if the timer is enabled). The initial setting is 20. The timeout used is subject to Send-Init negotiation. RETRIES number Sets the number of times that Arc-K will retransmit a packet when the expected reply is not received successfully. This includes packet read timeouts (if the timer is enabled), timeouts forced by pressing RETURN, packets received with a bad checksum or unexpected reception of a previously received packet. If this limit is exceeded, the transaction will be aborted. Note that the retry limit applies to the reception of one particular packet, and not the total number of retries in a transaction. The initial setting is 5. SEND END-OF-LINE code Specifies the end-of-line character that Arc-K will terminate a packet with; the initial setting is Carriage Return (ASCII 13). The remarks under the corresponding RECEIVE option regarding the specification of this parameter in the Send-Init exchange also apply here. SEND MARKER code Specifies the character that Arc-K will transmit to indicate the start of a packet. The initial setting is SOH (ASCII 1). SEND PACKET-LENGTH length Specifies the maximum packet length that Arc-K will send to the remote system. The initial setting is the maximum of 94. A sensible minimum is about 30, but this is not enforced by Arc-K. This length is subject to Send-Init negotiation. SEND TIMEOUT time Specifies the time, in seconds, that Arc-K will ask the remote system to wait for an incoming packet, if it has a timeout facility. The initial setting is 20. SERVER-WAKEUP OFF,ON Controls whether the Arc-K server sends periodic NAK packets while waiting for a command packet in server mode. If set to ON, they will be sent every 60 seconds; this ensures that even if Arc-K is serving a system that cannot time out or otherwise recover, the loss of a command packet will not cause communications to stop indefinitely. If set to OFF, no wakeups will be sent; it may be necessary to select this if the other system cannot clear its input buffer. See the Protocol Manual for more information. The initial setting is OFF. TAKE-ABORT OFF,ON Controls whether TAKE files are abandoned when a command or transfer error occurs. If it is set to ON, the entire stack of TAKE files (i.e. the one containing the command causing the error, as well as any that called it) is abandoned and control returns to the keyboard prompt. If set to OFF, the error is ignored and execution continues with the next command in the TAKE file. See the description of the TAKE command for more information. The initial setting is ON. TAKE-ECHO OFF,ON Controls whether command lines read from a TAKE file are echoed on the screen before execution. If set to ON, they are listed with a "prompt" identifying their source and the current level of TAKE file nesting. See the TAKE command for more information. The initial setting is ON. TIMER OFF,ON Controls whether Arc-K will time out if a packet being waited for is not received within the specified or negotiated time. If set to OFF, Arc-K will never time out and will wait indefinitely if a packet does not arrive (except that a timeout can be simulated, if in local non-server mode, by pressing RETURN). If set to ON, timeout processing will be performed normally. The initial setting is ON. Note that this option, and the SEND/RECEIVE timeout settings, have no bearing on the time that a server will wait for an initial command packet. See the SERVER-WAKEUP option. 6. Server mode functions available ----------------------------------- When Arc-K is running in server mode, the following facilities are available. They are described in terms of the commands used to initiate them on a "typical" Kermit system. BYE This causes Arc-K to exit server mode, and also to terminate itself. A brief message will be sent to acknowledge this. FINISH This causes Arc-K to exit server mode, and return to Kermit command level in either local or remote mode depending on what it was when the SERVER command was issued. A message will be sent to indicate what command mode Arc-K is returning to. GET remote-file [local-file] This causes Arc-K to send a file or group of files. The name may include wildcards as described under the SEND command in section 4. REMOTE CWD [directory] This generic command sets the current directory to that specified; the default is the standard one of $. Although a password will probably be asked for, none is required. REMOTE DELETE remote-file This causes the specified file to be deleted from the Archimedes's filestore. No translation or wildcard processing is done on the file name (the name may not include wildcards). An error is returned if the file does not exist. REMOTE DIRECTORY [directory] A listing of the specified directory, or if it is not given the current directory, will be sent. The listing includes the file name, a directory flag, size in bytes and the Arthur file type (if the file is stamped). REMOTE HELP This sends a list of the currently supported server commands. REMOTE HOST This executes an Arthur command line and reports the results. Operation is mostly as expected, but with some points to watch: 1) Attempting to start another application will abort Kermit, with no error indication. There appears to be a bug in Arthur 1.2's handling of application starts rejected via the upcall vector or module service call, so this situation cannot be detected before execution. Built-in commands are mostly acceptable. 2) Kermit will also be aborted if application workspace is corrupted, for example by using COPY with the Q (quick) option. 3) The command output is actually redirected to a file, so attempting to give another redirection specification will fail with a syntax error. 4) The results are not sent back until the command has finished executing. If it takes a long time, the client Kermit may time out and the subsequent transfer will fail with a protocol error. Arc-K attempts to avoid this by clearing its input buffer after executing the command and before sending the results back. 5) No input can be given to the command. Arc-K attempts to trap input requests by redirecting input from NULL:, but some commands (for example Wipe) bypass this and read the keyboard directly. When using this request, a directory $.Tmp must be present and writeable on the current drive. REMOTE SPACE [device] This reports the medium name, the amount of space free and the largest contiguous free space available either on the specified device, or the current drive (drive containing the current directory) by default. REMOTE STATUS This replies with the current Arc-K version, the serial port in use, and the current settings of the transfer file type. REMOTE TYPE remote-file This is similar to GET, except that the files will be sent with X packet headers thus causing them to be displayed on the receiving system's screen instead of being stored as files. Wildcard processing is performed on the file name. SEND local-file [remote-file] This causes the Arc-K server to accept a file or group of files and to store them in its filestore. All the receive options (name translation, overwrite warning, etc.) apply to the received files. 7. Notes on Send-Init parameter negotiation -------------------------------------------- Certain parameters relating to the file transfer that is just about to start are negotiated between the two sides in the Send- Init packet exchange. The algorithms Arc-K uses to derive the parameters eventually used in the file transfer are described here. Note that "send" and "receive" here refer to packets and not necessarily file data. Also observe that some Kermit implementations may well ignore the parameters requested in the exchange, and either use their own settings or some compromise (as Arc-K does in some cases). (a) Packet length Arc-K asks the remote system to send it packets no longer than the RECEIVE PACKET-LENGTH setting, but will not fail if for some reason this request is ignored. Initially the packet length that it sends is that specified by SEND PACKET-LENGTH; however if the remote system requests it to send a shorter packet, Arc-K will do that. The eventual length used is the minimum of the Arc-K setting and the remote request. (b) Timeout Arc-K requests the remote system to time out (if it is capable of doing so) after the SEND TIMEOUT interval. The initial timeout Arc-K uses is that set by RECEIVE TIMEOUT; if the remote system specifies that Arc-K should use a longer interval, it will do so. The eventual receive timeout used is the maximum of the Arc-K setting and the remote request. (c) Padding amount Arc-K does not require padding on receive, and always specifies that no padding should be sent to it. Initially the amount of padding sent, and the character used, are those set by PADDING; after the exchange, if a greater number of padding characters are requested by the remote, that number will be used. The padding character sent is always that specified in the packet. (d) End of line Arc-K sends the first packets with the terminator defined by SEND END-OF-LINE, and then uses that requested by the remote, if given. Arc-K does not require a terminator on incoming packets, but requests that set by RECEIVE END-OF-LINE for completeness. (e) Control quote The quote characters are not used until the Send-Init exchange is over, therefore no initial setting is relevant. Arc-K will inform the remote system that it will send data using the character set by CONTROL-QUOTE; for receiving data it will use the quote character the remote specifies. (f) 8th-bit quote The current parity setting interacts with 8th-bit quote negotiation as follows: If the parity setting is NONE, Arc-K need not do 8th-bit quoting, but will do so if the remote requires it. In this case, the quote character used is that specified by the remote, if it requires 8th-bit prefixing to be done. If the remote need not do 8th-bit quoting either, then it will not be done. The character specified by EIGHT-BIT-QUOTE is irrelevant in this case. If the parity setting is one which permits only 7-bit transmission, Arc-K will specify that it needs to do 8th-bit prefixing. The quote character used will depend on which side initiates the exchange: If Arc-K sends the Send-Init packet, it will request that 8th-bit quoting is to be done using the character currently set. If the remote replies that it will use the same character, or it will optionally do so, that character will be used for the transaction. In the case where Arc-K reads the Send-Init packet and acknowledges with its own parameters, if the remote has specified optional quoting then Arc-K will indicate that it must use the set character. If the remote specifies a quote character, thus indicating that it must prefix, then Arc-K will use the character specified too. (g) Other parameters Arc-K supports only checksum type 1, and assumes that the remote will agree. Repeat count prefixing is not supported; nor are any exotic features such as file attributes, sliding windows or long packets. Note that, if any parameters are not specified by the remote system (i.e. if it sends a short parameter packet), Arc-K will continue to use the initial settings as they were at the start of the transaction. 8. Building Arc-Kermit from source ---------------------------------- To build Arc-K from source requires the Acornsoft ANSI C development system. Obviously, the more memory and disc available the less tedious recompilation will be. A "make" utility, if available, simplifies the task of maintenance. The source files required are: Name Size (K) Contents main.c 10 Main program and global data command.c 15 Command processor display.c 8 Transfer status display function.c 14 Protocol support routines switcher.c 18 Protocol state switcher user_1.c 15 User commands user_2.c 12 The SET command terminal.c 1.5 Terminal emulation subr_1.c 9 General subroutines subr_2.c 15 Arthur-specific subroutines subr_3.c 2 Output formatting subroutines generic.c 7 Server generic commands kermit.h 14 General definitions command.h 1 Command processor definitions user.h 4 User command & option definitions makefile 1 Dependency definition file module_bas 3.5 Source for utility module Various include files, supplied with the C compiler, are also required. These source files compile to the following files: Name Size (K) Contents kermit 101 Main program module 0.5 Serial i/o utility module Note that the file names given here are "standard" form, not the Arthur forms, so that main.c will actually be stored as c.main (except that the C compiler cc, and the linker startup ld, will accept standard forms). No particular compiler control arguments are required, and the only additional library required is ArthurLib. A complete recompilation takes about 2 minutes (from hard disc). The Kermit main program reduces to 54K if the shared C library is used. For interest's sake, Arc-K was developed on an A440 under Arthur 1.2. As well as the C compiler and linker, the only other software used was First Word Plus for editing (much better than Twin), plus an Archimedes implementation of Make3. A very basic receive-only version of Kermit (written in Basic) was used to get the original source files onto the system. 9. Acknowledgments ------------------- Thanks are yet again due to: Robert Coughlan, once of Liverpool University, for writing the original version of QL-Kermit and making it available via Lancaster. The Lancaster Kermit Distribution Service, and especially Alan Phillips whose excellent implementation of BBC-Kermit inspired me to provide it with something to talk to (that was QL-Kermit, on which this version is heavily based). The writers of the original C-Kermit, from which many of the algorithms used in Arc-K are taken; also the original developers of the Kermit protocol. Acorn, for at last building the best affordable computer available. Let's fix the serial port bug next time, lads... Also Norman & Mycroft, the implementers of an excellent ANSI C for this wonderful machine. But no thanks to the writer of the ANSI C manual, which leaves out more useful information than it contains. The writers of PD-Make, which made the development of Arc-K much easier. Now if only someone would write a decent source debugger at a reasonable price...