
LIST OF COMMANDS AND FUNCTIONS

      ABS

HOW:       ABS(X)

EG:        A=-2329
           PRINT ABS(A)

PURPOSE:   RETURNS THE ABSOLUTE VALUE OF A NUMBER

      
      ADD

HOW:       ADD VAR,N

EG:        ADD B,12      (Same as  LET B=B+12  but twice as fast)

PURPOSE:   INCREASE VALUE OF VAR BY N


      ALERT

HOW:       ALERT A,MESSAGE$,B,BUTTON$,VAR

EG:        M$="ARE YOU SURE| ABOUT THIS?"
           ALERT 2,M$,"YES|NO|MAYBE",B
           PRINT B

PURPOSE:   CREATES AN ALERT BOX

'A'        CHOOSES TYPE OF ALERT SYMBOL, 0=NONE, 1=!, 2=?, 3=STOP 

'MESSAGE$' CONTAINS MAIN TEXT. UP TO 4 LINES OF 30 CHARACTERS/LINE
           LINES ARE SEPARATED BY THE '|' SYMBOL
 
'BUTTON$'  CONTAINS TEXT FOR THE BUTTONS (MAX 3, MAX 8 LETTERS)  
           BUTTONS ARE SEPARATED BY THE '|' SYMBOL

'B'        ONE BUTTON CAN BE HIGHLIGHTED (0,1,2,3) THIS BUTTON
           CAN THEN BE SELECTED BY JUST PRESSING RETURN

'VAR'      THIS VARIABLE IS SET TO THE NUMBER OF THE BUTTON
           SELECTED









      ARRAYFILL

HOW:       ARRAYFILL FIELD(),N

EG:        DIM A%(3,20),B(100)
           ARRAYFILL A%(),12
           C=7
           ARRAYFILL B(),C

PURPOSE:   ASSIGNS THE VALE 'N' TO ALL ELEMENTS OF A FIELD ARRAY
           

      ARRPTR

HOW:       ARRPTR(VAR)

EG:        A$="BASIC"
           PRINT ARRPTR(A$)]
           PRINT LPEEK(ARRPTR(A$))
           PRINT DPEEK(ARRPTR(A$)+4)

PURPOSE:   FINDS THE ADDRESS OF THE (6 BYTE LONG) DISCRIPTOR OF
           A STRING OR FIELD

           THE ABOVE EXAMPLE FINDS THE START ADDRESS AND LENGTH
           OF A$


      ASC

HOW:       ASC(X$)

EG:        A$="ZX81"
           PRINT ASC(A$)

PURPOSE:   FINDS THE ASCII CODE OF THE FIRST CHARACTER OF A STRING


      ATN

HOW:       ATN(X)

EG:        INPUT SLOPE
           RAD=ATN(SLOPE/100)
           GRAD=RAD*180/PI
           PRINT GRAD

PURPOSE:   RETURNS THE ARC TANGENT OF X

           THE ABOVE EXAMPLE CALCULATES THE ROAD ANGLE FROM THE
           PERCENTAGE SLOPE GIVEN ON ROAD SIGNS.
           'PI' IS A CONSTANT IN GFA BASIC
           

      BIN$

HOW:       BIN$(X)

EG:        A=234
           PRINT BIN$(A)

PURPOSE:   CHANGES VALUE OF 'X' TO A STRING CONTAINING THE 
           BINARY VALUE OF 'X'. X CAN BE AN INTEGER FROM
           -2147483648 AND +2147485648


      BLOAD / BSAVE

HOW:       BLOAD "FILENAME" [,ADDRESS]
           BSAVE "FILENAME",ADDRESS,LENGTH

EG:        BSAVE "A:SCREEN",XBIOS(2),32000
           CLS
           BLOAD "A:SCREEN"XBIOS(2)

PURPOSE:   LOAD AND SAVE MEMORY FROM AND TO DISC DRIVE

           XBIOS(2) IS THE SCREEN START ADDRESS


      BOX

HOW:       BOX X,Y,XX,YY

EG:        BOX 10,10,20,20

PURPOSE:   DRAWS A RECTANGLE WITH DIAGONALLY OPPOSITE CORNERS
           AT (X,Y) AND (XX,YY)


      C:

HOW:       C:VAR(PARAMETERS)

EG:        Q%=VARPTR(Q$)
           A=C:Q%(17,L:0,W:-1)

PURPOSE:   CALLS A COMPILED C PROGRAM WITH TRANSFER OF 
           PARAMETERS AS IN C

           'VAR' IS A NUMERIC VARIABLE WHICH CONTAINS THE
           START ADDRESS OF A C: ROUTINE 
           'PARAMETERS' IS A LIST OF THE PARAMETERS EITHER
           AS 16 OR 32 BIT WORDS WHICH ARE TO BE PASSED TO THE
           ROUTINE 32 BIT LONG-WORDS SHOULD BE PREFIXED 'L:'
           AND 16 BIT WORDS SHOULD BE PREFIXED W: OR HAVE NO
           PREFIX

      CALL

HOW:       CALL VAR
           CALL VAR(PARAMETERS)

EG:        CALL TEST(3,I%,A$)

PURPOSE:   CALLS A MACHINE CODE PROGRAM AT ADDRESS 'VAR'
           
           'PARAMETERS' IS A LIST IF PARAMETERS WHICH ARE TO BE 
           PASSED TO THE ROUTINE. IN THE 'STACK' THE ROUTINE 
           RECEIVES THE NUMBER OF PARAMETERS AS A 16 BIT WORD AND
           THE ADDRESS OF THE LIST AS A 32 BIT LONG-WORD
           IN THE CASE OF STRINGS, THE START ADDRESS IS GIVEN.


      CHAIN

HOW:       CHAIN "FILESPEC"

EG:        SAVE "PROGRAM"
             CHAIN "PRO*"

PURPOSE:   LOADS A PROGRAM FILE INTO THE WORK AREA AND STARTS IT

           IF NO EXTENSION IS GIVEN IN THE FILE NAME THEN BASIC
           ADDS THE EXTENSION .BAS.   IF FILESPEC IS NOT IS QUOTES
           THEY ARE ASSUMED PRESENT.


      CHDIR

HOW:       CHDIR "DIRECTORY NAME"

EG:        MKDIR "\DIR1"
             MKDIR "\DIR1\DIR2"
             CHDIR "\"
             FILES
             CHDIR "\DIR1"
             FILES

PURPOSE:   CHANGES THE CURRENT DIRECTORY

           IN THE NAMING OF THE DIRECTORY THE HIERARCHICAL FILE
           SYSTEM ( \ ) CAN BE USED.

           CHDIR  "\" SWITCHES TO THE ROOT DIRECTORY.   TO SWITCH
           TO AN OTHER, THE PATH MUST BE GIVEN, ALWAYS BEGINNING
           WITH "\" WHEN STARTING OUT FROM THE ROOT.

           



      CHDRIVE

HOW:       CHDRIVE N

EG:        CHDRIVE 1
             FILES
             CHDRIVE 2
             FILES

PURPOSE:   SETS THE DEFAULT DISK DRIVE

           'N'  IS AN EXPRESSION, OF VALUE 1-15.  CHDRIVE 0 WILL
           CAUSE THE SYSTEM TO ABORT


      CLEAR

HOW:       CLEAR

EG:        A=17
             B$="BASIC"
             CLEAR
             PRINT A,B$

PURPOSE:   CLEARS ALL VARIABLES AND FIELDS

           ALL NUMERIC VARIABLES BECOME 0 AND ALL STRINGS ARE NULL
           THE COMMAND MAY NOT BE USED WITHIN PROCEDURES OR WITHIN
           FOR - NEXT LOOPS


      CLEARW

HOW:       CLEARW N

EG:        CLEARW 2

PURPOSE:   CLEARS THE CONTENTS OF THE WINDOW NUMBERED 'N'


      CLOSE

