RTR logo

LBB

LB Booster



Introduction

LB Booster is a powerful utility for Liberty BASIC programmers. With LBB you can: LB Booster is Freeware; you are encouraged to purchase the full version of Liberty Basic on which to develop, test and debug your programs prior to 'boosting' them.

Benefits

Here are some examples of the benefits offered by LB Booster:

Performance

Bugs fixed

New features

Installation

Create a suitable directory (e.g. C:\Program Files\LBB\) and copy the LBB.exe file there. You will need administrative privileges to copy the file and when you execute it for the first time (in Windows Vista™, Windows 7™ and Windows 8/8.1™, with UAC enabled, use Run as administrator); however it can be run from a normal user account thereafter.

You can, if you wish, create a desktop shortcut to the program by right-dragging the LBB.exe file to your desktop and selecting 'Create shortcut here' from the menu that appears when you release the mouse button. You can create a shortcut in your Start Menu in a similar way.

LBB requires Windows 2000 or later. It is not compatible with Windows 95, Windows 98 or Windows Me. Sprites require a CPU with 'integer SSE' support, i.e. an Intel Pentium III or an AMD Athlon or later.

Compatibility

Although LBB can successfully boost most Liberty BASIC 4 programs, there are a few incompatibilities, including:
  1. There are no graphics segments; the 'delsegment' and 'segment' commands are ignored. However, on the plus side no special measures are required to make graphics 'stick'; if your program suffers from this problem under LB4 it won't when run under LBB!

  2. LBB does not support arbitrary precision arithmetic; integers (whole numbers) are limited to the range −18,446,744,073,709,551,615 to +18,446,744,073,709,551,615. Values outside this range will be stored as floating-point numbers and accuracy may suffer. In addition, the bitwise operations AND, OR and XOR work only with 64-bit integer values.

  3. The EVAL function works only with simple expressions containing 'standard' BASIC functions, and may fail if the expression contains variable names starting with a keyword. EVAL doesn't work if the expression contains a structure member, or a function name in mixed-case (e.g. Sqr).

  4. Child control handles must be mapped explicitly, e.g. MAPHANDLE #old.te,#new.te; mapping the parent window's handle is not sufficient.

  5. When printing a window, the resulting quality on the printer is no better than it is on the screen (but see here).

  6. The size of the 'canvas' onto which you can draw in a graphics box is limited (the width is limited to the width of your screen display). You can increase it using the horizscrollbar and/or vertscrollbar commands.

  7. The mainwin can hold only about 84 lines of text; if more lines are output the remainder will be 'scrolled off' the top of the window and lost. Also, the mainwin has no menu. You can copy the contents of the mainwin onto the clipboard by typing Ctrl+Tab.

  8. If one of the keypad number keys is pressed, two 'when characterInput' events are generated. One is the regular event that LB4 generates, and the other is a 'special key' event (LEN(Inkey$)=2). This makes it possible to distinguish the keypad from the regular number keys.

  9. The syntax for serial port parameters is slightly different. The basic options are the same, so for example this works:
    open "COM1:9600,n,8,1" for random as #comm
    
    but when specifying 'handshaking' parameters the syntax accepted by LBB is as follows:
    open "COMn: [baud=b] [parity=p] [data=d] [stop=s]
          [to=on|off] [xon=on|off] [odsr=on|off] [octs=on|off]
          [dtr=on|off|hs] [rts=on|off|hs|tg] [idsr=on|off]"
    
    A full description of these parameters can be found here.

  10. In a single-line IF statement LBB may behave differently from LB4 if there are multiple (cascaded) IFs and an ELSE clause. To resolve this recast the code as nested multi-line IFs.

  11. RESUME resumes execution at the line (not statement) where the error occurred; if in doubt use only one statement per line. Also, RESUME must be used within the scope of the SUB or FUNCTION (if any) in which the error occurred.

  12. Opening a file in BINARY mode does not prevent PRINT outputting a newline (CRLF). To suppress the newline add a trailing semicolon (;) to the PRINT statement; this will not affect the operation of the program in LB4.

  13. The maximum length of a DATA statement is approximately 250 characters.
In general, LBB may not always tolerate coding errors or weaknesses even if Liberty BASIC itself does. However in the case of an incompatibility from this cause it will usually be possible to modify the program so that it works under LBB as well as LB4. See Troubleshooting for some examples.

If, exceptionally, the only way to achieve compatibility is to use different code for LB4 and LBB you can test which platform your program is running under as follows:

if instr(Platform$, "LBB") then
  print "Running under LBB"
