CONCEPT

	Whilst the query facilities available within FastBase are very 
powerful, there is always something you want to do that requires that 
one extra facility. Rather than keep adding endless little features to 
an already complicated function I have implemented a small but very 
flexible programming language.

	Anyone who has used the BASIC programming language will 
feel at home since FBML uses many of the concepts of BASIC, toge- 
ther with some ideas borrowed from "C". FBML is an interpreted lan- 
guage. This means that you simply type the program into the editor 
and run it. There is no complicated edit-compile-link-run cycle and 
any mistakes that you make are reported to you as they are found.

	Whilst the editor is primarily designed to be used for entering 
FBML programs, you can use it to edit any ASCII text files. For ex- 
ample, you could use it to design a template for the "Mailshot" facil- 
ity.

THE EDITOR

	To open an editor window, select the "Program" option from the 
"Process" menu. The editor window will appear, and this is where 
you enter your program. You may open as many editor windows as you 
like, up to the ST's maximum (currently seven). Each window is en- 
tirely independent and each one can contain a different program.

THE STATUS BAR
	The top bar of the editor window shows some status informa- 
tion. "L:" and "C:" display the current line and column position of 
the cursor. "st" indicates that you are currently editing an ST com- 
patible ASCII file. For those that know the difference, the editor can 
also edit Unix compatible ASCII files. If you don't know the diffe- 
rence then don't worry, you don't need to. The "--" text indicates 
that you have not made any changes to the current text file that have 
not been saved. If this shows "**" then there are changes that have 
not been saved.

ENTERING TEXT
	Just type ! Yes it's as easy as that. Simply use the cursor keys 
or the mouse to position the cursor where you want it and type the 
information that you want. If you enter more than a screen full of 
text then you can use the arrow buttons and slider bar at the right of 
the window to move the display position. In addition to the arrow 
keys, there are several others available to help you move around your 
text quickly.

Shift-up		Scroll the display up by one screen
Shift-down		Scroll the display down by one screen
Shift-left		Move the cursor to the start of the line
Shift-right		Move the cursor to the end of the line
Control-up		Move to the top line in the text
Control-down	Move to the last line in the text
Control-left	Move to the previous word on the current line
Control-right	Move to the next word on the current line

	In addition to these, using "Control" in conjunction with "+" 
and "-" on the numeric keypad converts the letter under the cursor to 
upper or lower case, respectively.

OPTIONS
	There are a lot of options available to you, and are selectable 
by using "Control" plus another key. Alternatively you can bring up 
a popup menu by positioning the mouse pointer over the appropriate 
editor window and holding down the right button. The available op- 
tions are described, one at a time, below. If you want a quick look at 
a table of all the keyboard shortcuts then simply press the "Help" 
key.

FILE > LOAD
	This option allows you to load a text file from disk. Simply use 
the file selector to pick the name of the file that you want to load. If 
you are editing a file that contains changes that you haven't yet sa- 
ved then use the "Save" option to save it to disk. If the editor reports 
that the file is too big to load then you need to use the "Install" op- 
tion from the main "File" menu to alter the amount of memory the 
editor allows you to use. Alter this value to something slightly larger 
than the size of the file you want to load. To find out the size of a fi- 
le, click on it once while using the file selector and select "Informa- 
tion" from the popup menu that appears when you click on the 
"Tools" button.

FILE > SAVE
	This option saves the current file to disk for permanent storage. 
Simply use the file selector to choose the name of the file to save. 
You should always save your files to disk before leaving FastBase or 
closing the editor window.

FILE > MERGE
	Merging a file takes it from disk and inserts it into the text at 
the position of the cursor. Ensure that the cursor is at the position 
where you want the file to be inserted, then use the file selector to 
choose the name of the file to insert. The warnings about file size 
that were given above apply to this option.

EDIT > DELETE LINE, INSERT LINE, DEL. TO END
	These three options are used for quick editing of your text. Se- 
lecting "Delete line" deletes the entire line of text under the cursor. 
"Insert line" inserts a blank line under the cursor, moving all other 
lines down. "Del. to end" deletes all the text from under the cursor to 
the end of the current line.

TEXT > SEARCH
	This option is used for searching for text within the file you are 
editing. This is very useful when you are editing a large file and 
can't remember where in the file it is. A dialogue box will appear, 
into which you simply enter the text to search for and click on 
"Search".

	There are other options in this dialogue box that make the 
