0 - Introduction

 "These liars could be telling the truth."
                                              "Cannonball Run II"

                YOUR SECOND GFA BASIC 3.XX MANUAL
                             - or -
        HOW I LEARNED TO STOP WORRYING AND LOVE GFA-BASIC
                             PART 1
                          INTRODUCTION
                          by Han Kempen

 This entire series of "GfA Basic" tutorials is based almost 100%
on  Han  Kempen's "Your Second GfA-Basic  3  Manual",  the  third
edition,  finished in 1993. Kind permission has been given by him
to  include all the text and make changes in layout and  contents
where needed.  It is estimated that this series will continue for
about 5 issues of ST NEWS, including this one. There will be bits
of source code coming with it as well,  which you will be able to
find in the "GFA" folder of the archive on this disk.
 If  you don't have the program "ST Zip" that is required to  use
this archive,  please check out ST NEWS Volume 9 Issue  1,  which
had it.
 All  source  code offered with this course if  for  "GfA  Basic"
<3.5,  which  means  there  won't  be  any  attention  to  MATRIX
commands,  TT  commands,  etc.  Most likely everything  will  run
merrily on higher versioons.  You have to take into consideration
that  most  stuff  won't work on a Falcon  unless  you  adapt  it
yourself.
 And remember...this is not just another "GfA Basic"  course.  It
covers all aspects of further computing you might ever need!

 This course is built up of 25 parts plus an  introduction.  Each
issue  will  have  a collection of parts  with  the  accompanying
source  files  and whatever other material may  be  needed.  What
follows is a list of parts per issue.

                    ST NEWS Volume 9 issue 2

INTRODUCTION

The Works
The Second Edition
The Author
The Reader
the small print
The Manual
The Library
The Standard
  STANDARD.GFA
  STNDRD.GFA
  RESTRUCT.GFA
  STANDACC.GFA
  START.GFA

1. GENERAL

Start-up
Application
Monitor
Break
Operating System
Procedures (CHAPTER.01)
Functions (CHAPTER.01)

2. THE EDITOR

Abbreviated Commands
Syntax
Folded Procedures
Tab
Cut and Paste
Load
Save
Llist
Insert-mode
Direct Mode
DEFLIST
Special Characters
Procedures (CHAPTER.02)

                    ST NEWS Volume 9 Issue 3

3. VARIABLES

Variable Type
DEFWRD
Boolean
Integer
Floating Point
String
VAR
FUNCTION
CLEAR
ERASE
DUMP
TYPE-bug
READ
SWAP
TIME$
DATE$
SETTIME
Procedures (CHAPTER.03)
Functions (CHAPTER.03)

4. MEMORY

RAM
INT{}
RESERVE
Storing data in RAM
INLINE
MALLOC
BMOVE
Procedures (CHAPTER.04)
Functions (CHAPTER.04)

5. SORT

QSORT v. SSORT
QSORT of number-arrays
QSORT of string-arrays
Binary search
Procedures (CHAPTER.05)

6. OPERATORS and NUMERICAL FUNCTIONS

Integer-commands
\
PRED and SUCC
MOD
BCLR
BSET
BCHG
BTST
LOG
SINQ and COSQ
EQV-bug
CARD and SWAP
ABS-bug
ROUND
Procedures (CHAPTER.06)
Functions (CHAPTER.06)
 
7. STRINGS

INSTR-bug
RINSTR-bug
LSET and RSET
Garbage Collection
Functions (CHAPTER.07)
 
8. KEYBOARD INPUT

INKEY$
INPUT
INPUT-bug
INPUT$
FORM INPUT
KEYTEST
KEYGET
KEYLOOK-bug
KEYPRESS
KEYDEF
Keyboard
Key-click, Key-repeat and CapsLock
Procedures (CHAPTER.08)
Functions (CHAPTER.08)

                    ST NEWS Volume 10 Issue 1

9. SCREEN OUTPUT

CLS
PRINT
LOCATE
PRINT USING
PRINT TAB
Setscreen (XBIOS 5)
Animation
Font
Procedures (CHAPTER.09)
Functions (CHAPTER.09)

10. PRINTER

Printer ready
HARDCOPY
Procedures (CHAPTER.10)
Functions (CHAPTER.10)

11. FILES

