# LBB

## Introduction

LB Booster is a powerful utility for Liberty BASIC and Just BASIC programmers. With LBB you can:
• Speed up a Liberty BASIC program by up to ten times.
• Compile a Liberty BASIC program to a compact, standalone executable.
• Overcome many of Liberty BASIC's bugs and limitations.
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

• Speed is typically increased. For example the ELAPSED.bas program supplied with LB reported an execution time of approximately 2400 milliseconds under LB4 and 200 ms under LBB (twelve times faster) and the SIEVE2.bas program ran in about 250 ms under LB4 and 30 ms under LBB (more than eight times faster).

• Executables are much smaller. For example the supplied example program ContactMgr424.bas, when compiled with LB4 (using the Create Application menu selection), created ten files totalling over 2.8 Megabytes. The same program compiled using LBB created a single file executable of 122 Kilobytes (more than 20 times smaller).

• Floating-point numbers have an increased range (from less than 1E−4000 to more than 1E+4000) and precision (approximately 19 significant figures).

• Scrolling is smoother; text and graphics windows scroll continuously as you drag the scrollbar.

• Executables include the necessary manifest to make them fully Vista, Windows 7, Windows 8/8.1 and Windows 10 compatible.

• Executables include a VERSIONINFO resource, which can be edited by the user.

• Executables can have a multi-format icon (e.g. with different sizes and bit depths); LB4 supports only 32x32 16-color icons.

• LBB and its executables run successfully even if DEP (Data Execution Prevention) is fully enabled.

• Compiled executables are much more secure. The TKN files generated by LB4 are easily reverse-engineered to recover the BASIC program, and even your LB User Name and Password!

• Resource files, e.g. bitmaps, may be embedded in the executable, and will be automatically extracted when it is run.

• You may compile your program as a Console Application, e.g. for running from a command prompt.

• Random Access Files are not limited to a maximum size of 4 Gbytes, and record numbers are not limited to a 32-bit value.

### Bugs fixed

• TIMER does not cause the PROMPT statement to misbehave, and you can specify a subroutine to be called instead of a branch label (this option does not work correctly in LB).

• You can successfully pass a GLOBAL variable as a parameter to a SUB or FUNCTION.

• SORT and string comparisons use the conventional ASCII character sequence, and repeating a sort leaves the order unchanged.

• Recursion works reliably (in LB 4.04 it may not work when compiled to an EXE).