search facility more powerful. If you enter some text into the "Repla- 
ce:" text-entry field and click on the "Replace" button you can re- 
place occurrences of the search text with the replace text. You will 
be asked at each occurrence of the search text whether you really do 
want to replace it.

	The "From cursor" and "From start" buttons tell the editor 
where to start looking for the search text, and are self explanatory. 
The "AAAA=aaaa" and "AAAA<>aaaa" govern whether the search is 
to be case independent, or case dependent respectively. Case inde- 
pendent means that the search treats capital and lower case letters as 
the same.

TEXT > ...NEXT
	This option moves the cursor from the current position to the 
next position that matches the search criteria given in the "Search" 
option. When you select the "Search" option, described above, the 
cursor will move to the matching text within your file. This option is 
used to move to the next matching position.

TEXT > GO TO
	Selecting this option brings up a small box, into which you 
should type the number of the line that you wish to jump to. The 
cursor and screen display will move to the requested position.

TEXT > INFO
	This option displays some statistics about your text. Informa- 
tion displayed includes the cursor position, number of lines in the fi- 
le and the amount of memory used. This last value is shown as a 
number and a thermometer-style bar.

TEXT > TAB SIZE
	When you press the Tab key, the cursor jumps to the next tabu- 
lator position along the line. These tabulator marks are set by default 
to 2 spaces apart because program control structures are easy to read 
when indented by a small amount. If you don't like the default sett- 
ing of 2 spaces, use this option to change it.

TEXT > PRINT
	If you want to print out your text file to the printer, select this 
option. Do ensure that your printer is connected and on-line before 
selecting this option, otherwise you will have to wait about 30 se- 
conds to abort the print.

TEXT > CLEAR
	This option deletes all the text in the editor and leaves you to 
start afresh. If you have made changes that have not been saved to 
disk then you will be warned before the text is cleared. Any files that 
you have saved to disk are not affected by this option.

TEXT > SHOW KEY
	This option is used to show the codes of keys used by the 
@inkey(n) function, described further in this paper. The code of 
every key pressed will be shown at the top of the screen. When you 
have got all the codes that you require, press Return twice.

TEXT > EXPAND
	If you have loaded a text file that was created with a different 
text editor, there is a good chance that there will be some strange 
characters appearing in the text. These are Tab symbols and will be 
displayed as little "clock face" symbols. To change these symbols to 
the appropriate number of spaces, select this option. If the file is lar- 
ge there will be a small delay while the expansion is done.

TEXT > TO UNIX, TO ST/PC
	These options are for converting the text in the editor between 
the two commonly used formats and are not important for most users. 
If the file is large there will be a small delay while it is converted. 
Unix text files have a single linefeed "\n" at the end of each line, 
whereas the ST and the PC have a carriage return "\r" and a linefeed. 
So now you know.

BLOCK > SET START, SET END, CLEAR MARKS
	These options set the start and end of a text block. Text blocks 
are shown shaded on screen and may be cut and copied around the 
text file. The "Clear marks" option de-marks the block, making the 
display look tidier.

BLOCK > CUT, COPY
	These two options copy the marked block of text to a buffer in 
memory, ready for you to paste it somewhere else in the text, or save 
it to disk, or print it out. The only difference is that the "Cut" option 
deletes the block from the text after it has been copied to memory.

BLOCK > PASTE
	This option "pastes" the block that you copied to memory using 
one of the previous two options, into the text at the cursor position. 
The memory buffer is not cleared after the paste, so you can paste 
more copies of the block into the text at different positions.

BLOCK > DELETE
	This option deletes the marked block from the text, in much the 
same way as the "Cut" option, except the block is not saved in any 
memory buffer. It is just deleted and lost forever.

BLOCK > PRINT, SAVE
	These two options print the marked block to the printer, and sa- 
ve it to disk as a text file, respectively. The "Print" option is useful 
for printing out sections of your FBML program that you suspect to 
contain bugs.

CLIP > PRINT,SAVE, CLEAR
	These three options concern the area of memory that the mar- 
ked block is copied into when you select either the "Cut" or "Copy" 
option. The "Print" option prints out the contents of the memory buf- 
fer. The "Save" option saves it to disk as a text file, and the "Clear" 
option simply deletes it, freeing the memory that it occupied.

RUN
	This option is the most important one on the menu, it runs your 
FBML program. The program will run in the same window as the edi- 
tor, so it is wise to ensure that the window is the largest size that it 
can be.
	You can break into your program while it is running by press- 
