August 1991
No part of this publication may be copied , transmitted or stored
in a retrieval system or reproduced in any way including but not
limited to photography, photocopy, magnetic or other recording
means, without prior written permission from the publishers, with
the exception of material entered and executed for the reader's
own use.
This version created for ST FORMAT.
THIS IS NOT PUBLIC DOMAIN. FULL COPYRIGHT REMAINS IN FORCE.
MARCH 1992
Copyright 1991 GFA Data Media (UK) Ltd
Published by: GFA Data Media (UK) Ltd
Box 121
Wokingham
Berkshire
RG11 5XT
Special Offer to ST Format Readers
This document is over 129 pages if printed on A4. We have
documented all GFA-BASIC commands. All commands are also
contained in the full GFA-BASIC REFERENCE manual which contains
much more information than is contained in this 'brief' document.
Most commands are fully explained with an example program.
You can obtain the FULL documentation, normally sold for 50.00
pounds for only 25.00 pounds (plus 5.00 postage). All orders must
be returned direct to GFA, using the special coupon in the issue
of ST Format that this disk was supplied with.
Also you can obtain the GFA-BASIC Compiler 3.5 and manual for only
20.00 (plus postage of 5.00). (normally 30.00). The compiler
manual contains 48 pages. You will need the compiler to produce
desk top accessories and link C and assembler code into your GFA-
BASIC programs.
Or order both the Interpreter and Compiler for only 45.00 (plus
5.00 postage) which would normally retail for 80.00.
Please make Cheques and Postal Orders payable to GFA-DATA
MEDIA (UK) LTD. We also can accept VISA and ACCESS credit cards.
TECHNICAL SUPPORT
Technical Support is only available to users who have purchased
the full GFA-BASIC 3.5 Interpreter. All technical problems should
be sent to GFA in writing, enclosing a stamped addressed envelope,
and quoting their registration card number (supplied with each
purchased product). Sorry but we are unable to supply technical
support to users who are unable to quote their registration
number.
Now to the documentation:
Introduction
Welcome to GFA-BASIC. With the GFA-BASIC interpreter you now have
the opportunity to explore the Atari ST, and create professional
programs.
We believe that GFA is the best programming language available,
not just for the Atari ST, but also for the Amiga, MS-DOS and
Windows 3.0/3.1. When you have quickly mastered GFA-BASIC for the
Atari ST, you can transport your program to any PC running either
MS-DOS or Windows (and soon OS/2 and Unix!). This means that you
will only need to learn one language for all these different
machines and operating systems.
This manual contains all the GFA-BASIC 3.5 command descriptions
and syntax. This manual is an edited version of the full reference
manual (which is over 540 pages) and is a reference manual for the
GFA-BASIC commands only. The full reference manual contains
example programs for most of the commands and reference material
for the Atari BIOS, XBIOS and GEMDOS.
This manual is a reference manual for the GFA-BASIC commands. It
does not attempt to teach you to program, there are other books
available for this purpose. Neither does this edited manual does
not document the hardware or operating system features of the
Atari.
This is the GFA-BASIC Interpreter. There are many more products in
the GFA range to help you develop your programs. Please contact
your distributor or GFA for more information and prices of these
products.
GFA-BASIC Interpreter Reference Manual (Full version)
This loose leaf manual has over 540 pages, dealing with each
command with a full description an example. The Atari system
routines, GEMDOS, AES, VDI and GDOS are all described. The Line-A
call is also described (although Line-A is now declared as un
supported by Atari). Just about every useful table is presented in
this manual, including GFA-BASIC error messages, Bomb Error
messages, TOS Error messages, Scan code table, ASCII tables, Fill
and style patterns, and VT-52 control codes.
GFA-BASIC Compiler
The GFA-BASIC Compiler will compile your interpreter code into
fast stand alone programs. Desk top accessories can also be easily
created. The GFA-BASIC Compiler also has options for optimising
code for either speed or size. External code, either C or
assembler can also be linked into your programs using the GFA-
BASIC Compiler. The manual (48 pages) fully explains how to create
a desk top accessory with examples. The compiler also supports the
Atari TT, allowing code to be compiled for either ST or TT ram.
GFA-BASIC Software Development Book
This book covers in depth structured programming, debugging
routines, Line A calls, Assembly routines, AES functions and GDOS.
Special attention is paid to dialog boxes and their creation. This
book is over 341 pages and is supported by a disk containing the
many examples of source code discussed within the book.
GFA GEM Utility Pack
THE GEM GUP is a framework of GFA-BASIC 3 routines that you can
merge into your own programs. GUP takes the responsibility of
managing the intricate GEM interface, leaving the programmer to
concentrate on the main program logic. The example program
supplied demonstrates how easy it is to create alternative icons,
and use up to 5 different window types. The demonstration also
shows how to use all the GEM gadgets, including scroll bars, title
bar, info bar, grow box, grab bar etc. GFA GUP is a quick start to
programming GEM. GUP is supplied with a 60 page manual and disk,
fully documenting all of the GEM routines.
GFA Assembler
An integrated development tool for the Atari ST/STE, comprising
editor, macro assembler, linker and debugger. Supports multiple
window, file compare, background assembly. Editor checks syntax
of machine code on entry, hence ideal for programmers new to
assembly language. Also creates files that can be loaded directly
into GFA-BASIC.
GFA-Basic and Assembler User Book
This book covers all that you will need to know in interfacing
assembler routines into GFA-BASIC on the Atari ST/STE. Includes
an introduction into assembly programming, creation of desk top
accessories, graphic manipulation. Book (364 pages) plus disk.
GFA G-Shell
Professional development shell for GFA-BASIC Interpreter and
Compiler on the Atari ST/STE and TT.
GFA-GShell allows the programmer to skip between Interpreter and
Compiler and other programs, such as an assembler and resource
editor. Supports make facility and on line help files. If you
are using GFA-BASIC Interpreter and Compiler professionally, then
GFA-GShell will improve your productivity.
GFA-DRAFT 3.2
Powerful and comprehensive, yet easy to use CAD software for
Atari ST/STE and Atari TT. Runs in both high and medium resolu-
tions. Icon and menu driven commands. There are symbol libraries
for electrical, electronic users and architects. Libraries of
symbols are also easy to create.
A program/macro interface (using GFA BASIC) will enable you to
create complex forms and repetive patterns. Exports: HPGL, DXF
and GEM files. Will support almost any model of printer or
plotter. GFA-Draft Plus 3.2 also supports the Atari laser
printer.
These GFA products and others are available from:
GFA Data Media (UK) Ltd
Box 121
Wokingham
Berkshire
UK RG11 5XT
Sales Line Only Tel: 44 (0)734 794941
Fax: 44 (0)734 890782
Using GFA-BASIC for the first time
The GFA-BASIC program disk is not copy protected, so before you do
anything else, make a copy and store the original disk in a safe
place.
GFA-BASIC is started by double clicking on the program file icon
GFABASIC.PRG. After a short while the Editor screen will be
displayed, which is where you can write and debug your programs.
Lets now try entering an example program. Enter the following
program lines, pressing the RETURN key at the end of each line.
DEFFILL 1,2,8
REPEAT
WHILE MOUSEK=1
PBOX MOUSEX,MOUSEY,MOUSEX+30,MOUSEY+30
WEND
UNTIL MOUSEK=2
In the upper right hand corner of the editor screen you will find
the RUN menu item. Click the RUN button or press Shift and F10
keys together and the example program will start. A simple program
showing the use of the mouse. Move the mouse while holding down
the left button. End the program by pressing the right mouse
button. Press the Return key to end the program. The program could
also have been stopped by pressing the CONTROL, SHIFT and
ALTERNATE keys all at the same time. You will now be returned to
the editor.
GFA-BASIC does not need line numbers. It is bad programming
practice to say GOTO 10. If you must use GOTO, then use:
GOTO label
...
label:
GFA-BASIC offers you the chance to create structured programs, and
indented in such a way to enable easy documentation and
understanding of program flow.
How to proceed from here. We suggest you first become familiar
with the GFA-BASIC Interpreter's editor. Then load some of the
demonstration programs from the disk and run these. Experiment
with these programs by changing the values of variables to see the
effect. The next step really depends upon the individual, your
knowledge of the Atari, your knowledge of programming and your
program requirements. What ever your experience or requirements,
GFA-BASIC is the best documented programming language available
for the Atari ST, and there are several books and development aids
to help you.
The Editor
THE GFA-BASIC Editor has been specially designed for program
development. Syntax errors are recognised as you type the commands
in, and in addition the commands are indented automatically.
Only one instruction per line is allowed, but a comment may be
added to the end of a line by beginning the comment with a ! mark.
Program lines may be up to 255 characters long, but when a line
exceeds 80 characters, the line will scroll.
Cursor Keypad
Left arrow moves cursor left one character
Right arrow moves cursor right one character
Up arrow moves cursor up one line
Down arrow moves cursor down one line
Insert Inserts a blank line
ClrHome moves cursor to top left corner
Ctrl ClrHome moves cursor to start of program listing
Help With the help key procedures and functions can
be folded and unfolded. Move the cursor to the
start of a procedure or function and then
press Help. The procedure will the fold down
to a single line
Numeric Keypad
Ctrl 4 moves cursor left one character
Ctrl 6 moves cursor right one character
Ctrl 8 moves cursor up one line
Ctrl 2 moves cursor down one line
Ctrl 7 jumps to start of program
Ctrl 1 jump to end of program
Ctrl 9 move one page up
Ctrl 3 move one page down
Ctrl 0 Inserts a line
Ctrl . deletes a line
The numeric keypad can be swithed to a mode where it is not
required to press the Ctrl key. This mode is toggled on and off by
pressing Ctrl and - on the numeric keypad.
Delete deletes character at cursor position
Backspace deletes character to left of cursor
Tab moves cursor right eight characters
Ctrl Tab moves cursor left eight characters
Return moves cursor to start of next line
Enter moves cursor to start of next line
Escape enter Direct Mode
Further editor commands
Ctrl Delete deletes line which cursor is on
Ctrl U un-deletes line
Ctrl Y deletes line which cursor is on
Ctrl N inserts blank line
Ctrl Q call Block menu (as F4)
Ctrl B mark start of block
Ctrl K mark end of block
Ctrl R Page up
Ctrl C Page down
Ctrl E replace text
Shift Ctrl E find replace text
Ctrl F find text
Ctrl left arrow cursor to start of line
Ctrl right arrow cursor to end of line
Ctrl up arrow page up
Ctrl down arrow page down
Ctrl Clr Home cursor to start of program
Ctrl P delete character right of cursor
Ctrl O undelete text deleted with Ctrl P
Ctrl Z cursor to end of program
Ctrl Tab cursor left eight characters
Ctrl G move to line number display
Editor marks
Ctrl n where n= 0 to 6 will mark a position
Alt n will jump to marked position n, except:
Alt 7 cursor to last cursor position before RUN
Alt 8 to start of program
Alt 9 cursor to start of last search
Alt 0 cursor to position of last change
Menu Bar
Atari Logo
This leads to a GEM menu bar:
Save
A file select box will appear, and a program can be saved by
entering a name and selecting OK.
Load
A file select box will appear, and a program can be selected and
loaded into the editor.
Deflist
See the DEFLIST command.
New Names
The editor will warn you if you enter a new variable name.
Editor
Returns you to the editor.
Load (F1)
Load a GFA-BASIC 3 .GFA tokenised file.
Save (Shift F1)
Save the program as a tokenised .GFA file.
Merge (F2)
Load an ASCII text file into the editor at the cursor position.
The existing program in the editor is not erased.
Save,A (Shift F2)
Save the program in memory in ASCII format. The extension .LST
will be added to the file name. If the file already exists the old
file will be changed to .BAK.
Llist (F3)
This command controls the output of the print out. These Dot
commands have no effect on the running of the program and only
affect the printout:
.ll xx Max line length
.pl xx Max page length
.ff xxx Form feed character for printer
.he text Text to appear on first line of each page
.fo text Text to appear on last line of each page
.lr xx Left margin
.l- Switch dot commands off
.l+ Switch dot commands on (default)
.n1 to .n9 Switch on line numbers up to 9 characters
.n0 Switch off line numbers
.PA Force form feed
.P- Do not list dot commands
.P+ List dot commands
In the header and footer text, the following can also be inserted:
\xxx The ASCII character xxx
\d Date
\t Time
# Page number
To print the symbols \ and ##, use \\ and \ respectively.
Quit (Shift F3)
Results in Do you really want to quit message. If Yes selected,
thenyou will return to the desktop.
Block (F4)
If no block marked then message Block ??? will appear. If a block
has been selected using the BlkSta and BlkEnd then the block menu
will appear:
Copy
Copies the block to current cursor position.
Move
Moves the block to current cursor position.
Write
Saves the block as an ASCII file (.LST)
Llist
Prints the block out to printer
Start
Moves the cursor to start of block
End
Moves the cursor to end of block
Del
Deletes the block
Hide
Removes the block marker
Clicking the mouse outside the Block menu or pressing a key also
removes the block marker.
New (Shift F4)
The program currently in the editor is erased from memory.
Blk End (F5)
The line before the cursor is marked as the end of block. If the
start of block marker is located before this line, the block is
shown in a different colour (or dotted background on a monochrome
screen). Also actioned with Ctrl K.
Blk Sta (Shift F5)
Marks the beginning of a block as above. Also actioned with Ctrl
B.
Find (F6)
Enter a text string to be searched for. If the string is found,
the search cab be continued with Ctrl F or Ctrl L. Also actioned
with Shift Ctrl F or Shift Ctrl L.
Folded procedures and functions are not searched.
Replace (Shift F6)
This function will replace one string of text by another. Input
the text to be replaced, then the replacement text. On finding an
occurrence, the actual replacement can be effected with Ctrl E.
Also activated with Shift Ctrl E.
Pg down (F7)
Scrolls the screen down one page. Also activated with Ctrl C.
Pg Up (Shift F7)
Scrolls the screen up one page. Also activated with Ctrl R.
Insert/Overwr (F8)
Switches between insert and overwrite.
Txt16/Text8 (Shift F8)
Only on monochrome monitor. Either 16 pixel high characters or 8
pixel high characters will provide 23 or 48 lines on the screen
respectively.
Flip (F9)
Flip between Edit and Output screen. Press any key to return to
the Edit screen
Direct (Shift F9)
Switch to Direct mode, where commands will be actioned
immediately. Some commands, such as loop commands are not
available in direct mode. Direct mode can also be entered by
pressing Esc key. The last 8 commands entered in direct mode are
remembered and can be recalled using the up and down arrow keys.
The Undo key will recall the last command.
A procedure can be called from direct mode.
Test (F10)
Tests all loops, subroutines and conditional instructions for
consistency without running the program.
Run (Shift F10)
The program in the editor memory is started. A running program can
be interrupted using Ctrl Shift Alt keys together.
Clock Display
The clock can be set by clicking on the clock and entering a new
time.
Line Numbers
Clicking on the line number box (beneath the clock) allows you to
enter a line number. On input the cursor will jump to this line
number. Also activated with Ctrl G.
COMMANDS AND FUNCTIONS
======================
The following commands and functions have been sorted by alphabetical
order. Each entry describes the command syntax and the action of the
command. Some of the more complex commands have examples. The full
GFA-BASIC Interpreter Reference manual contains examples for most of
the commands. The advanced commands such as the operating system calls
BIOS, GEMDOS and XBIOS are not covered here and should be consulted in
the GFA-BASIC Interpreter Reference manual.
*
Syntax: *y
Action: returns the address of variables, but for strings or arrays
the address of the descritpor is returned. (ARRPTR is the
same as *).
+
Syntax: a$+b$
Action: Concatenation operator, to add strings together.
+ Arithmetic operator (a+b adds a and b).
* a*b (a times b).
/ a/b (a divided by b).
^ a^b (a to the power b).
<> a<>b (a not equal b).
<= a<=b (a less than or equal to b).
>= a>=b (a greater than or equal to b).
==
Syntax: a==b
Action: 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.
@
Syntax: @FRED
Action: GOSUB PROCEDURE fred (@ is synonymous with GOSUB).
ABS
Syntax: ABS(X)
Action: Returns the absolute value of a number. (see also SGN).
ABSOLUTE
Syntax: ABSOLUTE x,y
Action: Assigns the address y to the variable x.
ACHAR
Syntax: ACHAR code,x,y,font,style,angle
Action: ASCII characters value 'code' are displayed at the graphics
location x,y.
Font can be:
0 = 6x6 (Icon font).
1 = 8x8 (Normal colour font).
2 = 8x16 (Normal monochrome font).
Larger values are taken to be the font header address of a
GDOS font.
Text type (bold, faint etc. 0-31) and output angle
(0,900,1800,2700) can be specified.
ACLIP
Syntax: ACLIP flag,xmin,ymin,xmax,ymax
Action: To define a 'clipping' rectangle to which LINE-A screen
output will be limited.
Flag 0 = clipping off, non zero = on.
ACOS
Syntax: ACOS(x)
Action: Returns the arc-cosine (in radians) of x.
ADD(x,y)
Syntax: z%=ADD(x%,y%)
Action: Integer addition.
ADD
Syntax: ADD x,y
Action: Increase value of variable x by y.
ADDRIN
Syntax: address of the AES Address Input block.
With an index after this function, the appropriate
parameter block is accessed directly.
ADDRIN(2)=x is the same as
LPOKE ADDRIN+2,x
ADDROUT address of the AES Address Output block, see above.
AFTER ticks GOSUB proc (see also EVERY).
AFTER CONT
AFTER STOP
Procedures can be called after the expiry of a set time.
Time in ticks (200ths of a second).
To continue the process, use CONT, and to stop
use STOP.
ALERT
Syntax: ALERT a,message$,b,button$,var
Action: 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'.
'b' is the button to 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.
Example: ALERT 1,"Pick a|button",1,"Left|Right",a%
ALERT 0,"You pressed|Button"+STR$(a%),0,"OK",a%
ALINE
Syntax: ALINE x1,y1,x2,y2,f,ls,m
Action: Draw a line using LINE A. x1,y1 are the start coordinates
x2,y2 end of line. f = colour (0-15). ls = line style in 16
bit information, (solid, dashed, dotted ..).
m mode
0 Replace
1 Transparent
2 Inverted
3 Inverted transparent
AND
Syntax: x AND y
Action: Logical operator, performs a logical AND, results in a true
or false result.
AND()
Syntax: AND(x,y)
Action: See AND above.
APOLY TO
Syntax: APOLY adr_pnt,num_pnt,y0 TO y1,f,m,addr,num_pattern
Action: Similar to POLYFILL, draws a sequence of joined lines, with
'num_pnt' corners, and fills the resulting area with a user
defined pattern. 'adr_pnt' is the address of the array
holding the alternating x,y corner coordinates. 'num_pnt'
is the number of points. y0 and y1 specify the highest and
lowest part of the screen where filling can occur. The
parameters f,m,addr,num_pattern are the same as for HLINE.
APPL_EXIT
Syntax: APPL_EXIT()
Action: Informs the system prog has finished - this is a dummy
function as QUIT or SYSTEM do this automatically.
APPL_FIND
Syntax: APPL_FIND(fname$)
Action: Returns the ID of the sought after application. Either
returns the apps ID or -1 if it cant be found. fname$ is an
8 character filename - without extension.
Example: PRINT APPL_FIND("CONTROL")
prints -1 if it cant find the CONTROL.ACC, or
returns it's ID [2].
APPL_INIT
Syntax: APPL_INIT()
Action: Announce the program as an application.
APPL_READ
Syntax: APPL_READ(id,len,adr_buffer)
Action: Instruction bytes can be read from the event buffer.
id - id of the application from whose buffer reading is to
be done.
len - number of bytes to read.
adr_buffer - address of the buffer.
APPL_TPLAY(mem,num,speed)
APPL_TRECORD(mem,num)
APPL_TRECORD makes a record of user activities, and TPLAY
plays these back at the specified speed (1 - 1000).
* ONLY VALID on TOS 1.4 and above. *
APPL_WRITE
Syntax: APPL_WRITE(id,len,adr_buffer)
Action: Bytes are written to the event buffer. SEE APPL_READ.
ARECT
Syntax: ARECT x1,y1,x2,y2,f,m,addr,num_pattern
Action: Similar to PBOX, x1,y1 and x2,y2 are opposite corners of a
rectangle. The parameters f,m,addr,num_pattern are the same
as for HLINE.
ARRAYFILL
Syntax: ARRAYFILL x(),n
Action: Assigns the value 'n' to all elements of a field array
x().
ARRPTR
Syntax: ARRPTR(x)
Action: Finds the address of the (6 byte long) descriptor of
a string or field. (Same as *x)
ASC
Syntax: ASC(x$)
Action: Finds the ascii code of the first character of a string.
ASIN
Syntax: ASIN(x)
Action: Returns the arc-sine (in radians) of x.
ATEXT
Syntax: ATEXT x,y,font,s$
Action: Output text at x,y coordinates using A LINE.
ATN
Syntax: ATN(x)
Action: Returns the arc tangent of x.
BASEPAGE
Syntax: BASEPAGE
Action: Returns the address of the basepage of GFA-Basic.
BCHG(x,y)
BCLR(x,y)
Allow setting and resetting of bits.
BCLR sets the y-th bit of x to zero.
BGET
Syntax: BGET #i,adr,cnt
Action: 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.
BIN$
Syntax: BIN$(x[,n])
Action: Changes value of 'x' to a string containing the binary
value of 'x'. The optional parameter 'n' specifies the
number of character positions to be used (1 to 32).
BIOS
Syntax: BIOS(n[,x,y])
Action: To call the BIOS routine. The optional parameter list can
be prefixed with W: or L: to denote word or longword
parameters. (if non given, default is W:)
Example:
REPEAT
UNTIL BIOS(11,-1) AND 4
Waits for the Control key to be pressed.
Please refer to GFA-BASIC Interpreter Manual for full list
of BIOS calls.
BITBLT
Syntax: BITBLT s%(),d%(),p%()
Action: 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).
BLOAD/BSAVE
Syntax: BLOAD "filename" [,address]
BSAVE "filename",address,length
Action: Load and save memory from and to disc drive.
Example: DEFFILL 1,2,4
PBOX 100,100,200,200
BSAVE "RECT.PIC",XBIOS(2),32000
CLS
PRINT "IMAGE STORED. Press a key to continue"
~INP(2)
CLS
BLOAD "RECT.PIC",XBIOS(2)
BMOVE
Syntax: BMOVE scr,dst,cnt
Action: 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.
BOUNDARY
Syntax: BOUNDARY n
Action: Uses function vsf_perimeter to switch off (or on) borders
on filled shapes (PBOX, PCIRCLE ..). If n is zero - no
border, n - non zero = border.
BOX
Syntax: BOX x,y,xx,yy
Action: Draws a rectangle with corners at (x,y) and (xx,yy)
BPUT
Syntax: BPUT #n,adr,cnt
Action: Reads from an area of memory out to a data channel.
'n' is a channel number.
'adr' is start address of memory to read from.
'cnt' bytes are read from address.
BSAVE See BLOAD
BSET(x,y) Allows setting and resetting of bits.
BTST(x,y) BSET sets the y-th bit of x to 1.
BTST results in -1 (TRUE) if bit y of x is set.
Example: x=BSET(0,3)
PRINT x,BSET(0,5)
BYTE(x) Returns the lower 8 bits of the numerical expression x.
(See also CARD(), WORD() ).
BYTE{x} As a function eg. y=BYTE{x} one can read the contents of
the address x. As a command one writes to address x. eg.
BYTE{x}=y. This is similar to PEEK and POKE but is not done
in supervisor mode. (See also CARD{}, INT{}, LONG{}, {},
FLOAT{}, SINGLE{}, DOUBLE{}, CHAR{} ).
C:
Syntax: C:addr([ x,y,....L:x, w:y])
Action: Calls a C or assembler program with parameters as in C. The
parameters can be sent as 32-bit long words or 16-bit words
to the subroutine. eg. a%=C:adr%(L:x,W:y,z) leads to the
following situation on the stack:
(sp) ->return address (4bytes)
4(sp) ->x (4 bytes)
8(sp) ->y (2 bytes)
10(sp) ->z (2 bytes)
The value returned by the call is the contents of D0.
CALL
Syntax: CALL addr([ x,y,....L:x, w:y])
Action: Calls a machine code or C subroutine at address 'addr'.
When the call is made, the return address is on the top of
the stack, followed by the number of parameters as a 16-bit
word, then the address of the parameter list as a 32-bit
word.
CARD(x) Returns the lower 16 bits of the numerical expression x.
(See also BYTE, WORD).
CARD{x} Reads/writes a 2-byte unsigned integer (similar to
DPEEK/DPOKE). (See also BYTE{}, INT{}, LONG{}, {},
FLOAT{}, SINGLE{}, DOUBLE{}, CHAR{} ).
CASE See SELECT.
CFLOAT(x) Changes the integer x into a floating point number. (See
also CINT).
CHAIN
Syntax: CHAIN f$
Action: Loads a GFA Basic program file into memory and starts it
immediately it is loaded. If no extension is given '.GFA'
is assumed.
Example: CHAIN "A:\EXAMPLE.GFA"
CHAR{x} Reads a string of bytes until a null byte is encountered,
or writes the specified string of bytes and appends a null
byte.
Example: PRINT CHAR{BASEPAGE+129} prints the command line.
CHDIR
Syntax: CHDIR "directory name"
Action: Changes the current directory.
Example: CHDIR "B:\TEST"
CHDRIVE
Syntax: CHDRIVE n or n$
Action: Sets the default disk drive 0=current, 1=A, 2=B etc.
Example: CHDRIVE 1
PRINT DFREE(0)
PRINT DIR$(2)
CHDRIVE "C:\"
CHR$(x) Returns the character from a specified ASCII code.
Example: PRINT CHR$(65) !PRINTS A
CINT(x) Changes a floating point number into a rounded integer.
(See also CFLOAT).
CIRCLE
HOW: CIRCLE x,y,r[,w1,w2]
Action: Draws a circle with centre coordinates at x,y and a radius
r. Additional start and end angles w1 and w2 can be
specified to draw a circular arc.
Example: CIRCLE 320,200,100
CLEAR
Syntax: CLEAR
Action: Clears all variables and fields.
CLEARW
Syntax: CLEARW n
Action: Clears the contents of the window numbered 'n'
CLIP x,y,w,h [OFFSET x0,y0]
CLIP x1,y1 TO x2,y2 [OFFSET x0,y0]
CLIP #n [OFFSET x0,y0]
CLIP OFFSET x,y
CLIP OFF
This group of commands provide 'Clipping' functions,ie. the
limiting of graphic display within a specified rectangular
screen area.
The command CLIP x,y,w,h defines the clipping rectangle
starting at upper left coordinates x,y and extends w wide
and h high.
The next command CLIP .. TO .. allows input of the
diagonally opposite corners of the clipping rectangle.
The third variant makes it possible to dfine the limits of
the window 'n'. The optional additional command OFFSET
x0,y0 makes it possible to redefine the origin of the
graphic display. If used in its own right this command sets
the origin for graphic display at x0,y0.
The command CLIP OFF turns clipping off.
CLOSE
Syntax: CLOSE [#n]
Action: Close a data channel or a channel to a previously OPENed
device. If the channel number is omitted, all opened
channels are closed.
CLOSEW
Syntax: CLOSEW n
Action: Closes the window numbered n.
CLR
Syntax: CLR var [ ,var ]
Action: Deletes and sets specified variables (not arrays) to 0.
CLS
Syntax: CLS [#n]
Action: Clears the screen [numbered n].
COLOR
Syntax: COLOR color
Action: Sets the colour for drawing/text. (0-15).
COMBIN
Syntax: z=COMBIN(n,k)
Action: Calculates the number of combinations of n elements to the
kth class without repetitions. Defined as z=n!/((n-k)!*k!).
CONT
Syntax: CONT
Action: Resumes execution of a program.
Continue the execution of a program after interruption.
CONTRL Address of the VDI control table.
With an index after this function, the appropriate
parameter block is accessed directly.
CONTRL(2)=x is the same as
DPOKE CONTRL+4,x
COS
Syntax: COS(x)
Action: Returns the cosine of value x (radians)
COSQ(x) Returns the cosine of value x from an internal table in
steps of 16th of a degree so is 10 times faster than COS.
(in degrees).
CRSCOL CRSLIN
Syntax: CRSCOL
CRSLIN
Action: Returns current cursor line and column. (see also PRINT
AT).
CURVE
HOW: CURVE x0,y0,x1,y1,x2,y2,x3,y3
Action: The BEZIER-Curve starts at x0,y0, and ends at x3,y3.
The curve at x0,y0 is at a tangent with a line from
x0,y0 to x1,y1; and at x3,y3 is at a tangent with
a line between x3,y3 and x2,y2.
Example:
x0=10
y0=10
x1=50
y1=110
x2=150
y2=200
x3=350
y3=300
LINE x0,y0,x1,y1
LINE x2,y2,x3,y3
CURVE x0,y0,x1,y1,x2,y2,x3,y3
CVI CVL CVS CVF CVD
Syntax: CVI(x$) .... CVD(x$)
Action: Changes character strings into numeric variables.
CVI Changes a 2-byte string into an integer
CVL " " 4-byte " " " "
CVS " " 4-byte basic string into a floating point number
CVF " " 6-byte " " " a GFA 1 or 2 "
CVD " " 8-byte " " " a GFA 3 floating point.
*******************************************************************
DATA
Syntax: DATA [CONST[,CONST] ...]
Action: Used as memory variables which can be read by the READ
command. The constants are separated by commas.
Example: For i=1 to 3
READ A
PRINT A
Next i
DATA 1,2,3,4
DATE$
Syntax: DATE$
Action: Returns the system date.
DATE$=date$ Sets the system date. (either DD.MM.YY
(UK) orMM.DD.YY (US)
The format depends on MODE setting.
DEC
Syntax: DEC var
Action: Reduces the value of 'var' by 1
DEFAULT See SELECT
DEFBIT
DEFBYT
DEFWRD
DEFFLT
DEFSTR
The instruction DEFxxx sets the varaible type to that
specified.
Example: DEFBIT "a-z" defines all variables as boolean.
DEFFILL
Syntax: DEFFILL [col],[style],[pattern] or DEFFILLL [col],A$
Action: 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
Syntax: DEFFN func [(x1,x2,..)]=expression
Action: Allows the definition of single line functions. The term
'expression' can be any numeric or string expression.
Example: DEFFN test(y,a$)=x-y+LEN(a$)
x=2
PRINT @test(4,"abcdef")
See also FN
DEFLINE
Syntax: DEFLINE [style],[thickness],[begin_s,end_s]
Action: Sets line style, width & type of line start and end.
'style' determines the style of line:
1 Solid line
2 Long dashed line
3 Dotted
4 Dot-dashed
5 Dashed
6 Dash dot dot ..
7 User defined
'thickness' sets width in pixels (odd numbers only).
The start and end symbols are defined by the last
parameter, and can be:
0 Square
1 Arrow
2 Round
DEFLIST
Syntax: DEFLIST x
Action: Defines the program listing format.
x Command Variable
0 PRINT abc
1 Print Abc
2 PRINT abc#
3 Print Abc#
DEFMARK
Syntax: DEFMARK [C],[A],[G]
Action: 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
Syntax: DEFMOUSE n or DEFMOUSE a$
Action: 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.
Example:
DEFMOUSE 2
PAUSE 1
m$=MKI$(0)+MKI$(0)+MKI$(1)+MKI$(0)+MKI$(1)
FOR i%=1 TO 16
m$=m$+MKI$(65535)
NEXT I%
FOR i%=1 TO 16
m$=m$+MKI$(1)
NEXT i%
PBOX 200,150,400,250
DEFMOUSE m$
REPEAT
UNTIL MOUSEK
DEFNUM
Syntax: DEFNUM n
Action: Affects output of numbers by the PRINT command and its
variants. All numbers are outputted to occupy n character
positions, not counting the decimal point.
DEFTEXT
Syntax: DEFTEXT [colour],[attr],[angle],[height],[fontnr]
Action: Defines the colour,style,rotation and size of text
to be printed using the text command.
'colour' colour register number (0-15).
'attr' text style - 0=normal 1=bold 2=light 4=italic
8=underlined 16=outlined (can be combined).
'angle'= rotation only the following are possible :-
0 deg (0), 90 deg (900), 180 deg (1800), 270 deg (2700)
'height' size of text - 4=icon, 6=8*8, 13=std, 32=enlarged.
'fontnr' - the number of a desired character set. This font
must have been previously installed (See also GDOS,
VST_LOAD_FONT, VQT_NAME).
Example:
FOR i%|=0 TO 5
DEFTEXT 1,2^i|,0,13
TEXT 100,i|*16+100,"This is text attribute "+STR$(i|)
NEXT i|
DEG(x) Converts x from radians to degrees. See also RAD.
DELAY x Suspends program operation for x seconds (with a
theroetical resolution in milliseconds). See aslo PAUSE.
DELETE
Syntax: DELETE x(i)
Action: Removes the ith element of array x. All elements with a
larger index are shifted down one position. See also
INSERT.
DFREE
Syntax: DFREE(n)
Action: Locates free space on a disc 'n' = drive number (0-15)
DIM
Syntax: DIM var(indices)[,var(indices),.....]
Action: Sets the dimensions of an array or string array.
DIM?
Syntax: DIM?(field())
Action: Determines the number of elements in an array.
Note - arrays have an element '0'.
DIR
Syntax: DIR "filespec" [TO "file"]
Action: Lists the files on a disc. The output can be directed to a
file or other device.
Example: "LST:" See also FILES.
DIR$
Syntax: DIR$(n)
Action: Names the active directory for drive 'n'
'n' is drive number (1=A:, 2=B: ...).
DIV
Syntax: DIV var,n
Action: Divides the value of var by n. As var=var/n but 30% faster.
DIV()
Syntax: a%=DIV(x,y)
Action: See DIV above.
DMACONTROL
Syntax: DMACONTROL ctrlvar
Action: Controls the DMA sound on the STE.
cntrlvar = 0 - stop sound
1 - Play sound once
2 - Play sound in a loop
DMASOUND
Syntax: DMASOUND beg,end,rate[,ctrl]
Action: Output of DMA sampled sound on the STE.
beg - Sample start address.
end - Sample end address.
rate - Sample rate 0=6.25 kHz, 1=12.5 kHz, 2=25 kHz,
3=50kHz.
ctrl - See DMACONTROL above.
Example: 'Try each of the DMASOUND lines below.
n%=360*32
DIM a|(n%)
'DMASOUND V:a|(0),V:a|(n%),0
'DMASOUND V:a|(0),V:a|(n%),1
'DMASOUND V:a|(0),V:a|(n%),2
DMASOUND V:a|(0),V:a|(n%),3,3
FOR i%=0 TO n%
a|(i%)=128+SINQ(i%*i%/7200)*127
NEXT i%
REPEAT
UNTIL MOUSEK
DMACONTROL 0
DO....LOOP
Syntax: DO
(instructions)
LOOP
Action: Creates an endless loop, exit only with EXIT IF or GOTO.
DO UNTIL condition
DO WHILE condition
The commands DO and LOOP can be extended using UNTIL and
WHILE. The loop DO WHILE causes a loop as long as the
condition is true. See also LOOP WHILE, LOOP UNTIL.
DOUBLE{x} Reads/writes an 8-byte floating point variable in IEEE
double precision format. (See also BYTE{}, CARD{}, INT{},
LONG{}, {}, FLOAT{}, SINGLE{}, CHAR{} )
DOWNTO Used within a FOR..NEXT loop as a counter. Instead of using
step -1, the command DOWNTO is used, however STEP is not
possible with DOWNTO. eg:
FOR c=100 DOWNTO 1
is the same as FOR c=100 TO 1 STEP -1
DPEEK(x) Reads 2 bytes from address x (a word). Works in supervisor
mode.
DPOKE x,y Writes y as a 2 byte word to address x. To work in
supervisor mode use SDPOKE ..
DRAW
Syntax: DRAW [TO] [x,y]
DRAW [x1,y1][TO x2,y2][TO x3,y3][TO..]
Action: 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 last set
point (set by PLOT, LINE or DRAW).
DRAW expression
DRAW(i)
SETDRAW
These instructions give a turtle like approach to drawing.
An imaginary pen is moved over the screen and draws
relative to the last point. The 'expression' is a LOGO type
of convention controlled by graphic commands. The pen
leaving a trail over the 'paper' leaves a graphic image.
The statement below is an wxample of how these commands can
be used.
Example: DRAW "PU FD 40 PD FD 40"
The available commands are:
FD n ForwarD Moves the 'pen' n pixels forward
BK n BacKward Moves the 'pen' n pixels backwards
SX x Scale x Scales the 'pen' movement for FD and BK
SY y Scale y by the specified factor. Use SX0 or SY0
to turn off scaling.
LT a Left turn Turns the 'pen' left through the
specified angle a, given in degrees.
RT a Right turn As LT but turns right.
TT a Turn To Turns the 'pen' to the absolute angle
'a' in degrees. (see below)
0
|
|
270 -- zero point -- 90
|
|
180
MA x,y Move Absolute Moves the 'pen' to the absolute
coordinates x,y
DA x,y Draw Absolute Moves the 'pen' to the absolute
coordinates x,y and draws a line in the
current colour from the last position to
the point x,y
MR xr,yr Move Relative Moves the 'pen' position in the x and y
directions relative to the last
position.
DR xr,yr Draw Relative Moves the 'pen' by the specified
displacement relative to its last
position and draws a line in the current
colour from the last position to this
point.
The command SETDRAW x,y,w is an abbreviation for the expression
DRAW "MA",x,y,"TT",w.
CO c Colour Sets 'c' as the character colour (see
parameters for COLOR command).
PU Pen Up Lifts the 'pen' from the 'paper'.
PD Pen Down Lowers the 'pen' onto the 'paper'.
Additionally the following interrogation functions are available:
DRAW(0) returns the x position.
DRAW(1) returns the y position.
DRAW(2) returns angle in degrees.
DRAW(3) returns the X axis scale factor.
DRAW(4) returns the Y axis scale factor.
DRAW(5) returns the pen flag (-1=PD, 0=PU).
All these functions return floating point values.
Example:
DRAW "ma 160,200 tt 0"
FOR i&=3 TO 10
polygon(i&,90)
NEXT i&
PROCEDURE polygon(n&,r&)
LOCAL i&
FOR i&=1 TO n&
DRAW "fd",r&," rt ",360/n&
NEXT i&
RETURN
EDIT
Syntax: EDIT
Action: 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
Syntax: ELLIPSE x,y,rx,ry [,phi0,phi1]
Action: 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, to create an elliptical arc.
ELSE See command IF.
ELSE IF " " "
END
Syntax: END
Action: Closes all files and terminates program execution.
ENDFUNC See command FN.
ENDIF See command IF.
ENDSELECT See command SELECT.
EOF
Syntax: EOF (#n)
Action: Determines whether the file pointer for the file with
channel number 'n' is at End Of the File. Returns -1 if it
is, otherwise 0.
EQV
Syntax: x EQV y
Action: The operator EQV (equivalence) produces a TRUE result only
if the arguments of both are either TRUE or both FALSE.
(same as NOT(x XOR y)).
EQV(x,y)
Syntax: EQV(x,y)
Action: Sets a bit of the result if the appropraite bits in x and y
are both set, or both reset. eg:
PRINT BIN$(EQV(15,6),4) prints 0110
ERASE
Syntax: ERASE field()
Action: Deletes an array and releases the dimensioned area.
ERR
Syntax: ERR
Action: Returns the error code of any error that has occurred.
ERR$
Syntax: ERR$(x)
Action: Returns, as a string, the GFA Basic error mesage x.
ERROR
Syntax: ERROR n
Action: Simulates the occurrence of the error with the error
code 'n' and the appropriate error message is then
displayed.
EVEN
Syntax: EVEN n
Action: Determines if a number is even. Returns TRUE (-1) and
FALSE(0). Also see ODD
EVERY
EVERY CONT
EVERY STOP
Syntax: EVERY ticks GOSUB proc
Action: The command EVERY causes the procedure 'proc' to be called
every 'ticks' clock units. The clock unit is defined as one
two-hundredth of a second. But a branch can only be done
every fourth clock unit, resulting in an effective time
resolution of one fiftieth of a second.
Using EVERY STOP, the calling of a procedure can be
prevented. With EVERY CONT this is again allowed. See also
AFTER.
EVNT_BUTTON
Syntax: EVNT_BUTTON(clicks,mask,state[,mx,my,button,k_state])
Action: Waits for one or more mouse clicks, and returns the number
of clicks.
INPUTS
clicks - Maximum allowable clicks.
mask - Mask for the desired mouse key:
Bit 0 = 1 : Left Button
Bit 1 = 1 : Right Button
state - Desired status, in order to terminate the event.
Bit allocation as for mask.
RETURNED VALUES:
mx - x coordinate of mouse pointer on event termination
my - y coordinate of mouse pointer on event termination
button - state of mouse button, bit allocation as for mask.
k_state- Condition of keyboard shift keys:
Bit 0 = Right shift key
Bit 1 = Left shift key
Bit 2 = Control key
Bit 3 = Alternate key
EVNT_DCLICK
Syntax: EVNT_DCLICK(new,get_set)
Action: Sets the speed for double-clicks of a mouse button.
Returns the speed.
new - new speed (0-4)
get_set - determine whether to set or read. 0=read,1=set.
EVNT_KEYBD
Syntax: EVNT_KEYBD()
Action: Waits for a key to be pressed and returns a word-sized
value. The low order byte contains the ASCII code, the high
byte contains the keyboard scan code.
EVNT_MESAG
Syntax: EVNT_MESAG(adr_buffer)
Action: Waits for the arrival of a message in the event buffer. The
returned value is always 1.
adr_buffer is the address of a 16 byte buffer for the
message. If 0 is used, then the sytem message buffer is
used, ie. MENU(1) to MENU(8).
EVNT_MOUSE
Syntax: EVNT_MOUSE(flag,mx,my,mw,mh,mcur_x,mcur_y,button,k_state)
Action: Waits for the mouse pointer to be located inside (or
optionally, outside) a specified rectangular area of the
screen.
The returned value is always 1.
INPUTS:
flag - Presence inside(0) or outside(1) the desired area.
mx,my - Coordinates of top left corner of recatngle.
mw - Width of rectangle.
mh - Height of rectangle.
OUTPUTS:
mcur_x x coordinate of mouse when event occurs.
mcur_y y coordinate of mouse when event occurs.
button same as for mask in EVNT_BUTTON.
k_state same as for k_state in EVNT_BUTTON.
EVNT_MULTI
HOW: EVNT_MULTI(flag,clicks,mask,state,m1_flags,m1_x,
m1_y,m1_w,m1_h,m2_flags,m2_x,m2_y,m2_w,m2_h,adr_buffer,
count[,mcur_x,mcur_y,button,k_state,key,num_clicks])
Action: Waits for the occurence of selected events. Returns the
event which actually occured, with bit allocation as for
'flag' below:
INPUT:
flag Sets the event(s) to be waited for as follows:
BIT 0 keyboard MU_KEYBD
BIT 1 mouse button MU_BUTTON
BIT 2 first mouse event MU_M1
BIT 3 second mouse event MU_M2
BIT 4 report event MU_MESAG
BIT 5 timer MU_TIMER
OUTPUT:
num_clicks: number of expected mouse clicks
The parameters are already described for EVNT_MESAG, etc..
With ON MENU, which uses this routine internally, the
parameters are installed for the instruction ON MENU xxx
GOSUB.
MENU(1) to MENU(8) Message buffer.
MENU(9) Returned value.
MENU(10)=mcur_x x mouse position.
MENU(11)=mcur_y y mouse pos.
MENU(12)=button Mouse state button.
MENU(13)=k_state Shift key status.
MENU(14)=key ASCII and scan code.
MENU(15)=num_clicks Number of mouse clicks.
EVNT_TIMER
Syntax: EVNT_TIMER(count)
Action: The function waits for a period of time expressed in
'count' millisecondes.
The returned value is always 1.
EXEC
Syntax: EXEC flg,name,cmd,env
EXEC (flg,name,cmd,env)
Action: 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.
EXIST
Syntax: EXIST ("filespec")
Action: Determines whether a particular file is present on
a disc. If present -1 is returned, else 0 is returned.
EXIT
Syntax: EXIT IF Condition
Action: 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
Syntax: EXP(X)
Action: Calculates the value of an exponent x.
FACT
Syntax: x=FACT(n)
Action: Calculates the factorial (n!) of n and returns the result
in x. (0!=1).
FALSE
Syntax: FALSE
Action: 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).
FATAL
Syntax: FATAL
Action: 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.
FGETDTA
Syntax: n%=FGETDTA()
Action: Returns the DTA (Disk Transfer Address).
FIELD
Syntax: FIELD #n,num AS svar$ [,num AS svar$,...]
FIELD #n,num AT(x)[,num AT(x),...]
Action: Divides records into fields.
'n' is the channel number of a file previously OPENed.
The integer expression 'num' determines the field length.
'Svar' is a string variable containing data for one field
of a data record.
The section 'num 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.
By using AT() instead of AS, numeric variables can be read
and written. 'num' contains the length of the varaible
type. The brackets contain a pointer to the variable.
eg:
FIELD #2,4 AS a$,2 AT(*b&),8 AT(*c#),6 AS d$
FILES
Syntax: FILES p$ [TO name$]
Action: Lists the files on a disk.
Like DIR but more detailed data listing.
FILESELECT
Syntax: FILESELECT [#title$],path$,default$,name$
Action: Creates a fileselect box on the screen.
Title$ can be a string of max 30 characters. Allows a
header to be placed in the fileselect box (TOS 1.4 and
above).
path$ is the drive and path - if none specified then the
default drive is assumed.
default$ contains the name of the file to apppear in the
selection line. ("" for no default).
name$ contains the selected file, either an empty string if
CANCEL is selected, or the file name selected.
See also FSEL_INPUT
Example:
FILESELECT #"LOAD File","A:\*.PRG","GFABASIC.PRG",name$
FILL
Syntax: FILL x,y
Action: Fills a bordered area with a pattern commencing at
the co-ordinates 'x,y'.
Fill pattern can be chosen with the command DEFFILL.
FIX
Syntax: FIX(x)
Action: 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.
FLOAT{x} Reads/writes an 8-byte variable in Basic v3 floating point
format. (See also BYTE{}, CARD{}, INT{},LONG{}, {},
SINGLE{}, DOUBLE{}, CHAR{} )
FN
Syntax: FN func[(y1,y2...)]
Action: Call to a defined DEFFN function or a FUNCTION. (you can
also use @). See also DEFFN, FUNCTION.
FOR...NEXT
Syntax: FOR c=b TO e [STEP s]
instructions
NEXT c
Action: Creates a loop which is executed as many times as specified
at the beginning of the loop.
FORM INPUT
Syntax: FORM INPUT n,a$
Action: Enables the insertion of a character string (limited
to 255 characters in length) during program execution.
'n' = the maximum length of the character string.
a$ is the name of the string variable.
FORM INPUT AS
Syntax: FORM INPUT n AS a$
Action: Similar to FORM INPUT, except the current value of a$ is
displayed, and can be edited.
*** the following 7 commands are part of the AES FORM Library
commands, and are similar to C bindings for calling these AES
functions ***
FORM_ALERT
Syntax: a%=FORM_ALERT(button,string$)
Action: Creates an alert box.
button = number of the default button (0-3).
string$ = string defining the message in the alert. (in C
format) - note that the square brackets are part of the
string:
[i][Message][Buttons]
where i = the required alert symbol - see ALERT.
Message is a string max 30 characters.
Buttons = the name of the 3 buttons.
A good use of this command is in trapping errors:
Example: ~FORM_ALERT(1,ERR$(ERR))
FORM_BUTTON
Syntax: FORM_BUTTON(tree,obj,clicks,new_obj)
Action: Make inputs in a form possible using the mouse.
INPUTS:
tree - address of the object tree
obj - current object number
clicks - max expected number of mouse clicks
OUTPUT:
new_obj- next object to be edited.
Returns 0 if the FORM was exited, otherwise >0.
FORM_CENTER
Syntax: FORM_CENTER(tree,fx,fy,fw,fh)
Action: Centers the tree, and returns its coordinates.
INPUT: tree - address of the object tree.
OUTPUTS:
fx,fy coordinates of top left corner
fw,fh form width and height.
returns a reserved value (always 1).
FORM_DIAL
HOW: FORM_DIAL(flag,mi_x,mi_y,mi_w,mi_h,ma_x,ma_y,ma_w,ma_h)
Action: Release (or reserve) a rectangular screen area and draw an
expanding/shrinking rectangle.
Returns 0 if an error occured.
flag function
0 FMD_START reserve a display area.
1 FMD_GROW draw expanding box.
2 FMD_SHRINK draw shrinking box.
3 FMD_FINISH release reserved display area.
mi_x,mi_y top left corner of rectangle at min size
mi_w,mi_h width & height " " " " "
ma_x,ma_y top left corner of rectangle at max size
ma_w,ma_h width & height " " " " "
FORM_DO
Syntax: FORM_DO(tree,start_obj)
Action: Pass management of FORM over to the AES until an object
with EXIT or TOUCH EXIT status is clicked on.
Returns the number of the object whose clicking or double
clicking caused the function to end. If it was a double
click, bit 15 will be set.
tree = address of the object tree.
start_obj = Number of the first editable field (if there is
one).
FORM_ERROR
Syntax: FORM_ERROR(err)
Action: Displays the ALERT associated with the error numbered err.
Example: PRINT FORM_ERROR(10)
FORM_KEYBD
Syntax: FORM_KEYBD(tree,obj,next_obj,char,new_obj,next_char)
Action: Allows a form to be edited via the keyboard.
Returns 0 if the FORM was exited, otherwise >0.
tree address of the object tree
obj number of the object to be edited
next_obj number of the next EDITable object in the tree
char input character
new_obj object to be EDITed on the next call
returns next_char - next character (derived from keyboard)
This function is a subroutine of FORM_DO.
FRAC
Syntax: FRAC(x)
Action: 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
Syntax: f%=FRE(X) or f%=FRE()
Action: Returns the amount of memory free (in bytes).
The parameter 'x' is disregarded, but if present a 'Garbage
Collection' is carried out. (non current strings are freed
from memory).
FSEL_INPUT
Syntax: n%=FSEL_INPUT(path$,name$,[button])
Action: Calls the AES fileselect library, to provide a
fileselector.
The optional parameter 'button':
Returns a 1 or 0 depending whether 'OK' or 'Cancel' was
clicked on.
ON ENTRY:
path$ = initial directory path
name$ = Default name
ON EXIT:
path$ = final directory path
name$ = chosen filename.
button = 1 if 'OK'
= 0 if 'Cancel'
FSETDTA
Syntax: ~FSETDTA(addr)
Action: Sets the address of the DTA. (See also FGETDTA).
FSFIRST
Syntax: FSFIRST(p$,attr)
Action: Searches for the first file on a disk to fulfill the
criteria specified in p$ (eg: "C:\*.GFA"). If found, the
filename and attributes are to be found in the DTA.
The parameter 'attr' is the file atributes to search on.
FSNEXT
Syntax: FSNEXT()
Action: Search for the next file which fulfills the conditions of
FSFIRST.
Example:
~FSETDTA(BASEPAGE+128)
e%=FSFIRST("\*.GFA",-1) ! all bits set
DO UNTIL e%
IF BYTE{BASEPAGE+149} AND 16 !if its a folder
PRINT "*";CHAR{BASEPAGE+158} ! indicate by a star
ELSE ! otherwise
PRINT 'CHAR{BASEPAGE+158} ! a space before
' ! the filename
ENDIF
e%=FSNEXT() ! continue search
LOOP
FULLW
Syntax: FULLW [#]n
Action: Enlarges window 'n' to full screen size.
'n' is the window number. If the window has not
yet been opened, this takes place automatically.
FUNCTION
The commands FUNCTION and ENDFUNC form a subroutine, in a
similar manner to PROCEDURE. The name of the subroutine
and, optionally, the list of varaibles are given after
FUNCTION command. Calling the subroutine is done by the use
of @ or FN and the function name followed by a list of
parameters if necessary.
If the command RETURN is met during program execution, the
the value given after it or the value of the named variable
is returned. In a function, RETURN can be used several
times, with IF or the like. A function cannot be terminated
without a RETURN command being before the ENDFUNC command.
In a function name ending with the $ character the function
returns a string result.
Example:
f1%=@fac_loop(15)
PRINT "loop: fac(15) = ";f1%
'
FUNCTION fac_loop(f%)
w=1
FOR J%=1 TO f%
MUL w,j%
NEXT j%
RETURN w
ENDFUNC
GB Address of the AES Parameter Block
This (unlike the other AES address blocks) cannot be used
with index.
GCONTRL Address of the AES control block. With index (GCONTRL(2))
the elements can be accessed directly.
GDOS? Returns TRUE (-1) if GDOS is resident and FALSE (0)
otherwise.
GEMDOS
Syntax: GEMDOS(n[,x,y])
Action: To call the GEMDOS routines. The optional parameter list
can be prefixed with W: or L: to denote word or longword
parameters. (if non given, default is W:)
Example:
DO UNTIL GEMDOS(17)
ALERT 1,"Printer not ready",1,"retry|break",d%
LOOP UNTIL d%=2
GEMSYS
Syntax: GEMSYS n
Action: Calls the AES routine 'n'. The parameters necessary for the
operation of the routine must first be placed in the
appropriate AES parameter blocks.
GET
Syntax: GET x1,y1,x2,y2,sections$
Action: GET puts a section of the screen into a string variable
'section$' (x1,y1 and x2,y2 are coordinates of diagonally
opposite corners). See also PUT.
GET #
Syntax: GET #n[,r]
Action: Reads a record from a random access file.
'n' is the channel number (1 to 99)
'r' is number of the record to be read (1 to 65535)
If 'r' is not given then the next record in the file
will be read. (See also PUT #).
GETSIZE
Syntax: bytes%=GETSIZE(x1,y1,x2,y2)
Action: The TT does not have a constant screen memory of 32000
Bytes like the ST. A screen could require much more memory
(153600 Bytes). The commands GET and PUT are limited to
32000 Bytes and therefore a function has been introduced
to support the larger screen resolutions that require more
than 32000 Bytes.
This function will return the number of Bytes required by
the screen between the coordinates x1,y1,x2,y2. Several
GET or PUT commands could be used to address the entire
screen.
GINTIN Address of the AES Integer input block. (Can be used with
index GINTIN(0)).
GINTOUT Address of the AES Integer output block. (Can be used with
index GINTOUT(0)).
GOSUB
Syntax: GOSUB name [ (LIST OF EXPRESSIONS) ]
Action: 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
Syntax: GOTO label
Action: 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.
*** The following 10 functions form the Graphics library calls to the
AES.
GRAF_DRAGBOX
Syntax: GRAF_DRAGBOX(iw,ih,ix,iy,rx,,ry,rw,rh[,last_ix,last_iy])
Action: Allows a rectangle to be moved about the screen with the
mouse. Its movement is restricted to the interior of a
larger specified rectangle. This function should only be
called when the left mouse button is held down, as it
terminates when the button is released.
Returns 0 if an error occurs.
INPUTS:
iw,ih width & height of the moving rectangle
ix,iy initial coords of top left corner of moving
rectangle
rx,ry coords of top left corner of limiting rectangle
rw,rh width & height of limiting rectangle
OUTPUTS:
last_ix coords of top left corner of inside rectangle
last_iy when the function terminated.
GRAF_GROWBOX
Syntax: GRAF_GROWBOX(sx,sy,sw,sh,dx,dy,dw,dh)
Action: Draws an expanding rectangle.
Returns 0 if error occurs.
sx,sy Initial coords of top left corner of rectangle
sw,sh Initial width & height of rectangle
dx,dy Final coords of top left corner
dw,dh Final width & height
GRAF_HANDLE
Syntax: GRAF_HANDLE(char_w,char_h,box_w,box_h)
Action: Returns the ID number of the current VDI workstation and
supplies the size of a character from the system set.
OUTPUTS:
char_w width in pixels of a character
char_h height
box_w width of a character cell
box_h height
GRAF_MKSTATE
Syntax: GRAF_MKSTATE(mx,my,m_state,k_state)
Action: This function supplies the current mouse coordinates and
status of tht mouse buttons and shift keys.
Returns a reserved value (always 1)
OUTPUTS:
mx,my mouse coordinates
m_state mouse button status
bit 0 left button
bit 1 right button
k_state see k_state in function EVNT_BUTTON
GRAF_MOUSE
Syntax: GRAF_MOUSE(m_form,pattern_adr)
Action: This function allows the mouse shape to be changed.
(similar command to DEFMOUSE)
Returns 0 if an error occurs.
m_form number of the mouse pointer shape
0 = Arrow
1 = Double curly brackets
2 = Busy bee
3 = Pointing finger
4 = Open hand
5 = Thin cross hairs
6 = Thick cross hairs
7 = Outlined cross hairs
255 = User defined
256 = Hide mouse
257 = Show mouse
pattern_adr = address of bit information defining the mouse
pointer. 37 word-sized values as follows:
1 = x coordinate of the action point
2 = y " " " " "
3 = number of colour levels, always 1
4 = mask colour, always 0
5 = pointer colour, always 1
6 to 21 = Mask definition (16 words ie.16x16 bits)
22 to 37 = Pointer def "
GRAF_MOVEBOX
Syntax: GRAF_MOVEBOX(w,h,sx,sy,dx,dy)
Action: Draws a moving rectangle with constant width & height.
Returns 0 on error.
INPUTS:
w,h width & height of rectangle
sx,sy Initial coords of top left corner of rectangle
dx,dy Final coords of top left corner
GRAF_RUBBERBOX
Syntax: GRAF_RUBBERBOX(tx,ty,min_w,min_h[,last_w,last_h])
Action: This function draws an outline of a rectangle while the the
left mouse button is held down. The top left corner is
fixed, but the width & height of the rectangle change with
the position of the mouse. This function should only be
called when the left mouse button is held down, as it
terminates when the button is released.
Returns 0 if an error occurs.
INPUTS:
tx,ty coords of top left corner
min_w,min_h minimum width & height of rectangle
OUTPUTS:
last_w width of rectangle when function terminates
last_h height " " " " "
GRAF_SHRINKBOX
Syntax: GRAF_SHRINKBOX(sx,sy,sw,sh,dx,dy,dw,dh)
Action: Draws an shrinking rectangle.
Returns 0 if error occurs.
sx,sy Final coords of top left corner
sw,sh Final width & height
dx,dy Initial coords of top left corner of rectangle
dw,dh Initial width & height of rectangle
GRAF_SLIDEBOX
Syntax: GRAF_SLIDEBOX(tree,parent_obj,slider_obj,flag)
Action: This function (really belongs to the OBJECT library) moves
one rectangular object within another, in a similar manner
to GRAF_DRAGBOX. The object can only be moved vertically or
horizontally, and must be a 'child' of the limiting object.
This function should only be called when the left mouse
button is held down, as it terminates when the button is
released. Commonly used in movement of slider bars in
windows.
Returns the position of the moving rectangle relative to
the limiting one:
Horizontally: 0 = far left 1000 = far right
Vertically: 0 = top 1000 = bottom
INPUTS:
tree address of oobject tree
parent_obj object number of the 'limiting rectangle'
slider_obj " " " " moving rectangle
flag direction (0=horizontal, 1=vertical)
GRAF_WATCHBOX
Syntax: GRAF_WATCHBOX(tree,obj,in_state,out_state)
Action: This function (really belongs to the OBJECT library)
monitors an object tree while a mouse button is pressed,
checking whether the mouse pointer is inside or outside.
When the mouse button is released, the status of the object
takes one of two specified values (normal selected/normal),
depending on whether the pointer was inside the object or
outside.
Returns 1 if the mouse pointer was inside the object when
the button was released, or 0 if it was outside.
INPUTS:
tree address of the tree
obj number of the object to be monitored
in_state Status (OB_STATE) to be given to the object if
the mouse pointer is found within it.
out_state Status (OB_STATE) to be given to the object if
the mouse pointer is found outside it.
GRAPHMODE
Syntax: GRAPHMODE n
Action: Sets the graphic mode 1 to 4.
1=replace 2=transparent
3=xor 4=reverse transparent
HARDCOPY
Syntax: HARDCOPY
Action: Prints the screen (same as pressing <ALT> & <HELP>).
HEX$
Syntax: HEX$(x[,y])
Action: Changes the value of 'x' into a string expression
which contains the value of 'x' in hexadecimal form.
The optional parameter y specifies the number of character
positions (1 to 8) to be used.
HIDEM
Syntax: HIDEM
Action: Switches off the mouse pointer. (see also SHOWM).
HIMEM
Syntax: HIMEM
Action: Returns the address of the area of memory which is not
required by GFA Basic. Normally 16384 bytes below the
screen.
HLINE
Syntax: HLINE x1,y,x2,f,m,addr,num_pattern
Action: Similar to ALINE, but only horizontal lines can be drawn.
x1 and x2 contain the x coordinates of the line start and
end points and y the common y coordinate. f is the colour
(0-15). m is the graphic mode. addr is the address of a
block of memory which contains bit information for several
line styles each of 16 bits. Which style is used for a
given line depends on both the y coordinate and the
parameter num_pattern. They are ANDed together and the
resulting number used as an index to the style table.
HTAB Positions the cursor to the specified column. (Counting
from 0). See also VTAB
IF
Syntax: IF condition [ THEN ]
program block
ELSE
program block
ENDIF
Action: Divides a program up into different blocks depending
on how it relates to the 'condition'.
ELSE IF condition
Enables nested IF's to be more clearly expressed in a
program.
Example: 'the following code has no ELSE IF's
DO
t$=CHR$(INP(2))
IF t$="l"
PRINT "Load text"
ELSE
IF t$="s"
PRINT "Save text"
ELSE
IF t$="e"
PRINT "Enter text"
ELSE
PRINT "unknown command"
ENDIF
ENDIF
ENDIF
LOOP
The use of ELSE IF produces shorter code:
DO
t$=CHR$(INP(2))
IF t$="l"
PRINT "Load text"
ELSE IF t$="s"
PRINT "Save text"
ELSE IF t$="e"
PRINT "Enter text"
ELSE
PRINT "unknown command"
ENDIF
LOOP
IMP
Syntax: x IMP y
Action: The operator IMP (implication) corresponds to a logical
consequence. The result is only FALSE if a FALSE
expression follows a TRUE one. The sequence of the argument
is important.
IMP()
Syntax: IMP(x,y)
Action: This function resets a bit if the appropriate bit in x is
set and y is reset, otherwise the bit is set.
INC
Syntax: INC var
Action: Increases the value of 'var' by 1. the same as
var=var+1 but executes aprox 3.5 times faster
INFOW
Syntax: INFOW n,"string$"
Action: 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 off and on
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$
Syntax: INKEY$
Action: 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.
Example:
DO
t$=INKEY$
IF t$<>""
IF LEN(t$)=1
PRINT "Character: ";t$,"ASCII code:";ASC(t$)
ELSE
PRINT "CHR$(0)+Scan code ";CVI(t$)
ENDIF
ENDIF
LOOP
INLINE
Syntax: INLINE var,length
Action: Reserves an area of memory within a program.
var is any integer variable
length is how much memory to reserve, less than 32700 bytes
The reserved area always starts at an even address and is
initially filled with zeros. When implementing INLINE this
address is written to the integer variable adr. When the
program is loaded or saved, the reserved area is also.
Placing the cursor on the line containing the command
INLINE and pressing the HELP key causes a new menu to
appear with the entries: LOAD SAVE DUMP CLEAR. Load is used
to load a machine code program or data into the reserved
area, save saves the reserved area to disk (default
filename extension .INL). DUMP printsout the reserved area
in hex to the printer and CLEAR clears the araea of memory.
INP INP&(#) INP%(#)
OUT OUT& OUT%
Syntax: INP(#n)
OUT #n,a[,b,c...]
Action: Reads one byte from a file previously opened with OPEN.
Similarly OUT#n sends a byte to a file. The numerical
expression n is the channel number under which the channel
was opened.
INP and OUT without the # can be used for communicating
with the screen, keyboard etc. eg INP(2) takes a character
from the keyboard.
These functions cater for 16 and 32 bit input and output.
Example: a%=CVL(INPUT$(4,#1)) is replaced by a%=INP%(#1)
INP(n)
INP?(n)
OUT[#]n,a[,b..]
OUT?(n)
INP reads a byte from a peripheral device. The numerical
expression n can accept values 0-5 (see table below), or
contains a channel number(#n). The command OUT sends a byte
to a peripheral device. You can send several bytes with one
OUT command.
INP? and OUT? determine the input or output status of a
device. TRUE(-1) is device is ready ortherwise FALSE(0).
n Device
0 LST: (list) Printer
1 AUX: (Auxiliary) RS232
2 CON: (Console) Keyboard/screen
3 MID: (MIDI) MIDI Interface
4 IKB: (Intelligent kbd) Keyboard processor
5 VID: (Video) Screen
INPAUX$
INPMID$
Using these two commands, data can be read from the serial
and MIDI interfaces.
Example:
DO
PRINT INPAUX$;
LOOP
INPUT
Syntax: INPUT ["text",]x{,y,...]
INPUT ["text";]x[,y,...]
Action: Allows entry of data during program execution.
If "text" is given, then a string prompt is displayed.
Example:
INPUT a$
INPUT "",b$
INPUT "enter two numbers: ";x,y
INPUT$
Syntax: INPUT$(count[,#n]))
Action: Reads 'count' characters from the keyboard and assigns them
to a string. Optionally, if the channel number n is
specified, the characters are read in from a previously
OPENed channel.
INPUT #n,var1[,var2,var3,...]
LINE INPUT #n,a1$[,a2$,a3$,...]
These commands make it possible to take data from a
previously OPENed device. Individual variables or variable
lists (where the vars are separated by commas) can be
input.
INSERT
Syntax: INSERT x(i)=y
Action: Inserts an element into an array. The value of the
expression y is inserted into the position x(i). All
elements of the array are shifted up by one position, and
the last element lost. See also DELETE.
INSTR
Syntax: INSTR([n,]a$,b$) OR INSTR(a$,b$[,n])
Action: 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
Syntax: INT(x)
Action: Determines the largest integer that is less than or
equal to 'x'.
INTIN Address of the VDI integer input block. Also works with
index INTIN(2).
INTOUT Address of the VDI integer output block. Also works with
index INTOUT(2).
INT{x} Reads/writes a 2 byte signed integer from/to address x.
(See also BYTE{}, CARD{}, LONG{}, {}, FLOAT{}, SINGLE{},
DOUBLE{}, CHAR{} ).
KEYDEF
Syntax: KEYDEF n,s$
Action: Assign a string to a Function Key. The number n (1-20) is
the function key (for 11 and above use shift + function
key). The string is any string. Whilst using the Basic
Editor, you must also hold down the Alternate key,
otherwise the normal menu commands would not work!
KEYGET n
KEYLOOK n
KEYTEST n
KEYTEST is simialr to INKEY$ and reads a character from the
keyboard. If no key was pressed since the last input (apart
from Alternate, Control, Shift and Caps Lock) the returned
value is zero, otherwise its value corresponds to the key
in the fashion shown below for KEYGET.
KEYGET waits for a key to be pressed and then returns a
long word value corresponding to the key. This 32 bit word
is constructed as follows:
Bits 0-8 the ASCII code
Bits 8-15 Zero
Bits 16-23 the scan code
Bits 24-31 status of Shift, Control, Alternate, Caps lock
as follows:
Bit Key
24 Right shift
25 Left shift
26 Control
27 Alternate
28 Caps Lock
KEYLOOK allows a character to be read from the keyboard
buffer, without changing the buffer's contents, as with
KEYGET or INKEY$.
KEYPAD n Sets the usage of the numerical keypad. The numerical
expression n is evaluated bit by bit and has the following
meaning:
Bit Meaning 0 1
0 NUMLOCK On Off
1 NUMLOCK Not Switchable Switchable
2 CTRL-KEYPAD Normal Cursor
3 ALT_KEYPAD Normal ASCII
4 KEYDEF without ALT Off On
5 KEYDEF with ALT Off On
With bit 0 set the keypad will act as a 'PC' keypad with
numlock off ie. it responds with cursor movements.
With bit 1 set the 'PC' numlock mode can be toggled with
Alternate and '-', otherwise it can't.
With bit 2 set, numlock is effecively switched off while
the Control key is held down. Thus Control-4 (on the
keypad) produces cursor movements.
With bit 3 set ASCII values for characters can be typed in
with the Alternate key held down. When ALT is released the
character appears.
With bit 4 set, the character strings assigned with KEYDEF
to the function keys are output when the key is pressed.
With bit 5 set, the Alternate key must aslo be held down.
The deafult when the ST is turned on is KEYPAD 0. with GFA
Basic in operation it is 46.
KEYPRESS n
This simulates the pressing of a key. The character with
the ASCII code contained in the lowest 8 bits of 'n' is
added to the keyboard buffer. Additionally the status of
the Shift, Control and Alternate keys may be passed in the
high order bits as defined in KEYGET. If the ASCII code
given is zero, a scan code may be passed in bits 16-23.
Example:
KEYPRESS &H3B0000 presses F1.
Example:
FOR i&=65 TO 90 ! Simulates the pressing
KEYPRESS i& ! of keys A-Z
NEXT i&
KEYPRESS 13 !followed by Carriage Ret
INPUT a$ !Characters are taken up
' !to the first CR.
PRINT a$
KILL
Syntax: KILL "filespec"
Action: Deletes a file off disk (only one at a time).
L: Enable the passing of numerical expressions to Operating
system functions or to machine code routines. L: is a long
word.
Example: ~XBIOS(5,L:log_base%,L:phys_base%,-1)
LEFT$
Syntax: LEFT$(a$[,x])
Action: Returns the first [or first 'x'] character[s] of a string.
LEN
Syntax: LEN(x$)
Action: Returns the length of a string.
LET
Syntax: [LET] var=expression
Action: Assigns a variable with the value of an expression.
LINE
Syntax: LINE x,y,xx,yy
Action: Connects two points ('x,y' & 'xx,yy') with a straight
line, and is identical to DRAW x,y TO xx,yy.
LINE INPUT
Syntax: LINE INPUT ["text",]var$ [,var$... ]
LINE INPUT ["text";]var$ [,var$... ]
Action: Makes it possible to enter a string during program
execution.
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.
LINE INPUT# See INPUT#
LIST
Syntax: LIST "filename"
Action: stores the program currently in memory to disk 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 saved using LIST (or SAVE,A from the menu bar)
LLIST
Syntax: LLIST
Action: Prints out the listing of the current program. The setting
for the type of output is controlled by the '.' commands in
the editor.
LOAD
Syntax: LOAD "filespec"
Action: Loads a program into memory.
LOC
Syntax: LOC(#n)
Action: 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
Syntax: LOCAL var [ ,var.... ]
Action: Declares 'var' to be a local variable.
LOCATE
Syntax: LOCATE row,column
Action: Positions the cursor to the specified location.
LOF
Syntax: LOF(#n)
Action: Returns length of file OPENed for channel number 'n'.
LOG LOG10
Syntax: LOG(x)
LOG10(x)
Action: Determines the natural logarithm (log) or the logarithm
base 10 (log10) of 'x'.
LONG{x} Reads/writes a 4 byte integer from/to address x.
or (See also BYTE{}, CARD{}, INT{}, FLOAT{}, SINGLE{},
{x} DOUBLE{}, CHAR{} ).
LOOP See DO
LOOP UNTIL condition
LOOP WHILE condition
The commands DO and LOOP can be extended using UNTIL and
WHILE. LOOP WHILE causes the program to jump back to the DO
command as long as the condition is true. LOOP UNTIL
requires the condition to be false to cause the loop back.
LPEEK(x) Reads a 4 byte integer from address x. (In supervisor mode)
LPENX For the STE. Returns the x coordinate of a light pen.
LPENY For the STE. Returns the y coordinate of a light pen.
LPOKE n,x Writes a 4 byte ineger 'x' to address n. Not in supervisor
mode. (Add an 'S' to do in super mode ie. SLPOKE n,x).
LPOS
Syntax: LPOS(n)
Action: Returns the column in which the printer head (in the printer
buffer) is located.
LPRINT
Syntax: LPRINT [expressions [,][;][']]
Action: 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
Syntax: LSET var=string
Action: Puts the 'string' in the string variable 'var' justified
to the left.
L~A Returns the base address of the LINE-A variables.
MALLOC(x) Allocates an area of memory. (GEMDOS 72) If x is -1, then
the function returns the largest contiguous free memory
block. If x is positive, then MALLOC reserves that area of
memory and returns its base address. If 0 is returned then
there was a fault with the allocation.
See also RESERVE, MFREE, MSHRINK.
The following 33 commands are for the handling of MATRIXES
MAT ADD
MAT ADD a(),b()
MAT ADD a(),x
MAT ADD a()=b()+c()
MAT BASE
MAT CLR a()
MAT CPY
MAT CPY a([i,j])=b([k,l])[,h,w]
MAT DET x=a([i,j])[,n]
MAT INPUT #i,a()
MAT INV a()=b()
MAT MUL
MAT MUL a(),x
MAT MUL a()=b()*c()
MAT MUL x=a()*b()
MAT MUL x=a()*b()*c()
MAT NORM a(),0
MAT NORM a(),1
MAT ONE a()
MAT PRINT
MAT PRINT [#i]a[,g,n]
MAT QDET x=a([i,j])[,n]
MAT RANG x=a([i,j])[,n]
MAT READ
MAT READ a()
MAT SET a()=x
MAT SUB
MAT SUB a(),b()
MAT SUB a(),x
MAT SUB a()=b()-c()
MAT TRANS a()[=b()]
MAT XCPY
MAT XCPY a([i,j])=b([k,l])[,h,w]
Linear operations with vectors and matrices.
All THE MAT functions described relate only to one and/or two-
dimensional fields with floating point variables.
System commands
MAT BASE 0
MAT BASE 1
The MAT BASE command can only sensibly be used when OPTION BASE 0
has been activated. In this case, MAT BASE 1 can be used to set
the offset for the start of the row and column indexing of one or
two-dimensional fields with floating point variables to 1 for the
matrix operations. MAT BASE 0 resets this offset to 0 after a MAT
BASE 1.
The setting made with MAT BASE n affects the following commands
MAT READ
MAT PRINT
MAT CPY
MAT XCPY
MAT ADD
MAT SUB
MAT MUL
The default is MAT BASE 1.
Generating commands
MAT CLR a()
MAT SET a()=x
MAT ONE a()
a: Name of field with numeric variables
x: aexp
MAT CLR a() corresponds to an ARRAYFILL a(),0, i.e. the command
sets all elements in the field (matrix or vector) a() to a value
of 0.
MAT SET a()=x corresponds to an ARRAYFILL a(),x, i.e. the command
sets all elements in the field a() (matrix or vector) to the
value x.
MAT ONE a() generates from a square matrix a() a uniform matrix,
i.e. a square matrix in which elements a(1,1),a(2,2),...,a(n.n)
are all equally 1 and all other elements equally 0.
Write and Read commands
MAT READ a()
MAT PRINT [#i]a[,g,n]
MAT INPUT #i,a()
i,g,n: iexp
a: Name of field with numerical variables
MAT READ a() reads a previously dimensioned matrix or vector from
DATA rows.
MAT PRINT [#i,]a()[,g,n] outputs a matrix or a vector. Vectors
are output on one row, the elements being separated by commas.
With matrix, each row is followed by a rowfeed.
The output can optionally be redirected with #i, as with PRINT.
If g and n are specified, the numbers are formatted as with
STR$(x,g,n).
MAT INPUT #1,a() reads a matrix or vector from a file in ASCII
format (the format being the reverse of MAT PRINT, commas and
rowfeeds may be varied as with INPUT #).
Copy and Transposition commands
MAT CPY a([i,j])=b([k,l])[,h,w]
MAT XCPY a([i,j])=b([k,l])[,h,w]
MAT TRANS a()[=b()]
a,b: Name of fields with numerical variables
i,j,k,l,h,w: iexp
MAT CPY a([i,j])=b([k,l])[,h,w] copies h rows with w elements
each from matrix b to the row and column offset of matrix a
defined by i,j, starting from the row and column offset of matrix
b defined by l,k.
Special cases
MAT COPY a()=b() copies the complete matrix b into matrix a if
the matrix are of the same order.
Only those elements are copied in this process for which identi-
cal indices are given in both the source and the destination
matrix.
MAT COPY a(i,j)=b() copies matrix b, starting from the row and
column offset defined by MAT BASE, to the row and column offset
of matrix a defined by i,j. Only those elements are copied for
which identical indices are given in both the source and the
destination matrix.
MAT COPY a()=b(i,j) copies matrix b, starting from the row and
column offset defined by i,j, to the offset of matrix a defined
by MAT BASE. Only those elements are copied for which identical
indices are given in both the source and the destination matrix.
MAT COPY a(i,j)=b(k,l) copies matrix b, starting from the row and
column offset defined by k,l, to the offset i,j of matrix a. Only
those elements are copied for which identical indices are given
in both the source and the destination matrix.
MAT COPY a()=b() copies h rows with w elements each from the
matrix b, starting from the row and column offset defined by MAT
BASE, the row and column offset of matrix a defined by MAT BASE.
Only those elements are copied for which identical indices are
given in both the source and the destination matrix.
MAT XCPY a([i,j])=b([k,l])[,h,w] works basically in the same
manner as MAT CPY a([i,j])=b([k,l])[,h,w], except that matrix b
is being transposed while being copied to matrix a, i.e. the rows
and columns of matrix b are swapped while it is copied to matrix
a. Array b remains unchanged, however. Only those elements are
copied for which identical indices are given in both the source
and the destination matrix.
Further special cases
As with MAT CPY a(i,j)=b(k,l),w,h.
If MAT CPY or MAT XCPY are applied to vectors, j and l may be
ignored. Following a DIM a(n),b(m), a() and b() are interpreted
as row vectors, i.e. as matrix of the (1,n) or (1,m) types.
For a and b to be treated as column vectors, they must be
dimensioned as matrix of the (n,1) or (m,1) type, ie. DIM
a(n,1),b(n,1).
If both vectors are of the same order (both are row or column
vectors), MAT CPY must be used. Irrespective of the type of
vectors a and b, MAT CPY always treats both vectors syntactically
as column vectors, so that the correct syntax to be used for MAT
CPY is always
MAT CPY a(n,1)=b(m,1)!
MAT CPY a(3,1)=b(1,1) ! interprets a() and b() as column vectors
For MAT XCPY, one of the two vectors a and b must be explicitly
dimensioned as a row vector, the other as a column vector.
Since MAT XCPY first transposes the second vector before copying
it to the first. For this reason, MAT XCPY can only be used for
DIM a(1,n),b(m,1): a()=row vector, b()=column vector and DIM
a(n,1),b(1,m): a()=column vector, b()=row vector.
Optionally, the parameters h and w can also be used when copying
vectors with MAT CPY or MAT XCPY. However, the following
applies: with MAT CPY, only the h parameter is used for w=>1. No
copying takes place with w=0.
With MAT XCPY, only h is used for w=>1 if b is a column vector to
be copied into a row vector after transposition. No copying takes
place when w=0. On the other hand, only w is used for h=>1 if b
is a row vector which is to be copied to a column vector after
transposition. In this case, no copying takes place if h=0.
MAT TRANS a()=b() copies the transposed from matrix b to matrix a
if a and b are dimensioned accordingly, i.e. the number of rows
from a must correspond to the number of columns in b, and the
number of columns from a to the number of rows of n.
In the case of a square matrix, i.e. one with equal numbers of
rows and columns, MAT TRANS a() may be used. This command swaps
the rows and columns of matrix a and writes the matrix thus
changed back to a.
(The original matrix is lost in the process (but can be restored
with another MAT TRANS a()).
Operation commands
MAT ADD a()=b()+c()
MAT ADD a(),b()
MAT ADD a(),x
MAT SUB a()=b()-c()
MAT SUB a(),b()
MAT SUB a(),x
MAT MUL a()=b()*c()
MAT MUL x=a()*b()
MAT MUL x=a()*b()*c()
MAT MUL a(),x
MAT NORM a(),0
MAT NORM a(),1
MAT DET x=a([i,j])[,n]
MAT QDET x=a([i,j])[,n]
MAT RANG x=a([i,j])[,n]
MAT INV a()=b()
a,b,c: Names of numerical floating point fields
x: aexp; scalar value
i.j,n: aexp
MAT ADD a()=b()+c() is only defined for matrix (vectors) of the
same order, e.g. DIM a(n,m),b(m,m),c(n,m) or DIM a(n),b(n),c(n).
Array c is added to matrix b, element by element, and the result
is written to matrix a.
MAT ADD a(),b() is only defined for matrix (vectors) of the same
order, e.g. DIM a(n,m),b(n.m) or DIM a(n),b(n). Array b is added
to matrix a, element by element, and the result is written to
matrix a. The original matrix a is lost in the process.
MAT ADD a(),x is defined for all matrix (vectors). Here, the
scalar x is added to matrix a, element by element, and the result
is written to matrix a. The original matrix a is lost in the
process.
MAT SUB a()=b()+c() is only defined for matrix (vectors) of the
same order, e.g. DIM a(n,m),b(n,m),c(n,m) or DIM a(n),b(n),c(n).
Array c is subtracted from matrix b, element by element, and the
result is written to matrix a.
MAT SUB a(),b() is only defined for matrix (vectors) of the same
order, e.g. DIM a(n,m),b(n,m) or DIM a(n),b(n). Array b is
subtracted from matrix a, element by element, and the result
written to matrix a. The original matrix a is lost in the process.
MAT SUB a(),x is defined for all matrix (vectors). Here, the
scalar x is subtracted from matrix x, element by element, and the
result is written to matrix a. The original matrix a is lost in
the process.
MAT MUL a()=b()*c() is defined for matrix of an "appropriate"
order. Arrays b and c are multiplied with each other. The result
of this multiplication is written to matrix a. In order for the
result to be defined, the matrix on the left (matrix b in this
case) must have the same number of columns as the matrix on the
right (c in this case) has rows. Array a, in this case, must have
as many rows as b and as many columns as c.
Arrays are multiplied as "row by column", i.e. element a(i.j) is
obtained by multiplying the elements in the ith row of matrix b
with the elements in the jth column of matrix c, element by
element, and then adding up the individual products.
With vectors instead of matrix, MAT MUL a()=b()*c() results in
the dyadic (or external) product of two vectors.
MAT MUL x=a()*b() is only defined for vectors with an equal
number of elements. The result x is the scalar product (the so-
called interior product) of vectors a and b. The scalar product
of two vectors is defined as the sum of n products
a(i)*b(i),i=1,...,n.
MAT MUL x=a()*b()*c() is defined for qualified Vectors a and c
as well as qualified Matrix b().
MAT NORM a(),0 or MAT NORM a(),1 are defined for matrix and
vectors. MAT NORM a(),0 normalises a matrix (a vector) by rows,
MAT NORM a(),1 by columns. This means that after a normalisation
by rows (by columns) the sum of the squares of all elements in
each row (column) is identical at 1.
MAT DET x=a([i,j])[,n] calculates the determinants of a square
matrix of the (n,n) type. The row and column offsets are preset
to a(0,0) or a(1,1), depending on MAT BASE 0 or MAT BASE 1,
assuming that OPTION BASE 1 is enabled. It is also possible,
however, to calculate the determinant of a square part matrix. To
do this, the row and column offsets of a() must be specified as i
and j, and the number of elements in the part matrix as n. A part
matrix of the (n,n) type is then created internally starting from
the "position" ith row, jth column.
MAT QDET x=a([i,j])[,n] works in the same manner as MAT DET
x = a([i,j])[,n], except that it has been optimised for speed
rather than accuracy. Both will normally produce identical re-
sults. With "critical" matrix, whose determinant is close to 0,
you should always use MAT DET, though.
MAT RANG x=a([i,j])[,n] outputs the rank of a square matrix. As
with MAT DET or MAT QDET, you can select any row and column
offset. The number of elements in the part matrix must be
specified with n. This creates a part matrix of the (n,n) type
internally, starting from the "position ith row, jth column.
MAT INV b()=a() is used to determine the inverses of a square
matrix. The inverse of matrix a() is written to matrix b(), hence
b() must be of the same type as a().
MAX
Syntax: MAX(x [,y,z,...]) or MAX(a$[,y$,z$....])
Action: Returns the greatest value (or largest string) from
a list of expressions.
MENU(x) Returns the information about an event in the variable
'x' (-2 to 15). In the case where an item in a menu is
selected, the index of that item is found in MENU(0).
MENU(-2) is the address of the message buffer.
MENU(-1) is the address of the menu object tree.
The Message Buffer lies in the the variables MENU(1)
to MENU(8) and the AES Integer Output Block in MENU(9)
to MENU(15).
The Identification number of the event is in MENU(1).
The other elements of the message bufffer contain
various values, depending on the type of event that
occured.
MENU(1)=10 A Menu Item was selected.
MENU(0) Menu item index in the item list
MENU(4) Object number of the menu title
MENU(5) Object number of the chosen menu
item
MENU(1)=20 A window redraw is required
MENU(4) ID number (handle) of the window
MENU(5),(6) Coordinates of top left corner of
the window
MENU(7),(8) Width & height of the window area
MENU(1)=21 A window was clicked (activated)
MENU(4) ID number (handle) of the window
MENU(1)=22 The close box of a window was
clicked on
MENU(4) ID number (handle) of the window
MENU(1)=23 The full box was clicked on
MENU(4) ID number (handle) of the window
MENU(1)=24 One of the four arrow boxes, or a
slider bar area was clciked. The
movement of a slider is detected as
below, MENU(1)=24 only when the
grey area is clicked on.
MENU(4) ID number (handle) of the window
MENU(5) The area of the window that was
clicked:
0: Above the vertical slider
1: Below " " "
2: Up arrow
3: Down arrow
4: Left of the horizontal slider
5: Right " " " "
6: Left arrow
7: Right arrow
MENU(1)=25 The horizontal slider was moved
MENU(4) ID number (handle) of the window
MENU(5) Position of the moved slider (1 to
1000)
MENU(1)=26 The vertical slider was moved
MENU(4) ID number (handle) of the window
MENU(5) Position of the moved slider (1 to
1000)
MENU(1)=27 The size of the window was changed
(using the size box)
MENU(4) ID number (handle) of the window
MENU(5),(6) New x and y coordinates of top left
MENU(7),(8) New width & height
MENU(1)=28 The window's position was changed
same parameters as above
MENU(1)=29 A new GEM window was activated.
MENU(4) ID number (handle) of the window
MENU(1)=40 An Accessory was selected. This
value can only be received by an
accessory, which should chech the
value in MENU(5) to see if it is
that one being referred to.
MENU(5) ID of the accessory
MENU(1)=41 An accessory was closed. This value
can only be received from an
accessory.
MENU(5) ID of the accessory
The varaible MENU(9) contains bit information on which
kind of event has occurred. If the bit for the
appropriate event is set, the variables MENU(9) to
MENU(15) and GINTOUT(0) to GINTOUT(6) will contain
information as follows:
Bit 0 Keyboard
Bit 1 Mouse button
Bit 2 Mouse has entered/left rectangle 1
Bit 3 Mouse has entered/left rectangle 2
Bit 4 A message arrived in the message buffer
Bit 5 Timer event
MENU(10) x position of mouse when event terminated
MENU(11) y position of mouse when event terminated
MENU(12) Mouse buttons pressed:
0 = none
1 = left
2 = right
3 = both buttons
See also ON MENU BUTTON
MENU(13) supplies the status of the keyboard shift
keys in a bit pattern:
Bit 0 = right shift
Bit 1 = left shift
Bit 2 = control
Bit 3 = alternate
See also ON MENU KEY
MENU(14) Gives information about a pressed key. The
low order byte contains the ASCII code, and
the high order byte, the keyboard scan code
MENU(15) Returns the number of mouse clicks that
caused the event
MENU
Syntax: MENU m$()
Action: Displays a menu bar. The string array m$() contains
the headings, entries and reserved space for
accessories for the menu bar. The following format
must be adhered to:
m$(0) Name of the accessory menu heading
m$(1) Name of the first entry in the first menu
m$(2) A line of minus signs
m$(3)-m$(8) Reserved space for accessories. These
elements need only be 1 character long.
m$(9) An empty string, which marks the end of
the first menu.
All further menu entries have the following format:
1. Heading of the menu
2. List of menu entries
3. An empty string which marks the end of the menu.
After the last entry, a further empty string signifies
the end of the entire pull down menu.
eg:
DIM entry$(20)
DATA " Desk "," Test "
DATA ----------,1,2,3,4,5,6,""
DATA " File "," Load "," Save "
DATA --------," Quit ",""
DATA " Titles "," Entry 1 "," Entry 2 ",""
DATA End
i%=-1
REPEAT
INC i%
READ entry$(i%)
UNTIL entry$(i%)="End"
entry$(i%)=""
MENU entry$()
ON MENU GOSUB evaluate
'
REPEAT
ON MENU
UNTIL MOUSEK AND 2
'
PROCEDURE evaluate
MENU OFF
' MENU(0) contains array index of selected item
m%=MENU(0)
PRINT entry$(m%)
'
ALERT 0,"Tick before item ?",0,"YES|NO",a%
IF a%=1
MENU m%,1
ELSE
MENU m%,0
ENDIF
'
ALERT 0,"Lightened characters | (Not selectable)",0,"YES|NO",a%
IF a%=1
MENU m%,2
ELSE
MENU m%,3
ENDIF
RETURN
MENU x,y
Action: The x-th entry of a menu can be given certain (y)
attributes:
0 remove tick from in front of menu entry
1 install tick " " " " "
2 make menu entry non selectable (light text)
3 make menu entry selectable (normal text)
See MENU example.
MENU KILL
Action: Deactivates a menu, but does not remove it from the
screen. Also turns off the ON MENU GOSUB options.
MENU OFF
Action: Returns a menu title to 'normal' display. (After an
item is chosen from a menu, the title is shown in
reverse video).
MENU_BAR
Syntax: a%=MENU_BAR(tree%,flag)
Action: Displays/erases a menu bar (from a resource file)
Returns 0 if an error occurred.
tree = address of the menu object tree
flag - 1 display bar
- 2 erase bar
See also MENU x$ and MENU KILL
MENU_ICHECK
Syntax: a%=MENU_ICHECK(tree,item,flag)
Action: Deletes/displays a tick against a menu item.
tree = address of the menu object tree
item = object number of the menu item
flag - 1 delete tick
- 2 display tick
See also MENU x,0 and MENU x,1
MENU_IENABLE
Syntax: a%=MENU_IENABLE(tree,item,flag)
Action: Enables/disables a menu entry.
tree = address of the menu object tree
item = object number of the menu entry
flag - 1 disable
- 2 enable
See also MENU x,2 and MENU x,3
MENU_REGISTER
Syntax: a%=MENU_REGISTER(ap_id,m_text$)
Action: Give a desk accessory a name, and insert it into the
accessory menu entries. (provided the number of Accs
is less than 6).
Returns the object number of the appropriate menu
item:
0-5 for a valid result
-1 no more entries possible
ap_id = ID number of the accessory
m_text$ = name for the Accessory
MENU_TEXT
Syntax: a%=MENU_TEXT(tree,item,new_text$)
Action: Changes the text of a menu item.
Returns 0 on error.
tree = address of the menu object tree
item = object number of the menu item
new_text$ the new text for the menu entry (may not
exceed the old text length)
MENU_TNORMAL
Syntax: a%=MENU_TNORMAL(tree,title,flag)
Action: Switches the menu title to normal/inverse video.
Returns 0 on error.
tree = address of the menu object tree
item = object number of the menu item
flag - 1 inverse video
- 2 normal video
See MENU OFF
MFREE
Syntax: a%=MFREE(y)
Action: (GEMDOS 73) Releases the storage location reserved
with MALLOC. The parameter 'y' specifies the start of
the area of memory to be released. Returns 0 if no
error occurred, otherwise negative result.
MID$
Syntax: MID$(a$,x[,y]) (as a function)
Action: Returns 'y' characters in a string from the positon 'x'
of the string 'a$'. If x is larger than the length of
a$, then a null string is returned. If y is omitted,
then the function returns the whole of the string from
position x onwards.
MID$
Syntax: MID$(a$,x[,y]) (as a command)
Action: MID$ used as a command, makes it possible to replace
part of a string variable a$ with the string
expression b$. So with MID$(a$,x,y)=b$, characters
from b$ will overwrite those in a$, starting at the x-
th postion of a$. The optional parameter y determines
how many characters of b$ are used. If y is omitted,
then as many characters as possible of a$ are replaced
with those from b$. The length of a$ is unchanged, so
that no charatcers will be written beyond the end of
a$
eg:
a$="GFA SYSTEMTECHNIK"
MID$(a$,5)="BASIC "
would result in a$ being "GFA BASIC TECHNIK"
MIN
Syntax: MIN(expression [ ,expression... ])
Action: Returns the smallest value (or smallest string) from
a list of expressions.
MKDIR
Syntax: MKDIR "directory name"
Action: Creates a new directory.
'directory name' is the name of the new directory.
MKI$ MKL$ MKS$ MKF$ MKD$
Syntax: MKI$(N)
MKL$(N)
MKS$(N)
MKF$(N)
MKD$(N)
Action: 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,CVD,CVF
MOD
Syntax: a=x MOD y or a=MOD(x,y)
Action: Produces the remainder of the division of x by y.
The command in brackets operates in integer
arithmetic.
MODE
Syntax: MODE n
Action: With MODE the representation of decimal point and the
'thousands comma' are interpreted by PRINT USING (and
also by STR$ with 3 parameters).
Also selects the format of date representation used by
DATE$, SETTIME, and FILES.
MODE USING DATE$
0 #,###.## 16.05.1988
1 #,###.## 05/16/1988
2 #.###,## 16.05.1988
3 #.###,## 05/16/1988
MONITOR
Syntax: MONITOR [x]
Action: Calls a monitor resident in memory. This instruction
causes an illegal instruction vector. (address 16).
The parameter x is passed via the register D0.
MOUSEX
MOUSEY
MOUSEK
MOUSE mx,my,mk
Syntax: MOUSE x,y,k
x=MOUSEX
y=MOUSEY
k=MOUSEK
Action: 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
MSHRINK
Syntax: a%=MSHRINK(y,z)
Action: (GEMDOS 74) Reduces the size of a storage area
previously allocated with MALLOC. y specifies the
address of the area,z gives the required size.
Returns 0 if no error, -40 if incorrect address, or -
67 if size wrong.
See also RESERVE MALLOC MFREE
MUL
Syntax: MUL var,n
Action: Multiplies the value 'var' by 'n'.
same as var=var*n but executes 30% faster.
MUL() Same as for MUL. but integers only.
MW_OUT
Syntax: MWOUT mask,data
This command controls the STE-Internal Micro-Wire-
Interface, and is currently used for controlling
sound.
MWOUT &H7FF,x
x=&X10 011 ddd ddd Set Master Volume
000 000 -80 dB
010 100 -40 dB
101 xxx 0 dB
The value of the last 5 Bits is eqivalent to HALF of
the volume in dB.
x=&X10 101 xdd ddd Set Right Channel Volume
00 000 -40 dB
01 010 -20 dB
10 1xx 0 dB
x=&X10 100 xdd ddd Set Right Channel Volume
The last 4 Bits*2 = dB
x=&X10 010 xxd ddd Set Treble
x=&X10 001 xxd ddd Set Bass
0 000 -12dB
0 110 0 dB (flat)
1 100 +12 dB
x=&X10 000 xxx xdd Set Mix
00 -12dB
01 Mix GI Sound (normal ST)
10 Not Mix
11 Reserved
Example: MWOUT &H7FF,&X10000000010 Switches the ST's sound off.
NAME
Syntax: NAME "oldfile" AS "newfile"
Action: Renames an existing file. The contents of the file are
not affected.
NEW
Syntax: NEW
Action: Deletes the program currently in memory and clears all
variables.
NOT
Syntax: NOT x
Action: Negates a given logical expression.
The following 19 commands belong to the AES Object library.
OBJC_ADD
Syntax: a%=OBJC_ADD(tree,parent,child)
Action: Adds an object to a given tree and pointers between
the existing objects and the new object are created.
Returns 0 on error.
tree address of the object tree
parent object number of the parent object
child object number of the child to be added.
OBJC_CHANGE
Syntax: a%=OBJC_CHANGE(tree,obj,res,cx,cy,cw,ch,new_status,re_draw)
Action: Changes the status of an object.
Returns 0 on error.
tree address of the object tree
obj number of the object to be changed
res reserved (always 0)
cx,cy coordinates of top left corner of clipping
rectangle
cw,ch width & height of clipping rectangle
new_status new object status
re_draw 1 = redraw object
0 = don't redraw
OBJC_DELETE
Syntax: a%=OBJC-DELETE(tree,del_obj)
Action: An object is deleted from an object tree by removing
the pointers. The object is still there and can be
restored by repairing the pointers.
Rteurns 0 on error.
tree address of the object tree
del_obj Object number of the object to delete.
OBJC_DRAW
Syntax: a%=OBJC_DRAW(tree,start_obj,depth,cx,cy,cw,ch)
Action: Draws whole objects or part of objects on screen. A
clipping rectangle is specified, to which the drawing
is limited.
Returns 0 on error.
tree address of the object tree
start_obj number of the first object to be drawn
depth Number of object levels to be drawn
cx,cy coordinates of top left corner of clipping
rectangle
cw,ch width & height of clipping rectangle
OBJC_EDIT
Syntax: a%=OBJC_EDIT(tree,obj,char,old_pos,flag,new_pos)
Action: Allows input and editing in G_TEXT and G_BOXTEXT
object types.
Returns 0 on error.
tree address of the object tree
obj number of the object to be changed
char input character (incl. scan code)
old_pos current cursor position in input string
flag funtion:
0 ED_START -reserved-
1 ED_INIT string is formatted & cursor on
2 ED_CHAR Character processed & string
redisplayed
3 ED_END Text cursor switched off
new_pos returns new pos of text cursor to this
variable.
OBJC_FIND
Syntax: a%=OBJC_FIND(tree,start_obj,depth,fx,fy)
Action: Determines the object, if any, which is at the
coordinates specified in fx,fy.
Returns the object number, or -1 if no object found.
tree address of the object tree
start_obj number of the object from where to search
depth Number of object levels to be searched
fx x coordinate (usually MOUSEX)
fy y coordinate (usually MOUSEY)
OBJC_OFFSET
Syntax: a%=OBJC_OFFSET(tree,obj,x_abs,y_abs)
Action: Calculates the absolute screen coordinates of the
specified object.
Returns 0 on error.
tree address of the object tree
obj object number
x_abs,y_abs returns the x,y coordinates to these
variables.
OBJC_ORDER
Syntax: a%=OBJC_ORDER(tree,obj,new_pos)
Action: re-positions an object within a tree.
Returns 0 on error.
tree address of the object tree
obj object number
new_pos new level number
OB_ADR
Syntax: adr%=OB_ADR(tree,obj)
Action: Gets the address of an individual object.
Returns 0 on error.
tree address of the object tree
obj object number
OB_FLAGS
Syntax: a%=OB_FLAGS(tree,obj)
Action: Gets the status of the flags for an object.
Returns 0 on error.
tree address of the object tree
obj object number
OB_FLAGS Bit No.
Normal -
Selectable 0
Default 1
Exit 2
Editable 3
Rbutton 4
Lastob 5
Touchexit 6
Hidetree 7
Indirect 8
OB_H
Syntax: h%=OB_H(tree,obj)
Action: Returns the height of an object
Returns 0 on error.
tree address of the object tree
obj object number
OB_HEAD
Syntax: h%=OB_HEAD(tree,obj)
Action: Points to the object's first child, or -1 if none.
OB_NEXT
Syntax: n%=OB_NEXT(tree,obj)
Action: Points to the following object on the same level, or,
if it is the last object on that level, to the parent
object, or -1 if none.
OB_SPEC
Syntax: a%=OB_SPEC(tree,obj)
Action: Returns the address of the the data structure for the
object.
OB_STATE
Syntax: s%=OB_STATE(tree,obj)
Action: returns the status of an object:
OB_STATE Bit No.
Normal -
Selected 0
Crossed 1
Checked 2
Disabled 3
Outlined 4
Shadowed 5
OB_TAIL
Syntax: t%=OB_TAIL(tree,obj)
Action: Points to the objects last child, or -1 if none.
OB_TYPE
Syntax: t&=OB_TYPE(tree,obj)
Action: Returns the type of object specified.
OB_W
Syntax: w%=OB_W(tree,obj)
Action: Returns the width of an object
OB_X
OB_Y
Syntax: x (or y) =OB_X or OB_Y(tree,obj)
Action: Rteurns the relative coordinates of the object
relative to its parent (or the screen if it is the
parent)
OCT$
Syntax: OCT$(x[,n])
Action: Changes the value 'x' into a string containing the
value of 'x' in octal form (prefix &O), the optional
parameter n, giving the number of characters to print.
ODD
Syntax: ODD(n)
Action: Determines whether a number is odd. (see also even)
ON BREAK Syntax: ON BREAK
ON BREAK CONT
ON BREAK GOSUB name
Action: 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
Syntax: ON ERROR
ON ERROR GOSUB name
Action: Performs the procedure 'name' when an error occurs.
The program is not interrupted and no error message
is given.
See also RESUME
ON...GOSUB
Syntax: ON x GOSUB proc1,proc2......
Action: Depending on the result of 'x' one of several given
procedures is processed.
'proc1' .. is a list of procedure names separated by
commas. The result of 'x' 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 is not in the range then no procedure
will be executed.
ON MENU
Syntax: ON MENU[t]
Action: This command handles EVENTs. Prior to use, the
required action should be specified with an ON MENU
xxx GOSUB command. For constant supervision of events,
ON MENU is usually found in a loop.
The parameter t is the time in thousandths of a second
to elapse before the ON MENU command is terminated.
ON MENU xxx GOSUB
Syntax: ON MENU BUTTON clicks,but,state GOSUB proc
Action: Sets up the action to be taken when one or more mouse
clicks are received. With a subsequent ON MENU
command, the named procedure will be branched to if
the condition imposed by the parameters are met.
clicks - sets the maximum number of clicks that
will generate a response.
button - The expected button combination:
0 - any
1 - left
2 - right
3 - both
state - Specifies which button state (up or down)
will cause the event. 0 = up, 1 = down
proc - The procedure to branch to.
Syntax: ON MENU GOSUB proc
Action: The procedure to which control will be passed on
selection of a menu entry is determined. If an
accessory is currently open, the procedure will not be
called.
See also MENU(0)
Syntax: ON MENU IBOX n,x,y,b,h GOSUB proc
Action: Monitors the mouse coordinates, and branches to the
named procedure if the mouse enters Y
k=MOUSEK
Action: 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
Syntax: ON MENU KEY GOSUB proc
Action: Monitors the keyboard, and branches to proc if a key
was pressed during an ON MENU loop.
See MENU(13) & MENU(14) for the keys.
Syntax: ON MENU MESSAGE GOSUB proc
Action: Brances to proc if a message arrives in the message
buffer during an ON MENU loop.
See MENU(x) for the messages.
Syntax: ON MENU OBOX n,x,y,w,h GOSUB proc
Action: Monitors the mouse coordinates, and branches to the
named procedure if the mouse leaves a rectangular
screen area. It is possible to wait for two such boxes
to be left (n can be 1 or 2 ). x and y are the top
left coordinates of the rectangle, w & h being its
width and height. Continuous monitoring is done with
ON MENU.
OPEN
Syntax: OPEN mode$,#n,name$[,len]
Action: Opens a data channel to a file or a peripheral device.
'mode' must always be written in quotes and is one
of the following :-
'O' (output) opens a write file creating a new file if
needed.
'I' (input) opens a read file.
'A' (append) enables data to be annexed to an existing
file.
'U' (update) read/write, but file must be opened by 'o'
first.
'R' stands for random access file.
Instead of a filename, a periphral device can ne
specified. The expression 'len' is used only with
Random Access mode.
the following can be used instead of 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.
'STD:'. (This is the same as 'Stdin','Stdout' resp. in
C-programs.) So you can use a shell to redirect the
output of a GFA-BASIC program.
GFABASIC TEST >DUMMY
This line starts GFA BASIC and the program TEST.PRG
Any output via 'STD:' is redirected to the file DUMMY.
IMPORTANT: CONTROL-C will cause a hang- up when given
while reading/writing DUMMY. the default for input/output
is the keyboard/console.
The numerical expression 'n' contains the channel
number (0-99), and the variable name$, the access path
and filename.
OPENW
Syntax: OPENW nr[,x a rectangular
screen area. It is possible to wait for two such
boxes to be entered (n can be 1 or 2 ). x and y are
the top left coordinates of the rectangle, w & h being
its width and height. Continuous monitoring is done
with ON MENU.
OPTION BASE
Syntax: OPTION BASE 0 (default)
OPTION BASE 1
Action: This command can determine whether an array is to
contain a zero element or not. ie. with OPTION BASE 0,
doing a DIM a%(10) will allow a%(0) to exist.
OR
Syntax: x OR y
Action: The command OR (disjunction) checks whether at least
one of two logical expressions x and y is TRUE. Only
if x and y are both FALSE will the result FALSE be
produced.
OR()
Syntax: OR(x,y)
Action: The result of OR contains bits set in the places in
which bits are set in either x or y or both.
OTHERWISE See SELECT
OUT
Syntax: OUT [#]n,a[,b..]
Action: Transfers a byte[s] with the value 'a' to a peripheral
device or file 'n'.
See OPEN for valid peripherals.
See also INP
OUT# See INP#
OUT?
Syntax: OUT?(n)
Action: Determines the output status of a periphery.
This function returns 0 if a character can be output.
(see also INP?)
PADT(i)
Syntax: a=PADT(i)
Action: Reads the paddle buttons on the STE
PADX(i)
PADY(i)
Syntax: a=PADX(i) or PADY(i)
Action: Reads the x or y position of the paddles on the STE. i
can be 0 or 1.
PAUSE
Syntax: PAUSE x
Action: Interrupts a program for exactly x/50 seconds.
See also DELAY.
PBOX
Syntax: PBOX x,y,x1,y1
Action: Draws a filled rectangle with the coordinates of the
two opposite corners specified by x,y and x1,y1.
See also BOX,PRBOX, RBOX.
PCIRCLE
Syntax: PCIRCLE x,y,r[,w1,w2]
Action: Draws a filled circle with centre coordinates at x,y
and a radius r. Additional start and end angles w1 and
w2 can be specified to draw a circular arc.
PEEK DPEEK LPEEK
Syntax: PEEK(x)
DPEEK(x)
LPEEK(x)
Action: 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.
PELLIPSE
Syntax: PELLIPSE x,y,rx,ry [,phi0,phi1]
Action: Draws a filled 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, to create an elliptical arc.
PI
Syntax: PI
Action: Returns the value of PI. The value of PI is
3.141592653.....etc.
PLOT
Syntax: PLOT x,y
Action: Plots a point on the screen coordinates 'x,y'.
This command is the same as draw x,y.
POINT
Syntax: POINT x,y
Action: Checks if a graphic dot (at 'x,y') has been set and
returns its colour value.
POKE DPOKE LPOKE
Syntax: POKE x,n
DPOKE x,n
LPOKE x,n
Action: 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
Syntax: POLYLINE n,x(),y()[OFFSETx_off,y_off]
POLYFILL n,x(),y()[OFFSETx_off,y_off]
POLYMARK n,x(),y()[OFFSETx_off,y_off]
Action: POLYLINE draws a polygon with n corners. The x,y
coordinates for the corner pointa are given in arrays
x() and y(). The first and last points are
automatically connected. The optional parameter OFFSET
can be added to these coordinates.
POLYFILL fills the polygon with the pattern previously
defined by DEFFILL.
POLYMARK marks the corner points with the shape
defined by DEFMARK.
POS
Syntax: POS(n)
Action: Returns the column in which the cursor is positioned.
'n', a hypothetical argument, is optional.
See also CRSCOL, CRSLIN, TAB, HTAB, VTAB.
PRBOX
Syntax: PRBOX x,y,x1,y1
Action: Draws a filled rectangle with rounded corners.
See also BOX, PBOX, RBOX.
PRED
Syntax: a$=PRED(b$)
Action: Supplies the character with the ASCII code one less
than that of the first character of the specified
string.
See also SUCC.
PRED()
Syntax: i%=PRED(n%)
Action: Returns the next lower number of the integer argument.
See also SUCC().
PRINT
Syntax: PRINT
PRINT expression
Action: Displays information on the screen.
'expr' can be any number of expressions which must be
separated by commas, semicolons or apostrophes.
; -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 AT
Syntax: PRINT AT(column,row);expression
Action: Prints 'expression' at a specified row and column.
NB. These start at 1, not 0.
PRINT USING
Syntax: PRINT USING format$,expression[;]
PRINT AT(column,row);USING format$,expression[;]
Action: Prints formatted digits and character strings.
format$ is a string expression which sets the printing
format using a list of expressions separated by commas.
# reserves space for a digit.
. 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+
! 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.
PRINT TAB
Syntax: PRINT TAB(n)
Action: Prints spaces until POS(0) reaches n. If POS(0)
already exceeds n then a Line Feed/Carriage Return is
executed first.
PRINT#
Syntax: PRINT #n,expression
PRINT #n,USING format$,expression
Action: Outputs data to a specified channel n (0-99). PRINT#
USING allows formatted data to be output.
PROCEDURE
Syntax: PROCEDURE proc[(var1,var2,...)]
Action: Marks the beginning of a procedure.
Basic will only process a procedure when it is called
by the command GOSUB (or by simply naming the
procedure, or using @proc. If it comes across the command
procedure during 'normal' running of the program, it
considers it to be the end of the program.
Not only the values of variable, but also the
variable's address can be passed to procedures using
the VAR command in the Procedure's header.
PSAVE
Syntax: PSAVE f$
Action: Saves the current program to disk with the name f$, it
is saved with protection, and cannot be subsequently
listed on re-loading; PSAVEd programs RUN
automatically on loading.
See also SAVE
PTSIN Address of the VDI point input table
PTSOUT Address of the VDI point output table
These two commands can be used with index, to address
the array directly. eg. PTSIN(0).
PTST()
Syntax: a=PTST(x,y)
Action: Corresponds to the POINT command. Returns the colour
of the pixel at x,y.
PUT
Syntax: PUT x,y,section$[,mode]
Action: Places a graphics block on the screen at x,y which
has been previously grabbed by GET, and stored in
section$.
'mode' (optional) sets the way the image is placed.
0 - All points are cleared
1 - s AND d Only points set in both remain set.
2 - s AND (NOT d) Sets only points which are set in
the source and clear in the
destination.
3 - s Overwrite (default GRAPHMODE 1)
4 - (NOT s)AND d
5 - d
6 - s XOR d
7 - s OR d
8 - NOT(s OR d)
9 - NOT(s XOR d)
10 NOT d
11 s OR(NOT d)
12 NOT s
13 (NOT s)OR d
14 NOT(s AND d)
15 1 All points set.
The important ones are:
3 Repalce
4 XOR
7 Transparent
13 Inverse Transparent.
PUT #
Syntax: PUT #n[,r]
Action: Writes a record to a random access file.
'n' data channel number (0 to 99).
'r' 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.
See also GET #, RECORD #
QSORT
Syntax: QSORT a(s) [OFFSET o] [WITH i()] [,n[,j%()]]
QSORT x$(s) WITH i() [,n[,j%()]]
Action: Sorts the elements of an array. 's' can be a minus
sign or a plus sign, indicating an ascending sort(+)
or a descending sort(-), the default being ascending.
The parameter 'n' specifies that only the first 'n'
elements are to be sorted. (Depends on OPTION BASE)
whether 0 or 1. If n=-1, then all elements are sorted.
When a further array is specified, then that array
will be sorted along with the first array.
OFFSET determines how many characters off the
beginning shall not be considered.
During sorting of string arrays a sorting criteria can
be specified in an array of at least 256 elements by
using WITH. Without using this option, a normal ASCII
sort is used.
eg:
DIM a$(256)
FILES "*.*" TO "liste"
OPEN "i",#1,"liste"
RECALL #1,a$(),-1,x%
CLOSE #1
QSORT a$() OFFSET 13,x%
OPEN "o",#1,"con:"
STORE #1,a$(),x%
CLOSE
Saves the directory as 'LISTE', then reloads the file,
sorts the array, not on name but on file length.
DIM x%(20)
PRINT "Unsorted: ";
FOR i%=0 TO 10
x%(i%)=RAND(9)+1
PRINT x%(i%);" ";
NEXT i%
PRINT
'
QSORT x%(),11
PRINT "Ascending sort: ";
FOR i%=0 TO 10
PRINT x%(i%);" ";
NEXT i%
PRINT
'
QSORT x%(-),11
PRINT "Descending sort: ";
FOR i%=0 TO 10
PRINT x%(i%);" ";
NEXT i%
PRINT
QUIT
Syntax: QUIT[n]
Action: Terminate the program and leave GFA Basic.
Returns a two byte integer to the calling routine
(normally the desktop).
RAD
Syntax: RAD(degrees)
Action: Converts from degrees to radians. (equivalent to
x*PI/180).
See also DEG
RAND
Syntax: RAND(y)
Action: Produces a 16 bit random integer in the range 0 to y-
1. Where y is an integer max value &HFFFF.
RANDOM
Syntax: RANDOM(x)
Action: Returns a random integer between 0 (inclusive) and
'x' (exclusive).
RANDOMIZE
Syntax: RANDOMIZE [y]
Action: Initialises the random number generator [with the
value y].
RBOX
Syntax: RBOX x,y,x1,y1
Action: Draws a rectangle with rounded corners from the two
diagonally opposite corner points 'x,y' and 'x1,y1'
See also BOX, PBOX, PRBOX.
RCALL
Syntax: RCALL addr,reg%()
Action: Calls an assembler routine (similar to C: or CALL)
with pre-allocated values in the registers.
The integer array reg% must have 16 elements and holds
the values. At the end of the routine, the values are
also returned in the array.
Data registers d0 to d7 --->reg%(0) to reg%(7)
Address registers a0 to a6 --->reg%(8) to reg%(14)
User Stack Pointer (a7) --->reg%(15)
RC_COPY
Syntax: RC_COPY s_adr,sx,sy,sw,sh TO d_adr,dx,dy[,m]
Action: Copies rectangular screen sections between areas of
memory.
s_adr source address
sx,sy top left corner of source rectangle
sw,sh width & height " " "
d_adr destination address
dx,dy destination x and y coordinates
m optional mode (see PUT for modes).
RC_INTERSECT
Syntax: y%=RC_INTERSECT(x1,y1,w1,h1,x2,y2,w2,h2)
Action: Detects whether two rectangles overlap. The rectangles
being specified by the coordinates of the top left
corner(x,y) and their width & height (w,h).
Returns TRUE (-1) if they do overlap and the variables
x2,y2,w2,h2 contain the size of the common rectangle.
READ
Syntax: READ var[,var1, ...]
Action: Reads values from a DATA command and assigns them to a
variable 'var'. Reading is taken from the last point a
RESTORE was done (if any).
RECALL
Syntax: RECALL #i,x$(),n[TO m],x
Action: Inputs n lines from a text file to the array x$(). If
n=-1 all available lines are read. x contains the
number of lines read.
RECORD
RELSEEK
Syntax: RELSEEK [#]N,X
Action: Moves tINT
'
QSORT x%(-),11
PRINT "Descending sort: ";
FOR i%=0 TO 10
PRINT x%(i%);" ";
NEXT i%
PRINT
QUIT
Syntax: QUIT[n]
Action: Terminate the program and leave GFA Basic.
Returns a two byte integer to the calling routine
(normally the desktop).
RAD
Syntax: RAD(degrees)
Action: Converts from degrees to radians. (equivalent to
x*PI/180).
See also DEG
RAND
Syntax: RAND(y)
Action: Produces a 16 bit random integer in the range 0 to y-
1. Where y is an integer max value &HFFFF.
RANDOM
Syntax: RANDOM(x)
Action: Returns a random integer between 0 (inclusive) and
'x' (exclusive).
RANDOMIZE
Syntax: RANDOMIZE [y]
Action: Initialises the random number generator [with the
value y].
RBOX
Syntax: RBOX x,y,x1,y1
Action: Draws a rectangle with rounded corners from the two
diagonally opposite corner points 'x,y' and 'x1,y1'
See also BOX, PBOX, PRBOX.
RCALL
Syntax: RCALL addr,reg%()
Action: Calls an assembler routine (similar to C: or CALL)
with pre-allocated values in the registers.
The integer array reg% must have 16 elements and holds
the values. At the end of the routine, the values are
also returned in the array.
Data registers d0 to d7 --->reg%(0) to reg%(7)
Address registers a0 to a6 --->reg%(8) to reg%(14)
User Stack Pointer (a7) --->reg%(15)
RC_COPY
Syntax: RC_COPY s_adr,sx,sy,sw,sh TO d_adr,dx,dy[,m]
Action: Copies rectangular screen sections between areas of
memory.
s_adr source address
sx,sy top left corner of source rectangle
sw,sh width & height " " "
d_adr destination address
dx,dy destination x and y coordinates
m optional mode (see PUT for modes).
RC_INTERSECT
Syntax: y%=RC_INTERSECT(x1,y1,w1,h1,x2,y2,w2,h2)
Action: Detects whether two rectangles overlap. The rectangles
being specified by the coordinates of the top left
corner(x,y) and their width & height (w,h).
Returns TRUE (-1) if they do overlap and the variables
x2,y2,w2,h2 contain the size of the common rectangle.
READ
Syntax: READ var[,var1, ...]
Action: Reads values from a DATA command and assigns them to a
variable 'var'. Reading is taken from the last point a
RESTORE was done (if any).
RECALL
Syntax: RECALL #i,x$(),n[TO m],x
Action: Inputs n lines from a text file to the array x$(). If
n=-1 all available lines are read. x contains the
number of lines read.
The optional parameter TO will read in the start of
the file to the named elements of the array.
eg.
DIM a$(20)
FOR n=0 TO 19
a$(n)="Line # "+STR$(n)
NEXT n
OPEN "o",#1,"test"
STORE #1,a$()
CLOSE
DIM b$(20)
OPEN "i",#1,"test"
RECALL #1,b$(),12 TO 15,x
'or RECALL #1,b$(),-1,x
CLOSE
PRINT x
FOR n=0 TO 20
PRINT b$(n)
NEXT n
See Also: STORE
RECORD
Syntax: RECORD #n,r
Action: Sets the number of the next record to br read or stored
with GET or PUT.
Example: RECORD #1,15
See Also: FIELD,GET#, PUT#, SEEK
RELSEEK
Syntax: RELSEEK [#]n,x
Action: Moves the random access file pointer forward (+X) or
backwards (-X) 'X' number of bytes.
REM
Syntax: REM remark
Action: Whatever follows a REM coomand on a particular line
is ignored by Basic. ' is synonoymous with REM.
Example: REM This is a comment
RENAME
Syntax: RENAME old$ AS new$
Action: Renames a file.
REPEAT...UNTIL
Syntax: REPEAT
UNTIL end
Action: Creates a pre-defined loop. The section of the program
between repeat and until is repeated continuously until
the condition is fulfilled.
Example: REPEAT
UNTIL MOUSEK 'Waits for mouse key to be pressed.
RESERVE
Syntax: RESERVE n
Action: 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)
Example: RESERVE 2560
EXEC 0,"\PROGRAM.PRG","",""
RESERVE
2560 bytes are reserved and PROGRAM.PRG is loaded and
started. After running the reserved space is restored.
Memory can be reserved in blocks of 256 bytes.
If n is negative then the whole of the free memory is
reserved.
RESTORE
Syntax: RESTORE [label]
Action: Positions the data pointer for READ.
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
Syntax: RESUME RESUME NEXT RESUME label
Action: The RESUME command is only meaningful with error capture
(ON ERROR GOSUB) where it allows a reaction to an error.
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
Example: ON ERROR GOSUB error_trap
ERROR 5
PRINT "and again..."
ERROR 5
PRINT "is not reached."
'
PROCEDURE error_trap
PRINT "OK, error intercepted"
RESUME NEXT
RETURN
RETURN
Syntax: RETURN
Action: Terminates a sub-routine
Syntax: RETURN x
Action: If the command RETURN is reached during program ececution
and is within a FUNCTION...ENDFUNC execution, then the
value given after it is returned.
RIGHT$
Syntax: RIGHT$(string[,n])
Action: Returns the last characters or 'n' number of characters
(from the right) of a character string 'string'
Example: PRINT RIGHT$"Hello GFA",3) 'PRINTS GFA
RINSTR
Syntax: RINSTR(a$,b$)
RINSTR(a$,b$,[x])
RINSTR([x],a$,b$)
Action: Operates in same way as INSTR except that search begins at
the right end of a$.
RMDIR
Syntax: RMDIR "directory name"
Action: Deletes empty directories
RND
Syntax: RND [(x)]
Action: 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)
ROL
Syntax: ROL(x,y)
ROL&(x,y)
ROL|(x,y)
Action: Rotates a bit pattern left.
ROR
Syntax: ROR(x,y)
ROR&(x,y)
ROR|(x,y)
Action: Rotates a bit pattern right.
ROUND
Syntax: ROUND(x[,n])
Action: Rounds off the numeric expression x.
Example: y=ROUND(-1.2)
PRINT y,ROUND(1.7)
RSET
Syntax: RSET a$=b$
Action: Moves a string expression, right justified to a string.
See Also: LSET,MID$
The following commands are part of the Resource Library. These
routines provide the creation of a graphical user interface. The full
descriptions of these functions are beyond the scope of these
abreviated manual. A full description is contained within the full
GFA-BASIC Reference manual and also the GFA-BASIC Software Development
Book.
RSRC_FREE
Syntax: ~RSRC_FREE(0)
Action: This function releases the memory space reserved by
RSRC_LOAD.
Returns 0 if an error.
RSRC_GADDR
Syntax: ~RSRC_GADDR(type,index,addr)
Action: This function determines the address of a resource
structure after it has been loaded with RSRC_LOAD.
Depending on the version of GEM, this function may only
work for Object trees and Alert boxes.
Returns 0 if an error.
Type:0 OBJECT TREE
1 OBJECT
2 TEDINFO
3 ICONBLK
4 BITBLK
5 STRING
6 image data
7 obspec
8 te_ptext
9 te_ptmplt
10 te_pvalid
11 ib_pmask
12 ib_pdata
13 pb_ptext
14 bi_pdata
15 ad_frstr
16 ad_frimg
Index: The number of the object whose address is
required, counting objects of that type one by one
from the beginning of the resource file.
addr: The required address.
Example: ~RSRC_GADDR(0,0,TREE%)
RSRC_LOAD
Syntax: RSRC_LOAD(name$)
Action: This function reserves memory and loads a resource file.
Then internal pointers are set and the co-ordinates of
characters converted into pixel format.
Example: ~RSRC_LOAD("TEST.RSC")
RSRC_OBFIX
Syntax: RSRC_OBFIX(tree,obj)
Action: This function converts the coordinates of an object within
a tree, from character coordinates to pixel coordinates,
taking into account the current screen resolution. It is
automatically called by RSRC_LOAD, but must be used if the
object is created direct in memory by POKE.
tree: address of the object tree
obj: object number
RSRC_SADDR
Syntax: RSRC_SADDR(type,index,addr)
Action: This function sets the address of an object.
Returns 0 if an error.
type: type of structure
index: the number of the object
addr address
RUN
Syntax: RUN(a$)
Action: Runs the program in memory, or if a file name is supplied
will load and then run the appropriate program.
Example: RUN "A:\PROGRAM.GFA"
SAVE
PSAVE
Syntax: SAVE a$
PSAVE a$
Action: Saves a program file (psave is with list protection)
'file name' is the name of the program.
Programs which are saved with psave are not listed but
run straight after the command 'load' is given.
SEEK
Syntax: SEEK [#]n,x
Action: 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.
SCRP_READ
Syntax: SCRP_READ(path$)
Action: This function reads data, left there by another program,
from a small internal buffer, thus allowing communication
between GEM programs. Returns 0 if an error.
Example: SCRP_READ(a$)
See Also: SCRP_WRITE
SCRP_WRITE
Syntax: SCRP_WRITE(path$)
Action: This function writes data, into a small internal buffer,
thus allowing communication between GEM programs.
Example: SCRP_WRITE("A:\PROGRAM.TXT")
See Also: SCRP_READ
SDPOKE
Syntax: SDPOKE x,y
Action: Allows DPOKE to operate in supervisor mode, so that
protected address (0 to 2047) can be modified.
SEEK
Syntax: SEEK #n,pos
Action: Absolute positioning of data pointer within file. This
allows the realisation of indexed sequential file access.
The numerical expression n contains the channel number of
the file.
SELECT
Syntax: SELECT x
CASE y [TO z] or CASE y [,z,...]
CASE TO y
CASE y TO
DEFAULT
ENDSELECT
CONT
Action: A conditional command which enables execution of specified
program segments depending on an integer.
The maximum of a CASE is 4 characters (eg CASE "A,B,C,D"
The CONT command provides a method of jumping over a CASE
or DEFAULT command.
Example: REPEAT
a%=ASC(INKEY$)
SELECT a%
CASE 65 TO 90
PRINT "CAPITAL LETTER"
CASE 97 TO 122
PRINT "LOWER CASE LETTER"
DEFAULT
PRINT "NOT CAPITAL OR LOWER CASE"
ENDSELECT
UNTIL a%=27
SETCOLOR
Syntax: SETCOLOR i,r,g,b
SETCOLOR i,n
Action: 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
See Also: COLOR,VSETCOLOR
SETDRAW See DRAW command.
SETMOUSE
Syntax: SETMOUSE mx,my,[,mk]
Action: The SETMOUSE command permits the positioning of the mouse
cursor under program control. Tje optional parameter mk can
simulate the mouse button being pressed or released.
Example: FOR i%=0 TO 300
HIDEM
SETMOUSE i%,i%
PLOT MOUSEX,MOUSEY
SHOWM
PAUSE 2
NEXT i%
SETTIME
Syntax: SETTIME time$,date$
Action: Sets the time and the date.
time$ 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.
date$ is a character string expression for the
date. It must always contain: day, month and year,
each separated by a full stop.
Example: PRINT DATE$,TIME$
SETTIME "17:30:30","27.10.1952"
PRINT DATE$,TIME$
SGET
Syntax: SGET screen$
Action: Fast reading of the entire screen area into a string
variable.
Example: PCIRCLE 100,100,50
SGET b$
~INP(2)
CLS
~INP(2)
SPUT b$
See Also: SPUT, GET, PUT and BMOVE
SGN
Syntax: SGN(x)
Action: Ascertains whether 'x' is positive, negative or 0
'x' can be any numeric expression. SGN(x) is the
mathematic sign function.
The following commands are part of the Shell Library and enable
an application to call another, preserving both the original
application and its environment.
The full descriptions of these functions are beyond the scope of these
abreviated manual. A full description is contained within the full
GFA-BASIC Reference manual.
SHEL_ENVRN
Syntax: SHEL_ENVRN(addr,search$)
Action: This function determines the values of variables in the GEM
environment.
Returns 1.
search$: The string to be sought
addr: address of the byte following the string
Example: PRINT SHEL_ENVRN(a%,"PATH")
PRINT CHAR{a%-4}
' Displays: PATH=A:\
SHEL_FIND
Syntax: SHEL_FIND(paths$)
Action: This function searches for a file and supplies the full
file specification. First the path on the current drive is
searched, then the root directory of drive A:.
Returns 0 if file not found, or 1 if found.
On entry:
path$: String contains sought after filename.
On exit:
path$: Contains the full file specification if the file
was found, otherwise it is unchanged.
SHEL_GET
Syntax: SHEL_GET(num,x$)
Action: This function reads data from the GEMDOS environmental
string buffer (into which the file DESKTOP.INF is read on
start up).
Returns 0 if an error.
num: number of bytes to be read
x$: string to contain data
Example: SHEL_GET(500,x$)
PRINT x$
SHEL_PUT
Syntax: SHEL_PUT(len,x$)
Action: This function writes data into the GEMDOS environmental
string buffer.
Returns 0 if an error.
x$: String containing the data to be written
len: number of bytes to be written
Example: 'Register GFA-BASIC
~SHEL_GET(2000,a$)
q%=INSTR(a$,CHR$(26))
IF q%
a$=LEFT$(a$,q%-1)
IF INSTR(a$,"GFABASIC.PRG")=0
a$=s$+"#G 03 04 A:\GFABASIC.PRG@*.GFA
+MKI$(&HDOA)+CHR$(26)
~SHEL_PUT(LEN(a$),a$)
ENDIF
ENDIF
' Registers that all .GFA files cause GFABASIC.PRG to be
loaded when clicked on.
SHEL_READ
Syntax: SHEL_READ(cmd_string$,tail_string$)
Action: This function allows the program to identify the command by
which it was invoked and supplies the name, eg
GFABASIC.PRG, and the command line if any.
cmd_string$ string variable to contain the command
line.
tail_string$ string variable to contain name.
SHEL_WRITE
Syntax: SHEL_WRITE(prg,grf.gem.cmd$,nam$)
Action: This function informs the AES that another application is
to be started after the current one has terminated. In
contrast to p_exec (GEMDOS 75), however the current program
does not remain in memory.
prg: 0 Back to desktop
1 Load new program
grf: 0 TOS program
1 Graphic application
gem: 0 not a GEM application
1 GEM application
cmd$ command line string
nam$ name of next application
Example: ~SHEL_WRITE(1,1,1,"","GFABASIC.PRG")
SHL
Syntax: SHL(x,y)
SHL&(x,y)
SHL|(x,y)
Action: Shifts a bit pattern left
SHOWM
Syntax: SHOWM
Action: Makes the mouse pointer appear.
See Also: HIDEM
SHR
Syntax: SHR(x,y)
SHR&(x,y)
SHR|(x,y)
Action: Shifts a bit pattern right
SIN
Syntax: SIN(x)
Action: Returns the sine value of 'x'
SINGLE{}
Syntax: SINGLE{x}
Action: Reads/writes a 4 byte floating point variable in IEEE
single precision format.
SINQ
Syntax: SINQ(degrees)
Action: Returns the extrapolated sine of a numeric expression.
SLPOKE
Syntax: SLPOKE x,y
Action: Allows LPOKE to operate in supervisor mode, so that
protected address (0 to 2047) can be modified.
SOUND
Syntax: SOUND chn,vol,note,octave[,dur]
SOUND chn,vol,note,#period[,dur]
Action: 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 that 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$
Syntax: SPACE$(x)
Action: Creates a character string containing 'x' spaces.
SPC
Syntax: SPC(n)
Action: Produces 'n' spaces in a print command
SPOKE SDPOKE SLPOKE
Syntax: SPOKE x,n SDPOKE x, SLPOKE x,n
Action: Writes 1, 2 or 4 bytes into an area of memory which
begins with the address 'x'
SPRITE
Syntax: SPRITE A$[,x,y]
Action: 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
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.
SPUT
Syntax: SPUT var
Action: Fast copying of a 32000 byte string into the screen
area.
See Also: SGET, PUT, GET and BMOVE
SQR
Syntax: SQR(X)
Action: Calculates the square root of 'X'.
SSORT
Syntax: SSORT a(s) {OFFSET o][WITH i()][,n[,j%()]]
SSORT x$(s) WITH i() [,n[,j%{}]]
Action: Sorts the elements in an array by its size using the Shell-
Metzner method.
a() array or string array
i() integer array
j% 4byte integer array
x$() string array
s + or - or no sign
STE?
Syntax: STE?
Action: Returns -1 for STE otherwise 0
STICK
Syntax: STICK m
STICK(p)
Action: The function STICK(p) returns the position of a joystick.
STICK 0 causes port 0 to supply mouse information.
STICK 1 causes port 1 to read the joystick.
Example: STICK 1
REPEAT
direction%=STICK(0)
fire%=STRIG(0)
SELECT direction%
CASE 4
PRINT "LEFT"
CASE 8
PRINT "RIGHT"
CASE 2
PRINT "DOWN"
CASE 1
PRINT "UP"
ENDSELECT
UNTIL fire!
WHILE STRIG(0)
WEND
STOP
Syntax: STOP
Action: 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.
STORE
Syntax: STORE #i,x$()[,n[TO m]]
Action: Fast save of a string array as a text file. The instruction
STORE is used for sending the contents of an array to a
file or data channel (elements seperated by CR/LF).
See Also: RECALL
STR $
Syntax: STR$(X)
Action: Transforms the value 'X' into a character string.
STRING$
Syntax: STRING$(N,string) OR STRING$(N,C)
Action: Produces a string formed by repeating 'string' or
CHR$(C) 'N' times. 'N' is a number from 0 to 32767.
SUB
Syntax: SUB VAR,N
Action: Deducts 'N' from 'VAR'. Same as VAR=VAR-N but executes
almost twice as fast.
Example: x=57
SUB x,3*5
PRINT x 'PRINTS 42
SUB()
Syntax: SUB(x,y)
Action: Corresponds to x-y
Example: PRINT SUB(5^3,4*20+3) 'PRINTS 42
SUCC()
Syntax: SUCC(n)
Action: Determines the next higher number.
See Also: PRED()
SWAP
Syntax: SWAP var1,var2
Action: Exchanges the values of 'var1' and 'var2'.
The variables must be of the same type.
When swapping array fields the dimensions are also swap
ped.
SWAP()
Syntax: SWAP(n)
Action: Swaps the high and low words of a varaible.
SYSTEM
Syntax: SYSTEM
Action: Causes a return to the desktop, same as quit.
TAB
Syntax: TAB(n)
Action: 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
Syntax: TAN(X)
Action: Returns the tangent of 'X' (X is the angle in radians).
TEXT
Syntax: TEXT X,Y, [ L, ]string
Action: Puts a text onto the screen at graphics coordinates
'X,Y'. The graphics can first be defined by using
the command DEFTEXT.
TIME$
Syntax: TIME$
Action: Returns the system time as a string.
Format: hh:mm:ss and is updated every two seconds.
Example: PRINT TIME$
TIME$=
Syntax: TIME$=a$
Action: The time can be set.
Example: TIME$="20:15:30"
TIMER
Syntax: t%=TIMER
Action: TIMER suuplies the elapsed time in 1/200 seconds since the
system was started.
Example: t%=TIMER
FOR i%=1 TO 2500
NEXT i%
PRINT (TIMER-t%)/200;" Seconds"
TITLEW
Syntax: TITLEW n,"title"
Action: Gives the window number 'n', the new title 'title'.
TOPW
Syntax: TOPW #1
Action: Activates the windows number n.
TOUCH
Syntax: TOUCH[#]n
Action: Updates the date and time stamps od a file, giving it the
current system time and date.
Example OPEN "u",#1,"TEST.TXT"
TOUCH #1
CLOSE #1
TRACE$
Syntax: TRACE$
Action: The variable TRACE$ contains the command which is next to
be processed.
See Also: TRON,TROFF
TRIM$
Syntax: TRIM$(a$)
Action: Removes spaces at the beginning of a string expression.
TROFF
Syntax: TROFF
Action: Switches the trace function off.
TRON
Syntax: TRON
Action: Switches the trace function on. This causes each command to
be listed on the screen.
TRON#
Syntax: TRON #1
Action: Switches the trace function on. This causes each command to
be listed to the relevant channel number.
TRONproc
Syntax: TRON tr_proc
Action: A procedure can be specified which is called before the
execution of each command.
TRUE
Syntax: TRUE
Action: 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).
TRUNC
Syntax: TRUNC(X)
Action: Returns the integer portion of 'X'.
TT?
Syntax: TT?
Action: Returns -1 for 68020 or 68030 processeor, otherwise 0.
TYPE
Syntax: TYPE(ptr)
Action: 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.
UPPER$
Syntax: A$="basic"
PRINT UPPER$(A$)
PRINT UPPER$("1a")
Action: Transforms all lower case letters of a string to upper
case. Any non letter characters are left unchanged.
V:
Syntax: V:x
Action: Returns the address of a variable or strings or elements of
an array.
VAL
Syntax: VAL(X$)
Action: Transforms 'X$' into a number, as far as possible.
In the case of a purely alphabetical string the value
0 is returned.
VAL?
Syntax: VAL?(X$)
Action: Determines the number of characters starting at the
beginning of a string that can be converted into a
numerical value with VAL.
VAR
Syntax: name([a,b,...] VAR x,y..a(),b(),...)
Action: Declaration part of the parameter list for a PROCEDURE or
FUNCTION.
Example: sum(13,12,a)
sum(7,9,b)
PRINT a,b
'
PROCEDURE sum(x,y,VAR z)
z=x+y
RETURN
VARIAT()
Syntax: VARIAT(n,k)
Action: Returns the number of permutations of n elements to the kth
order without repitition.
Example: PRINT VARIAT(6,2) 'prints 30
See Also: FACT(), COMBIN()
VARPTR
Syntax: VAPTR(var)
Action: Determines the address or starting address of a
variable 'var'.
VDIBASE
Syntax: VDIBASE
Action: 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.
VDISYS
Syntax: VDISYS[opcode [,c_int,c_pts[,subopc]]]
Action: The VDI function with function code opcode is called. If
opcode is not specified, then the function code must, like
other parameters, be placed in the control block with
DPOKE.
The depth of this command is betond the scope of this
abbreviated manual.
VOID
Syntax: VOID exp
Action: 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.
VQT_EXTENT
Syntax: VQT_EXTENT(text$[,x1,y1,x2,y2,x3,y3,x4,y4])
Action: Returns the corner coordinates of a rectangle which will
surround the text in text$. The coordinates can either be
found in the variables x1,y1 to x4,y4, or in PTSOUT(7). The
corner pointers are numbered in a clockwise direction.
Example: INPUT text$
CLS
ATEXT 100,25,2,text$
~VQT_EXTENT(text$,x1,y1,x2,y2,x3,y3,x4,y4)
BOX x4+100,y4+25,x2+00,y2+25
VQT_NAME
Syntax: VQT_NAME(i,font_name$)
Action: Supplies the handle of the font with the indentification
number i and places the name of the loaded character set
into the string variable font_name$.
VSETCOLOR
Syntax: VSETCOLOR colour,red,green,blue
VSETCOLOR colour,composite
Action: Due to an error in TOS, SETCOLOR does not correspond to the
registers used by COLOR. VSETCOLOR is used to overcome this
problem.
Low Resolution
SETCOLOR 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
VSETCOLOR 0 2 3 6 4 7 5 8 9 10 11 14 12 15 13 1
Medium Resolution
SETCOLOR 0 1 2 3
VSETCOLOR 0 2 3 1
High Resolution
SETCOLOR 0,even = VSETCOLOR 0,0
SETCOLOR 0,odd = VSETCOLOR 0.&H777
The term composite is calculated the same way as with
SETCOLOR: ie rgb=(r*256)+(g*16)+b
VST_LOAD_FONTS
Syntax: VST_LOAD_FONTS(x)
Action: Loads the additional character sets specified in
ASSIGN.SYS, and the number of loaded fonts is returned.
Example: RESERVE 25600
num_fonts%=VST_LOAD_FONTS(0)
face%=VQT_NAME(num_fonts%,fonts$)
FOR i%=1 to num_fonts%
DEFTEXT,,,,face%
TEXT 80,80,"This is the "+font$+" font."
~INP(2)
NEXT i%
~VST_UNLOAD_FONTS(0)
RESERVE
VST_UNLOAD_FONTS
Syntax: VST_UNLOAD_FONTS(x)
Action: Removes the character set previously loaded with
VST_LOAD_FONTS from memory.
VSYNC
Syntax: VSYNC
Action: Enables synchronization with the screen by waiting
until the next vertical sync pulse is received - helps
avoid flickering of the screen during animation when using
GET and PUT.
Example: t%=TIMER
FOR i%=1 TO 100
VSYNC
NEXT i%
PRINT SUB(TIMER,t%)/200
' PRINTS the time for 100 scans of screen.
VTAB
Syntax: VTAB line
Action: VTAB positions the cursor to the specified column or line
number . Note that the cursor columns and lines are counted
from 1, not 0.
See Also: HTAB, PRINT AT, TAB
The following VDI Workstation routines and functions are only
available if GDOS has been booted and a valid ASSIGN.SYS file is
available. In depth documentation on the VDI routines are beyond the
scope of this abbreviated manual. Further information can be found in
the full GFA-BASIC Interpreter Manual or Software Development Book.
V_CLRWK
Syntax: V_CLRWRK()
Action: This function clears the output buffer. For example the
screen or the printer buffer is cleared.
V_CLSVWK
Syntax: V_CLSVWK(id)
Action: Closes a virtual workstation opened with V_OPNVWK.
V_CLSWK
Syntax: V_CLSWK()
Action: Closes the current workstation opened with V_OPNWK().
V_OPNVWK
Syntax: V_OPNVWK(id,1,1,1,1,1,1,1,1,1,2)
Action: Opens a virtual screen driver and supplies the handle for
the specified device id.
V_OPNWK
Syntax: V_OPNWK(id)
Action: Supplies the handle for the specified device id.
V_UPDWK
Syntax: V_UPDWK()
Action: Sends buffered graphic instructions to the attached device.
V~H
Syntax: V~H
Action: Returns the internal VDI handle of GFA-BASIC.
V~H=x 'Sets internal VDI handle
V~H=-1 'Sets VDI handle to value from V_OPNVWK()
W:
Syntax: W:x
Action: Allows passing of numerical expressions to the operating
system and C routines as a word (2-byte).
See Also: L:
WAVE
Syntax: WAVE voice,env,form,per,del
Action: Produces noises from the three sound channels.
WAVE 0,0 switches off all sound channels.
voice: Any channel or combination of channels may be
activated simultaneously. The value of voice is
256 * by the period.
1 Channel 1
2 Channel 2
4 Channel 3
8 Noise (Channel 1)
16 Noise (Channel 2)
32 Noise (Channel 3)
env: Specifies the channels for which the wnvelope is
to be active.
1 Channel 1
2 Channel 2
3 Channel 3
form: Envelope shape
0 - 3 As 9
4 - 7 As 15
8 Falling sawtooth
9 Falling linear
10 Triangle falling
11 Falling linear, then to max
12 Rising sawtooth
13 Rising linear and holding
14 Triangle, then rising
15 Linear rising, then to zero
per: Period of the waveform multiplied by 125000.
del: Delay in 1/59ths second before the next GFA-BASIC
command is executed.
Example: SOUND 1,15,1,4,20
SOUND 2,15,4,4,20
SOUND 3,15,8,4,20
WAVE 7,7,0,65535,300
' A tone is generated from each channel then modulated by
' WAVE.
See Also: SOUND
WHILE....WEND
Syntax: WHILE condition
WEND
Action: 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.
The following functions are all functions of the Window Library
WINDTAB
Syntax: WINTAB
WINTAB(i,j)
Action: Gives the address of the Window Parameter Table. This table
contains the data that determines the appearance of a
window.
Window Parameter Table:
Offset
0 Handle of Window 1
2 Attributes for Window 1
4 x coordinates of Window 1
6 y coordinates of Window 1
8 Width of Window 1
10 Height of Window 1
12-22 Parameters for Window 2
24-34 Parameters for Window 3
36-46 Parameters for Window 4
48 -1
50 0
52-58 Coordinates and size of Desktop
60-63 Coordinates of the joint of the four windows
64-65 Origin for graphic instructions (CLIP OFFSET)
Window Attibute element:
Bit
0 Window Title
1 Close box
2 Full box
3 Move box
4 Information line
5 Sizing box
6 Up arrow
7 Down arrow
8 Vertical slider
9 Left arrow
10 Right arrow
11 Horizontal slider
Example: OPEN #1,100,120,200,70,&HFFF
' corresponds to:
DPOKE WINTAB+2,&HFFF
DPOKE WINTAB+4,100
DPOKE WINTAB+6,120
DPOKE WINTAB+8,200
DPOKE WINTAB+10,70
OPENW 1
' or
WINTAB(1,1)=&HFFF
WINTAB(1,2)=100
WINTAB(1,3)=120
WINTAB(1,4)=200
WINTAB(1,5)=70
OPENw 1
WIND_CALC
Syntax: WIND_CALC(w_type,attr,ix,iy,iw,ih,ox,oy,ow,oh)
Action: This function computes the total size of the work area from
the size of the window.
Returns 0 if an error.
w_type: 0 Compute total size
1 Compute work area size
attr: Bit
0 Title bar with name
1 Close box
2 Full size box
3 Move bar
4 Info line
5 Size box
6 Up arrow
7 Down arrow
8 Vertical slider
9 Left arrow
10 Right arrow
11 Horizontal slider
ix,iy top left coorinates
iw,ih width and height
ox,oy Calculated top left coordinates
ow,oh Calculated width and height
WIND_CLOSE
Syntax: WIND_CLOSE(handle)
Action: Closes the specified window.
WIND_CREATE
Syntax: WIND_CREATE(attr,wx,wy.ww.wh)
Action: Allocates a new window, specifying the attributes and
maximum size. The handle of the window is returned.
attr: Bit
0 Title bar with name
1 Close box
2 Full size box
3 Move bar
4 Info line
5 Size box
6 Up arrow
7 Down arrow
8 Vertical slider
9 Left arrow
10 Right arrow
11 Horizontal slider
wx Max x position of left edge
wy Max y position of top edge
ww Max width of window
wh Max height of window
WIND_DELETE
Syntax: WIND_DELETE(handle)
Action: Deletes a window allocation and frees reserved memory.
WIND_FIND
Syntax: WIND_FIND(fx,fy)
Action: Determines the id number of a window within which the
specified coordinates lie.
fx: x coordinates
fy: y coordinates
WIND_GET
Syntax: WIND_GET(handle,code,w1,w2,w3,w4)
Action: Supplies information about a window determined by the code.
handle: Id number of the window
code: depending upon the code, information is
supplied in w1,w2,w3,w4.
code: 4 supplies size of window work area
w1: x coordinates
w2: y coordinates
w3: width
w4: height
code: 5 supplies total size of entire window
including borders
w1: x coordinates
w2: y coordinates
w3: width
w4: height
code: 6 supplies total size of previous window
w1: x coordinates
w2: y coordinates
w3: width
w4: height
code: 7 supplies the total max size of the
window.
w1: x coordinates
w2: y coordinates
w3: width
w4: height
code: 8 supplies the position of the horizontal
slider
w1: 1=far left 1000=far right
code: 9 supplies the position of the vertical
slider
w1: 1=top 1000=bottom
code: 10 supplies the id number of the top
(active) window
w1: id number of active window
code: 11 supplies the coordinates of the first
rectangle in the specified rectangle
list.
w1: x coordinates
w2: y coordinates
w3: width
w4: height
code: 12 supplies the coordinates of the next
rectangle in the specified windows
rectangles list
w1: x coordinates
w2: y coordinates
w3: width
w4: height
code: 13 reserved
code: 15 supplies the size of the horizontal
slide bar compared to its max possible
w1: -1 = minimum size
1 = small
1000 = full width
code: 16 supplies the size of the vertical slide
bar compared to its max possible
w1: -1 = minimum size
1 = small
1000 = full height
WIND_OPEN
Syntax: WIND_OPEN(handle,wx,wy,ww,wh)
Action: Draws on the screen a window previously created with
WIND_CREATE.
WIND_SET
Syntax: WIND_SET(handle,code,w1,w2,w3,w4)
Action: Changes the parts of a window according to the specified
function code.
code: 1 Sets new windows components as with
WIND_CREATE.
w1: new window element
code: 2 Gives a window a new title
w1: Hi word
w2: Low word of address of title string
code: 3 Specifies a new information line
w1: Hi word
w2: Low word of address of information
string
code: 5 Sets the window size
w1: x coordinates
w2: y coordinates
w3: width
w4: height
code: 8 Positions the horizontal slider
w1: 1=far left 1000=far right
code: 9 Positions the vertical slider
w1: 1=top 1000=bottom
code: 10 Sets top (active) window
w1: id number
code: 14 Sets a new desk top Menu tree
w1: Low word
w2: High word of address of new tree
w3: id number of the first object to be
drawn
code: 15 Sets the size of the vertical slide bar
w1 -1=minimum size
1= small
1000 max size
code: 16 Sets the size of the horizontal slider
bar
w1 -1=minimum size
1= small
1000 max size
WIND_UPDATE
Syntax: WIND_UPDATE(flag)
Action: Coordinates all functions concerned with screen redraws,
in particular with drop down menus.
flag: 0 screen redraw completed
1 screen redraw starting
2 application loses mouse control
3 application takes on mouse control
WORD()
Syntax: WORD(x)
Action: Extends a word to long word length (32 bits) by copying
bits 15 to bit positions 16 to 31, thus preserving the
sign.
WORK_OUT()
Syntax: WORK_OUT(x)
Action: Determines the values found in INTOUT(0) to INTOUT(44),
PTSOUT(0) and PTSOUT(1) after returning from the function
OPEN_WORKSTATION.
WRITE
Syntax: WRITE [ expressions ][ ; ]
WRITE #n [ expressions ][ ; ]
Action: 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.
WRITE#
Syntax: WRITE#n,expression
Action: Saves data to sequential file, for later reading with
INPUT#.
Example: OPEN "o",#1,"TEST.DAT"
WRITE #1,"Version ",3,".6"
CLOSE #1
OPEN "i",#1,"TEST.DAT"
INPUT #1,v1$,v2$,v3$
CLOSE #1
PRINT v1$+V2$+v3$
W_HAND
Syntax: W_HAND(#n)
Action: Returns the GEM handle of the window whose channel number
is n.
Example: OPENW 2
PRINT W_HAND(#2)
~INP(2)
CLOSE #2
W_INDEX
Syntax: W_INDEX(#hd)
Action: Returns the window number of the specified GEM handle.
Reverse of W_HAND().
XBIOS
The XBIOS function is used to call XBIOS system routines.
~XBIOS(0,t%,l:p%.l:v%)
Initialises the mouse handling routine but not compatible
with GEM.
t% 0 Switches mouse off
1 Switches mouse into relative mode
2 Switches mouse into absolute mode
4 Mouse in keyboard mode
p% Address of information structure
v% Address of the mouse handling routine
r%=XBIOS(2)
Returns the base address of the physical screen memory.
r% Address of the physical screen memory
r%=XBIOS(3)
Returns the address of the logical screen memory when
writing to the screen.
r% Address of the logical screen memory
r%=XBIOS(4)
Returns the current screen resolution
r% 0 320 x 200
1 640 x 200
2 640 x 400
~XBIOS(5,l:l%,l:p%,r%)
Enables the resolution to be changed from low res and high
res when using a colour monitor. Can not be used with GEM.
l% New address of logical screen memory
p% New address of the physical screen memory
r% New screen resolution (see XBIOS(4))
~XBIOS( 6,L:adr%)
Allows all colour registers to be reset at one time.
adr% Address of a table of 16 words, which contains new
pallete data.
r%=XBIOS(7,n%,c%)
Sets or gets a colour register.
r% For c%=-1 the previous specified colour register
is returned.
n% Colour register
c% New colour, at c%=-1 see r%
r%=XBIOS(8,L:b%,L:f%,d%,sec%,t%,side%,n%)
Reads sectors of a disk
r% 0 if no error
b% address of the area from which sectors are read
f% unused
d% drive number (0=A, 1=B etc)
sec% sector number
t% track number
side% disk side (0 or 1)
n% number of sectors to be read
r%=XBIOS(9,L:b%,L:f%,d%,sec%,t%,side%,n%)
Writes sectors to a disk
r% 0 if no error
b% address of the area to which sectors are written
f% unused
d% drive number (0=A, 1=B etc)
sec% sector number
t% track number
side% disk side (0 or 1)
n% number of sectors to be written
r%=XBIOS(10,L:b%,L:f%,d%,sec%,t%,side%,i%,L:m%,v%)
A trace of the disk formats
r% 0 if no error
b% address of an area for intermediate memory
f% unused
d% drive number (0=A, 1=B etc)
sec% sectors per track
t% track number to be formatted
side% disk side (0 or 1)
i% Interleave factor (normaaly 1)
m% Magic number &H87654321
v% value in sectors of format (normally &HE5E5
~XBIOS(12,n%,L:adr%)
Outputs the contents of a block of memory to MIDI.
n% number of bytes -1
adr% address of the source storage area
~XBIOS(13,n%,L:adr%)
Sets the MFP interrupt vector on the ST. This can only be
used from assembly language or C and is not available from
GFA-BASIC.
n% Interrupt number
adr% new address of the interrupt
r%=XBIOS(14,d%)
Returns the address of the I/O table used by the serial
interface.
r% Address of the data buffer for the serial I/O
table
d% 0: RS232
1: IKBD
2: MIDI
~XBIOS(15,b%,h%,ucr%,rsr%,tsr%,scr%)
Configures the serial interface. The parameters remain
unchanged with a value of -1.
b% Baud rate
h% hand shake mode
0: no handshake
1: XON/XOFF
2: RTS/CTS
3: both
ucr% USART control register of MFP
rsr% receiver status register of MFP
tsr% transmitter status register of MFP
scr% synchronous character register of MFP
r%=XBIOS(16,L:us%,L:sh%,L:cl%)
Changes the keyboard translation tables.
r% address of the KEYTAB structure
us% address of the table for keys without shift
sh% address of the table for keys with shift
cl% address of the table for keys with Cap-lock
r%=XBIOS(17)
Returns a random number
r% number with 24 bit accuracy (0 to 16777215)
~XBIOS(18,L:b%,L:s%,d%,f%)
Creates a boot sector for the disk in memory
b% address of a 512 byte buffer for producing the
boot sector
s% serial number that forms part of the boot sector
-1: previous serial retained
>24 bits: random number returned
d% disk type (tracks/sides)
0:40 tracks,single sided (180K)
1:40 tracks,double sided (360K, IBM)
2:80 tracks, single side (360K)
3:80 tracks, double sided (720K)
f% 0:non executable boot sector
1:executable
-1:leave unchanged
r%=XBIOS(19,L:b%,L:f%,d%,sec%,t%,side%,n%)
Verifies the disk contents
b% address of the memory area with which a comparison
is made.
f% not used
d% disk drive number
sec% start sector
t% track number
side% disk side
n% number of sectors
~XBIOS(20)
Calls the hardcopy routine and thus dumps the screen to
printer.
r%=XBIOS(21,c%,s%)
Configure cursor.
r% when c%=5 returns the cursor blink rate
c% 0: Hide cursor
1: Show cursor
2: blink cursor
3: solid cursor
4: blink rate set in s%
5: see r%
s% when c%=4, blink rate set to s%
~XBIOS(22,L:t%)
Sets date and time
t% Bits 0-4: seconds
5-19: minutes
11-15: hours
16-20: day
21-24: month
25-31: year - 1980
r%=XBIOS(23)
returns date and time
r% see XBIOS(22) for bit settings
~XBIOS(24)
re installs the original keyboard allocation (see
XBIOS(16))
XBIOS(25,n%,L:adr%)
writes bytes from memory to the keyboard processor (IKBD)
n% number bytes-1 to be sent
adr% address where the data to be sent is stored
~XBIOS(26,i%)
Disables an MFP interrupt.
i% interrupt number (0-15) to be disabled
~XBIOS(27,i%)
enables an MFP interrupt.
i% interrupt number (0-15) to be enabled
~XBIOS(28,d%,reg%)
reads and writes from and to the sound chip register
r% returns register value when reading
d% value to be writen (8 bits)
r% register number (0-15), bit 7 defines write mode
when set.
~XBIOS(29,b%)
sets the bit of port A on the register of the sound chip to
zero
b% bit pattern wicj is OR'ed with existing contents.
~XBIOS(30,b%)
sets the port A bit of the sound chip register to 1
b% bit pattern which is ANDed with the existing
contents.
XBIOS(31,t%,c%,d%,L:adr%)
Sets the MFP timers
t% number of the timer (0 to 3)
c% control register
d% data register
adr% address of the timer interrupt routine
~XBIOS(32,L:adr%)
Starts a sound sequence, whic is processed in the interrupt
adr% address of the staorage area
r%=XBIOS(33,c%)
sets or reads the printer parameters
r% current configuration when c%=1
c% Bit set reset
0 Dot Matrix Daisy Wheel
1 Monochrome Colour
2 Atari Epson
3 Parallel RS-232
4 Continuous Single sheet
r%=XBIOS(34)
returns address of table with vectors to the keyboard and
MIDI processor.
r% returned address
r%=XBIOS(35,a%,w%)
sets and reads keyboard repeat rate
r% current data
bits 0-7 repeat rate
8-15 time of repeat delay
a% repeat delay
w% repeat rate
~XBIOS(36,L:adr%)
Hardcopy routine returns parameter block address
adr% address of a parameter block for the hardcopy
routine.
~XBIOS(37)
waits for next vertical blank interrupt.
~XBIOS(38,L:adr%)
calls an assembler routine in supervisor mode
adr% address of assembler routine
~XBIOS(39)
turns off AES if not in ROM
r%=XBIOS(64,b%)
contols and interrogates the blitter
r% b%=-1 current blitter status
bit 1 : blitter there
XOR
Syntax: x XOR y
Action: Logical exclusive OR operator
XOR()
Syntax: XOR(x,y)
Action: Sets those bits in x that are different in x and y.
_DATA
Syntax: _DATA
_DATA=
Action: Specifies the position of the DATA pointer. _DATA is 0 if
the next READ would result in an out of data message.
~
Syntax: ~function
Action: Similar to VOID. Forget the returned value
End of File