Vectronix 2/VECTRONIX2.iso/FILES_09/EPGP092C.LZH/TOS2GEM/TOS2GEM.TXT

Text File | 1995-09-10 | 20KB | 428 lines

Brief documentation for TOS2GEM dated 26.07.1995, position at 03.08.1995
========================================================================

 1. What is TOS2GEM?
 -------------------
 TOS2GEM is an Auto folder program which GEM applications can access in
 a flexible way to display the output from TOS and TTP programs as VDI
 text in a Console window.
 TOS2GEM makes the ideal Console window for use with shells or alternative
 desktops and saves the programmer some effort!

 TOS2GEM was principally designed for use under Single TOS and although it
 runs fine under Geneva, MagiC and MultiTOS its use there is limited as
 under these systems TOS programs run in windows anyway (if they have been
 started correctly).

 The most important TOS2GEM features at a glance:
 - Gives prorammers a clean way of redirecting the output of TOS/TTP type
   programs into a GEM window.
 - Simulates TOS screens of various sizes (not just boring 80x25) that may
   optionally be only partly visible.
 - Works with all monospaced fonts irrespective of size.
 - Optional output buffer allows faster output than with GEMDOS/BIOS (only
   for SingleTOS/MagiC).
 - Optional scroll-back buffer allows output to be reviewed.
 - Offers almost complete VT52 emulation (colour sequences optional only)


 2. Installation
 ---------------
 Copy TOS2GEM.PRG to the Auto folder of your boot partition. TOS2GEM
 installs a Cookie during booting which programmers can use to control
 some of TOS2GEM's functions. TOS2GEM.PRG can also be run from the desktop.


 3. What is T2GRESET.PRG?
 ------------------------
 Programs must reserve TOS2GEM for themselves; until released other
 programs cannot make use of TOS2GEM.
 If a program which had reserved TOS2GEM crashes or is exited without
 releasing TOS2GEM, you can use T2GRESET.PRG from the desktop to release
 TOS2GEM. It's not a good idea to run T2GRESET.PRG if an application
 which has reserved TOS2GEM is still running, as this inevitably causes
 serious complications.
 Signs that a lock-up has taken place are if no program using TOS2GEM will
 run, and a newly-started one reports that it cannot make a reservation.


