home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 4 / CDPD_IV.bin / fish / 891-910 / ff896 / wbstart / wbstart.doc < prev    next >
Text File  |  1994-05-04  |  7KB  |  209 lines
  1. Documentation for WBStart V1.3                                      27-Jun-1993
  2.  
  3. Disclaimer
  4. ----------
  5.  
  6.    Permission is granted to make and distribute verbatim copies of this
  7. manual provided the copyright notice and this permission notice are
  8. preserved on all copies.
  9.  
  10. COPYRIGHT
  11.  
  12.    Copyright (C) 1991-93 Stefan Becker
  13.  
  14.    No program, document, data file or source code from this software
  15. package, neither in whole nor in part, may be included or used in other
  16. software packages unless it is authorized by a written permission from the
  17. author.
  18.  
  19.  
  20. NO WARRANTY
  21.  
  22.    There is no warranty for this software package. Although the author has
  23. tried to prevent errors, he can't guarantee that the software package
  24. described in this document is 100% reliable. You are therefore using this
  25. material at your own risk. The author cannot be made responsible for any
  26. damage which is caused by using this software package.
  27.  
  28.  
  29. DISTRIBUTION
  30.  
  31.    This software package is freely distributable. It may be put on any
  32. media which is used for the distribution of free software, like Public
  33. Domain disk collections, CDROMs, FTP servers or bulletin board systems.
  34.  
  35.    In order to ensure the integrity of this software package, distributors
  36. should use the original archive file WBStart1_3.lha. The author cannot be
  37. made responsible if this software package has become unusable due to
  38. modifications of the archive contents or of the archive file itself.
  39.  
  40.    There is no limit on the costs of the distribution, e.g. for the media,
  41. like floppy disks, streamer tapes or compact disks, or the process of
  42. duplicating. Such limits have been proven to be harmful to the idea of
  43. freely distributable software, e.g. instead of reducing the price of the
  44. floppy disk below the limit, the software was simply removed from the
  45. master disk.
  46.  
  47.    Although the author does not impose any limit on the distribution of
  48. this software package, he would like to express his personal opinions on
  49. this matter:
  50.  
  51.    * This software package should be made available to everyone free of
  52.      charge whenever it is possible.
  53.  
  54.    * If you have acquired this software package under normal conditions from
  55.      a Public Domain dealer on a floppy disk at a price higher than 5DM or
  56.      US $5, then you have definitely paid too much. Please don't support
  57.      this improper profit making any longer and switch to a cheaper source
  58.      as soon as possible.
  59.  
  60.  
  61. USAGE RESTRICTIONS
  62.  
  63.    No program, document, data file or source code from this software
  64. package, neither in whole nor in part, may be used on any machine which is
  65. used
  66.  
  67.    * for the research, development, construction, testing or production of
  68.      weapons or other military applications. This also includes any machine
  69.      which is used in the education for any of the above mentioned
  70.      purposes.
  71.  
  72.    * by people who accept, support or use violence against other people,
  73.      e.g. citizens from foreign countries.
  74.  
  75.  
  76. SPECIAL NOTE
  77.  
  78.    Support Fred Fish and his AmigaLibDisk collection! If you have some
  79. money to spare then please set up a subscription of his disks or donate it
  80. to him directly. If he has to close down, we will loose our main source for
  81. freely distributable Amiga software.
  82.  
  83.  
  84. What is the purpose of this program?
  85. ------------------------------------
  86.  
  87.  WBStart is a package to emulate the Workbench startup procedure. Emulating
  88.  this method is easy, because you only have to load a program, create a process
  89.  for it and then send a WB startup message to it. The only problem is this
  90.  startup message, because it contains memory and directory locks owned by your
  91.  process and it is only returned after the WB process ends. So you can't leave
  92.  your program until ALL WB processes you created have ended, or the replied
  93.  messages will go into nowhere land.
  94.  
  95.  WBStart solves this problem by using a handler process, which handles the
  96.  creation of the processes and then waits for the reply messages. You just send
  97.  a message to the handler port, which contains all needed information, like
  98.  name and parameters. The handler duplicates this information, so you can free
  99.  your copy and leave your program.
  100.  
  101.  
  102. Installation & Usage
  103. --------------------
  104.  
  105.  Just copy the file WBStart-Handler into your L: directory. Be sure to set the
  106.  execute flag on this file with
  107.  
  108.    Protect L:WBStart-Handler +e
  109.  
  110.  You can break WBStart-Handler by sending a CTRL-C to its process. If all WB
  111.  processes have returned, it will exit.
  112.  
  113.  WBStarter is an example program how to use the handler. It has the following
  114.  syntax:
  115.  
  116.    WBStarter <command> [<command> ...]
  117.  
  118.  WBStarter tries to start every command as WB process without parameters. If
  119.  the handler is not running, WBStarter tries to start it.
  120.  
  121.  
  122. How to use WBStart-Handler from your programs
  123. ---------------------------------------------
  124.  
  125.  The handler opens a public message port named "WBStart-Handler Port". You must
  126.  send a message of the following type to this port:
  127.  
  128.    struct WBStartMsg {
  129.                       struct Message  wbsm_Msg;
  130.                       char           *wbsm_Name;
  131.                       BPTR            wbsm_DirLock;
  132.                       ULONG           wbsm_Stack;
  133.                       LONG            wbsm_Prio;
  134.                       ULONG           wbsm_NumArgs;
  135.                       struct WBArg   *wbsm_ArgList;
  136.                      };
  137.  
  138.    wbsm_Msg
  139.     Standard message structure. You MUST initialize the mn_ReplyPort field to
  140.     your own message port.
  141.  
  142.    wbsm_Name
  143.     Pointer to a string, which contains the name of the program. The handler
  144.     recognizes project icons and extracts the default tool.
  145.  
  146.    wbsm_DirLock
  147.     Lock on a directory. wbsm_Name will be used relative to this directory.
  148.  
  149.    wbsm_Stack
  150.     Stack size for the new process. Minimum is 4096 Bytes. If a tool icon
  151.     exists, then the stack size from the icon is used. When this message is
  152.     replied, this field contains a boolean, which indicates the success of the
  153.     action.
  154.  
  155.    wbsm_Prio
  156.     Priority of the new process. Must be in the range -128..127.
  157.  
  158.    wbsm_NumArgs
  159.     Number of arguments in wbsm_ArgList. May be 0.
  160.  
  161.    wbsm_ArgList
  162.     Pointer to an array of WB Arguments. These arguments contain lock on a
  163.     directory  and a pointer to a file name, which is relative to the
  164.     directory. Look into <workbench/startup.h> for the definition of this data
  165.     structure.
  166.  
  167.  Look into the C source for WBStarter for the details.
  168.  
  169.  
  170. Compilation
  171. -----------
  172.  
  173. This program was compiled with DICE, Matt Dillon's superb C compiler. Just
  174. say "DMake" and it will produce the binary.
  175.  
  176.  
  177. History
  178. -------
  179.  
  180. 1.3 (27.06.1993)
  181.    - The handler now copies the path from the WB process. This solves the
  182.      problems with programs which use WB2CLI() or similiar functions to get
  183.      the WB path list, e.g. SYS:System/CLI.
  184.      My apologies to Michael Sinz, Michael B. Smith and the GRn beta testers.
  185.    - The handler now scans the path list when it tries to load a program.
  186.    - The handler now uses NewLoadSeg() instead of LoadSeg().
  187.    - Major source cleanup.
  188.  
  189. 1.2 (21.09.1992)
  190.    - corrected version strings
  191.  
  192. 1.1 (13.09.1992)
  193.    - Fixes weird return bug in WBStart
  194.    - Fixes "Insert volume PROGDIR:..." bug
  195.  
  196. 1.0 (24.11.1991)
  197.    - Initial release
  198.  
  199.  
  200. Contact addresses
  201. -----------------
  202.  
  203.  Send comments, suggestions or bug reports to:
  204.  
  205.    Snail : Stefan Becker, Holsteinstrasse 9, 52068 Aachen, GERMANY
  206.    EMail : stefanb@pool.informatik.rwth-aachen.de
  207.            stefanb@yello.adsp.sub.org
  208.  
  209.