1 - General

 "Life is a lemon and I want my money back."
                 Meat Loaf, "Bat out of Hell II - Back Into Hell"

                YOUR SECOND GFA BASIC 3.XX MANUAL
                             - or -
        HOW I LEARNED TO STOP WORRYING AND LOVE GFA-BASIC
                             PART 2
                      CHAPTER ONE - GENERAL
                          by Han Kempen

1.  GENERAL

Start-up

 Programs  in an AUTO-folder are executed automatically  after  a
reset.  The interpreter GFABASIC.PRG is a GEM-program, and cannot
be  started  in this way.  With TOS 1.4 you can  install  a  GEM-
program as auto-booting.  With older TOS-versions you could use a
program   like   HEADSTRT.PRG  in  your  AUTO-folder   to   start
GFABASIC.PRG  automatically.  But you can't start  a  GFA-program
this way.

 You  can  test  if your program is  running  as  an  interpreted
(*.GFA)  or a compiled (*.PRG) program by examining the  Basepage
of the program that called your program.  An interpreted  program
should find "GFABASIC.PRG" (or "GFABASRO.PRG") there.

 If you have written a (compiled) program that can be run  either
from the AUTO-folder or from the desktop, you can determine which
is the case:

     IF PEEK(&H2C+4)=0        ! examine Line-F vector
       (...)                  ! AUTO: GEM not activated yet
     ELSE
       (...)                  ! desktop: GEM is activated
     ENDIF

 There are several ways to (re)start your computer.  The  obvious
one is to switch the ST off,  wait a few seconds (15 seconds with
a  1040 ST!),  and switch on again.  This is called a  "cold"  or
"hard" reset.  Your computer suffers a little,  and it takes some
time.  If  you  use the reset-button on your ST,  you  perform  a
"warm"  or  "soft"  reset.  The  operating  system  automatically
performs  a  warm  reset if you switch  between  Low  and  Medium
resolution on the desktop.  If you suspect a program of  changing
system- variables,  you should always use a cold reset.  After  a
warm  reset the system-variables in low memory (below &H93A)  are
not  initialised  again.   Garbage  will  stay  there  and   will
undoubtedly lead to interesting effects.  You can perform both  a
warm and a cold reset from GFA-Basic with XBIOS 38 (Superexec):

     ' Cold reset
     SLPOKE &H420,0           ! clear system-variable memvalid
     SLPOKE &H426,0           ! clear system-variable resvalid
     SLPOKE &H43A,0           ! clear system-variable memval2
     ~XBIOS(38,L:LPEEK(4))    ! call reset-routine

     ' Warm reset
     ~XBIOS(38,L:LPEEK(4))    ! call reset-routine

 If you would like to (re)boot from your second (external)  drive
B you can use system-variable _bootdev at &H446:

     ' Warm reset from drive B
     SLPOKE &H446,1           ! boot from drive B after next reset
     ~XBIOS(38,L:LPEEK(4))    ! call reset-routine

Application

 It is convenient to install the extension GFA as an  application
