 ************************************************************************
   Please note, the following text is not up to my usual(?) standard of
  translation.  It is both colloquial, and contains a lot of jargon - too
               much for my understanding and my dictionary!
         Nevertheless, I hope it will be both useful, and usable!

                           The Saint - July '94
 *************************************************************************

                                                           19.08.93

     CompilerLibrary patches for GFABASIC Atari ST/STE/TT/Falcon

     P*ST:
           Christoph Conrad
           Adalbertsteinweg 113
           52070 Aachen

 E-Mail direct:     MAUS: Christoph Conrad @ AC3

 E-Mail Gateways:
     FIDO: Christoph Conrad % Maus AC3 2:242/2.6
           ACHTUNG: evt. neu
           Christoph Conrad % Maus AC3 2:242/42.333
   USEnet: Christoph_Conrad@ac3.maus.de    (keine ueberlangen Mails!)
 Zerberus: Christoph_Conrad%ac3@zermaus.zer
   Pronet: MAUS:AC3:Christoph_Conrad
 Internet: conrad@pool.Informatik.RWTH-Aachen.DE
           (selten, bitte keine ueberlangen Mails!)
      BTX: Seite *35008024#, im Formular ausfllen
           Christoph_Conrad@AC3.MAUS.DE.UUCP
           (kostet 90 Pfennig)

In case you have discovered something  that  causes  a problem, or you have
suggestions for improvements, write to me by EMail (preferably) or P*ST.

When you find an error in Basic, write to me!

I cannot accept any responsibility  or  take  liability for any damage that
could possibly have been caused to your data or programs either directly or
indirectly that have occurred as a result of using these patches!

Contents:

 (I) General & specific info for these patches
(II) Various questions and answers

(I) General & specific info for these patches

Moin,

GFABASIC has grown close to all of our  hearts.  When I first got my ST, it
was the only programming language  that  offered  a really fast turn around
time   (edit   a   program,   test    it,   edit   a....),   a   hyperspeed
compiler/interpreter (in most  cases  the  compiler  also created correctly
fixed code!) a usable  editor  and  could  usefully  be  employed  on a 1Mb
computer _without_ a hard drive. I suspect that this was the reason for the
success of GFA BASIC.

In the course of time and  particularly  (but not only) in conjunction with
graphic improvements has GFABASIC  shown  some  of  its shortcomings. These
library patches correct some (serious) problems.

The library patches have already appeared  in  two versions as GFAL1030 and
improved in GFAL1072. I was then  asked  by  Gregor Duchalski whether I did
not have the desire  to  contribute  some  of  my  own  ideas  to patch the
interpreter using a convenient GEM interface.

Since my patch  program  offered  a  convenient  operating  environment AND
because of Gregor's involvement and the  wishes of the GFABASIC MAUS group,
I decided to do this. This convinced me  to develop my own GFA library that
can be installed using GFA_PTCH.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
What does the compiler patch part of GFA_PTCH offer?

- Line-A patches are incorporated automatically!
- Clean Auto folder recognition
- Clean recognition of accessories
- In case the memory requested by $m does not exist, this can be recognized
- $U/$I bug in 3.6 removed!
  Important: I definitely advise against the $I matter in particular. It is
  untidy or in fact lethal. Also, $U can be critical. With this Init part,
  $U/$I will run just as "dirty" or "uncertain" as before, apart from the
  fact that it does now actually run under 3.6.

ERR.LST demonstrates to you in an  exemplary  way all of the features. This
also uses $I+ cleanly in the case  of  the  demo. Take note of the comments
incorporated in ERR.LST and the hints offered below!

!!! Part of the assembler code is GFA Systemtechnik

Changes made to either part are for  personal use only. Modified copies may
not be re-distributed!

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Since there was a great deal of  work involved in developing these patches,
If you find them useful, a  gift  (of  thanks)  of  >= 10,- would show your
appreciation :-)

Alternatively, since I am a music fan,  you  can send me a cassette (Chrome
dioxide, Dolby  B  -  preferably  a  TDK  SA-X)  containing  some  of  your
favourites. All types from  Classical  vocal  (Opera, Operetta etc.), Rock,
Folk and Disco (Bananarama,  Sabrina)  are  welcome.  I prefer lesser known
groups/bands/interpretations. I hope to get a flood of cassettes!!! :-)

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
What does GFA_PTCH.PRG do ?

== (a) patches the compiler

Attention: Programs created using a patched compiler will _NOT_ run with an
original library!

== (b) Patches the library

In the strictest sense this is not a patch but an exchange of code.

