BBC Micrcomputer X-talk User Guide Release Version 1.0 1st Nov 1984 Keith Mitchell ERCC Real Time Support Group Contents 1) Introduction 2 2) The BBC Microcomputer 2 3) Getting Started 2 4) Terminal Emulation Mode 3 4.1 Overview 3 4.2 Function and Editing Keys 3 4.3 Flow Control 4 4.4 Graphics Driving 5 5) Local Command Options 5 5.1 Overview 5 5.2 Getfile & Putfile 5 5.3 File Types 6 5.4 Operating System Commands 6 5.5 Configure 7 5.6 Printer Echo 7 5.7 Quit 7 5.8 Recovering From Problems 7 6) Hosts and Modes of Connection 8 7) Performance 8 Appendix I - Known Problems 9 Appendix II - Error Messages 10 Appendix III - Later Versions 12 1 1) Introduction The purpose of this program is to allow the BBC Microcomputer to be used as a terminal to a mainframe on the ERCC network, and to allow file transfer between the BBC's disk(s) and the mainframe filestore. To make use of existing software support, and ensure compatibility, the ERCC X-talk (Crosstalk) protocol has been used. The program is thus functionally very similar to Micro Support's TTY program in the X-talk package for UCSD machines, and the same host support routines are used. This software is fully supported by the Real Time Support Group (RTSG) only on those BBC micros which are used for real time computing. Note that the program works exclusively from disks. It it thus not possible to transfer files directly between cassette tape and EMAS. Acknowlegement is made to Micro Support for providing information and assistance regarding the X-talk Protocol. 2) The BBC Microcomputer The minimum hardware required for this program to work is a BBC Micro model B, with a single 40 track disk drive and monochrome monitor. Note that the micro must have Machine Operating System (MOS) version 1.2. See the User Note "The BBC Micro as a Laboratory Tool" for more details of approved hardware. The connection to the network is via the BBC's RS423 serial port to a network TCP, possibly via a dial-up link. It is hoped that future versions of this program will be provided on ROM chips for the BBC's "sideways" ROM facility, rather than on disk. This will allow it to be used with non disk-based systems, file transfer being directly to or from cassette or memory. 3) Getting Started Three things are required to connect the BBC micro to the ERCC network: (1) A connection to a TCP, as for an ordinary terminal. If you do not already have this, please contact J F Livingstone, ERCC (central area ext. 6408), who will advise on the cost involved. (2) A suitable connecting lead. This is available from "Microworld", 12 Leven St, Tollcross, Edinburgh (031 228 1111). (3) Software. The software is available from C J Adie, ERCC (KB ext. 2611). Please supply a blank, formatted disk, stating whether 40 or 80 track. Please report any suspected communications malfunctions to KB ext. 2737 in the first instance. 2 The program comprises 4 files: XTLK10A, XTLK10B, XTLK10C and XTLK10Y, together with a !BOOT file for startup. Auto-booting the disk, by placing it drive 0, holding down SHIFT and pressing BREAK, will run the program. A title will appear, and the program will enter terminal emulation mode (defaulting to 1200 baud). It is strongly recommended that the user keeps the disk on which the software is supplied as a "master", and makes a copy using *BACKUP onto another disk for day to day use. When running the Micro under this program, the user should ensure that the relevant support is provided on the host. For EMAS, the two once-and-for-all commands should have been entered: OPTION SEARCHDIR=MICROS.EMASLIB OPTION ITINSIZE=16 The ERCC Filestore has this support built in. 4) Terminal Emulation Mode 4.1 Overview When in terminal emulation mode, the BBC behaves exactly as a normal terminal with a 25x80 display, but with some additional facilities. The default baud rate is 1200 receive and transmit, but this can be changed to a range of values between 75 and 19200 baud - see 'configure' below. All the black keys on the keyboard generate the normal codes, including control codes, and send them to the host. Note that although the escape key behaves exactly as it would on a normal terminal, 'BREAK' still has its normal BBC function of causing a system reset, and should not be pressed. 4.2 Function & Editing Keys The red function keys have two roles when running this program - they are used to select the various program options when pressed together with the control key, but by themselves can be made to generate strings or ASCII codes as in normal BBC operation. The program options which can be selected are as follows - CTRL/f0 - Initiate 'GETFILE' to transfer file from host to BBC. CTRL/f1 - Initiate 'PUTFILE' to transfer file from BBC to host. CTRL/f2 - Allow BBC operating system ('*') commands to be entered without leaving the program. CTRL/f3 - Initiate 'CONFIGURE' to modify various program parameters. 3 CTRL/f4 - Switch local printer echo on. CTRL/f5 - Switch local printer echo off. CTRL/f6 - Exit program and return to BASIC. It is a good idea to put a strip of paper above the keys to remind the user of their function. A suitable strip is provided with the software. The brown editing keys (up,down,left,right & copy) have two modes of operation - LOCAL or REMOTE editing. In the local edit mode (the default), the keys behave exactly as they do in normal BBC operation. Thus in terminal emulation mode they can be usefully used to correct mistyped commands without retyping the whole line. Alternatively, they can be set up to hold strings like the red function keys. In REMOTE edit mode, the edit keys generate ASCII codes corresponding to the arrows (VT,LF,BS,HT,BEL respectively), and the function keys no longer generate strings. This might be of some use with screen editors. The local/remote edit option is selected by 'Configure' (see below). 4.3 Flow Control All output to the terminal from the TCP is subject to XON/XOFF flow control. Thus if the TCP is sending characters too quickly for the micro, the micro will send an XOFF character to the TCP to temporarily halt it, and send an XON when it is ready again. In normal terminal emulation mode, at any speed, the micro is able to keep up with the TCP, and no flow control characters will be sent. However, if the micro is doing anything which slows or halts output to the screen, it may need to make use of this facility. This is likely when echoing output to a local printer which is slower than the baud rate, or when drawing graphics rather than just characters on the screen. It can also happen if the user uses CTRL-SHIFT to halt output on the BBC, or performs local operations when output is coming from the host. When EMAS is the host, flow control must be explicitly enabled, otherwise the user may be logged off with the "**Terminal Violation" error message. To explicitly set flow control on, the EMAS command: SETMODE FLOW=ON should be used, or else the TCP command F Other hosts may have different methods, or may provide flow control by default. 4 4.4 Graphics Driving Because of the nature of the VDU drivers of the BBC, and the fact that most ERCC links allow 8-bit transmission, it is very straightforward to use the BBC as a colour graphics display terminal driven by the host, using this program. To do this, the host program should send to the terminal output stream the control codes and data bytes as described in the BBC User Guide PP377-389. Note that all output should be via an 8-bit link and be transparent, ie set graphmode on for ERCC TCPs. 5) Local Command Options 5.1 Overview After the relevant CTRL-FN key has been pressed, local mode will be entered. Apart from 'Configure', this is indicated by all output appearing in inverse video. The user will then be presented with a series of prompts outlining what to do next. At any point in local mode, the user may return to terminal emulation mode by pressing the escape key. When the local action is completed, messages as to its success or failure will be output, and terminal emulation mode reentered to. Error messages are always prefixed by a double star sequence ('** '), and if they are not directly from the X-talk program, they will be prefixed by one of '** Host:' , '** DFS:', or '** MOS:', depending on whether they originate from the host, BBC Disk Filing System, or some other part of the BBC Machine Operating System. 5.2 Getfile & Putfile Once in local mode, the user will be prompted for the names of the files to be transferred, source filename first, and destination filename second. To each prompt, a list of filenames in host or BBC format, separated by commas, should be entered. The source and destination files are paired up according to their place in the lists. If when fetching a file from the host to the micro, a file of the same name as the destination file exists already on disk, the user will be asked if the old file is to be overwritten. Various errors may occur during file transfer; this will cause the current transfer to be aborted. The program will then either return to terminal emulation mode, or attempt the next transfer in the list. A transfer may be aborted by the user pressing the escape key. Once a file has been successfully opened, and the transfer initiated at the host end, the name of the source file will be output to the screen. During transfer, an arrow will be output to the screen for each block of 256 bytes sucessfully 5 transferred. When the transfer is complete, the destination filename will be printed at the end of the line. The program will then either start the next transfer, or return to terminal mode. If you only have one drive, and you wish to transfer files using a disk other than the X-talk disk, then enter Putfile or Getfile (using CTRL/F0 or CTRL/F1), remove the X-talk disk, insert your data disk, and continue as usual. Remember to replace the X-talk disk when you have finished transferring files. 5.3 File Types There are two modes of file transfer - TEXT and BINARY. Text mode is the default, and is used for transferring BBC files generated by *SPOOL, *BUILD or BPUT#, and readable by *TYPE, *LIST, *EXEC or BGET# (or files output from word processor programs). This mode is required to translate between the different newline representations on BBC and host. Binary mode is used for transferring files directly without any newline translation. Selection between the two modes is done via 'Configure'. The default mode when the program is run is TEXT. It may be desirable to transfer a BASIC program between host and BBC, perhaps to edit the file on the host. The format the BBC normally stores BASIC programs in is an encoded binary format, which is meaningless to the host, so it is important that the file is in character format for sending to EMAS. The conversion can be performed by LOADing the file and using *SPOOL to list it to a disk file which can be transferred. Likewise, a character file from EMAS could be loaded into memory using *EXEC. 5.4 Operating System Commands After entering local mode, the user will be given the prompt '>*'. At this point any command available to the BBC as an MOS '*' command may be entered, with some exceptions. (Note that the user need not type the star.) This allows the user to examine and modify the local filestore, and to control other options on the micro. Typing escape at any point, or to an empty line will cause the micro to return to terminal emulation mode, as will any MOS errors caused by the command. In this mode it is possible to define keys using '*KEY', and change the function of the edit using *FX4. However, to prevent the operation of the program being interfered with, *FX calls 2,3,5,7,8,225,226,227,229 & 232 will have no effect. Also, the DFS commands *COPY, *BACKUP and *COMPACT (or similar) should not be used as they will overwrite memory and corrupt the program. Note that although other filing systems may be active, the file transfer operations are only designed to work with the DFS. 6 The user should not use *DIR or *DRIVE to change the default drive or directory, as the program will be unable to access the XTLK files. If you wish to transfer a file which is not on the current drive/directory you should enter the full file specification when prompted for the local file name. Another feature of command mode is that any control characters typed are passed to the VDU drivers, allowing mode etc to be changed locally. 5.5 Configure This a separate program which is loaded in whenever it is required. It allows the transmit & receive baud rates, file transfer mode, 8th bit mask, and edit mode to be selected. The user is presented with a menu for each of these, the currently selected option in each menu being illuminated. One of the menus, the active one, will be illuminated more brightly than the rest. To change an option in the active menu, the space bar should be pressed, and to change which menu is active, the TAB key should be pressed. When all options are as required, the escape key should be pressed to return to terminal emulation. All the options except the bit mask have been explained previously. The choice between 7 and 8-bit modes depends on the TCP link. The default is 8-bit, as only old or dial-up lines are 7-bit. In 7-bit mode, the top (parity) bit is set to zero for all transferred data, and any attempt to send 8-bit values will result in corrupted data. 5.6 Printer Echo In some circumstances it may be useful to have a teletype-like option, in which anything printed on the screen is also printed on the micro's printer. This is possible only if a parallel printer is connected to the micro. To echo output to the printer, press , and to switch back to screen only, use . Remember flow control should be set on. 5.7 Quit This is used for a clean return to BASIC, as if the X-talk program had never been used. The user will be asked for confirmation after this. Remember it will not log you off the host. 5.8 Recovery from problems in the use of the Get and Put File The following is a suggested procedure to attempt to recover from a problem. Carry on down the list until the host responds. a) Wait at least 2 minutes to see if an arrow appears to indicate that the system is still transferring a file. b) Send CTRL/S (the XON character) followed by carriage return to flush output in case the system is stuck in XON/XOFF flow control. 7 c) Type '?' followed by a carriage return. This will free the system if it is stuck in putfile. '?' is the file terminator. d) Reset the BBC Micro and X-talk program. Repeat b) and c). e) Check your TCP or host is active. f) If all else fails, ring the host operators and ask them to cancel the host process before logging back in. 6) Hosts and Modes of Connection This program is tailored to work with the EMAS and FSTORE implementations of X-talk, connected to an ERCC TCP. The X-talk protocol is also implemented on other hosts, including UCSD and VAX/VMS. The program works when the BBC micro is directly connected to VAX (but not when connected through a TCP). The program also works into a Sirius running the HOST program under UCSD. (However, there may be problems if a p-code file is to be transferred. See the Micro Support Unit for details.) 7) Performance Over a TCP to EMAS link at 1200 baud, the Putfile speed is about 90-100 characters per second, the Getfile speed about 100-110 cps. 8 Appendix I - Known Problems I.1 Hanging in Putfile Due to a shortcoming in the BBC DFS V0.90, it is possible that the system may hang while sending a file to the host. This is associated with a timing problem with the disk drives, and has so far only happened at 1200 baud. The program compensates for this, but different combinations of disk drives and baud rates may cause very occasional problems. If this happens, contact RTSG who may be able to adjust the program for you. Unfortunately the only way out of this problem if it happens is to press the BREAK key, and restart the program. Once back in terminal emulation mode, typing '?' will terminate the transfer. Copy the problem file onto another disk, and try again. Hopefully later versions of the DFS will not have this bug. I.2 Screen Modes Currently the X-talk program takes up about 8K of RAM, and this together with the RAM taken up by the operating system, means that the 3 highest-resolution (20K) screen modes, modes 0,1 & 2, cannot be used. However, if one of these modes is selected by VDU 22 from the host, or from the keyboard in *command mode, no check will be made and the mode will be entered. This causes corruption of the program, and it will eventually crash. Later X-talk versions, provided in ROM, should avoid this. 9 Appendix II - Error Messages These fall into 3 categories - errors from the X-talk program, error messages from the host, and error messages from the BBC's operating system. Error messages from the X-talk program and the host are generated during file transfer, those from the MOS either during file transfer or local *commands. II.1 X-talk Errors Checksum Faulty (Getfile only) Checksum sent by host does not agree with sum calculated by micro - probable corruption of data. No Checksum Micro did not receive checksum at end of file from host - may be using wrong version of X-talk on host. Transfer Aborted by User The user has typed the escape key during file transfer. Note that a partial file will still be transferred. Transfer Aborted by Host Something has gone wrong at the host end - it may have gone down. XON to Start not Received (Putfile only) The host has not signalled the micro to start the transfer properly. Incorrect Prompt From Host The host does not have the relevant support routines set up. Unable to Open Local File (Putfile only) The file does not exist on the micro's disk. Null Filename An empty string has been entered as the source or destination filename. File Names not Paired The number of files in the source file list is not the same as the number in the destination file list. II.2 Host Errors These are self-explanatory, and are as follows - File Already Exists (Putfile only) File Does not Exist (Getfile only) PD File Does not Exist Illegal File Name Checksum Faulty No Checksum 10 II.3 BBC MOS Errors The following errors can be caused by the X-talk program - Bad Filename, Bad Directory, Bad Drive Catalogue Full, Disk Full File Read Only, File Locked, Disk Write Protected Drive Fault, Disk Fault, Disk Changed, Bad Sum See the DFS User Guide for more details. 11 Appendix III - Later Versions This appendix gives differences between the latest release of X-talk and the first release which is version 1.0. The version number of the latest release is given at the end of this appendix. This userguide will be completely revised when version 2.0 becomes available. III.1 Differences (a) The latest release is all in machine code, whereas V1.0 was partly in BASIC. The program thus occupies only one file on disk (called "XTALK") instead of four. The restriction on changing default drives (section 5.4) is thus removed. (b) The bug of appendix II section 2 does not now occur, due to the reduced memory requirement. Some other minor bugs which have been revealed through use have also been fixed. (c) When X-talk prompts the user for a Y or N response, it is no longer necessary to type return afterwards. (d) The !BOOT file becomes simply "*XTALK". (e) Error messages are prefixed merely with "**" instead of "** MOS:" or "** DFS:". (f) The latest version now works with the JNT PAD, which is gradually replacing TCPs. Slight changes to the protocol were necessary, but these have been done in such a way that the same software will work with the PAD and with TCPs. Faster communications speeds are available with the PAD. The recommended speed to run Xtalk over the PAD is 4800 baud. Problems may occurr in terminal emulation mode at 9600 baud if the BBC contains a ROM expansion board with many ROMs on it. Transferring files to EMAS at 9600 baud is possible, but offers little effective speed increase over transfer at 4800 baud. Transferring files from EMAS to the BBC at 9600 baud will result in a checksum error, caused by the BBC missing interrupts from the communications port while the disk is causing NMIs. (If you don't understand that last bit, don't worry!) (g) A line break can now be sent from the BBC using SHIFT-F7. This is useful for returning to PAD mode if Xtalk crashes in the middle of a file transfer. See your PAD terminal users guide for details. (h) The program has been relocated to start at &1A00, to allow it to work with the Acorn IEEE Filing System. III.2 Upgrading To obtain the latest version of X-talk, you can either send a blank formatted disk to C.J.Adie at the ERCC, Kings Buildings, or if you already have an earlier version of X-talk, you can 12 download the new version using the following procedure. (a) Run up your old version of X-talk and select BINARY mode using the configure option. This is essential. (b) Log onto the 2976 or the 2988 and bring down the file ERCH12.MISC_LATESTXTALK onto a clean disk, giving it the local filename XTALK. Log off. (c) Type control-break to reset your BBC micro and execute the following two commands: *LOAD XTALK aaaa *SAVE XTALK aaaa bbbb cccc The values of aaaa and bbbb and cccc are given below. (d) Now create a !BOOT file as follows: *BUILD !BOOT 1 *XTALK 2 and finally set your startup option on your new disk with: *OPT 4,3 Version number aaaa bbbb cccc 1.3 1A00 2B52 2A6E 13