for GFABASIC.PRG.  Click once on GFABASIC.PRG and choose  Install
Application  from the Options-menu.  Type GFA as  Document  Type,
click  on  OK and save the desktop.  If you double-click  a  GFA-
program  (extension .GFA) from the desktop,  GFABASIC.PRG is  now
automatically loaded first. Choosing Install Application you will
only  see the most recently installed application.  Use  a  disk-
editor  to  examine the file DESKTOP.INF and you  will  find  all
other installed applications as well (look for #G).

Monitor

 The Atari colour monitor SC1224 works with a vertical  frequency
of either 50 Hz or 60 Hz:

     SPOKE &HFF820A,254       ! 50 Hz
     SPOKE &HFF820A,252       ! 60 Hz

 For  60 Hz,  bit 1 of the Sync Mode Register is  cleared.  Don't
change bit 0,  or the video controller chip will not use the  so-
called sync pulses.  After a reset, the operating system defaults
to  50  Hz (probably 60 Hz in the USA).  The screen is  a  little
larger than at 60 Hz,  but the screen flickers slightly.  If  you
connect your ST to a PAL-TV through a modulator,  you should  use
50  Hz  (60  Hz for an NTSC-TV in the  USA).  Otherwise  you  are
advised to use 60 Hz.
 These don't work on a Falcon.

Break

 It's not easy to find in the GFA-manual:  you can stop a running
program   by   pressing  <Control>   <Left   Shift>   <Alternate>
simultaneously.  But if you're reading this text,  you know  this
already.  It's impossible to interrupt a program during DELAY! If
you  are  testing/debugging a program,  a 'Break' could  lead  to
problems such as a strange palette, no key-repeat or an invisible
screen.  Write your own Break-Procedure to restore everything  to
normal after a Break!  Or use the Break-Procedure in my  standard
program-structure STANDARD.GFA.

Operating System

 If  you program in a language like GFA-Basic,  you won't  notice
much  of  the  actual  workhorse  inside  your  ST-computer:  The
Operating System (TOS).  But even GFA-Basic does not have a Basic
equivalent for all TOS-functions, although you can use almost all
functions from GFA-Basic.

 TOS  can be divided in two main parts:  (GEM)DOS  and  GEM.  The
first is a collection of "lower level" routines for communication
with keyboard,  screen,  printer,  etc. In GFA-Basic you can call
these  routines  with  the  commands  BIOS  (Basic   Input/Output
System),   XBIOS  (eXtended  BIOS)  and  GEMDOS.   The   Graphics
Environment   Manager  (GEM)  consists  of  two  collections   of
routines:   the  VDI  (Virtual  Device  Interface)  and  the  AES
(Application Environment Services). The VDI takes care of regular
graphics and should have included GDOS (Graphics Device Operating
System).  Atari  didn't include GDOS in the VDI,  so you have  to
load  it  if  you  need  it.  Most  VDI-functions  have  a  Basic
equivalent in GFA.  The AES takes care of the communication  with
the user through menu, Alert-box, window, etc. Most AES-functions
can be accessed through the AES-library in GFA-Basic 3.

 With  GEMDOS-function 48 (Sversion) you can find the version  of
your  GEMDOS.  For  both the old TOS and the  Blitter-TOS  &H1300
(version 0.19) is returned. The French Turbo-DOS has version 0.20
and the Rainbow TOS of 1988 has version 0.21.

 Another  way  to  find out the version of TOS  uses  the  system
header of TOS (not necessarily located in ROM!):

     adr%=LPEEK(&H4F2)                 ! system-variable _sysbase
     version$=HEX$(DPEEK(adr%+2))

 The  good old ROM-TOS (1986,  actually not so good) has  version
&H0100  (1.00),  the  Mega-ST Blitter-TOS (1987)  version  &H0102
(1.02). And of course the Rainbow-TOS has version 1.04. You could
also examine the date of your TOS-version:

     date$=HEX$(LPEEK(adr%+24))

 My ancient TOS 1.00 has '11201985' as the date.

     TOS-version            Name         GEMDOS-version

     &H0100  1.00        old TOS             0.19
     &H0102  1.02        Blitter-TOS         0.19
     &H0104  1.04        Rainbow-TOS         0.21
     &H0106  1.06        STE-TOS             0.21
     &H0162  1.62        STE-TOS             0.23
     &H0205  2.05        Mega-STE-TOS        0.25
     &H0301  3.01        TOS 030             0.25

Procedures (CHAPTER.01)

50_hertz                                                 50_HERTZ
 Switch colour-monitor to 50 Hz (default after a reset):
     @50_hertz

60_hertz                                                 60_HERTZ
 Switch colour-monitor to 60 Hz (less flickering, recommended):
     @60_hertz

Reset_b                                                   RESET_B
 Reset computer from external drive B:
     @reset_b

Reset_cold                                               RES_COLD
 Execute a cold reset (= hard reset):
     @reset_cold
 This has the same effect as turning your ST off and on.

Reset_warm                                               RES_WARM
 Execute a warm reset (= soft reset):
     @reset_warm
 This  has the same effect as pressing the reset-button  on  your
ST.

Runonly_auto_patch                                        RUNONLY
 Patch the run-only interpreter GFABASRO.PRG for AUTO-starting  a
program:
     @runonly_auto_patch

Functions (CHAPTER.01)

Auto_prg                                                 AUTO_PRG
Test if program was started from AUTO-folder:
     IF @auto_prg
       ' yes, indeed started from AUTO-folder
     ELSE
       ' no, not started from AUTO-folder
     ENDIF

Tos_date$                                                TOS_DATE
Return the TOS-date:
     PRINT @tos_date$

Tos_version$                                             TOS_VERS
Return the TOS-version:
     PRINT @tos_version$