• The INPUT statement will accept a string variable as the prompt (the Liberty BASIC Help file says this works, but it doesn't in LB 4.04).

• The RND function is improved compared with the LB 4.04 version, and doesn't suffer from bias.

• The MIDDLEBUTTONMOVE event works correctly (in LB 4.04 it never fires).

• The PIE and PIEFILLED graphics commands work correctly.

• The TRAPCLOSE command works correctly with a TEXT window (in LB the window is unconditionally closed).

• The INPUTCSV statement works correctly even if a record contains embedded quotes.

• Many other Liberty BASIC bugs are fixed in LB Booster.

### New features

• You can change the printer font within a page. If you assign a new value to PrinterFont$it will immediately affect subsequent output with LPRINT, allowing you to mix different fonts and styles (e.g. bold) on the same sheet. • You can change the current printer (used by LPRINT and the graphics PRINT command) by setting PrinterName$ to the name of the printer, e.g. PrinterName$= "DoPDF v7". • A new statement PAGESETUPDIALOG is implemented. This displays the standard Page Setup dialogue box, which allows the user to select the margins and paper orientation (portrait or landscape) that will be used by a subsequent LPRINT. • Graphics 'stick' (i.e. automatically get redrawn when a window is restored or uncovered) without any extra effort by the programmer. • The TEXTEDITOR control can be configured for word-wrap using STYLEBITS (LB4's TEXTEDITOR does not support word-wrap at all). • The unary minus is supported. For example the statement 'y = −x' is valid in LBB. • USING() supports a much wider range of options than the LB4 version, including trailing minus, leading or trailing plus, leading asterisks, currency ($ and £), thousands separated by commas and scientific notation.

• DATE$() can return the date in many additional formats, such as European day-month ordering, hyphen delimiters or the month name as an abbreviation. For example PRINT date$("dd/mm/yyyy") or PRINT date$("dd-mmm-yyyy"). • Array elements and structure members can be read directly from a DATA statement, e.g. READ array(i), and can be passed by reference to SUBs and functions. • An entire array may be passed as a parameter to a function or subroutine, making it possible to write general-purpose routines which operate on the contents of any specified array. • LOADBMP accepts a wider range of BMP files than LB4, including files created by Photoshop and GIMP. • The HWND() function has been extended to work with files and communication ports as well as windows. It returns the native Windows file handle, making it possible to use file-related API functions on files opened in LBB. • The background color of (for example) a STATICTEXT control may be selected independently of the background color of its parent window, by changing the value of the BackgroundColor$ variable in between.

• EXIT can exit from nested loops. For example if a FOR...NEXT loop is nested inside a DO loop, an EXIT DO used within the FOR...NEXT loop will exit both loops.

• Sprites can have a linear transparency (alpha mask), allowing the background to show through to varying degrees.

• Unicode text is supported in the mainwin and when outputting to the printer using LPRINT. There is also partial support for displaying Unicode in a GUI control, with the help of some API code.

• Anywhere you can specify a color using one of the preset names (e.g. "brown") you can alternatively specify it using an RGB value (e.g. "0 127 200"). LB4 doesn't allow you to set a GUI color (e.g. BackgroundColor$) that way. • OPEN can open a parallel port (e.g. open "LPT1:" for output as #lpt), for example in order to send data to a printer that does not have (or need) a printer driver. • MAPHANDLE can be used with child controls as well as with windows. This allows, for example, the creation of multiple child controls in a loop, something you cannot normally achieve in LB4. • A TEXTEDITOR control can be used in a DIALOG window, allowing entry of multi-line text (the Enter key moves the cursor to the next line rather than activating the 'default' button). • The GETBMP command can 'see' graphics which are outside the currently visible window, so if you have a scrollable graphics window you can get its entire contents into a bitmap. • The !CONTENTS? command also works with STATICTEXT controls. • The !AUTORESIZE command also works with TEXTBOX and LISTBOX controls. • You can create three- (and more) dimensional arrays using DIM, for example DIM array$(1,2,3,4), but you cannot subsequently resize the array using REDIM (you can, however, use REDIM with the original dimensions simply as a means of emptying the array).

• You can assign a new value to a sub-string, for example MID$(test$,7,1) = "W" or RIGHT$(hello$,6) = "world!".

• A %mode directive optionally enables a standard INT function and conventional precedence of AND over OR.

• An %options directive controls the character encoding and emulation of the string-slicing functions.

• An 'include' directive supports splitting up a large program into modules, and the use of code libraries.
The syntax is: 'include filename.bas.

• Native arrays of structures are supported, they may have any number of dimensions.
To declare an array of structures: STRUCT name(dims), member1 AS type, member2 AS type...
To access a structure array member: PRINT name(index).member.struct

• Compound assignment operators (+=. ‑=, *=, /=) are provided.

• The RUN statement has an option to wait until the program exits.

• The graphics PRINT command has an option to suppress the dump.

• You can paste text into the mainwin INPUT statement using Ctrl+V.

• Object Oriented Programming (OOP) is supported.

• Structured Exception Handling (SEH) is supported.

• A new reserved word PrinterMargin$is introduced which controls output from the LPRINT statement. It should be set to a string such as "10,10,10,10" which sets the left, bottom, right and top margins respectively to 10 millimetres (note that this is in addition to any fixed printer margins). PrinterMargin$ also initialises the PAGESETUPDIALOG.

• Array arithmetic is supported, for example a() = b() - c()   or  a$() = b$() + "!". You can also initialise an entire array to the same value, for example a() = 42.

• Random Access Files may be opened for output (creating a new file) and for input (i.e. read-only) making it possible for a file to be concurrently open for output in one program and open for input in one or more other programs. This can be valuable in a multi-user environment.

• The FILES statement returns each file's date/time stamp in a standard, sortable, format in column 4 of the array.

## Installation

Create a suitable directory (e.g. C:\Program Files (x86)\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™, Windows 8/8.1™ and Windows 10™, 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. 14. There is a limit of 8 on the number of simultaneously-open RANDOM files; however this may be worked around by opening and closing the files for every transaction (GET or PUT). 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

## Liberty BASIC 4.5.0

LB Booster supports the language extensions available in LB 4.5.0, including the INPUTCSV statement and the BACKCOLOR, FORECOLOR, FIND, FINDBACK and RESETFIND texteditor commands.

The LBB implementation of INPUTCSV, unlike LB's, accepts all valid CSV files including those in which records contain embedded quote characters ("). It also accepts CSV files with either Windows-style (CRLF) or Unix-style (LF) line terminations, and files using a delimiter other than a comma.

The new LB 4.5.0 functions are made available through the supplied library file lb45func.bas. This file contains BASIC implementations of the after$(), afterlast$(), endswith(), httpget$(), remchar$(), replstr$(), and upto$() functions. If you want to use any of these functions, add the following line at the very end of your program:

'include lb45func.bas
Compatibility with LB 4.5.0 is maintained, because it will treat this directive as an ordinary comment. Note that the function names must be specified in lower-case.

## 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).

### %options ansi

This directive selects ANSI character encoding, overriding (and changing if necessary) the current selection in the Options menu; it should normally be inserted at or near the start of the program. Note that there must not be a space after the percent sign.

### %options unicode

This directive selects Unicode (UTF-8) character encoding, overriding (and changing if necessary) the current selection in the Options menu; it should normally be inserted at or near the start of the program.

### %options slicing

This directive enables full emulation of the LB string-slicing functions, overriding (and changing if necessary) the current selection in the Options menu; it should normally be inserted at or near the start of the program.

### %options noslicing

This directive disables emulation of the LB string-slicing functions, overriding (and changing if necessary) the current selection in the Options menu; it should normally be inserted at or near the start of the program.

### ! 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:

 -R Run a BAS file on startup -D Debug a BAS file on startup -T Translate and tokenise a BAS file to an LBB file -C Translate and compile a BAS file to an EXE file -A Automatically exit LBB on completion -M Minimise LBB on startup

Examples:

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 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; the buttons are 'greyed out' if they are not functional in the current circumstances:

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

The toolbar also contains a combobox which lists all the branch labels, SUBs and FUNCTIONs in the currently-loaded program. Selecting one of these from the list causes the editor to scroll directly to the appropriate line. You can choose whether the list is sorted alphabetically or according to the order in which the labels etc. appear in the program.

### 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 are displayed the current Encoding (ANSI or Unicode), the Insert/Overtype status, the Caps Lock setting, the Num Lock setting and the Line number of the line containing the text cursor (caret), starting at line 1.

The File menu contains the items New, Load, Save, Save As, Insert, Compare, 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.

The Load command (keyboard shortcut Ctrl+L) loads a Liberty BASIC program into memory. The file should be in plain text (ANSI/ASCII) or Unicode (UTF-8) format; LBB will attempt to detect the format and enable or disable the Unicode Support option as required, although this may not be totally reliable. The file will normally have the extension .BAS.

You can alternatively load a .TKN file created by Liberty BASIC. This can be very useful if you have deleted or mislaid a program, but still have a TKN file generated from it. Note that you must know the original user's Name and LB Password; it is not possible to load a TKN file created by Just BASIC or an unregistered copy of Liberty BASIC.

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.

The program is saved either as ANSI/ASCII text or with UTF-8 encoding, depending on the current setting of the Unicode Support option.

#### Insert

The Insert command inserts the contents of the selected file at the current position of the text cursor (caret); the file should normally contain BASIC code in plain-text (ANSI/ASCII) or Unicode (UTF-8) format. If any text is selected, it is replaced by the inserted text (in the same way as the Paste command).

#### Compare

The Compare command compares the currently-loaded program with the selected file (which should usually be an earlier version of the program) and lists the differences in the right-hand pane. Lines which are identical in the two versions are displayed with the default background color and an equals sign (=) in the first column. Lines in the old version which are different from the new version are shown in red, with a < sign in the first column. Lines in the new version which are different from the old version are shown in green with a > sign in the first column.

To scroll down to the next difference press F8; to scroll up to the previous difference press F7. Note that if your program contains Unicode text this will not display correctly. When you have finished studying the differences you can hide the right-hand pane using the Show LBB pane selection in the Options menu.

#### 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 contains the items Undo, Redo, Cut, Copy, Paste, Delete, Select All, Find, Find Next, Find Previous, Replace and Go To . 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 or beginning of the program the message "Text not found" is displayed; selecting Find Next again causes the search to restart from the beginning or end of the program.

#### Find Previous

The Find Previous command (keyboard shortcut Shift+F3) searches in the reverse direction from the Find Next command. If the current search direction is downwards, Find Previous searches upwards. If the current search direction is upwards, Find Previous searches downwards.

#### 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.

#### Go To

The Go To command (keyboard shortcut Ctrl+G) opens a dialogue box into which you can enter a line number. On selecting OK, or pressing Enter, the text cursor (caret) is positioned at the start of the specified line (the editor scrolls if necessary). This can be particularly useful if an error message indicates a problem in a specific line.

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, Windows™ 8/8.1 and Windows™ 10.

The following additional options are available:

• The program's icon may be changed by clicking on the Change Icon button in the dialogue box. You can select an icon either from an existing executable file, or from a separate icon file (for example as produced by an icon editor). If the file contains a number of different icons, you can select the one you want to use. Please respect Copyright, and use only an icon which you have generated yourself or have legitimately obtained for this purpose.

If the selected icon contains multiple variants with different resolutions (e.g. 16x16, 32x32, 48x48) and/or different color depths (e.g. 8 bits, 32 bits) all the variants will be stored in the compiled executable file. The version used will be the one most suited to the current display settings. Note that such an icon can significantly increase the size of the executable.

• You can embed resource files needed by your program, for example bitmap files or sound files; these will automatically be extracted when the executable is run. This may make it unnecessary to use a separate installer utility, and can be particularly useful in allowing your program to be run directly from a website. Do not incorporate files which your program needs to modify, since any changes will be overwritten the next time the program is run!

To embed resource files in the executable click the Add button; you may select multiple files. The files can be either in the directory containing your program, or in a subdirectory (the subdirectory will be created when the program is run, if necessary). To remove resource files highlight them in the list and click Remove. Note that if your program is installed in a 'protected' location, administrative privileges will be required the first time it is run, to allow the embedded files to be extracted; thereafter it may be run normally.

To embed resource files which will be extracted to the target PC's temporary directory (%TEMP%) - or a subdirectory thereof - click the Add Temp button. The files must be copied to your own temporary directory before the program can be compiled, but you are likely to want to do that anyway for the purposes of testing in the IDE.

• You can create a Console Application by selecting the checkbox. Such an application uses the console terminal instead of the mainwin; output which would normally go to the mainwin will instead go to the console (stdout) and input which would normally be entered in the mainwin will instead be read from the console (stdin). To forcibly close a console application type Ctrl+Break.

• You can edit the Version Information which will be embedded in the executable. There are three checkboxes (Debug, Patched and Prerelease) and eight text fields. Two of those fields (File version and Product version) are expected to contain a numeric version number in the format n.n.n.n (e.g. 5.94.123.678); if you use a different format a warning is issued but the creation of the executable proceeds normally.

#### 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 contains the items Show LBB Pane, Emulate Slicing, Unicode Support, Syntax Coloring, Auto Indenting, Set Font, Set Printer Font and Set Colors. 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.

This option is also used to dismiss the differences listing generated by the File... Compare command.

The Emulate Slicing command alternately enables and disables the full emulation of Liberty BASIC's LEFT$, MID$ and RIGHTfunctions 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 behavior, 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. #### Syntax Coloring The Syntax Coloring command alternately enables and disables the highlighting of elements of your program in different colors. Note that if your program contains Unicode text, and the selected font does not support the required characters, it may display incorrectly. In that case either disable Syntax Coloring or select a different font (Courier New contains a wide selection of Unicode glyphs and will usually be suitable). #### Auto Indenting The Auto Indenting command alternately enables and disables auto-indentation when the Enter (Return) key is pressed. If enabled, the next line is automatically indented to the same column as the current line. #### 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. #### Set Colors The Set Colors command opens a dialogue box allowing you to select which colors are used for the various syntax elements: labels, keywords, quoted strings, handles, comments (delimited with an apostrophe) and everything else. You may choose either from a selection of 48 preset colors, or click on Define Custom Color to make full adjustments available. You can preview the current selection by clicking on Apply and when you are happy click OK. If you click on Cancel any changes will be discarded. Note that the window background color is set, as usual, in your Windows display preferences (for example right-click on the desktop and select Properties or Personalize). ### 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. ### The Editing Pane The editing pane is where the BASIC program currently loaded into memory (if any) is displayed for viewing or editing, or where a new program is entered. All of the normal features which you expect from a Windows™ text editor are available. You can manipulate and edit the program using the keyboard, mouse and touch screen (if applicable). #### Keyboard commands The following operations are available using the keyboard. Note that references to left and right apply to normal left-to-right text, and may be reversed when editing right-to-left text such as Arabic or Hebrew: KeyOperation Insert Toggle between insert and overtype mode. In overtype mode any character typed will over-write the existing character at that position on the line. In insert mode any character typed will 'push' the rest of the line to the right to make room. Delete Delete the character to the immediate right of the cursor (caret) and move the rest of the line left to fill the gap. Home Move the cursor (caret) to the start of the current program line, and scroll the display horizontally (if necessary) to ensure that the cursor is visible. Ctrl+Home Move the cursor (caret) to the start of the program, and scroll the display horizontally and/or vertically (if necessary) to ensure that the cursor is visible. End Move the cursor (caret) to the end of the current program line, and scroll the display horizontally (if necessary) to ensure that the cursor is visible. Ctrl+End Move the cursor (caret) to the end of the program, and scroll the display horizontally and/or vertically (if necessary) to ensure that the cursor is visible. Page Up Display the previous 'page' of the program by scrolling the display down by one screenful (less one line) or until the first line of the program is visible, whichever is less. If the first line of the program is already in view, Page Up has no effect. Page Down Display the next 'page' of the program by scrolling the display up by one screenful (less one line) or until the last line of the program is visible, whichever is less. If the last line of the program is already in view, Page Down has no effect. Move the cursor (caret) one character to the left, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a character. Move the cursor (caret) one character to the right, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a character. Move the cursor (caret) up one line, and scroll the display vertically (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a line. If the cursor is already on the first line, the key has no effect. Move the cursor (caret) down one line, and scroll the display vertically (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a line. If the cursor is already on the last line, the key has no effect. Backspace Delete the character immediately to the left of the cursor (caret), and move the cursor left one position. The rest of the line, to the right of the cursor, is moved left to fill the gap. If the cursor is at the beginning of a line, delete the preceding 'new line' and concatenate the contents of the present line onto the end of the previous line. Return (Enter) Insert a 'new line' at the current position of the cursor (caret). Everything to the right of the cursor will be moved onto the next line, and the rest of the program is moved down one line to make space. By this means you can split an existing line into two or more lines Ctrl+ Move the cursor (caret) one word to the left, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is also held down, select (or de-select) a word. Ctrl+ Move the cursor (caret) one word to the right, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is also held down, select (or de-select) a word. Tab Enter space characters so as to move the text cursor (caret) to the next multiple-of-four column. For correct alignment on the screen and/or the printer a fixed-pitch (monospaced) font must be selected. Ctrl+Backspace Delete the previous word (i.e. to the left of the cursor) and move the rest of the line left to fill the gap. Ctrl+Delete Delete the next word (i.e. to the right of the cursor) and move the rest of the line left to fill the gap. The 'printing' keys (letters, numbers and symbols) cause the appropriate character to be entered at the position of the cursor (caret), and the cursor position is then updated. If any text is selected (highlighted) when the key is pressed, it is first deleted. #### Mouse commands The following operations are available using the mouse: ActionOperation Left click Clicking in the editing pane with the left mouse button causes the text cursor (caret) to be moved to the character position nearest to the mouse pointer. If Shift is held down, the region between the previous position of the text cursor and the new position will be selected. Left double-click Double-clicking in the editing pane with the left mouse button causes the word under the mouse pointer (and the following space, if any) to be selected. The selected word can then be cut, copied, deleted or dragged. Left triple-click Triple-clicking in the editing pane with the left mouse button causes the entire line under the mouse pointer to be selected. The selected line can then be cut, copied, deleted or dragged. Left drag Holding down the left mouse button and 'dragging' the mouse pointer over the program displayed in the editing pane causes a section of the program to be selected. Right click Clicking in the editing pane with the right mouse button causes the Context Menu to be displayed. Wheel Operating the mouse wheel causes the editing pane to scroll vertically, usually by three lines per 'notch'. Ctrl+Wheel Holding down the Ctrl key and operating the mouse wheel causes the editing pane to zoom; note that this will not work if you have selected the System Fixed Font (FixedSys). #### Drag and Drop If you move the mouse pointer over a selected (highlighted) region of your program, the pointer shape changes to an arrow. In this situation holding down the left mouse button and 'dragging' the mouse pointer initiates a Drag and Drop operation. If you drag the mouse pointer to a different point in your program (outside the selected region), and then release the left button, the selected text will be deleted from its original place and inserted where the button was released. This is equivalent to a cut-and-paste operation via the clipboard. Alternatively, if you hold down the Ctrl key before releasing the left button the selected text is copied to the location where the button was released (a plus sign appears next to the mouse pointer indicating a copy rather than a move). This is equivalent to a copy-and-paste operation via the clipboard. If you want to cancel the Drag and Drop operation you can do that by pressing the ESCape key before you release the left button, or by releasing the button when the pointer is inside the selected area. #### Context Menu Clicking in the editing pane with the right mouse button causes the 'floating' context menu to be displayed at the position of the mouse pointer. Alternatively pressing Shift+F10 causes the context menu to appear at the position of the text cursor (caret). If you have a touch screen you can display the context menu by pressing-and-holding until the square or circle appears. The context menu contains the same items as the Edit menu except in the following circumstances: • If you right-click on a label, SUB name or FUNCTION name (or press Shift+F10 when the text cursor is in one of these) the menu will contain the additional item 'Jump to' at the top. Selecting that item will cause the editing pane to scroll so that the label, subroutine or function is visible. • If you have previously executed a 'Jump to' the menu will contain the additional item 'Go back'. Selecting that item will scroll the editing pane back to where it was before the jump took place. Up to 16 jumps may be reversed in this way. #### Scroll bars If the current program cannot be displayed in its entirety within the editing pane, vertical and/or horizontal scroll bars are displayed. These allow you to scroll the display until the part of the program in which you are interested is in view. The scroll bars can be operated in the following ways: • Dragging the scroll box (thumb) along the bar causes the display to scroll accordingly. The size of the scroll box indicates the proportion of the entire program which is displayed within the editing pane - the larger the scroll box the more of the program which is visible. • Clicking on one of the arrow buttons causes the display to scroll in units of one character (horizontally) or one line (vertically). • Clicking in the shaded regions between the scroll box and the arrow buttons causes the display to scroll by one page (less one line) vertically, or by one window's width horizontally. • If your mouse has a 'wheel', rotating the wheel causes the display to scroll vertically, usually by three lines per 'notch'. • If you have a touch screen, you can scroll by 'flicking' in the appropriate direction. Alternatively you can scroll vertically by dragging with a single-finger and horizontally by dragging with two-fingers. ## Language summary Below are alphabetical lists of statements, functions and GUI commands with a brief description of each; there is also a list of reserved names. In the informal syntax definitions square brackets [] indicate optional items, braces {} indicate items which may be repeated zero or more times, and the pipe symbol | indicates alternatives. ### Statements #### BEEP Causes an alert sound to be output from the PC's speakers. #### BMPBUTTON #window[.ext], bmpfile, handler, anchor, posx, posy

Creates a pushbutton containing a bitmap image. The handler may be a branch label or a SUB. The anchor must be UL, LL, UR or LR.

Displays a box containing a question and requesting a yes/no response. On return replyvar$contains either the string "yes" or the string "no". #### CURSOR cursortype Changes the mouse pointer (cursor) shape; options are NORMAL, ARROW, CROSSHAIR, HOURGLASS or TEXT. Alternatively you may specify a Windows Constant, for example CURSOR _IDC_SIZEWE. #### DATA [constant {, constant}] Specifies a list of numeric or string constants to be read by a READ statement. #### DIM array(size{,size}) {, array(size{,size})} Dimensions one or more numeric or string arrays. In LBB arrays may have any number of dimensions. The allowed suffices run from zero to the value of size. DIM is also used to specify class properties in Object Oriented Programming. #### DISCARD object Deletes the specified object (instance of a class) and frees the memory it occupied. #### DO [WHILE | UNTIL condition] Begins a DO loop; optionally followed by a condition determining whether the loop is executed or not. #### DUMP Ejects the page currently being printed. Used in conjunction with LPRINT (and, in LBB, optionally the graphics PRINT command). #### ELSE A delimiter which specifies an alternative course of action in a single-line or multi-line IF statement. Also used in the CASE statement. #### END Terminates the current program. If the mainwin is hidden, or if the program is running as a compiled executable, also terminates the process. #### END CLASS | FUNCTION | IF | SELECT | SUB | TRY Marks the end of the specified clause. #### EXIT FOR | WHILE | DO | FUNCTION | SUB Forces a premature exit from a FOR loop, WHILE loop, DO loop, FUNCTION or SUB. #### FIELD #file, length AS var {, length AS var} Specifies the record structure of a random-access file. The variables may be numeric or string. #### FILEDIALOG "Title", template$, returnvar$Displays a file selector dialog. The template$ determines which files are initially listed, e.g. "*.bas;*.bbc". On return returnvar$contains the selected file, or an empty string if the user pressed Cancel. #### FILES path$, [filter$,] array$()

Fills array$() with a list of files and directories at path$, optionally specifying a filter (e.g. "*.bas").

Displays a Choose Font dialog, initialised with the specified font. On return returnvar$contains the selected font, or an empty string if the user pressed Cancel. See FONT. #### FOR loopvar = start TO finish [STEP increment] Begins a FOR...NEXT loop. If finish is less than start (and the increment is positive) the body of the loop is not executed at all. #### FUNCTION name([[BYREF] parameter {, [BYREF] parameter}]) Begins a user-defined function definition, with optional numeric, string or array formal parameters. If the BYREF qualifier is used the parameter is passed 'by reference' and the variable specified in the function call may be modified by the function. #### GET #file, recordnumber Reads the specified record of a random-access file. The first record in the file is record number 1. #### GETTRIM #file, recordnumber Reads the specified record of a random-access file, and trims leading and trailing whitespace from each field. #### GOSUB destination Calls a subroutine. The destination may be a branch label or a line number. #### GLOBAL variable {, variable} Declares one or more variables as being accessible both outside and inside SUBs and FUNCTIONs. #### GOTO destination Jumps to the specified destination, which may be a branch label or a line number. #### GRAPHICBOX #window.ext, xpos, ypos, width, height Creates a child control that can contain colored graphics and text, or sprites. #### GROUPBOX #window[.ext], "label", xpos, ypos, width, height Creates a groupbox to contain other controls (especially RADIOBUTTONs). #### IF condition THEN Executes the code after THEN if condition, truncated to an integer, is non-zero. May be either a single-line IF statement or, if nothing follows the THEN, a multi-line IF statement. #### INPUT ["prompt";] returnvar {, returnvar} Requests the user to supply numeric or string input in the mainwin. #### INPUT #handle, returnvar {, returnvar} Inputs data from a file or a GUI control; the return variables may be numeric or string. #### INPUTCSV [delim$,] #file, returnvar${, returnvar$}

Inputs data from a Comma-Separated Value (CSV) file; each return variable receives the contents of one field, and may be numeric or string. An alternative delimiter character, for example a semicolon, may be specified; if omitted a comma is assumed.

Creates a listbox and loads it with the contents of array$(). The handler may be a branch label or SUB. #### LOADBMP "bitmap", bmpfile$ | handle

Loads the named bitmap from the specified BMP file. Alternatively a native Windows bitmap handle may be specified as the source.

#### LOCATE column, row

Moves the mainwin text cursor (caret) to the specified coordinates. The rows and columns are numbered starting from 1.

#### LOOP [WHILE | UNTIL condition]

Marks the end of a DO loop. Optionally, looping continues only WHILE or UNTIL the specified condition (truncated to an integer) is non-zero.

#### LPRINT [[TAB(n);] expression {, | ; [TAB(n);] expression} [, | ;]]

Outputs the specified numeric or string expression(s) to the current printer followed by a newline. TAB(n) advances to the specified column and a comma advances to the next multiple-of-14 column; a trailing comma or semicolon suppresses the newline.

#### MAINWIN columns [rows]

Sets the mainwin width to the specified number of character columns, and optionally also sets the height to the specified number of character rows.

#### MAPHANDLE #oldhandle, #newhandle | newhandle$Assigns a new handle to a window or control after it has been created. The new handle may be a string such as "#newhandle". #### MENU #handle, "title", "text", handler {, "text", handler} Creates a drop-down menu. Each item activates a handler, which may be a branch label or a SUB. #### NAME oldspec$ AS newspec$Renames a file. If the file is not found or the rename fails, an error is reported. #### NEW object[(dim [,dim])] AS class [parm {, parm}] Create a new instance (or array of instances) of the specified class, optionally passing parameters to the constructor. #### NEXT [loopvar] Marks the end of a FOR loop, optionally specifying the loop variable. #### NOMAINWIN Hides the 'main window'. When debugging, this statement is ignored. #### NOTICE string$ | number

Displays a message box containing a warning triangle and the specified string or number.

#### ONCOMERROR [handler]

Sets up a handler (which may be a branch label or a SUB) to be called if an error occurs when opening a serial port. If the handler is omitted error trapping is disabled.

#### ON ERROR GOTO destination | 0

Sets up an error handler; if a trappable error occurs control will be passed to the destination, which may be a branch label or a line number. If zero is specified as the destination, error trapping is restored to its previous or default state. For an alternative approach see Structured Exception Handling.

#### OPEN device$FOR type AS #handle [LEN=reclen] Opens a DLL, file, port or window. File open types are INPUT, OUTPUT, APPEND, RANDOM or BINARY; a record length may be specified. Window types are DIALOG, DIALOG_MODAL, DIALOG_POPUP, DIALOG_FS, DIALOG_NF, DIALOG_FS_NF, DIALOG_NF_MODAL, GRAPHICS, GRAPHICS_FS, GRAPHICS_NSB, GRAPHICS_FS_NSB, GRAPHICS_NF_NSB, TEXT, TEXT_FS, WINDOW, WINDOW_NF and WINDOW_POPUP. #### OUT port, data Outputs data to an I/O port (deprecated). #### PAGESETUPDIALOG Displays the standard Page Setup dialog box, allowing the user to specify the paper orientation, margins etc. used by subsequent LPRINT statements. #### PLAYMIDI midifile$, length

Plays a MIDI file; the variable length is set to the length of the music (in arbitrary units, see MIDIPOS).

#### PrinterFont$= "Font_Name points style" Changes the font, size and style used by LPRINT; this has immediate effect, even within a page. #### PrinterName$ = "New printer name"

Changes the printer used for subsequent output using LPRINT or the graphics PRINT command. Also determines which printer is initially selected in the PRINTERDIALOG.

#### PRIVATE

Precedes a method definition, to specify that it may be called only from within the same class.

#### PUT #file, recordnumber

Writes the specified record of a random-access file. The first record in the file is record number 1.

#### RADIOBUTTON #handle.ext, "label", sethandler, resethandler, xpos, ypos, width, height

Creates a radiobutton; if there is more than one group of radiobuttons each group must be placed in a separate group box. The handlers may be branch labels or SUBs.

#### RANDOMIZE [seed]

Causes subsequent random numbers to be predictable, depending on the value of seed (0.0 < seed < 1.0).

Reads one or more numeric or string variables from constants in a DATA statement or statements.

Reads the specified joystick and returns values in Joy1x, Joy1y, Joy1z, Joy1button1, Joy1button2 or Joy2x, Joy2y, Joy2z, Joy2button1, Joy2button2.

#### REDIM array(size{,size}) [, array(size{,size})]

Clears the contents of an array to zeroes or empty strings, and optionally changes its dimensions. Note that you cannot change the dimensions of a three-or-more-dimensional array.

#### REM remark

Allows a comment to be inserted into a program (similar to starting a statement with an apostrophe).

#### RESTORE [destination]

Sets the DATA pointer to the first DATA statement, or to the first DATA statement after the specified destination (which may be a label or a line number).

#### RESUME

Used after an ON ERROR GOTO statement has been executed, causes execution to continue at the line in which the error occurred. Only useful if the cause of the error has been cleared. For an alternative approach see Structured Exception Handling.

#### RETURN

Returns from a subroutine called with GOSUB.

#### RUN command$[, state] Runs the specified external command (which may include 'command-line' parameters), optionally initialising the window to the specified state (e.g. HIDE or MINIMIZE). If the state is WAIT, does not return until the external program has finished. #### SCAN Gives an opportunity for a pending event (for example a TIMER or mouse event) to be handled. #### SEEK #handle, position Moves the file pointer to the specified position (in bytes, not records). #### SELECT CASE [testexpression] Evaluates the specified (numeric or string) expression, and compares it with the values specified in subsequent CASE statements. If equal, the code following the CASE statement is executed. If the expression is omitted, each CASE statement must specify a Boolean expression. #### SORT array(), start, end [, column] Sorts the specified range of array elements (numeric or string); if end is less than start the array is sorted into reverse order. If the array is two-dimensional, start and end indicate the range of rows to be sorted, and column indicates which column to use as the sort key. #### STATICTEXT #handle[.ext], "title", xpos, ypos, width, height Creates a static text control, typically used to label another control or to give instructions. #### STOP Identical in effect to END. #### STOPMIDI Stops any currently playing MIDI file (see PLAYMIDI). #### STRUCT name[(size{,size})], member AS type {, member AS type} Creates a user-defined structure, or array of structures. Valid data types are CHAR[n], DOUBLE, LONG, BOOLEAN (same as LONG), ULONG, HANDLE (same as ULONG), PTR, STRUCT, SHORT, USHORT and WORD (same as USHORT). #### STYLEBITS #handle[.ext], addbits, removebits, addextendedbits, removeextendedbits Adds or removes bits from the style and/or extended-style of the specified window or control. Must be used before the window is opened. #### SUB name [[BYREF] parameter {, [BYREF] parameter}] Begins a user-defined subroutine definition, with optional numeric, string or array formal parameters. If the BYREF qualifier is used the parameter is passed 'by reference' and the variable specified in the CALL statement may be modified by the SUB. #### TEXTBOX #handle.ext, xpos, ypos, width, height Creates a textbox (usually single-line, unless modified by STYLEBITS), into which the user can type information. #### TEXTEDITOR #handle.ext, xpos, ypos, width, height Creates a multi-line texteditor control. #### THROW errnumber [, errstring$]

Causes a user-defined error to be generated. Err is set equal to errnumber and, optionally, Err$is set equal to errstring$. User-defined error numbers should be limited to the range 70 to 180.

#### TIMER milliseconds, handler | 0

Starts an event timer; the specified handler (which may be a branch label or a SUB name) is called repetitively with the specified period in milliseconds. TIMER 0 causes the timer to be disabled.

#### TITLEBAR title$Changes the contents of the mainwin's title bar. #### TRACE 0 | 1 | 2 Enables or disables run-time tracing; normally used in conjunction with the debugger. TRACE 2 pauses the program and enables single-step mode, TRACE 1 prints line numbers to the mainwin as they are executed, TRACE 0 restores normal operation. #### TRY Begins a TRY...CATCH...END TRY clause. #### UNLOADBMP "bitmap" Deletes the specified bitmap and releases the memory it occupied. #### UNTIL Part of the DO...LOOP clause. #### WAIT Waits for an event (e.g. a TIMER, keyboard or mouse event). Execution never continues beyond this statement. #### WEND Indicates the end of a WHILE loop. #### WHILE condition Begins a WHILE...WEND loop. Looping continues whilst the specified condition, truncated to an integer, is non-zero. ### Functions #### ABS(numeric) Returns the absolute value, i.e. if the parameter is negative it is returned as positive. #### ACS(numeric) Returns, in radians (0 to +PI), the angle with the specified cosine. #### ASC(string$)

Returns the ASCII/ANSI value of the first character in the string. If the string is empty, zero is returned

#### ASN(numeric)

Returns, in radians (-PI/2 to +PI/2), the angle with the specified sine.

#### ATN(numeric)

Returns, in radians (-PI/2 to +PI/2), the angle with the specified tangent.

#### CHR$(numeric) Returns a string of length one containing the character with the specified ASCII/ANSI value. #### COS(numeric) Returns the cosine of the specified (radian) angle. #### DATE$([format$| dayno]) Returns the current date in various formats, or converts a day number to a date. #### DECHEX$(numeric)

Converts an integer value to its hexadecimal equivalent.

#### EOF(#handle)

Returns non-zero if the end of the file has been reached and zero otherwise.

#### EVAL(string$) Evaluates the specified expression and returns the result as a number. #### EVAL$(string$) Evaluates the specified expression and returns the result as a string. #### EXP(numeric) Returns e (2.718281828459045236) raised to the power of the specified value. #### HBMP("bitmap") Returns the native Windows handle of the specified bitmap. #### HEXDEC(hex$)

Converts the specified hexadecimal number to a numeric value. The hex number may optionally be prefixed with "&H".

#### HWND(#handle[.ext])

Returns the native Windows handle of the specified window, control, file or serial port.

#### INP(numeric)

Inputs a value from the specified I/O port (deprecated).

#### INPUT$(count) Reads a single character from the keyboard in the mainwin (count is ignored). #### INPUT$(#handle, count)

Reads the specified number of characters (bytes) from the specified file.

#### INPUTTO$(#handle, char$))

Reads from the specified file up to the specified delimiter character or CR (carriage return), whichever comes first.

#### INSTR(searchin$,searchfor$[,startat])

Searches a string for the specified sub-string, optionally starting at a specified place, and returns the position of the first match. If the string was not found, zero is returned.

#### INT(numeric)

Converts a numeric value to an integer. By default LBB works in the same non-standard way as LB 4.04 (it truncates towards zero). If the %mode std directive has been issued, it works in the standard way (it truncates towards minus infinity).

#### LEFT$(string$,count)

Returns the first count characters from the string. By default if count is negative the entire string is returned; if the Emulate Slicing option has been enabled, an empty string is returned.

#### LEN(string$| structname.struct) Returns the length of the specified string, or the size of the specified structure (in bytes). #### LOC(#handle) Returns the current position of the file pointer (in bytes). #### LOF(#handle) Returns the length of the file, in bytes. #### LOG(numeric) Returns the natural (base-e) logarithm of the specified value. #### LOWER$(string$) Converts the specified string to lower-case characters. #### MAX(numeric,numeric) Returns the maximum (most positive) of the two specified values. #### MID$(left$,start[,count]) Returns a sub-string, starting at start and containing a maximum of count characters. If the third parameter is omitted, it returns the rest of the string. By default if count is negative the rest of the string is returned; if the Emulate Slicing option has been enabled, an empty string is returned. #### MIDIPOS() Returns the current position of a playing MIDI file, in the same units as returned by PLAYMIDI. #### MIN(numeric,numeric) Returns the minimum (most negative) of the two specified values. #### MKDIR(path$)

Attempts to create the specified directory (folder) and returns zero if it was sucessful; a non-zero return indicates a failure.

#### NOT(numeric)

Boolean negation: returns zero if the specified value (truncated to an integer) is non-zero, and ‑1 if the specified value is zero.

#### RIGHT$(string$,count)

Returns the rightmost count characters of the specified string. By default if count is negative the entire string is returned; if the Emulate Slicing option has been enabled, an empty string is returned.

#### RMDIR(path$) Attempts to remove the specified directory (folder) and returns zero if it was sucessful; a non-zero return indicates a failure. #### RND([n]) Returns a pseudo-random number in the range 0 to 1.000. The parameter n, if supplied, is ignored. The sequence length is 233‑1. #### SIN(numeric) Returns the sine of the specified (radian) angle. #### SPACE$(n)

Returns a string consisting of n spaces.

#### SQR(numeric)

Returns the square-root of the specified (non-negative) value.

#### STR$(numeric) Converts the specified value to a string representation. For floating-point numbers this returns a maximum of 9 significant figures; for more precision use USING() instead. #### TAN(numeric) Returns the tangent of the specified (radian) angle. #### TIME$([format$]) Returns the current time. If the format string is omitted the time is returned as "hh:mm:ss". If the format string is "seconds" or "ms" the number of seconds or milliseconds, respectively, since midnight is returned. #### TRIM$(string$) Removes 'whitespace' (spaces and non-printing characters) from the beginning and end of the specified string. #### UPPER$(string$) Converts the specified string to upper-case (capitals). #### USING(template$, numeric)

Converts the specified value to a string representation, using the format specified in the template (e.g. "#.##", "###,###,###", "#.###^^^^"). For floating-point numbers, up to 19 significant figures may be returned.

#### VAL(string$) Convert the specified string to a numeric value. If the string does not represent a numeric constant, zero is returned. #### WINSTRING(pointer) Returns the NUL-terminated string stored in memory at the specified address. #### WORD$(string$, number [, delim$])

Splits the specified string into words separated by the specified delimiter (if supplied) or otherwise by whitespace (spaces and non-printing characters). Returns the word indexed by number.

### Operators

#### numeric AND numeric

Returns the bitwise AND of the two operands, truncated to 64-bit integers. In other words a bit is set in the output only if that bit is set in both operands. Commonly used in Boolean expressions.

#### numeric MOD numeric

Returns the remainder after division of the first operand by the second operand. If the second operand is zero a Division by zero error will result.

#### numeric OR numeric

Returns the bitwise OR of the two operands, truncated to 64-bit integers. In other words a bit is set in the output if that bit is set in either or both of the operands. Commonly used in Boolean expressions.

#### numeric XOR numeric

Returns the bitwise XOR of the two operands, truncated to 64-bit integers. In other words a bit is set in the output only if that bit is set in just one of the operands, but not both.

### Graphics commands

#### BACKCOLOR color

Sets the color used to fill a solid shape. The color may be specified either as a name or an RGB triplet (see COLOR).

#### BOX xpos ypos

Draws an outline axis-aligned rectangle with one corner at the current graphics (pen) position and the opposite corner at the specified coordinates.

#### BOXFILLED xpos ypos

Draws a filled axis-aligned rectangle with one corner at the current graphics (pen) position and the opposite corner at the specified coordinates.

Draws an outline circle with its centre at the current graphics (pen) position and with the specified radius.

Draws a filled circle with its centre at the current graphics (pen) position and with the specified radius.

#### CLS

Clears the entire GRAPHICBOX or graphics window to white (or whatever your default window color is set to be in Display Properties).

#### COLOR color

Sets the color used to draw lines or text. The color may be specified either as a name (black, blue, brown, buttonface, cyan, darkblue, darkcyan, darkgray, darkgreen, darkpink, darkred, green, lightgray, palegray, pink, red, white, yellow) or an RGB triplet (e.g. 0 128 255).

Ignored by LBB. Depending on the usage, consider substituting REDRAW (deprecated).

#### DOWN

Enables graphics drawing.

#### DRAWBMP bitmap x y

Plots the specified bitmap with its top-left corner at the specified coordinates.

#### ELLIPSE width height

Draws an outline axis-aligned ellipse with its centre at the current graphics (pen) position and with the specified width and height.

#### ELLIPSEFILLED width height

Draws a filled axis-aligned ellipse with its centre at the current graphics (pen) position and with the specified width and height.

#### FILL color

Fills the entire GRAPHICBOX or graphics window with the specified color, specified either as a name or an RGB triplet (see COLOR).

#### FLUSH [segment]

Makes a temporary copy of the current contents of the GRAPHICBOX or graphics window, which may later be restored using REDRAW; if a segment is specified it is ignored (deprecated).

#### FONT typeface [width] height {style}

Sets the current text font to the specified typeface, size and optional style(s). The size may be specified either in points or as a width and height in pixels (if the width is set to zero the default width is used). The styles are italic, bold, strikeout, and underscore.

#### GETBMP bitmap xpos ypos width height

Copy the specified region of the GRAPHICBOX or graphics window to the specified bitmap.

#### GO distance

Move the pen 'forwards' the specified distance, drawing if it is DOWN.

#### GOTO xpos ypos

Move the pen to the specified coordinates, drawing if it is DOWN.

#### HOME

Centers the pen in the GRAPHICBOX or graphics window.

#### HORIZSCROLLBAR on | off [min max]

Enables or disables the horizontal scrollbar, and optionally specifies the scroll range.

#### LINE x1 y1 x2 y2

Draws a line between the specified coordinates; the pen is moved to the end point.

#### NORTH

Sets the current pen direction to 'upwards' (270 degrees).

#### PIE width height start sweep

Draws an outline sector, with the centre at the current graphics (pen) position. The start angle is in degrees, with zero representing 'east', and a positive value of sweep indicates a clockwise direction.

#### PIEFILLED width height start sweep

Draws a filled sector, with the centre at the current graphics (pen) position. The start angle is in degrees, with zero representing 'east', and a positive value of sweep indicates a clockwise direction.

#### PLACE xpos ypos

Moves the pen to the specified coordinates; no line is drawn, even if the pen is DOWN.

#### POSXY xvar yvar

Copies the current graphics (pen) coordinates to the specified variables.

#### PRINT [size [nodump]]

Sends the contents of the GRAPHICBOX or graphics window to the printer, scaling them so that a width of size pixels fills the printed page. Normally the page is automatically ejected, but by specifying nodump you can LPRINT text on top of the graphics and then issue a DUMP command.

#### REDRAW [segment]

Replaces the current graphics with the temporary copy saved using FLUSH; if a segment is specified it is ignored (deprecated).

#### RULE code

Sets the drawing method to normal (OVER) or exclusive-or (XOR). Alternatively one of the Windows _R2_ constants may be specified.

#### SET xpos ypos

Draws a single point at the specified coordinates.

#### SIZE thickness

Sets the line thickness, in pixels.

#### STRINGWIDTH? string$retvar Measures the width of the specified string, in pixels, and returns it in the specified variable. #### TURN degrees Rotate the drawing direction by the specified number of degrees (clockwise). #### UP Disable graphics drawing (some drawing commands still work even if the pen is 'up'). #### VERTSCROLLBAR on | off [min max] Enables or disables the vertical scrollbar, and optionally specifies the scroll range. #### WHEN event handler Calls the specified handler (which may be a branch label or a SUB) when the specified mouse or keyboard event occurs: leftButtonDown leftButtonUp leftButtonDouble leftButtonMove rightButtonDown rightButtonUp rightButtonDouble rightButtonMove middleButtonDown middleButtonUp middleButtonDouble middleButtonMove mouseMove characterInput #### \text string Displays the specified text followed by a newline. Additional \ characters cause newlines to be printed. | may be used instead of \ if the backslash character needs to be printed. ### Text commands #### !BACKCOLOR color (TEXTEDITOR or TEXT window only) Sets the background color; the color may be specified either as a name or an RGB triplet (see COLOR). #### !CLS Clears the window. #### !CONTENTS string$ | #filehandle

Loads the window with the contents of the specified string or open file.

#### !CONTENTS? string$Copies the text contents into the specified variable. #### !COPY Copies the current selection (if any) to the clipboard. If nothing is selected the clipboard is emptied. #### !CUT Cuts the current selection (if any) to the clipboard. If nothing is selected the clipboard is emptied. #### !FIND string$

Searches downwards to find the text contained in the specified variable.

#### !FINDBACK string$Searches upwards to find the text contained in the specified variable. #### !FONT typeface [width] height {style} Sets the current text font to the specified typeface, size and optional style(s). The size may be specified either in points or as a width and height in pixels (if the width is set to zero the default width is used). The styles are italic, bold, strikeout, and underscore. #### !FORECOLOR color (TEXTEDITOR or TEXT window only) Sets the color of all the text; the color may be specified either as a name or an RGB triplet (see COLOR). #### !INSERT string$

Inserts the contents of the specified variable at the current text cursor (caret) position.

#### !LINE n string$(TEXTEDITOR or TEXT window only) Copies the specified line into the string variable (the top line is line 1). #### !LINES retvar Returns the total number of lines in the specified numeric variable. #### !MODIFIED? answer$

If the text has been modified sets the specified variable to "true", otherwise sets it to "false".

#### !ORIGIN column row

Scrolls the text so that the first visible character is as specified (the first row and column are number 1).

#### !ORIGIN? colvar rowvar

Sets the specified variables to the text coordinates of the first visible character (the first row and column are number 1).

#### !PASTE

Pastes the text contents of the clipboard (if any) at the current text cursor (caret) position.

#### !RESETFIND

Starts the next search from the beginning or end of the text.

#### !SELECT column row

(TEXTEDITOR or TEXT window only) Moves the text cursor (caret) to the specified column and row (this command is confusingly named!).

#### !SELECTALL

Selects all the text.

#### !SELECTION? string$(TEXTEDITOR or TEXT window only) Copies the currently-selected text, if any, into the specified string variable. ### Other GUI commands #### AUTORESIZE Automatically resizes the control if the user resizes the window. #### BITMAP bitmap Displays the specified bitmap on the button (BMPBUTTON). #### DISABLE Disables the control. #### ENABLE Enables the control. #### HIDE Hides the control. #### LOCATE xpos ypos [width height] Repositions and optionally resizes the control according to the specified values. #### REFRESH Redraws the window and any child controls. Also updates the WindowWidth and WindowHeight variables to correspond to the window's client area (i.e. excluding any borders). #### RELOAD Reloads the control from the associated array (COMBOBOX or LISTBOX). #### RESET Unchecks the specified box (CHECKBOX or RADIOBUTTON). #### RESIZEHANDLER handler Calls the specified handler (which may be a branch label or a SUB) when the window is resized. #### SELECT string Searches for the specified literal string and if found selects that item (COMBOBOX and LISTBOX). #### SELECTINDEX index Selects the item at the specified index (COMBOBOX or LISTBOX). #### SELECTION? string$

Copies the currently selected item to the specified string variable (COMBOBOX and LISTBOX).

#### SELECTIONINDEX? retvar

Returns the index of the currently selected item in the specified numeric variable (COMBOBOX and LISTBOX).

#### SET

Checks the specified box (CHECKBOX or RADIOBUTTON).

#### SETFOCUS

Transfers 'input focus' to the control, causing subsequent keyboard and mouse input to be received by it.

#### SHOW

Makes the control visible.

#### SINGLECLICKSELECT [handler]

Causes the control's handler to be activated by a single-click rather than a double-click (COMBOBOX or LISTBOX). If the optional handler is specified it will be activated by a single click (in which case a double-click will activate both that handler and the control's normal double-click handler).

#### TRAPCLOSE handler

Activates the specified handler (which may be a branch label or a SUB) when the window is closed.

#### VALUE? retvar$Returns the current state ("set" or "reset") in the specified string variable (CHECKBOX or RADIOBUTTON). ### Sprite commands #### ADDSPRITE sprite bitmap { bitmap} Adds a named sprite. Multiple bitmaps may be specified for animated sprites. #### BACKGROUND bitmap Use the specified bitmap as the sprites' background. The bitmap is stretched as necessary. #### BACKGROUNDXY x y Scroll the background so the specified coordinates are in the top-left corner. The bitmap is tiled as necessary. #### CENTERSPRITE sprite Offsets the sprite so that its reference point is centered. #### CYCLESPRITE sprite dir [once] Automatically cycles the sprites through its image list at each DRAWSPRITES command. dir specifies whether the images are cycled forwards (1) or backwards (-1). If the optional once parameter is specified, the sprite cycles through its image list just once. #### DRAWSPRITES Updates the display: draws the background and all the sprites. Animates and/or moves sprites to which the CYCLESPRITE, SPRITEMOVEXY or SPRITETRAVELXY command has been issued. #### REMOVESPRITE sprite Deletes the specified sprite. #### SPRITECOLLIDES sprite list$

Copies into the specified string variable a list of other sprites which the specified sprite currently overlaps (if any).

#### SPRITEIMAGE sprite bitmap

Selects the specified bitmap from the sprite's image list.

#### SPRITEMOVEXY sprite xshift yshift

Moves the sprite by the specified amount at each DRAWSPRITES command.

#### SPRITEOFFSET sprite xoff yoff

Offsets the sprite from its nominal coordinates.

#### SPRITEORIENT sprite orientation

Displays the sprite according to the specified orientation (normal, flip, mirror, rotate180).

#### SPRITEROUND sprite

When testing for sprite collisions, assumes the sprite is elliptical not rectangular.

#### SPRITESCALE sprite scale

Scales the sprite by the specified amount in percent.

#### SPRITETOBACK sprite

Displays the sprite behind all the others.

#### SPRITETOFRONT sprite

Displays the sprite in front of all the others.

#### SPRITETRAVELXY sprite x y speed handler

Automatically moves the sprite towards the specified coordinates at the specified speed, at each DRAWSPRITES command. When the sprite has reached its destination, activates the specified handler, which may be a branch label or SUB.

#### SPRITEVISIBLE sprite on | off

Makes the sprite visible or invisible.

#### SPRITEXY sprite xpos ypos

Moves the sprite directly to the specified coordinates.

#### SPRITEXY? sprite retx rety

Returns the sprite's current coordinates in the specified numeric variables.

### Reserved names

The following variable names are pre-defined and have special meanings in LB Booster:

BackgroundColor$, Com, ComboboxColor$, ComError$, ComErrorNumber, CommandLine$, ComPortNumber, DefaultDir$, DisplayHeight, DisplayWidth, Drives$, Err, Err$, ForegroundColor$, Inkey$, Joy1button1, Joy1button2, Joy1x, Joy1y, Joy1z, Joy2button1, Joy2button2, Joy2x, Joy2y, Joy2z, ListboxColor$, MouseX, MouseY, Platform$, PrintCollate, PrintCopies, PrinterFont$, PrinterMargin$, PrinterName$, StartupDir$, TextboxColor$, TexteditorColor$, UpperLeftX, UpperLeftY, Version$, WindowHeight, WindowWidth.

## Object Oriented Programming

LB Booster (version 3.00 and later) supports Object Oriented Programming (OOP). Whilst this is an entirely optional feature, which does not affect compatibility with earlier versions of LBB or LB4, it is a powerful modern capability. Four new statements are defined: CLASS, DISCARD, NEW and PRIVATE.

Below is a brief syntax description, but for more details and examples see this article at the LBB Wiki.

#### Instantiating an object

An object is created as an instance of a class. Objects may either be created individually, or an array of identical objects may be created. When an individual object is created, parameters may optionally be passed to its constructor (having the correct signature). If an array of objects is created, only the default constructors are called:
NEW object AS class [parm {, parm}]                ' calls constructor [with parameters]
NEW objarr(dimensions) AS class                    ' calls default constructors (if any)

#### Calling object methods

Object methods behave either like SUBs or like FUNCTIONs, and they are called in the same way. The target is specified as the name of the object followed by two colons :: (known as the scope resolution operator) and then the name of the method. If the object is an element of an array, the index or indices come before the colons:
CALL object::method [parameter {, parameter]}]     ' subroutine-like method
lvalue = object::method([parameter {, parameter}]) ' function-like method
CALL objarr(indices)::method [parm {, parm]}]      ' subroutine-like method
lvalue = objarr(indices)::method([parm {, parm}])  ' function-like method

