Docstoc

Manual for QBT version 0

Document Sample
Manual for QBT version 0 Powered By Docstoc
					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 : ql@mcad.demon.co.uk
Enjoy !

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:3
posted:6/23/2011
language:English
pages:9