The MACRO BASIC and LINKEDT utilities.
=====================================

The MACRO BASIC and LINKEDT programs are designed for users who wish
to
extend infinitely the processing ability of the BBC machine. By this,
we
mean that users may now define their own language and commands to use
when
they develop their programs. Furthermore, they may even set up
libraries
of their favourite routines and have these routines incorporated into
new
or old programs instantly, without the hassle of recoding or merging
files. As users may now define their own commands (or macros) very
simply
by using MACRO BASIC, they may even compile these macros into macro
libraries which they can then access every time they start work on a
new
project. Certain libraries are supplied free of charge with the
utilities,
and that includes a special macro library that will allow the user to
run
programs of infinite sizes by using virtual memory handling to page in
and
page out program segments and system utilities. MACRO BASIC and
LINKEDT
will work equally well with BASIC and/or machine code programs, and
the
virtual memory macros will also handle both BASIC and machine code
segmemts during paging.
                       
The MACRO BASIC utility is used to  define  user  macros, implement
the
user's own coding standards, and is the starting point for the
inclusion
of system macros including the virtual memory handler. MACRO BASIC
will
accept several very simple directives, and all the BBC BASIC syntax,
including the assembler conventions. The directives special to MACRO
BASIC
are summarised as follows:

  #DEFINE macid  = macdef
  #MACRO  macid  = macdef
  #LOAD   macfile
  #SAVE   macfile
  #DELIM  x
  #CLEAR

The #DEFINE directive is use to define a macro. An example of a simple
macro is '#DEF YELLOW = CHR$131'. If MACRO BASIC has processed the
macro
just described, then every time MACRO BASIC encounters 'YELLOW', a
macro
substitution will be performed, whereby MACRO BASIC will turn the
macro
'YELLOW' into its definition, 'CHR$131'. Imagine how much more
readable
programs would be if they had statements like 'PRINT YELLOW;"How are
you?'
as opposed to seeing 'PRINT CHR$131;"Text"', etc.

Macros, of course, can be made more useful if you can specify your own
variable parameters to them. As such, up to 10 user-definable
parameters
are allowed within each macro definition: %0% through to %9%. An
example
of using macro parameters is a macro defined as follows:
  
  #MACRO greet = PRINT YELLOW;"How are you today, %0%? How is %1%?"

If you now use the macro by coding 'greet FRED,JANE', MACRO BASIC will
turn
it into 'PRINT CHR$131;"How are you today, FRED? How is JANE?". Notice
that you may even use another macro within a macro, but take care that
a
macro does not invoke itself in a loop, as MACRO BASIC may not be able
to
resolve it past a certain degree. Note that the comma after the
parameter
FRED is very important as MACRO BASIC seperates the parameters by the
commas, although you may change the seperator or delimiter by using
the
#DELIM x command, where 'x' is your own delimiter. #DEFINE and #MACRO
are
exactly identical in operation, and the only reason for having 2 ways
of
defining macros is because you may wish to group macros without
parameters
by using #DEFINE and use #MACRO for macros with variable parameters.
If
you use a non-alphabetic character to begin a macro definition, you
must
preceed and terminate the definition by a delimiter, such as '/' or
'!',
etc. Eg. #DEF MASK = /&FF/.

If you have defined a lot of macros, it would be wasteful for MACRO
BASIC
to compile them out every time in your source, so to speed things up,
you
may use a #SAVE macfile command AFTER you have defined all your macros
in
one of your sources. The effect is that a more efficient, compact
version
of your macros will then be saved into 'macfile', which may then be
reloaded by another program by using #LOAD macfile. You may use #LOAD
to
load as many macros as the memory space for MACRO BASIC will allow.

If, for whatever reason you wish to remove all the macro definitions
in
store, just issue the #CLEAR directive. You may want to do this to
redefine certain macros differently in different parts of the same
program.

During a session with MACRO BASIC, you will see that it is possible to
invoke the link-editor from the MACRO BASIC command screen. This shows
the
powerful capability of these two utilities in tandem. Whereas MACRO
BASIC
allows you to define your own environment or language, LINKEDT
provides
the ability to draw on your past utilities and subroutines which you
may
have written to actually produce the whole executable program. Your
subroutines and utilities will have been organised in library files
which
LINKEDT will now search, and if LINKEDT finds that you require a
routine
which is not currently in your new program, it will incorporate it
into
your new program automatically. It does not matter if the routine
calls
other routines which call other routines, LINKEDT will make certain
that
all the required code will be included to make up a whole program,
provided that your libraries have been ordered properly. LINKEDT
requires
you to merely tell it what new program you are writing, and what the  
  
library file names are. If LINKEDT cannot resolve all the routines
required, it will warn you with an error message.

It may occassionally be required that you do not want to resolve all
the
routines in a program. This is the case when you wish to use the
virtual
memory management macros. Since you will only load in program segments
only as and when you require them, it would be pointless for LINKEDT
to
include them in the main program. As such, you may have to press
ESCAPE
during a linking session or use the '/' as a reply to the
request for a new library file name. LINKEDT will warn you that all
routines have not been resolved, and then terminate. The missing
routines
should have been defined in segment files, preferably not too large in
size, which the main program can then page in when it needs the
routine.
The segment files will usually contain only a main DEFPROC or DEFFN,
plus
a few other procedures or functions needed by the main procedure or
function in the segment file. These segment files will then get
overwritten by a new segment file when the main program decides to
page in
another routine, and so on.

Using the virtual memory management is simple: just include the macro
library 'M.VIRTUAL' in your source, and use the following macros
included
in the macro library:

  VIRTUAL_POOL nnnn
  DO routine,p1,p2,p3,p4,p5,p6
  HOLD routine
  FREE_POOL

The macro VIRTUAL_POOL must be the first line in your program, and the
figures 'nnnn' defines the maximum size of your largest virtual
segment
file. The 'DO' macro actually pages in the segment file, if it is not
already in memory, and passes the 6 parameters to the routine. Please
ensure that your virtual routine will accept the 6 parameters whether
it
actually needs them or not. If you decide for whatever reason to
freeze a
segment in memory, you can make it permanently resident in memory
after
paging in by issuing a 'HOLD' macro. The 'FREE_POOL' macro will free
all
the routines held by the 'HOLD' macro. Be aware that if your routines
decide to 'HOLD' themselves in memory, that the VIRTUAL_POOL space is
sufficient for the inclusion of other segments on top of the held
segment.
A held segment may, of course, also page in program segments on top of
itself.

For simple development purposes, and to allow the use of a word
processor
to format the source file when printing, MACRO BASIC will accept its
input
from a normal ASCII file such as that produced by WORDWISE, etc. The
link-editor utility will access its files in normal BASIC format; ie,
as
produced by the BBC BASIC editor, as speed is a requirement when
searching
through large libraries.