Floppy Write Test
Step Rate
RAM-disk
DFREE
DIR$()
DIR and FILES
FSFIRST and FSNEXT
EXIST
LOF
TOUCH
NAME
KILL
File Copy
Disk Format
File Allocation Table (FAT)
Sectors
Bootsector
BLOAD
INP and OUT
INPUT and LINE INPUT
STORE and RECALL
FILESELECT
Procedures (CHAPTER.11)
Functions (CHAPTER.11)

                    ST NEWS Volume 10 Issue 2

12. MIDI

INPMID$
INP
Procedures (CHAPTER.12)

 
13. MODEM

INPAUX$
INP
Rsconf (XBIOS 15)
Procedures (CHAPTER.13)
 
14. MOUSE

Editor
Fileselector
MOUSE
SETMOUSE
HIDEM
DEFMOUSE
Procedures (CHAPTER.14)
  
15. JOYSTICK

STRIG and STICK
Functions (CHAPTER.15)
  
16. SOUND

Soundchip
SOUND and WAVE
Dosound (XBIOS 32)
Samples
Speech
Soundmachine
GIST
TCB Tracker
Staccato
Music Studio
Procedures (CHAPTER.16)
Functions (CHAPTER.16)
 
17. PROGRAM DECISIONS

IF ... ENDIF
ON ... GOSUB
SELECT
SELECT-bug
 
18. PROGRAM LOOPS

Calculations
FOR ... NEXT
Loops

19. PROGRAM CONTROL

GOSUB
LOCAL
ON BREAK GOSUB
ON ERROR GOSUB
ERROR
EVERY and AFTER
REM
GOTO
DELAY-bug
STOP
CHAIN
CALL
EXEC
Procedures (CHAPTER.19)

                    ST NEWS Volume 10 Issue 3

20. GRAPHICS

Resolutions
SETCOLOR and VSETCOLOR
VSETCOLOR-bug
Palette
DEFMARK
DEFFILL
DEFLINE
DEFTEXT
GRAPHMODE
PLOT and DRAW
PLOT-bug
PCIRCLE-bug
CURVE
TEXT
SPRITE
VQT_EXTENT
Line-A
HLINE
ACHAR and ATEXT
SGET and SPUT
GET and PUT
Degas-Pictures
Other Picture-Formats
BMOVE and RC_COPY
VSYNC
BITBLT
ACLIP
Blitter
Procedures (CHAPTER.20)
Functions (CHAPTER.20)

21. EVENTS

MENU()
ON MENU BUTTON
ON MENU IBOX
ON MENU KEY
 
22. PULLDOWN MENU

OPENW 0
Desk-submenu
File-submenu
Edit-submenu
Procedures (CHAPTER.22)
 
23. WINDOWS

GFA-windows
CLOSEW
TITLEW
CLEARW

24. AES-LIBRARY

APPL_INIT
EVNT_MESAG
GRAF_GROWBOX and GRAF_SHRINKBOX
ALERT and FORM_ALERT
SHEL_GET and SHEL_PUT
Procedures (CHAPTER.24)

25. INDEX

INTRODUCTION

The Works

 My  current  contribution to the GFA-community consists  of  two
parts:

     - Your Second GFA-Basic 3 Manual ('The Manual')
     - Procedure/Function-Library ('The Library')

 Here is an overview of the complete Works:

     MANUAL-folder
     Contains the Manual in 26 1st Word Plus files  (MANUAL00.DOC
     to MANUAL25.DOC).  Also contains the file ABBREVNS.DOC. Read
     the paragraph 'The Manual' for more information.

     LIBRARY-folder
     Contains  a large collection of Procedures and Functions  in
     24  folders (CHAPTER.01 to CHAPTER.24).  Read the  paragraph
     'The  Library' (page 16) for more information.  This  folder
     also contains the folders INLINE, STANDARD and GFABUGS:

          INLINE-folder
          Contains several INLINE-files (*.INL) that are used  by
          some Procedures.  Read the paragraph 'The Library'  for
          more information.

          STANDARD-folder
          Contains some files that play an important role if  you
          adopt  my standard-structure for writing  GFA-programs.
          Read the paragraph 'The Standard' for more information.

          GFABUGS-folder
          Contains a couple of programs (*.GFA) that  demonstrate
          certain bugs.

 It  should be noted that you won't have all of these  until  the
course is complete.

The Second Edition

 If you don't have the second edition of this manual (also  known
as 'GFAXPERT' or 'GFA Expert'), you can skip this paragraph.

 The manual itself has retained the same structure, although some
