Short information for TOS2GEM of 13.09.1996. As at: 13.09.1996 -------------------------------------------------------------- 1. What is TOS2GEM? ------------------- TOS2GEM is a program for the AUTO-folder which offers GEM applications a flexible way to redirect screen output of .TOS or .TTP programs to a window. This is achieved with VDI text commands, and allows programmers of shells or alternative desktops to install a kind of Console window without much effort. From this it becomes clear, of course, that TOS2GEM is intended for use mainly under SingleTOS. Actually it will also run under Geneva, MagiC and MultiTOS, though here its use is of course very restricted as TOS programs under these systems run in windows anyway (if they are started correctly). The most important properties of TOS2GEM at a glance: - Offers programmers a clean way of diverting output of TOS programs started after it to a GEM window - Simulates TOS screens of any desired size (so not just the boring 80x25), that may also be only partly visible - Works with all non-proportional fonts in any point size - With (optional) output buffering can have faster output than with GEMDOS/BIOS (only for SingleTOS/MagiC) - Optionally offers a 'history' buffer for older output ('scroll-back') - Has complete VT52 emulation (colour sequences only optional) 2. How does one install it? --------------------------- TOS2GEM.PRG is simply copied to the AUTO-folder on the boot partition and during each boot process creates a cookie which the programmer can use to control the use of TOS2GEM. But if required TOS2GEM.PRG can also be started from ther desktop. 3. What is T2GRESET.PRG? ------------------------- Programs have to reserve TOS2GEM for themselves; until it is released other programs cannot make use of TOS2GEM. Should a program that has reserved TOS2GEM for itself crash, or forget to release it when it terminates, then this blockage can be removed by calling T2GRESET. It is not advisable to call T2GRESET while the application that reserved TOS2GEM is still running, because this will necessarily lead to serious complications. An indication that such a blockage has occurred is when no program using TOS2GEM is running and a newly started one reports that it cannot reserve it for itself. 4. What is T2G_INTR.PRG? ------------------------ Since the beta version of 09.07.1995 TOS2GEM hooks into the VBL (vertical blanking) interrupt in order to be able to trigger a refresh of the screen contents during time-controlled buffering even when the running program has made no output for some time (previously checks were made directly during output only to see whether the time interval had been exceeded). If this should give rise to unexpected problems (e.g. unexplained crashes while output redirection is active) one can use T2G_INTR.PRG to switch off the use of the interrupt (and switch it back on again if required). If this is desired or required permanently, then T2G_INTR.PRG should be placed physically after TOS2GEM.PRG in the AUTO folder. Important: Those who have included the mini-package of TOS2GEM with their own programs in the past (see item 9) should ensure that T2G_INTR.PRG is included in this pckage! 5. What are T2G_BSP.PRG/T2G_TEST.PRG and PRIMZAHL.TOS/PRIME_NO.TOS? ------------------------------------------------------------------- As it is difficult to visualise what TOS2GEM actually does from a theoretical description of how it works, I have written a small example program (called T2G_BSP.PRG for 'TOS2GEM-Beispiel' (-example) in German and T2G_TEST.PRG in the English translation). Incidentally, neither file is contained in the small archive (see item 9) such as the one included with Thing! After starting this program (TOS2GEM must of course have been started earlier) a dialog box appears in which one can specify the dimensions of the TOS screen to be simulated by TOS2GEM, and the maximum amount of this to be visible. In addition one can select here whether and how output buffering and colour support are to be used by TOS2GEM. Following this a corresponding window will be opened to which (already using TOS2GEM redirection) the dimensions to be realised are written. Directly after this the program PRIMZAHL.TOS (PRIME_NO.TOS in English) will be started (it has to be present in the same directory) which can calculate all the primes up to a specified number which the user is asked to input, using the 'Sieve of Eratosthenes' algorithm; one could also use any other .TOS program as long as it is placed in the correct directory and renamed to PRIMZAHL.TOS or PRIME_NO.TOS for the German and English versions of the example program respectively. At the end of the prime number program one can position the window into which clean output was made anywhere on the screen. Clicking on the 'Closer' button terminates the program, a click within the working area of the window brings up an alert offering three choices: 'Resize' permits altering the TOS2GEM window size (with the same dialog as at its start; the screen is cleared if the total size is altered). With 'Rerun' PRIMZAHL/PRIME_NO.TOS can be started again and 'Nothing' does just that... The example program has been kept simple deliberately, so that one can see that TOS2GEM support is relatively easy. Not all capabilities of TOS2GEM are demonstrated (in particular neither various fonts and character sizes nor a 'scroll-back' history buffer are available), but it should make clear the possibilities that TOS2GEM offers. Those who would like to obtain the source code in order to obtain a concrete picture of TOS2GEM support should get in touch with me (see below). As the source has been extensively furnished with comments (in German) and some library fuinctions have been incorporated directly so that it can be compiled as it stands, its size has grown to some 46 kilobytes. However the portion that is required for TOS2GEM support only is relatively small (excluding the comments), so there's no need to be afraid... 6. Docs for programmers ----------------------- I have decided to release the hypertext with information (not only) for programmers in its still incomplete version, since it may be half-way usable in its present state. To view it one requires ST-GUIDE by Holger Weets, whom I'd like to thank here once more for this excellent utility. In addition to the hypertext docs, those who can read German may be helped by a look at 'ST-Computer' 04/95 and 05/95. In addition I'd advise everyone to take a look at the TOS2GEM library by Dirk Klemmt (klemmt@stud.uni-frankfurt.de) for Pure and Gnu C, which makes using TOS2GEM child's play. A short summary of its capabilities can be obtained from 'ST-Computer' 05/95. Anyone wishing to know more please get in touch directly with Dirk, as I have little or nothing to do with the library itself. 7. INSPECT.TTP -------------- This tiny program serves as an aid for programmers who wish to write applications with TOS2GEM support. More about this can be found in the hypertext. 8. Legal -------- TOS2GEM was programmed with great care and tested extensively. However one cannot exclude the possibility that some bugs remain. I can therefore neither guarantee fault-free operation of TOS2GEM nor its fitness for any particular purpose. Furthermore, you use TOS2GEM at your own risk! I, Thomas Binder, do not accept any liability or responsibility for any direct or indirect damage that may arise, either financial, material or any other kind from either the use or misuse of TOS2GEM. The same applies, of course, to the associated applications, utilities and documentation contained in the archive. 9. Distribution of TOS2GEM -------------------------- TOS2GEM is freeware and may be copied and used freely. For general distribution one of two of the following packages has to be chosen, where all the named files have to be copied unchanged in each case (archiving is permitted): a) Complete package Contains TOS2GEM.PRG, T2GRESET.PRG, T2G_INTR.PRG, TOS2GEM.H, TOS2GEM.TXT, T2G_BSP/T2G_TEST.PRG, PRIMZAHL/PRIME_NO.TOS, INSPECT.TTP, as well as TOS2GEM.HYP and TOS2GEM.REF. This package is mainly intended for distributing TOS2GEM on its own (when it is not included with another program). b) Mini-package Contains only TOS2GEM.PRG, T2GRESET.PRG, T2G_INTR.PRG and TOS2GEM.TXT. This variant should only be used when one wants TOS2GEM to accompany a program that requires it. Those who have developed their own programs that support or require TOS2GEM may include TOS2GEM in their program package (in one of the forms mentioned above) no matter whether it is PD/Shareware or commercial software, as long as the following conditions are fulfilled: - TOS2GEM must be copied to its own folder - The documentation or the program must contain instructions for using TOS2GEM - It must be clear from the documentation that TOS2GEM is a separate, free-standing utility developed by me, and that it does not belong to the actual program Additionally I would be most grateful if you would send me a sample of the program. 10. Contact with the Author --------------------------- Anyone who has found any bugs, would like the source code, needs help for programming TOS2GEM applications, wishes to send praise, criticism and/or suggestions or just simply wishes to 'chat' with me can make use of the following addresses: Thomas Binder Johann-Valentin-May-Straže 7 64665 Alsbach-H„hnlein Deutschland/Germany InterNet: binder@rbg.informatik.tu-darmstadt.de (preferred) gryf@hrzpub.tu-darmstadt.de MausNet: Thomas_Binder @ HD (no mails > 16K!) IRC: Gryf Those who would like to obtain the extensively commented source code for the TOS2GEM example should either send me a self-addressed envelope with German stamps or 2 International Reply Coupons, or be in a position to receive binaries by Email. In addition you should specify whether you want the code for the old or new TOS2GEM example. The newer one uses a little more complicated but in return multitasking-friendly method of control, while the old version proceeds 'conventionally'. I'd only recommend the new version to those who have had previous experience with TOS2GEM programming! For beginners I suggest the older source code. Naturally I'd be very happy if some of you would reward the work that I have put into TOS2GEM with a small contribution sent to my bank account (or to my British representative - see SUPPORT.TXT.) Every contributions safeguards further development of TOS2GEM, which I hope is desirable. My banking details: Dresdner Bank AG Frankfurt am Main Konto-Nummer/Account No.00 Bankleitzahl/Sort code: 500 800 00 Many thanks! 11. Which programs support TOS2GEM? ----------------------------------- Up to now I am aware of four programs that use TOS2GEM to redirect output of TOS programs into a window: - The POVShell by Dirk Klemmt (klemmt@stud.uni-frankfurt.de) from Version 1.3 onwards - The alternative desktop Thing originally programmed by Arno Welzel (arno@alphasystems.de) and now with continued development by me - The Shell Easy-PGP by Manfred Ssykor (msy@lafp.tng.oche.de) - A POV-3.0 port by Szymon Stasik (ss158962@students.mimuw.edu.pl) Since in the age of MagiC and N.AES no other people seem to be interested in supporting TOS2GEM in their own programs, I have not done much more in the docs for programmers. I don't want to do unnecessary work ;) 12. Thanks ---------- The following people took part in the development of TOS2GEM, directly or indirectly (in alphabetical order): - Denesh Bhabuta - Alexander Clauss - Joe Connor - Frank Danapfel - Dirk Klemmt - Harald Sch”nfeld - Thomas Schulze - Manfred Ssykor - Arno Welzel In addition I'd like to thank all those who have sent me a contribution for TOS2GEM. 13. Outlook for further development of TOS2GEM ---------------------------------------------- Apart from some possible bug fixes I doubt if I'll do much more with TOS2GEM, since in my opinion it's already relatively mature; in any case there seems to be no great demand for it from programmers or users any more. 14. History ----------- The history only contains changes from the last pre-release beta-version of TOS2GEM, as it would get a bit long otherwise... TOS2GEM of 13.09.1996: - No more crashes if the visible portion lies outside the physical screen (even though this is not allowed anyway according to the docs) - Under certain circumstances the internal colour-buffer pointer introduced in the beta of 10.02.1996 was not updated when diversion was switched back on again, which resulted in the colour buffer being kept at the wrong position TOS2GEM-beta of 01.03.1996: - Further small increase in output speed with buffering active TOS2GEM-beta of 10.02.1996: - If the time interval for time- and(!) interrupt-controlled buffering is smaller than 200ms, TOS2GEM omits refreshes during input as one happens often enough. Thanks to this output from Mupfel under MagiC is no longer painfully slow (Mupfel asks after outputting each(!) character whether a character is on the way, which TOS2GEM under MagiC must normally evaluate as a refresh request) - The output speed in colour mode is now almost as fast with a white background as in monochrome, since in this case the additional drawing of the character background is dispensed with in favour of the replace-mode. Since a white background is the norm, this improvement is very noticeable - Output buffering too has now become appreciably more efficient when lines contain many space charactes at the ends. Although this is not quite as common as a white background, it still happens often enough to make an appreciable difference TOS2GEM of 26.07.1995: - Stupidly the 'MiNT' cookie was only looked for when TOS2GEM was started, so that TOS2GEM also buffered under MiNT when this was started first (recognition of input requests doesn't work with MiNT so one may not buffer with it) - The TOS2GEM example program now exploits the possibility of reserving TOS2GEM really only when it is needed. So one can now start it several times (with multitasking) as TOS2GEM is not permanently engaged TOS2GEM-beta of 09.07.1995: - A number of errors or inadequacies in the stats-evaluation removed - With time-controlled buffering TOS2GEM hooks into the VBL (vertical blanking) interrupt in order to be able to trigger a refresh of the screen contents even when the running program has made no output for some time (previously checks were made directly during output only to see whether the time interval had been exceeded) - New file 'T2G_INTR.PRG' to switch interrupt usage on and off, in case of problems arising - With active buffering TOS2GEM now also clears the buffer when the visible area is moved TOS2GEM of 21.06.1995: - New cookie-element 'stats', in which the contents of several internal variables can be stored when output redirection is inactive, to be read out again later (see more about this in the docs) TOS2GEM-beta of 01.06.1995: - During initialising of the text buffers setting Null bytes for the line end was omitted (the source line seems to have got lost while incorporating colour support...) TOS2GEM-beta of 11.05.1995 - Serious error under MiNT removed: Due to an oversight in the source, buffering took place under MiNT though the recognition of input does not work there - TOS2GEM can now also use time-controlled output buffering, where refreshes take place at specified time intervals. This is achieved by negative values in the cookie element 'buffer_output' - The line redraw in colour mode was altered to a 'flicker-free' method, which while being slower is far easier on the eye TOS2GEM-beta of 07.04.1995 - TOS2GEM now also uses the colour sequences (which also includes inversion!). The new cookie element 'color' sets the type of colour support (compatible or VDI-conforming). More about this in the .HYP docs, which have now been released - Under SingleTOS, TOS2GEM now also uses a timer that triggers a refresh after 500 ms at Bconstat calls during output buffering. This permits TOS programs that interrogate the keyboard with Bconstat/ Bconin to work correctly (e.g. SYSOK). Under MagiC this is not necessary as in that case the buffer is cleared anyway at each Bconstat call TOS2GEM of 24.03.1995 - As a bug report informed me that the 'TOS2GEM' cookie was still present after a reset, TOS2GEM no also hooks into the reset vector to clear the cookie pointer even when it only needs to extend the cookie jar. I hope this has removed the problem (I could not duplicate it) - With output buffering active, a 'refresh' will also be executed now when the screen contents (internally) have moved by the height of the window. This prevents any output from being completely 'swallowed' TOS2GEM-beta of 02.02.1995 - Now the recognition of keyboard input also works under MagiC, so that buffering is also possible with that operating system. Unfortunately it does not work with MiNT/MultiTOS (but there one would use TOSWIN/MINIWIN in preference to TOS2GEM anyway, which also applies to VT52 under MagiC, of course - Buffering could be improved once more so that output now takes place more than twice as fast as without buffering (in part this is faster than the standard GEMDOS/BIOS output) TOS2GEM-beta of 31.01.1995(?) - With the new cookie element 'buffer_output' one can achieve buffering of the output, which brings a marked speed increase. Unfortunately this only works with SingleTOS, as TOS2GEM can only recognise keyboard input correctly there (in such a case the buffer has to be cleared to make it possible to see what is to be input) TOS2GEM of 19.01.1995 - If TOS2GEM had to create or extend the cookie jar, this was lost at the first activation of output redirection, as it lay in the same memory region as the VDI array TOS2GEM of 03.01.1995 - When reactivating output redirection with 'switch_output' the y_offset was not adapted correctly. As this is a not inconsiderable error, it is advisable to use at least this TOS2GEM version with programs in which the size of the TOS2GEM window can be altered (take note of the 'date' cookie element!) - TOS2GEM.PRG now has the memory protection flag 'Global' once again (I had forgotten this the last time because the Pure C linker unfortunately cannot do this (at least not the one from PC 1.0)) - The header file has been improved: The constant RESERVED_SIZE now exists for the 'reserved' field of the cookie, specifying the size of the field TOS2GEM of 12.12.1994: - A small error crept into the calculation of two internal variables which led to faulty scrolling in certain circumstances (if only the first row of pixels of a line was visible) - TOS2GEM example included into the 'large' archive so that one can visualise what TOS2GEM actually does and how it works. I hadn't thought of this originally (thanks to Dirk Klemmt, who pointed this out to me) TOS2GEM of 22.11.1994: - First official version, unfortunately still without ST-Guide docs (I wanted to 'release' TOS2GEM at the proTOS...) - Under MagiC there is a workaround for the problem that an 'Fread' call for the Console switches on the 'real' cursor and places the one for TOS2GEM in completely the wrong place. The solution is a little 'dirty' (write access to the negative LineA variables) but I could find no other reliable method to accomplish this - TOS2GEM now has the memory protection flag 'Global', so that no problems should arise with this under MiNT/MultiTOS ------------------------------------------------------------------------- English translation of this and associated files: Peter West, TransAction.