
                           *** NOTE ***

NEWAPP.SCR and DOSLIB.SCR are subject to change (really!)  There is
no guarantee - or intent - that future versions will remain backward
compatible.  When backing up or distributing application source code,
be sure to include DOSLIB.SCR as a future version may no longer be
compatible.

                           Introduction

NEWAPP is a skeletal program that allows users to quickly develop
an DOS application.  It provides often needed tasks including error
handling, command-line parsing, file operations, buffered I/O, help
screen, number and string functions.

NEWAPP comprises two parts:

  NEWAPP.SCR   skeletal main program
  DOSLIB.SCR   function library

NEWAPP is supplied as a functioning program which may be turnkeyed.
Styled as a typical DOS command-line application it demonstrates
how the various tasks are integrated to form a functioning program.
Making NEWAPP perform a useful task can be as easy as adding one
line e.g. to turn NEWAPP into a filecopy utility just uncomment
line 5 of the definition (RUN) and recompile!

DOSLIB is a library of forth and MS-DOS functions in source form.
While its primary role is support for NEWAPP, DOSLIB can be used
by any application.  Library functions are organized as 'modules'
which can be loaded on demand.

New users are encouraged to first examine NEWAPP and understand how
it works before attempting to build their own application.  The
following notes should help with some of the less obvious aspects.
Unless otherwise stated all screen references refer to NEWAPP.SCR.

First, an explanation of the function +IS which is commonly used by
NEWAPP.  +IS is similar to IS but instead of replacing the existing
behaviour of a DEFERed word, it chains in a new action.  When the
deferred word is eventually executed, all actions in the chain will
be performed beginning with the most recently added.

1. Setting the options

   Screen 1 defines the title of the program, version, date and name
   for the turnkey executable.

   The programmer may optionally specify the top of memory address or
   LIMIT for the application.  This is useful for environments where
   available memory is limited.  The calculation assumes 256 bytes
   for the PAD and data stack plus any RESERVE bytes tallied during
   compilation.  Typically RESERVE is the count of bytes ALLOTed at
   run-time.  If the option is not enabled then LIMIT will default
   to the compiler's top of memory address (usually $FFF0 for MS-DOS
   or CCP/BDOS base for CP/M).

   Screen 2 loads the remainder of the application.  It also defines
   and sets the action for several deferred words which are explained
   below.

   ONSTART is a deferred word.  Its function is to perform any system
   initialization that may be required before the application begins.
   Typically these will be "run once" tasks such as alloting buffers
   or initializing memory management functions.  Actions are added to
   ONSTART via +IS.

   SET-IO is a deferred word that sets the console input/output method.
   By default SET-IO is set to BIOS-IO.  Users needing DOS console I/O
   redirection can do so either by selectively surrounding words with
   DOS-IO ... SET-IO  pairs or by uncommenting the line:
   ' DOS-IO IS SET-IO.

   The DOSLIB disk read/write routines include a keyboard test.  If
   ESC CTRL-C or CTRL-BREAK keys are detected, the user is given an
   opportunity to abort the program.  The feature may be disabled by
   commenting out the line: ' (?BREAK) IS ?BREAK.

   ONERROR is the application's top-level error handler.  It intercepts
   exceptions before the system's error handler deals with it.  ONERROR
   permits the application to perform any necessary 'clean-up' tasks
   before aborting.

   ONERROR is a deferred word whose action is modified with +IS.  An
   example is the DOSLIB 'files' module which extends ONERROR to
   automatically close the default files should an error occur.

   Note: If a function performed by ONERROR itself generates an exception
   then the original exception that caused ONERROR to execute is likely
   to be masked.

2. Loading DOSLIB modules

   Screen 3 of NEWAPP.SCR initializes the DOSLIB library then proceeds
   to load the named modules.  This screen contains the support modules
   typically needed by NEWAPP based applications. If your application
   does not require a particular module and you wish to conserve space,
   then you may comment out the line on which the module's name appears.

3. Default files

   The default files module simplifies much of the drudgery associated
   with file handling e.g. display of filenames when opening, overwrite
   checking, error messages when reading or writing files etc.

   One input and one output file are supported - sufficient for most
   applications.  All the usual file read/write functions are provided
   including file position and reposition.  Output file overwrite
   checking is enabled by default.  It may be turned off by uncommenting
   the line:  WRTCHK OFF  on screen 2.

   When an application aborts as a result of a fatal error, the default
   files will be automatically flushed and closed.  If it is desired to
   delete the default output file, it can be done by uncommenting the
   line on screen 2:  ' DELOUTFILE +IS ONERROR

   FLUSHWRITE is an optional function that works similarly to FLUSH-FILE.
   Data written to the default output file is forced to disk updating the
   directory.  Buffered output, if loaded, is also flushed.

4. Buffered files

   This is an optional extension to the default files and allows reading
   and writing one character at a time.  For speed buffers are used to
   hold the data.  Buffer refill and flushing is automatic and requires
   no user intervention.  The default buffer size is 512 bytes and
   is given by /INBUF /OUTBUF respectively.  Buffers are statically
   allocated at compile-time but may be ALLOTed at run-time if desired.