else
  print "Running under LB"
end if 

Directives

LB Booster accepts the following Compiler Directives in the source code of the BASIC program; they are case-sensitive:

'include filename.bas

This directive, which takes the form of a special comment, includes the specified file at the point in the program where the directive is inserted; note that there must not be a space after the apostrophe. This allows you to develop and test separate code modules which can then be incorporated in programs whenever they are required.

For maximum compatibility with Liberty BASIC Workshop the 'include directive is ignored when it is at the very beginning of the program. See this Wiki article for more information, and for details of how to integrate LBW with LBB.

%mode std

This directive causes LBB to evaluate the INT() function, and expressions containing both AND and OR operators, in a standard way; note that there must not be a space after the percent sign. Specifically the INT function truncates towards minus infinity (e.g. INT(−3.5) is −4) and OR has a lower precedence than AND (e.g. 1 OR 2 AND 4 is 1).

%mode lb4

This directive (which is the default) causes LBB to evaluate the INT() function, and expressions containing both AND and OR operators, in the non-standard Liberty BASIC 4 way. Specifically the INT function truncates towards zero (e.g. INT(−3.5) is −3) and OR has the same precedence as AND, i.e. they are evaluated strictly left-to-right (e.g. 1 OR 2 AND 4 is 0).

!BBC-code

If a line starts with an exclamation mark (!) the rest of the line is assumed to consist of BBC BASIC code and is passed, unmodified, to the output of the translator. This facility should be used with care since only a subset of BBC BASIC statements may be safely used. For example red text may be output to the mainwin as follows:
!COLOR 1
print "This is red"

Operation

When you start LBB you are presented with a conventional window containing the normal features which make up the Windows™ Graphical User Interface: a title bar, a set of drop-down menus, a toolbar and a status bar. The main part of the screen is an editing pane in which the BASIC program appears and can be edited. This pane can be scrolled horizontally and vertically as necessary.

Command line options

LBB will accept parameters on the command line in a similar fashion to Liberty BASIC. If a filename is specified, it is automatically loaded; this allows you to drop a .BAS file onto the LBB icon, or to associate the .BAS file extension with LBB.exe.

The following command line switches are accepted:

-RRun a BAS file on startup
-DDebug a BAS file on startup
-TTranslate and tokenise a BAS file to an LBB file
-CTranslate and compile a BAS file to an EXE file
-AAutomatically exit LBB on completion
-MMinimise LBB on startup

Examples:

LBB program.bas           (loads the program)
LBB -R -A -M program.bas  (runs the program)
LBB -T -A -M program.bas  (generates program.lbb)

The title bar

The title bar contains the name of the application and its version number, the name of the current BASIC program (or 'untitled' if the New command has been issued), a minimise button, a maximise button and a close button. If you right-click in the title bar you will get a context menu containing the Restore, Move, Size, Minimize, Maximize and Close items.

The menu bar

The menu bar contains the drop-down menus File, Edit, Run, Options and Help. These menus may be activated by clicking on the appropriate menu name or by using a keyboard shortcut (hold down Alt and press the key corresponding to the underlined character). When a menu is opened a brief description of the highlighted item is displayed in the status bar. Menu items are 'greyed out' if they are not functional in the current circumstances.

The toolbar

The toolbar provides easy access to the most common commands, without having to select them from the drop-down menus, simply by clicking on the appropriate button. The commands for which buttons are provided are as follows:

From the File menu: New, Load, Save and Print.
From the Edit menu: Undo, Redo, Cut, Copy, Paste, Find and Replace.
From the Run menu: Run Program, Debug Program and Make Executable.

Toolbar buttons are 'greyed out' if they are not functional in the current circumstances.

The status bar

When a menu item is highlighted, the status bar displays a brief description of the function of that command. Otherwise, the status bar displays the version number and copyright information for LB Booster.

At the right-hand end of the status bar is displayed the number of the line containing the text cursor (caret), starting at line 1. This can be useful in locating the line which is responsible for a run-time error (the error message usually includes a line number).

The File menu

The File menu contains the items New, Load, Save, Save As, Page Setup, Print, Recent files and Exit. The File menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-F.

New

The New command (keyboard shortcut Ctrl+N) deletes the current BASIC program from memory, giving you a 'clean sheet' into which to load, paste or type a new program. If the current program has been modified and not saved, you are first prompted to save it.

Load