When an object, or array of objects, is no longer required it should be DISCARDed. This automatically calls the object's destructor (if any) and then frees the memory occupied by the object:
DISCARD object                                     ' calls destructor (if any)
DISCARD objarr()                                   ' calls destructor in each (if any)

#### Defining a class

A class definition should be placed after the end of the main program, in the same way as SUB and FUNCTION definitions are. If a class inherits properties and/or methods, its parent class must be defined first.

The class properties (variables and arrays) are private to the class: they can be accessed only from the methods in the same class; this is similar to the scope of variables within ordinary SUBs and FUNCTIONs except that class properties 'remember' their values from one call of a method to the next. Unlike conventional arrays, class property arrays are not global.

The properties should be declared first, using a special form of the DIM statement, followed by the methods. The default constructor(s), if any, have the same name as the class; the destructor (if any) has the name of the class prefixed with a tilde ~.

To call a method in the same class, prefix its name with this::, a PRIVATE method can only be called this way.

CLASS class [INHERITS class]
' class properties are automatically private
DIM var | var$| array(n) | array$(n) | child AS class {, ....}

SUB class
' default constructor (optional)
END SUB

SUB ~class
' destructor (optional)
END SUB

SUB class parm {, parm]}
' constructor with parameter(s)
END SUB

[PRIVATE] SUB method [parm {, parm}]
' subroutine-like or setter method
CALL this::method [parameter {, parameter]}]    ' call another method in this class
lvalue = this::method([parameter {, parameter}])' function-like method in this class
CALL child::method [parameters]                 ' call method in child class
lvalue = child::method [parameters]             ' function in child class
lvalue = property                               ' read property variable
property = rvalue                               ' write property variable
END SUB