HOW:       CLOSE [ [#] N]

EG:        OPEN "O",#1,"PRO"
             PRINT #1,"GFA BASIC"
             CLOSE #1
             OPEN "I",#1,"PRO"
             INPUT #1,A$
             CLOSE
             PRINT A$

PURPOSE:   CLOSE A DATA CHANNEL OR A CHANNEL TO THE DISK DRIVE
           'N' IS A NUMBER FROM 0-99, WITHOUT IT ALL ARE CLOSED

      CLOSEW

HOW:       CLOSEW N

EG:        CLOSEW 2

PURPOSE:   CLOSED THE WINDOW NUMBERED 2

           CLOSEW 0 SWITCHES TO NORMAL SCREEN DISPLAY.  THIS 
           COMMAND MUST ONLY BE USED WHEN A WINDOW DISPLAY IS
           COMPLETED


      CLS

HOW:       CLS [#N]

EG:        PRINT AT(32,13);" PRESS A KEY! "
             A=INP(2)
             CLS

PURPOSE:   CLEARS THE SCREEN

           THIS IS IDENTICAL TO PRINT CHR$(27);"E"; AND CAUSES
           THE SCREEN TO BE CLEARED, AND THE CURSOR RETURNED TO
           THE HOME POSITION
      
           IT CAN ALSO BE USED IN DATA CHANNELS (OPENED WITH -
            OPEN "",#1,"VID:")  


      COLOR

HOW:       COLOR C

EG:        PCIRCLE 100,100,100
             COLOR 0
             LINE 0,0,200,200

PURPOSE:   SETS THE COLOUR FOR DRAWING

           THIS COMMAND IS USED WITH DRAWING COMMANDS  BOX, CIRCLE
           DRAW, ELLIPSE, LINE, PLOT AND RBOX


      CONT

HOW:       CONT

EG:        - NOT APPLICABLE -

PURPOSE:   RESUMES EXECUTION OF A PROGRAM
           THIS COMMAND IS USED ONLY IN DIRECT MODE TO CONTINUE THE
           EXECUTION OF A PROGRAM AFTER INTERRUPTION
      COS

HOW:       COS(X)

EG:        1)  INPUT RAD
               PRINT GRAD
               PRINT COS(GRAD*PI/180)

           2)  PLOT 320,300
               FOR I=1 TO 5400
                 X=I/36*COS(I*PI/180)
                 Y=I/36*SIN(I*PI/180)
                 DRAW TO 320+X,200+Y
               NEXT I

PURPOSE:   RETURNS THE COSINE OF VALUE X

           X IS AN ANGLE, FOR WHICH THE COSINE IS CALCULATED,
           IN THE RADIAN MEASURE (RAD)
           IF THE ANGLE IS TO BE INDICATED IN DEGREES, 'X' IS
           REPLACED BY GRAD*PI/180


      CVI   CVL   CVS   CVF   CVD

HOW:       CVI (X$) ... CVD (X$)
           
EG:        A=0.1111
             A$=MKF$(A)
             PRINT CVF (A$)

PURPOSE:   CHANGES CHARACTER STRINGS INTO NUMERIC VARIABLES

      CVI  CHANGES A 2-BYTE STRING INTO A 16-BIT INTEGER
      CVL     "    " 4-BYTE    "    "   " 32-BIT    "
      CVS     "    " 4-BYTE ATARI BASIC STRING INTO A NUMBER
      CVF     "    " 6-BYTE GFA     "      "    "   "   "
      CVD     "    " 8-BYTE MBASIC FORMAT  "    "   "   "

           IF THE LENGTHS ARE LONGER THAN ALLOWED, ONLY PART OF
           THE STRING WILL BE CONVERTED.  IF THEY ARE TOO SHORT
           THE VALUE 0 WILL BE RETURNED


      DATA

HOW:       DATA [CONST[,CONST] ...]

EG:        READ A,B$,C$,D,E!
             PRINT A;B$;C$;D;E!
             DATA 234,"G,F,A",  BASIC,&HFF,56

PURPOSE:   USED AS MEMORY VARIABLES WHICH CAN BE READ BY THE READ
           COMMAND

           THE CONSTANTS ARE SEPERATED BY COMMAS.  INVERTED COMMAS
           ARE ONLY NEEDED WITH STRINGS THAN CONTAIN COMMAS.  IF 
           THERE ARE ANY SPACES BEFORE OR AFTER THE COMMA THEY ARE
           TAKEN AS BEING PART OF THE STRING.  IF NOTHING FOLLOWS
           THE DATA STATEMENT, THE STRING IS TAKEN TO BE EMPTY


      DATE$

HOW:       DATE$

EG:        DEFTEXT 1,16,0,32
             PRINT DATE$
             TEST 240,180,DATE$

PURPOSE:   CREATES A DATE FUNCTION

           IT CREATES A CHARACTER STRING WHICH DISPLAYS THE SYSTEM
           DATE IN THE FORMAT:  DD.MM.YYYY


      DEC

HOW:       DEC VAR

EG:        T=TIMER
           A%=1000
           FOR I%=1 TO 1000
             DEC A%
           NEXT I%           
           PRINT (TIMER-T)/200

PURPOSE:   REDUCES THE VALUE OF 'VAR' BY 1

           IT IS IDENTICAL TO VAR=VAR-1, BUT IS 3 1/2 TIMES FASTER


      DEFFILL

HOW:       DEFFILL [C],[A],[B]     OR
             DEFFILLL [C],A$

EG:        BOX 100,100,400,300
             DEFFILL 1,2,9
             FILL 50,200
             DEFFILL ,,10
             FILL 320,200

PURPOSE:   SETS FILL-IN COLOUR AND PATTERN, OR ALLOWS USER-DEFINED
           PATTERNS

           THE PATTERN IS SET WITH 'C' AND THE COLOUR BY 'A,B'

           THE TYPE OF FILLIN IS SET BY 'A':
           0=EMPTY, 1=FILLED IN, 2=DOTS, 3=STRAIGHT LINES, 4=USERS
           24 DOTTEN PATTERS AND 12 LINED CAN BY CHOSED WITH 'B'

           A USER-DEFINED FILL PATTERN IS DEFINED IN THE SECOND
           VARIATION - DEFFILL C,A$   THIS IS ACHIEVED BY DEFINING
           A 16 X 16 BIT PATTERN ARRAY.  THE DEFINING STRING A$ IS
           THE RESULT OF LINKING (WITH +) 16 BIT-PATTERN NUMBERS
           WHICH HAVE BEEN STRUNG TOGETHER WITH THE FUNCTION MKI$,
           EACH NUMBER REPRESENTS ONE LINE OF THE ARRAY.


      DEFFN

HOW:       DEFFN NAME [(VARLIST)]=EXPRESSION CALLED UP BY:
              FN NAME [(LIST OF EXPRESSIONS)]

EG:        DO
             INPUT X
             PRINT X,FN THREE,FN MULT(10)
           LOOP
           DEFFN MULT(Y)=Y*FN THREE
           DEFFN THREE=3*X

PURPOSE:   DEFINES SPECIFIC USER FUNCTION

           THE FUNCTION IS DEFINED USING DEFFN, AND CALLED BY FN.
           
           WHEN CALLING UP THE FUNCTION BY FN OR @, ALL VARIABLES
           IN 'EXPRESSION' ARE GIVEN THE CURRENT VALUES AT THE 
           TIME AFTER WHICH THE VALUE OF THE FUNCTION IS 
           CALCULATED AND RETURNED
           ALL DEFFN FUNCTIONS ARE INTERPRETED FIRST, AND SO CAN 
           BE ANYWHERE IN THE PROGRAM


      DEFLINE

HOW:       DEFLINE (S),(B),(A),(E)    (COMMAS ARE OPTIONAL)

EG:        DEFLINE 1,10,2,1
             LINE 140,25,350,25
             PRINT AT(1,2);"A=2 E=1  B=10:"
             FOR I=1 TO 6
               PRINT "S=";I;":"
               DEFLINE I,1,0,0
               LINE 50,25+I*16,350,25+I*16
             NEXT I

PURPOSE:   SETS LINE STYLE, WIDTH & TYPE OF LINE BEGINNING AND END

           THE LINE WIDTH IN GRAFIC DOTS IS SET BY 'B'.  THE TYPE
           OF BEGINNING & END ARE SET BY 'A' AND 'E'.  0=NORMAL,
           1=ARROW, 2=ROUNDED.  'S' = LINE STYLE


      DEFLIST

HOW:       DEFLIST X

EG:        DEFLIST 0

PURPOSE:   DEFINES THE PROGRAM LISTING FORMAT

           X = 0:  THE COMMAND AND FUNCTION NAMES ARE WRITTEN  OUT 
           IN FULL IN CAPITAL LETTERS,  AND VARIABLES ARE  WRITTEN 
           IN SMALL LETTERS.

           X<>0:   THE FIRST LETTER OF FUNCTION AND VARIABLE NAMES
           ARE CAPITAL, AND THE REST ARE SMALL LETTERS


      DEFMARK


HOW:       DEFMARK [C],[A],[G]

EG:        DIM X(5),Y(5)
             DO
               FOR I=0 TO 5
               X(I)=RANDOM(640)
               Y(I)=RANDOM(400)
             NEXT I
             DEFMARK 1,RANDOM(7),0
             POLYMARK 6,X(),Y()
           LOOP

PURPOSE:   SETS COLOUR,TYPE AND SIZE OF THE CORNER POINTS TO BE
           MARK USING THE COMMAND POLYMARK

           'C' IS THE COLOUR REGISTER NUMBER
           'A' DEFINES THE TYPE OF MARK. THE FOLLOWING TYPES
           ARE POSSIBLE :-

           1=DOT
           2=PLUS SIGN
           3=ASTERISK
           4=SQUARE
           5=CROSS
           6=HASH
           ALL OTHER VALUES RETURN THE ASTERISK SYMBOL

           'G' SETS THE SIZE OF MARK


      DEFMOUSE

HOW:       DEFMOUSE N        or
           DEFMOUSE A$

EG:        FOR I=0 TO 7
             DEFMOUSE I
             PAUSE 100
           NEXT I
           X$=MKI$(1)
           Y$=MKI$(1)
           MF$=MKI$(0)
           CF$=MKI$(1)
           M$=MKI$(65535)
           FOR I=1 TO 14
             M$=M$+MKI$(32769)
           NEXT I
           M$=M$+MKI$(65535)
           C$=MKI$(0)
           FOR I=1 TO 14
             C$=C$+MKI$(36766)
           NEXT I
           C$=C$+MKI$(0)
           A$=X$+Y$+MKI$(1)+MF$+CF$+M$+C$
           PBOX 10,10,200,200
           DEFMOUSE A$
           DO
           LOOP

PURPOSE:   CHOOSES A PRE-DEFINED MOUSE FORM OR DEFINES A NEW ONE
           THE FOLLOWING MOUSE FORMS ARE AVAILABLE :-

           0=ARROW             1=EXPANDED (ROUNDED) X
           2=BEE               3=POINTING HAND
           4=OPEN HAND         5=THIN CROSSWIRE
           6=THICK CROSSWIRE   7=BOARDERED CROSSWIRE

           A MOUSE CAN BE DEFINED BY THE COMMAND DEFMOUSE A$
           16*16 DOTS ARE AVAILABLE TO CREATE A SHAPE. ALSO
           A 'MASK' MUST BE DEFINED SO THAT THE CURSOR REMAINS
           VISIBLE WHEN IT IS THE SAME COLOUR AS THE BACKGROUND
           ONE OF THE 256 DOTS MUST BE DEFINED AS THE STARTING
           POINT TO WHICH THE MOUSE FUNCTIONS WILL RELATE.
           
           THE DEFINING STRING IS COMPOSED AS FOLLOWS:-

           A$=MKI$       (X=STARTING POINT)
             +MKI$       (Y=STARTING POINT)
             +MKI$(1)
             +MKI$       (MASK COLOUR)
             +MKI$       (CURSOR COLOUR)
             +M$         (BIT PATTERN OF MASK)
             +C$         (BIT PATTERN OF CURSOR)
             

      DEFTEXT

HOW:       DEFTEXT [C],[S],[R],[G]
           (The commas can be omitted)

EG:        DEFTEXT 1,16,0,32
           TEXT 10,50,"BORDERED"
           DEFTEXT 24,900
           TEXT 500,300,"OUTLINED/UNDERLINED"

PURPOSE:   DEFINES THE COLOUR,STYLE,ROTATION AND SIZE OF TEXT
           TO BE PRINTED USING THE TEXT COMMAND
           'C' COLOUR REGISTER NUMBER
           'S' TEXT STYLE (0=NORMAL 1=BOLD 2=LIGHT 4=ITALIC
           8=UNDERLINED 16=BORDERED) THE STYLES CAN BE COMBINED
           BY ADDING THE SINGLE VALUES OF EACH TOGETHER
           eg. BOLD ITALICS WOULD BE STYLE 5 (1+5)
           'R' ROTATION ONLY THE FOLLOWING ANGLES (IN TENTHS OF
           A DEGREE) ARE POSSIBLE :-
           0 DEG (0), 90 DEG (900), 180 DEG (1800), 270 DEG(2700)
           'G' SIZE OF TEXT  4=ICON, 6=8*8 ,13=STANDARD
           32=ENLARGED PRINT


      DFREE

HOW:       DFREE(N)

EG:        PRINT DFREE(0)
           PRINT DFREE(1)

PURPOSE:   LOCATES FREE SPACE ON A DISC
           'N'=DISC DRIVE NUMBER (0-15)


      DIM

HOW:       DIM VAR(INDICES)[,VAR(INDICES),.....]

EG:        DIM A(1000),B(4,8,3)
           DIM N$(20,5)

PURPOSE:   SETS THE DIMENSIONS OF AN ARRAY OR STRING ARRAY
           MULTI-DIMENSIONAL ARRAYS ARE LIMITED TO 65535
           ELEMENTS. SINGLE DIMENSIONAL ARRAYS ARE LIMITED
           ONLY BY THE MEMORY AVAILABLE.
           
           SEE ALSO ERASE.


      DIM?

HOW:       DIM?(FIELD())

EG:        DIM A$(3,4,5)
           DIM N%(12,12)
           PRINT DIM?(A$())
           PRINT DIM?(N%())

PURPOSE:   DETERMINES THE NUMBER OF ELEMENTS IN AN ARRAY.
           NOTE THE ARRAYS HAVE AN ELEMENT '0', SO THE
           VALUES RETURNED IN THE ABOVE EXAMPLES WOULD BE
           120 AND 169

 
      DIR

           
HOW:       DIR [ "FILESPEC" [ TO "FILE" ]]

EG:        DIR "A:*.*" TO "A:CONTENTS"
           DIR "A:*.*" TO "LST:"

PURPOSE:   LISTS THE FILES ON A DISC

           'FILESPEC' IS A FILENAME WHICH NEEDS THE FOLLOWING
           SPECIFICATION :-

           THE DISC DRIVE IS SPECIFIED BY A LETTER PLACED IN FRONT 
           OF THE FILENAME AND FOLLOWED BY A COLON (eg. A: FOR 
           DISC DRIVE ). 
           IF ONE OR MORE QUESTION MARKS ARE IN A FILE NAME, ALL
           FILES WHICH CORRESPOND WITH THE FILENAME, APART FROM 
           THE QUESTION MARKS WILL BE ADDRESSED. eg.
           
           DIR "ART??.DOC"

           THIS COMMAND WOULD SEARCH FOR ALL FILES WHICH ARE FIVE
           LETTERS LONG, BEGIN WITH 'ART' AND HAVE THE EXTENSION
           DOC.

           THE CHARACTER '*' MEANS THAT A WHOLE PART OF THE FILE  
           NAME IS TO BE DISREGARDED IN THE SEARCH eg.

           DIR "J*.BAS"

           THIS COMMAND WOULD SEARCH FOR ALL FILES WHICH HAVE THE
           EXTENSION 'BAS' AND BEGIN WITH 'J'

           BY USING THE OPTIONAL ADDITION 'TO "FILE"' THE LIST
           FOUND CAN BE SENT TO ANOTHER FILE OR PRINTED OUT
           ( "LST:" )


      DIR$

HOW:       DIR$(N)

EG:        MKDIR "/TEST"
           CHDIR "/TEST"
           PRINT DIR$(0)

PURPOSE:   NAMES THE ACTIVE DIRECTORY FOR THE DISC DRIVE WITH THE
           NUMBER 'N'

           'N' IS A NUMERIC EXPRESION WHICH REPRESENTS THE THE
           VALUE OF THE DISC DRIVE NUMBER (1=A:, 2=B:,...0=ACTUAL
           DISC DRIVE).


      DIV

HOW:       DIV VAR,N

EG:        DIV NUM,X
           PRINT NUM

PURPOSE:   DVIDES THE VALUE OF VAR BY N. SAME AS VAR=VAR/N
           BUT EXECUTES 30% FASTER.


      DO....LOOP

HOW:       DO
           LOOP

EG:        DO
             INC I
             PRINT I
           LOOP

PURPOSE:   CREATES AN ENDLESS LOOP. THE PART OF THE PROGRAM
           IN BETWEEN IS REPEATED ENDLESSLY. THE LOOP CAN ONLY
           BE LEFT BY EXIT  eg. EXIT IF I=234.


      DRAW

HOW:       DRAW [ TO ] X,Y
           DRAW X1,Y1, TO X2,Y2 TO X3,Y3.......

EG:        DRAW 50,50
           DRAW TO 40,25
           DRAW 200,10 TO 200,100

PURPOSE:   DRAWS POINTS AND CONNECTS TWO OR MORE POINTS WITH
           STRAIGHT LINES
           DRAW X,Y IS THE SAME AS PLOT X,Y
           DRAW TO X,Y CONNECTS THE POINT TO THE PREVIOUSLY
           DRAWN POINT (DRAWN BY PLOT, LINE OR DRAW).

           SEE ALSO DEFLINE

      EDIT

HOW:       EDIT

EG:        PRINT "BACK TO THE EDITOR WITHOUT "
           PRINT "A PROGRAM END BOX"
           EDIT

PURPOSE:   RETURNS TO THE EDITOR.
           WHEN USED IN DIRECT MODE THE COMMAND ALLOWS A RETURN
           TO THE EDITOR. 
           IN A PROGRAM IT IS THE SAME AS END BUT WITHOUT THE
           PROGRAM END ALERT BOX.


      ELLIPSE

HOW:       ELLIPSE X,Y,RX,RY [,phi0,phi1]

EG:        ELLIPSE 100,100,30,40
           ELIPSE  200,200,30,40,900,2700

PURPOSE:   DRAWS AN ELLIPSE AT X,Y. 'RX' IS THE LENGTH OF THE 
           HORIZONTAL AXIS AND 'RY' IS THE LENGTH OF THE VERTICAL 
           AXIS.
           THE OPTIONAL ANGLES 'phi0' & 'phi1' GIVE THE START AND
           FINISH (IN TENTHS OF A DEGREE) ANGLES SHOULD ONLY A
           SEGMENT BE REQUIRED.


      END

HOW:       END

EG:        DO
             INC I
             PRINT I
             EXIT IF I=10000
           LOOP
           END

PURPOSE:   CLOSES ALL FILES AND TERMINATES PROGRAM EXECUTION CAN 
           BE USED AT ANY POINT IN A PROGRAM. ITS USE AT THE END
           OF A PROGRAM IS OPTIONAL.


      EOF

HOW:       EOF ([ # ] N)

EG:        OPEN "O",#1,"DATA"
           PRINT #1,"BEST BEFORE 17/8/26"
           CLOSE #1
           OPEN "I",#1,"DATA"
           DO
             PRINT INP(#1),EOF(#1)
             EXIT IF EOF(#1)
           LOOP
           END

PURPOSE:   DETERMINES WHETHER THE FILE POINTER FOR THE FILE WITH
           CHANNEL NUMBER 'N' IS AT THE END OF THE FILE.
           'N' IS AN INTEGER BETWEEN 0 & 99 WHICH REFERS TO THE
           CHANNEL NUMBER OF A FILE OPENED WITH THE OPEN COMMAND.
           THE LINE:  EXIT IF EOF(#1)  ABOVE AVOIDS THE ERROR
           MESSAGE: "END OF FILE REACHED EOF".
           THIS FUNCTION CAN ONLY BE USED WITH DISC FILES.
           (NOT FOR CON: LST: etc.).


      ERASE

HOW:       ERASE FIELD()

EG:        DIM A(100,50,5)
           PRINT FRE(0)
           ERASE A()
           PRINT FRE(0)
           DIM A(3000)

PURPOSE:   DELETES AN ARRAY AND RELEASES THE DIMENSIONED AREA.
           IF AN ARRAY HAS BEEN DIMENSIONED WITH DIM IT CANNOT
           BE RE-DIMENSIONED. THE ERASE COMMAND DELETES THE ARRAY
           AND THEREFORE ALLOWS IT TO BE DIMENSIONED AGAIN.
           IF AN ARRAY IS NO LONGER NEEDED FOR THE REST OF THE
           PROGRAM, AND THE AVAILABE MEMORY IS SMALL, IT IS A 
           GOOD IDEA TO ERASE IT AND FREE THE RESERVED MEMORY.

      
      ERR

HOW:       ERR

EG:        ON ERROR GOSUB Error-routine
           REM ATTEMPT TO CALCULATE THE SQUARE ROOT OF -1
           PRINT SQR(-1)
           PROCEDURE Error-routine
             PRINT "ERROR NUMBER ";ERR
           RETURN

PURPOSE:   RETURNS THE ERROR CODE OF ANY ERROR THAT HAS OCCURED.
           'ERR' IS A RESERVED NAME AND CANNOT BE USED AS A 
           VARIABLE.
      
           SEE ALSO FATAL, ERROR AND ON ERROR


      ERROR

HOW:       ERROR N

EG:        PRINT "ENTER ERROR NUMBER ";
           INPUT E
           ERROR E

PURPOSE:   SIMULATES THE OCCURENCE OF THE ERROR WITH THE ERROR
           CODE 'N' AND THE APPROPRIATE ERROR MESSAGE IS THEN
            DISPLAYED.
           'N' IS AN INTEGER BETWEEN -128 & 127


      EXIST

HOW:       EXIST ("FILESPEC")

EG:        PRINT EXIST("A:ZIRCON.DOC")

PURPOSE:   DETERMINES WHETHER A PARTICULAR FILE IS PRESENT ON
           A DISC.
           'FILESPEC' IS A FILENAME WHICH ALLOWS THE SAME
           SPECIFICATIONS AS THE DIR COMMAND.
           IF THE FILE IS PRESENT THE VALUE -1 IS RETURNED, IF
           NOT THEN THE VALUE 0 IS RETURNED.


      EXIT

HOW:       EXIT IF Condition

EG:        DO
             A=A+1
             PRINT A
             EXIT IF A=20
           LOOP

PURPOSE:   ENABLES THE EXIT FROM A LOOP.
           IF THE EXIT COMMAND IS MET WITHIN A LOOP AND THE EXIT
           CONDITION IS MET, THE PROGRAM CONTINUES FROM THE FIRST
           COMMAND AFTER THE LOOP.
           THIS COMMAND ALLOWS ANY LOOP TO BE LEFT ie: FOR...NEXT
           DO...LOOP,  REPEAT...UNTIL AND  WHILE...WEND.


      EXP

HOW:       EXP(X)

EG:        PRINT EXP(1)
           PRINT EXP(0.5)
           PRINT EXP(-2)

PURPOSE:   CALCULATES THE VALUE OF AN EXPONANT
               
              
      FATAL


HOW:       FATAL

EG:        ON ERROR GOSUB Error-routine
           ERROR 5
           PROCEDURE Error-routine
             PRINT "FATAL=";FATAL
           RETURN

PURPOSE:   RETURNS THE VAUE 0 OR -1 ACCORDING TO THE TYPE OF
           ERROR.
           ON NORMAL ERRORS THE FUNCTION RETURNS 0. THE VALUE -1
           IS RETURNED ON ALL ERRORS WHERE THE ADDRESS OF THE
           LAST EXECUTED COMMAND IS NO LONGER KNOWN.
           NORMALLY THIS IS AN OPERATING SYSTEM ERROR WHICH
           WOULD LEAD TO THE 'BOMB' ERRORS AND THE BREAKDOWN OF 
           THE PROGRAM.

      
      FIELD

HOW:       FIELD [#]N,expression AS svar .......

EG:        OPEN "R",#1,"TEST",50
           FIELD #1,20 AS A$,30 AS B$
           FOR I=1 TO 4
             INPUT "NAME1,NAME2: ",V$,N$
             LSET A$=V$
             LSET B$=N$
             PUT #1,I            
           NEXT I
           FOR I=4 DOWNTO 1
             GET #1,I
             PRINT A$,B$
           NEXT I

PURPOSE:   DIVIDES RECORDS INTO FIELDS.
           'N' IS THE CHANNEL NUMBER.
           'expression'  DEFINES THE FIELD LENGTH.
           'Svar' IS A STRING VARIABLE WHICH ACCEPTS A DATA FIELD.
           THE SECTION 'expression AS svar' CAN BE REPEATED IF THE
           RECORD IS TO BE DIVIDED INTO SEVERAL FIELDS. THE SUM OF
           THE FIELDS SHOULD EQUAL THE RECORD LENGTH.
           EACH OPEN DATA CHANNEL MAY HAVE ONLY ONE FIELD COMMAND.

           THE EXAMPLE CREATES A NAME FILE WHICH IS THEN READ IN
           REVERSE ORDER.
           GFA BASIC DOES NOT USE A BUFFER OF ITS OWN FOR THIS
           TYPE OF FILE ACCESS. THEREFORE THE COMMAND VARPTR(#N)
           IS NOT POSSIBLE.


      FILES

HOW:       FILES [ "FILESPEC" [ TO "FILE" ]] 
           
EG:        FILES "A:*.*" TO "A:CONTENTS"
           FILES "A:*.*" TO "LST:"

PURPOSE:   LISTS THE FILES ON A DISC.
           THIS COMMAND WORKS ALMOST THE SAME AS DIR, THE 
           DIFFERENCE BEING THAT FILES COMPILES A DETAILED
           DATA LISTING WHICH CONTAINS ITS LENGTH, THE TIME AND
           DATE AS WELL AS THE FILENAME
           (SEE DIR FOR FURTHER INFORMATION).


      FILESELECT

HOW:       FILESELECT "FILESPEC","FILENAME",X$

EG:        DO
             FILESELECT "/*.*",B$,A$
             EXIT IF A$=""
             PRINT A$
           LOOP

PURPOSE:   CREATES A FILESELECT BOX ON THE SCREEN
           'FILESPEC' IS THE SO-CALLED SEARCH PATH. THIS IS A
           FILE NAME WHICH ALLOWS THE USE OF THE SPECIFICATIONS
           DESCRIBED IN DIR AND THE HIERACHICAL FILE SYSTEM (/).
           'FILESPEC' HAS TO CONTAIN AT LEAST "/*.*". IN THIS 
           CASE ALL THE FILES IN THE ROOT DIRECTORY OF THE CURRENT
           DISC DRIVE IN THE FILESELECT BOX ARE SELECTED
           'X$' RETURNS AS CHOSEN FILENAME. IF THE ABORT BUTTON IS
           IS CLICKED THEN 'X$' IS RETURNED AS AN EMPTY STRING.

      
      FILL

HOW:       FILL X,Y

EG:        BOX 10,10,100,100
           DRAW 10,10,100,100
           FILL 50,30
      
PURPOSE:   FILLS A BORDERED AREA WITH A PATTERN COMMENCING AT
           THE CO-ORDINATES 'X,Y',. 
           THE FILL PATTERN CAN BE CHOSEN WITH THE COMMAND
           DEFFILL.


      FIX

HOW:       FIX(X)

EG:        A=3.1415926
           PRINT FIX(A)
           PRINT FIX(-1.99)

PURPOSE:   RETURNS THE INTEGER OF 'X' AFTER IT HAS BEEN ROUNDED.
           SAME AS INT(X) FOR POSITIVE NUMBERS BUT FOR NEGATIVE
           NUMBERS INT(-1.99)=-2 AND FIX(-1.99)=1.
           FIX IS IDENTICAL TO THE FUNCTION TRUNC AND COMPLEMENTS
           FRAC.


      FOR...NEXT

HOW:       FOR var=A [ DOWN ]TO E [ STEP S ]
           NEXT var                                                   

EG:        FOR I=3 TO 5
             FOR J=5 DOWNTO 3
               FOR K=1 TO 5 STEP 2
                 PRINT I,J,K
               NEXT K
             NEXT J
           NEXT I

PURPOSE:   CREATES A LOOP WHICH IS EXECUTED AS MANY TIMES AS
           SPECIFIED AT THE BEGINNING OF THE LOOP.
           'var' IS GIVEN THE VALUE 'A' AND THE COMMANDS BETWEEN
           THE FOR AND NEXT STATEMENTS ARE EXECUTED.
           WHEN NEXT IS ENCOUNTERED 'var' IS INCREASED BY 'S'
           (IF 'S' ISN'T GIVEN A VALUE IT DEFAULTS TO 1).
           IF 'S' HAS A NEGATIVE VALUE 'var' IS DECREMENTED.
           THE OPTIONAL COMMAND DOWNTO CAN BE USED INSTEAD OF
           SETTING 'S' TO -1.
           THE USE OF AN INTEGER VARIABLE (eg. I%) WILL SPEED
           UP THE EXECUTION OF A LOOP BY UP TO 30%.


      FORM INPUT

HOW:       FORM INPUT N,var

EG:        PRINT "ENTER YOUR NAME"
           PRINT "(MAX 15 LETTERS)"
           PRINT AT(15,15);
           FORM INPUT 15,NAME$
           PRINT "YOUR NAME IS ";NAME$

PURPOSE:   ENABLES THE INSERTION OF A CHARACTER STRING (LIMITED 
           TO 255 CHARACTERS IN LENGTH) DURING PROGRAM EXECUTION.
           'N' REPRESENTS THE MAXIMAL LENGTH OF THE CHARACTER
           STRING.
           'var' IS THE NAME OF THE STRING VARIABLE.
           BOTH <DELETE> AND <BACKSPACE> CAN BE USED AS CAN THE 
           ARROW KEYS.
           THE BUZZER SOUNDS WHEN THE MAX LENGTH IS REACHED.

      
      FRAC

HOW:       FRAC(X)

EG:        A=-10.1234
           PRINT FRAC(A)
           PRINT FRAC(3.1415926)
           PRINT TRUNC(A)+FRAC(A)

PURPOSE:   RETURNS THE DIGITS AFTER THE DECIMAL POINT IN A 
           NUMBER. 
           'X' CAN BE ANY NUMERIC EXPRESSION. IF 'X' IS AN
           INTEGER THEN A ZERO IS RETURNED.
           THEREFORE FRAC(X)=X-TRUNC(X)

      
      FRE

HOW:       FRE(X)
      
EG:        PRINT FRE(A%)
           DIM N$(1000)  
           PRINT FRE(0)

PURPOSE:   RETURNS THE AMOUNT OF MEMORY FREE (IN BYTES)
           THE PARAMETER 'X' IS DISREGARDED.
           IF THE FUNCTION FRE IS USED GFA BASIC CALCULATES
           THE AMOUNT OF FREE MEMORY AFTER DELETION OF ALL
           UNUSED AREAS (GARBAGE COLLECTION).


  
     FULLW

HOW:       FULLW N

EG:        FULLW2

PURPOSE:   ENLARGES WINDOW 'N' TO FULL SCREEN SIZE.
           'N' IS THE WINDOW NUMBER. IF THE WINDOW HAS NOT
           YET BEEN OPENED, THIS TAKES PLACE AUTOMATICALLY.


      GET

HOW:       GET [ # ] N [ ,I ]

EG:        SEE FIELD

PURPOSE:   READS A RECORD FROM A RANDOM ACCESS FILE.
           'N' IS THE CHANNEL NUMBER (1 TO 99)
           'I' IS NUMBER OF THE RECORD TO BE READ (1 TO 65535)
           IF 'I' IS NOT GIVEN THEN THE NEXT RECORD IN THE FILE
           WILL BE READ.


      GOSUB

HOW:       GOSUB name [ (LIST OF EXPRESSIONS) ]

ABBR:      GO or @

EG:        PRINT "MAIN PROGRAM"
           GOSUB Routine.1
           PRINT "BACK FROM 1"
           PROCEDURE Routine.1
             PRINT "PROCEDURE 1"
             GOSUB Routine.2(3,2)
             PRINT "BACK FROM 2"
             PRINT A,B
           RETURN
           PROCEDURE Routine.2(A,B)
             PRINT A,B
             PRINT "PROCEDURE 2"
           RETURN

PURPOSE:   BRANCHES TO THE PROCEDURE CALLED 'name'
      
           A PROCEDURE NAME CAN BEGIN WITH A DIGIT AND CONTAIN
           LETTERS, NUMBERS, DOTS AND THE UNDERLINE DASH.
           '(LIST OF EXPRESSIONS)' CONTAINS THE VALUES OF ANY
           LOCAL VARIABLES TO BE PASSED TO THE PROCEDURE.
           WHEN THE INTERPRETER COMES ACCROSS A GOSUB COMMAND,
           IT BRANCHES TO THE PROCEDURE NAMED IN THE GOSUB.
           IT IS POSSIBLE TO CALL FURTHER PROCEDURES WHILST IN
           A PROCEDURE, IT IS EVEN POSSIBLE TO CALL THE PROCEDURE
           ONE IS IN AT THE TIME (RECURSIVE CALL).

           THE ABOVE EXAMPLE CALLS THE PROCEDURE NAMED 'Routine.1'
           FROM THE MAIN PROGRAM. FROM WITHIN THIS PROCEDURE, THE 
           PROCEDURE 'Routine.2' IS CALLED AND THE VALUES 2 & 3
           ARE GIVEN TO THE LOCAL VARIABLES A & B.

           SEE ALSO PROCEDURE, RETURN AND LOCAL
                  
           
      GOTO

HOW:       GOTO label            

EG:        Start:
           PRINT "ENDLESS LOOP"
           GOTO start

PURPOSE:   ALLOWS AN UNCONDITIONAL JUMP TO A LABEL.
           'label' MUST END IN A COLON AND CAN CONSIST OF LETTERS,
           NUMBERS, DOTS, DASHES AND CAN BEGIN WITH A DIGIT.
                      
           
  
 
      GRAPHMODE

HOW:       GRAPHMODE N

EG:        DEFFILL 1,3,4
           PBOX 10,100,50,250
           GRAPHMODE 4
           DEFFILL 1,3,5
           PBOX 120,200,200,300
           GRAPHMODE 1
           PBOX 120,180,200,50
           DO
             IF K=1 THEN
               GRAPHMODE 1
             ELSE
               GRAPHMODE 3
             ENDIF
             MOUSE X,Y,K
             CIRCLE X,Y,50
             CIRCLE X,Y,50
           LOOP

PURPOSE:   SETS THE GRAPHIC MODE 1 TO 4.

           1=REPLACE     2=TRANSPARENT
           3=Xor         4=REVERSE TRANSPARENT

           THIS COMMAND DETERMINES THE GRAPHIC MODE OF THE SCREEN
           IT IS IMPORTANT WHEN PICTURES ARE TO BE DRAWN ON TOP
           OF EACH OTHER.

      
      HARDCOPY

HOW:       HARDCOPY
      
EG:        GRAPHMODE 3
           FOR I=0 TO 800
             BOX I MOD 640, I MOD 400,639-I MOD 640,399-I MOD 400
           NEXT I
           HARDCOPY

PURPOSE:   PRINTS THE SCREEN (SAME AS PRESSING <ALT> & <HELP> ).


      HEX$

HOW:       HEX$(X)

EG:        A=-1
           B=&022
           PRINT HEX$(A)
           PRINT HEX$(B)

PURPOSE:   CHANGES THE VALUE OF 'X' INTO A STRING EXPRESSION
           WHICH CONTAINS THE VALUE OF 'X' IN HEXADECIMAL FORM.
           
           SEE ALSO BIN$, OCT$, AND STR$


      IF

HOW:       IF condition [ THEN ]
             program block
             [ ELSE ]
               [ program block ]
           ENDIF

EG:        INPUT A,B
           IF A=3
             PRINT "YOU HAVE WON THE "
             IF B=3 THEN
               PRINT "JACKPOT !"
             ELSE
               PRINT "BOOBY PRIZE !"
             END IF
           ELSE
             PRINT "TRY AGAIN "
           ENDIF
           PRINT "SEE YOU SOON "

PURPOSE:   DIVIDES A PROGRAM UP INTO DIFFERENT BLOCKS DEPENDING
           ON HOW IT RELATES TO THE 'condition'.
           FOR A BETTER UNDERSTANDING OF THIS COMMAND IT WOULD
           BE A GOOD IDEA TO TRY THE ABOVE EXAMPLE.

      INC

HOW:       INC var

EG:        DO
             INC A
             EXIT IF A=100
           LOOP
           PRINT A

PURPOSE:   INCREASES THE VALUE OF 'var' BY 1. THE SAME AS
           var=var+1 BUT EXECUTES APROX 3.5 TIMES FASTER


      INFOW

HOW:       INFOW N,"STRING"

EG:        INFOW 2,"SMOKING CAN DAMAGE YOUR HEALTH"

PURPOSE:   ALLOCATES THE (NEW) INFORMATION LINE TO THE WINDOW
           WITH THE NUMBER 'N'. 
           IF THE STRING IS EMPTY THEN THE LINE IS REMOVED
           ALTOGETHER. 
           AS THE INFO LINE CANNOT BE SWITCHED ON AND OFF (GEM)
           WHEN THE WINDOW IS OPENED, INFOW HAS TO BE USED IN 
           FRONT OF OPENW WHEN AN INFORMATION LINE IS REQUIRED.
           IF THE COMMAND INFOW,N,"" IS USED ("" = NULL STRING)
           BEFORE OPENW THEN THE WINDOW WILL HAVE NO INFO LINE.


      INKEY$

HOW:       INKEY$

EG:        DO
             REPEAT
               Z$=INKEY$
             UNTIL Z$<>""
             PRINT LEN(Z$)
             PRINT LEFT$(Z$)''ASC(Z$),
             PRINT RIGHT$(Z$)''ASC(RIGHT$(Z$))
           LOOP

PURPOSE:   READS A CHARACTER FROM THE KEYBOARD.
           THIS FUNCTION RETURNS A STRING WHICH IS 2,1 OR 0
           CARACTERS LONG.
           IF THE KEY IS A NORMAL KEY, THEN ONE CHARACTER IS
           RETURNED CONTAINING THE ASCCII CODE.
           IF THE KEY IS A FUNCTION KEY OR HELP, UNDO etc.
           THEN TWO CHARACTERS ARE RETURNED. THE FIRST IS ALWAYS
           ASCCII CODE ZERO AND THE KEY CODE IS IN THE SECOND.
           


      INP

HOW:       INP(X)
           INP(#N)

EG:        OPEN "O",#1,"DAT"
           PRINT #1,"ABC"
           CLOSE #1
           OPEN "I",#1,"DAT"
           PRINT INP(#1)
           PRINT "PRESS ANY KEY TO CONTINUE"
           PRINT INP(2)

PURPOSE:   READS ONE BYTE FROM THE PERIPHERY OR FROM A FILE.
           'X' MUST HAVE A VALUE BETWEEN 0 & 5
                         
           0= LST:  1= AUX:  2= CON:  3= MID: 4=NOT POSSIBLE
           5= CON:

           THE FUNCTION INP(X) READS ONE BYTE FROM THE PERIPHERY          
           NAMED IN 'X' AND THE PROGRAM WAITS UNTIL A BYTE IS 
           ACCESSED (eg. WITH X=2 UNTIL A KEY IS PRESSED).
           INP(#N) READS ONE BYTE FROM THE FILE WITH THE DATA
           CHANNEL 'N'.

           THE FUNCTION var=BIOS(1,N) CAN BE USED TO SEE IF A 
           BYTE IS AVAILABLE.


      INPUT

HOW:       INPUT [ "TEXT"; (; or ,) ] VAR [ ,VAR.... ]              
           INPUT #N,var [ ,var.... ]

EG:        INPUT K
           PRINT AT(5,15);
           INPUT "ENTER YOUR NAME ";N$
           INPUT "Age and Address: ",A,W$

PURPOSE:   ALLOWS ENTRY OF DATA DURING PROGRAM EXECUTION

           WHEN PRINTING TEXT BEFORE INPUT, IT MUST ALWAYS BE IN
           INVERTED COMMAS.  IF THERE IS A SEMICOLON BETWEEN THE
           'TEXT' AND 'VAR' A QUESTION MARK AND A SPACE WILL BE
           DISPLAYED BEFORE THE CURSOR.  IF A COMMA IS USED, THE
           CURSOR WILL BE DIRECTLY AFTER THE LAST CHARACTER OF
           'TEXT'

           IF WRONG INFORMATION IS ENTERED FOR THE TYPE OF 'VAR',
           A BUZZER WILL SOUND AND ANOTHER ATTEMPT CAN BE MADE.

           IF THE INFORMATION HAS BEEN TAKEN FROM A FILE (USING
           INPUT #N) AN ERROR MESSAGE WILL BE DISPLAYED. A STRING
           CAN BE UPTO 255 CHARACTERS LONG.
           SPECIAL CHARACTERS CAN BE SEARCHED FOR AND ENTERED IN
           THREE DIFFERENT WAYS, BY PRESSING :-

           - <ALT> KEY TOGETHER WITH ANOTHER KEY
           - <CONTROL> AND <S> TOGETHER, FOLLOWED BY ANOTHER KEY
           - <CONTROL> AND <A> TOGETHER, FOLLOWED BY THE ASCII
             CHARACTER CODE OF THE CHOSEN KEY

           THE BEGINNING AND END OF THE TEXT CAN BE REACHED BY
           USING THE UP AND DOWN ARROR KEYS.
           IF THE INFORMATION ENTERED CONTAINS A COMMA, THEN ONLY
           THE PART BEFORE THE COMMA WILL BE ACCEPTED, HOWEVER IF
           IF THE STRING CONTAINING COMMAS IS ENTERED BETWEEN 
           INVERTED COMMAS, THE WHOLE STRING WILL BE ACCEPTED
           WITHOUT THE INVERTED COMMAS.


      INPUT$

HOW:       INPUT$(X[,#N])

EG:        OPEN "O",#1,"DAT"
           PRINT #1,"GFA BASIC"
           CLOSE #1
           OPEN "I",#1,"DAT"
           PRINT INPUT$(3,#1)
           PRINT "TYPE IN 5 CHARACTERS"
           PRINT INPUT$(5)

PURPOSE:   READS 'X' FROM THE KEYBOARD OR FILE AS A STRING

           'X' IS AN INTEGER BETWEEN 0 AND 32767 (STRING LENGTH)
           'N' IS AN INTEGER BETWEEN 0 AND 99 WHICH REPRESENTS
           THE DATA CHANNEL NUMBER OPENED WITH 'OPEN'
           IF THE OPTIONAL PART IS NOT USED, THE COMMAND FORMS A
           STRING FROM 'X' CHARACTERS FROM THE KEYBOARD.  IF THE
           OPTIONAL PART '#N' IS USED THEN A STRING OF 'X' 
           CHARACTERS WILL BE READ FROM THE FILE #N


      INSTR

HOW:       INSTR([N,]A$,B$)      OR       INSTR(A$,B$[,N])

EG:        N$="GFA BASIC"
0           S$="BASIC"
           PRINT INSTR(N$,"A")
           PRINT INSTR(4,N$,"A")
           PRINT INSTR("GFA BASIC","FB")
           PRINT INSTR(N$,S$)

PURPOSE:   SEARCHES TO SEE IF B$ IS PRESENT IN A$ AND RETURNS
           ITS POSITION.
           'N' IS A NUMERIC EXPRESSION INDICATING THE POSITION IN
           A$ AT WHICH THE SEARCH IS TO BEGIN.  IF 'N' IS NOT 
           GIVEN, THE SEARCH BEGINS AT THE FIRST CHARACTER OF A$.

           IF B$ IS FOUND IN A$ THE START POSITION IS RETURNED.

      
      INT

HOW:       INT(X)

EG:        A=3.1415926
           PRINT INT(A)
           PRINT INT(-1.001)

PURPOSE:   DETERMINES THE LARGEST INTEGER THAT IS LESS THAN OR
           EQUAL TO 'X'
      

      KILL

HOW:       KILL "FILESPEC"

EG:        OPEN "O",#1,"WUBBISH"
           CLOSE
           FILES
           KILL "WUBBISH"
           PRINT 
           FILES

PURPOSE:   DELETES A DISC FILE (ONLY ONE AT A TIME)

 
      LEFT$

HOW:       LEFT$(STRING [ ,N ] )

EG:        N$="SOCIALISM"
           PRINT LEFT$(N$)
           PRINT LEFT$(N$,2)
           PRINT LEFT$(N$,5)

PURPOSE:   RETURNS THE FIRST CHARACTER OR FIRST 'N' CHARACTERS
           OF A STRING.


      LEN

HOW:       LEN(X$)

EG:        A$="ABCDEFGHIJKLMNOPQRST"
           PRINT LEN(A$)
           PRINT LEN(A$+"UVWXYZ")

PURPOSE:   DETERMINES THE LENGTH OF A STRING.


      LET

HOW:       [ LET ] var=expression

EG:        LET A=666
           PRINT A
           REM  OR WITHOUT THE WORD 'LET'
           A=999
           PRINT A

PURPOSE:   ASSIGNS A VARIABLE WITH HE VALUE OF AN EXPRESSION.


      LINE

HOW:       LINE X,Y,XX,YY

EG:        LINE 0,0,200, 200
           LINE 200,0,0,200

PURPOSE:   CONNECTS TWO POINTS ('X,Y' & 'XX,YY') WITH A STAIGHT
           LINE.
           THIS COMMAND IS IDENTICAL TO DRAW X,Y TO XX,YY

           SEE ALSO DEFLINE


      LINE INPUT  LINE INPUT #

HOW:       LINE INPUT [ "TEXT" ; ( , ) ]var [ ,var... ]
           LINE INPUT #N,var [,var...]

EG:        LINE INPUT K$
           LINE INPUT A$,B$,C$
           PRINT AT(15,15)
           LINE INPUT "ENTER NAME" N$
           LINE INPUT "STREET & TOWN ",S$,T$

PURPOSE:   MAKES IT POSSIBLE TO ENTER A STRING DURING PROGRAM
           EXECUTION.
           'TEXT' IS A STRING WHICH IS SHOWN ON THE SCREEN PRIOR
           TO INFORMATION BEING ENTERED.
           'var' CAN BE ANY STRING VARIABLE NAME.
           THIS COMMAND IS THE SAME AS INPUT EXCEPT THAT A COMMA 
           IS TAKEN AS PART OF THE ENTERED STRING AND NOT AS A
           SEPARATOR. ONLY <RETURN> IS REGARDED AS A SEPARATOR.


      LIST

HOW:       LIST "FILENAME"

EG:        PRINT "LIST PROGRAM TO DISC AS ASCCII CODE"
           LIST "PROG"
           PRINT "LIST PROGRAM TO SCREEN"
           LIST ""

PURPOSE:   STORES THE PROGRAM CURRENTLY IN MEMORY TO DISC IN
           ASCCII FORMAT. IF THE 'FILENAME' IS AN EMPTY STRING
           (eg. "") THEN THE LISTING IS SHOWN ON THE SCREEN.
           IN ALL OTHER CASES THIS COMAND IS THE SAME AS THE 
           EDITOR MENU OPTION SAVE,A 
           PROGRAMS WHICH ARE TO BE JOINED TOGETHER USING THE
           COMMAND MERGE MUST BE SAVE USING LIST.
           IF NO FILENAME EXTENSION IS GIVEN THEN .LST IS
           ASSUMED.


      LLIST

HOW:       LLIST

EG:        PRINT "LIST PROGRAM TO PRINTER"
           LLIST

PURPOSE:   PRINTS OUT THE LISTING OF THE CURRENT PROGRAM.


      LOAD

HOW:       LOAD "FILESPEC"

EG:        SAVE "PROGRAM"
           LOAD "PROGRAM"

PURPOSE:   LOADS A PROGRAM INTO MEMORY. IF NO EXTENSION IS GIVEN
           THEN .BAS IS ASSUMED.
           FOR 'FILESPEC' SEE DIR.


      LOC

HOW:       LOC( [ # ]N)

EG:        OPEN "O",#1,"DAT"
           PRINT #1,"1234567"
           SEEK #1,3
           PRINT LOC(#1)

PURPOSE:   RETURNS THE LOCATION OF THE FILE POINTER FOR THE
           FILE WITH THE CHANNEL NUMBER 'N'
           THE LOCATION IS GIVEN IN NUMBER OF BYTES FROM THE
           START OF THE FILE.


      LOCAL

HOW:       LOCAL var [ ,var.... ]

EG:        A=1000
           PRINT A
           GOSUB sub
           PRINT A
           PROCEDURE sub
             LOCAL A 
             I=I+1
             A=I
             PRINT A
             IF I=10 THEN 
             ELSE
               GOSUB sub
             ENDIF
             PRINT A
           RETURN

PURPOSE:   DECLARES 'var' TO BE A LOCAL VARIABLE.
           'VAR' CAN BE ANY VARIABLE  (EXCEPT A FIELD (ARRAY?)
           VARIABLE ). IF THE VARIABLE IS ASSIGNED A VALUE
           FROM WITHIN A PROCEDURE, THE VALUE OF ANY VARIABLES
           WITH THE SAME NAME USED OUTSIDE THE PROCEDURE REMAINS
           UNCHANGED.
           SEE ALSO GOSUB, PROCEDURE AND RETURN.


      LOF

HOW:       LOF ([ # ]N)

EG:        OPEN "O",#1,"DAT"
           PRINT LOF(#1)
           PRINT #1,"1234567"
           PRINT LOF(#1)

PURPOSE:   DETERMINES THE LENGTH OF THE FILE (IN BYTES) WITH 
           CHANNEL NUMBER 'N'.
           SEE ALSO OPEN


      LOG  LOG10

HOW:       LOG(X)
           LOG10(X)

EG:        A=2.718281818285
           PRINT LOG(A)
           PRINT LOG(A^2)
           PRINT LOG10(10*10*10)
           PRINT LOG10(2.456)

PURPOSE:   DETERMINES THE NATURAL LOGARITHM (LOG) OR THE LOGARITHM
           BASE 10 (LOG10) OF 'X'.


      LPOS

HOW:       LPOS(N)

EG:        FOR I=1 TO 600
             LPRINT "A";
             IF LPOS(1)=30 THEN
               LPRINT
             END IF
           NEXT I

PURPOSE:   RETURNS THE COLUMN IN WHICH THE PRINTER HEAD
           (IN THE PRINTER BUFFER) IS LOCATED.
           'N' CAN BE ANY NUMBER. THE FIRST COLUMN IS '0'
           THE VALUE RETURNED BY THIS FUNCTION WILL NOT CORRESPOND
           TO THE ACTUAL POSITION OF THE PRINTER HEAD IN EVERY 
           CASE BECAUSE FOR THIS FUNCTION ONLY THE LINES ACTUALLY
           PRINTED ARE COUNTED. CR, LF AND BS [CHR$(13,10,8)] ARE
           TREATED AS A SPECIAL CASE.


      LPRINT

HOW:       LPRINT [ expressions [ , ][ ; ][ ' ]] 
      
EG:        A$="GFA"
           B=1986
           LPRINT A$'
           LPRINT B,
           LPRINT A$,B,
           LPRINT A$,B;"GFA"
           LPRINT A$'''''B
           LPRINT USING "###.##",PI*100

PURPOSE:   PRINTS DATA ON THE PRINTER.
           'expression' IS ANY NUMBER OF EXPRESSIONS SEPARATED
           BY COMMAS OR SEMICOLONS OR APOSTROPHES. IF NONE OF 
           THESE IS GIVEN A SEMICOLON IS ASSUMED.
           THIS COMMAND IS SIMILAR TO THE PRINT COMMAND IN ALL 
           RESPECTS APART FROM THE FACT THAT THE OPTION AT(X,Y)
           CANNOT BE USED.
           SEE ALSO PRINT AND PRINT USING


      LSET

HOW:       LSET var=string

EG:        A$="AAAAAAAAA"
           B$=SPACE$(7)
           C$="GFA"
           LSET A$=C$
           LSET B$="GFA-BASIC"
           PRINT A$;B$

PURPOSE:   PUTS THE 'string' IN THE STRING VARIABLE 'var' 
           JUSTIFIED TO THE LEFT. IF THE CHARACTER STRING IS
           SMALLER THAN THE VARIABLE THEN THE UNUSED PART WILL
           CONTAIN SPACES. IF THE REVERSE IS TRUE, THEN THE
           STRING WILL BE TRUNCATED FROM THE RIGHT UNTIL IT FITS
           THE VARIABLE.
           LSET IS NORMALLY USED IN CONJUNCTION WITH FIELD WHEN
           CREATING A RELATIVE FILE. IN THIS CASE THE NUMERIC
           VALUES MUSRT BE TRANSFORMED INTO STRINGS USING MKI$,
           MKS$, MKF$ OR MKD$ BEFORE THE COMMAND LSET CAN BE USED.
           LSET IS THE OPPOSITE OF THE COMMAND RSET.


      MAX

HOW:       MAX(expression [ ,expression... ])

EG:        A=17
           B=3
           A$="AAA"
           PRINT MAX(A,B,2*2)
           PRINT MAX(A$,"AAAA")

PURPOSE:   RETURNS THE GREATEST VALUE (OR LARGEST STRING) FROM
           A LIST OF EXPRESSIONS.
           'expression' IS ANY NUMERIC OR STRING EXPRESSION.
           ALL EXPRESSIONS IN THE LIST MUST BE OF THE SAME TYPE
           (i.e ALL NUMERIC OR ALL STRING).
           IF NUMBERS ARE BEING COMPARED, THE LARGEST IS RETURNED.
           IF IT IS STRINGS THENM THE OPERATOR '>' IS USED TO
           DETERMINE THE 'LARGEST' STRING.
           THE OPPOSTIE TO MAX IS MIN


      MENU

HOW:       MENU field (n)
           MENU KILL
           MENU OFF
           MENU n,x

EG:        See ON MENU GOSUB

PURPOSE:   MAKES IT POSSIBLE TO CREATE AND MODIFY MENU STRIP

           'field' IS A ONE-DIMENSIONAL FIELD OF STRING VARIABLES
           WHICH CONTAINS THE TEXT OF THE MENU STRIP. THE FIELD OF
           STRING VARIABLES MUST BE CONSTRUCTED IN THE FOLLOWING
           WAY:

           THE MENU TITLE AND ITEMS OF THE PULL-DOWN MENU MUST BE
           ENTERED ONE AFTER THE OTHER.  AN EMPTY STRING MUST
           FOLLOW EACH MENU TITLE WITH ITS RESPECTIVE PULL-DOWN
           MENU.  TWO EMPTY MUST FOLLOW THE LAST ITEM IN THE MENU.
           
           THE FIRST MENU MUST BE ENTERED IN THE FOLLOWING WAY:
           TITLE, PROGRAM INFORMATION, A SERIES OF MINUS SIGNS TO
           SEPERATE IT FROM THE REST, 6 DUMMY STRINGS (LENGTH >0)
           FOR THE DESK ACCESSORIES.
           THE MENU STRIP IS ACTIVATED AND DISPLAYED BY USING THE
           COMMAND 'MENU field()'.  THIS MENU DE-ACTIVATED BY THE
           COMMAND 'MENU KILL'.  'MENU OFF' DISPLAYS MENU TITLES
           IN THE NORMAL WAY AGAIN IF THEY WERE DISPLAYED INVERSE.
           MENU ITEMS CAN BE ALTERED BY USING 'MENU n,x'. 'n' IS
           THE ITEM NUMBER IN THE MENU AND 'x' FOR AN INTEGER FROM
           0 TO 3.

           MENU n,0 REMOVES THE TICK FROM IN FRONT OF THE MENU
                    ITEM WHICH WAS SET WITH MENU n,1

           MENU n,1 PLACES A TICK IN FRONT OF A MENU ITEM. THERE
                    MUST BE A SPACE BEFORE THE ITEM FOR IT TO WORK

           MENU n,2 THE ITEM IS WRITTEN IN PALE LETTERS AND CANNOT
                    BE CHOSEN

           MENU n,3 THE ITEM IS WRITTEN IN NORMAL LETTERING AND
                    CAN BE CHOSEN AGAIN

           A MENU ITEM CANNOT BE CHOSEN IF IT STARTS WITH A MINUS
           SIGN. (AS IN MENU N,2). DESK ACCESSORIES CAN BE 
           DEACTIVATED BY REPLACING THE SIX DUMMY STRINGS WITH
           MINUS SIGNS. IT IS ALSO POSSIBLE TO ACTIVATE AND
           DEACTIVATE THEM WITH THE OPTIONS MENU N,3 AND MENU N,2.
           SEE ON MENU GOSUB AND THE FUNCTION MENU.

           

      MENU


HOW:       MENU(N)


EG:        SEE ON MENU GOSUB

PURPOSE:   THE   FUNCTION  MENU(N)  MAKES IT POSSIBLE TO USE THE
           PARAMETERS FROM THE ON MENU GOSUB ROUTINES.

           AFTER ON MENU THE FUNCTION RETURNS THE VAUES WHICH WERE
           RETURNED WHEN 'event_multi' WAS CALLED UP.
           
           N=0 THE NUMBER OF CLICKED PULL DOWN MENUS
           N=1 TO 8 RETURNS THE CORRESPONDING MESSAGE BUFFER
           ENTRIES
           N=9 RETURNS A FLAG WHICH INDICATES WHAT THE LAST
           OCCURENCE WAS (int_out[0]).
           N=10 & N=11 RETURN THE COORDINATES WHICH MOVE THE MOUSE
           (int_out[1 & 2]).
           N=12 RETURNS THE STATUS OF THE MOUSE KEYS
           (int_out[3]).
           N=13 RETURNS THE SATE OF THE ALT KEYS.
           N=14 RETURNS THE KEY THAT WAS CLICKED AS A WORD,
           HIGH BYTE=SCAN CODE, LOW BYTE=ASCCII CODE (int_out[5]).
           N=15 RETURNS THE NUMBER OF MOUSE CLICKS (int_out[6]).
           N=16 RETURNS THE ADDRESS OF THE MENU OBJECT TREE.

           
      MID$

HOW:       MID$(string,A [ ,N ])

EG:        N$="GFA BASIC"
           PRINT MID$(N$,5)
           PRINT MID$(N$,1,3)
           PRINT MID$(N$,3,12)

PURPOSE:   RETURNS ALL OR 'N' CHARACTERS IN A STRING FROM THE 
           POSITION 'A' ONWARDS.
           IF THE OPTIONAL PARAMETER 'N' IS NOT USED, THE FUNCTION
           RETURNS ALL CHARACTERS OF THE STRING FROM 'A' ONWARDS.
           NOTE: A=0 PRODUCES THE SAME AS A=1.
           IF 'N'=0 AN EMPTY STRING IS RETURNED.


      MIN

HOW:       MIN(expression [ ,expression... ])

EG:        A=17
           B=3
           A$="AAA"
           PRINT MIN(A,B,2*2)
           PRINT MIN(A$,"AAAA")

PURPOSE:   RETURNS THE SMALLEST VALUE (OR SMALLEST STRING) FROM
           A LIST OF EXPRESSIONS.
           'expression' IS ANY NUMERIC OR STRING EXPRESSION.
           ALL EXPRESSIONS IN THE LIST MUST BE OF THE SAME TYPE
           (i.e ALL NUMERIC OR ALL STRING).
           IF NUMBERS ARE BEING COMPARED, THE SMALLEST IS RETURNED.
           IF IT IS STRINGS THENM THE OPERATOR '>' IS USED TO
           DETERMINE THE 'SMALLEST' STRING.
           THE OPPOSTIE TO MIN IS MAX


      MKDIR

HOW:       MKDIR "DIRECTORY NAME"

EG:        MKDIR "A:\DIRECTORY1"
           MKDIR "A:\DIRECTORY1\DIRECTORY2"
           FILES "A:\*.*K"
           FILES "A:\DIRECTORY1\*.*"

PURPOSE:   CREATES A NEW DIRECTORY.
           'DIRECTORY' NAME IS THE NAME OF THE NEW DIRECTORY.
           IT IS POSSIBLE TO USE THE HIERARCHICAL FILE SYSTEM (\)
           WHEN CHOOSING THE NAME.


      MKI$ MKL$ MKS$ MKF$ MKD$

HOW:       MKI$(N)
           MKL$(N)
           MKS$(N)
           MKF$(N)
           MKD$(N)

EG:        A=0.1111
           PRINT MKF$(A)
           FOR I=0 TO 5
             Z=PEEK(VARPTR(A)+I)
             PRINT Z,CHR$(Z)
           NEXT I

PURPOSE:   TRANSFORMS A NUMBER INTO A CHARACTER STRING.

           MKI$ 16-BIT NUMBER INTO A 2-BYTE STRING.
           
           MKL$ 32-BIT NUMBER INTO A 4-BYTE STRING.

           MKS$ A NUMBER INTO AN ATARI BASIC 4-BYTE FORMAT.                    
                                              
           MKF$ A NUMBER INTO GFA BASICS OWN 6-BYTE FORMAT.

           MKD$ A NUMBER INTO A MBASIC COMPATIBLE 8-BYTE FORMAT.

           EVERY NUMBER THAT IS TO BE STORED IN A RANDOM ACCESS
           FILE MUST FIRST BE TRANSFORMED WITH ON OF THE ABOVE
           FUNCTIONS.
           THE EXAMPLE ABOVE SHOWS THAT GFA BASIC STORES NUMBERS
           INTERNALLY IN THE 6-BYTE FORMAT WHICH CAN ALSO BE
           CREATED USING THE MKF$ FUNCTION.
           SEE ALSO CVI, CVL, CVS, CVF AND CVD


      MOUSE  MOUSEX  MOUSEY  MOUSEK

HOW:       MOUSE X,Y,K
           MOUSEX
           MOUSEY
           MOUSEK

EG:        DO
             MOUSE A,B,C
             PRINT AT(1,1);A,B,C
             X=MOUSEX
             Y=MOUSEY
             K=MOUSEK            
             PRINT AT(3,1);X,Y,K
           LOOP

PURPOSE:   DETERMINES THE MOUSE POSITION (X,Y) AND THE STATUS
           OF THE MOUSE BUTTONS.
           
           K=0 NO BUTTONS PRESSED
           
           K=1 LEFT BUTTON
      
           K=2 RIGHT BUTTON

           K=3 BOTH BUTTONS        
           

      MUL

HOW:       MUL var,N

EG:        A=2
           FOR I=1 TO 20
             MUL A,2
             PRINT A
           NEXT I

PURPOSE:   MULTIPLIES THE VALUE 'var' BY 'N'.
           SAME AS var=var*N BUT EXCECUTES 30% FASTER.


      NAME

HOW:       NAME "OLDFILE" AS "NEWFILE"

EG:        OPEN "O", #1,"YORK"
           CLOSE #1
           FILES
           NAME "YORK" AS "NEWYORK"
           FILES

PURPOSE:   RENAMES AN EXISTING FILE. THE CONTENTS OF THE FILE ARE
           NOT AFFECTED.
           THE COMMAND CAN REFER ONLY TO ONE DRIVE. IF 'OLDFILE'      
           IS ON DRIVE A THEN 'NEWFILE' WILL ALSO BET PUT ON THIS
           DRIVE. 
           'NEWFILE' CAN HOWEVER BE PUT INTO ANOTHER FOLDER eg.
           NAME "B:PARTS" AS "\CAR\SPARES"


      NEW

HOW:       NEW

EG:        PRINT "IS THIS A DAGGER I SEE BEFORE ME ?"
           NEW

PURPOSE:   DELETES THE PROGRAM CURRENTLY IN MEMORY AND CLEARS ALL
           VARIABLES.


      OCT$

HOW:       OCT$(X)
      
EG:        A=-1
           B=&H22
           PRINT OCT$(A)
           PRINT OCT$(234)
           PRINT OCT$(B)
           
PURPOSE:   CHANGES THE VALUE 'X' INTO A STRING CONTAINING THE
           VALUE OF 'X' IN OCTAL FORM (PREFIX &O)
           SEE ALSO HEX$, BIN$ & STR$


      ON...GOSUB

HOW:       ON expression GOSUB procedure list

EG:        DO
             INPUT A
             ON A GOSUB PRO1,PRO2
           LOOP
           PROCEDURE PRO1
             PRINT "1<=A<2"
           RETURN
           PROCEDURE PRO2
             PRINT "2<=A<3"
           RETURN

PURPOSE:   DEPENDING ON THE VALUE OF 'expression' ONE OF SEVERAL
           GIVEN PROCEDURES IS PROCESSED.
           IF THE VALUE OF 'EXPRESSION' IS GREATER THAN OR = TO 1
           AND SMALLER THAN 2, THE FIRST PROCEDURE IN THE LIST IS
           PROCESSED.
           IF THE VALUE OF 'EXPRESSION' IS GREATER THAN OR = TO 2
           AND SMALLER THAN 3, THE SECOND PROCEDURE IN THE LIST IS
           PROCESSED AND SO ON.
           IF THE VALUE DOES NOT COME IN RANGE THEN NO PROCEDURE
           WILL BE EXECUTED.


      ON BREAK  ON BREAK CONT  ON BREAK GOSUB

HOW:       ON BREAK
           ON BREAK CONT
           ON BREAK GOSUB name

EG:        ON BREAK GOSUB comment
           PRINT "INTERRUPT PROGRAM"
           REPEAT
           UNTIL MOUSEK
           ON BREAK 
           PROCEDURE comment 
             PRINT "NO INTERRUPTION POSSIBLE"
           RETURN

PURPOSE:   ON BREAK CONT MAKES IT IMPOSSIBLE TO STOP A PROGRAM
           BY PRESSING BREAK ( <ALT><SHIFT><CNTRL> ).
           ON BREAK REACTIVATES IT.
           ON BREAK GOSUB MAKES IT POSSIBLE TO JUMP TO THE 
           PROCEDURE 'name' BY THE ABOVE KEY COMBINATION.


      ON ERROR  ON ERROR GOSUB

HOW:       ON ERROR
           ON ERROR GOSUB name
           
EG:        ON ERROR GOSUB error routine
           PRINT SQR(-1)
           PRINT 3/0
           ON ERROR
           PRINT SQR(-1)
           PROCEDURE error routine
             PRINT "ERROR NO. ";ERR
             ON ERROR GOSUB error routine
             RESUME NEXT
           RETURN

PURPOSE:   PERFORMS THE PROCEDURE 'name' WHEN AN ERROR OCCURS.
           THE PROGRAM IS NOT INTERUPTED AND NO ERROR MESSAGE
           IS GIVEN. THE COMMAND MUST BE PRESENT IN THE 
           PROGRAM BEFORE THE ERROR OCCURS. THE PROGRAM WILL
           DEVIATE ONLY ONCE TO THE PROCEDURE. IF A FURTHER
           ERROR OCCURS, THE PROGRAM WILL STOP AND AN ERROR
           MESSAGE WILL BE DISPLAYED AS USUAL.
           IF IT IS NECESSARY TO DEVIATE WITH EVERY ERROR THEN
           THIS MODE MUST BE SWITCHED ON EACH TIME WITHIN THE 
           ERROR ROUTINE BY ON ERROR GOSUB BEFORE RETURNING TO
           THE MAIN PROGRAM.
           THE COMMAND OR ERROR SWITCHES THE PROGRAM BACK TO 
           THE NORMAL ERROR HANDLING PROCEDURE.

      
      ON MENU GOSUB

HOW:       ON MENU GOSUB proc1
           ON MENU KEY GOSUB proc2
           ON MENU MESSAGE GOSUB proc3
           ON MENU IBOX A,X,Y,B,H GOSUB proc4
           ON MENU OBOX A,X,Y,B,H GOSUB proc5

EG:        DIM STRIP$(50)
           FOR I=0 TO 50
             READ STRIP$(I)
             EXIT IF STRIP$(I)="***"
           NEXT I
           STRIP$(I)=""
           STRIP$(I+1)
           DATA DESK,MENUTEST
           DATA ------------------------
           DATA 1,2,3,4,5,6,""
           DATA FILE,LINE1,LINE2,LINE3,""
           DATA HELP,HELP 1, HELP 2,""
           DATA EDIT,EDIT1,EDIT2,EDIT3,QUIT
           DATA ***
           MENU STRIP$()
           OPENW 0
           ON MENU GOSUB menue
           ON MENU IBOX 1,100,100,200,100 GOSUB inbox1
           DO
             ON MENU
           LOOP
           PROCEDURE menue
             PRINT " MENU SELECTION ";
             PRINT STRIP$(MENU(0))
             IF STRIP$(MENU(0))="QUIT"
               END
             END IF
           RETURN
           PROCEDURE inbox1
             DEFMOUSE 4
             ON MENU OBOX 1,100,100,200,100 GOSUB outbox1
           RETURN
           PROCEDURE outbox1
             DEFMOUSE 0
             ON MENU IBOX 1,100,100,200,100 GOSUB inbox1
           RETURN

PURPOSE:   CERTAIN MENU ASPECTS CAN BE HANDLED USING ON MENU....
           'proc1' TO 'proc5' ARE NAMES OF PROCEDURES WHICH DEAL
           WITH CERTAIN ASPECTS OF THE MENU. 
           ON MENU GOSUB DEFINES THE PROCEDURE WHICH HANDLES MENU
           SELECTION.ON MENU KEY GOSUB DEFINES THE PROCEDURE
           WHICH HANDLES KEY INPUT.
           
           (CONT.)


           ON MENU IBOX...GOSUB  AND  ON MENU OBOX...GOSUB DEFINE
           THE PROCEDURES TO MAKE THE MOUSE MOVE IN OR OUT OF 
           PRE-DEFINED RECTANGLES. 'A' DEFINES WHICH ONE OF THE
           TWO POSSIBLE INDEPENDANT RECTANGLES WILL BE USED
           'X' AND 'Y' DEFINE THE TOP COORDINATES AND 'B' AND 'H'
           DEFINE THE WIDTH AND HEIGHT.

           THESE MENU ASPECTS CAN ONLY BE CALLED UP BY THE COMMAND
           ON MENU. THEREFORE, THIS COMMAND SHOULD BE FREQUENTLY
           USED (FOR EXAMPLE, IN A LOOP).


      OPEN

HOW:       OPEN "mode", [#]N,"FILENAME" [ ,LEN ]

EG:        OPEN "O",#1,"NAME"
           PRINT #1,"GFA BASIC"
           OPEN "I",#2,"NAME"
           DO
             EXIT IF EOF(#2)
             PRINT INPUT$(1,#2)
           LOOP
           CLOSE

PURPOSE:   OPENS A DATA CHANNEL OR A CHANNEL TO A DISC FILE.
           'mode' MUST ALWAYS BE WRITTEN IN QUOTES AND IS ONE
           OF THE FOLLOWING :-
              
           'O' OPENS A WRITE FILE CREATING A NEW FILE IF NEEDED.

           'I' OPENS A READ FILE.

           'A' ENABLES DATA TO BE ANNEXED TO AN EXISTING FILE.

           'U' READ/WRITE, BUT FILE MUST BE OPENED BY 'O' FIRST.

           'R' STANDS FOR RANDOM ACCESS FILE.

           THE FOLLOWING PREFIXES CAN ALSO BE USED AS FILENAMES :- 
                     
           'CON:'  FOR THE CONSOLE.

           'LST:'  OR 'PRN:' FOR THE PRINTER.

           'AUX:'  FOR THE SERIAL INTERFACE.

           'MID:'  FOR MIDI.

           'VID:'  FOR THE CONSOLE IN TRANSPARENT MODE
                   (COMMANDS ARE PRODUCED BUT NOT EXECUTED).

           'IKB:'  FOR DIRECT ACCESS TO THE KEYBOARD CONTROLLER.


           'LEN' IS ONLY USED IN FILES WITH RANDOM ACCESS. THE 
           LENGTH OF A FILE ENTRY IS DEFINED. IF THIS PREFIX IS
           NOT PRESENT, A LENGTH OF 128 BYTES IS DESIGNATED.
     

      OPENW

HOW:       OPENW N [ ,X,Y ]

EG:        OPENW 2,320,200

PURPOSE:   OPENS A WINDOW WITH THE NUMBER 'N'.
           THE OPTIONAL 'X & Y' DEFINE THE POINT OF CONTACT FOR
           THE FOUR POSSIBLE WINDOWS. THESE ARE ARRANGED ON THE 
           SCREEN LIKE THE FOUR QUADRANTS OF A SYSTEM OF 
           COORDINATES. THE POINT OF CONTACT CORRESPONDS WITH THE
           ORIGIN OF THE COORDINATES IN THE ANALOGY. THE NUMBERING
           OF THE WINDOWS IS SET AS FOLLOWS :-


                          1                    2

                     ---------------------------------    
                         
                          3                    4


           AFTER USING THE COMMAND OPENW 0 THE WHOLE SCREEN,
           WITHOUT THE MENU STRIP, IS USED AS A WINDOW. THE 
           STARTING POINT FOR GRAPHICS COMMANDS IS SET WITH
           OPENW 0,X,Y
                

      OUT

HOW:       OUT X,A
           OUT #N,A

EG:        OPEN "O",#1,"DATA"
           OUT #1,65
           CLOSE #1
           OPEN "I",#1,"DATA"
           PRINT INPUT$(1,#1)
           OUT 2,66

PURPOSE:   TRANSFERS A BYTE WITH THE VALUE 'A' TO A PERIPHERAL
           DEVICE OR FILE.
           'X' IS AN INTEGER FROM 0 TO 5  WHERE :-

           0=LST:   1=AUX:  2=CON:  3=MID:  4=IKB:  5=VID:     
           
           'A' IS AN INTEGER FROM 0 TO 255. IF 'A'>255 THEN
           'A' mod 256 IS SENT.

           OUT X,A SENDS THE VALUE 'A' TO THE DEVICE 'X'

           OUT #N,A SENDS THE VALUE 'A' TO A FILE CHANNEL 'N'

           

      PAUSE

HOW:       PAUSE X

EG:        PRINT "PLEASE WAIT FIVE SECONDS"
           PAUSE 250
           PRINT "READY"

PURPOSE:   INTERRUPTS A PROGRAM FOR EXACTLY  X/50 SECONDS.


      PBOX

HOW:       PBOX X,Y,XX,YY

      PCIRCLE

HOW:       PCIRCLE X,Y,R [ ,PHI0,PHI1 ]

      PELLIPSE

HOW:       PELLIPSE X,Y,RX,RY [ ,PHI0,PHI1 ]

      PRBOX

HOW:       PRBOX X,Y,XX,YY

PURPOSE:   THE FOUR COMMANDS ABOVE ARE THE SAME AS BOX, CIRCLE,
           ELLIPSE AND  RBOX EXCEPT THAT THEY DRAW FILLED SHAPES.
           THE TYPE OF FILL IS DEFINED BY THE COMMAND DEFFILL.


      PEEK  DPEEK  LPEEK

HOW:       PEEK(X)
           DPEEK(X)
           LPEEK(X)

EG:        A$="A"
           D=ARRPTR(A$)
           A=LPEEK(D)
           L=DPEEK(D+4)
           C=PEEK(A)
           PRINT "DESCRIPTOR ADDRESS"''D
           PRINT "ADDRESS"''A
           PRINT "LENGTH"''L
           PRINT "ASCCII CODE"''C

PURPOSE:   RETURNS THE CONTENTS OF THE MEMORY AT ADDRESS 'X'
           PEEK  RETURNS A 1 BYTE AT ADDRESS X
           DPEEK  RETURNS A 2 BYTE NUMBER FROM X AND X+1
           LPEEK  RETURNS A 4 BYTE NUMBER FROM X, X+1, X+2 & X+3
         
           FOR DPEEK AND LPEEK, 'X' MUST BE AN EVEN NUMBER                                             
                      

      PI

HOW:       PI

EG:        PRINT PI

PURPOSE:   RETURNS THE VALUE OF PI. THE VALUE OF PI IS
           3.141592653.....etc.


      PLOT

HOW:       PLOT X,Y

EG:        PLOT 320,200
           DEFLINE 1,6,2,2
           PLOT 30,30

PURPOSE:   PLOTS A POINT ON THE SCREENA COORDINATES 'X,Y'.
           THIS COMMAND IS THE SAME AS DRAW X,Y.
           IF A LINE WIDTH HAS BEEN SET WITH DEFLINE, IT IS
           NECESSARY TO SET THIS BACK TO 1, OTHERWISE NO DOT
           WILL BE DRAWN.
           THERE IS AN EXCEPTION TO THIS RULE: IF THE BEGINNING
           AND THE END TYPE OF DEFLINE IS 'ROUNDED DOWN', A LARGE
           DOT, VARYING IN SIZE ACCORDING TO THE WIDTH SET, WILL
           BE DRAWN (SEE EXAMPLE).



      POINT

HOW:       POINT X,Y
           
EG:        PLOT 10,10
           PRINT POINT(20,20)
           PRINT POINT(20,21)

PURPOSE:   CHECKS IF A GRAPHIC DOT (AT 'X,Y') HAS BEEN SET AND 
           RETURNS ITS COLOUR VALUE.


      POKE  DPOKE  LPOKE

HOW:       POKE X,N
           DPOKE X,N
           LPOKE X,N

EG:        A$="A"
           L=ARRPTR(A$)
           DPOKE L+4,4
           Z=VARPTR(A$)
           LPOKE Z,1111638594
           PRINT A$
           POKE Z,67
           PRINT A$

PURPOSE:   WRITES 1, 2 OR 4 BYTES INTO MEMORY AT AN ADDRESS WHICH
           STARTS AT 'X'.
           THE VALUE OF 'X' MUST BE AN EVEN NUMBER FOR DPOKE AND
           LPOKE.
           'N' MUST BE :-  

           FROM 0 TO 255 FOR POKE
           FROM 0 TO 65535 FOR DPOKE
           FROM -2147483648 TO +2147483648 FOR LPOKE

           THE COMMANDS MENTIONED HERE ALL WORK IN THE 68000
           'USER' MODE (USUALLY THE AREAS 0 TO 2047 AND THE AREA
           OVER 8MBYTES CANNOT BE USED).
           IN ORDER TO REACH THESE AREAS THE SUPERVISOR COMMANDS 
           SPOKE, SDPOKE AND SLPOKE ARE REQUIRED.

           
      POLYLINE  POLYFILL  POLYMARK

HOW:       POLYLINE N,X(),Y() [OFFSET XX,YY ]                          
           POLYFILL N,X(),Y() [OFFSET XX,YY ]   
           POLYMARK N,X(),Y() [OFFSET XX,YY ] 

EG:        DIM X(8),Y(8)
           FOR I=0 TO 8
             X(I)=320+150*SIN(I*2*PI/8)
             Y(I)=200+150*SIN(I*2*PI/8)
           NEXT I
           DEFFILL 1,2,9
           POLYFILL 9,X(),Y()            

PURPOSE:   DRAWS A (FILLED IN) SHAPE OF 'N' DOTS OR MARKS THE 
           CORNER POINTS.
           'N' STATES THE NUMBER OF DOTS (MAX 128). IF A CLOSED
           SHAPE IS TO BE DRAWN THEN THE FIRST AND LAST DOT
           POSITIONS MUST BE IDENTICAL.
           THESE COMMANDS WORK SIMILARLY TO DRAW BUT THEY ARE MUCH
           QUICKER, ESPECIALLY WITH INTEGER ARRAYS X%() AND Y%().

           X() & Y() ARE NUMERIC FIELDS (ARRAYS) WHICH CONTAIN THE
           COORDINATES OF THE 'N' DOTS FROM WHICH THE SHAPE WILL
           BE DRAWN. IT IS NECESSARY TO STORE THE FIRST DOT IN
           X(0) AND Y(0).

           IF THE OPTIONAL 'OFFSET XX,YY, IS USED THEN THE ENTIRE
           SHAPE WILL BE DRAWN RELATIVE TO THESE COORDINATES.
           
           DEFFILL DEFINES THE FILL PATTERN AND DEFMARK DEFINES
           THE TYPE OF MARK TO BE USED WITH POLYMARK.


      POS

HOW:       POS(N)

EG:        FOR I=0 TO 600
             PRINT "A";
             IF POS(1)=30 THEN
               PRINT
             END IF
           NEXT I            
 
PURPOSE:   RETURNS THE COLUMN IN WHICH THE CURSOR IS POSITIONED.
           'N', A HYPOTHETICAL ARGUMENT, IS OPTIONAL. THE COLOUMNS 
           START AT 0. THE VALUE DOES NOT ALWAYS CORRESPOND TO THE
           ACTUAL CURSOR POSITION. PRINT AT AND CURSOR COMMANDS ARE 
           IGNORED. IF OVER 80 CHARACTERS WITHOUT A CARRIAGE RETURN 
           IS PRINTED THEN POS CAN RETURN A VALUE GREATER THAN 100.
  


      PRINT  PRINT#

HOW:       PRINT [ AT(X,Y) ][ ; ][ expr [ , ][ ; ][ ' ]]
                       PRINT #N [ ,expr [ , ][ ; ][ ' ]]

ABBR.:     P OR ?

EG:        A$="GFA"
           B=1986
           PRINT A$'
           PRINT B,
           PRINT A$,B;"GFA"
           PRINT A$'''''B
           PRINT AT(77,25);A$;

PURPOSE:   DISPLAYS INFORMATION ON THE SCREEN OR SENDS IT TO
           DATA CHANNEL 'N'.
           'expr' CAN BE ANY NUMBER OF EXPRESSIONS WHICH MUST BE 
           SEPARATED BY COMMAS, SEMICOLONS OR APOSTROPHES.
           IF THESE SIGNS ARE MISSING A SEMICOLON WILL BE INSERTED
           AUTOMATICALLY.

           ; -ITEMS ARE PRINTED ONE AFTER AN OTHER IN ONE LINE.

           , -ITEMS ARE PRINTED AT INTERVALS OF 16 COLUMNS.

           ' -EACH APOSTROPHE CAUSES A SPACE TO BE PRINTED.

           IF NONE OF THE ABOVE ARE PLACED ON THE END OF 'expr'
           THEN A CARRIAGE RETURN AND LINE FEED IS MADE.
           THE OPTIONAL AT(X,Y) SPECIFIES THE ROW & COLUMN AT
           WHICH PRINTING WILL START.


      PRINT USING

HOW:       PRINT USING "FORMAT",LIST [ ; ]#
           PRINT #N,USING "FORMAT",LIST [ ; ]#

EG:        PRINT AT(7,5);USING "###.##",PI*100
           PRINT USING "A!b","LAMBDA"

PURPOSE:   ISSUES FORMATED DIGITS AND CHARACTER STRINGS.
           'FORMAT' IS A STRING EXPRESSION WHICH SETS THE PRINTING
           FORMAT (SEE BELOW). 'LIST' IS A LIST OF EXPRESSIONS
           SEPARATED BY COMMAS.

           #    RESERVES SPACE FOR FIGURES.
           .    POSITION OF THE DECIMAL POINT.
           +    EXECUTES A PLUS SIGN.
           -    RESERVES SPACE FOR A MINUS SIGN.
           *    ZEROS BEFORE THE COMMA ARE REPLACED BY * OTHERWISE
                THE SAME AS #.
          $$    PREFIX $.
           '    INSERTION OF A COMMA.     
        ^^^^    EXECUTION IN EXPONENT FORM  E+100
       ^^^^^        "     "      "     "    E+1000
           !    INDICATES THAT THE FIRST CHARACTER OF A STRING IS
                ISSUED.
           &    THE WHOLE STRING IS ISSUED.
        \..\    AS MANY CHARACTERS AS THE LENGTH OF \..\ IS ISSUED
                (INCLUDING BACK-SLASHES).
           -    PRINTS THE PROCEEDING CHARACTER.


      PROCEDURE

HOW:       PROCEDURE name [ (VARIABLE LIST) ]
                      
EG:        PRINT "MAIN PROG"
           GOSUB subr(7)
           PRINT "BACK A=";A
           PROCEDURE subr(a)
             PRINT "PROC A=";A
           RETURN
           PRINT "IS DISREGARDED"

PURPOSE:   MARKS THE BEGINNING OF A PROCEDURE.
           BASIC WILL ONLY PROCESS A PROCEDURE WHEN IT IS CALLED
           BY THE COMMAND GOSUB. IF IT COMES ACROSS THE COMMAND
           PROCEDURE DURING 'NORMAL' RUNNING OF THE PROGRAM, IT
           CONSIDERS IT TO BE THE END OF THE PROGRAM.
           (SEE GOSUB & RETURN FOR FURTHER INFORMATION).


      PUT

HOW:       PUT X,Y,A$ [ ,MODE ]

EG:        FOR I=1 TO 5
             CIRCLE 320,200,I*40
           NEXT I
           GET 0,0,320,399,A$
           PUT 320,0,A$,3

PURPOSE:   WRITES A STRING OBTAINED BY GET ONTO THE SCREEN AS A
           BIT PATTERN. 'X,Y' MARKS THE STARTING POINT OF THE 
           BLOCK. 'A$' IS A STRING VARIABLE WHICH HOLDS THE BIT
           PATTERN DATA. 'MODE' IS A NUMBER (0 TO 15) WHICH
           DEFINES THE WAY IN WHICH THE STRING WILL BE DISPLAYED
           ON THE SCREEN.
      
           0 = DELETE                 8 = NOT (S OR B)
           1 = S AND B                9 = NOT (S OR B)
           2 = S AND (NOT B)         10 = NOT B (INVERSE)
           3 = S (OVERWRITE)         11 = S OR (NOT B)
           4 = (NOT S) AND B         12 = NOT S (INV. OVERWRITE)
           5 = B (DO NOTHING)        13 = (NOT S) OR B
           6 = S XOR B               14 = NOT (A AND B)
           7 = S OR B                15 = 1                              

           
      PUT

HOW:       PUT [ # ]N[ ,I ]             

EG:        SEE FIELD

PURPOSE:   WRITES A RECORD TO A RANDOM ACCESS FILE.
           'N' DATA CHANNEL NUMBER (0 TO 99).
           'I' IS AN INTEGER EXPRESSION BETWEEN 1 AND THE NUMBER
           OF RECORDS IN THE FILE (MAX 65535) AND DENOTES THE
           RECORD NUMBER OF THE RECORD TO BE WRITTEN.
           IF I IS NOT USED THEN THE NEXT RECORD IN THE FILE WILL
           BE WRITTEN.


      QUIT

HOW:       QUIT

EG:        INPUT "ENTER PASSWORD! ";P$
           IF P$<>"SPLIB IBBLE LIBBLE IB" THEN
             QUIT
           ENDIF

PURPOSE:   CAUSES A RETURN TO THE GEM DESKTOP, SAME AS SYSTEM.


      RANDOM

HOW:       RANDOM(X)

EG:        PRINT "DIE THROW=";RANDOM(6)+1

PURPOSE:   RETURNS A RANDOM INTEGER BETWEEN 0 (INCLUSIVE) AND 
           'X' (EXCLUSIVE).

           RANDOM(X) = TRUNC(X*RND)


      RBOX

HOW:       RBOX X,Y,XX,YY

EG:        RBOX 50,50,590,350

PURPOSE:   DRAWS A RECTANGLE WITH ROUNDED CORNERS FROM THE TWO
           DIAGONALLY OPPOSITE CORNER POINTS 'X,Y' AND 'XX,YY'

           SEE ALSO DEFLINE


      READ

HOW:       READ var [ ,var0 ] ......

EG:        READ P,N$,Z%
           PRINT P'N$'Z%
           DATA LONDON.W1

PURPOSE:   READS VALUES FROM A DATA COMMAND AND ASSIGNS THEM TO A
           VARIABLE 'var'.

           THE VALUES READ FROM THE DATA LINES MUST BE OF A TYPE
           WHICH CORRESPONDS TO THE VARIABLE IN THE READ COMMAND.
           (IMPORTANT  SEE ALSO DATA AND RESTORE).

      
      RELSEEK

HOW:       RELSEEK [#]N,X

EG:        OPEN "O",#1,"DATA"
           PRINT #1,"1234567890"
           SEEK #1,8
           RELSEEK #1,-5
           PRINT LOC(#1)

PURPOSE:   MOVES THE RANDOM ACCESS FILE POINTER FORWARD (+X) OR
           BACKWARDS (-X) 'X' NUMBER OF BYTES.


      REM

HOW:       REM remark

ABBR.:     R OR '

EG:        REM calculation of distance
           LET S= (A*T*T)/2

PURPOSE:   WHATEVER FOLLOWS A REM COMMAND ON A PARTICULAR LINE
           IS IGNORED BY BASIC.
           REM CAN BE USED TO PUT REMARKS INTO A PROGRAM TO MAKE
           THE LISTING MORE READABLE. IT CAN ALSO BE USED TO
           DEACTIVATE A LINE OF CODE TO AID IN DEBUGGING.


      REPEAT...UNTIL

HOW:       REPEAT
           UNTIL end

EG:        REPEAT
             A=A+1
             PRINT A
           UNTIL A=20
           
PURPOSE:   CREATES A PRE-DEFINED LOOP. THE SECTION OF THE PROGRAM
           BETWEEN REPEAT AND UNTIL IS REPEATED CONTINUOUSLY 
           UNTIL THE CONDITION IS FULFILLED.
           THE CONDITION IS CHECKED AT THE END OF THE LOOP ie.
           THE LOOP HAS TO BE COMPLETED AT LEAST ONCE.

           
      RESTORE

HOW:       RESTORE [label]

EG:        RESTORE
           READ A,B,C,D
           RESTORE Other
           READ E$,F,G,H
           DATA 1,2,3,4
           Other:
           DATA MORE,5,6,7

PURPOSE:   PLACES THE DATA POINTER AT THE BEGINNING, OR BEHIND THE
           LABEL NAMES 'label'

           'label' CAN BE ANY LIST OF CHARACTERS AND CAN CONTAIN
           DIGITS, LETTERS, UNDERSCORE AND FULL STOPS.  UNLIKE
           OTHER VARIABLE NAMES IT CAN BEGIN WITH A DIGIT.
           IF NO LABEL IS SPECIFIED, THE POINTER IS SET TO THE
           FIRST DATA STATEMENT.


           RESUME

HOW:       RESUME    RESUME NEXT    RESUME label

EG:        see ON ERROR GOSUB

PURPOSE:   EXITS OUT OF AN ERROR ROUTINE

           RESUME REPEATS THE ERRONEOUS COMMAND.  RESUME NEXT
           RESUMES PROGRAM EXECUTION AFTER AN INCORRECT COMMAND.
           RESUME 'label' BRANCHES TO THE 'label'.

           IF A FATAL ERROR OCCURS ONLY RESUME 'label' IS POSSIBLE


           RETURN

HOW:       RETURN

EG:        PRINT "main program"
           GOSUB sub
           PRINT "return"
           PROCEDURE sub
             PRINT "procedure"
           RETURN

PURPOSE:   TERMINATES A SUB-ROUTINE

           IF THE INTERPRETER COMES ACROSS THE COMMAND RETURN IN A
           PROCEDURE (SUB-ROUTINE) EXECUTION IS CONCLUDED AND
           EXECUTION CONTINUES AFTER THE GOSUB COMMAND WHICH MADE
           THE PROGRAM BRANCH OFF INTO THAT PROCEDURE.  LOCAL
           VARIABLES ARE DELETED.

           (see GOSUB, PROCEDURE, LOCAL)


      RIGHT$

HOW:       RIGHT$(string[,n])

EG:        N$="GFA BASIC"
           PRINT RIGHT$(N$)
           PRINT RIGHT$(N$,5)
           PRINT RIGHT$(N$,12)

PURPOSE:   RETURNS THE LAST CHARACTERS OR 'n' NUMBER OF CHARACTERS
           (FROM THE RIGHT) OF A CHARACTER STRING 'string'

           'string' IS A CHARACTER STRING OR STRING VARIABLE.  'n'
           IS, LOGICALLY ENOUGH, A NATURAL DIGIT OR A VARIABLE.
           (DECIMAL DIGITS CAN ALSO BE USED, IN WHICH CASE THE 
           EDITOR WILL ONLY CONSIDER THE WHOLE NUMBER OF THE
           DECIMAL)

           IT FUNCTION PRODUCES A PARTIAL STRING OF 'n' CHARACTERS
           (STARTING FROM THE RIGHT) - SPACES INCLUDED. IF THE
           OPTIONAL 'n' IS NOT USED, THE FUNCTION RETURNS THE LAST
           CHARACTER OF THE CHARACTER STRING 'string'.  IF 'n' IS
           GREATER THAN THE NUMBER OF CHARACTERS IN 'string' THEN
           THE WHOLE OF 'string' IS RETURNED.  IF 'n' IS ZERO, AN
           EMPTY STRING IS RETURNED.


      RMDIR

HOW:       RMDIR "directory name"

EG:        MKDIR "A:DIRECTORY"
           FILES "A:*.*"
           RMDIR "A:DIRECTORY"
           FILES "A:*.*"

PURPOSE:   DELETES EMPTY DIRECTORIES

           FOR 'directory name' - See MKDIR

           WHEN DELETING FROM A SPECIFIC DIRECTORY THE DIRECTORY
           SEARCH PATH MUST BE ENTERED IN FRONT OF THE DIRECTORY
           NAME.  FROM A ROOT DIRECTORY, THIS ALWAYS BEGINS WITH
           '\', FOR EXAMPLE, RMDIR "\vehicle\driver" WOULD DELETE
           A DIRECTORY 'driver' FROM 'vehicle' IN THE ROOT.


      RND

HOW:       RND [(x)]

EG:        FOR I=1 TO 20
             PRINT RND
           NEXT I

PURPOSE:   RETURNS A RANDOM NUMBER BETWEEN 0 AND 1

           THE OPTIONAL PARAMETER (x) IS DISREGARDED.  RND RETURNS
           A RANDOM NUMBER BETWEEN 0 (INCLUSIVE) AND 1 (EXCLUSIVE)
           IT IS POSSIBLE TO CREATE RANDOM NUMBERS BETWEEN 1 AND 
           'n' (BOTH INCLUSIVE) WITH THE FOLLOWING FORMULA:

           Z=INT(RND*n)+1

           (see RANDOM)


      SAVE   PSAVE  

HOW:       SAVE "file name"
           PSAVE "file name"

EG:        SAVE "A:\PROG"
           FILES "A:\*.*"

PURPOSE:   SAVES A PROGRAM FILE (PSAVE IS WITH LIST PROTECTION)

           'file name' IS THE NAME OF THE PROGRAM.  SEE MKDIR FOR
           THE EXPLANATION OF HIERARCHICAL FILING SYSTEM.  IF A
           PROGRAM ALREADY EXISTS WITH THE SAME NAME IT WILL BE
           WRITTEN OVER DURING THE SAVE.

           PROGRAMS WHICH ARE SAVED WITH PSAVE ARE NOT LISTED BUT
           RUN STRAIGHT AFTERH THE COMMAND 'LOAD' IS GIVEN.           


      SEEK

HOW:       SEEK [#]n,x

EG:        OPEN "O",#1,"DAT1"
           OPEN "O",#2,"DAT2"
           PRINT #1,"1234567"
           PRINT #2,"ABCDEF"
           SEEK #1,3
           SEEK #2,5
           PRINT LOC(#1),LOC(#2)

PURPOSE:   SETS THE FILE POINTER ON THE BYTE NUMBER 'x' OF FILE #n

           'n' IS AN INTEGER EXPRESSION BETWEEN 0 AND 99 WHICH 
           REFERS TO THE CHANNEL NUMBER.  'x' HAS A VALUE (TOTAL)
           EITHER GREATER OR SMALLER THAN THE LENGTH OF THE FILE
           ADDRESSED.

           EVERY DATA CHANNEL HAS A FILE POINTER (READING AND 
           WRITING POINTER) WHICH POINTS TO A SPECIFIC BYTE IN THE
           FILE.  THIS POINTER CAN BE PLACED ON ANY BYTE IN THE 
           FILE BY SEEK.  POSITIVE 'x' PLACES IT AY BYTE NUMBER 
           'x' AT THE BEGINNING OF THE FILE, WHEREAS NEGATIVE 'n'
           VALUES CAUSE THE POINTER TO BE PLACED 'n' NUMBER OF 
           BYTES FROM THE END OF THE FILE.


      SETCOLOR

HOW:       SETCOLOR i,r,g,b       OR SETCOLOR i,n

EG:        SETCOLOR 0,0,0,0
           FOR COL=1 TO 30000
             SETCOLOR 0,COL
           NEXT COL

PURPOSE:   DEFINES THE COLOURS RED, GREEN AND BLUE FOR THE COLOUR
           REGISTER 'i'.
           'r,g,b' ARE THE LEVELS OF THE THREE PRIMARY COLOURS
           FROM 0 TO 7.
           ANOTHER WAY OF DEFINING COLOURS IS TO USE THE VALUE 'n'
           WHERE N=R*256+G*16+B


      SETTIME

HOW:       SETTIME timestring,datestring

EG:        PRINT TIME$,DATE$
           SETTIME "11:30:11", "29.6.1987"
           PRINT TIME$,DATE$

PURPOSE:   SETS THE TIME AND THE DATE.

           'timestring' IS A STRING EXPRESSION WHICH CONTAINS THE
           TIME.  HOURS, MINUTES AND SECOND CAN BE DISPLAYED. THE
           COLONS ARE OPTIONAL AS TWO DIGITS HAVE TO BE ENTERED.
           THE SECONDS CAN ALSO BE LEFT OUT.  

           'datestring' IS A CHARACTER STRING EXPERSSION FOR THE
           DATE.  IT MUST ALWAYS CONTAIN:  Day, Month and Year, 
           EACH SEPERATED BY A FULL STOP.  WHEN USING THE YEARS
           BETWEEN 1980 AND 2097 THE FIRST TWO DIGITS CAN BE LEFT
           OUT.


      SGN

HOW:       SGN(x)

EG:        INPUT A
           B=SGN(A)*A
           PRINT B

PURPOSE:   ASCERTAINS WHETHER 'x' IS POSITIVE, NEGATIVE OR 0

           'x' CAN BE ANY NUMERIC EXPERSSION.  SGN(x) IS THE
           MATHEMATIC SIGN FUNCTION.
           THE VALUES -1, 0 AND 1 CAN BE RETURNED:-

           -  0  IF X=0
           - +1  IF X>0
           - -1  IF X<0

           (See ABS)


      SIN

HOW:       SIN(x)

EG:        1)  INPUT RAD
               PRINT SIN(RAD)
               INPUT GRAD
               PRINT SIN(GRAD*PI/180)

           2)  PLOT 320,200
               FOR I=1 TO 5400
                 X=I/36*SIN(I*PI/180)
                 Y=I/36*SIN(I*PI/180)
                 DRAW TO 320+X,200+Y
               NEXT I

PURPOSE:   RETURNS THE SINE VALUE OF 'x'

           'x' IS A NUMERIC EXPERSSION WHICH SHOWS THE ANGLE, FOR
           WHICH THE SINE IS CALCULATED, IN RADIAN MEASURE (RAD)

           IF THE ANGLE IS TO BE INDICATED IN DEGREES, 'x' IS
           REPLACED BY GRAD*PI/180. IN THE FIRST EXAMPLE THE (RAD)
           OF THE CHOSEN ANGLE IS CALCULATED AND THEN THE DEGREE
           ACCORDING TO THE SINE VALUE.  IN THE SECOND EXAMPLE A
           'SNAIL' FORM IS CREATED BY USING DEGREES.


      SOUND

HOW:       SOUND voc,vol,note,octave[,dur]
           SOUND voc,vol,note,#period[,dur]

EG:        FOR I=1 TO 8
             SOUND 1,15,1,I,40
             FOR J=1 TO 6
               READ A
               SOUND 1,15,A,I,20
             NEXT J
             RESTORE
           NEXT I
           DATA 3,5,6,8,10,12

PURPOSE:   GENERATES MUSICAL NOTES

           'voc' IS AN EXPRESSION WITH ONE OF THE VALUES 1,2,3 AND
           SELECTS THE SOUND CHANNEL.
           'vol' IS AN EXPRESSION WITH A VALUE OF 1 TO 15 AND
           SELECTS THE VOLUME.
           'note' IS AN EXPRESSION WITH A VALUE OF 1 TO 12 AND
           SELECTS ONE OF THE FOLLOWING NOTES:

           1=C, 2=C#, 3=D, 4=D#, 5=E, 6=F, 7=F#, 8=G, 9=G#, 10=A
           11=A#, 12=B

           'octave' IS AN EXPRESSION WITH A VALUE BETWEEN 1 AND 8,
           AND DETERMINES THE OCTAVE IN WHICH THE NOTE IS PLAYED.
           THE NOTE A IN TH SCALE OF C (440 Hz) IS THE 4th 
           OCTAVE (10th NOTE).

           'dur' IS AN INTEGER EXPRESSION AND SPECIFIES THE TIME 
           IN 1/50ths OF A SECOND THE TIME GFA BASIC HAS TO WAIT
           BEFORE EXECUTION OF THE NEXT COMMAND.

           A FURTHER POSSIBILITY TO CHOOSE THE PITCH IS TO ENTER 
           'PERIOD'  PREFIXED BY '#' INSTEAD OF 'note' AND 
           'octave'.  THE PERIOD CAN BE CALCULATED FROM THE
           FREQUENCY AS FOLLOWS:
           
           Period = TRUNC(125000/frequency +0.5)

           THEREFORE THE NOTE A (440 Hz) HAS A PERIOD OF 284. THIS
           NOTE CAN BE PLAYED FOR 10 SECONDS THUS:

           SOUND 1,15,10,4,500   OR
           SOUND 1,15,#284,500

           (See WAVE)


      SPACE$

HOW:       SPACE$(x)

EG:        FOR I=0 TO 20
             PRINT SPACE$(I);I
           NEXT I

PURPOSE:   CREATES A CHARACTER STRING CONTAINING 'x' SPACES.

           'x' IS A NUMERIC EXPRESSION WITH A VALUE WHICH MUST LIE
           BETWEEN 0 AND 32767.  ONLY INTEGERS OF 'x' WILL BE
           ACCEPTED.

           
      SPC

HOW:       SPC(n)

EG:        PRINT "GFA";SPC(10);"BASIC"
           PRINT "here";SPC(200);"there"

PURPOSE:   PRODUCES 'n' SPACES INA PRINT COMMAND

           'n' IS AN INTEGER EXPERSSION. HOWEVER, ONLY THE VALUE
           TRUNC(n MOD 256) IS CONSIDERED.

           THE FUNCTION SPC CAN ONLY BE USED WITH PRINT COMMANDS.


      SPOKE    SDPOKE    SLPOKE

HOW:       SPOKE x,n    SDPOKE x,    SLPOKE x,n

EG:        A$="A"
           L=ARRPTR(A$)
           SDPOKE L+4,4
           Z=VARPTR(A$)
           SLPOKE Z,1111638594
           PRINT A$
           SPOKE Z,67
           PRINT A$

PURPOSE:   WRITES 1, 2 or 4 BYTES INTO AN AREA OF MEMORY WHICH
           BEGINS WITH THE ADDRESS 'x'

           'x' IS A NUMERIC EXPRESSION WHICH NAMES AN ADDRESS IN 
           THE MAIN MEMORY.  THE VALUE OF 'x' MUST BE AN EVEN
           NUMBER IN THE COMMANDS SDPOKE AND SLPOKE. 
           'n' IS A NUMERIC EXPRESSION WHEREBY THE VALUE FOR
           SPOKE MUST LIE BETWEEN 0 AND 255, THE VALUE FOR SDPOKE
           BETWEEN 0 AND 65535 AND THE VALUE FOR SLPOKE BETWEEN
           -2147483648 AND +2147483647.

           THIS COMMAND WORKS IN THE SUPERVISOR MODE OF THE 68000
           CPU, IE. RESERVED STORAGE SPACE CAN ALSO BE ACCESSED.
           OTHERWISE THE SAME AS POKE.


      SPRITE

HOW:       SPRITE A$[,x,y]

EG:        A$=MKI$(1)+MKI$(1)+MKI$(0)
           A$=A$+MKI$(0)+MKI$(1)
           FOR I=1 TO 16
             A$=A$+MKI$(0)+MKI$(65535)
           NEXT I
           SPRITE A$,20,20
           PAUSE 200
           SPRITE A$

PURPOSE:   PUTS THE SPRITE DEFINED IN A$ AT (X,Y) OR, IF NO
           COORDINATES ARE GIVEN, DELETES IT.
           A$ IS 74 CHARACTERS LONG :-

           A$ = MKI$(X POSITION)
              + MKI$(Y POSITION)
              + MKI$( 0=NORMAL OR 1=XOR MODE)
              + MKI$(SCREEN COLOUR MOSTLY 0)
              + MKI$(SPRITE COLOUR MOSTLY 1)
              + BIT PATTERN OF SCREEN AND SPRITE

           UNLIKE DEFMOUSE THE BIT PATTERNS FOR SCREEN AND SPRITE
           ARE NOT STORED IN SEPARATE BLOCKS BUT IN ALTERNATE
           WORDS (16 BITS).
           IF THE SAME SPRITE IS PUT ONTO THE SCREEN IN ANOTHER
           POSITION THEN THE FIRST SPRITE IS DELETED.


      SQR

HOW:       SQR(X)

EG:        INPUT X
           PRINT SQR(X)

PURPOSE:   CALCULATES THE SQUARE ROOT OF 'X'.
           

      STOP

HOW:       STOP

EG:        FOR I=0 TO 200
             PRINT I
             IF I=123 THEN
               STOP
             ENDIF
           NEXT I

PURPOSE:   STOPS EXECUTION OF A PROGRAM.
           UNLIKE THE END COMMAND IT DOES NOT CLOSE ANY FILES AND
           BY TYPING CONT THE PROGRAM WILL RESUME FROM THE LINE
           FOLLOWING THE STOP COMMAND.


      STR$

HOW:       STR$(X)

EG:        INPUT "INPUT A NUMBER ";N
           A$=STR$(N)
           PRINT A$
 
PURPOSE:   TRANSFORMS THE VALUE 'X' INTO A CHARACTER STRING.
           (SEE ALSO HEX$, OCT$ AND BIN$)


      STRING$

HOW:       STRING$(N,string)  OR  STRING$(N,C)

EG:        Z$="A"
           PRINT STRING$(50,Z$)
           PRINT STRING$(50,"A")
           PRINT STRING$(50,65)
           PRINT STRING$(25,"AA")

PURPOSE:   PRODUCES A STRING FORMED BY REPEATING 'string' OR
           CHR$(C) 'N' TIMES. 
           'N' IS A NUMBER FROM 0 TO 32767.
           ALL THE ABOVE EXAMPLES PRODUCE A STRING OF FIFTY
           LETTER 'A's.


      SUB

HOW:       SUB VAR,N

EG:        FOR I=5 TO 50
             PRINT I,SUB I,5
           NEXT I

PURPOSE:   DEDUCTS 'N' FROM 'VAR'. SAME AS VAR=VAR-N BUT EXECUTES
           ALMOST TWICE AS FAST.


      SWAP

HOW:       SWAP var1,var2

EG:        DIM A(3),B(8)
           ARRAYFILL B(),8
           A$="FIRST"
           B$="SECOND"
           SWAP A$,B$
           SWAP A(),B()
           PRINT A$,B$
           PRINT A(8),B(2)

PURPOSE:   EXCHANGES THE VALUES OF 'var1' AND 'var2'.
           THE VARIABLES MUST BE OF THE SAME TYPE.
           WHEN SWAPPING ARRAY FIELDS THE DIMENSIONS ARE ALSO
           SWAPPED.


      SYSTEM

HOW:       SYSTEM

EG:        INPUT "ENTER PASSWORD! ";P$
           IF P$<>"BEH HEH HEH HEH" THEN
             SYSTEM
           ENDIF

PURPOSE:   CAUSES A RETURN TO THE GEM DESKTOP, SAME AS QUIT.


      TAB

HOW:       TAB(N)
           
EG:        PRINT TAB(30);"GFA"
           PRINT SPACES$(40)
           PRINT TAB(30);"BASIC"

PURPOSE:   SETS THE TABULATOR TO THE Nth COLOUMN.
           TAB CAN ONLY BE USED IN CONJUNCTION WITH THE PRINT
           COMMAND.
           IF THE CURREN POSITION IS ALREADY PAST 'N' THEN THE
           TAB FUNCTION IS SET FOR THE NEXT LINE.


      TAN

HOW:       TAN(X)

EG:        INPUT RAD
           PRINT TAN(RAD)
           INPUT GRAD
           PRINT TAN(GRAD*PI/180)

PURPOSE:   RETURNS THE VALUE OF THE TANGENT OF 'X'
           'X' IS THE ANGLE IN RADIANS.


      TEXT

HOW:       TEXT X,Y, [ L, ]string

EG:        DEFTEXT 1,16,0,21
           A$="ABC D"
           TEXT 10,50,A$
           TEXT 10,350,200,A$
           TEXT 300,350,-200,"ABC D"

PURPOSE:   PUTS A TEXT ONTO THE SCREEN AT GRAPHICS COORDINATES
           'X,Y'. THE GRAPHICS CAN FIRST BE DEFINED BY USING
           THE COMMAND DEFTEXT.
           THE POINT 'X,Y' IS AT THE BOTTOM LEFT HAND CORNER OF
           THE TEXT TO BE PRINTED.
           THE OPTIONAL PARAMETER 'L' CAN BE POSITIVE OR 
           NEGATIVE AND DETERMINES THE LENGTH OF THE TEXT TO BE
           DISPLAYED IN GRAPHIC DOTS. IF +L THEN THE TEXT IS SET
           TO THIS LENGTH BY ALTERING THE SPACING BETWEEN THE
           CHARACTERS. IF -L, THEN THE TEXT IS MADE TO FIT BY
           ALTERING THE SPACES BETWEEN THE WORDS.
           (SEE EXAMPLE )
           IF L=0 THEN THE TEXT IS UNCHANGED.


      TIME$

HOW:       TIME$

EG:        DEFTEXT 1,16,0,32
           DO
             PRINT AT(1,1);TIME$
             TEXT 240,180,TIME$
           LOOP

PURPOSE:   RETURNS THE SYSTEM TIME.
           THE STRING FORMAT IS HH:MM:SS . THE SECONDS ARE UPDATED
           EVERY TWO SECONDS.


      TITLEW

HOW:       TITLEW N,"title"

EG:        TITLEW 2,"HEADING"

PURPOSE:   GIVE THE WINDOW NUMBER 'N', THE NEW TITLE 'title'.
           IF BEFORE OPENW A TITLEW N,"" IS EXECUTED THEN THE 
           WINDOW DOES NOT HAVE A TITLE LINE. THIS CAN BE CHANGED
           BY ENTERING TITLEW N,"".


      TRON   TROFF

HOW:       TRON
           TROFF

EG:        TRON
           DO
             PRINT I
             INC I
             IF I=25 THEN
               TROFF
             ENDIF
           LOOP

PURPOSE:   SWITCHES THE TRACE FUNCTION ON AND OFF.


      TRUNC

HOW:       TRUNC(X)

EG:        A=3.14155
           PRINT TRUNC(A)
           PRINT TRUNC(-12)
           PRINT TRUNC(-1.99)

PURPOSE:   RETURNS THE INTEGER PORTION OF 'X'.
           TRUNC IS IDENTICAL TO FIX (SEE ALSO).


      UPPER$

HOW:       A$="basic"
           PRINT UPPER$(A)
           PRINT UPPER$("1a")
           PRINT UPPER$("GFA")

PURPOSE:   TRANSFORMS ALL LOWER CASE LETTERS OF A STRING TO UPPER
           CASE. ANY NON LETTER CHARACTERS ARE LEFT UNCHANGED.


      VAL

HOW:       VAL(X$)
      
EG:        A$="4000 DUESSELDORF 11"
           PRINT VAL(A$)
           PRINT VAL("1.5E+05")
           PRINT VAL("GFA")

PURPOSE:   TRANSFORMS 'X$' INTO A NUMBDER, AS FAR AS POSSIBLE.
           IN THE CASE OF A PURELY ALPHABETICAL STRING THE VALUE
           0 IS RETURNED.


      VAL?
      
HOW:       VAL?(X$)

EG:        A$="22 KG"
           PRINT VAL?(A$)
           PRINT VAL?("1.0+E19")
           PRINT VAL?("1E19")
           PRINT VAL?("AB123")

PURPOSE:   DETERMINES THE NUMBER OF CHARACTERS STARTING AT THE
           BEGINNING OF A STRING THAT CAN BE CONVERTED INTO A 
           NUMERICAL VALUE WITH VAL.
           

      VARPTR

HOW:       VAPTR(var)

EG:        A%=17
           N$="GFA"
           PRINT VARPTR(A%)
           PRINT LPEEK(VARPTR(A%))
           PRINT VARPTR(N$)
           PRINT PEEK(VARPTR(N$))
           PRINT PEEK(VARPTR(N$)+1)
           PRINT PEEK(VARPTR(N$)+2)
           
PURPOSE:   DETERMINES THE ADDRESS OR STARTING ADDRESS OF A
           VARIABLE 'var'. 


      WAVE

HOW:       WAVE voc,env,form,len,dur

EG:        SOUND 1,15,1,4,20
           SOUND 2,15,4,4,20
           SOUND 3,15,8,4,20
           WAVE 7,7,0,65535,300
           WAVE 0,0

PURPOSE:   PRODUCES NOISES FROM THE THREE SOUND CHANNELS.
           
           'voc' IS TREATED 'BIT-WISE' WITH THE BIT-VALUES FOR THE
           THREE CHANNELS AS FOLLOWS. 

           BIT 1=CHANNEL 1           BIT  8 NOISE ON CHANNEL 1
           BIT 2=CHANNEL 2           BIT 16 NOISE ON CHANNEL 2
           BIT 4=CHANNEL 3           BIT 32 NOISE IN CHANNEL 3

           256*PERIOD OF THE NOISE GENERATOR (0 TO 31) CAN ALSO
           BE ADDED TO THIS.

           'env' DEFINES WHICH CHANNELS THE ENVELOPE WILL BE
           ACTIVE UPON (eg. BINARY 101 WOULD BE CHANNELS 1 & 3).
           
           'form' SPECIFIES THE ENVELOPE SHAPE :-

           0 TO 3 = LINEAR FALLING.
           4 TO 7 = LINEAR RISING AND TERMINATING.            
                8 = SAWTOOTH FALLING.
                9 = LINEAR FALLING (AS 0 TO 3).
               10 = PEAKED BEGIN FALLING.                      
               11 = LINEAR FALLING VAR.LOUDNESS.
               12 = SAWTOOTH RISING.
               13 = LINEAR RISING CONTINUOUS.
               14 = PEAKED BEGIN RISING.
               15 = LINEAR RISING (AS 4 TO 7)

           'len' SPECIFIES THE PERIOD OF THE ENVELOPE.

           'dur' IS THE TIME IN 1/50S BEFORE NEXT COMMAND.

           PARAMETERS WHICH ARE LOCATED AT THE END OF THE COMMAND
           AND WHICH ARE TO REMAIN UNCHANGED CAN BE OMITTED IN THE
           NEXT COMMAND.
           WAVE 0,0 SWITCHES OFF ALL SOUND CHANNELS.


      WHILE....WEND

HOW:       WHILE condition
           WEND

EG:        WHILE A<10
             A=A+1
             PRINT A
           WEND

PURPOSE:   CREATES A CONDITIONAL LOOP BETWEEN WHILE AND WEND UNTIL
           THE 'condition' IS FULFILLED. THIS IS CHECKED AT THE
           BEGINNING OF THE LOOP AND SO IT IS POSSIBLE THAT THE
           LOOP IS NEVER EXECUTED.


      WRITE

HOW:       WRITE [ expressions ][ ; ]
           WRITE #n [ expressions ][ ; ]

EG:        OPEN "O",#1,"DAT"
           WRITE #1,"SMITH","JOHN",18
           CLOSE #1

PURPOSE:   STORES DATA IN A SEQUENTIAL FILE TO BE READ WITH INPUT.
           UNLIKE THE PRINT COMMAND THE NUMBERS ARE SEPARATED BY
           COMMAS AND THE STRINGS ARE ENCLOSED IN QUOTES.
           (SEE ALSO PRINT)
 

      SPECIAL FUNCTIONS


      *

HOW:       *

EG:        DIM A$(9)
           FOR I=0 TO 9
             A$(I)=STR$(RND)
           NEXT I
           @DSP
           @SORT(*A$())
           @DSP
           PROCEDURE DSP
             FOR I=0 TO 9
               PRINT A$
             NEXT I
           RETURN
           PROCEDURE SORT(P.SARR)         !SORT X$()
             IF TYPE(P.SARR)<>5
               ERROR 47                   !STRING PARAMETER
             END IF
             SWAP *P.SARR,X$()              !WORK FIELD
             LOCAL I%,J%
             REM BUBBLESORT SLOW
             FOR I%=DIM?(X$())-2 DOWNTO 0
               FOR J%=0 TO I%
                 IF X$(J%)>X$(J%+1)
                   SWAP X$(J%),X$(J%+1)         
                 ENDIF
               NEXT J%
             NEXT I%
             SWAP *P.SARR,X$()              !FIELD RETURN
           RETURN

PURPOSE:   PASSES ON VARIALBLES AND ARRAYS INDIRECTLY.
           THE ASTERIX IS NOT ONLY FOR MULTIPLICATION BUT ALSO
           SIGNIFIES THE INDIRECT ADDRESSING IN PROCEDURES WITH
           PARAMETERS OR FIELDS TO BE RETURNED.

           GOSUB XXX(*A) DOES NOT SPECIFY THE VALUE OF 'A' BUT
           IT'S ADDRESS. *PTR=5 SETS THE VARIABLE WHOSE ADDRESS
           IS CONTAINED IN PTR TO 5.
           WITH FIELDS IT IS ONLY POSSIBLE TO CHANGE AN ELEMENT OF
           THE FIELD BY MEANS OF AN INDIRECT SWAP. TYPE() SHOWS
           WHAT SORT OF VARIABLE IS AT THE POINTER LOCATION.
           IMPORTANT  LOCAL VARIABLES AND GLOBAL VARIABLES WITH
           THE SAME NAME ARE STORED IN THE SAME AREA (THE GLOBAL
           VALUES ARE SAVED WHEN LOCAL BEGINS AND RESTORED ON
           RETURN). THEREFORE LOCAL VARIABLES MAY NOT HAVE THE
           NAME OF A RETURN PARAMETER.
           
      ==

HOW:       a==b

EG:        FOR I=-1 TO 0 STEP 0.1
             EXIT IF I==0.5
           NEXT I
           PRINT I

PURPOSE:   COMPARISON OPERATOR FOR APPROXIMATELY EQUAL

           'a' AND 'b' ARE NUMERIC EXPRESSIONS. THE == OPERATOR IS
           USED IN THE SAME WAY AS A COMPARISON WITH = EXCEPT THAT
           THE CONDITION IS TRUE NOT ONLY WHEN THE TWO ARE EQUAL,
           BUT WHEN THEY ARE APPROXIMATLEY EQUAL.  28 BITS OF THE
           MANTISSA ARE COMPARED i.e. ABOUT 8.5 DIGITS.  IN THE
           EXAMPLE THE LOOP IS LEFT ALTHOUGH IT IS POSSIBLE THAT
           DUE TO ROUNDING ERRORS THE NUMERIC VARIABLE IS NEVER
           EXACTLY 0.5

           (see DEFNUM and PRINT USING)


      BASEPAGE

HOW:       BASEPAGE

EG:        VOID GEMDOS(&H1A,BASEPAGE+128)
           P$="*.*"+CHR$(0)
           STAT=GEMDOS(&H4E,L:VARPTR(P$),8)
           D.name$=""
           IF STAT=0                      ! <>0 Something wrong
              I%=BASEPAGE+30
              WHILE PEEK(I%)
                D.name$=D.name$+CHR$(PEEK(I%))
                INC I%
              WEND
           END IF

PURPOSE:   RETURNS THE ADDRESS OF THE BASEPAGE OF GFA-BASIC

           EVERY PROGRAM THAT IS LOADED UNDER GEMDOS IS ASSIGNED A
           BASEPAGE WHICH HAS A LENGTH OF 256 BYTES.  THE FIRST 
           128 BYTES OF THIS PAGE CONTAIN INTERNAL INFORMATION
           THAT THE OPERATING SYSTEM NEEDS TO ORGANISE PROGRAMS IN
           MEMORY - A POKE HERE CAN, AMONGST OTHER THINGS, LEAD TO
           SYSTEM BREAKDOWN ON 'QUIT'.

           THE SECOND HALF OF THE BASEPAGE CONTAINS THE COMMAND
           LINE.  THE FIRST 44 BYTES OF THE SECOND HALF ARE USED,
           THE REST CAN, FOR EXAMPLE, BE USED FOR SMALL MACHINE
           CODE PROGRAMS WHICH RETURN JOYSTICK INFORMATION.


      BITBLT

HOW:       BITBLT s%(),d%(),p%()

PURPOSE:   RASTER COPYING COMMAND.

           's%' CONTAINS THE SOURCE MEMORY FORM DESCRIPTOR - THE
                DESCRIPTION OF THE SOURCE RASTER
           'd%' CONTAINS THE DESTINATION MEMORY FORM DESCRIPTOR -
                THE DESCRIPTION OF THE DESTINATION RASTER
           'p%' CONTAINS THE CO-ORDINATES OF THE TWO EQUALLY 
                SIZED RECTANGLES AND THE COPYING MODE (see PUT).
                THESE FIELDS MUST BE AS FOLLOWS:

           s%(0) = RASTER ADDRESS (EVEN)  e.g. XBIOS(3)
           s%(1) = RASTER WIDTH IN POINTS e.g. 640 (MUST BE
                   DIVISIBLE BY 16)
           s%(2) = RASTER HEIGHT IN POINTS e.g. 400
           s%(3) = RASTER WIDTH IN WORDS e.g. 40, i.e. s%(1)/16
           s%(4) = ALWAYS 0
           s%(5) = NUMBER OF BIT PLANES (e.g. 2/4)
           d%()    as s%()
           p%(0...3) = SOURCE RECTANGLE (x0,y0,x1,y1)
           p%(4...7) = DESTINATION RECTANGLE (AS ABOVE)
           p%(8)     = MODE (see PUT)


      BGET

HOW:       BGET [#] i,adr,cnt

EG:        OPEN "I",#1,"SCR.DAT"
           SEEK #1,8000
           BGET #1,XBIOS(3)+24000,8000
           CLOSE #1

PURPOSE:   READS FROM A DATA CHANNEL INTO AN AREA OF MEMORY

           'i', 'adr' AND 'cnt' ARE INTEGER EXPRESSIONS.
           'i' IS A CHANNEL NUMBER.
           'cnt' BYTES ARE READ IN AND STORED IN MEMORY STARTING 
                 AT ADDRESS 'adr'
           UNLIKE BLOAD, SEVERAL DIFFERENT AREAS OF MEMORY CAN BE
           READ FROM A FILE.  IN THE EXAMPLE, THE SECOND QUARTER
           OF THE SCREEN FILE IS READ INTO THE BOTTOM EDGE OF THE
           SCREEN.

           (see BPUT, BSAVE, BLOAD)


      BMOVE

HOW:       BMOVE scr,dst,cnt

EG:        BMOVE XBIOS(3),XBIOS(3)+2,31998

PURPOSE:   FAST MOVEMENT OF MEMORY BLOCKS
      
           'scr', 'dst' AND 'cnt' ARE INTEGER EXPRESSIONS.
           'scr' IS THE ADDRESS AT WHICH THE BLOCK TO BE MOVED
                 BEGINS.
           'dst' IS THE ADDRESS TO WHICH THE BLOCK IS TO MOVED
           'cnt' IS THE LENGTH OF THE BLOCK IN BYTES.
           BMOVE IS A FAST, INTELLIGENT MOVING ROUTINE WHICH MEANS
           THAT IT IS ALSO SUITABLE FOR OVERLAPPING SOURCE AND
           DESTINATION ADDRESSES.  THE EXAMPLE DISPLACES THE   
           CONTENTS OF THE SCREEN BY TWO BYTES.


      BPUT

HOW:       BPUT [ # ] I,adr,cnt

EG:        OPEN "O",#1,"SCREEN.DAT"
           BPUT #1,XBIOS(3)+16000,16000
           BPUT #1 XBIOS(3),16000
           CLOSE #1

PURPOSE:   READS FROM AN AREA OF MEMORY OUT TO A DATA CHANNEL.
           'I' IS A CHANNEL NUMBER.
           'cnt' BYTES ARE READ FROM ADDRESS 'adr' AND GIVEN OUT
           ON A DATA CHANNEL.


      CLR

HOW:       CLR var [ ,var ]

EG:        CLR A,B,C%,D!,E$

PURPOSE:   DELETES VARIABLES. THE EXAMPLE ABOVE SETS THE SPECIFIED
           VARIABLES (NOT ARRAYS) TO ZERO AND IS THE SAME AS:-
           
           A=0
           B=0
           C%=0
           D!=0
           E$=""


      CRSCOL  CRSLIN

HOW:       CRSCOL
           CRSLIN

EG:        CX=CRSCOL
           CY=CRSLIN
           PRINT AT(9,9);"TEST"           
           PRINT AT(CX,CY);

PURPOSE:   RETURNS THE CURRENT CURSOR LINE AND COLUMN.
           (SEE ALSO PRINT AT).


      DEFNUM

HOW:       DEFNUM N

EG:        DEFNUM 8
           FOR I=-1 TO 1 STEP 0.1
             PRINT I
           NEXT I

PURPOSE:   ROUNDS ALL NUMBERS BEFORE OUTPUT TO 'N' DIGITS.
           'N' IS AN INTEGER BETWEEN 3 AND 11.
           (SEE ALSO PRINT USING)


      EVEN

HOW:       EVEN N

EG:        REPEAT
             INPUT "ENTER AN EVEN NUMBER";N
           UNTIL EVEN(N)

PURPOSE:   DETERMINES WHETHER A NUMBER IS EVEN.
           (SEE ALSO ODD)


      EXEC

HOW:       EXEC flg,name,cmd,env
           EXEC (flg,name,cmd,env)
      
EG:        RESERVE FRE(0)-10000
           EXEC 0,"TEST.PRG","",""
           RESERVE FRE(0)+10000-255

PURPOSE:   LOADS AND EXECUTES MACHINE CODE PROGRAMS OR COMPILED
           PROGRAMS FROM DISC.
           flg=0 IS LOAD AND GO . flg=3 IS LOAD ONLY.
           'name' IS THE NAME OF THE PROGRAM.
           'cmd' IS COMMAND LINE (SEE BASEPAGE).
           'env' IS ENVIRONMENT STRING (USUALLY JUST "").
           THE NAMED PROGRAM IS LOADED FROM DISC, THE ABSOLUTE
           ADDRESSES ARE RELOCATED, A BASEPAGE IS CREATED AND IF
           REQUIRED THE PROGRAM IS RUN.
           IF EXEC IS USED AS A FUNCTION THE RESULT IS THE
           RETURNED VALUE FROM THE PROGRAM OR, WHEN flg=3 THE
           BASEPAGE ADDRESS OF THE LOADED PROGRAM.
           (SEE ALSO RESERVE AND HIMEM).


      FALSE

HOW:       FALSE

EG:        FLAG!=FALSE

PURPOSE:   CONSTANT 0. THIS IS SIMPLY ANOTHER WAY OF EXPRESSING
           THE VALUE OF A CONDITION WHEN IT IS FALSE AND IS EQUAL
           TO ZERO.
           (SEE ALSO TRUE).


      FORM INPUT AS

HOW:       FORM INPUT n AS var

EG:        PRINT "CHANGE FIELD 3"
           PRINT AT(15,15);
           FORM INPUT 15 AS FIELD3$

PURPOSE:   ALLOWS A CHARACTER STRING TO BE CHANGED DURING A 
           PRORAM. 
           'n' IS THE MAXIMUM LENGTH FOR THE STRING VARIABLE 'var'
           THIS COMMAND WORKS IN THE SAME WAY AS FORM INPUT 
           EXCEPT THAT THE OLD CONTENTS OF HE STRING VARIABLE IS
           GIVEN OUT TO BE CHANGED.
           (SEE ALSO FORM INPUT)

      
      HIDEM

HOW:       HIDEM

EG:        HIDEM
           DO
             PLOT MOUSEX,MOUSEY
           LOOP

PURPOSE:   SWITCHES OFF THE MOUSE POINTER.
           (SEE ALSO SHOWM).


      HIMEM

HOW:       HIMEM

EG:        SEE EXECUTE 

PURPOSE:   RETURNS THE ADDRESS OF THE AREA OF MEMORY WHICH IS  NOT 
           REQUIRED BY GFA BASIC.
           BASIC OCCUPIES THE MEMORY BETWEEN BASEPAGE AND HIMEM.
           WITH HIIEM ONE CAN DETERMINE THE FIRST ADDRESS ABOVE
           BASIC WHICH IS FREE (NORMALLY 16384 BYTES BELOW THE
           SCREEN AREA).
           ABOVE HIMEM THERE SHOULD BE AT LEAST 4000 BYTES FREE
           BECAUSE THE FILESELCT BOX AND OTHER GEM CALLS REQUIRE
           THIS MUCH SPACE.
           UNFORTUNATELY THE EXACT AMOUNT REQUIRED IS NOT 
           DOCUMENTED BY ATARI, BUT EXPERIMENTS HAVE SHOWN THAT IT
           REQUIRES AT LEAST 2500 BYTES.

      
      INP?

HOW:       INP?(N)

EG:        IF INP?(1)
             @Routine
           ENDIF

PURPOSE:   DETERMINES THE INPUT STATUS OF A PERIPHERY.
           'N' IS THE NUMBER OF AN INTERFACE (0=LST: 1=AUX: 2=CON:
           3=MID: ). THE FUNCTION RETURNS THE VALUE 0 IF A BYTE
           IS PRESENT OTHERWISE -1.
           THE EXAMPLE CALLS A SUBROUTINE IF SOMETHING HAS ARRIVED
           AT THE SERIAL PORT.
           (SEE ALSO OUT?)


      MONITOR

HOW:       MONITOR [ N ]

PURPOSE:   CALLS A MONTIOR RESIDENT IN MEMORY OR A COMMAND 
           EXTENSION.
           WITH THIS COMMAND A MINITOR OR DEBUGGER IS CALLE UP IF
           IT HAS SUITABLY SET THE ILLEGAL INSTRUCTION VECTOR SO
           THAT THE MSB OF THE VECTOR IS ZERO BEFORE LOADING 
           GFA BASIC (THIS IS DONE, FOR EXAMPLE, BY THE DEBUGGER
           IN THE ATARI DEVELOPEMENT SYSTEM).
           IT IS POSSIBLE TO PASS ON THE INTEGER VALUE 'N' IN 
           REGISTER D0 AND THEREFORE WRITE COMMAND EXTENSIONS.
           IN ADDITION TO THIS IN A0 THE ADDRESS OF A POINTER
           TABLE IS PASSED ON HICH POINTS TO THE EIGHT VARIABLE
           TYPES (SEE TYPE). THESE EIGHT POINTERS ARE ALSO 
           AVAILABLE FOR THE COMPILER.


      ODD

HOW:       ODD(N)
      
EG:        REPEAT
             INPUT "ENTER AN ODD NUMBER ";N
           UNTIL ODD(N)

PURPOSE:   DETERMINES WHETHER A NUMBER IS ODD.
           (SEE ALSO EVEN)


 
      ON MENU BUTTON

HOW:       ON MENU BUTTON C,M,S GOSUB proc

EG:        ON MENU BUTTON 8,1,1 GOSUB button
           DO
             ON MENU
           LOOP
           PROCEDURE button
             PRINT MENU(15)'              !NUMBER OF CLICKS
             PRINT MENU(10)'MENU(11)      !X,Y
             IF MENU(15)=4                !EXIT ONLY ON
               END                        !FOUR CLICKS
             END IF
           RETURN

PURPOSE:   RETURNS MOUSE CLICKS.
           C=MAX. NUMBER OF CLICKS TO BE COUNTED.
           M=MASK (1=LEFT 2=RIGHT 3=BOTH).
           S=STATUS (AS FOR 'M')
           IN THE EXAMPLE A MAXIMUM OF 8 CLICKS IS EXPECTED.
           WHEN THE MOUSE IS CLICKED, THE NUMBERR OF CLICKS AND
           THE MOUSE POSITION IS SHOWN. IF THE NUMBER OF CLICKS
           IS 4 THEN THE PROGRAM ENDS.


      OPTION   OPTION BASE 0   OPTION BASE 

HOW:       OPTION BASE 0
           OPTION BASE 1
           OPTION [ " ]TEXT[ " ]

EG:        OPTION "TRAPV +"
           OPTION BASE 1
           DIM A(9)
           FOR I=1 TO 9
             A$(I)=STR$(I)
           NEXT I

PURPOSE:   CHANGES THE FIELD ARRAY BASE OR CONTROL FOR THE 
           COMPILER. OPTION BASE 0/1 ALLOWS THE LOWER LIMIT FOR
           FIELD DIMENSIONING TO BE CAHNGED FROM 0 TO 1.
           SOME PROGRAMS CAN SAVE A FEW BYTES FOR THE ZERO
           ELEMENT. 
           WITH OPTION "TEXT" CONTROL COMMANDS CAN BE PASSED ONTO
           THE COMPILER.

      
      OUT?

HOW:       OUT?(N)

EG:        DO
             OUT 0,0                      !IGNORED
             EXIT IF OUT?(0)
             PRINT "PRINTER ON !!!!"
           LOOP

PURPOSE:   DETERMINES THE OUTPUT STATUS OF A PERIPHERY.
           THIS FUNCTION RETURNS 0 IF A CHARACTER CAN BE OUTPUT.
           IN  THIS  EXAMPLE  THE  READINESS  OF  THE  PRINTER  IS 
           CHECKED.
           (SEE ALSO INP?)

      
      RESERVE

HOW:       RESERVE n

EG:        see EXEC

PURPOSE:   INCREASES OR DECREASES THE MEMORY USED BY BASIC

           'n' IS A NUMERIC EXPRESSION WHICH DETERMINES HOW BIG
           FRE(0) SHOULD BE AFTER THIS COMMAND.
           AS 'HIMEM' CHANGES IN STEPS OF 256, FRE(0) CAN BE UPTO
           255 BYTES LONG.  WITH THIS COMMAND AREAS OF MEMORY CAN
           BE PROTECTED FROM ACCESS VIA BASIC AND CAN BE USED, 
           FOR EXAMPLE, FOR MACHINE CODE PROGRAMS OR RSC FILES.
           FOR AREAS CONTAINING PURELY DATA MALLOC() - that is -
           (adr=GEMDOS(&48,1:number) SHOULD BE USED TO PROTECT
           AGAINST ACCESS VIA GEM (fileselect, alert, etc)

           (see HIMEM, EXEC)


      SGET

HOW:       SGET var

EG:        SGET SCREEN1$
           FOR I=1 TO 100
             PRINT I'
           NEXT I
           SGET SCREEN2$
           DO
             SPUT SCREEN1$
             SPUT SCREEN2$
           LOOP

PURPOSE:   FAST READING OF THE ENTIRE SCREEN AREA INTO A STRING
           VARIABLE.
           (SEE ALSO SPUT, GET, PUT AND BMOVE)

           
      SHOWM

HOW:       SHOWM

EG:        SHOWM
           DO
             PLOT MOUSEX,MOUSEY
           LOOP

PURPOSE:   MAKES THE MOUSE SYMBOL APPEAR.
           (SEE ALSO HIDMEM)


      SPUT

HOW:       SPUT var

EG:        SEE SGET

PURPOSE:   FAST COPYING OF A 32000 BYTE STRING INTO THE SCREEN
           AREA.
           (SEE ALSO SGET, PUT, GET AND BMOVE)


      TRUE

HOW:       TRUE

EG:        FLAG!=TRUE

PURPOSE:   CONSTANT 0. THIS IS SIMPLY ANOTHER WAY OF EXPRESSING
           THE VALUE OF A CONDITION WHEN IT IS TRUE AND IS EQUAL
           TO ZERO.
           (SEE ALSO FALSE).
   
             
      TYPE

HOW:       TYPE(ptr)
          
EG:        SEE *

PURPOSE:   DETERMINES THE TYPE OF THE VARIABLE AT WHICH A POINTER
           IS SET.
           'ptr' IS AN INTEGER EXPRESION (USUALLY *var).
           TYPE(ptr) RETURNS A CODE ACCORDING TO THE TYPE OF
           VARIABLE TO WHICH 'ptr' IS POINTING.
           0=var  1=var$  2=var%  3=var!  4=var()  5=var$()
           6=var%()  7=var!().
           ON ERRORS -1 IS RETURNED.
           (SEE ALSO *)


      VDIBASE

HOW:       VDIBASE

PURPOSE:   DANGEROUS POKES!
      
           DETERMINES THE ADDRESS ABOVE THE AREA USED BY BASIC
           AND THE REQUIRED TABLES AND VARIABLES.
           THIS IS THE POINT FROM WHICH THIS VERSION OF GEM KEEPS
           PARAMETERS FOR THE VDI (TEXT STYLE, CLIPPING etc.).
           AFTER THIS FOLLOWS THE BASIC PROGRAM.
           BY USE OF PEEK AND POKE IN THIS AREA, VARIOUS EFFECTS
           (AND ALSO NASTY CRASHES !) CAN BE OBTAINED.


      VOID

HOW:       VOID exp

EG:        VOID FRE(0)
           VOID INP(2)

PURPOSE:   SUBSTITUTE FOR DUMMY=  . (FASTER, ESPECIALLY FOR THE
           COMPILER).
           THIS COMMAND PERFORMS A CALCULATION AND FORGETS THE
           RESULT, THIS MAY SOUND SILLY BUT THERE ARE OCCASIONS
           WHEN THIS COMMAND IS REQUIRED.
           FOR EXAMPLE, FORCED GARBAGE COLLECTION (FRE(0)) OR
           WAITING FOR A KEYSTROKE (INP(2)) OR CALLING VARIOUS
           BIOS-, XBIOS, GEMDOS OR C: ROUTINES WHICH HAVE NO
           PARAMETERS.

      
      VSYNC

HOW:       VSYNC

PURPOSE:   ENABLES SYNCHRONIZATION WITH THE SCREEN OR CAN BE 
           USED AS A PAUSE.
           HALTS THE PROGRAM UNTIL THE NEXT VERTICAL SYNC PULSE
           IS RECEIVED, i.e. UNTIL THE PICTURE IS COMPLETE ON
           THE SCREEN. THIS CAN HELP AVOID FLICKERING OF THE
           SCREEN DURING ANIMATIONS (eg. WITH GET/PUT) BUT THE
           NEXT SCREEN MUST BE PUT ONTO THE SCREEN VERY QUICKLY
           THIS FUNCTION IS THE SAME AS VOID XBIOS(37).

                  
             