ing both "shift" keys simultaneously. The alert box that appears of- 
fers you the choice of resuming program execution, returning to the 
editor at the line where you left it or the line that was executing 
when you pressed the break keys.

THE LANGUAGE

	FBML is a subset of the BASIC programming language known 
and loved by enthusiasts everwhere ! It is very structured in that it 
neither has nor needs line numbers or "goto" statements. It supports 
local and global variables, procedures that may take and return mul- 
tiple values and has numerous control and conditional structures.

VARIABLES
	Variables in FBML are "stongly typed". This means that each 
one has its own distinct type and only a very limited amount of con- 
version between types is possible. You must "declare" any variable 
before you can use it. This is done in the following general format:

type name1,name2,name3 ...

	Where "type" is one of the available variable types, and the 
names of the variables must start with a letter and may consist only 
of letters, numbers and the underscore character ("_"). The maximum 
length of a variable name is 20 characters and FBML does distin- 
guish between upper and lower case letters. The available types are:

int		Signed integer in the range -32768<=n<=32767
uint		Unsigned integer in the range 0<=n<=65535
long		Signed long integer in the range 
-2147483647<=n<=2147483646
ulong		Unsigned long integer in the range 0<=n<=4294967294
real		64-bit double precision floating point "real" number
string		A text string, such as "Hello world"
dbase		A database
record	A record in a database
field		A field in a database

	Since all internal calculations in FBML are done in "real" for- 
mat, there is very little to gain, in terms of speed, by using numeric 
types other than "real". Variables may be arrayed. For instance...

int i[10]

	...declares an integer array, i, with ten elements. These ele- 
ments are referenced from 1 through to 10, ie, i[1], i[2], ... , i[10]. By 
default all variables are set to zero when they are declared. You can- 
not assign a value to a variable at the same time as you declare it. 
This must happen on a different line. For instance:

real r
r=5
print r

	Typing this in and running it will produce the obvious result of 
"5" appearing on the screen. In this example I chose to assign "5" to 
"i". You can, in fact, assign any standard FastBase formula to a vari- 
able. For example...

real r
r=@cos(@pi)
print r

	...would print "-1", as expected. Several new functions are 
available for you to use in formulae. As you will find out, they provi- 
de the key to accessing the data in your database. Here is a list of 
those additional functions, together with their meaning:

@dbase("name")		Returns a "dbase" variable that refers to the 
requested database. Naturally, "name" could be 
any nested formula that returns a "string" type 
variable.

@inkey(n)			Wait for a keypress for no longer than "n" mil- 
liseconds. If "n" is zero, inkey will wait forever 
for the keypress. The value retuned is the nu- 
meric code of the key pressed, or -1 if the 
function times out.

@record(db,n)		"db" is a variable of type "dbase", and "n" is 
the number of the record in the database that 
you want. A variable of type "record" is retur- 
ned.

@field(db,"name")		"db" is a variable of type "dbase", and "name" 
is the name of the field that you want. A vari- 
able of type "field" is returned.

@data(db,rec,fld)		"db" is a variable of type "dbase", "rec" is a 
variable of type "record" and "fld" is a variable 
of type "field". This function returns the actual 
data in the requested record and field. @data is 
very frequently used.

@records(db)		"db" is a variable of type "dbase", and it re- 
turns the number of records in that database. 
This is often used to control a loop that looks 
through each record in a database.

@winw			Returns the width of the program window
@winh			Returns the height of the program window
@cw				Returns the width of a single character
@ch				Returns the height of a single character

@selected(rec)		"rec" is a variable of type "record". This func- 
tion returns 1 if the record is "selected" or 0 if 
it is not.

@isloaded("name")	"name" is a text string that matches the name of 
the database that you are looking for. 1 is re- 
turned if the database is loaded, and 0 if it is 
not.

@today			Returns the numeric equivalent of todays date. 
The number is the number of days that have 
elapsed since 1-1-1900. This number is compat- 
ible with the format used by Lotus 1-2-3.

@gdos			If GDOS is present then 1 is returned, else 0 is 
returned.

@availfonts			Returns the number of fonts available. If GDOS 
is not present then 1 is always returned.

	Variables remain in existence until you explicitly destroy 
them, or they go out of scope. Any variables declared inside a proce- 
dure are local to that procedure and are lost when the procedure re- 
turns. This is explained further in this paper when procedures are ex- 
plained. To explicitly destroy a variable use the "destroy" command, 
thus:

destroy name1,name2,name3...

	The named variables will be forgotten completely and may be 
