home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga 13 / MA_Cover_13.bin / source / c / stefanb_src / old_projects / wbstart / wbstart.doc < prev    next >
Encoding:
Text File  |  1993-10-03  |  7.4 KB  |  210 lines
  1. Documentation for WBStart V1.3                                      03-Oct-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_4.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. What is the purpose of this program?
  77. ------------------------------------
  78.  
  79.  WBStart is a package to emulate the Workbench startup procedure. Emulating
  80.  this method seems to be easy, because you only have to load a program, create
  81.  a process for it and then send a Workbench startup message to it.
  82.  
  83.  But complications arise from this startup message. It contains pointers to
  84.  memory and directory locks owned by your process and it will not be returned
  85.  until the new created Workench process exits. So your program can't quit until
  86.  ALL Workbench processes you created are finished and returned their startup
  87.  messages, or the replied messages will go into nowhere land.
  88.  
  89.  WBStart solves this problem by using a handler process, which handles the
  90.  creation of the process and then waits for the reply message. You just send a
  91.  message to the handler port, which contains all needed information, like name
  92.  and arguments. The handler duplicates this information, so your program can
  93.  free its copy and exit.
  94.  
  95.  
  96. Installation & Usage
  97. --------------------
  98.  
  99.  Just copy the file WBStart-Handler into your L: directory. Be sure to set the
  100.  execute flag on this file with
  101.  
  102.    Protect L:WBStart-Handler +e
  103.  
  104.  You can break WBStart-Handler by sending a CTRL-C to its process. If all
  105.  Workbench processes have returned, it will exit.
  106.  
  107.  WBStarter is an example program how to use the handler. It has the following
  108.  syntax:
  109.  
  110.    WBStarter <command> [<command> ...]
  111.  
  112.  WBStarter tries to start each command as Workbench process without parameters.
  113.  If the handler is not running, WBStarter tries to start it.
  114.  
  115.  
  116. How to use WBStart-Handler from your programs
  117. ---------------------------------------------
  118.  
  119.  The handler opens a public message port named "WBStart-Handler Port". You must
  120.  send a message of the following type to this port:
  121.  
  122.    struct WBStartMsg {
  123.                       struct Message  wbsm_Msg;
  124.                       char           *wbsm_Name;
  125.                       BPTR            wbsm_DirLock;
  126.                       ULONG           wbsm_Stack;
  127.                       LONG            wbsm_Prio;
  128.                       ULONG           wbsm_NumArgs;
  129.                       struct WBArg   *wbsm_ArgList;
  130.                      };
  131.  
  132.    wbsm_Msg
  133.     Standard message structure. You MUST initialize the mn_ReplyPort field to
  134.     your own message port.
  135.  
  136.    wbsm_Name
  137.     Pointer to a string, which contains the name of the program. The handler
  138.     recognizes project icons and extracts the default tool.
  139.  
  140.    wbsm_DirLock
  141.     Lock on a directory. wbsm_Name will be used relative to this directory.
  142.  
  143.    wbsm_Stack
  144.     Stack size for the new process. Minimum is 4096 Bytes. If a tool icon
  145.     exists, then the stack size from the icon is used. When this message is
  146.     replied, this field contains a boolean, which indicates the success of the
  147.     action.
  148.  
  149.    wbsm_Prio
  150.     Priority of the new process. Must be in the range -128..127.
  151.  
  152.    wbsm_NumArgs
  153.     Number of arguments in wbsm_ArgList. May be 0.
  154.  
  155.    wbsm_ArgList
  156.     Pointer to an array of Workbench arguments. These arguments contain lock on
  157.     a directory and a pointer to a file name, which is relative to the
  158.     directory. Look into <workbench/startup.h> for the definition of this data
  159.     structure.
  160.  
  161.  Look into the C source for WBStarter for the details.
  162.  
  163.  
  164. Compilation
  165. -----------
  166.  
  167. This program was compiled with DICE, Matt Dillon's superb C compiler. Just
  168. say "DMake" and it will produce the binary.
  169.  
  170.  
  171. History
  172. -------
  173.  
  174. 1.4 (03.10.1993)
  175.    - If the handler can't duplicate the lock of an argument, it now looks if
  176.      the argument name ends with a ':'. This type of argument specifies a
  177.      device and is produced by the Workbench, e.g. if you put an unformatted
  178.      disk into a drive and use the device icon as argument to the program
  179.      SYS:System/Format.
  180.  
  181. 1.3 (27.06.1993)
  182.    - The handler now copies the path from the WB process. This solves the
  183.      problems with programs which use WB2CLI() or similiar functions to get
  184.      the WB path list, e.g. SYS:System/CLI.
  185.      My apologies to Michael Sinz, Michael B. Smith and the GRn beta testers.
  186.    - The handler now scans the path list when it tries to load a program.
  187.    - The handler now uses NewLoadSeg() instead of LoadSeg().
  188.    - Major source cleanup.
  189.  
  190. 1.2 (21.09.1992)
  191.    - corrected version strings
  192.  
  193. 1.1 (13.09.1992)
  194.    - Fixes weird return bug in WBStart
  195.    - Fixes "Insert volume PROGDIR:..." bug
  196.  
  197. 1.0 (24.11.1991)
  198.    - Initial release
  199.  
  200.  
  201. Contact addresses
  202. -----------------
  203.  
  204.  Send comments, suggestions or bug reports to:
  205.  
  206.    Snail : Stefan Becker, Holsteinstrasse 9, 52068 Aachen, GERMANY
  207.    EMail : stefanb@pool.informatik.rwth-aachen.de
  208.            stefanb@yello.adsp.sub.org
  209.  
  210.