************************************************************************
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    /
/                                                                             /
/     Compiler/Library 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 (preferrably) 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 programmming 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 ther reson 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 has 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 definately advise against the $I matter in particular. It is 
  untidy or in fact lethal. Also, $U can be critical. Wirth 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 demonstartes to you in an exemplary way all of the features. This also 
uses $I+ cleany 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 - prefferrably 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 occurrance 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 orignal 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 routinmes. 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 color 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 a sclear as mud: DON'T PANIC!

The deciding factor in all this will be that progams 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 oder v_pmarker bei grob > 200 Punkten
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 conformant programming?

ANSWER:
Tim Orens ProGEM. This text from 1985, which you should be able to find in 
most mailboxes provides the best in 'Professsional 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 erros. 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 (seee 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 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 unneccessary
' 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 indispensible 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