redeclared further in the program. Remember that you can declare 
and destroy variables anywhere in your program, not just at the start.

CONTROL STRUCTURES

	There are numerous commands available in FBML that control 
the flow of your program, and all have been seen before in other lan- 
guages.

REPEAT ... UNTIL
	The general structure of the "repeat-until" loop is:

repeat
  <program statements>
until <condition>

	The program will do nothing when it firsts sees the "repeat" 
command except note it's position. When the "until" command is en- 
countered the following formula is executed and, if its result is not 
zero, execution resumes at the line following the "repeat". Otherwise 
execution continues past the "until" command. "repeat-until" loops 
may be nested to a finite depth, currently set at 15. The following ex- 
ample prints out the numbers 1 to 10.

int i
i=1
repeat
  print i
  i=i+1
until i=11

WHILE ... WEND
	The general structure of the "while-wend" loop is:

while <condition>
  <program statements>
wend

	This is similar to the "repeat-until" loop except that the condi- 
tion is tested at the top of the loop, rather than the bottom. This 
means that the loop may never execute at all if the condition evalua- 
tes to zero the first time it is encountered. "while-wend" loops may 
be nested to a finite depth, currently set at 15. The following examp- 
le prints the numbers from 1 to 10.

int i
i=1
while i<11
  print i
  i=i+1
wend

FOR ... NEXT
	The "for-next" loop is probably the best known flow-control 
structure that there is, and this is its format:

for <assignment>,<condition>,<assignment>
  <program statements>
next

	<assignment> means that this must be of the form 
"variable=formula". <condition> is simply a formula that must eva- 
luate to non-zero for the loop to continue. The "for-next" loop may 
not execute at all if the condition evaluates to zero the first time it 
is encountered. "for-next" loops may be nested to a finite depth, cur- 
rently set at 15. The following example prints out the numbers from 1 
to 10:

int i
for i=1,i<=10,i=i+1
  print i
next

	The following, more realistic example, adds up the total of a 
field in a database. Assume the database to be called "sales", and 
the field that we want to sum is called "cost":

real i,total
dbase db
db=@dbase("sales")
for i=1,i<=@records(db),i=i+1
  total=total+@data(db,@record(db,i),@field(db,"cost"))
next
print "Total cost=";total

CONDITIONAL COMMANDS

	Conditional commands are essential to any language, they al- 
low you to make choices based on conditions. FBML provides two po- 
werful conditional constructs.

IF ... [ELSE ...] ENDIF
	If-else-endif statements are the simplest form of conditional 
choice available within FBML, and the two possible forms are:

if <condition>
  <program statements>
endif

if <condition>
  <program statements>
else
  <program statements>
endif

	If the condition after the "if" evaluates to anything other than 
zero, the following statements are executed. Otherwise execution 
continues after the "endif", in the first form, or the "else" in the se- 
cond form. Each "if" always has a matching "endif". "if" statements 
may be nested to a finite depth, currently set at 20. The following ex- 
ample prints out the even numbers between 1 and 10:

int i
for i=1,i<=10,i=i+1
  if i/2=@int(i/2)
    print i
  endif
next

	This next example prints out the even numbers between 1 and 
10, and displays each odd number as the appropriate number of dots:

int i,j
for i=1,i<=10,i=i+1
  if i/2=@int(i/2)
    print i
  else
    for j=1,j<=i,j=j+1
      print ".";
    next
    print ""
  endif
next

SWITCH ... CASE
	In addition to the simple "if-else-endif" construct, FBML pro- 
vides an advance selection mechanism, borrowed from the "C" pro- 
gramming language. The general form is:

switch <formula>
  case <formula 1>
    <program statements>
  case <formula 2>
    <program statements>
  .
  .
  .
endswitch

	This construct allows you to select from a whole range of poss- 
ible outcomes from a given formula. As always, this is best illustra- 
ted by example. The following program prints out the numbers from 1 
to 5 in words, and 6 to 10 as numbers:

int i
for i=1,i<=10,i=i+1
  switch i
    case 1
      print "one"
    case 2
      print "two"
    case 3
      print "three"
    case 4
      print "four"
    case 5
      print "five
    case i
      print i
  endswitch
next

	In the above example I used only one statement per "case". You 
can have as many statements as you like, including further "switch- 
case-endswitch" constructs. "switch-case-endswitch" constructs 
may be nested to an infinite depth. Notice the trick I used to catch 
the numbers 6 to 10. The last "case" statement will always match the 
test since its formula is the same as that in the "switch". However, 
this "case" will never be encountered for the numbers 1 to 5 because 
of the previous "case" statements, ensuring that only the numbers 6 
to 10 are matched. This can be a very useful trick.