The Load command (keyboard shortcut Ctrl+L) loads a Liberty BASIC program into memory. The file must be in plain text (ASCII) format and should ideally have been tested on, and saved from, the full version of Liberty BASIC to ensure it does not contain any syntax errors. The file will normally have the extension .BAS.

If the current program has been modified and not saved, you are first prompted to save it.

Save

The Save command (keyboard shortcut Ctrl+S) saves the current BASIC program, replacing the original file; it is enabled only if the program has been modified since it was loaded. If you have made changes which might be incompatible with Liberty BASIC 4 you are advised to save the program under a new name (see Save As below).

Save As

The Save As command saves the current BASIC program under a new name, or in a new location. It is useful for making a backup copy, or to avoid modifying the original program if a change has been made which might be incompatible with Liberty BASIC 4.

Page Setup

The Page Setup command allows you to configure the paper size, orientation (portrait or landscape) and margins used when you print out the BASIC program. You can also use this command to select a different printer.

Print

The Print command (keyboard shortcut Ctrl+P) creates a hardcopy printout of the current BASIC program.

Recent files

The nine most-recently loaded programs are listed, and can be re-loaded simply by clicking on the appropriate entry or by using the keyboard shortcut Alt-F followed by the digit 1 to 9. When one of the entries is highlighted, the full pathname of the file is displayed in the Status Bar. If the previous program was not saved, you are first prompted to save it.

Exit

The Exit command quits from LB Booster and closes its window. If modifications have been made to the program and not saved, you are first prompted to save it. If BASIC programs are still running (and therefore using up Windows resources and potentially wasting CPU time) you are prompted to terminate them.

The Edit menu

The Edit menu contains the items Undo, Redo, Cut, Copy, Paste, Delete, Select All, Find, Find Next and Replace. The Edit menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-E.

Undo

The Undo command (keyboard shortcut Ctrl+Z) reverses the effect of the last editing operation. Multiple operations can be undone.

Redo

The Redo command (keyboard shortcut Ctrl+Y) reverses the effect of the last undo (if any). Multiple operations can be redone.

Cut

The Cut command (keyboard shortcut Ctrl+X) transfers any selected text to the clipboard, and deletes it from the program. If no text is selected, the Cut command is inhibited. Once the selected text is in the clipboard, you can Paste it either elsewhere in your BASIC program or into any other application which supports pasting of text from the clipboard. Any previous contents of the clipboard are discarded. Selected text is highlighted in reverse-video.

Copy

The Copy command (keyboard shortcut Ctrl+C) transfers any selected text to the clipboard, but unlike Cut it leaves the text in the BASIC program. If no text is selected, the Copy command is inhibited. Once the selected text is in the clipboard, you can Paste it either elsewhere in your BASIC program or into any other application which supports pasting of text from the clipboard. Any previous contents of the clipboard are discarded.

Paste

The Paste command (keyboard shortcut Ctrl+V) inserts the contents of the clipboard into the BASIC program at the current position of the text cursor (caret). If the clipboard contains no text, the Paste command is inhibited. You can use Paste to transfer a block of code from elsewhere in your BASIC program, or to insert a block of code which has been placed in the clipboard by any other application.

Delete

The Delete command deletes any selected text, without copying it into the clipboard. Text which is deleted can only be recovered by using the Undo command.

Select All

The Select All command (keyboard shortcut Ctrl+A) selects the entire BASIC program. It is useful if you want to transfer the program into another application (e.g. a word processor) via the clipboard

Find

The Find command (keyboard shortcut Ctrl+F) allows you to search your program for the occurrence of some specified text. The command opens the Find dialogue box into which you can type the text you wish to search for. You can also specify whether the case (capitals or lower-case) is significant and whether to match only an entire word. The search begins at the position of the text cursor (caret) when the Find command was issued. If you want to search the entire program, ensure that you move the cursor to the start of the program before issuing the command.

Find Next

Once the Find dialogue box has been dismissed, you can continue to search for the next and subsequent occurrences of the search string by using the Find Next command or by pressing F3. If the text is not found before the end of the program the message "Text not found" is displayed; selecting Find Next again causes the search to restart from the beginning of the program.

Replace

The Replace command (keyboard shortcut Ctrl+R) allows you to search your program for the occurrence of some specified text and then, optionally, replace it with some different text. The command opens the Replace dialogue box into which you can type the text you wish to search for and the text you want it to be replaced with. The search begins at the position of the text cursor (caret) when the Replace command was issued.

The Run menu

The Run menu contains the items Run Program, Debug Program, Profile Program, Make Executable, Make *.LBB file and Kill BASIC Programs. The Run menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-R.

Run Program