[PRIVATE] FUNCTION method [parm {, parm}]
' function-like or getter method
END FUNCTION
END CLASS

#### OOP notes

• Methods can't take BYREF parameters which aren't variables or arrays.

• Methods are overloaded using the number of parameters as a signature.

• An object name cannot be the same as a STRUCT name.

• The default constructor (with no parameters) is always called (first) if present.

• The constructor/destructor in a parent class is not called automatically if the descendent class has one.

• Constructors/destructors in a child class aren't called automatically.

## Structured Exception Handling

LB Booster (version 3.00 and later) supports Structured Exception Handling (SEH). This is a way of handling errors which is easier to use, and more flexible, than ON ERROR GOTO. Three new statements are defined: TRY (and END TRY), CATCH and THROW.

This is the structure of the TRY clause:

TRY
' Code which might fail
CATCH
' Code to execute if an error occurs in the TRY clause
END TRY
Here is a practical example:
for n = -3 to 3
try ' code to try
print "The reciprocal of "; n ; " is ",
print 1/n,
print "(successful)"
catch ' code to run on an error
print Err$; print " (failed: code "; Err; ")" end try ' end of try clause next n which produces the following output: The reciprocal of -3 is -0.333333333 (successful) The reciprocal of -2 is -0.5 (successful) The reciprocal of -1 is -1 (successful) The reciprocal of 0 is Division by zero at line 4 (failed: code 11) The reciprocal of 1 is 1 (successful) The reciprocal of 2 is 0.5 (successful) The reciprocal of 3 is 0.333333333 (successful) THROW is used to trigger a user-defined error: throw 88, "My custom error" This generates an error which sets Err to 88 and Err$ to "My custom error". The string may be omitted, in which case a default message is generated:
throw 88
Custom error codes should be limited to the range 70 to 180 to avoid a clash with pre-defined LBB error numbers.