GRAPHICS COMMANDS

	Since FastBase is a very graphical database you might expect 
there to be a wealth of graphics facilities in FBML, and you would 
be correct. All graphics commands work on a co-ordinate system that 
has its origin in the top left of the window. X-coordinates extend to 
the right, and y-coordinates extend to the bottom of the window. 
When you first run your program, or execute a CLS command, the 
current graphics position is reset to this point.

	All graphics commands, and the print statement operate at this 
current position. You can move the current position manually, and 
some commands move it automatically. The available graphics com- 
mands are described below.

MOVE
	The "move" command allows you to manually move the current 
graphics position anywhere in the window. The format is:

move x,y

	The current graphics position is moved to the requested posi- 
tion. It is up to the user to ensure that the requested position lies 
within the program window. The behaviour of FBML when given ne- 
gative and very large co-ordinates is undefined.

PLOT
	The "plot" command places a single point on the display. If no 
co-ordinates are specified then the point will be plotted at the cur- 
rent graphics position, otherwise the graphics position is moved to 
the requested point before it is plotted. For example:

plot
plot 100,100

	The first example plots a point at the current graphics position, 
whereas the second example plots a point at the position x=100, 
y=100.

LINETO
	This command draws a line from the current graphics position 
to the point specified after the command. For example:

move 100,100
lineto 200,200

	This simple example draws a line from (100,100) to (200,200) 
using the current line style and attributes. Changing the line style is 
explained further in this manual.

CIRCLE
	This command draws a filled circle at the current graphics po- 
sition. You need only specify the radius of the circle. For example:

move 100,100
circle 50

	This example will draw a filled circle with its centre at 
(100,100) and with a radius of 50. See further in this manual for 
changing the fill pattern.

BAR
	The "bar" command draws a filled bar with the specified width 
and height, and filled with the currently selected fill pattern. For ex- 
ample:

move 100,100
bar 40,60

	This example will draw a bar with its top left at (100,100) and 
with a width of 40 and a height of 60. This command is useful for 
drawing bar charts.

ELLIPSE
	The "ellipse" command draws a filled ellipse with its centre at 
the current graphics position, and with the selected 'x' and 'y' radii. 
For example.

move 100,100
ellipse 100,50

	This example draws an ellipse with its centre at (100,100) and 
with an x-radius of 100 and a y-radius of 50.

ELLPIE, ELLARC
	These two commands draw part of an elliptical pie and part of 
an elliptical-arc, respectively. The only difference between the two 
is that "ellpie" fills its pie-shaped segment with the current fill pat- 
tern, and "ellarc" only draws the outer arc of the ellipse. The general 
formats are:

ellpie xradius,yradius,startangle,endangle
ellarc xradius,yradius,startangle,endangle

	The x-radius and y-radius are self explanatory. The starting 
and ending angle govern where the pie-segment or arc is to appear 
within the circle. These angles should be specified in degrees be- 
tween 0 and 3600. No that isn't a typing error, having a range of 0 to 
3600 allows more precise control of the position down to 1/10 of a 
degree. For example:

move 100,100
ellpie 50,50,0,900

	This example draw a circular pie segment that is precisely a 
quarter of a circle. Notice that the zero position is at "3-o'clock" and 
the angles extend anti-clockwise. Using angles greater than 3600 can 
cause unusual, but sometimes desirable results.

FILL
	This command does a "flood-fill" from the current graphics po- 
sition, in the current fill colour and position. A flood fill continues 
in all directions until it either hits the border of the window or a 
point on the screen with a different colour to the one where the fill 
started. This can be used to replace one area of colour with another. 
For example:

move 200,200
ellarc 100,150,0,3600
fill

	This simple example draws the outline of an ellipse and then 
fills it with the current fill patten and colour.

PRINT
	The print command is probably the most well known of all tho- 
se in the BASIC language. The FBML implementation is very simi- 
lar, the general format is:

print <formula>,<formula> ...

	The formulae used in the print command can be any valid 
FBML formula that yields either a number or a string as its result. 
The formulae to be printed may be separated by a number of different 
characters, each one having a different meaning:

,	[comma]		Print the next argument at the start of the next 
line
;	[semi-colon] 	Print the next argument directly after the last 
one
'	[apostrophe]	Prints the next argument on the next line, but at 
the same x-position as the previous argument

	The following example illustrates all the possible separators:

move 100,0
print "hello"'"it is 3:00";"pm","now"

	This yields output something like this:

					hello
					it is 3:00pm
now

CLS
	This command simply clears the screen and resets the current 
graphics position to the top left corner of the screen. "cls" does not 
take any parameters.

STYLE SETTING COMMANDS

	Just about all the graphics commands described in the previous 
section can have their styles changed somehow. Lines and fills can 
have their patterns changed. Text can have its font and size changed, 
and everything can have its own colour.

FONT
	If you have GDOS loaded then you can select which font the 
"print" command is to use with this command. The format is simple:

font <number>

	Where the number is a formula that yields a number between 1 
and the number of fonts available. You can determine this number 
with the "@availfonts" function.

FONTSIZE
	This command is used to set the size, in points, of the text that 
will be printed with the "print" command. The format is:

fontsize <number>

	Even if you do not have GDOS loaded you can change the size 
of the default system font with this command.

FONTCOLOUR
	This command is used to change the colour of the text printed 
with the "print" command. The format is:

fontcolour <number>

	The number can be anything between 0 and 15. Users of mono- 
chrome monitors can only use colours 0 and 1. Medium resolution 
users can use colours 0 to 3, and low resolution users can use all the 
available colours.

FONTEFFECTS
	This command is used to specify certain special effects to be 
applied to text, such as underlining, bold, italic etc. The format is:

fonteffects <number>

	The number represents the styles that you want, and is calcula- 
ted by adding up the numbers of the styles that you want, given be- 
low:

1	Bold
2	Lightened, or greyed text
4	Italics
8	Underlined
16	Outlined

	For example, if you wanted bold underlined text then you would 
specify a number of 1+8=9.

LINESTYLE
	You can change the pattern of the line that is used by the "li- 
neto" command using this command. The format is:

linestyle <number>

	The number is calculated by writing down a 16 digit binary 
number that represents the style of the required line. A 1 digit indi- 
cates "on", and a zero indicates "off". Those sixteen digits will be 
repeated along the line. Since you cannot give "linestyle" a binary 
number directly, you must convert it to decimal or hex. For instance, 
if you wanted a dotted line you would write down the following bi- 
nary number...

0101010101010101

	...When converted to decimal this gives the number 21845 
($5555 in hex). So you would then execute the following command:

linestyle 21845

LINEWIDTH
	You can set the width of a line using this command. The gene- 
ral format is:

linewidth <number>

	The number that you specify should be an odd number between 
1 and whatever the system is currently capable of displaying. Under 
TOS 1.2 this is about 45.

LINECOLOUR
	You can set the colour of lines using this command. The colour 
restrictions that were pointed out under the "fontcolour" command 
also apply to "linecolour". The general format is, of course:

linecolour <number>

FILLSTYLE
	You can set the style that is used to fill objects such as the 
"bar" or the "ellipse" using this command. The general format is:

fillstyle <number>

	The number can be any whole number between 1 and 37 inclu- 
sive. The available fills include a variety of shaded, patterned and 
hatched fills. One of the example programs on the disk displays all 
the available fills and their numbers.

FILLCOLOUR
	The colour of the fill that is used to fill objects can be set 
using this command. The same restrictions that were described under 
the "fontcolour" command apply equally well "fillcolour". The gene- 
ral format is:

fillcolour <number>

SCROLLOFF
	This command is used to stop the display automatically scroll- 
ing upwards when printing reaches the bottom of the screen. It is 
useful when you want to print some text in the lowest lines of the 
window and don't want the display to automatically move it upwards. 
There are no parameters to this command.

SCROLLON
	This command is used to re-enable display scrolling, and is 
simply the reverse of the above command. Display scrolling is enab- 
led by default when you first run your program. There are no parame- 
ters to this command.

NUMFORMAT
	When you print out a number using the "print" and "lprint" 
commands, that number may be formatted in any of the ways nor- 
mally allowed within FastBase. By default the number has no for- 
matting and just appears in a general format. To change the formatt- 
ing, you can use the command:

numformat <number>

	The "number" is calculated by deciding which formatting op- 
tions you want, from the list below, and then adding up the corres- 
ponding numbers. The available formatting options are:

1		Fixed decimal places, eg. 2.00
2		Insert Commas in large numbers, eg. 1,000,000
4		Display zeros as blank
8		Negative numbers in parentheses, eg. -300=(300)
16		Append a percentage symbol (%) and multiply the number by 
100, eg. 0.1=10%
32		Insert a currency string prefix (see "currency" command to 
set currency)
64		Show number as pseudo-graphic display of "*" symbols
128		Exponential, or "Scientifc" display, eg. 4.1e+3
256		Integer, no decimal places.
512		Append a suffix string (see "suffix" command to set suffix)

	For example, suppose you wanted to display a number with 2 
decimal places and a currency string prefix. You would look at the 
above table to locate the options you require. In this case they are 
numbered 1 and 32. Adding these numbers up gives the answer 33 
which is what you give to the "numformat" command.

CURRENCY
	The "numformat" option, described above, gives you the ability 
to display a currency string prefix before numbers. To set the cur- 
rency you use the "currency" command thus:

currency <string>

	The <string> formula must yield a string of no more than 5 cha- 
racters. Any characters after the initial 5 will be ignored. Two ex- 
amples are:

currency "US$ "
currency @right("US$ HK$ ",4)

	The first example sets the currency string to "US$ ", and the 
second to "HK$ ". Note the use of a simple formula to yield the string 
in the second example.

SUFFIX
	The "numformat" option, described above, gives you the ability 
to display a suffix string appended to numbers. To set the suffix str- 
ing you should use the "suffix" command thus:

suffix <string>

	The <string> formula must yield a string of no more than 10 
characters. Any characters after the first 10 will be ignored. A simple 
example would be:

suffix " km/h"

DPLACES
	The "numformat" option, described above, gives you the ability 
to display a number with a fixed amount of decimal places. To set the 
amount of decimal places to be shown, you should use the "dplaces" 
command like this:

dplaces <number>

	The <number> formula should give the number of decimal pla- 
ces that you require. For example:

numformat 33
currency "$"
dplaces 2

	This is a very common sequence of actions that sets the num- 
bers to be displayed with two decimal places and a currency prefix, 
which in this case is "$".

PROCEDURES

	Procedures are a very important feature of FBML. They allow 
you to put commonly used actions and routines in self-contained 
areas that may be called by the main program. Procedures are analo- 
gous to functions in "C", and subroutines in BASIC.

	There are three commands associated with procedures, and they 
are:

procedure <name> [<parameters>]
call <name> [<parameters, ...> : <variable, ...>]
return [ <variable, ...> ]

	The square brackets "[]" in the above general format indicate 
optionality, ie. the contents of the brackets may or may not appear. 
Let's take the simplest form first. To define a procedure that sets the 
number format to "currency with two decimal places", one would de- 
fine a procedure something like this:

procedure numcurrency
  numformat 33
  currency "$ "
  dplaces 2
return

	That's all there is to it. Now, every time within your main pro- 
gram that you want to call the procedure you would use the line:

call numcurrency

	That example was the simplest possible. It took no parameters 
from the caller, and gave no results back. Let's look at a more com- 
plicated example that takes two numbers and prints the sum of all 
the integers between them:

procedure sum first,last
long total
  while first<=last
    total=total+first
    first=first+1
  wend
print total
return

	Now, suppose you want to print the sum of the integers between 
10 and 20, you would enter the following line in your program:

call sum 10,20

	This example introduces two new ideas. This procedure takes 
parameters, two of them to be exact. All you have to do is give them 
names after the procedure name, separated by commas. You do not 
have to say what type they are because FBML will give them the ap- 
propriate type when the procedure is called.

	The other concept introduced in this example is that of "local 
variables". A local variable is one that is known only to the procedu- 
re in which it is defined. The local variables in the above example 
are "first", "last" and "total". When the "return" statement is en- 
countered, these variables are destroyed. You may give local variab- 
les the same name as global variables (ie. those not defined in proce- 
dures). When you refer to a local variable that has the same name as 
a global variable, the local variable is used.

	The last idea to be introduced is that of returning values from 
procedures. The following complete example takes a number and re- 
turns it's square, and it's square root:

real square, sqroot
call calc 3:square,sqroot
print "3 squared=";square,"root 3=";sqroot
end

procedure calc value
return value*value,@sqr(value)

	Notice the way we use a colon ":" character to separate the va- 
lues to be passed to the procedure in the "call" statement from the 
names of the variables to take the return values. The only other 
change is the list of return values, separated by commas, after the 
"return" statement. We can summarise the rules for using procedures 
in a list:

1.	If you want to pass parameters to a procedure, list them after 
the "call" statement and give them names when you define the 
procedure.

