5. The creation of standalone Programs
--------------------------------------
    ARMForth provides an extremely powerful method of creating standalone
programs i.e. programs that can be used without the (visible) ARMForth
system. Using this facility new customised versions of ARMForth can also be
created to suit the user.

5.1 CREATE-PROG
---------------
    The CREATE-PROG word is available to create standalone programs. The
action of this word is dependent on a parameter which takes a value between
1 and 5 inclusive. It takes other parameters according to the "action"
parameter. The interface specification of CREATE-PROG is

       <action dependent params> action CREATE-PROG

Each of the action parameters is now described.

    Action = 1
    ----------
        This mode creates a new ARMForth system. One parameter is needed on
the stack. This is the address of a buffer which contains information about
the main terminal window in the form that "Wimp_CreateWindow" expects. This
allows customised windows to be used as the main ARMForth window. The
complete specification of this mode is

       wind_buffer_addr 1 CREATE-PROG

    Action = 2
    ----------
        This mode allows a standalone program to be created which can make
use of the ARMForth window. It allows programs which have a textual
interface to be easily created without the programmer having to be concerned
with the management of windows. The standalone program is run as a RISCOS
task. Upon entry to the program the window appears, and any output in the
program going via the normal ARMForth output words will cause its output to
be placed in this window. The ARMForth icon will not appear. Clicking on the
'quit' icon in the terminal window will cause the task to be terminated. The
complete specifiection of the interface for this mode is

       win_title_addr task_title_addr entry_addr win_buf_addr 2 CREATE-PROG

    win_title_addr is the address of a string which gives the title to
appear in the main window when the program is run.

    task_title_addr is the address of a string which gives the name of the
task (it appears in the task manager window)

    entry_addr is the entry address of the program. For example, if MAIN is
the word which starts the program, the entry address of MAIN is found by the
command sequence

       ' MAIN

    Notice the entry point is just the code field address of the word.

    win_buf_addr is the address of a buffer containing information in the
form used by "Wimp_CreateWindow"

    Action = 3
    ----------
        If action is 3 then a standalone program is created which does not
have any initial windows available to it. It is used in programs which want
to perform all their own window management. All output in these programs
must be achieved by the mean of customised output routines, since EMIT and
TYPE will fail as there is no window for them to output to. There is no
checking done by EMIT and TYPE, so the program will simply crash if these
words are used. The interface specification is

       task_title_addr entry_addr 3 CREATE-PROG

    task_title_addr and entry_addr are the same as in the previous section.

    Action = 4
    ----------
        This mode is used to produce a customised ARMForth system which does
not run in the Wimp mode, and does not run as a task. Upon starting up a
system created this way, Mode 0 is entered. As mentioned in section ????,
the Wimp mode cannot be entered from this situation by means of the word
WIMPS, since the program does not run as a task. This mode is provided for
those who prefer a simple "Arthur type" interface to their ARMForth system.
No extra parameters are required with this action, and the interface
specification is simply

       4 CREATE-PROG

    Action = 5
    ----------
        Again, action 5 creates programs that do not run as a task and enter
Mode 0 on startup, but it creates programs with customisable entry
addresses. The entry address is specified as an extra parameter. The
interface is

       entry_addr 5 CREATE-PROG

5.2 Discussion on CREATE-PROG
-----------------------------
    The total number of characters in the main window of the ARMForth system
cannot be more than the default number i.e. 78 * 300 = 23400. Within this
restriction, the aspect ratio may be as desired.
    The maximum lengths of the window and task titles are set by RISCOS.
