A1.2 COMMANDS FOR TRANSFERRING DATA In this section we shall look at the detailed format of the commands that you use to transfer files using BBC KERMIT, and to control how BBC KERMIT will perform the transfers. GET ~~~ This command should only be used if the remote KERMIT is running in server mode. BBC KERMIT will send the server a command, requesting it to transfer a file: the effect is to "pull" a file from the remote server to BBC KERMIT. The format of the command is this: GET The parameters are as follows: This parameter is mandatory, and specifies the name of the file on the remote machine. The format of the name will, of course, be that required by the remote machine. This parameter is optional, and specifies the name of the file on the BBC system into which you wish data to be transferred. This name may include drive and directory specifications if you wish the file to be on a drive and directory other than the current default. When this command is issued, BBC KERMIT will send a command to the remote server to pull the file from it. The transfer will take place automatically, and you need do nothing further. There are several points to be considered about the format and use of the filename parameters. 1. If you have used the SET DESTINATION MEMORY or SET DESTINATION PRINTER commands to transfer data into the BBC's RAM or to a printer instead of into a file, you must omit the parameter. 2. If the destination of the data is a file, and you omit the parameter, BBC KERMIT will try to generate a legal BBC filename from the you supplied. If this name is the same as a file that already exists, then by default BBC KERMIT will try to alter it until there is no clash. The display will tell you what is happening, and give you the name of the file that is actually going to be written. You may prevent this renaming operation with the SET FILE WARNING command: if you turn the facility off, any existing file will be overwritten. 3. If you do specify a parameter, then BBC KERMIT will use this file for the received data whether or not it exists already. It will not attempt to rename the file to miss an existing one. 4. You may GET a group of files from the remote server by putting that system's wildcard characters into the . The remote server will send each file in turn automatically, and you need take no action until the group transfer is complete. Note that, if you do include wildcards in the parameter, you must omit the parameter or all the files from the remote server will be placed in the same BBC file. RECEIVE ~~~~~~~ This command should be used only if the remote KERMIT is not running in server mode, and causes BBC KERMIT to wait for a file transfer to be started by the remote system. You will thus need to issue a SEND command to the other KERMIT in order to make something happen. The command format is this: RECEIVE The parameters are: This parameter is optional, and specifies the name of a file on the BBC system into which you wish data to be transferred. It must be a legal BBC filename, and can include drive and directory specifications. When the command is issued, BBC KERMIT will wait passively for a signal from the remote 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 parameter, this name is for information only, and the data will be written to the file you have identified. If you do omit the parameter, BBC KERMIT will attempt to generate a suitable BBC filename from the name supplied by the remote system. The actions taken are the same as those described above in the GET command. Some points that must be considered when using the RECEIVE command are: 1. If you have used the SET DESTINATION MEMORY or SET DESTINATION PRINTER commands to transfer data into the BBC's RAM or to a printer instead of into a file, youmust omit the parameter. 2. If you have directed the remote system to send a group of files by including a wildcard in the filename, you should omit the parameter, or all the data will end up in the one BBC file, each file overwriting the previous ones. SEND ~~~~ This command is used whether or not the remote KERMIT is a server, and sends a file or group of files to it. The command has two possible formats: SEND used if you are transferring data from a BBC file, and SEND if you are sending data from the BBC's memory. The parameters are as follows: This parameter specifies the name of the file on the BBC that you wish to send, and can be any legal BBC filename. This parameter is optional if you are sending data from a file, and mandatory if you are sending data from the BBC's memory. It specifies the filename that BBC KERMIT will send to the remote system to identify the file: this may be used by the remote system as the name of the file that it puts the data into, but this is entirely up to the remote system. If the filename is legal for the remote system, the file would normally be called by this name. If the remote KERMIT is not running in server mode, you must issue a RECEIVE command to the remote system to prepare it for this SEND. You can either do this before you issue the SEND command, or you can issue the SEND first and then issue the RECEIVE to the other system. To allow you to do this latter option, BBC KERMIT will pause after you issue the SEND command (by default for 30 seconds) before it actually starts sending. You can change this pause interval with the SET DELAY command; alternatively, pressing any key while BBC KERMIT is waiting will make it start the transfer immediately. Some points to note about the SEND command are: 1. If you omit the parameter, BBC KERMIT will generate a "generally acceptable" name from the parameter and pass this to the remote system. It forms this name by stripping off any drive and directory specifications, then adding a filename suffix in the form ".XXX" to what remains. By default, the suffix added is ".BBC", but the SET FILE SUFFIX command allows you to change this, or suppress it altogether. 2. You may send a group of files in one operation by including the "*" or "#" wildcard characters in . BBC KERMIT will then send all files in the current directory whose names match. You should not specify drive or directory details in the name if you include wildcards: you may select different drives or directories with the *DIR command before you issue the SEND if you need to. You must omit the name if you include wildcards in . SET DELAY ~~~~~~~~~ This command sets the period for which BBC KERMIT will wait after you issue a SEND command. The command format is SET DELAY The parameters are The delay in seconds, in the range 0 to 255. When you issue a SEND command, BBC KERMIT will do nothing for the specified period to enable you to issue commands to a remote system. You can interrupt the delay and make BBC KERMIT proceed by pressing any key. By default, BBC KERMIT will delay for 30 seconds after you issue a SEND command. Example: SET DELAY 5 will cause BBC KERMIT to wait after a SEND command for 5 seconds, or until a key is pressed. SET DESTINATION FILE ~~~~~~~~~~~~~~~~~~~~ This command specifies that any data received by BBC KERMIT is to be stored in a file, rather than placed into the BBC's memory or sent directly to the parallel printer. The command format is SET DESTINATION FILE This is the default condition when BBC KERMIT is entered. SET DESTINATION MEMORY ~~~~~~~~~~~~~~~~~~~~~~ This command, available in the sideways ROM version only, specifies that data received by BBC KERMIT is to be placed into the BBC's memory rather than being stored in a file. The command format is SET DESTINATION MEMORY
The parameters are:
This specifies the address where you want the first byte received to be placed. The value must be from 1 to 4 hexadecimal digits, optionally preceded by "X", "$" or "&". After issuing this command, any data that you receive is placed in memory instead of a file. The first byte is placed at the specified address, and subsequent bytes are placed at higher addresses. BBC KERMIT will not allow the received data to overflow into the mode 7 file transfer status display screen, so that the highest address available is &7BFF. BBC KERMIT makes no checks on the address supplied: it is up to you to ensure that you direct data to a sensible place. The destination for incoming data will remain the BBC's memory until you specify otherwise. Note that BBC KERMIT will process the data received according to the currently defined file type, even though the destination is not a file. The default condition for BBC KERMIT is to place data in files. The RAM version of BBC KERMIT always uses destination FILE. Example: SET DESTINATION MEMORY 1900 will cause incoming data to go to memory, starting at address &1900 (the default value of PAGE for Acorn DFS systems). SET DESTINATION PRINTER ~~~~~~~~~~~~~~~~~~~~~~~ This command specifies that data received by BBC KERMIT is to be transferred directly to a printer rather that stored in a file or in memory. The command format is SET DESTINATION PRINTER The default condition is for BBC KERMIT to transfer data into files. Note that BBC KERMIT will process the data received according to the currently defined file type, even though no file is involved. SET INCOMPLETE ~~~~~~~~~~~~~~ This command defines what BBC KERMIT will do if either you interrupt the reception of a file, or if an error occurs while a file is being received. The command format is SET INCOMPLETE The parameters are This must be either KEEP or DELETE. If the action is set to DELETE, BBC KERMIT will delete any file whose reception is interrupted and is thus incomplete. If the action is set to KEEP, BBC KERMIT will close the file normally, and you will be able to use whatever data was received before the interruption or error. By default, BBC KERMIT will DELETE an incomplete file. Example: SET INCOMPLETE KEEP causes BBC KERMIT to leave an incomplete file on the disc after the transfer. SET FILE BUFFER-SIZE ~~~~~~~~~~~~~~~~~~~~ This command, available in the sideways ROM version only, defines the size of buffer BBC KERMIT uses when reading or writing files. The command format is SET FILE BUFFER-SIZE The parameters are: This specifies the size of the buffer, in 256 byte pages. It must be a value from 1 to 64. BBC KERMIT uses the file buffer to read and write files in large chunks, which can improve performance in some cases. However, with large buffers, although BBC KERMIT will access the discs less frequently, it will take longer when it does, so the remote KERMIT may mistakenly think that contact has been lost. If this occurs, the buffer size can be reduced. By default, BBC KERMIT uses a buffer of 16 pages (4K bytes). The RAM version of BBC KERMIT uses a file buffer of 8 pages (2K bytes). Example: SET FILE BUFFER-SIZE 1 changes the file buffer to be 1 256 byte page long. SET FILE SUFFIX ~~~~~~~~~~~~~~~ This command defines the characters that BBC KERMIT will add to a BBC filename when generating a "generally acceptable" filename to send to the remote system. The command format is SET FILE SUFFIX The parameters are This is the suffix you wish added, consisting of up to 8 characters. The "." is not part of the suffix and should not be included. BBC KERMIT will, when generating a "generally acceptable" filename, take the final part of the BBC filename, add a ".", then add the suffix defined by this command. This command lets you change the suffix to suit your requirements. If you omit the string, BBC KERMIT will not add anything to the BBC filename at all (not even the ".") By default, the suffix added to the BBC filename is "BBC". Examples: SET FILE SUFFIX ADE will cause BBC KERMIT to add ".ADE" to BBC filenames for the remote name. SET FILE SUFFIX will cause it not to add anything at all to the BBC filename. SET FILE NAME ~~~~~~~~~~~~~ This command controls how BBC KERMIT handles the filename given it by a remote system when it is receiving a file. The command format is SET FILE NAME The parameters are This can be one of NORMAL or UNTRANSLATED. If you set the action to NORMAL, BBC KERMIT will assume that the name given by the remote system has the standard "name.type" form, and will generate a BBC filename from it. If the action is UNTRANSLATED, BBC KERMIT will use the exact name to create the file: it is up to you to ensure that what the remote system gives it really is a valid BBC file name. By default, BBC KERMIT will translate filenames sent by the remote system. (action NORMAL). Example: SET FILE NAME UNTRANSLATED causes BBC KERMIT to use the name sent exactly as it is. SET FILE TYPE ASCII ~~~~~~~~~~~~~~~~~~~ This command tells BBC KERMIT that files it transmits and receives are to taken as containing printable ASCII text and to transform them accordingly. The command format is SET FILE TYPE ASCII The parameters are This optional parameter tells BBC KERMIT how a file you are sending denotes the end of a line of text, or how you wish this to be denoted in a file you receive. It can be one of LFCR, CRLF, CR or LF, where LF stands for the Line Feed character, and CR for Carriage Return. If you omit the parameter, BBC KERMIT assumes LFCR. After using this command, BBC KERMIT treats all files as containing printable ASCII text, with the end of each line indicated by the specified sequence of control characters. When sending a file, it will transform every occurrence of the specified sequence into KERMIT's standard "endofline" indicator, and the remote KERMIT should then change this into whatever the standard representation of end-of-line is on its own system. When receiving files, BBC KERMIT will change every occurrence of the standard KERMIT indicator into the specified sequence of bytes. Note that this command has effect even if the source or destination of data is memory rather than files. Also, you may need to give an equivalent command to the remote KERMIT system to make it treat the data correctly. By default, BBC KERMIT treats files as ASCII, with end of line indicated by LFCR bytes. Example: SET FILE TYPE ASCII CR specifies a file type of ASCII, with lines being terminated with a CR (&0D) byte. SET FILE TYPE BINARY ~~~~~~~~~~~~~~~~~~~~ This command tells BBC KERMIT that all files it receives or sends should be treated as containing binary data. The command format is SET FILE TYPE BINARY After using this command, BBC 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 that this command has effect even if the source or destination of data is the BBC's memory or the parallel printer rather than a file. Also, you may need to give an equivalent command to the remote KERMIT system to make it treat the data correctly. By default, BBC KERMITs treats files as ASCII text. Example: SET FILE TYPE BINARY makes BBC KERMIT treat files as containing binary data. SET FILE WARNING ~~~~~~~~~~~~~~~~ This command specifies the action that BBC KERMIT must take on receiving a file if the name it tries to store the data under clashes with that of an existing file. The command format is SET FILE WARNING The parameters are This must be either ON or OFF. If the file warning facility is ON, BBC KERMIT will check whether the name it wishes to use to store incoming data clashes with an existing file name. If it does, a warning is displayed on the screen, and BBC KERMIT will change the right-most character of the name to a "+" and check again. If this still clashes, the next right-most characer is changed, and so on. An error will occur if no unique name is found by the time the name has been changed to be entirely "+" characters. If file warning is OFF, BBC KERMIT will make no checks. Any existing file will be overwritten with the new data. By default, file warning is ON. Example: SET FILE WARNING OFF turns off the file warning facility. SET RECEIVE TIMEOUT ~~~~~~~~~~~~~~~~~~~ This command defines the interval after which BBC KERMIT will take action if it has received no data from the remote system. The command format is SET RECEIVE TIMEOUT The parameters are Specifies the timeout period in seconds, in the range 0 to 255. The command defines the timeout that BBC KERMIT is to use. Note, though, that BBC KERMIT will not perform any timeout at all unless you have used the SET TIMER command to turn the facility on - by default it is OFF. The choice of the timeout period will depend on many factors. Regard should be paid to how fast the remote system is running - if it is mainframe, 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 BBC KERMIT will repeatedly timeout unnecessarily. By default, a timeout interval of 15 seconds is set. Example: SET RECEIVE TIMEOUT 10 causes BBC KERMIT to timeout if no data has been received after 10 seconds, providing that the timeout facility is turned on. SET SEND TIMEOUT ~~~~~~~~~~~~~~~~ This command sets the timeout interval that BBC KERMIT asks the remote system to use. The remote system should timeout if no data has been received from BBC KERMIT after this interval. The command format is SET SEND TIMEOUT The parameters are specifies the interval required in seconds, in the range 0 to 94. BBC KERMIT will pass this value to the remote system at the beginning of every file transfer. Note, though, that it is entirely up to the remote system whether it uses this value, ignores it, or uses a value of its own. You may need to give the remote system commands to turn its timeout facility on. By default, BBC KERMIT requests the remote system to time out after 15 seconds. Example SET SEND TIMEOUT 10 causes BBC KERMIT to ask the remote system to time out after 10 seconds if no data has been received from the BBC system SET SOURCE FILE ~~~~~~~~~~~~~~~ This command, available in the sideways ROM version only, specifies that data transmitted to the remote system is taken from files rather than the BBC's memory. The command format is SET SOURCE FILE This is the default condition when BBC KERMIT is entered. The RAM version of BBC KERMIT always uses source FILE. SET SOURCE MEMORY ~~~~~~~~~~~~~~~~~ This command, available in the sideways ROM version only, causes data transmitted to the remote system to be taken from the BBC's memory rather than from files. The command format is SET SOURCE MEMORY The parameters are Specifies the address of the first byte to be transferred. The value must be from 1 to 4 hexadecimal digits, optionally preceded by "X", "$" or "&". Specifies the address of the last byte to be transferred plus one. The value must be from 1 to 4 hexadecimal digits, optionally preceded by "X", "$" or "&". After issuing this command, BBC KERMIT will send data from the BBC's memory instead of from a file. The area of memory to be transmitted is defined by the two command parameters: it is up to you to ensure that the addresses are sensible. Note that BBC KERMIT will still process the data transmitted according to the defined file type, even though the source of data is not a file. By default, BBC KERMIT will use source FILE. The RAM version of BBC KERMIT always uses source FILE. Example SET SOURCE MEMORY 1B00 3200 will cause BBC KERMIT to send the data between memory addresses &1B00 and &31FF inclusive in a SEND command. SET TIMER ~~~~~~~~~ This command controls whether BBC KERMIT will timeout if no data is received from the remote system after the timeout period has expired. The command format is SET TIMER The parameters are This must be either ON or OFF. If the timer facility is turned ON, BBC KERMIT will use the value defined by SET RECEIVE TIMEOUT to time the remote system out. If it is OFF, the value is ignored, and BBC KERMIT will wait for ever for data. By default, the timer is OFF. Example SET TIMER ON turns the timeout facility on.