2.	If you want to return values from the procedure, list them after 
the "return" statement. Each time you call the procedure you 
must give a corresponding list of variables after the colon ":" 
character that are to receive the return values.

3.	Place all your procedure definitions at the end of the program, 
and separate them from the main program by an "end" state- 
ment. An error will be reported if program execution runs into a 
procedure definition.

MISCELLANEOUS COMMANDS

LPRINT
	The "lprint" option is much like the "print" option except that 
its output goes to the printer, rather than the screen. There is one 
difference, however, concerning text. When you print a text string to 
the printer it may contain control codes. These codes are indicated 
by a backslash ("\"), followed by at least one other character. The 
available codes are:

\r		Carriage return
\n		new line
\xdd		Hexadecimal number "dd"
\\		A single backslash

	For example. If you have an Epson compatible printer the fol- 
lowing two statements will put it in Underline mode, and take it out 
of Underline mode, respectively.

lprint "\x1b-1"
lprint "\x1b-0"

INPUT
	The input command is used to request input from the user. This 
input is then assigned to a variable for future use by the program. 
The general format is:

input "prompt",variable,validator

	The "prompt" is a text string, of no more than 20 characters, 
that is used as a visual prompt to the user. This normally indicates to 
the user what he or she is expected to type. "variable" is simply the 
name of the variable that the data is to be assigned to. "validator" is 
a single character that indicates what type of characters the user is 
allowed to type in. The available validators are:

9	Only digits 0..9
A	Only upper case letters A..Z or spaces
a	Only upper and lower case letters or spaces
N	Only digits 0..9 or upper case letters or spaces
n	Only digits 0..9 or upper and lower case letters or spaces
F	All valid TOS filename characters and ?*:
p	All valid TOS filename characters and ?*:\
P	All valid TOS filename characters and :\
X	All characters are allowed

	The following example requests the user to input a number, and 
assigns it to the variable "number". The user is restricted to typing 
digits 0..9.

int number
input "Enter a number",number,9
print "You typed: ";number

	The final example asks the user to enter some text, and then 
assigns it to the string variable "text". The user is allowed to type 
any characters on the keyboard.

string str
intput "Enter some text",str,X
print "You typed: ";str

LOAD
	This command is used to load a database from disk. It is simple 
to use, and takes the form:

load "filename"

	The "filename" may be a formula that yields a text string as its 
result. If you are going to use the "load" command it is usual to sur- 
round it with an "if" statement that checks to see if the database is 
already loaded. For example:

if @isloaded("the world")=0
  load "world.fb"
endif

	Remember that the "load" command uses the full disk filename 
of the database, and the @isloaded function uses the actual name of 
the database itself.

END
	This command simply stops program execution when encounte- 
red. You normally use the "end" command to stop the program runn- 
ing into procedure definitions.

REM
	When this command is encountered everything else until the 
end of the line is ignored. The "rem" command is used to add com- 
ments, or REMarks, to the program.

SORT
	Since most FBML programs will involve you looping through 
the contents of a database, it is often desirable to have the database 
sorted into a particular order. To save you the effort of using the 
"Sort" option from the "Process" menu, the "sort" command has been 
provided. It offers all the functionality of the main sort option, and 
has the general syntax:

sort dbase,primary,ascending1[,secondary,ascending2]

	Parameters shown in square brackets are optional. The "dbase" 
parameter is a variable of type "dbase", and indicates the database 
that you want to sort. Both "primary" and "secondary" (if supplied) 
are text variables that contain the name of the field that you want to 
sort by. "ascending1" and "ascending2" (if supplied) are numbers 
that indicate whether the data is to be sorted in ascending or des- 
cending order. If the numbers are anything but zero then the data is 
to be sorted into ascending order, if they are zero then the data will 
be sorted into descending order.

	This first example would sort the example database "The 
World" into ascending order of name:

sort @dbase("The World"),"name",@TRUE

	This further example would sort the same example database in- 
to ascending order of adult literacy, and, where the adult literacy ra- 
tes are the same, those records are sorted by descending order of na- 
me:

sort @dbase("The World"),"adult literacy",@TRUE,"name",@FALSE

AND FINALLY
	Whilst this paper covers all the commands and their syntax, it 
does not cover programming style or design. This is really up to you. 
If, like me, you like to learn by example then there are numerous ex- 
ample programs in the "PROGRAMS" folder on the supplied disk. I 
would recommend that you try all of these programs, and perhaps 
adapt them to your needs.