== 9c) Creation of a new index file GFA3BLIB.NDX

MAKE_NDX.PRG  must  be  used   _unconditionally_,   which   creates  a  new
GFA3LIB.NDX. this ought to be used with GFA_PTCH.

You ought probably to save the old  version of GFA3BLIB.NDX even though you
could re-create this at any time using MAKE_NDX.PRG with the old library.

Unfortunately, MAKE_NDX first appeared  with  version  3.5.  Currently I am
unaware (even if you are) whether  it  could  be included with this package
and I have queried this with  GFA.   If  it  can't, I will probably write a
functional equivalent.

== (d) Patch the interpreter

You must _unconditionally_  patch  the  interpreter  using GFA_PTCH.PRG. In
case your version of the interpreter has not been seen by us:

Replace the FIRST occurrence of $A00A  and  $A009 by $4E71. This _ought_ to
cause a crash. As a result of the patch: $E0C0 $A00A $4CDF as well as $0008
$A009 $246E.

This will produce  "mouse  droppings"  when  moving  the  mouse  within the
interpreter editor, but not whilst a  program is running (the clean nesting
of hidems/showms for GRAF_MOUSE is taken for granted!).


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
In case you have further problems:

- Make a test with the original GFA3BLIB (+ the previous GFA3BLIB.NDX).

Send me
- the INIT.O file for your library
- The exact version number/length of the library & compiler.

This can be done  simply  by:  Run  INIT2DMP.PRG  from  the  same folder as
GFA3BLIB which will produce a printable or E-mail-able file INIT.DMP.

!!! Make sure that you use your ORIGINAL library or a copy of it and !!!
!!! not one that has already been patched                            !!!


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
How do I work with it ?

Please take a look at the  ERR.LST  file.  I  hope that will be enough. You
should then read through the question and answers section of this text. The
commands that you ought to avoid  (e.g.  the  Line A patches), and you will
find many of the tips useful.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
BUGS:

Hopefully there are not too many

Still being worked on:

ERR appears when starting the  interpreter  not  always when initialised to
zero.

Before you blame  this  INIT,  please  test  it  first  using  the original
GFA3BLIB (& the previous GFABLIB.NDX).

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Disclaimer:

I have taken all possible precautions to create error-free programs & data.
Nevertheless, it is not totally possible  to exclude errors. Therefore, the
authors cannot accept any responsibility  or  take liability for any damage
that could possibly  have  been  caused  to  your  data  or programs either
directly or indirectly  that  have  occurred  as  a  result  of using these
programs!

***************************************************************************
(II) Questions & answer section

QUESTIONS & ANSWERS:

+++++++++++++++++++++
QUESTION:
I have taken your advice that Line-A  should  not  be used. Why is this so?
Therefore, how can I make my compiler library (GFA3BLIB) Line-A free?

ANSWER:
Here is an extract from the 10th edition of the Profibook:

[Start of quote]

The architecture of the operating system certainly speaks against the usage
of Line-A routines. These are used for  display in the low-level VDI screen
driver. Using them prevents the  possible  usage of another (faster) screen
driver!

Also, Line-A routines are  only  provided  for  ST modes (320*200, 640*200,
640*400). Already, with 256 colour  graphics  (special graphic cards or the
TT in 'low' resolution) the  provisions  of  the Line-A interface have been
exhausted (see COLBIT0 to COLBIT3)

[End of quote]

In case that was as clear as mud: DON'T PANIC!

The deciding factor in all this will be that programs using Line-A routines
will not run correctly with graphic cards! Ergo: Do away with it!

*** Take heed from a correct  nesting  of hidems/showms (via GRAF_MOUSE AES
78). For each hide of a show,  "droppings"  will result. With the mouse not
switched on, when it already is, as is the rule when starting GEM programs,
there are no "droppings".

*** AVOID THE FOLLOWING COMMANDS:

RSCOL   CRSLIN   MOUSE    MOUSEK   MOUSEX   MOUSEY   SETMOUSE RC_COPY
SHOWM    HIDEM    SPRITE   ACHAR    ACLIP    ALINE    APOLY    ARECT
ATEXT    BITBLT   HLINE    L~A      PSET     PTST     GET      PUT
SGET     SPUT     FILESELECT        FILESELECT #

When using without #file_number:
INPUT    INPUT$   LINE INPUT

Replacement commands:

MOUSE/MOUSEK/MOUSEX/MOUSEY -> (AES) GRAF_MKSTATE
SETMOUSE                   -> (AES) APPL_TPLAY
SHOWM/HIDEM                -> (AES) GRAF_MOUSE
FILESELECT                 -> (AES) FSEL_INPUT
FILESELECT #               -> (AES) FSEL_EXINPUT
SPRITE                     -> (VDI) vro/vrt_cpyfm
ACHAR                      -> (VDI) TEXT
ACLIP                      -> (VDI) CLIP
ALINE                      -> (VDI) LINE
APOLY                      -> (VDI) POLYLINE
ARECT                      -> (VDI) PBOX
ATEXT                      -> (VDI) TEXT
BITBLT                     -> (VDI) BITBLT q%(),z%(),d%()
HLINE                      -> (VDI) LINE
PSET                       -> (VDI) PLOT
PTST                       -> (VDI) POINT
GET/PUT/SGET/SPUT          -> (VDI) BITBLT
RC_COPY                    -> (VDI) BITBLT

  >> Without a guarantee of completeness!

+++++++++++++++++++++

QUESTION:
Where can I find information about GEM conforming programming?

ANSWER:
Tim Orens ProGEM. This text from 1985, which  you should be able to find in
most mailboxes provides the  best  in  'Professional  GEM' programming. You
will find more in the book 'Vom  Anfnger zum GEM-Profi' by Gebrder Geiss.
A little confused, but  otherwise  very  good.  As  reference material, the
'Profibuch' by Jankowski/Reschke/Rabich, is undoubtedly irreplaceable.

++++++++++++++++++++
QUESTION:
GFA already has good commands  for  using  windows.  What can these be used
for?

ANSWER:
I advise against using GFA's  own  window  management routines. In previous
versions this is incorrect - today, who knows? Using the AES, it is equally
as 'simple' or 'difficult'.

+++++++++++++++++++++
QUESTION:
Sometimes my program is no longer under  my  control. With the best will in
the world I cannot find any  errors.  What  is  happening and how do I find
out?

ANSWER:
Use SysMon and TempleMon. You can find TempleMon in many mailboxes - SysMon
can be obtained directly from the author:-

Karsten Isakovic
Wilmersdorferstr. 82
1000 Berlin 12

At the time of the crash, you will  at  least be able to establish the last
used system call and possibly the bad parameter.

Another good  possibility  is  to  use  the  TRACE  procedurename  (see the
manual). When all of the  lines  that  have  been  traced  are written to a
previously opened file  (PRINT  #1,TRACE$)  you  will  quickly  be  able to
localise the cause of the crash.

The Turbo-C/Pure-C debugger can be equally  as  useful when the program has
been translated into symbols.

There is an extensive unknown error  that  exists in GFA-Basic's own memory
management. This exists in all three versions.

Hint: add a FRE(0) command  (in  conjunction  with any string) liberally to
your code.

Try the following (after re-booting):


' Compiler version with $m
' instead of RESERVE
RESERVE 1000
$m 4711
' RESERVE will cause a quicker crash but is actually unnecessary
' The lines ending (**) will then really cause the interpreter to return a
' value of minus 4 from (FRE() MOD 16) == 0 after the RESERVE
' Because of the backtrailer with rest16$ with the compiler in case
' $m XXXX with (XXXX MOD 16)<>0
rest16%=(FRE(0) MOD 16)-4   ! **
IF rest16%<0                ! **
  ADD rest16%,16            ! **
ENDIF                       ! **
rest16$=STRING$(rest16%,0)  ! **
' (FRE() MOD 16) == 0 now fulfilled
str$="AHAH"
DO
  @crash(str$)
LOOP
PROCEDURE crash(str$)
  str$="OHOH"
RETURN

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Special thanks:

- Harald Ax for DELITE, an outstanding GFA-Shell
- Jankowski/Rabich/Reschke for his "Profibuch", an indispensable treasure.
- Karsten Isakovic for his 'SysMon', as well as
  Thomas Tempelmann and Johannes Hill for 'TempleMon'
  Both tool are known as 'The Programmers best friends' :-)
- ATARI / Landon Dyer for the 'MadMac'.
- GENESIS for 'Selling England by the pound' as well as 'Foxtrot'
  THE CURE for 'Disintegrations'
  THE RED HOT CHILI PEPPERS for 'Blood sugar sex magik'
  KING'S X  1992 (with 'Black Flag')
  TEMPLE OF THE DOG fr ihr Debtalbum
  RAGE AGAINST THE MACHINE for their debut album
  BODY COUNT & ICE-T for the Plate
- Barbara for her understanding, that gives me life without my
  computer =:^}

Have fun,
Byeeeeeeeeeeeeee, Chris
