"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.
Disclaimer
The text of the articles is identical to the originals like they appeared
in old ST NEWS issues. Please take into consideration that the author(s)
was (were) a lot younger and less responsible back then. So bad jokes,
bad English, youthful arrogance, insults, bravura, over-crediting and
tastelessness should be taken with at least a grain of salt. Any contact
and/or payment information, as well as deadlines/release dates of any
kind should be regarded as outdated. Due to the fact that these pages are
not actually contained in an Atari executable here, references to scroll
texts, featured demo screens and hidden articles may also be irrelevant.