Columbia Kermit

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

/ Columbia Kermit / kermit.zip / d / vmeker.doc < prev next >

Wrap

Text File | 2020-01-01 | 82KB | 2,914 lines

VME KERMIT User Guide ===================== This document describes how to use the VME implementation of KERMIT produced at the South West Universities Regional Computer Centre. The information in this edition applies to version 1.01 of VME KERMIT. EDITION 1.01 October 1986 ACKNOWLEDGEMENT The layout and content of this document is derived from the 'USER GUIDE FOR BBC KERMIT' written by Alan Phillips of the Computing Department at the University of Lancaster. We are grateful for his permission to use this material. VME KERMIT User Guide CONTENTS 1. INTRODUCTION 2. AN OVERVIEW OF KERMIT 3. CONTROLLING VME KERMIT 3.1 Entering VME KERMIT 3.1.1 The OPTION parameter 3.1.2 The VME_FILE parameter 3.1.3 The REM_FILE parameter 3.2 Leaving VME KERMIT 3.3 VME KERMIT command language 3.1.1 Command format 3.3.2 Abbreviating commands 3.3.3 Numeric parameters 3.3.4 The help facility 4. TRANSFERRING FILES WITH KERMIT 4.1 Principles 4.2 Setting file type 4.2.1 How files are organised 4.2.2 Sending eight-bit data 4.2.3 Binary files 4.2.4 ASCII files 4.2.5 EBCDIC files 4.3 File transfer as a server 4.4 File transfer as a non-server 4.4.1 Sending files as a non-server 4.4.2 Receiving files as a non-server 4.5 Handling problems 4.6 Advanced facilities 4.6.1 Incomplete file transfers 4.6.2 Using timeouts 4.6.3 Protocol control 5. COMMANDS FOR GENERAL CONTROL OF KERMIT 6. COMMANDS FOR TRANSFERRING DATA 7. COMMANDS FOR PROTOCOL CONTROL 8. OBTAINING, BUILDING AND MODIFYING VME KERMIT 8.1 Obtaining VME KERMIT 8.1.1 The source files 8.2 Building VME KERMIT from source 8.3 Changing KERMIT defaults Appendix 1. VME KERMIT capabilities Appendix 2. Valid VME control characters Appendix 3. Running KERMIT over a JNT PAD VME KERMIT User Guide 1: INTRODUCTION =============== This user guide describes the VME implementation of KERMIT produced by the South West Universities Regional Computer Centre at Bath University. It is intended to provide enough information for a novice KERMIT user to be able to transfer data to and from VME to another KERMIT system. Other KERMIT systems are desribed only in passing: thus a user would almost certainly need to consult the equivalent user guide for the KERMIT system on the other machine. The guide is divided into several chapters. The first chapter is a general overview of KERMIT as a whole, and explains its advantages as a file transfer system over "dumb capture" pograms. The next chapter describes the command language that VME KERMIT uses. Following that are chapters that describe how to use VME KERMIT to transfer data. The final chapters comprise the "reference section". They describe in full detail the commands available in VME KERMIT, grouping them by functionality (i.e. "Commands for file transfer", etc). The very last chapter of the guide describes how to obtain VME KERMIT, and, having obtained it, how to build it from the S3 language source. VME KERMIT is, of course, freely available to anyone who wants it. It can be obtained from Lancaster University's KERMIT distribution service over file transfer from their VAX 11/780 system. The Lancaster distribution service also maintains on-line bulletin files giving details new releases of VME KERMIT and of reported bugs: these can be consulted in a public-access username. 1-1 VME KERMIT User Guide 2: AN OVERVIEW OF KERMIT ======================== KERMIT is a system, devised at the Center for Computing Activities at the University of Columbia, New York (CUCCA), to permit the simple and flexible transfer of data from a microcomputer to a mainframe or another microcomputer. CUCCA retain the copyright on KERMIT, but have published full information on it and permit anyone to implement it on their own machines, provided this is not done for commercial purposes. The result is that KERMIT is now available on a very wide range of machines indeed: very few micros and mainframes now do not have a KERMIT of some sort available for them. The primary design aim of KERMIT is to permit the transfer of any data whatsoever between systems, and to make the data usable on the system that receives it if this is possible. To illustrate why this is important, and not possible with simple systems, we can consider an ordinary terminal emulation system that allows data to be captured into files or sent from them. Simple terminal emulator systems, such as those commercially available for many micros, do permit you to transfer files from a mainframe in a rudimentary way. You would tell the emulator to copy any characters that appear on the screen into a file, then ask the mainframe to display the file. The reverse process would let you input data into a mainframe file from your micro's discs. The problems arise in the nature of the communications system that connect the micro to the mainframe, and how the mainframe itself uses this system. A character of data in a file occupies one byte, which consists of 8 binary digits or "bits". If you regard the pattern of bits representing a character as a number, this allows numbers ranging from 0 to 255 to be used. However, many communications systems will allow only 7 of the eight bits to be transmitted along them. The most significant bit, termed the "parity bit", is used by the communications system as an error-checking device. Thus, even though you send a byte of 8 bits to the mainframe, it may receive only 7 of them. This immediately restricts the range of characters that can be sent to those whose codes are in the range 0 to 127. A further restriction may be imposed if the communications system uses some of those characters for its own control purposes: thus systems often will use the characters whose codes are 17 and 19 to prevent overloads occurring. In such systems, you cannot transmit these characters at all. To make matters even worse, some machines will (apparently arbitrarily) decide that you could not possibly want to send some characters, so, if you do send them, it will change them into something else entirely. The character range 0 to 127 covers all the printable characters, so that transferring text files should just about be possible. Of course, if the communications line you are using is unreliable or noisy (a slow dial up line, for instance) there is nothing to prevent data being garbled in transmission, so that you will never be sure sure that the data that arrives is the data that you sent. 2-1 VME KERMIT User Guide KERMIT overcomes all these difficulties by encoding the data it sends according to a standard set of rules or "protocol". KERMIT recognises that many characters cannot be transmitted down a communications line, so if those characters occur, they will be translated into something that will be transmitted. The receiving end, of course, will translate them back again to what they were. This technique enables you to send any data at all, even machine code programs. It further guarantees that the data you send is the data that arrives, since KERMIT uses special methods for detecting garbling and will repeat any transmissions that did not get through correctly. KERMIT's encoding and checking techniques are more efficient than some other systems that offer this facility, since only bytes that need encoding actually are encoded, thus keeping the volume of data sent to the minimum possible. Besides the problems of actually transferring data corectly, there is the problem of making it usable on the other end of the transmission link. If you are sending, say, a SAVEd BASIC program from a micro to VME, this isn't a problem, since VME can't understand micro BASIC anyway. Nor does it matter if you use the VME system only as an archive: it's irrelevant how the data is held on VME, as long as when it is brought back to the micro side it looks the same as when it was sent. The usability problem does appear, though, if you want to move a file from a micro to VME and then actually use it on VME. You might, for instance, word process a file on the micro then send it to VME to be printed. In this case, you do NOT want to transfer the data byte-for-byte, since the way the micro and VME denote things like the end of each line of text will almost certainly be different. What you require is that the file of printable lines on the micro which you can process on that machine, becomes a file of printable records on VME, that can be processed there. Using a dumb terminal emulator system would probably let you send the data, but it would appear byte-for-byte as it was on the micro. And probably you would get a file on VME with extra line-feeds and carriage-returns that would need laborious editing before you could use the file sensibly. With KERMIT the problem can easily be circumvented. The KERMIT protocols define a standard way of indicating the end of a printable line. When you send a file from VME, VME KERMIT will translate whatever ends the lines of text in your file into this standard form before sending the data. The receiving end, seeing this standard end-of-line indicator, will translate it into however IT indicates end-of-line. You thus end up with a usable file of lines, with no extra characters anywhere. 2-2 VME KERMIT User Guide The requirements you must meet before using KERMIT are simple. You will need a KERMIT in your micro which supports terminal emulation; a KERMIT program in the VME system you wish to transfer data to; and a way of linking the machines, be it a network, an ordinary cable, or whatever. Micro to mainframe transfers involves entering the micro's terminal emulator program: you initially use this to log in to VME as though the micro was an ordinary terminal. Once logged in, you start the VME KERMIT program, and can then flip from giving commands to VME KERMIT, to giving commands to the micro KERMIT. You tell one machine that it is going to receive a file, tell the other to send it, and sit back and relax while it happens. Some micro KERMIT's provide one further facility to help you spend time doing more useful things. As well as sending one file at a time from one machine to the other, you can send them in groups: thus, you could say "send all the files on my disc to VME" in one command. The KERMIT programs will send the files one by one until all are gone, quite automatically. This facility is not available with VME KERMIT. 2-3 VME KERMIT User Guide 3: CONTROLLING VME KERMIT ========================= In this section we shall look at how you start and stop VME KERMIT, and also how its command language operates. 3-1 VME KERMIT User Guide 3.1 ENTERING VME KERMIT ----------------------- To invoke VME KERMIT you must log in to VME and issue the command: KERMIT ( OPTION = @ initial mode @ , VME_FILE = @ name of VME file @ , REM_FILE = @ name of remote file @ , RESPONSE = @ result code variable @ ) to the VME command prompt. 3.1.1. The OPTION Parameter This parameter defines which mode VME KERMIT is to start up in. If you set this parameter to COMMAND (the default) then VME KERMIT will start up in command mode and you will be prompted to type comands. You must not specify the VME_FILE or REM_FILE parameters when you have set the OPTION parameter to COMMAND. If you wish to initiate a file transfer directly you may do so by setting the OPTION parameter to either RECEIVE (VME KERMIT is to receive a file) or SEND (VME KERMIT is to send a file). For RECEIVE, the VME_FILE parameter is optional but you must not set the REM_FILE parameter. For SEND, the VME_FILE parameter is mandatory and it must be set to the name of the VME file to be sent. The REM_FILE parameter however is optional. Alternatively you may wish to enter server mode directly, you may do this by setting the OPTION parameter to SERVER. As for COMMAND mode the VME_FILE and REM_FILE parameters must not be specified. 3.1.2. The VME_FILE parameter This parameter specifies the name of the VME file to be used in the file transfer. If you have set the OPTION parameter to COMMAND or SERVER you must not set this parameter. This parameter is optional if you set the OPTION parameter to RECEIVE. If it is given then it must contain the name of the VME file to receive the data. If you default this parameter then KERMIT will take the VME file name from the file indentified by the micro KERMIT. This parameter is manadatory when you set the OPTION parameter to SEND and it must contain the name of the VME file to be transfered. 3.1.3. The REM_FILE parameter This parameter specifies the file name that VME KERMIT will send to the micro KERMIT to identify the file. This parameter is optional when the OPTION parameter is set to SEND, but must be omitted in all other cases. If you set the 3-2 VME KERMIT User Guide option parameter to SEND and default this parameter the VME KERMIT will send to the micro KERMIT a file name taken from the VME file name. 3.1.4. The RESPONSE parameter This parameter is used to return result codes. VME KERMIT does not generate any result codes of it's own but standard VME result codes may be returned. Normally this parameter should be omitted. 3.2 LEAVING VME KERMIT ---------------------- To leave VME KERMIT you would normally use the EXIT command. This will close down KERMIT and return to the VME command level. Alternatively, if you are running VME KERMIT in server mode you can close KERMIT remotely and either return to the VME command level or log out the VME terminal session. 3.3 VME KERMIT COMMAND LANGUAGE ------------------------------- You control what you want VME KERMIT to do, and how it should do it, by giving it commands in its "command language". The format of the command language closely follows that used on most other KERMIT implementations on other machines. 3.3.1. Command format When you enter VME KERMIT, you will see a prompt on the screen VME Kermit> This indicates that KERMIT is expecting you to type a command. KERMIT commands can be typed in upper case, lower case, or any mixture of the two as you please. KERMIT commands take the form of a command name, such as "SET" sometimes followed by one or more further pieces of information or "parameters", which must be separated from each other by spaces. For example, one command you might use is SET RETRY 10 to set the number of times an attempt will be made to send a particular packet before giving up. Here the command is "SET", and RETRY and 10 are the parameters to the command. Since there are a large number of variations to the SET command, these are often referred to in this guide as separate comands. Thus you 3-3 VME KERMIT User Guide see references to the "SET FILE TYPE BINARY" command, for instance. You can regard this as either a command whose name has spaces in it, or as a form of the SET command with parameters FILE, TYPE and BINARY. In either case, the effect will be the same. At the end of each command you should press the RETURN key to send the line to KERMIT for action. If you have made a typing mistake you can use the delete key and cancel key exactly as for other VME commands. The reference section at the end of this guide gives the complete specification of all the VME KERMIT commands. The commands are grouped according to their function (such as "file transfer control"), rather than in one alphabetical list. Thus you will find variations of the SET command appearing in many places, grouped with other commands that function in the same area. The reference section presents each command in a formal way to show you exactly what you are allowed to type at any point. You might find one command described as having a format SET PAUSE <number> for example. Here the fixed parts, that you would always include, are shown in capitals. The third part of the command, "<number>" is enclosed in "<>" brackets to show that here you must provide your own parameter value. The fact that it says "number" indicates that what you should type is a number of some sort: the description of the command will tell you what sort of number you must provide and why. Note that you don't type the "<>" brackets yourself here. Thus, a valid way of using this command might be SET PAUSE 10 where you have supplied the numeric value "10" where it was expected. Sometimes, not all the parameters of some commands need be typed. In these cases, VME KERMIT will take a "default" value for the parameter you did not supply. The reference section will tell you which parameters can be omitted, and what values VME KERMIT will assume if they are omitted. 3.3.2. Abbreviating commands To reduce the amount of typing that you need to do, VME KERMIT allows you to abbreviate all commands and most parameters. You may abbreviate to as few characters as you wish, provided that what you type is unique. Thus HELP HEL HE H 3-4 VME KERMIT User Guide are legal, but S is not, since it could stand for either SEND, SERVER, SET, SHOW or STATISTICS. To take a full example, you could type either SET FILE TYPE BINARY or abbreviate it as far as SET F T B 3.3.3. Numeric parameters Except where explicitely stated, numeric parameters to commands can be typed in either decimal or hexadecimal. By default, VME KERMIT expects the value to be decimal, but you can indicate a hexadecimal number by preceding the parameter with an "X". Thus 123 is a decimal value, and X123 is a hexadecimal value. 3.3.4. The help facility Quite often, you may wish a reminder as to what parameters or commands you can give. KERMIT has a "help" facility that will act as an "aide-memoire" for you. To use help, simply type HELP in response to the command prompt. KERMIT will immediately give you a list of the commands available and the option of requesting further information about the commands. For example, if you type HELP after the prompt thus: VME Kermit> HELP KERMIT will output a list of the commands you can use. You may then request more information about one of the commands from the menu. The HELP command may be augmented by folowing it by a command name and parameters. 3-5 VME KERMIT User Guide For example, if you require help for the "SET" command you type VME Kermit> HELP SET VME KERMIT will then give you an explanation ot the "SET" command and a list of the parameters available. You will then be given the option of requesting further information about the parameters and their values. 3-6 VME KERMIT User Guide 4: TRANSFERRING FILES WITH KERMIT ================================= The primary use of VME KERMIT is to transfer files between it and a microcomputer. The methods used will be substanstially the same whatever the other system is, since any KERMIT system should be able to communicate with any other. Though the general techniques will be same, the exact commands used to control the different KERMITs will vary from one system to another. You will need to consult the user guides of the other system to discover how it should be controlled. In this section we shall cover in detail how VME KERMIT is controlled. 4-1 VME KERMIT User Guide 4.1 PRINCIPLES -------------- KERMIT differs from other "dumb" file transfer systems (such as you might find in a terminal emulator ROM, for instance) in that it aims to transfer files in a USABLE way between systems. Thus, if you have a program source on your micro's discs that you can edit with some editor, and transfer this to VME, the resulting file should also be editable using VME's editors. KERMIT will resolve all the differences in how files are stored on your behalf, so that, in this example, the VME file will not contain extra line-feed characters at inconvenient places that the VME editor cannot handle. Transferring files with KERMIT involves several discrete steps. We shall consider here the most common case of transfer to and from a microcomputer. 1. The micro KERMIT is entered and set up for the transfer. In particular, you may wish to tell KERMIT what types of file are to be moved. You will also need to set the parameters for terminal emulation, and, depending on the micro system's needs, you may need to change some of the more detailed aspects of the VME KERMIT's operation. 2. Terminal emulation mode is entered, and the micro is logged in to VME as though it were an ordinary terminal. 3. Operating as a terminal, the VME KERMIT program is started. 4. Commands can then be given to the VME KERMIT (from terminal emulation mode) and to the micro's KERMIT (from KERMIT command mode). The two KERMIT systems will communicate with each other using the standard KERMIT protocol. 5. After the transfers are done, the terminal is logged out from the VME system. In practice, the steps taken will range up and down this list as required. For example, VME KERMIT parameters can be changed at any time, not only at the start, and if you are moving several tyes of file you will need to change them frequently. In the sections below we shall consider the various actions you will need to take; the order of doing them is up to you. 4.2 SETTING FILE TYPE --------------------- 4.2.1 How files are organised VME KERMIT can only operate on serial access files, and the user must have the required access permissions (read or write, as necessary). The maximum record size that VME KERMIT can handle is 4096 bytes. 4-2 VME KERMIT User Guide 4.2.2 Sending eight bit data Futher more VME KERMIT restricts data it sends to only 7 bits in each byte: thus you can only normally send characters whose ASCII codes are in the range 0 to 127. However, every binary file will contain bytes from the whole character set, with codes from 0 to 255. KERMIT in general has a technique for overcoming this restriction, by encoding characters in the range 128 to 255 into special sequences that can be sent down any communication line. VME KERMIT and most modern KERMITs will use this technique, which is known as "eigth-bit-prefixing", but you may encounter an older implementation on some machine that does not support it. In this case it will not be possible to transfer the file. There is regrettably, no way round this problem from within KERMIT. 4.2.3. Binary files These files contain data that is not primarily printable text, such as machine-code programs. When you transfer these files, you wish every byte in the file on one system to appear unchanged in the file on the other system, regardless of what it is. You tell KERMIT that you are handling binary files with the command SET FILE TYPE BINARY which tells it not to change any data that it either sends or receives. Note here that you may need to issue a comparable command to the micro KERMIT, to prevent it trying to manipulate the data. 4.2.4. ASCII files These files contain data that is primarily printable text, but they also contain some characters whose codes are in the range 0 to 255, such as word processing text files. As with binary files, the data is transferred byte-for-byte, but in this case the record format is maintained. You tell KERMIT that you are handling ASCII files with the command SET FILE TYPE ASCII which tells it not to change any data that it either sends or receives, but it is to recognise end of record delimeters. 4.2.5. EBCDIC files These files contain printable text, such as program listings. When you transfer one of these files, you do not necessarily want a byte-for-byte transfer, since the two machines may differ in how they store text files. VME for example, uses the EBCDIC character code to store text files, whilst most micro's use the ASCII character code. The KERMIT standards defines a fixed way in 4-3 VME KERMIT User Guide which things such as end-of-line are transferred: VME KERMIT will translate your data to this standard format, and the other end will then translate the standard format into whatever its own specific requirements are. You tell VME KERMIT that EBCDIC text files are to be transferred with the SET FILE TYPE EBCDIC 4.3 FILE TRANSFER AS A SERVER ----------------------------- VME KERMIT will run as a KERMIT server, but it is essential that your micro KERMIT is able to communicate with a server: that is, it must support the commands GET and BYE or FINISH. You should put VME KERMIT into server mode with the command "SERVER". You should then use your micro KERMITs local escape sequence to return to command mode. The operation of both KERMITs can now be controlled from your micro KERMIT, and your micro KERMITs user guide should give you further information regarding running with a server. 4.4 FILE TRANSFER AS A NON-SERVER --------------------------------- Transferring data as a non-server is a little more complicated, since you will need to continually change from the micro KERMITs command mode to terminal mode and back again. With a little practice, though, the technique becomes natural. 4.4.1. Sending files as a non-server To send a file as a non-server you use the command SEND. However, you must also tell the micro KERMIT that a file is on its way. One means of doing this is as follows: a. In terminal mode, start the VME KERMIT program, and issue the SEND command. This tells it to send a file to the micro system. Normally, VME KERMIT will pause for 30 seconds to enable you to escape back and issue commands to your micro KERMIT. b. Use your micro KERMITs local escape sequence to return back to its command mode. c. Issue the micro KERMIT RECEIVE command. When the VME KERMITs delay expires, it will start to send the file. 4.4.2. Receiving files as a non-server If the VME KERMIT system is not running as a server, you will need to transfer files from it by the exact reverse of the above 4-4 VME KERMIT User Guide SEND procedure: all you need to do is reverse the roles of the two machines. Thus, you could take the following steps: a. In terminal mode, start the VME KERMIT program, and issue its RECEIVE command. This tells it that a file is on its way from the micro system. b. Use your micro KERMITs local escape sequence to return back to its command mode. c. Issue the micro KERMITs SEND command. There will normally be a delay before anything happens. The interval may be anything from a few seconds upwards. When the micro system's delay time expires, it will start to send the file 4.5 HANDLING PROBLEMS --------------------- By design, KERMIT is a highly reliable file transfer system, and performs considerably better than any "dumb capture" facility within a terminal emulator. The error-detection capabilities of KERMIT ensure that data is transmitted correctly: in the rare cases where the communications system you are using is unreliable, KERMIT systems will abort a file transfer rather than transfer garbage. That said, there are some cases where you may need to give VME KERMIT some assistance. The most common case will arise when one byte is transmitted by one system but does not arrive at the other. KERMIT breaks data up into small chunks called "packets", and if the missing byte is one of the ones that the KERMIT systems use to control these packets, you may end up with a machine that is waiting forever for something that will never arrive. The simplest way out of this possible problem is for you to keep an eye on the progress of the transfer and see when it appears to grind to a halt. Your micro KERMIT may display a continuous count of packets as they are transmitted and received: normally the number will increment steadily. If the number does not change for a significant time (and here you must bear in mind that the VME system may be running very slowly, so allow a good interval to pass), your micro KERMIT may have a facility, where you can manually force it to to drop whatever it was doing, and retransmit its last packet of data to the other end. If the VME system was stuck waiting for data that had been lost, the retransmission will prod it into life, and the automatic recovery mechanisms of KERMIT should allow the two ends to pick up the transfer from where it stopped. If you wish, you can automate this recovery by using the "timeout" facility of VME KERMIT. This is described below in the section on "Advanced facilities". 4-5 VME KERMIT User Guide 4.6 ADVANCED FACILITIES ----------------------- VME KERMIT permits you to use some more advanced techniques to control file transfers. Some of these facilities involve the micro KERMIT system, and it is possible that you will find a system that does not implement them, since they are fairly recent additions to the KERMIT specification. However, VME KERMIT will be able to detect this, and will act accordingly. 4.6.1. Incomplete file transfers If you interrupt the reception of a file into VME KERMIT (or, indeed if an error such as "file full" occurs), you will be left with a file on disc that contains only part of the data that should have been sent. By default, VME KERMIT will delete this partial file for you. If, though, you want to preserve whatever data has been transferred, you can issue the command SET FILE INCOMPLETE KEEP after which VME KERMIT will close the file normally and preserve it. You can re-instate the normal situation at any time with the command SET FILE INCOMPLETE DISCARD 4.6.2. Using timeouts As we saw above, it is possible to automate the detection that the transfer has stopped. This is done by defining "timeout periods": if one or other system has not received any data when its timeout expires, it will try to re-establish contact with the other. You control the use of timeouts in two ways. The first way enables you to tell the micro system what timeout interval it should use when receiving data from VME KERMIT. This information is transmitted to the micro system when a transfer starts. By default, VME KERMIT asks the micro system not to use a timeout, but you can change this with the SET SEND TIMEOUT command. Note, though, that the micro system may or may not do as it is asked: it may not support the timeout facility; it may ignore the value sent and use its own interval; or the timeout facility may need to be switched on by your giving it a command. VME KERMIT can also timeout if data does not arrive from the micro system within a given interval. By default, a timeout interval of 0 seconds is set, so VME KERMIT will never time out. Issuing the command SET RECEIVE TIMEOUT 30 will set the timeout interval to 30 seconds, and VME KERMIT will time out if it has not received any data in 30 seconds. The SET RECEIVE TIMEOUT command lets you change this interval as required. You can turn the timeout facility off at any time with 4-6 VME KERMIT User Guide SET RECEIVE TIMEOUT 0 Note that here the micro system may ask VME KERMIT to use a specified timeout period when a transfer starts. 4.6.3. Protocol control The rules by which files are transferred between KERMIT systems are termed the "KERMIT protocol". These rules define in detail how data should be transferred: they specify how much can be sent in one chunk or packet; what control sequences indicate the start and end of a packet; what character encoding is to be used, and so on. In almost every case you will have no need to change any of these settings, since they are carefully chosen so that any KERMIT can communicate to any other KERMIT in just about every circumstance. However, it is possible that you may come across cases where you need to change some of the protocol values, either to improve the performance of the file transfer mechanism, or because the standard settings are inappropriate and do not work. The protocol values are changed by the SET command, and VME KERMIT allows you to change all the possible values. The reference section details all the SET commands concerned and their effects. A detailed discussion of the various possibilities is beyond the scope of this user guide, though, since some understanding of the KERMIT protocol is needed. You will find this protocol explained in the "KERMIT Protocol Manual" (use issue 5 or later); or you might contact the systems support personnel at your computer centre. 4-7 VME KERMIT User Guide 5: COMMANDS FOR GENERAL CONTROL OF KERMIT ========================================= In this section, we shall look at the commands you can you can use to control the general operation of VME KERMIT. 5-1 VME KERMIT User Guide EXIT This command causes VME KERMIT to return to the VME command mode at the end of a session. The command format is: EXIT There are no parameters. Example: EXIT HELP This command gives information for the specified command, or allows information for a number of commands to be requested via a menu. The command format is: HELP <command> The parameters are: <command> This parameter must be one of the VME KERMIT commands. If the parameter is omitted, the help command menu will be displayed and you will be able to select th e command for which you require the information. Example: HELP SET FILE TYPE will display the help text for the command SET FILE TYPE. SET DEBUG This command allows you turn the VME KERMIT debugging facility on or off. The command format is: SET DEBUG <level> <action> 5-2 VME KERMIT User Guide The parameters are: <level> This parameter must be one of: FILE (contents of all file records read or written), PROTOCOL (protocol states and events), PACKETS (contents of all packets sent or received), DEVICE (all data transmitted over the communications line) or ALL (all the above). <action> This must be either ON or OFF. If debugging is on, VME KERMIT will output information during all file transfers to enable you to trace errors. It may be configured to record the protocol state, the contents of the file sent or received, the contents of all packets received and transmitted, plus all the data transmitted over the communication line. All this information is output to the users job journal. By default, all debugging is OFF. Example: SET DEBUG PACKET ON will turn on packet level debugging. SHOW This command displays the values of all the KERMIT control values. The command format is: SHOW There are no parameters. Example: SHOW STATISTICS This command displays the statistics about the most recent file transfer, such as the number of packets received etc. The command format is: STATISTICS There are no parameters. 5-3 VME KERMIT User Guide Example: STATISTICS 5-4 VME KERMIT User Guide 6: COMMANDS FOR FILE TRANSFER ============================= In this section we shall look at the detailed format of the commands that you use to transfer files using VME KERMIT, and to control how VME KERMIT will perform the transfers. 6-1 VME KERMIT User Guide RECEIVE This command causes VME KERMIT to wait for a file transfer to be started by the micro system. You will thus need to issue a SEND command to the micro KERMIT in order to make somethong happen. The command format is: RECEIVE <VME-file> The parameters are: <VME-file> This parameter is optional, and specifies the name of a file on the VME system into which you wish data to be transferred. When the command is issued, VME KERMIT will wait passively for a signal from the micro KERMIT that a file transfer is beginning. This signal will include the name of the file that is being sent: if you have included the <VME-file> parameter, this name is for information only, and the data will be written to the file you have identified. If you omit the <VME-file> parameter, VME KERMIT will by default attempt to generate a suitable VME filename from the name supplied by the micro system. Example: RECEIVE MYFILE will cause VME KERMIT to receive a file, and to store it in a file called MYFILE. SEND This command sends a file to the micro KERMIT. The command format is: SEND <VME-file> <remote-file> The parameters are: <VME-file> This parameter is mandatory. It specifies the name of the file on the VME system that you wish to send, and can be any legal VME filename. <remote-file> This parameter is optional. It specifies the filename that VME KERMIT will send to the micro system to 6-2 VME KERMIT User Guide identify the file: this may be used by the micro system as the name of the file that it puts the data into, but this is entirely up to the micro system. If the filename is legal for the micro system, the file would normally be called by this name. You must issue a RECEIVE command to the micro system to prepare it for this SEND. You must issue the SEND first and then issue the RECEIVE to the other system. To allow you to do this VME KERMIT will pause after you issue the SEND command (by default 30 seconds) before it actually starts sending. You can change this pause interval with the SET DELAY command. If you omit the <remote-file> parameter, VME KERMIT will by default generate a "generally acceptable" name from the <VME-file> parameter. It does this by stripping off any user-name, library-name, generation number etc. Example: SEND MYFILE YOURFILE causes VME KERMIT to send the file MYFILE to the micro KERMIT. The file will be identified as YOURFILE by the micro system. SERVER This command causes VME KERMIT to enter server mode and to wait for commands or file transfer requests from the micro system. You will thus be able to control the KERMIT session from your micro. The command format is: SERVER When the command is issued, VME KERMIT will wait passively for commands and file transfer requests from the micro KERMIT. Example: SERVER SET DELAY This command sets the period for which VME KERMIT will wait after you issue a SEND command. The command format is: SET DELAY <number> 6-3 VME KERMIT User Guide The parameters are: <number> The delay in seconds, in the range 5 to 300. When you issue a SEND command, VME KERMIT will do nothing for the specified period to enable you to issue commands to a micro system. By default, VME KERMIT will delay for 30 seconds after you issue a SEND command. Example: SET DELAY 10 causes VME KERMIT to wait for 10 seconds after receiving a SEND command, before starting the file transfer. SET FILE INCOMPLETE This command defines what VME KERMIT will do if wither you interrupt the reception of a file, or if an error occurs while a file is being received. The command format is: SET FILE INCOMPLETE <action> The parameters are: <action> This must be either KEEP or DISCARD. If the action is set to DISCARD, VME KERMIT will delete any file whose reception is interrupted and is thus incomplete. If the action is set to KEEP, VME KERMIT will close the file normally, and you will be able to use whatever data was received before the interruption or error. By default, VME KERMIT will DISCARD an incomplete file. Example: SET FILE INCOMPLETE KEEP causes VME KERMIT to save incomplete files. SET FILE NAMING This command defines how VME KERMIT interprets file names, when the VME filename or the remote filename are not explicitly stated. 6-4 VME KERMIT User Guide The command format is: SET FILE NAMING <action> The parameters are: <action> This must be either NORMAL-FORM or UNTRANSLATED. If the action is set to NORMAL-FORM, VME KERMIT will, when sending a file, and the remote filename is omitted, attempt to genrate a "generally acceptable" name from the VME filename. It does this by stripping off any user-name, library-name, generation number etc. Similarly, when receiving a file, and the VME filename is omitted, VME KERMIT will attempt to generate a suitable name from the name supplied by the remote KERMIT. If action is set to UNTRANSLATED, VME KERMIT will not attempt to generate a standardised name. By default, VME KERMIT will normalise filenames. Example: SET FILE NAMING UNTRANSLATED will turn off file normalisation. SET FILE OVERWRITE This command specifies the action that VME KERMIT must take on reciving a file if the name it tries to store the data under clashes with an existing file. The command format is: SET FILE OVERWRITE <action> The parameters are: <action> This must be either ON or OFF. If the file overwrite facility is ON, VME KERMIT will check whether the name it wishes to use to store incoming data clashes with an existing file name. If it does, VME KERMIT will overwrite the file with the new data. If file overwrite is OFF, VME KERMIT will not overwrite the file, but will report an error. By default, file overwrite is OFF. 6-5 VME KERMIT User Guide Example: SET FILE OVERWRITE ON turns on the file overwrite facility. SET FILE TYPE EBCDIC This command tells VME KERMIT that files it transmits and receives are to taken as containing printable text and to transform them accordingly. The command format is: SET FILE TYPE EBCDIC There no parameters. After using this command, VME KERMIT treats all files as containing printable text. When sending a file, it will translate all EBCDIC text to ASCII, and transform every end of record into KERMIT's standard "end of line" terminator, and the micro KERMIT should then change this into whatever the standard representation of end-of-line is on its own system. When receiving files, VME KERMIT will translate all ASCII text to EBCDIC, and treat every occurrence of the standard KERMIT "end-of-line" indicator as a record terminator. Note, you may need to give an equivalent command to the micro KERMIT system to make it treat the data correctly. By default, VME KERMIT treats files as EBCDIC. Example: SET FILE TYPE EBCDIC makes VME KERMIT treat files as containing EBCDIC data. SET FILE TYPE ASCII This command tells VME KERMIT that files it transmits and receives are to taken as containing ASCII text and to transform them accordingly. The command format is SET FILE TYPE ASCII There no parameters. After using this command, VME KERMIT will transmit the characters from the file exactly as they are, and will not change any of 6-6 VME KERMIT User Guide them. Similary the data it receives will be written to file with no alteration. However, as with EBCDIC files, VME KERMIT will maintain the record format. Note, You may need to give an equivalent command to the micro KERMIT system to make it treat the data correctly. By default, VME KERMIT treats files as EBCDIC. Example: SET FILE TYPE ASCII makes VME KERMIT treat files as containing ASCII data. SET FILE TYPE BINARY This command tells VME KERMIT that all files it receives or sends should be treated as containing binary data. The command format is: SET FILE TYPE BINARY There are no parameters. After using this command, VME KERMIT will transmit the bytes from a file exactly as they are, and will not change any of them. Similarly, the data it receives will be written to file with no alteration. Note, You may need to give an equivalent command to the micro KERMIT system to make it treat the data correctly. By default, VME KERMIT treats files as EBCDIC. Example: SET FILE TYPE BINARY makes VME KERMIT treat files as containing binary data. SET RECEIVE TIMEOUT This command defines the interval after which VME KERMIT will take action if it has received no data from the micro system. The command format is: SET RECEIVE TIMEOUT <interval> 6-7 VME KERMIT User Guide The parameters are: <interval> Specifies the timeout period in seconds, in the range 0 to 94. The command defines the timeout that VME KERMIT is to use. The choice of the timeout period will depend on many factors. Regard should be paid to how fast the VME system is operating, it could be running slowly due to heavy use and also to the delays that operating over a network may impose. Care should be taken not to set the value too low, or VME KERMIT will repeatedly timeout unnecessarily. By default, a timeout interval of 0 seconds is set. Example: SET RECEIVE TIMEOUT 10 causes VME KERMIT to timeout if no data has been received after 10 seconds. SET SEND TIMEOUT This command sets the timeout interval that VME KERMIT asks the micro system to use. The micro system should timeout if no data has been received from VME KERMIT after this interval. The command format is: SET SEND TIMEOUT <interval> The parameters are: <interval> specifies the interval required in seconds, in the range 0 to 94. VME KERMIT will pass this value to the micro system at the beginning of every file transfer. Note, though, that it is entirely up to the micro system whether it uses this value, ignores it, or uses a value of its own. You may need to give the micro system commands to turn its timeout facility on. By default, VME KERMIT requests the micro system to set a timeout value of 0 seconds. Example: SET SEND TIMEOUT 10 causes VME KERMIT to ask the micro system to timeout after 10 seconds if no data has been received from the VME system. 6-8 VME KERMIT User Guide 7: COMMANDS FOR DETAILED PROTOCOL CONTROL ========================================= The commands described in this section are used to exert detailed control over the KERMIT protocol. As explained earlier, it is unlikely that you would ever need to use these commands. You should consult the KERMIT Protocol Manual for a detailed description of the facilities they control. 7-1 VME KERMIT User Guide SET PAUSE This command defines a "turn-round" delay that VME KERMIT will use in packet transmission. It defines the time that VME KERMIT will wait, after receiving a packet from the micro system, before transmitting the next to it. This overcomes problems with some systems that cannot accept input that comes too soon after output. The command format is: SET PAUSE <number> The parameters are: <number> The pause time in tenths of a second, in the range 0 to 50. By default, VME KERMIT does not pause (i.e. the pause value is 0). Example: SET PAUSE 1 causes VME KERMIT to pause for 1 tenth of a second after receiving one packet before sending the next. SET RECEIVE END-OF-LINE This command defines the value that VME KERMIT request the other end to use to signal the end of a packet. The command format is: SET RECEIVE END-OF-LINE <number> The parameters are: <number> The number of the control character in the range 0 to 31 or 127. Note, a number of the control characters are not accepted by VME as a valid end-of-line terminator (see Appendix 2). By default, VME KERMIT asks for packets to be terminated with Carriage Return (hex 0D). 7-2 VME KERMIT User Guide Example: SET RECEIVE END-OF-LINE X09 requests the micro KERMIT to terminate packets with Horizontal Tab (code hex 09). SET RECEIVE PACKET-LENGTH This command defines the maximum packet size that VME KERMIT will ask the micro system to send. The command format is: SET RECEIVE PACKET-LENGTH <number> The parameters are: <number> The maximum size of packet wanted from the micro system, in the range 30 to 94. By default, VME KERMIT asks the micro system to use a maximum packet size of 80 bytes. Example: SET RECEIVE PACKET-LENGTH 60 causes VME KERMIT to request the micro system to use a maximum packet size of 60 bytes. SET RECEIVE PAD-CHARACTER This command defines the control character that VME KERMIT requests the other to use when padding before sending a packet. The command format is: SET RECEIVE PAD-CHARACTER <number> The parameters are: <number> The numeric code of the control character to be used for padding in the range 0 to 31 or 127. Note, a number of the control characters are not accepted by VME as valid pad characters (see Appendix 2). By default, VME KERMIT will ask for a pad character of code 0. 7-3 VME KERMIT User Guide Example: SET RECEIVE PAD-CHARACTER X00 requests the micro KERMIT to pad with NUL characters (code 0). SET RECEIVE PADDING This command defines the number of pad characters that VME KERMIT will ask the other end to send before each packet. The command format is: SET RECEIVE PADDING <number> The parameters are: <number> The number of pad characters to be requested, in the range 0 to 94. By default, VME KERMIT asks for no pad characters to be sent. Example: SET RECEIVE PADDING 10 will cause VME KERMIT to request the micro system to precede each packet with 10 pad characters. SET RECEIVE START-OF-PACKET This command defines to VME KERMIT the control character that the micro system will use to indicate the start of each packet. The command format is: SET RECEIVE START-OF-PACKET <number> The parameters are: <number> The numeric code of the character the micro system will use, in the range 0 to 31 or 127. Note, a number of the control characters are not accepted by VME as a valid start-of-packet marker (see Appendix 2). By default, VME KERMIT will expect the micro system to precede each packet with a hex 1E character. 7-4 VME KERMIT User Guide Example: SET RECEIVE START-OF-PACKET X07 tells VME KERMIT that the micro system will precede each packet with a hex 07 character. SET RETRY This command sets the maximum number of times that VME KERMIT will attempt to send or receive a packet before abandoning the transfer. The command format is: SET RETRY <number> The parameters are: <number> The maximum number of retries to be attempted, in the range 0 to 10. By default, VME KERMIT will retry transfers 4 times. Example: SET RETRY 7 sets the packet retry limit to 7. SET SEND EIGTH-BIT-PREFIX This command defines the eigth-bit-prefix character that VME KERMIT will ask the micro system to agree to use. The command format is: SET SEND EIGTH-BIT-PREFIX <character> The parameters are: <character> The printable character to be used. By default, VME KERMIT will attempt to use the "&" character as its eigth-bit prefix. 7-5 VME KERMIT User Guide Example: SET SEND EIGHT-BIT-PREFIX % sets the eigth-bit prefix character to be "%". SET SEND END-OF-LINE This command defines the control character that VME KERMIT will use to terminate the first packet it sends to the micro system in each transfer. Subsequent packets will be terminated by the character that the micro system requests in its SEND-INIT packet. The command format is: SET SEND END-OF-LINE <number> The parameters are: <number> The numeric code of the character to be used, in the range 0 to 31 or 127. Note, a number of the control characters are not accepted by VME as a valid end-of-line terminator (see Appendix 2). By default, VME KERMIT uses hex 0D (Carriage Return). Example: SET SEND END-OF-LINE 9 causes the first packet sent in each transfer to be ended with Horizontal Tab (code 9). SET SEND PAD-CHARACTER This command defines the padding character with which VME KERMIT will precede the first packet to be sent in a transfer. Subsequent packets will be preceded by the character requested by the micro system in its SEND-INIT packet. The command format is: SET SEND PADCHAR <number> The parameters are: <number> The numeric code of the character to be used, in the range 0 to 31 or 127. Note, a number of the control characters are not accepted by VME as a valid pad character (see Appendix 2). 7-6 VME KERMIT User Guide By default, VME KERMIT uses a pad character of NUL (code hex 0). Example: SET SEND PADCHAR X1A sets the pad character used to be hex 1A. SET SEND PADDING This command defines the number of pad characters VME KERMIT will send before the first packet in a transfer. Subsequent packets will be preceded by the number requested by the micro system in its SEND-INIT packet. The command format is: SET SEND PADDING <number> The parameters are: <number> The number of pad characters to be sent, in the range 0 to 94. By default, VME KERMIT sends no pad characters. Example: SET SEND PADDING 21 causes VME KERMIT to send 21 pad characters before its first packet. SET SEND QUOTE This command defines the character that VME KERMIT will use to prefix control characters in data packets that it sends. The command format is: SET SEND QUOTE <character> The parameters are: <character> The printable character to be used. By default, VME KERMIT uses the "#" character (hash). Note that the "hash" character appears as "pound" on some keyboards and printers. 7-7 VME KERMIT User Guide Example: SET SEND QUOTE $ causes VME KERMIT to prefix control characters it sends in data packets with a "$". SET SEND START-OF-PACKET This command defines the control character that VME KERMIT will send to indicate the start of every packet. The command format is: SET SEND START-OF-PACKET <number> The parameters are: <number> The numeric code of the character to be sent, in the range 0 to 31 or 127. Note, a number of the control characters are not accepted by VME as a valid start-of-packet marker (see Appendix 2). By default, VME KERMIT sends a hex 1E character in front of every packet. Example: SET SEND START-OF-PACKET X08 causes VME KERMIT to precede every packet it sends with a hex 08 character. 7-8 VME KERMIT User Guide 8: OBTAINING, BUILDING AND MODIFYING VME KERMIT =============================================== This chapter describes how you can get hold of VME KERMIT and build it from the S3 and MTUP language sources, or modify an existing version. 8-1 VME KERMIT User Guide 8.1 OBTAINING VME KERMIT ------------------------ You can obtain the VME KERMIT files by file transfer over the JANET or PSS networks, or by using KERMIT itself, from Lancaster University. You will eventually have a set of S3 and MTUP source files from which you need to generate compiled OMF. There are two SCL files: KERMIT, an interface procedure, and KMT_SCL which is executed to compile and collect your version of VME KERMIT. 8.1.1 The source files VME KERMIT source is held in a fair number of files and is now quite large (and still growing). The source is split by functionality. The organisation is not fixed, we shall refine it with experience and as the system changes, so the names are not guaranteed to be unchanged from one release to another. For version 1.01 and later, the files that make up VME KERMIT are are as follows: VME KERMIT as issued consists of four types of file. The first type consists of the S3 source files: KMT_DATA_MODULE Global declarations. KMT_DH_MODULE Communications device handling code. KMT_EH_MODULE Error handling code. KMT_FH_MODULE File handling code. KMT_MAIN_MODULE Entry code. KMT_PH_MODULE Protocol handling code. KMT_PP_MODULE Packet handling code. KMT_SP_MODULE Support procedures. KMT_UI_MODULE User interface code. The second type of the file consists of the MTUP source files: KMT_HELP_MTM Help message texts. KMT_SP_MTM Support procedures message texts. The third type of file consists of SCL files. KERMIT Interface procedure. KMT_SCL Compilation and collection SCL. The fourth type of file consists of the User Guide: VME_KMIT_DOC User Guide documentation. 8-2 VME KERMIT User Guide 8.3 BUILDING VME KERMIT FROM SOURCE ----------------------------------- Prior to generating VME KERMIT check that the SCL interface procedure KERMIT meets your requirements. In particular, ensure that the BOOL value ASG is set appropriately. It should be set TRUE if terminal connection to VME is via ASG, but FALSE if via some other communications controller, eg NIC or CSC. If in doubt set ASG FALSE. The purpose of this BOOL is to allow checking of control character setting for START-OF-PACKET etc. VME I/O is not transparent to all control characters. The ASG can handle a superset of the characters that can be handled by CSC or NIC. If you wish to change the default VME KERMIT option (see 3.1) this can be altered most easily in the SCL interface procedure KERMIT. Generating VME KERMIT from the S3 and MTUP sources is a fairly easy process. Having transferred the files to your VME filestore you can compile them by executing the SCL file KMT_SCL. Edit this file to suit your VME filestore, then execute the SCL file as follows: EXSCL(FIL=KMTSRC.KMTSCL) 8.4 CHANGING KERMIT DEFAULTS ---------------------------- If you have the S3 compiler, you can change the defaults by altering the values held in the source files (in particular the procedure KMT_SP_SET_DEFAULTS in KMT_SP_MODULE) and re-compiling the source. 8-3 VME KERMIT User Guide Appendix 1. VME KERMIT capabilities =================================== Local operation: No Remote operation: Yes Transfer text files: Yes Transfer binary files: Yes (prefix only) Wildcard send: No ^X/^X interruption: Yes (receive only) Filename collision avoidance: Yes Can timeout: Yes 8th-bit prefixing: Yes Repeat count prefixing: No Alternate block checks: No Terminal emulation: No Communications settings: No Transmit BREAK: No IBM communication: No Diagnostic logging: Yes Session logging: No Raw transmit: No Act as server: Yes Talk to server: No Advanced server commands: No Local file management: No Handle file attributes: No Command/init files: No Host commands: No Printer control: No A1-1 VME KERMIT User Guide Appendix 2. Valid VME control characters ======================================== The control characters that are acceptable to VME depend on the communications device through which the terminal running Kermit is routed. The ASG permits a greater range of control characters than do CSC or NIC. Character Input via Output via name dec hex ASG CSC/NIC ASG CSC/NIC NUL 0 00 + - + + SOH 1 01 + - - - STX 2 02 + - + + ETX 3 03 + - - - EOT 4 04 + - - - ENQ 5 05 + - + + ACK 6 06 + - + + BEL 7 07 + + + + BS 8 08 + + + + HT 9 09 + - + + LF 10 0A + - - - VT 11 0B + - + + FF 12 0C + - + + CR 13 0D + - + + SO 14 0E + + + + SI 15 0F + + + + DLE 16 10 - - + + DC1 17 11 - - + + DC2 18 12 - - + + DC3 19 13 - - + + DC4 20 14 + + + + NAK 21 15 + - + + SYN 22 16 + - + + ETB 23 17 + - + + CAN 24 18 + - + + EM 25 19 + + + + SUB 26 1A + + + + ESC 27 1B + + + + FS 28 1C + + + + GS 29 1D + + + + RS 30 1E + + + + US 31 1F + + + + DEL 127 7F + + + + A2-1 VME KERMIT User Guide Appendix 3. Running KERMIT over a JNT PAD ========================================= KERMIT may be ran over a JNT PAD, but special attention must be made to the KERMIT configuration parameter settings and to the PAD settings. The choice of the KERMIT start of packet marker and end of line terminator will dictate the PAD settings required. Normally, the additional PAD settings of TRANSPARENT and NOPRINTMASK will be sufficient. However, the FORWARD and LFINSERT PAD settings may also require consideration. A3-1 VME KERMIT Questionaire Please reply to the following questions and return to: David Lord, S.W.U.R.C.C. The University Of Bath, Claverton Down, Bath. BA2 7AY. 1. Name of organisation: 2. Address of organisation: 3. Specify the KERMIT implementations with which VME KERMIT is to operate. 4. List any problems encountered during the installation of VME KERMIT. 5. Comment on the contents and structure of the User Guide. VME KERMIT Questionaire 6. Other comments.