The Run Program command firsts 'boosts' (translates) the current BASIC program and then runs it. If an error occurs during the translation process, a message is reported and the process is aborted (once the error message is dismissed the line which resulted in the error is highlighted). If the program has already been translated, it is simply run. If no program is loaded, the command is inhibited.

Debug Program

The Debug Program command firsts 'boosts' (translates) the current BASIC program, if necessary, and then runs it with debugging aids enabled and any breakpoints activated. See Debugging for details.

Profile Program

The Profile Program command firsts 'boosts' (translates) the current BASIC program, if necessary, and then runs it with profiling enabled. Whilst profiling, the currently-executing line is highlighted in the editing pane (as when debugging). When the program terminates, a Profiler Report is generated and displayed in your default text-file viewer; this shows the approximate number of milliseconds, and percentage of the total time, spent in each program line.

Make Executable

The Make Executable command firsts 'boosts' (translates) the current BASIC program (if necessary) and then 'compiles' the program to a compact, standalone executable file (typically less than 150 Kbytes in size). The executable may run a little faster than when using the Run Program command. If no program is loaded, the command is inhibited.

You are prompted to supply a filename and location for the executable; by default it will be stored in the same directory as the Liberty BASIC program but with the extension '.exe'. LBB incorporates a manifest in the executable, to enable the use of Windows XP Visual Styles and improve compatibility with Windows™ Vista, Windows™ 7 and Windows™ 8.

The following additional options are available:

Make *.LBB file

Unlike Liberty BASIC, LBB compiles directly to an EXE so it isn't normally necessary to create a 'tokenised' program file; however the Make *.LBB file command allows you to do so if you wish. A tokenised LBB file must be executed using the run-time engine LBBRUN.exe (rather as LB's TKN files must be executed using RUN404.exe). Note that tokenised files are less secure than compiled executables so it is best not to use them if you want to keep your program confidential.

Kill BASIC Programs

The Kill BASIC Programs command terminates any BASIC programs which are still executing in memory after having been run during this LBB session. If a BASIC program doesn't properly exit (e.g. because of omitting a TRAPCLOSE command) it may have no visible window yet be using up Windows resources and CPU time. If no programs are still running, the command is inhibited.

In the current version of LBB you cannot choose which programs to kill.

The Options menu

The Options menu contains the items Show LBB Pane, Emulate Slicing, Unicode Support, Set Font and Set Printer Font. The Options menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-O.

Show LBB Pane

The Show LBB Pane command alternately enables and disables a 'split window' mode in which the original Liberty BASIC program is displayed in the left-hand pane and the translated program is shown in the right-hand pane. This may be useful for diagnostic purposes or simply for interest.

Emulate Slicing

The Emulate Slicing command alternately enables and disables the full emulation of Liberty BASIC's LEFT$, MID$ and RIGHT$ functions when the length parameter is negative. In that case LB4 returns an empty string. Since emulating the negative-length case significantly slows execution of the functions, and since very few programs rely on this behaviour, it is not enabled by default.

Unicode Support

The Unicode Support command alternately enables and disables partial support for Unicode output. When this option is selected foreign-alphabet literal (quoted) strings may be included in a program, and will display correctly in the mainwin and when output to a printer using LPRINT. Unicode strings may also be displayed in GUI controls (except TEXTEDITOR controls), with the assistance of a little API code.

Set Font

The Set Font command selects the font used to display the BASIC program on the screen. The default is the System Fixed Font (FixedSys).

Set Printer Font

The Set Printer Font command selects the font used when a hardcopy printout of the BASIC program is generated.

The Help menu

The Help menu contains the items Help Topics, Email, Website, Discussion Group, Message Board, Wiki and About LB Booster. The Help menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-H.

Help Topics

The Help Topics command (keyboard shortcut F1) displays this Help documentation.

Email

The Email command opens your default mail program (if any) so that you can send a message to request help or information about LB Booster.

Website

The Website command opens your default web browser (if any) and automatically directs it to the LB Booster home page.

Discussion group

The Discussion Group command takes you to the LBB Yahoo!™ group, where you can seek help and advice, report bugs, download (or upload) useful utilities and learn about new developments in LB Booster.

Message board

The Message Board command takes you to the LBB Conforums message board, where you can take part in discussions about LB Booster.

Wiki

The Wiki command takes you to the LB Booster Wiki, where you will find articles on all aspects of using LBB.

About LB Booster

The About LB Booster command displays information about LBB, including the version number and copyright information.

Debugging