chapters  have undergone a major revision.  I won't try to  point
out the differences between the second and the third edition,  so
you'll have to read the third edition yourself.  Each chapter  is
now in a separate DOC-file.

 The  Procedure-library  of the second edition did not  have  the
same  quality as the manual.  For the third edition I improved  a
lot of Procedures and Functions and I also added a few new  ones.
The  Procedures and Functions are now available as separate  LST-
files. I feel the Library is now up to par with the Manual.

 If  you already use the Standard Globals and Standard  Functions
as  recommended  in  the second  edition,  you  should  note  the
following changes:

     2nd edition         3rd edition
     scrn.x.max&         x.max&
     scrn.y.max&         y.max&
     scrn.col.max&       col.max&
     scrn.lin.max&       lin.max&
     color.index&()      setcolor&()
     Ink$                Print_ink$
     Paper$              Print_paper$

The Author

 My name is Han Kempen,  I was born in 1953 and live in the  town
of Coevorden in the Netherlands.  I'm a chemistry teacher at  the
local secondary school.  My other hobby's are Acol and GFA-Basic.
I  entered  the computer-age with a TRS-80 Model III and  am  now
quite happy with my old 1040 STf.  I am not interested in  STE's,
Mega's,  TT's  or  Falcons as long as my ST satisfies  my  modest
needs.  I  jumped  on the GFA-wagon with version 2  and  now  use
version 3.07.

 I don't program in GFA-Basic every day.  It may sound weird, but
that's the main reason I stick to GFA-Basic. I find it relatively
easy to start programming again after long computer-free periods.
GFA-Basic  probably  is  not the first  choice  for  professional
programmers,  but  for  casual users like myself  it's  the  only
choice. GFA-Basic usually is fast enough, so I don't even compile
my programs.  Interpreted programs are also convenient for sloppy
programmers like me, because I improve a program about every time
I run it.

 I still use GFA-Basic 3.07,  although I do have a legal copy  of
version 3.5.  It's just that I like 3.07,  don't have an STE  and
don't  care  about matrices.  There are a few  scattered  remarks
about version 3.5 in the Manual, but if actual 3.5 (or 3.6) users
have some useful tips I will be glad to incorporate these in  the
Manual or the Library.

 I wrote the Manual because I was disappointed by the contents of
most books about GFA-Basic 3. Some authors use page after page to
describe  a  boring  program.  Others delve  deeply  into  menus,
windows and RSC,  but ignore the 'regular' Basic-commands that  I
use all the time.  Instead of complaining, I decided to write the
book  that  I  would  really like to  see  myself.  Must  be  the
teacher's  blood  in me.  Now that you have my  Manual,  you  can
forget all other books about GFA-Basic. You need only two things:
your regular GFA-manual and my Manual. And, to be honest, perhaps
a  good book about the AES-library,  because you won't find  much
about  that  subject in this text.  Everybody is entitled  to  at
least one weak spot and AES is mine.

 In  the Library you'll find my private collection of  Procedures
and  Functions.  I'm  certain  you'll find  quite  a  few  useful
Procedures  and  Functions if you take the time  to  examine  the
Library thoroughly.  Even if you don't use the Library, it's nice
to be the proud owner of the largest collection of GFA-Procedures
and -Functions in the world.

 Of course I could write the Manual and Library only because many
GFA-users shared their experience with me. Thanks to everyone who
pointed out bugs,  mistakes and omissions in the second  edition.
Special thanks to Jan Biemans, John Hutchinson and Brian Lehne.

 I welcome any comments (bugs, improvements, additions) about the
Manual  and the Library.  I offer no 'money back' or 'disk  back'
guarantee  if you have problems with the Manual or  the  Library,
but you can always write to me. Send you letter and/or disk to:

     Han Kempen
     Rubensstraat 12
     NL-7741 AR  Coevorden
     The Netherlands

 If you have any problem with programming in GFA-Basic I will  be
happy  to  help you.  Unfortunately I don't know  everything  and
sometimes don't touch my computer for months, but I'll give it my
best shot.

The Reader

 Congratulations, you're obviously one of the happy few who still