4. What is T2G_INTR.PRG?
 ------------------------
 Since the beta-version dated 09.07.1995, TOS2GEM uses the vertical-blank
 interrupt during time-controlled buffering to trigger screen refreshes
 even when there has been no TOS-output for some time (previously checks
 for exceeding the given period were only made during output). If this
 should unexpectedly lead to problems (e.g. unexplained crashes while
 output redirection is active), one can use T2G_INTR.PRG to switch off the
 use of this interrupt (and to switch it on again, if desired, by running
 the program a second time). If one wishes or needs to disable the use of
 the VBL interrupt permanently, then T2G_INTR.PRG should be placed
 physically after TOS2GEM.PRG in the AUTO folder.

 Important: Those who have previously included the mini-package of TOS2GEM
 (see Section 9) with their programs mustn't overlook the fact that
 T2G_INTR.PRG has now been included in this package!


 5. What are T2G_TEST.PRG and PRIME_NO.TOS?
 ------------------------------------------
 (These have been renamed from the German T2G_BSP.PRG and PRIMZAHL.TOS so
 that the titles indicate their purpose better to English-speaking users).
 Since it is difficult to visualise from the theoretical description of
 TOS2GEM operation what the program actually does, I wrote a small test
 program (namely T2G_TEST.PRG, meaning TOS2GEM-test). These two programs
 are incidentally not contained in the mini-package (see Section 9).

 After starting the test program (TOS2GEM must of course have been started
 first) a dialog box appears in which one can input the dimensions of the
 TOS screen that TOS2GEM is to simulate, and the maximum area that is to
 be visible. One can also choose here whether and how output buffering and
 colour support of TOS2GEM is to be used. Following this a corresponding
 window will be opened (already using the TOS2GEM redirection) into which
 the realised dimensions will be written.

 Immediately after this the PRIME_NO.TOS program (that has to be in the
 same directory) will be started; it can execute simple prime number
 calculations using the 'Sieve of Eratosthenes' method (one can also use
 any other TOS program, it just has to be re-named to PRIME_NO.TOS and
 placed in the correct directory). To use it, just follow the prompts;
 note that you have to type 'j' for 'Yes' (which in German is 'ja').

 After ending the prime number program one can move the window, into which
 the output was redirected cleanly, around the screen. Clicking on the
 Closer symbol at top left quits the program. A click inside the window
 area brings up an alert box offering three options: 'Resize' permits
 altering the TOS2GEM window area (with the same dialog that appeared at
 the start; during this the whole screen will be cleared if its total size
 is changed). With 'Rerun' one can start PRIME_NO.TOS again, while
 'Nothing' does just that...

 The test program has been kept simple deliberately, partly so one can see
 that TOS2GEM support is quite easy to realise. Not all the options of
 TOS2GEM are demonstrated (in particular, neither multiple fonts in
 various sizes are used nor is a scroll-back buffer implemented), but
 there should still be enough to illustrate the opportunities that TOS2GEM
 offers.

 Those who would like to have the source code in order to get a concrete
 picture of what TOS2GEM support involves should apply to me (see below).
 Since the source has now been extensively commented (in German!) and a
 number of library functions have been included directly so that it can be
 compiled on its own, it has grown to a stately 46 kB in the meantime.
 However the portion needed only for TOS2GEM support is relatively small
 (not including the comments), so don't be frightened...


 6. Where is the programmers documentation?
 ------------------------------------------
 It's still not quite complete at the moment. I have decided to release
 the hypertext with information (not only) for programmers in its still
 incomplete form, since it has now become at least half-way usable.
 To view it you need ST-Guide by Holger Weets, who I wish to thank once
 more here for this wonderful tool.

 In addition, those who understand German will find articles in
 ST-Computer magazine for 04/95 and 05/95 very helpful. Furthermore it is
 suggested that all programmers should take a look at the TOS2GEM library
 from Dirk Klemmt ([e-mail]) for Pure and Gnu C,
 since this makes the use of TOS2GEM childishly easy. A short overview of
 its capabilities can be obtained from ST-Computer 05/95. Those wanting to
 know more should approach Dirk, since I have had little or nothing to do
 with the library itself.


 7. INSPECT.TTP
 --------------
 This tiny program serves as an aid for programmers who want to write
 applications with TOS2GEM support. You will find more about this in the
 text and hypertext files.


 8. Disclaimer
 -------------
 Although TOS2GEM and the associated utilities have been carefully
 programmed and thoroughly tested I cannot guarantee that no bugs remain.
 Therefore I cannot guarantee either the fault-free operation of TOS2GEM,
 nor its fitness for any particular purpose. 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 and its
 associated applications, utilities and documentation.

 All trademarks mentioned in the TOS2GEM documentation are acknowledged
 and recognised.


 9. Distribution of TOS2GEM
 --------------------------
 TOS2GEM is freeware and may be copied and used freely. However
 distribution may take place only in one of two variants, 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_TEST.PRG, PRIME_NO.TOS, INSPECT.TTP, 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 need or support TOS2GEM
 may include TOS2GEM in their program package (in one of the  above-
 mentioned forms) under the following conditions:

   - 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.

 Furthermore I would be most grateful if you would send me a sample of the
 program.


 10. Contact with the author
 ---------------------------
 For those who have found errors, would like the test program source code,
 need help with programming TOS2GEM applications, want to express praise,
 criticism or simply to chat, here are my details:

 Thomas Binder
 Johann-Valentin-May-Strasse 7
 64665 Alsbach-Haehnlein
 Germany

 InterNet: [e-mail]
 IRC: Gryf

 Please include a disk and SAE (Self Addressed Envelope) along with either
 an International Reply Coupon or a second disk, or be in a position to
 receive binaries via E-mail. You should also state whether you want the
 old or new source for T2G_BSP.TOS (renamed T2G_TEST.TOS in English). In
 the new version a somewhat more complicated, but multi-tasking friendly
 method is used for control, whereas the older version proceeds
 'conventionally'. The new version is recommended only for those that
 already have some experience with TOS2GEM! For beginners I recommend the
 older source code.

 TOS2GEM has taken a considerable amount of my free time to develop and
 if you'd like to contribute to ensure I continue to support the Atari
 platform please don't hesitate to do so! This is aimed particularly, but
 not exclusively, at those that want to support TOS2GEM in their own
 programs.

 My banking arrangements are:
 Dresdner Bank AG Frankfurt am Main
 Account No: 9 024 050 00
 Sort code: 500 800 00

 Thanks a lot!


 11.British support
 -------------------
 British support for the English-language version of TOS2GEM  is provided
 by Denesh Bhabuta at:

   CyberSTrider
   203 Parr Lane
   Unsworth
   Bury
   Lancashire
   BL9 8JW

 He will be pleased to accept any contributions on behalf of the  TOS2GEM
 author gratefully,  sent by Sterling or Euro-cheque, International Money
 Order or Postal Order; a minimum of £6 is recommended.

 Denesh also supports other Freeware and Shareware,  much of it of recent
 German origin. He may be contacted by E-mail at:

   [e-mail]      or
   [e-mail]


 12. What programs support TOS2GEM?
 ---------------------------------
 Currently three main programs use TOS2GEM as Console windows:
 - POVSHELL v1.3 onwards, programmed by Dirk Klemmt:
   Email: [e-mail]
 - Thing alternative desktop, programmed by Arno Welzel:
   Email: [e-mail]
 - The shell Easy-PGP by Manfred Ssykor:
   Email: [e-mail]

 Other programmers are interested but until I'm 100% certain we'll leave
 it at that.

 At this time I would like to repeat an open call to all who have
 previously shown an interest: Let's hear from you! I would be glad of
 some more feedback so that I know whether and what things you are
 programming with TOS2GEM.


 13. Credits and thanks
 ----------------------
 The following people either directly or indirectly took part in the
 development of TOS2GEM (in alphabetical order):
 - Alexander Clauss
 - Joe Connor
 - Frank Danapfel
 - Dirk Klemmt
 - Harald Schönfeld
 - Thomas Schulze
 - Manfrd Ssykor
 - Arno Welzel

 In addition I would like to thank all those who have been willing to send
 me a contribution for TOS2GEM.


 14. Outloook for further development of TOS2GEM
 -----------------------------------------------
 Up to now there have been problems when one uses TOS2GEM and Gemini
 together (not fundamentally, but in certain situations - see hypertext).
 To overcome this will be the next step.

 Oh yes, sometime I should also finish writing the docs....


 15. History
 -----------
 This history only contains the changes since the last pre-release
 beta-version of TOS2GEM, since otherwise it would be a bit long...

 TOS2GEM dated 26.07.1995:
    - Stupidly the MiNT cookie was only interrogated when starting
      TOS2GEM, therefore TOS2GEM also used buffering under MiNT if it
      was started first (the recognition of input calls doesn't work with
      MiNT, therefore one must not buffer).
    - The TOS2GEM test program now uses the option to reserve TOS2GEM
      really only when required. One can therefore start it repeatedly
      (with multi-tasking), as TOS2GEM is not permanently engaged.

    TOS2GEM-beta dated 09.07.1995:
    - A number of errors and inadequacies with the 'stats' evaluation
      removed.
    - With time-controlled buffering TOS2GEM now uses the VBL-interrupt,
      to trigger a screen refresh even when there has been no TOS-output
      for some time (previously checks for exceeding the set period were
      only made during output).
    - New file 'T2G_INTR.PRG' that switches on and off the use of the
      interrupt in cases when problems arise.
    - With buffering active TOS2GEM now also empties the buffer when the
      visible area is moved.

    TOS2GEM dated 21.06.1995:
    - New 'stats' Cookie-element, in which the contents of several
      internal variables are stored when output redirection is not
      activated so that they can be read out later (more about this in the
      docs).

    TOS2GEM-beta dated 01.06.1995:
    - During initialisation of the text buffer, setting of null-bytes for
      line-ends was left out (the source line seems to have got lost when
      colour support was added...)

    TOS2GEM-beta dated 11.05.1995
    - Serious error under MiNT removed: Due to carelessness in the source,
      buffering also took place under MiNT, though input recognition does
      not work in that case.
    - TOS2GEM can now also use time-controlled output buffering; with
      this, screen refreshes take place at pre-set time intervals. This is
      achieved by negative values in the 'buffer_output' Cookie-element.
    - Line redraw in colour mode has been converted to a 'flicker-free'
      method, which, though a little slower, is kinder on the eyes.

    TOS2GEM-beta dated 07.04.1995
    - TOS2GEM can now also handle colour sequences (in which I also
      include those for inverted video)!  The new 'color' Cookie-element
      determines the type of colour support (compatible or VDI-
      conforming). More about this in the HYP doc, which has now been
      released.
    - Under SingleTOS, TOS2GEM output buffering now also uses a timer
      triggering a refresh after 500 ms for Bconstat calls. Thanks to
      this, TOS programs that interrogate the keyboard via Bconstat/Bconin
      will work correctly (e.g. SYSOK). Under MagiC this is unnecessary,
      as there the buffer will be cleared at each Bconstat call anyway.

    TOS2GEM dated 24.03.1995
    - Since I was informed in a bug report that the TOS2GEM Cookie was
      still present after a reset, TOS2GEM now also hooks into the reset
      vector to clear the Cookie pointer even when it only has to extend
      the Cookie-jar. I hope that this has removed the problem (I couldn't
      reproduce it).
    - With output buffering active, a refresh is now also performed when
      the screen contents have (internally) moved by the window height.
      Thanks to this, no output will get lost completely.

    TOS2GEM-beta dated 02.02.1995
    - Keyboard input is recognised now also under MagiC, so that buffering
      is also possible with this operating system. Unfortunately it
      doesn't work with MiNT/MultiTOS (though here one is likely to forego
      TOS2GEM in favour of TOSWIN/MINIWIN, which natutally also applies to
      VT52 under MagiC).
    - Buffering could be improved once more, so that output is more than
      twice as fast as without buffering (this is in part faster than the
      standard GEMDOS/BIOS output).

    TOS2GEM-beta dated 31.01.1995(?)
    - With the new 'buffer_output' Cookie element one can achieve
      buffering of the output, which results in a marked increase in
      speed. Unfortunately this only works under SingleTOS, as only there
      can TOS2GEM recognise keyboard output correctly (it is necessary to
      clear the buffer in this case, so one can recogise what should be
      input).

    TOS2GEM dated 19.01.1995
    - If TOS2GEM had to create or extend the Cookie-jar, this was lost
      when output redirection was first activated as it lay in the same
      memory region as the VDI array.

    TOS2GEM dated 03.01.1995
    - In re-activating output redirection via 'switch_output', the
      Y-offset was not adapted correctly. Since this was not an
      insignificant error, it is advisable to use at least this version
      (note the 'date' Cookie-element!) in programs in which the size of
      the TOS2GEM window can be altered.
    - TOS2GEM.PRG now has the memory protection flag 'global' once again
      (I forgot it the last time, because the Pure C linker unfortunately
      can't do this (at least that of 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
      this field.

    TOS2GEM dated 12.12.1994:
    - A small error occurred during calculation of two internal variables
      that resulted in faulty scrolling in some circumstances (if only
      the first pixel row of a line was visible).
    - TOS2GEM test example included in the 'large' archive, so that one
      can see what the purpose of TOS2GEM is and how it works. I hadn't
      thought of this at first (thanks to Dirk Klemmt, who brought this
      omission to my attention).

    TOS2GEM dated 22.11.1994:
    - First official version, unfortunately without ST-Guide documentation
      (I wanted to release TOS2GEM at the proTOS...)
    - A problem under MagiC that switches on the 'real' cursor for an
      'Fread' call for the console and completely misplaces the one for
      TOS2GEM has now been circumvented. Though the solution was not a
      'clean' one (write access to the negative LineA variables), I could
      not find any other reliable method.
    - TOS2GEM now has a 'Global' memory protection flag, so that no
      problems arise in this respect with Mint/MultiTOS.


 15. English translation
 -----------------------
 English version of this document by Joe Connor, with additions and
 corrections in various files by Peter West (who is also responsible for
 the hypertext translation).