## 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). Any NOMAINWIN statement in your program will be ignored when debugging, since the mainwin is a useful place for your program to send diagnostic information.

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. DefaultDir$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

• If your program uses the graphics command discard, and does not run properly in LBB, try changing the discard to redraw:
#w "redraw"

• Compatibility with LBB may be impaired if you draw graphics using the Windows API, without periodically executing a wait statement. For example, rather than calling the Sleep API (or simply having an 'infinite loop' containing a scan statement) use a timer/wait combination:
timer 40, [loop]
wait

[loop]
' do the graphics drawing here
wait

• If you receive the error message 'Bad use of array' check that your program doesn't attempt to access an array before it is DIMensioned. This code, taken from FreeForm404.bas, runs (but doesn't do anything useful) under LB4, but LBB reports an error:
font$(1)=dFont$
...
dim font$(3) • If you receive the error message 'Handle used for incompatible devices' it means you have used the same handle name for both a file and a window (or a DLL and a window, etc.). LBB needs each handle name to refer to only one kind of device. To fix the problem change one of the handles. • If you receive the error message 'Duplicate structure with ambiguous member' it means you have used the same name for two different STRUCTs, which share a member having the same name but a different type. To fix the problem change one of the structure or member names. • If your program uses string slicing (i.e. the LEFT$, MID$or RIGHT$ functions), and it is giving unexpected results, try selecting Emulate Slicing in the Options menu.

• LBB-compiled programs reserve 500 Mbytes of virtual address space (not the same thing as 500 Mbytes of memory!). If, exceptionally, your virtual memory is heavily fragmented, or if you have disabled VM in your Windows settings, this allocation may fail. In that case add a line similar to this in the [settings] section of LBB.ini (which can be found in your %appdata% folder):
memory=100000000

## 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.