have an Atari ST and GFA-Basic.  Although Atari and GFA  probably
will ignore us completely in the future,  you should not despair.
As the lucky owner of my Works you will be able to spend a couple
of fruitful programming-years with your obsolete ST and old  GFA-
Basic. Unless you do not have the following:

     - GFA-Basic version 3.07 or higher
     - the original manual for your GFA-Basic version
     - 1st Word Plus or compatible wordprocessor
     - double-sided drive

 Don't blame me if you don't have all of the above,  someone else
must have made a terrible mistake...

 If you only have GFA-Basic version 2,  you're in  trouble.  Some
important  commands/functions  in  version 3  can't  be  used  in
version  2.  I use word-variables as the default,  but version  2
doesn't recognize these. This means you'll have to spend a lot of
time  converting  the Library without any help from  me  or  this
Manual.  Serves you right for not noticing that you need at least
version 3.07.  All's not lost however,  because GFA-Basic version
3.5E (E = English version) is widely available for almost $ 0.00.
Of course you still have to buy the original manual for GFA-Basic
3.5E before you start any serious programming.

 I'll assume you not only have the original GFA-Basic manual, but
that  you  are familiar with both the manual and  programming  in
GFA-Basic.  Perhaps your GFA-manual is better than mine, but even
then I think you still can use my Manual to learn more about GFA-
Basic.  If  you are a novice you really should first  spend  some
time with GFA-Basic and come back to this Manual later. See you.

 Don't  forget  to read the paragraph 'the  small  print'  before
using the Manual or the Library.

 You  can  show me your gratitude for receiving  all  these  GFA-
goodies by sending me a disk or letter with your own contribution
to  the GFA-Basic world.  You'll find my address in the  previous
paragraph. Thank you.

the small print

 Please  read this paragraph carefully (for your convenience  the
letters  are enlarged) before using information from this  Manual
or using Procedures and Functions from the Library.

 You are free to use and change all files,  but only for personal
use.  If  you plan to spread my Works (Manual and Library)  among
your GFA-friends you are doing me a big favour. If you spread the
Works  you  are not allowed to change anything  in  the  original
files. Furthermore, you should assume that files in the Works are
not  'Public Domain' but 'Freeware',  unless specifically  stated
otherwise.  Freeware software can be given away only if you don't
change  anything  (not even bugs and mistakes!) in  the  original
files.

 Public  Domain Clubs may distribute the Works on disk and  BBS's
are free to make the Works available for downloading.  It is  not
necessary  to  ask  my permission to  do  so,  although  I  would
appreciate  a  short  description  of  the  way  the  Works   are
distributed.

 Please  note  that I retain the full copyright to  the  complete
Works,  but  the  distributor assumes  legal  responsibility  for
distributing  the Works.  It is possible that parts of the  Works
fall  under  the  copyright  of a third  party,  but  it  is  the
responsibility   of  the  distributor  to  check  for   copyright
infringements before distributing the Works.

 Any  part  from  the  Manual or the Library  may  be  quoted  in
newsletters   or  magazines  if  accompanied  by  the   following
reference:

    from 'Your Second GFA-Basic 3 Manual' (3rd ed.) by Han Kempen

 I  can  not be held responsible for any damage that  may  result
from using the Works.

 © Han Kempen, December 1993

The Manual

 The  folder MANUAL contains 'Your Second GFA-Basic 3 Manual'  in
26  "1st  Word  Plus"  DOC-files.  Each  chapter  of  the  Manual
(MANUAL00.DOC  to MANUAL25.DOC) can therefore be read or  printed
separately.

 The  Manual  is meant to be a supplement to your  original  GFA-
manual and can not be used as a stand-alone manual for GFA-Basic.
The  Manual is not a tutorial,  but more or less a collection  of
remarks about GFA-Basic.  The remarks are arranged in 24 chapters
that follow about the same plan as my Dutch GFA-manual.

 Obviously you already discovered the file MANUAL00.DOC,  because
you  are reading it right now.  I suggest you print  MANUAL00.DOC
and  MANUAL25.DOC first (tough!  MANUAL25.DOC is the INDEX  which
will  be  in  the last part of  the  course,  ED.).  Examine  the
'CONTENTS' (in MANUAL00.DOC) and/or the 'INDEX' (in MANUAL25.DOC)
to  find  your  favourite subjects.  My advice is  to  print  all
chapters, but I admit I'm not entirely impartial.

 The  MANUAL-folder  also contains the file  ABBREVNS.DOC  (which
will,  likewise,  be  found in the last course  instalment,  ED).
Print  this file if you need an overview of all abbreviations  of
GFA-Basic commands.

