GFA-Basic ver. 2.0 ------------------ COMMANDS AND FUNCTIONS ====================== ABS HOW: ABS(X) USE: Returns the absolute value of a number ADD HOW: ADD VAR,N USE: Increase value of var by N ALERT HOW: ALERT A,MESSAGE$,B,BUTTON$,VAR USE: 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 (Shift \). 'BUTTON$' Contains text for the buttons 'B' A button can be highlighted (0,1,2,3) to be selected by just pressing return 'VAR' This variable is set to the number of the button selected ARRAYFILL HOW: ARRAYFILL FIELD(),N USE: Assigns the value 'n' to all elements of a field array ARRPTR HOW: ARRPTR(VAR) USE: Finds the address of the (6 byte long) descriptor of a string or field ASC HOW: ASC(X$) USE: Finds the ascii code of the first character of a string ATN HOW: ATN(X) USE: Returns the arc tangent of x. BIN$ HOW: BIN$(X) USE: Changes value of 'X' to a string containing the binary value of 'X'. BLOAD/BSAVE HOW: BLOAD "FILENAME" [,ADDRESS] BSAVE "FILENAME",ADDRESS,LENGTH USE: Load and save memory from and to disc drive. BOX HOW: BOX X,Y,XX,YY USE: Draws a rectangle with corners at (X,Y) and (XX,YY) C: HOW: C:VAR(PARAMETERS) EG: A=C:Q%(17,L:0,W:-1) USE: Calls a C program with parameters as in C CALL HOW: CALL VAR CALL VAR(PARAMETERS) USE: Calls a machine code program at address 'var' CHAIN HOW: CHAIN "FILESPEC" USE: Loads a program file into the work area and starts it CHDIR HOW: CHDIR "DIRECTORY NAME" USE: Changes the current directory CHDRIVE HOW: CHDRIVE N USE: Sets the default disk drive CLEAR HOW: CLEAR USE: Clears all variables and fields CLEARW HOW: CLEARW N USE: Clears the contents of the window numbered 'n' CLOSE HOW: CLOSE [ [#] N] USE: Close a data channel or a channel to the disk drive CLOSEW HOW: CLOSEW N USE: Closes the window numbered N CLS HOW: CLS [#N] USE: Clears the screen COLOR HOW: COLOR C USE: Sets the colour for drawing CONT HOW: CONT USE: Resumes execution of a program Continue the execution of a program after interruption COS HOW: COS(X) USE: Returns the cosine of value x CVI CVL CVS CVF CVD HOW: CVI (X$) ... CVD (X$) USE: 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 " " " " DATA HOW: DATA [CONST[,CONST] ...] USE: Used as memory variables which can be read by the READ command. The constants are separated by commas. DATE$ HOW: DATE$ USE: Creates a date function Creates a date string in the format: dd.mm.yyyy DEC HOW: DEC var USE: Reduces the value of 'var' by 1 DEFFILL HOW: DEFFILL [col],[style],[pattern] or DEFFILLL [col],A$ USE: Sets fill colour and pattern, or allows user-defined patterns. 'style' - 0=empty, 1=filled, 2=dots, 3=lines, 4=user 24 dotted patterns and 12 lined can by chosen. A user-defined fill pattern is defined in the second variation - DEFFILL col,A$ by defining a 16 x 16 bit pattern array. DEFFN HOW: DEFFN NAME [(VARLIST)]=EXPRESSION CALLED UP BY: FN NAME [(LIST OF EXPRESSIONS)] USE: Defines specific user function DEFLINE HOW: DEFLINE (style),(width),(start),(end) USE: Sets line style, width & type of line start and end. DEFLIST HOW: DEFLIST X USE: Defines the program listing format X=0: Commands/Functions - capitals, variables - small letters. X<>0: Only first letter of functions/variables are capitals. DEFMARK HOW: DEFMARK [C],[A],[G] USE: 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$ USE: 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=bordered 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. DEFTEXT HOW: DEFTEXT [col],[style],[rot],[size] USE: 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 (can be combined). 'R' rotation only the following are possible :- 0 deg (0), 90 deg (900), 180 deg (1800), 270 deg (2700) 'G' size of text - 4=icon, 6=8*8, 13=std, 32=enlarged. DFREE HOW: DFREE(N) USE: Locates free space on a disc 'N' = drive number (0-15) DIM HOW: DIM VAR(INDICES)[,VAR(INDICES),.....] USE: Sets the dimensions of an array or string array DIM? HOW: DIM?(FIELD()) USE: Determines the number of elements in an array. Note - arrays have an element '0'. DIR HOW: DIR [ "FILESPEC" [ TO "FILE" ]] USE: Lists the files on a disc. DIR$ HOW: DIR$(N) USE: Names the active directory for drive 'N' 'N' is drive number (1=A:, 2=B: ...). DIV HOW: DIV VAR,N USE: Divides the value of VAR by N. As VAR=VAR/N but 30% faster. DO....LOOP HOW: DO LOOP USE: Creates an endless loop, exit only with EXIT. DRAW HOW: DRAW [ TO ] X,Y DRAW X1,Y1, TO X2,Y2 TO X3,Y3....... USE: 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). EDIT HOW: EDIT USE: Returns to the editor. When used in direct mode the command allows a return to the editor. In a program, is the same as END but without the program end alert box. ELLIPSE HOW: ELLIPSE X,Y,RX,RY [,phi0,phi1] USE: Draws an ellipse at X,Y, having 'RX' as length of the horizontal axis and 'RY' as length of the vertical axis. The optional angles 'phi0' & 'phi1' give start and end angles in tenths of a degree, for segments. END HOW: END USE: Closes all files and terminates program execution. EOF HOW: EOF ([ # ] N) USE: Determines whether the file pointer for the file with channel number 'N' is at End Of the File. ERASE HOW: ERASE FIELD() USE: Deletes an array and releases the dimensioned area. ERR HOW: ERR USE: Returns the error code of any error that has occurred. ERROR HOW: ERROR N USE: Simulates the occurrence of the error with the error code 'N' and the appropriate error message is then displayed. EXIST HOW: EXIST ("FILESPEC") USE: Determines whether a particular file is present on a disc. If present -1 is returned, else 0 is returned. EXIT HOW: EXIT IF Condition USE: 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) USE: Calculates the value of an exponent FATAL HOW: FATAL USE: Returns the value 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 ....... USE: 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. FILES HOW: FILES [ "FILESPEC" [ TO "FILE" ]] USE: Lists the files on a disc. Like DIR but more detailed data listing. FILESELECT HOW: FILESELECT "FILESPEC","FILENAME",X$ USE: Creates a fileselect box on the screen 'FILESPEC' is the so-called search path. If the abort button is clicked then 'X$' is an empty string. FILL HOW: FILL X,Y USE: Fills a bordered area with a pattern commencing at the co-ordinates 'X,Y'. Fill pattern can be chosen with the command DEFFILL. FIX HOW: FIX(X) USE: 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 USE: Creates a loop which is executed as many times as specified at the beginning of the loop. FORM INPUT HOW: FORM INPUT N,var USE: Enables the insertion of a character string (limited to 255 characters in length) during program execution. 'N' = the maximum length of the character string. 'var' is the name of the string variable. FRAC HOW: FRAC(X) USE: 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) USE: Returns the amount of memory free (in bytes) The parameter 'X' is disregarded. FULLW HOW: FULLW N USE: Enlarges window 'n' to full screen size. 'N' is the window number. If the window hasn't yet been opened, this takes place automatically. GET HOW: GET [ # ] N [ ,I ] USE: 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' isn't given then the next record in the file will be read. GOSUB HOW: GOSUB name [ (LIST OF EXPRESSIONS) ] USE: 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 across 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). GOTO HOW: GOTO label USE: 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 USE: Sets the graphic mode 1 to 4. 1=replace 2=transparent 3=xor 4=reverse transparent HARDCOPY HOW: HARDCOPY USE: Prints the screen (same as pressing & ). HEX$ HOW: HEX$(X) USE: Changes the value of 'X' into a string expression which contains the value of 'X' in hexadecimal form. IF HOW: IF condition [ THEN ] program block ELSE program block ENDIF USE: Divides a program up into different blocks depending on how it relates to the 'condition'. INC HOW: INC var USE: 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" USE: 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 can't 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$ USE: Reads a character from the keyboard. This function returns a string which is 2, 1 or 0 characters long. Normal keys, return the ASCII code. Function keys, HELP, UNDO etc. return two characters: The ASCII code zero and then the key code. INP HOW: INP(X) INP(#N) USE: 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 file on data channel 'N'. INPUT HOW: INPUT [ "TEXT"; (; or ,) ] VAR [ ,VAR.... ] INPUT #N,var [ ,var.... ] USE: Allows entry of data during program execution when printing text before input. INPUT$ HOW: INPUT$(X[,#N]) USE: 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 isn't 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]) USE: 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' isn't 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) USE: Determines the largest integer that is less than or equal to 'X' KILL HOW: KILL "FILESPEC" USE: Deletes a disc file (only one at a time) LEFT$ HOW: LEFT$(STRING [ ,N ] ) USE: Returns the first or first 'N' characters of a string. LEN HOW: LEN(X$) USE: Determines the length of a string. LET HOW: [ LET ] var=expression USE: Assigns a variable with the value of an expression. LINE HOW: LINE X,Y,XX,YY USE: Connects two points ('X,Y' & 'XX,YY') with a straight line, and is identical to DRAW X,Y TO XX,YY. LINE INPUT LINE INPUT # HOW: LINE INPUT [ "TEXT" ; ( , ) ]var [ ,var... ] LINE INPUT #N,var [,var...] USE: 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 is regarded as a separator. LIST HOW: LIST "FILENAME" USE: stores the program currently in memory to disc in ascii format. If the 'filename' is an empty string (eg. "") then the listing is shown on the screen. In all other cases this command is the same as the editor menu option SAVE,A Programs to be joined together using the command MERGE must be save using LIST. LLIST HOW: LLIST USE: Prints out the listing of the current program. LOAD HOW: LOAD "FILESPEC" USE: Loads a program into memory. LOC HOW: LOC( [ # ]N) USE: 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.... ] USE: Declares 'var' to be a local variable. LOF HOW: LOF ([ # ]N) USE: Determines length of file on channel number 'N'. LOG LOG10 HOW: LOG(X) LOG10(X) USE: Determines the natural logarithm (log) or the logarithm base 10 (log10) of 'X'. LPOS HOW: LPOS(N) USE: Returns the column in which the printer head (in the printer buffer) is located. LPRINT HOW: LPRINT [ expressions [ , ][ ; ][ ' ]] USE: 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. LSET HOW: LSET var=string USE: Puts the 'string' in the string variable 'var' justified to the left. MAX HOW: MAX(expression [ ,expression... ]) USE: Returns the greatest value (or largest string) from a list of expressions. MENU HOW: MENU field (n) MENU KILL MENU OFF MENU n,x USE: 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 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. MENU HOW: MENU(N) USE: The function MENU(N) makes it possible to use the parameters from the on menu gosub routines. After ON MENU the function returns the values which were returned when 'event_multi' was called up. MID$ HOW: MID$(string,A [ ,N ]) USE: Returns all or 'N' characters in a string from the position 'A' onwards. If the optional parameter 'N' isn't used, the function returns all characters of the string from 'A' onwards. MIN HOW: MIN(expression [ ,expression... ]) USE: Returns the smallest value (or smallest string) from a list of expressions. MKDIR HOW: MKDIR "DIRECTORY NAME" USE: Creates a new directory. 'DIRECTORY NAME' is the name of the new directory. MKI$ MKL$ MKS$ MKF$ MKD$ HOW: MKI$(N) MKL$(N) MKS$(N) MKF$(N) MKD$(N) USE: 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. MOUSE MOUSEX MOUSEY MOUSEK HOW: MOUSE X,Y,K MOUSEX MOUSEY MOUSEK USE: 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 USE: Multiplies the value 'var' by 'N'. same as var=var*N but executes 30% faster. NAME HOW: NAME "OLDFILE" AS "NEWFILE" USE: Renames an existing file. The contents of the file aren't affected. NEW HOW: NEW USE: Deletes the program currently in memory and clears all variables. OCT$ HOW: OCT$(X) USE: Changes the value 'X' into a string containing the value of 'X' in octal form (prefix &O) ON...GOSUB HOW: ON expression GOSUB procedure list USE: Depending on the result of 'expression' one of several given procedures is processed. 'procedure list' is a list of procedure names separated by commas. The result of 'expression' denotes which procedure is carried out. Eg: If result = 1 then the first procedure in the procedure list is processed. If result = 2 then the second procedure in the procedure list is processed. If result = 3 then the third procedure in the procedure list is processed and so on. If the value isn't in the 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 USE: ON BREAK CONT makes it impossible to stop a program by pressing break ( ). 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 USE: Performs the procedure 'name' when an error occurs. The program isn't interrupted and no error message is given. 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 USE: 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 IBOX...GOSUB AND ON MENU OBOX...GOSUB define the procedures to make the mouse move in or out of pre-defined rectangles. 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 ] USE: 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 isn't present, a length of 128 bytes is designated. OPENW HOW: OPENW N [ ,X,Y ] USE: Opens a window with the number 'N'. The optional 'X & Y' define the point of contact for the four possible windows. OUT HOW: OUT X,A OUT #N,A USE: 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 USE: 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 USE: 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) USE: 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 USE: returns the value of PI. The value of PI is 3.141592653.....etc. PLOT HOW: PLOT X,Y USE: Plots a point on the screen coordinates 'X,Y'. This command is the same as draw X,Y. POINT HOW: POINT X,Y USE: 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 USE: 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. 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 ] USE: Draws a (filled in) shape of 'N' dots or marks the corner points. 'N' STATES THE NUMBER OF DOTS (MAX 128). POS HOW: POS(N) USE: Returns the column in which the cursor is positioned. 'N', a hypothetical argument, is optional. PRINT PRINT# HOW: PRINT [ AT(X,Y) ][ ; ][ expr [ , ][ ; ][ ' ]] PRINT #N [ ,expr [ , ][ ; ][ ' ]] USE: 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. PRINT USING HOW: PRINT USING "FORMAT",LIST [ ; ]# PRINT #N,USING "FORMAT",LIST [ ; ]# USE: Issues formatted 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) ] USE: 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. PUT HOW: PUT X,Y,A$ [ ,MODE ] USE: Places a graphics block on the screen at X,Y which has been previously grabbed by GET, and stored in A$. 'MODE' (optional) sets the way the image is placed. PUT HOW: PUT [ # ]N[ ,I ] USE: 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. QUIT HOW: QUIT USE: Causes a return to the desktop, same as SYSTEM. RANDOM HOW: RANDOM(X) USE: Returns a random integer between 0 (inclusive) and 'X' (exclusive). RBOX HOW: RBOX X,Y,XX,YY USE: Draws a rectangle with rounded corners from the two diagonally opposite corner points 'X,Y' and 'XX,YY' READ HOW: READ var [ ,var0 ] ...... USE: Reads values from a data command and assigns them to a variable 'var'. RELSEEK HOW: RELSEEK [#]N,X USE: Moves the random access file pointer forward (+X) or backwards (-X) 'X' number of bytes. REM HOW: REM remark ABBR: ' USE: Whatever follows a REM COMMAND on a particular line is ignored by Basic. REPEAT...UNTIL HOW: REPEAT UNTIL end USE: Creates a pre-defined loop. The section of the program between repeat and until is repeated continuously until the condition is fulfilled. RESTORE HOW: RESTORE [label] USE: 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. RESUME HOW: RESUME RESUME NEXT RESUME label USE: 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 USE: Terminates a sub-routine RIGHT$ HOW: RIGHT$(string[,n]) USE: Returns the last characters or 'n' number of characters (from the right) of a character string 'string' RMDIR HOW: RMDIR "directory name" USE: Deletes empty directories RND HOW: RND [(x)] USE: Returns a random number between 0 and 1 The optional parameter (x) is disregarded, and returns a random number between 0 (inclusive) and 1 (exclusive) SAVE PSAVE HOW: SAVE "file name" PSAVE "file name" USE: Saves a program file (psave is with list protection) 'file name' is the name of the program. Programs which are saved with psave aren't listed but run straight after the command 'load' is given. SEEK HOW: SEEK [#]n,x USE: 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. SETCOLOR HOW: SETCOLOR i,r,g,b OR SETCOLOR i,n USE: 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 USE: 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 expression for the date. It must always contain: day, month and year, each separated by a full stop. SGN HOW: SGN(x) USE: Ascertains whether 'x' is positive, negative or 0 'x' can be any numeric expression. SGN(x) is the mathematic sign function. SIN HOW: SIN(x) USE: Returns the sine value of 'x' SOUND HOW: SOUND chn,vol,note,octave[,dur] SOUND chn,vol,note,#period[,dur] USE: GENERATES MUSICAL NOTES 'chn' is a 1, 2, or 3 and selects the sound channel. 'vol' selects the volume. 'note' is a value of 1 to 12 and selects 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 between 1 and 8, and determines octave. 'dur' is the time in 1/50ths of a second 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 with: Period = TRUNC(125000/frequency +0.5) SPACE$ HOW: SPACE$(x) USE: Creates a character string containing 'x' spaces. SPC HOW: SPC(n) USE: Produces 'n' spaces in a print command SPOKE SDPOKE SLPOKE HOW: SPOKE x,n SDPOKE x, SLPOKE x,n USE: Writes 1, 2 or 4 bytes into an area of memory which begins with the address 'x' SPRITE HOW: SPRITE A$[,x,y] USE: Puts the sprite defined in a$ at (X,Y) or, if no coordinates are given, deletes it. 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 aren't 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) USE: Calculates the square root of 'X'. STOP HOW: STOP USE: Stops execution of a program. Unlike the END command it doesn't close any files and by typing CONT the program will resume from the line following the STOP command. STR$ HOW: STR$(X) USE: Transforms the value 'X' into a character string. STRING$ HOW: STRING$(N,string) OR STRING$(N,C) USE: Produces a string formed by repeating 'string' or CHR$(C) 'N' times. 'N' is a number from 0 to 32767. SUB HOW: SUB VAR,N USE: Deducts 'N' from 'VAR'. Same as VAR=VAR-N but executes almost twice as fast. SWAP HOW: SWAP var1,var2 USE: 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 USE: Causes a return to the desktop, same as quit. TAB HOW: TAB(N) USE: Sets the tabulator to the Nth column. Tab can only be used in conjunction with the print command. If the current position is already past 'N' then the tab function is set for the next line. TAN HOW: TAN(X) USE: Returns the tangent of 'X' (X is the angle in radians). TEXT HOW: TEXT X,Y, [ L, ]string USE: Puts a text onto the screen at graphics coordinates 'X,Y'. The graphics can first be defined by using the command DEFTEXT. TIME$ HOW: TIME$ USE: Returns the system time as a string. Format: hh:mm:ss and is updated every two seconds. TITLEW HOW: TITLEW N,"title" USE: Gives the window number 'N', the new title 'title'. TRON TROFF HOW: TRON TROFF USE: Switches the trace function on and off. TRUNC HOW: TRUNC(X) USE: Returns the integer portion of 'X'. UPPER$ HOW: A$="basic" PRINT UPPER$(A$) PRINT UPPER$("1a") USE: Transforms all lower case letters of a string to upper case. Any non letter characters are left unchanged. VAL HOW: VAL(X$) USE: Transforms 'X$' into a number, as far as possible. In the case of a purely alphabetical string the value 0 is returned. VAL? HOW: VAL?(X$) USE: 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) USE: Determines the address or starting address of a variable 'var'. WAVE HOW: WAVE voc,env,form,len,dur USE: Produces noises from the three sound channels. WAVE 0,0 switches off all sound channels. WHILE....WEND HOW: WHILE condition WEND USE: 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 ][ ; ] USE: 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. Special Functions * HOW: * USE: Passes on variables and arrays indirectly. The asterisk isn't only for multiplication but also signifies the indirect addressing in procedures with parameters or fields to be returned. == HOW: a==b USE: Comparison operator for approximately equal 'a' and 'b' are numeric expressions. The == operator is used in the same way as a comparison with = but only 28 bits of the mantissa are compared i.e. about 8.5 digits. BASEPAGE HOW: BASEPAGE USE: Returns the address of the basepage of GFA-Basic BITBLT HOW: BITBLT s%(),d%(),p%() USE: Raster copying command similar to GET and PUT but more flexible and faster for some applications. 's%' the description of the source raster 'd%' the description of the destination raster 'p%' co-ordinates of the two equally sized rectangles and the copying mode (see PUT). BGET HOW: BGET [#] i,adr,cnt USE: Reads from a data channel into an area of memory 'i' \ 'adr' -- integer expressions. 'cnt' / 'i' is the 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. BMOVE HOW: BMOVE scr,dst,cnt USE: Fast movement of memory blocks '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. BPUT HOW: BPUT [ # ] I,adr,cnt USE: 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 ] USE: Deletes and sets specified variables (not arrays) to 0. CRSCOL CRSLIN HOW: CRSCOL CRSLIN USE: Returns current cursor line and column. (see also PRINT AT). DEFNUM HOW: DEFNUM N USE: Rounds all numbers before output to 'N' digits. 'N' is an integer between 3 and 11 (see also PRINT USING). EVEN HOW: EVEN N USE: Determines if a number is even. (also see ODD) EXEC HOW: EXEC flg,name,cmd,env EXEC (flg,name,cmd,env) USE: Loads and executes machine code programs or compiled programs from disc. flg=0 - load and go. flg=3 - load only. 'name' - the name of the program. 'cmd' - command line (see BASEPAGE). 'env' - 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 run. FALSE HOW: FALSE USE: 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 USE: Allows a character string to be changed during a program. '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 the string variable is given out to be changed. (see also FORM INPUT) HIDEM HOW: HIDEM USE: Switches off the mouse pointer. (see also SHOWM). HIMEM HOW: HIMEM USE: Returns the address of the area of memory which isn't required by GFA Basic. INP? HOW: INP?(N) USE: 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. (see also OUT?) MONITOR HOW: MONITOR [ N ] USE: Calls a monitor resident in memory or a command extension. ODD HOW: ODD(N) USE: Determines whether a number is odd. (see also even) ON MENU BUTTON HOW: ON MENU BUTTON C,M,S GOSUB proc USE: RETURNS MOUSE CLICKS. C=max number of clicks to be counted. M=mask (1=left 2=right 3=both). S=status (as for 'M') OPTION OPTION BASE 0 OPTION BASE HOW: OPTION BASE 0 OPTION BASE 1 OPTION [ " ]TEXT[ " ] USE: Changes the field array base or control for the compiler. OPTION BASE 0/1 allows the lower limit for field dimensioning to be changed 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) USE: Determines the output status of a periphery. This function returns 0 if a character can be output. (see also INP?) RESERVE HOW: RESERVE n USE: Increases or decreases the memory used by basic 'n' is a numeric expression which determines how big FRE(0) should be after this command. (see HIMEM, EXEC) SGET HOW: SGET var USE: Fast reading of the entire screen area into a string variable. (see also SPUT, GET, PUT and BMOVE) SHOWM HOW: SHOWM USE: Makes the mouse pointer appear. (see also HIDEM) SPUT HOW: SPUT var USE: Fast copying of a 32000 byte string into the screen area. (see also SGET, PUT, GET and BMOVE) TRUE HOW: TRUE USE: 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) USE: Determines the type of the variable at which a pointer is set. 'ptr' is an integer expression (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 USE: 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.). By use of peek and poke in this area, various effects (and nasty crashes!) can be obtained. VOID HOW: VOID exp USE: This command performs a calculation and forgets the result. Sounds silly but there are occasions when this command is required, eg. forced garbage collection (fre(0)), waiting for a keystroke (inp(2)), or calling various bios, xbios, gemdos or c: routines which have no parameters. VSYNC HOW: VSYNC USE: Enables synchronization with the screen by waiting for the next vertical sync pulse is received - helps avoid flickering of the screen during animations. For the more advanced programmer, GFA Basic also has advanced features for accessing the VDI, AES and OS. Various control blocks and pointers are covered, such as ADDRIN, ADDROUT, CONTRL , GB, GCONTRL, GINTIN, INTIN, INTOUT, PTSIN, and PTSOUT etc. AES is covered with GEMSYS, the VDI with VDISYS and the window parameter table with WINDTAB. Special OS functions include BIOS, XBIOS and GEMDOS to call routines in TOS (the actual operating system of the ST), as GEM provides only the user surface. BIOS XBIOS GEMDSOS HOW: a=Xbios(f [,parameter list]) eg a=Xbios(4,0,L:(a$),1,1,0) reads sector 1 for 1 sector drive a. - o = O = o -