---------------------- | Making a program run | ---------------------- Introduction ============ Once you've transferred a program to RISC OS, the next thing you've got to do is to make it run. BASIC programs -------------- For BASIC programs there are two possibilities you should explore: * running it directly under RISC OS (we call this running native) * running it by using one of the emulators. It's far better to run native if at all possible, because you'll save yourself all the overheads of using an emulator. In other words, running native: * makes your program run faster * saves you memory. Other programs -------------- Any other type of program will not run native; you'll have to use one of the emulators instead. Alternatively, if you wrote the program yourself in a high-level language (such as C or Pascal), you can try porting the sources and recompiling them using a RISC OS compiler. It's quite likely you'll need to re-write parts of the program, particularly those dealing with input and output. You should consider converting your program to a proper RISC OS application. Finding out if a program will run unchanged =========================================== There are two ways of finding out if a program will run unchanged: * You can just try to run the program, and see what happens. The advantages of this method are that it requires no technical knowledge, and that it is quick to try. The disadvantage of this method is that it is hard to be certain that you have exhaustively tested all parts of the program. Even though you might think that the program runs satisfactorily, a user may later discover a particular part of the program or set of circumstances which cause it to fail. * You can conduct a more exhaustive line-by-line investigation of the program. The advantage of this method is that you can be certain the program will run. The disadvantages of this method are that it requires technical knowledge, that it can be more time-consuming, and that you need the program's source code to do so (which you're unlikely to have unless you wrote the program yourself, or it's been written in BASIC). To help you check BASIC programs we've provided a utility named BBCscan. This utility scans a BASIC program for code that may not port directly to a RISC OS computer, and reports the nature of any problems. Below we look at these two methods in more detail. Trying to run an unchanged program ================================== Running a BASIC program under RISC OS ------------------------------------- The best way to try to run a BASIC program under RISC OS is from the command line. Because the BASIC program may crash your RISC OS computer, you should first save any other work you have done. Then leave the desktop by choosing Exit from the Task Manager's icon bar menu. At the command line type *BASIC to enter the RISC OS BASIC interpreter. You'll find this environment very similar to the BASIC interpreter on a 6502-based Acorn computer. So, for example: * You can change directory by typing *DIR . * You can list a directory by typing *CAT. * You can load a program by typing LOAD "". * You can run a program you've loaded by typing RUN. Use the commands you're familiar with to load and run the program you want to test. If the program appears to work ------------------------------ If the program appears to work, make sure you test it thoroughly - try to use all parts of the program. If all still appears well, then you've shown the program will run native. Now all you need to do is to make the program run from the RISC OS desktop. There are two ways of doing this: * Set the file's type to BASIC using the command *SetType BASIC * Make the program into a RISC OS application - see the chapter entitled Making a RISC OS application from a 6502-based program. In both cases the program will run if you double-click on it; however, the latter method is preferable, and easy to do. If the program doesn't work --------------------------- If the program doesn't work you can either give up trying to make it run native, or you can modify it until it does run. The BBCscan utility may help you to discover the nature of the problem. Details of this utility appear later in this chapter. One of the most common problems is a program that uses DFS; RISC OS does not support this now obsolete filing system. You have two choices here: * Convert the program to use another filing system, such as ADFS or NetFS. Because DFS uses a different naming convention to the standard RISC OS filing systems, you may find discrepancies between any filenames the program uses, and the names that the files actually have. (This is especially likely if you used DFSConv to transfer the DFS files to RISC OS.) If this occurs, you will have to make the filenames match each other. * Give up trying to make the program run native; instead run the program under 65Host, using its emulation of DFS. Under RISC OS you can list and edit lines of a BASIC program in the same way as on a 6502-based Acorn computer. Running any program under one of the emulators ---------------------------------------------- To try running any program under one of the emulators you first need to start the relevant emulator. Because the program may crash your RISC OS computer, you should first save any other work you have done. Then double-click on the emulator's icon from within the RISC OS desktop. Once the emulator's started you'll find almost everything just as you're used to on a 6502-based Acorn computer. Try running the program in just the way you usually do. If the program appears to work ------------------------------ If the program appears to work, make sure you test it thoroughly - try to use all parts of the program. If all still appears well, then you've shown the program will run under the emulator. There are two ways you can run the program in future: * Run it just as you've done now. * Make the program into a RISC OS application - see the chapter entitled Making a RISC OS application from a 6502-based program. In the latter case the program will automatically run under the emulator if you double click on the application's icon. If the program doesn't work If the program doesn't work you'll only be able to get it to do so by modifying it. See the next section. Checking through a program for problems ======================================= There are two reasons why you might wish to check through a program for potential problems: * You know the program won't run, and wish to find out why * You wish to be methodical in ensuring that the program will run. How much checking you can do (and how easy it will be to correct any problems) depends largely on how the program was written, and whether you've got the program's source code available: * If the program wasn't written in BASIC and you haven't got its source code available, you won't be able to do much to check it. All you can do is try to run it, and see what happens. See the section entitled Running any program under one of the emulators, above. * If the program wasn't written in BASIC but you've got its source code available, you'll be able to check it. The chapter entitled Technical Reference gives details of known problems with the emulators. * If the program was written in BASIC you'll be able to check it. To help you do this we've written a utility called BBCscan which will find any potential problems with a BASIC program; see below. If the problems you get are caused by BBC screen files or by files of User Defined Graphics, we've written two utilities (PicConv and UdgConv respectively) to help you convert such files to a format you can use under RISC OS. Again these are described below. Test files ========== There are a number of example files for use with the utilities. These are supplied on the distribution disc in the directory TestFiles: code Test file of BASIC, for use with BBCscan. BBCm1 Test screen file in Mode 1, for use with PicConv. BBCm2 Test screen file in Mode 2, for use with PicConv. BBCm7 Test screen file in Mode 7, for use with PicConv. ARMm1 File of RISC OS sprites, produced from BBCm1 by PicConv. ARMm2 File of RISC OS sprites, produced from BBCm2 by PicConv. ARMm7 File suitable for *Printing, produced from BBCm7 by PicConv. GXRgarf File of GXR sprites, for use with PicConv. ARMgarf File of RISC OS sprites, produced from GXRgarf by PicConv. udgs Test file of Master B-Font characters &D0 to &EF, for use with UdgConv. vdus File of VDU codes, produced from udgs by UdgConv. BBCscan ======= Introduction ------------ This utility searches a BASIC program for code that may not port directly to a RISC OS computer. It runs on the BBC Model B, B+, the Master series, the Electron and all RISC OS computers. Use BBCscan to help assess the feasibility of porting existing software onto RISC OS computers, as well as to help with the conversion once you've decided to do so. Using BBCscan ============= Starting up ----------- To run BBCscan on a 6502-based computer: 1. Type *BASIC to enter BASIC (if you're not already using it). 2. Type CHAIN "BBCscan" to run the program. To run BBCscan on a RISC OS computer, double-click on its icon. It is not a desktop program, and will take over the screen. Initially you're shown a numbered menu of the various options available: * To choose an option: press the number corresponding to the option you want, followed by the Return key to confirm your choice. * To leave an option: press the Esc key - although you should only do this if the computer is waiting for input from you. Option 1: Quit -------------- Use this option to quit BBCscan. If you're using RISC OS you'll be prompted to press the Space bar or to click a mouse button before you can return to the desktop. Option 2: * Command ------------------- Use this option to type in a * Command for immediate execution, such as *Cat or *Dir. BBCscan ignores an unrecognised * Command, and returns you to its main menu. Option 3: Search ---------------- This option searches a BASIC program for code that may not port directly to a RISC OS computer. You will be prompted for the BASIC program you want to search through. (You might like to start off by using the test file, code, which is provided in the TestFiles directory.) This is followed by prompts for selecting Page mode and Printer output. * In Page mode, press the Space bar at the end of each screen of output. * BBCscan doesn't check for the presence of an online printer, and so will crash if you select the Printer output option without first having set up your printer. BBCscan will flag lines which may cause problems when porting the program to RISC OS, producing a message indicating the nature of the problem. In fact, in many cases you won't need to change the line at all. For example, all references of the ? indirection operator will be picked up; you'll need to look at the context to establish whether you need to change a specific instance: DIM space 10:?(space+4)=200 will run native on a RISC OS computer (ie on BBC BASIC V) mode%=?&355 will not return the current screen mode except under an emulator. CMOS opcodes ------------ Some later models of 6502-based Acorn computers use a CMOS version of the 6502 processor - the 65C02 processor. This introduced additional assembly language opcodes to those used by the earlier 6502 processor. Support was added to BBC BASIC for these opcodes. However, BBCscan does not detect these opcodes specific to the 65C02 processor; nor can 65Host emulate all of them. BBCscan messages ---------------- BBCscan produces messages of the form: / / The following list of message numbers are annotated by the BASIC feature that triggers them. * Specific numbers (eg 101 for CALL &FFF4) are issued only when BBCscan can easily compute the address involved. At other times a generic message will be given (for example, CALL OSBYTE, even though it is functionally identical to CALL &FFF4, will instead give the message number 100). * Not every OS entry point has a specific number allocated to it; so some entry points (such as OSWRCH, OSNEWL, OSRDCH, OSBGET, OSBPUT...) will always just give a generic message. It is up to you to decide whether or not a BBCscan message means that a BASIC statement needs attention. 1qq CALL 2qq USR qq= 00 General machine code call 01 &FFF4 (OSBYTE) 02 &FFF1 (OSWORD) 03 &FFDD (OSFILE) 04 &FFCE (OSFIND) 05 &FFD1 (OSGBPB) 06 &FFF7 (OSCLI) 300 CHAIN ADFS naming different 400 ENVELOPE sound different, unless using 65Host 500 HIMEM may need 65Host or 65Tube 600 LOMEM may need 65Host or 65Tube 700 PAGE may need 65Host or 65Tube 800 MODE (note that MODE does not affect HIMEM except under 65Host) 900 SOUND sound different, unless using 65Host 10xx * Command non OS - needs 65Host or 65Tube xx= 00 General 01 *DELETE ADFS naming different 02 *DIR directories different 03 *DISK/C no DFS - change to ADFS 04 *EXEC ADFS naming different 05 *FX not all OSBYTEs carried over 06 *MOTOR gone 07 *OPT changed 08 *RENAME ADFS naming different 09 *RUN needs 65Host or 65Tube 10 *SPOOL ADFS naming different 11 *TAPE gone 2y *LOAD 3y *SAVE y = 0 General machine code - needs 65Host or 65Tube 1 Screens needs 65Host, 65Tube, or conversion 2 Charset needs 65Host, 65Tube, or conversion 3 SoftKeys needs 65Host, 65Tube, or conversion 110z ? byte indirection 120z ! word indirection 130z $ string indirection z= 0 General needs 65Host or 65Tube, unless into DIMed block 1 Hardware totally unportable - needs conversion 2 OS space totally unportable - unless as user space, which needs 65Host or 65Tube 3 Screen not portable (if being used as that), unless using 65Host 2ppp Assembler used: needs 65Host or 65Tube ppp=000 General 01z LDA/X/Y &num may be unportable address 02z STA/X/Y &num 03z INC &num 04z DEC &num 05z ADC &num 06z SBC &num 07z CMP &num 08z AND &num 09z ORA &num 10z EOR &num z= 0 General needs 65Host or 65Tube, unless into DIMed block 1 Hardware totally unportable - needs conversion 2 OS space totally unportable - unless as user space, which needs 65Host or 65Tube 3 Screen not portable (if being used as that), unless using 65Host 2qq JMP &num 3qq JSR &num qq= 00 General machine code call 01 &FFF4 (OSBYTE) 02 &FFF1 (OSWORD) 03 &FFDD (OSFILE) 04 &FFCE (OSFIND) 05 &FFD1 (OSGBPB) 06 &FFF7 (OSCLI) PicConv ======= Introduction ------------ This utility provides a means of porting 6502 BBC screen files onto RISC OS computers. It runs on RISC OS computers only. Mode 0, 1, 2, 4 and 5 screens ----------------------------- To ensure future compatibility, PicConv converts Mode 0,1,2,4 and 5 screenfiles to RISC OS sprites. You can edit sprites using Paint, which is on the Applications disc supplied with every RISC OS computer. See your RISC OS User Guide for details of how to use Paint. You can also manipulate sprites from software - see the chapter entitled Sprites in the RISC OS Programmer's Reference Manual. You'll also need to edit your 6502-based application. Replace the *LOAD command normally used on a 6502-based machine to load a screen with the *ScreenLoad command used on RISC OS computers. * Because *ScreenLoad always loads the first sprite it finds in a file, you should save each sprite you generate to a separate file. * *ScreenLoad loads sprites at the bottom lefthand corner of the current graphics window, whereas *LOAD loads screenfiles at the bottom lefthand corner of the screen. Consequently, if the original 6502-based program had a graphics window set up before loading a screenfile, using *ScreenLoad under RISC OS will not have the same effect. In practice this is very unlikely to happen. Mode 3 and 6 screens -------------------- Mode 3 and 6 screens are not handled by PicConv. This is because they are text-only modes, and so there is no need to convert them. Mode 7 screens -------------- Mode 7 screens require a different approach. This is because this mode is emulated on RISC OS computers, and consequently each screen would take 80 Kb to save as a sprite. Instead, PicConv converts BBC Mode 7 screens as follows: * scrolling at the bottom of the screen is prevented * the maximum number of characters is limited to 1000 * adjustment is made for a partial screen, if necessary * codes are massaged to handle the characters '?', '#' and '_' * the cursor is returned to the home position and scrolling is re-enabled. The resultant file is then saved. You can display it in Mode 7 using the *Print command either from an application, or from the command line. GXR sprites ----------- PicConv also provides an option for converting a file of GXR sprites (ie sprites generated using either the Acorn Graphics Extension ROM, or a Master series computer) into RISC OS sprites. Using PicConv ============= Starting up ----------- To run PicConv, double-click on its icon. It is not a desktop program, and will take over the screen. Initially you're shown a numbered menu of the various options available: * To choose an option: press the number corresponding to the option you want, followed by the Return key to confirm your choice. * To leave an option: press the Esc key - although you should only do this if the computer is waiting for input from you. Option 1: Quit -------------- Use this option to quit PicConv. You'll be prompted to press the Space bar or to click a mouse button before you can return to the desktop. Option 2: * Command ------------------- Use this option to type in a * Command for immediate execution, such as *Cat or *Dir. PicConv gives an error message if you give it an unrecognised * Command, and then returns you to its main menu. Option 3: View sprite --------------------- Use this option to view a file of RISC OS sprites, pressing the Space bar to move through the sequence. To view a Mode 7 file converted for a RISC OS computer, you will need to exit from PicConv. At the command line type *Print . Option 4: BBC -> RISC OS ------------------------ Use this option to convert a named BBC screen into a named RISC OS sprite file (for modes 0, 1, 2, 4 and 5) or a *Print file (for Mode 7). You will find some test files in the TestFiles directory: * BBCm1 a Mode 1 screen * BBCm2 a Mode 2 screen * BBCm7 a Mode 7 screen As an example of how to use this option: 1. Type TestFiles.BBCm2 at the source file prompt. 2. Type 2 at the screen mode prompt. 3. Type TestFiles.ARMm2 at the destination prompt. The screen will clear, and the picture file will be drawn. A prompt will appear at the bottom of the screen when the process is finished. You could now display the RISC OS sprite you have created using Option 3: View sprite. Option 5: GXR -> Sprite ----------------------- Use this option to convert a file of GXR sprites (ie sprites generated using the Acornsoft Graphics Extension ROM) into RISC OS sprites. A GXR sprite file, GXRgarf, is provided in the TestFiles directory. Option 6: View BBC file ----------------------- Use this option to look at a BBC graphics screen (Modes 0,1,2,4 and 5) or a Mode 7 screen without saving a conversion for RISC OS. UdgConv ======= Introduction ------------ This utility provides a means of porting files of User Defined Graphics characters onto RISC OS computers. It runs on RISC OS computers only. The file of graphics characters must be one that loads its character definitions into the BBC Model B or B+ within page &C. Consequently you cannot use UdgConv to convert an exploded font. Using UdgConv ============= Starting up ----------- To run UdgConv, double-click on its icon. It is not a desktop program, and will take over the screen. Initially you're shown a numbered menu of the various options available: * To choose an option: press the number corresponding to the option you want, followed by the Return key to confirm your choice. * To leave an option: press the Esc key - although you should only do this if the computer is waiting for input from you. Option 1: Quit -------------- Use this option to quit UdgConv. You'll be prompted to press the Space bar or to click a mouse button before you can return to the desktop. Option 2: * Command ------------------- Use this option to type in a * Command for immediate execution, such as *Cat or *Dir. UdgConv ignores an unrecognised * Command, and returns you to its main menu. Option 3: Convert ----------------- Use this option to convert a file of user defined graphics characters. You will be prompted in turn for the name of the file of graphics characters, its original load address (if in doubt, type 0C00) and the name of the destination file. You then have a choice of two output formats, which you can toggle between by pressing the M key: * Binary gives a binary output file. You can load these under RISC OS using the *Print command. * BASIC gives a text file of BBC BASIC VDU statements. If you wish, you can renumber the lines using a text editor (such as Edit). To change the text file to a BASIC program: 1. Type *BASIC at the RISC OS command line. 2. At the BASIC prompt, type *Exec filename The BASIC VDU statements will be displayed on the screen, just as if you had typed them in. 3. Type SAVE "filename" to save the file as a BASIC program. 4. Type *Quit to leave BASIC. If you wish to, you can load another BASIC program before you use *Exec to mimic typing in the VDU statements. Hence you can merge the statements into another program - assuming there are no duplicate line numbers. Alternatively you can run the VDU statements as a separate program, and then use the BASIC CHAIN keyword to start the original 6502-based program. A test file of Greek characters, udgs, is provided in the TestFiles directory. Please note that UdgConv will attempt to convert almost any file that you present to it, and input validation for entering the load address is not fully implemented.