
NEWAPP is a skeletal program that allows users to quickly develop an
MS-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 MS-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.

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

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

   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 fully, 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.

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

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

   Note: If a function performed by ERRFIX itself generates an exception
   then the original exception that caused ERRFIX to execute is likely
   to become 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, closing of files
   on error 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, the default files will be automatically
   flushed and closed.  If it is also desired to delete the default
   output file, it can be done by uncommenting the line:
   ' DELOUTFILE +IS ERRFIX  on screen 2.

4. Buffered files

   This is an optional extension to the default files and allows the
   reading and writing of one character at a time.  For speed, 1024
   byte buffers are used to hold the data.  Buffer refill and flushing
   is automatic and requires no user intervention.

   Note: When using buffered output, it is recommended (though not
   mandatory) that FLUSHWRITE is performed before executing CLOSEFILES
   CLOSEOUTFILE or REPOSOUTFILE.  While these latter functions will
   automatically do a flush, errors are not reported.  By preceding
   them with FLUSHWRITE users will be notified of any errors should
   they occur.

5. History

-  1.1  Renamed +DEFER to +IS.  OPENOUTFILE renamed to MAKEOUTFILE;
        new OPENOUTFILE attempts to open named file for output and
        aborts if not found.

-  2.0  Split into main program NEWAPP.SCR and support library
        DOSLIB.SCR.

   Hereafter all version numbers and changes refer to DOSLIB.

-  1.2  File functions revised to use and support "handles".  Several
        low-level file functions renamed.  CLOSEFILES is DEFERed.

-  Add ONSTART to NEWAPP.