The Library

 Please read this paragraph carefully, before using the LST-files
in the Library.

 The folder LIBRARY contains a large collection of Procedures and
Functions in separate LST-files. The LST-files are grouped in the
folders CHAPTER.01 to CHAPTER.24, corresponding with the chapters
1 to 24 in this Manual.

 At  the  end  of  each chapter in this  Manual  you'll  find  an
overview  of  all Procedures and Functions in  the  corresponding
CHAPTER-folder.  The purpose of a Procedure/Function is explained
and usually a short example is included to show you how you could
use the Procedure or Function in your programs.  The name of  the
LST-file  (without  the LST-extension) is  also  mentioned.  It's
possible  that  several related LST-files are put together  in  a
separate  folder  within  a  CHAPTER-folder.  In  that  case  the
appropriate path is included in the file-name.  Sometimes you are
referred  to  a chapter in this Manual where you  can  find  more
information  about  an  important  aspect  of  the  Procedure  or
Function.  Do read that information before you try to use such  a
Procedure or Function in your own programs!

 All Procedures in the Library are folded,  but Functions are not
folded.  You can use any GFA-Basic version from 3.07 upwards.  In
the  first line of a LST-file you'll find the name of  that  file
and  a reference to this Manual.  Please read the information  in
the  Manual carefully,  before using a Procedure or  Function  in
your own programs.

 Always  read  the comment-lines in the LST-files  (preceded  by:
' *** ) before using a Procedure or Function!

 You  must  use DEFWRD "a-z" in your program before you  merge  a
LST-file  from the Library!  After Merging a LST-file  you  could
delete  the  DEFWRD-line if you don't agree with  me  that  word-
variables  should be the default (read the paragraph 'DEFWRD'  in
chapter 3).

 I   use   local   variables   whenever   possible,    but   some
Procedures/Functions  use  global variables.  In  that  case  you
should  check  your  program for the occurence  of  an  identical
global variable in order to prevent a nasty name-conflict. Global
variables  are easily spotted after ' ***  Global:  .  All  local
variables are of course listed in the LOCAL-line.

 Sometimes  another Procedure or Function is  called.  These  are
always listed after ' *** Procedure:  or ' *** Function: .

 If an INLINE-line is used, you'll find clear instructions in the
comment-lines.  You'll  have  to create  the  proper  INLINE-line
yourself (the name of the address-variable and the length of  the
line are given in the comment-lines) and then you'll have to load
the proper INLINE-file.

     INLINE-file    length    Procedure                   Chapter
                    (bytes)

     BASCODE.INL     2794     Sample                         16
     BLEND.INL         68     Blend                          20
     FASTPRT2.INL     192     Fastprint_init                 9
     GEM_IMG.INL      958     Gem_image_load_show            20
     GISTDRVR.INL    2248     Gist_init                      16
     MAGNIFY.LST      254     Magnify                        20
     MIRROR.INL       238     Mirror                         20
     POMPOM.INL       384     Sound_pompom                   16
     SCRNCONV.INL     320     Screen_convert                 20
     SPECTR_1.INL     675     Spectrum_load_show             20
     SPECTR_2.INL     235     Spectrum_load_show             20
     STAR24_L.INL    2000     Screendump_star24_degas        10
     STAR24_S.INL    2000     Screendump_star24_degas        10
     UNPAC.INL         60     Degas_load & Degas_load_show   20
     UNRAV.INL         40     Degas_load & Degas_load_show   20

     15 files       12466

 The  'chapter' in the table above refers to the chapter in  this
Manual  where you can find a short description of the  Procedure.
Also read the paragraph 'INLINE' in chapter 4.
 In  the  original version of these texts there  were  also  page
numbers but these could not be retained.

 I  strongly  recommend the use of a standard structure  in  your
GFA-programs  and especially the use of some global variables  as
Standard  Globals.  Read  the paragraph 'The  Standard'  in  this
chapter for more information.  If you don't agree with my  choice
of  Standard Globals you have to pay attention to the line '  ***
Standard:   in  the  LST-files.  In  this line  you'll  find  all
Standard  Globals that are used,  so you know immediately if  you
have to adapt the Procedure/Function.

 If you would like to change a variable-name in a  LST-file,  you
should  locate the first occurrence of the name on the  following
line:

     - variables called by value/reference: Procedure/Function-
        name
     - Standard Globals: ' *** Standard:
     - other global variables: ' *** Global:
     - local variables: LOCAL

 If you worry about the speed of your program, you could move all
remark-lines    (preceded   by   an   apostrophe)    outside    a
Procedure/Function.   Or  you  could  delete  these  remark-lines
entirely. Removing remarks after an exclamation mark doesn't make
much sense (paragraph 'REM' in chapter 19).

The Standard

 This  paragraph is essential reading for programmers  who  would
like to make optimal use of the Library.

 The STANDARD-folder (located inside the LIBRARY-folder) contains
the following files:

     STANDARD.GFA
     STNDRD.GFA
     RESTRUCT.GFA
     STANDACC.GFA
     START.GFA

STANDARD.GFA

 I don't know what a structured program is,  but I recognize  one
if I see one.  STANDARD.GFA is my way to force myself to write  a
well-structured program.  Please Llist STANDARD.GFA  now,  before
you read further.

 There  are several reasons why I developed a standard  structure
for my GFA-programs. Here is a short list:

     - a program should be well-structured
     - a program should be well-documented (plenty remarks)
     - a program should test for correct resolution
     - often-used variables should be available as Standard
        Globals
     - after a break or error the exit should be 'neat'
     - a normal exit should also be 'neat' (leave everything as
        it was)

 In the following description you'll find all the details. Let me
state  clearly that it is indeed possible to write good  programs
without  using  this standard structure.  No hard feelings  if  I
don't  succeed in converting you to my  standard  structure.  You
program your way,  and I program the right way. Just kidding. Let
me know how you think about STANDARD.GFA and what your ideas  are
about a standard structure.

 The  first  line of STANDARD.GFA is there to remind you  how  to
Save  this  file  after  you  change  anything  in  the  standard
structure.  Delete  the first two lines before you go on.  I  use
'<<<  this >>>' to indicate that the programmer has to adapt  the
listing.

*** INLINE ***

 INLINE-lines should be located above the 'WARNING'-line. Editing
the program will not result in destroying the INLINE-data. Remove
this part if you won't use INLINE-lines in your program.

 Enter the name of the program on line 8 and from now on Save the
program regularly.  While developing a program, I usually Save it
before  I  run  it.  After the first  Save  the  GFA-editor  will
remember  the  name,  so  from  now on  you  can  press  <Return>
immediately after the Fileselector appears.  On the same line  as
the name you see the GFA-version that is used (3.07 in my case).

 All  allowed  resolutions  are mentioned in  line  10  for  easy
reference.

*** Initiation ***

 Word-variables are the default and the first element of an array
has  index  0.  The TOS-screen is cleared and we  start  with  an
invisible arrow-mouse.  The path of the 'shell'-program START.GFA
is  defined  as start.gfa$.  This path is used in  the  Procedure
Program_exit.  Read the part about START.GFA for more information
about  the  'shell'-program.  By  the way,  I use  the  point  in
variable-names  to  improve readability (from what I  know  about
the new "Basic 4.00", variable names sporting points will have to
be change,  ED). In Procedures and Functions I use the underscore
for  the same purpose.   If you are going to compile the  program
later,  you  don't have to reserve memory for strings and  arrays
with  the  'm$'-command.  The  compiler  automatically  lets  the
compiled  program reserve all available memory (except 16  K  for
GEM).  For  accessories  and (true)  shell-programs  however  you
should try to use not more memory than necessary. You can use the
Procedure  Mem_test (chapter 3) to determine how many  bytes  are
needed.  Or  you could include RESERVE (chapter 4) here and  test
the GFA-program thoroughly to find out if enough memory has  been
reserved:

     $m1024              ! for compiled program
     RESERVE 1024        ! for interpreted program

 Now  the Procedure Program_init is called.  That's the heart  of
STANDARD.GFA  where  most  Standard  Globals  are  defined.   The
Procedure  is heavily commented,  but here is an overview of  all
Standard Globals anyway:

     interpreter!        - *.GFA-program, run by the interpreter
     run.only!           - *.GFA-program, run by Run-Only
                             interpreter

     default.path$       - current path

     palet.max&          - number of colours in palette
     color.max&          - number of colours on screen
     old.palet$          - the palette when the program was
                             started
     kbd.state&          - state of key-click and key-repeat

     physbase%           - address of physical screen (monitor)
     logbase%            - address of logical screen (graphical
                             output)

     white&,black&       - colours for all resolutions
     red&,green&         - colours for Medium and Low resolution
     blue&,yellow&       - colours for Low resolution only

     x.max&              - maximal x-coordinate on screen
     y.max&              - maximal y-coordinate on screen

     char.width&         - character-width of default-font in
                             pixels
     char.height&        - character-height of default-font in
                             pixels
     col.max&            - last column for PRINT
     lin.max&            - last line for PRINT

     setcolor&()         - array with SETCOLOR-indices

     high.res!           - flag for High resolution
     med.res!            - flag for Medium resolution
     low.res!            - flag for Low resolution

     standard.palet$     - standard palette for this program

     on!                 - on-switch (TRUE)
     off!                - off-switch (FALSE)

     return$             - the <Return>-key
     esc$                - the <Esc>-key
     help$               - the <Help>-key

 The Standard Global default.path$ makes it easy to locate  files
in  the same folder as your program.  In a compiled program  this
works  flawlessly,  but  in  an interpreted program  there  is  a
problem.  In  the  latter  case the path  of  the  interpeter  is
returned, not the path of your program. If an interpreted program
is  started from the 'Shell'-program START.GFA  everything  works
fine,  because  CHDRIVE and CHDIR is used before the  program  is
started.  During  the development of the  program you  could  use
CHDRIVE/CHDIR once in Direct Mode if necessary.  Another solution
is to use a (temporary) global variable during development, e.g.:

     path$="A:\GAMES\"        ! where are the data-files?

 You could leave this variable in the finished program,  but then
you  should  make  it very clear to the  user  that  the  program
expects to find files at a certain location!

 The list of Standard Globals looks formidable enough.  Your  own
list  of useful global variables probably is much  shorter.  Some
are essential because the Procedure Program_restore needs them to
exit the program 'neatly'.  A program really should try to  leave
everything  as  it  was  when  the  program  was  started.  Other
variables  are  convenient  if you try to  write  Procedures  for
different resolutions. And a few variables are included because I
use them in almost every program I write.

 While I'm developing a program I usually encounter plenty errors
and often pull the emergency-break. The Procedures Edit_break and
Edit_error are activated to take care of all the dirty work after
an unpleasant surprise. Both Procedures use Program_restore for a
neat exit.

 If you encounter too many bugs, it's not a bad idea to Merge the
Procedure  Edit_debug  (ED_DEBUG.LST  in  CHAPTER.02)  into  your
program and activate it with:

     TRON edit_debug     ! insert after 'ON BREAK GOSUB
                             edit_break'

 After removing the last bug, the program is finished. But errors
will occur, even if you think that's impossible. Now it's time to
activate the Procedure Program_error and delete all  Edit-related
Procedures.  Also activate the Procedure Program_break,  unless a
break should be impossible.
 Think hard before you decide to include 'ON BREAK CONT' in  your
program.  As  a  user  I'm strongly  against  it.  The  Procedure
Program_break  will  ask the user if he would like  to  continue,
restart or quit.  If the user decides to continue,  he is offered
the possibility to freeze the screen for a screendump. Do not use
the  Procedure  Program_error  and Program_break  in  a  compiled
program.
 It may be noted here that in "GfA Basic" versions 3.5 and up the
ON ERROR GOSUB and ON FATAL things don't work properly.

 Activate  Procedure Program_resolution to check the  resolution.
All  allowed resolutions must be mentioned in the string that  is
passed to the Procedure.

 I  use  a simple title-screen in  the  Procedure  Program_title.
Improve it, or leave it out completely.

*** Main Program ***

 Here the hard work starts, although the main program could be as
simple as:

     @start
     @game
     @finish
     @edit_exit          ! use @program_exit after debugging

 You're  almost ready now,  just a few Procedures that need  your
attention.   After   debugging  you  should  activate   Procedure
Program_exit.  This Procedure takes care of a neat exit from  the
program.

*** Standard Procedures ***

 Here you find all Procedures that are present in all programs:

     Program_init        - initialise Standard Globals
     Program_error       - process unexpected error
     Program_break       - called after user-break
     Program_resolution  - test for correct resolution
     Program_title       - simple title-screen
     Program_exit        - neat exit from program
     Program_restore     - restore original settings

 You'll  also find all Procedures here that are temporarily  used
while developing the program:

     Edit_error          - process an error
     Edit_break          - break by developer (you)
     Edit_exit           - restore settings and return to editor

 You could include the Procedure Edit_debug here.  You could also
include  a Procedure that automatically Saves your  program  when
you  start  it.  All  Edit-Procedures should be  deleted  if  the
program is debugged entirely.

*** Standard Functions ***

 Four Standard Functions are available in all programs:

     Center$             - PRINT text centered on current line
     Rev$                - PRINT text reverse
     Print_ink$          - change ink-colour (for PRINTed letters)
     Print_paper$        - change paper-colour (under PRINTed letters)

 Except  Center$ these Functions use VT52-commands,  so they  can
only be used on the TOS-screen.

*** Procedures ***  and  *** Functions ***

 Here  you put the Procedures and Functions that are called  from
the  main  program.  If  you're lucky you  can  Merge  ready-made
Procedures/Functions  of  the  shelf  (from  the  Library)  here,
otherwise you have to write these yourself.

*** Data ***

 Here you put DATA that will be used in the main  program.  There
already   are   some  DATA  that  are  used  by   the   Procedure
Program_init.

*** The End ***

 No surprises here.

 Perhaps  you  find  all this talk  about  a  standard  structure
extremely boring. But you will make other GFA-users very happy if
you spread your beautiful programs around the world only if  they
are well-structured (my way or your way) and well-documented.  If
you  feel  ashamed  about  the structure  you  could  spread  the
compiled  program  and  nobody will ever  know  how  terrible  it
looked.  But I strongly urge you to spread the (listable)  source
as well, so other GFA-users can learn from you. Don't be insulted
if others improve your program.  I certainly will not be insulted
if you send me your improved version of STANDARD.GFA.

STNDRD.GFA

 This  is  a short version of STANDARD.GFA that is  suitable  for
developing  relatively simple programs.  All Edit-Procedures  are
omitted.

RESTRUCT.GFA

 You  can use RESTRUCT.GFA to convert an existing GFA-program  to
the  standard-structure.  Read the instructions  in  RESTRUCT.GFA
before you attempt to do that.

STANDACC.GFA

 The  program STANDACC.GFA can be used to develop  an  accessory.
The program can be debugged as a GFA-program,  but after that you
should test it as an accessory:  compile it and use the extension
ACC.  Test  an  accessory  from a  floppy  disk,  not  from  your
harddisk.  A nasty bug in your accessory could lead to that  most
horrible solution of a harddisk-problem:  formatting it all  over
again.  The problem is that the faulty accessory will lead to the
abortion of the boot-up process,  so you won't reach the desktop.
That  makes  it  rather  difficult to kill  the  accessory  on  a
harddisk!  On  a floppy disk that's not a big problem,  you  just
reset  your  ST  with  another  disk in  drive  A  and  kill  the
accessory.  There  even is a solution to the harddisk-problem  if
you  think ahead.  If you use a boot-program that allows  you  to
switch  accessories  off  during boot-up you  don't  have  to  do
anything. Otherwise you could write a short emergency program:

     PRINT "Kill accessory (<Enter> to ignore): ";
     LINE INPUT acc$
     IF acc$<>""
       KILL acc$
     ENDIF

 Not  very sophisticated (you could show all active  accessories,
rename  the  accessory to *.ACX,  etc.) but it will do  the  job.
Compile it and put it in the AUTO-folder of drive C.

START.GFA

 The program START.GFA can be used as a kind of shell-program  to
run  GFA-programs  from  the interpreter.  Not a  true  shell  of
course,  but  it  'feels'  as if all GFA-programs  are  run  from
START.GFA.  In reality a GFA-program is CHAINed in START.GFA  and
after finishing the GFA-program you're CHAINed back to START.GFA.
I  guess  we  should  call  this  a  shell-chain.  The  Procedure
Program_exit  (available in STANDARD.GFA) takes care of  CHAINing
you  back.  Because  I have installed 'GFA'  as  application  for
GFABASIC.PRG  I  can  start  a  GFA-session  by   double-clicking
START.GFA on the desktop.

 If  you  decide to use START.GFA,  you should note that  in  the
current version:

     - vertical frequency is switched to 60 Hz in Medium or Low
       resolution; read the paragraph 'Monitor' in chapter 1
     - Write Verify Test is switched off; read the paragraph
         'Floppy Write Test' in chapter 11

 It should be easy to adapt START.GFA to your specific needs.