VIEWS: 3 PAGES: 9 POSTED ON: 6/23/2011
Manual for QBT version 0.72beta - (c) Malcolm Cadman 2000 QL BASIC Dialect Translator( QBT ) QDOS version 0.72 beta (c) Malcolm Cadman 1995-2000 Additional code (c) Peter S Tillier 1999 Distributed as Freeware. Index of contents General guide 1.1 Introduction 1.2 Making a backup 1.3 Quick start 1.4 Options available 1.5 Worked examples Detailed information 2.1 The keywords translated 2.2 Other translations made 2.3 Viewing the translation 2.4 Getting better speed 2.5 Getting your programs in to the QL Further information 3.1 General points 3.2 Effectiveness 3.3 Disclaimer 3.4 Copyright Acknowledgements 1.1 Introduction The purpose of this software is to help with the process of transferring programs having different 'dialects' of the BASIC language used by personal computers. A 'dialect' is the interpretation of BASIC on a particular computer. The 'dialects' catered for at present are :- QDOS SuperBASIC, MSDOS QuickBASIC and RISCOS BBCBASIC. This software will take a program listing from any of these sources provided that it is in a readable QL format and convert a selected set of 'keywords' from one to the another. It thus helps in taking programs that may have been originally written on one system over to another.The 'translation' is not a complete solution, being only concerned with the principal structure of a program and does not do a full 'one-for-one' translation. Neither does it attempt to 'understand' the meaning of a program, which would be far too complex, but it does automate a good deal of the conversion process necessary. Saving considerable time with one program, and a great deal of time when several programs are intended for translation. As well as going in both directions. Giving an output which should be recognised by the intended new system, where more complete work can be undertaken. Note - Any mistakes in logic or structure in the original program will not be altered in the output file ! This will remain exactly as the original. It will not make programs that do not work in their original form work either ! It remains your responsibilty to actually get your program to work as you intended. The translator does not 'alter' the input file ( source program ) in any way. What it does is to scan that 'file' line by line, and then produce a new copy in the new format. In this way your original program is always protected against alteration, and is obviously still available for use. But, as ever, it is always best to use a 'backup' copy of any original source files when using this software. 1.2 Making a backup ALWAYS use a 'backup' of the translator disk itself rather than the original ! To do this for disk drives place a new floppy disk in 'flp2_' and give the command 'format flp2_QBTwork'. ( This will result in a 'QBT' working disc ). Then place the original in 'flp1_'. If you do not have TK2_EXT in your QL then give the command 'dir flp1_' to show the files on 'flp1_'. Then use the command 'copy flp1_filename to flp2_filename' for each individual file that you can see from the directory of the original in 'flp1_'. If you have TK2_EXT then simply give the command 'wcopy flp1_ to flp2_' and press 'A' for 'All' when presented with the prompt. This will automate the copying to copy all files from 'flp1_' to 'flp2_'. If you download a copy of QTB from the internet - http://www.mcad.demon.co.uk - then proceed in a similiar way to the above to work from a backup copy for regular use. 1.3 Quick start To see the program in operation quickly follow the instructions below. To make the program easy to use a single keypress is usually all that is necessary. * Place the backup of the translator disk in to disk drive one. * Type 'lrun flp1_QBT_072_bas' or 'ex flp1_QBT_072' if it is compiled code. * Hard disk or RomDisq users may load in a similar manner, substituting 'win1_' or 'rom1_' for 'flp1_'. * The program will load and display six windows : - window 1 at the top of screen, white background, shows the program title and copyright author, - window 2 next one down, white background, is for text input to the program, - window 3 left hand side, white background, is for drive directory display and program information during translation, - window 4 upper right hand side, green background, is for the input program file information during translation, - window 5 lower right hand side, green background, is for the output program file information during a translation, - window 6 middle of screen, is an initial 'pop-up' menu of choices. * At the start you are in window 6 - menu of choices. The current option is highlighted. Press ENTER to accept the first choice for 'Quick start'example. Which is SuperBASIC to QuickBASIC. ( The menu choice is selected by using the up and down arrow keys for other choices - it cycles around back to the first when you reach the bottom ). * The menu of choices will disappear and Window 1 will change to show to current translation option ( SuperBASIC to QuickBASIC ). * Window 2 will display a prompt for a drive to load the 'input file' from. Drive type to use > flp, mdv, ram, win or other ( f/m/r/w/o ) ? Press 'f' for flp, ( or whatever your default medium ). * Window 2 will prompt for a drive number. Drive number ( 1 to 8 ) - Arrow keys up/down / ENTER to accept Press ENTER to accept the drive number '1', or simply use to up/down arrows to get the number that you need. * Window 2 will prompt to show an optional sub-directory of a device. Type in the sub-directory to use e.g, progs - ( or press ENTER ) Press ENTER to accept the current directory. * Window 2 will prompt to display a directory of 'flp1_'. Dir of drive ( your choice ) ? - ENTER > Yes / SPACE > No / ESC to Exit Press ENTER for yes. ( A press of SPACE is used for no ). * A directory display of 'flp1_' will be shown in window 3 - left hand side of the screen ). The source drive name will be shown at the top. A highlighted prompt will ask for a 'filename'. Type 'test_qlb' as the filename. ( This is an example test program supplied in QL SuperBASIC on the program disk ). * Window 2 will prompt for an 'output file' name. Type name for output file ( ENTER / default 'filtered_bas' ) ? Accept the default name 'filtered_bas' with ENTER. Or else type in your own and then press ENTER. ( If you just press ENTER then a default name of 'filtered_bas' is applied to the output file ). * Window 2 will prompt to add the append of '_lis' to the file on output. Press SPACE for no. ( Using the 'yes' option will help if you intend to load the file into QUILL at some time using the 'import' option ). * Window 2 will prompt to retain the line indenting that the source program may have. Retain program indenting ENTER > Yes SPACE > No ? This gives you the option of retaining the program listing indents, if any, or losing them entirely. Press ENTER for yes. * Window 2 prompts for the drive to be saved to. Save file > ( choice of name ) to ( choice of device and directory ) ENTER > Yes SPACE > NO ? This gives you the option of saving to a different device than the source device that holds the input file listing. Press ENTER to accept it as 'flp1_. * Window 2 prompts to 'show the line scanning'. Show line scanning ENTER > Yes SPACE > No ? This gives you the option of seeing each line of the input file as it is translated in to the output file. Useful to confirm the progress being made and for information as to how the program works. Obviously this takes more time, so for best speed do not show the line scanning. Press SPACE for no. * Window 2 will then display an information message - 'Fast scanning - no line display'. ( Assuming that the last option was a 'no' ). * Window 3 will clear the directory listing previously shown, and now display information on the changes to be made. * Window 4 will just show the current 'linelength' and 'linecount' for the input file. Window 5 will remain blank. * WARNING : The drive selected will be active ( here 'flp1_' ), so do not attempt to remove the disk or switch the drive off. * The translator reads from and writes to the media on the drive(s) chosen. You must wait until the translation is complete. * When complete an analysis window ( window 7 ) shows the substitutions made and the time taken in seconds, minutes, and lines per minute. * Press SPACE to end the program.( You can stay in the program by pressing ENTER for yes, if you require a further run ). * Information on how to view the newly created file is shown on screen after exiting the program. ( See page * for more details ). The above may seem like quite a long explanation for a 'Quick Start' ! However, in practice you will find it easy to use - even if you have never read these instructions ! 1.4 Options available The program is designed to translate the following six options : 1 SuperBASIC to QuickBASIC 2 QuickBASIC to SuperBASIC 3 BBCBASIC to QuickBASIC 4 QuickBASIC to BBCBASIC 5 SuperBASIC to BBCBASIC 6 BBCBASIC to SuperBASIC 1.5 How it works The translator examines a line from the 'source' file as a text line and checks if any substution work can be done to it. If it can it will make all the necessary changes and then save the 'destination' file line by line as they are interpreted. To do this it needs to both 'read' from and 'write' to a QL media device. WARNING - Do not attempt to remove a media or turn off a device whilst the program is in operation. It tries to do this as quickly as possible, without doing any harm to the file in any other way. So, your 'input' and 'output' will match up except that they have the 'style' of a different dialect applied. The original 'source' file is left unchanged by the translator. A new file is created as a copy of the original, but now in a new format. See Section 2 for a more complete explanation. *********************************************************************** 2.1 The keywords translated For each 'dialect' - SuperBASIC / QuickBASIC / BBCBASIC are those dialects that are currently supported - the principal set of ten keywords are substituted. For SuperBASIC these are. REMark Used to document a program DEFine PROCedure Used to start a code module. END DEFine Used to end a code module. REPeat Used to start a code loop. END REPeat Used to end a code loop. END FOR Used to end a FOR loop. DEF FuNction Used to start a code module. SELect ON Used to select options. AT Used to place PRINT on screen. INK Used to colour text on screen. For QuickBASIC these are. ' Used to document a program SUB Used to start a code module. END SUB Used to end a code module. DO Used to start a code loop. LOOP Used to end a code loop. NEXT Used to end a FOR loop. FUNCTION Used to start a code module. SELECT CASE Used to select options. LOCATE Used to place PRINT on screen. COLOR Used to colour text on screen. ( Note : AMERICAN spelling ). For BBCBASIC these are. REM Used to document a program DEF PROC Used to start a code module. END PROC Used to end a code module. REPEAT Used to start of code loop. UNTIL Used to end a code loop. NEXT Used to end a FOR loop. FN Used to start a code module. IF Used to select options ( NOT really the same ). TAB Used to place PRINT on screen. COLOUR Used to colour text on screen ( ENGLISH spelling ). These are the only keyword substitutions made. Note - QuickBASIC for MSDOS is an earlier version of what is now known as VisualBASIC for Windows, so this is another possible use for the translated software. Also, BBCBASIC is emulated on the Acorn RISC OS computers, again allowing for software to be taken in to this environment. 2.2 Other translations made In SuperBASIC and BBCBASIC programs a variable or a procedure/function name can be of the form with an 'underscore' to link together different parts, e.g, variable - 'first_number',procedure/function name - 'erase_line_numbers'. In QuickBASIC these would by convention be either 'firstnumber' or 'FirstNumber', and either 'eraselinenumbers' or 'EraseLineNumbers'. Because QuickBASIC does not allow an 'underscore' to be used in names. The second choice, e.g, 'FirstNumber' is the recommended style of distinguishing one word from the other. The translator removes any 'underscores' encountered when translating into QuickBASIC and tries to place capital letters in a suitable place.This is not so much of a problem between SuperBASIC and BBCBASIC as they can have either method of naming. SuperBASIC and BBCBASIC have line numbers, QuickBASIC does not have line numbers. These are therefore removed when translating to QuickBASIC from either SuperBASIC or BBCBASIC. Of course, they are put in when translating a QuickBASIC program in to SuperBASIC or BBCBASIC. The program will start at line 100 and increment in steps of 10. 2.3 Viewing the translation This program was written with the intention of making the workings of the program transparent. It is interesting to watch the operation of the program when translating a file. Therefore if you answer yes ( ENTER ) to the prompt 'Show line scanning' you will be able to do this. Both windows 4 and 5 ( with green backgrounds ) are used for this. Window 4 shows the input file information, and window 5 the output information. This allows you to see what is 'going on' and to compare the results as they happen in 'real time'. It is both instructive and fun to watch this take place ! But it is not presented at normal 'reading' speed as the program is still trying to get through its job as quickly as possible ( it would be very tedious if it didn't ). So, it does take a little getting used to ! On faster machines reading the information will of course be even more difficult ! However, it is obviously much slower in overall program execution speed to have this option turned on. Normally, once you are experienced with the program, ( that your program file will be OK ! ), it is better to have 'Fast scanning - no line display' selected ( No - SPACE, when prompted for the choice ). Because this will do the necessary translation in the fastest time that your hardware and operating system allow. Note : SMSQ/E is a lot quicker than QDOS as this newer operating system for QL computers is faster in operation. 2.4 Getting better speed The translator takes into account 'multi-line' assignments, i.e. using the ':' ( colon ) on the same program line to indicate a second, third, etc, line, on one 'physical' line. Checking for a 'multi_line' is a little time consuming, as well as the time to change several things in one line. Programs that have single lines will be checked a bit quicker than those that have 'multi_lines'. But, if you've already written the program don't worry about it ! Just accept the time penalty, the translator will still cope ! The translator will 'skip' lines that do not have keywords that it recognises to in order to be as fast as possible. Using a RAM disk rather than a physical disk is the best way to get more speed. It also saves the wear on a physical drive, because the translator 'opens' the device for reading from and writing to when it is working on a file. So, before using the translator, create a RAM disk and copy the files(s) that you wish to 'translate' on to the RAM disk. You can, of course, load the translator on to RAM and run it from there too ! Also, choose the option of saving the 'output' file as RAM disk. ( This will be the automatic default if the source drive is a RAM disk. But don't forget to eventually save your newly created files to a more permanent media before you switch off ! Easy to forget ! ( Lost file - oops ! ). 2.5 Getting your programs in to the QL Of course, you have to get the program file to be translated into a file format that the QDOS can recognise before this Translator can be applied ! This is may be the hard bit ! The translator tries to make the rest easy ! Yet there are several ways of doing this. Some are discussed here. SuperMedia Manager by Digital Precision will read a MSDOS disk and copy the files to a QL disk. This can be done using the 3 1/2" disk format quite conveniently. Some versions of the software can also read in other 'alien disks' like the BBCBASIC format. ( Note - The 'Special Edition' only deals with MSDOS and TOS formats ). BBCBASIC programs are usually found on the older 5 1/4" disk format. If you have one of these available. The QL can easily read these drives when set to '80 track'. You may find it more convenient to use the QL software on the 5 1/4" format too. The quickest and simplest way to do this is to create a RAM disk of say 1600 sectors and then copy a program like SuperMedia Manager to the RAM disk. You can then save the QL software to the 5 1/4" disk ( having first formatted it of course ! ), and then use it directly from there. Or, continue to use the software from the RAM drive. You can also physically change to a 3 1/2" drive and a 5 1/4" drive ( if you have one ), whilst the computer is 'ON' by physically unplugging one drive and changing to the other if need be. But take care not to damage any pins on the sockets. Another way would be to use the microdrives if they have sufficient space for the software you are using. This will be a lot slower, but they can still have their uses ! Do you still have any ..... ? Another alternative, if you still have an Acorn BBC computer is to save the software on to 3 1/2" disks ( by plugging in your QL drive to the BBC computer and formatting the disk as 80 track - 80 track just gets more information on a disk and is equivalent to QL 1440 sectors ). These can then be used with SuperMedia Manager back in the QL environment and again read as an 'alien disk'. If you have a version of SMSQ/E this will automatically read the MSDOS format disk for you. Software like 'DiscOver' can also do this job. It is also possible to use the BBCBASIC emulator for MSDOS, if you own a copy, and to have BBCBASIC programs already in the MSDOS format on 3 1/2" disks ! If none of above applies to you, you can at least get going with 'translating' by using the sample files of the different types that are included on the program disk. This will give you experience. Also included is a SuperBasic program to do simple networking between two QL's. This program - called 'SimpNet2' - sets up one QL to be the 'master' and the second to be the 'slave'. Each can have different types of drive attached to them. List the program to screen and read the REMarks to understand how to operate the simple networking ( and try to find that networking cable that came with the QL ! ). A program loaded on the 'master' can be sent to the 'slave', and of course, vice-versa ! Whichever way you find to do it, you will need to get your 'source program files' into a form readable by the QDOS. If you cannot do this, then a version of the translator is also available on MSDOS format to run on PC186 machines ( at the time of development ). You may in fact simply prefer it this way ! Or, even like to use both formats. 2.6 Getting your SuperBASIC in to good shape If you are intending to translate your SuperBASIC programs it is a good idea to make sure that they are 'well structured'. This means the use of procedures rather than GOTO's or GOSUB's. Keeping your program line short to something like 60 characters is better than very long lines. Documenting your program with REMarks will help you understand even you own intentions when you have the file in a new format ! The 'BETTERBASIC' software by Charles Dillon - formerly sold by Digital Precision is recommended as an excellent way to improve your BASIC program. Even if you think that you have already got the BASIC in to 'good shape'. I always use it for tidying up, or simply to clarify the indenting of procedures, etc. Also, if you intend to 'TurboCharge' the SuperBASIC at some time then 'BETTERBASIC' is almost essential ! The translator can retain any program indenting from the source file to the output file, so a well structured program will come out the same style in the translation. 3.1 General points To make the program easy to use the usual response to a 'prompt' ( a question asked of the user ) is either ENTER for "yes" or SPACE for "no". This is consistent throughout the program.These key presses can also be replicated by a mouse button press if you have one attached ( LEFT button for ENTER and RIGHT button for SPACE ). In order to work the translator has to make use of reading and writing to a device. So, if using disk drives, do not attempt to take a disk out of a drive, etc, or turn off the device in question when in use ! Always make use of a 'backup' of the program and your files as a safeguard against any accidental loss of data. CAUTION - If for some reason the program halts unexpectedly and returns to SuperBASIC then type in 'close' as a direct command at the cursor. This will simply close the channels used for input and output of data.In normal operation this should never occur ! But this will protect your system from possible erroneous file problems in subsequent use. 3.2 Effectiveness This version of the program was developed entirely in SuperBASIC on a black box QL. It works happily with QPC1 and QPC2. It was also then used to translate an early original version into a QuickBASIC version. This was then altered and further enhanced to become the MSDOS version which is available on a DOS format disk. The MSDOS version is compiled under QuickBASIC v4.5. As MSDOS QuickBASIC is compiled, it is fast. Development system > QL - Minerva ROM 1.65, Gold Card 2.31, Cumana 3 and 1/2" twin disk drives. Tested on QL - JS ROM, 512K ExpanderRam, Cumana Disk Interface, Watford Electronics 5 1/4" 40/80 track disk drive ( and Cumana 3 and 1/2" twin disk drives ). 3.3 Disclaimer This software is only to be used as intended and by following the instructions given should cause no problems or damage to both hardware and software. The Translator will pass programs 'clean through' if no changes can be made, for example ! It is intended for the personal use of the owner to translate his/her own software programs. If other BASIC software from any other source is used then the owner must be aware of, and take resposibility for, any infringement of the original author's copyright or commercial copyright. The author of this software known as file - QBT072_bas - accepts no responsibility for misuse or loss of data when using the software, nor any harm to any hardware used. For whatever reason.It is supplied in good faith for you to enjoy. 3.4 Copyright This software remains the intellectual property of the author and must not be copied or sold in any format without the prior permission of the author. Any distribution on a media must include the program file - 'QBT072_bas' and the manual for the program - 'ManQBT_doc' ( which is in Quill document format for greatest convenience ). Other files are optional, and are supplied as a quick way of getting started in 'translating' files. The owner of this copy of the software is free to use it on any QL related equipment for his/her own purposes, and to make backup copies for his/her own use without restriction. Any software development that may come about as a result of using this software should simply acknowledge its use at some time in that programs development. Either in the program listing, or in accompanying documentation. It is hoped that it provides a useful service to both users and to software authors. Acknowledgements SuperBASIC is a trademark of Sinclair Research Ltd. QuickBASIC is a trademark of MicroSoft Ltd, as is MSDOS. BBCBASIC is a trademark of Acorn Ltd. Digital Precision is a trademark of Digital Precision. Special thanks to :- Peter S Tillier, for getting involved in the programming during 1999, and for this SuperBASIC version. As well as the great deal of advice and programming with the c68 version. Malcolm Cadman February 2000. email : firstname.lastname@example.org Enjoy !
Pages to are hidden for
"Manual for QBT version 0"Please download to view full document