Documentation for WBStart V1.3 03-Oct-1993 Disclaimer ---------- 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-93 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 put on 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 WBStart1_4.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 costs of the distribution, e.g. for the media, like floppy disks, streamer tapes or compact disks, or the process of duplicating. Such limits have been proven to be harmful to the idea of freely distributable software, e.g. instead of reducing the price of the floppy disk below the limit, the software was simply removed from the master disk. Although the author does not impose any limit on the distribution of this software package, he would like to express his personal opinions on this matter: * This software package should be made available to everyone free of charge whenever it is possible. * If you have acquired this software package under normal conditions from a Public Domain dealer on a floppy disk at a price higher 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. What is the purpose of this program? ------------------------------------ WBStart is a package to emulate the Workbench startup procedure. Emulating this method seems to be easy, because you only have to load a program, create a process for it 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 new created Workench process exits. So your program can't quit until ALL Workbench processes you created are finished and returned their startup messages, or the replied messages will go into nowhere land. WBStart solves this problem by using a handler process, which handles the creation of the process and then waits for the reply message. You just send a message to the handler port, which contains all needed information, like name and arguments. The handler duplicates this information, so your program can free its copy and exit. Installation & Usage -------------------- Just copy the file WBStart-Handler into your L: directory. Be sure to set the execute flag on this file with Protect L:WBStart-Handler +e You can break WBStart-Handler by sending a CTRL-C to its process. If all Workbench processes have returned, it will exit. WBStarter is an example program how to use the handler. It has the following syntax: WBStarter [ ...] WBStarter tries to start each command as Workbench process without parameters. If the handler is not running, WBStarter tries to start it. How to use WBStart-Handler from your programs --------------------------------------------- The handler opens a public message port named "WBStart-Handler Port". You must send a message of the following type to this port: struct WBStartMsg { struct Message wbsm_Msg; char *wbsm_Name; BPTR wbsm_DirLock; ULONG wbsm_Stack; LONG wbsm_Prio; ULONG wbsm_NumArgs; struct WBArg *wbsm_ArgList; }; wbsm_Msg Standard message structure. You MUST initialize the mn_ReplyPort field to your own message port. wbsm_Name Pointer to a string, which contains the name of the program. The handler recognizes project icons and extracts the default tool. wbsm_DirLock Lock on a directory. wbsm_Name will be used relative to this directory. wbsm_Stack Stack size for the new process. Minimum is 4096 Bytes. If a tool icon exists, then the stack size from the icon is used. When this message is replied, this field contains a boolean, which indicates the success of the action. wbsm_Prio Priority of the new process. Must be in the range -128..127. wbsm_NumArgs Number of arguments in wbsm_ArgList. May be 0. wbsm_ArgList Pointer to an array of Workbench arguments. These arguments contain lock on a directory and a pointer to a file name, which is relative to the directory. Look into for the definition of this data structure. Look into the C source for WBStarter for the details. Compilation ----------- This program was compiled with DICE, Matt Dillon's superb C compiler. Just say "DMake" and it will produce the binary. History ------- 1.4 (03.10.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.06.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.09.1992) - corrected version strings 1.1 (13.09.1992) - Fixes weird return bug in WBStart - Fixes "Insert volume PROGDIR:..." bug 1.0 (24.11.1991) - Initial release Contact addresses ----------------- Send comments, suggestions or bug reports to: Snail : Stefan Becker, Holsteinstrasse 9, 52068 Aachen, GERMANY EMail : stefanb@pool.informatik.rwth-aachen.de stefanb@yello.adsp.sub.org