LB Booster incorporates a debugger, to help you locate faults in your programs. To activate the debugger either click on the 'beetle' button in the toolbar or select 'Run... Debug Program' from the menu (keyboard shortcut Alt+RD). This will translate (if necessary) and then run your program, but execution will pause at the first statement (which will be highlighted in the editing pane).

A small, resizable, debugging window will open, having a toolbar and a scrollable listbox. The listbox displays the variables in your program, updating as their values change and new ones are created. Initially it will contain the 'reserved' variables (e.g. DefautDir$ and Drive$) and any globals defined in your program. If you want to monitor the value of a specific variable you can click on it; it will then be highlighted and the list will be scrolled automatically to keep it in view. To deselect that variable click in the title bar of the debugging window.

The toolbar contains 'Resume', 'Pause', 'Step into' and 'Step over' buttons (hovering your mouse over a button will indicate its function in a tooltip). 'Resume' causes execution of the program to continue at full speed until it encounters a WAIT or TRACE 2 statement, stops to receive user input (e.g. INPUT or PROMPT), hits a breakpoint (see below) or the 'Pause' button is clicked. If your program executes a WAIT statement whilst in a paused state, you may need to 'unpause' it (click on 'Resume') and pause it again before it will respond to an event such as a TIMER tick, button press etc.

The 'Step into' and 'Step over' buttons are active only when the program is paused. 'Step into' causes a single statement to be executed; you may find that some statements require it to be clicked more than once. If the statement transfers control into a function or subroutine 'Step into' will cause execution to pause within that module. 'Step over' causes execution to pause again only on the next line, so if the statement transfers control into a function or subroutine it will run at full speed until it returns, and if the statement terminates a loop (e.g. a NEXT or WEND) execution will continue at full speed until the loop is complete. It is not usually desirable to use 'Step over' on an END FUNCTION, END SUB or RETURN statement.

You can insert temporary breakpoints in your program by double-clicking in the left margin of the editing pane, a small square will appear there as a marker; to remove the breakpoint double-click again (to clear all breakpoints right-click in the margin and select the appropriate menu item). When a breakpoint is encountered during execution the program will pause, as if you had clicked on the 'Pause' button in the debugging window's toolbar; breakpoints have no effect if you use Run rather than Debug. Breakpoints are linked to the line number, so if you insert or delete any lines above a breakpoint it will move in relation to the code. You cannot add or remove breakpoints once the program is running.

A 'permanent' breakpoint can be inserted by means of a TRACE 2 statement; this has the same effect as a temporary breakpoint but can be saved as part of the program. It will only pause the program when you are debugging it, but you are recommended to remove TRACE 2 statements once your program is fully tested since their presence may cause execution to be slowed slightly. Note that TRACE 1 has a different function in LB Booster from that in LB 4.04: it causes line numbers to be logged to the mainwin during execution. LBB has no equivalent of LB's animate mode, since the variable list and statement highlighting continue to be refreshed even when the program is running at full speed.

Troubleshooting

Here are some hints for how to get the best from LB Booster:

How It Works

For those who may be interested, here is a technical description of how LB Booster works.

LBB is a hybrid translator and emulator. The translator automatically converts Liberty BASIC syntax to the equivalent BBC BASIC syntax. This translation takes place when you first issue the Run Program or Make Executable command.

The emulator (LBLIB) implements at run-time those aspects of Liberty BASIC which aren't part of the standard BASIC language and which have no direct equivalent in BBC BASIC; principally these are the Graphical User Interface elements (windows, controls, graphics and sprites). The emulator is itself written in BBC BASIC.

When you issue the Make Executable command LBB creates a single-file standalone executable containing the BBC BASIC for Windows run-time engine, the LBLIB emulator and a tokenised/compressed version of the translated BASIC program.

Formal Stuff

LB Booster is thought to be free from serious bugs, and it is highly unlikely that it could do any harm to other software or systems. However there is NO warranty that it will not and its use is at your own risk.

LB Booster is the Copyright © 2014 of R. T. Russell.

BBC BASIC for Windows is the Copyright © 2001-2014 of R. T. Russell. The name BBC BASIC is used with the permission of the British Broadcasting Corporation.

Liberty BASIC is the trademark of Carl Gundel trading as Shoptalk Systems.

Liberty BASIC Workshop is the Copyright © 2010 of Alyce Watson.

The aPLib compression library is used with permission. Copyright © 1998-2009 by Joergen Ibsen, All Rights Reserved.


Best viewed with Any Browser Valid HTML 3.2!
© Richard Russell 2014