Documentation for WBStart V2.0                                13-Mar-1996


   Permission is granted to make and distribute verbatim copies  of  this
manual provided the copyright  notice  and  this  permission  notice  are
preserved on all copies.

COPYRIGHT

   Copyright (C) 1991-96 Stefan Becker

   No program, document, data file or  source  code  from  this  software
package, neither in whole nor in part, may be included or used  in  other
software packages unless it is authorized by a  written  permission  from
the author.


NO WARRANTY

   There is no warranty for this software package.  Although  the  author
has tried to prevent errors he can't guarantee that the software  package
described in this document is 100% reliable. You are therefore using this
material at your own risk. The author cannot be made responsible for  any
damage which is caused by using this software package.


DISTRIBUTION

   This software package is freely distributable. It may be transfered to
any media which is used for the distribution of free software like Public
Domain disk collections, CDROMs, FTP servers or bulletin board systems.

   In order to ensure the integrity of this software package distributors
should use the original archive file WBStart2_0.lha (file name on Aminet:
WBStart.lha). The author cannot be  made  responsible  if  this  software
package has become unusable due to modifications of the archive  contents
or of the archive file itself.

   There is no limit on the fee taken by distributors, e.g. for the media
costs of floppy disks, streamer tapes or compact discs, or the process of
duplicating. Such limits have proven to be harmful to the idea of  freely
distributable software, e.g. the software package was removed instead  of
reducing the price of a floppy disk below the limit.

   Although the author does not impose any limit on these fees  he  would
like to express his personal opinions on this matter:

   * This software package should be made available to everyone  free  of
     charge whenever this is possible.

   * If you have purchased this software package under normal  conditions
     from a Public Domain dealer on a floppy disk and have paid more than
     5DM or US $5 then you have definitely paid too  much.  Please  don't
     support this improper profit making  any  longer  and  switch  to  a
     cheaper source as soon as possible.


USAGE RESTRICTIONS

   No program, document, data file or  source  code  from  this  software
package, neither in whole nor in part, may be used on any  machine  which
is used

   * for the research, development, construction, testing  or  production
     of weapons or other military applications. This  also  includes  any
     machine which is  used  in  the  education  for  any  of  the  above
     mentioned purposes.

   * by people who accept, support or use violence against other  people,
     e.g. citizens from foreign countries.



I. What is the purpose of this software package?
================================================

WBStart is a package  to  emulate  the  Workbenchs'  method  of  starting
programs. Emulating this method seems to  be  easy  on  the  first  look,
because you only have to load a program, create a process and then send a
Workbench startup message to it.

But complications arise from this startup message. It  contains  pointers
to memory and directory locks owned by your process and it  will  not  be
returned until the newly created Workbench process exits. So your process
can't quit until ALL Workbench processes which have been started by  your
process are finished. If you don't wait the replied messages will go into
nowhere land and the man from India will visit you.

WBStart solves this problem by using a handler process, which  loads  the
program, creates the process, sends the message and then  waits  for  the
reply. You just supply all  needed  information  like  program  name  and
arguments in a library call. The handler copies this information so  your
program can free its resources and exit.



II. Installation
================

Just copy the file libs/wbstart.library into your LIBS: directory.

The file WBStarter in dev/c/examples is an example program how to use the
library. It has the following syntax:

   WBStarter <command> [<command> ...]

WBStarter tries to  start  each  command  as  Workbench  process  without
parameters.



III. Contents of this software package
======================================

dev/         Autodoc, FD and C header files for wbstart.library. It  also
             contains the source code for the WBStarter example  and  the
             DICE link libraries.

libs/        wbstart.library. Copy this file to LIBS:

src/         Source code for the wbstart.library. It has been written for
             DICE 3.0 and is included for educational purposes only.  Use
             the command "DMake" to compile it.

WBStart.txt  This documentation.



IV. History
===========

2.0 (13-Mar-1996)
   - The code has been rewritten from scratch.
   - The handler has been integrated into a shared  library.  This  means
     that you don't have to start the handler by hand anymore. It will be
     started automagically when you try to start a  WB  program  using  a
     library call. This also means an end to all these "I can't start  WB
     programs" error reports resulting from a missing e-Flag on the  file
     L:WBStart-Handler :-)

     NOTE: The old interface is not supported anymore!
           You have to rewrite your applications.

   - Requires OS 3.0 (V39) or better.
   - Now uses memory pools to reduce memory fragmenting.
   - Improved WB starter code. It should be almost 100% compatible to the
     real Workbench now.

     NOTE: This may result in some incompatibilities to the  old  WBStart
           package, so you  might  have  to  change  some  of  the  input
           parameters, e.g. in ToolManager Exec objects.

   - Fixed the problem with variables and aliases.
   - Fixed the problem with project icons whose default tool had no icon.

1.4 (03-Oct-1993)
   - If the handler can't duplicate the lock of an argument, it now looks
     if the argument  name  ends  with  a  ':'.  This  type  of  argument
     specifies a device and is produced by the Workbench, e.g. if you put
     an unformatted disk into a drive and use the device icon as argument
     to the program SYS:System/Format.

1.3 (27-Jun-1993)
   - The handler now copies the path from the WB process. This solves the
     problems with programs which use WB2CLI() or similiar  functions  to
     get the WB path list, e.g. SYS:System/CLI. My apologies  to  Michael
     Sinz, Michael B. Smith and the GRn beta testers.
   - The handler now scans the path list when it tries to load a program.
   - The handler now uses NewLoadSeg() instead of LoadSeg().
   - Major source cleanup.

1.2 (21-Sep-1992)
   - Corrected version string.

1.1 (13-Sep-1992)
   - Fixed weird return bug in WBStart.
   - Fixed "Insert volume PROGDIR:..." bug.

1.0 (24-Nov-1991)
   - Initial release



V. Contact addresses
====================

Send comments, suggestions or bug reports to:

 Postal address:

                  Stefan Becker
                  Bonner Ring 68
          D-50374 Erftstadt
                  GERMANY

 EMail:           stefanb@yello.ping.de

 World Wide Web:  http://www.ping.de/sites/yello/
