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' (page 15) 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' (page 17) 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' (page 18) for more information. GFABUGS-folder Contains a couple of programs (*.GFA) that demonstrate certain bugs. 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 menu's, 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' guaranty 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 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' (page 14) 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 (page 12). 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. (c) 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. Use a left margin of 10 and NLQ print-quality with 1st Word Plus or other compatible wordprocessor. Examine the 'CONTENTS' (starting on page 2 in MANUAL00.DOC) and/or the 'INDEX' (starting on page 25-1 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. 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 page 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, page 3-1). 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 page (bytes) BASCODE.INL 2794 Sample 16-12 BLEND.INL 68 Blend 20-23 FASTPRT2.INL 192 Fastprint_init 9-9 GEM_IMG.INL 958 Gem_image_load_show 20-25 GISTDRVR.INL 2248 Gist_init 16-12 MAGNIFY.LST 254 Magnify 20-26 MIRROR.INL 238 Mirror 20-26 POMPOM.INL 384 Sound_pompom 16-13 SCRNCONV.INL 320 Screen_convert 20-29 SPECTR_1.INL 675 Spectrum_load_show 20-30 SPECTR_2.INL 235 Spectrum_load_show 20-30 STAR24_L.INL 2000 Screendump_star24_degas 10-4 STAR24_S.INL 2000 Screendump_star24_degas 10-4 UNPAC.INL 60 Degas_load & Degas_load_show 20-25 UNRAV.INL 40 Degas_load & Degas_load_show 20-25 15 files 12466 The 'page' in the table above refers to the page in this Manual where you can find a short description of the Procedure. Also read the paragraph 'INLINE' in chapter 4 (page 4-5). 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 (page 18) 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, page 19-4). 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 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 (page 24) for more information about the 'shell'-program. By the way, I use the point in variable-names to improve readability. 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 (page 3-10) to determine how many bytes are needed. Or you could include RESERVE (page 4-2) 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 -key esc$ - the -key help$ - the -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. 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 ( 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 (page 1-2) - Write Verify Test is switched off; read the paragraph 'Floppy Write Test' in chapter 11 (page 11-1) It should be easy to adapt START.GFA to your specific needs.